@deepseek-ai/dsh-win32-process 0.1.5-rc.2 → 0.1.6-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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/subprocess/win32-process/README.md
-README.md: 7a4d12f7fe6ef553113e0f202886fd42e8a313a2
-README.zh.md: 8ebc614d38ea206cba792b90a2f118c028bf0447
+README.md: 155ca3807791a83fef437af67312b3480ce7d2a2
+README.zh.md: f0c4439af27ef45c88d73bcba54851d789da063d

package/README.md

@@ -32,8 +32,12 @@ This low-level Win32 process library is consumed by the Windows ACL sandbox and
 - **Ordinary settlement operations** — `pollProcessExit()` publishes direct exit separately, while `isJobEmpty()` reads `QueryInformationJobObject(JobObjectBasicAccountingInformation)` until `ActiveProcesses` reaches zero. Checked Job termination and handle closure keep the runner as the only native owner.
 - **Explicit settlement ownership** — `waitForProcessExit()` waits and closes a sandbox process handle; ordinary runner process polling, Job accounting, and checked Job termination/closure remain separate operations. `drainPipe()` reuses one native count slot while draining, frees it, and closes the pipe read handle. Each caller owns its result composition and returned handles.
 
+Process creation sets `STARTF_USESHOWWINDOW` with `SW_HIDE` before target code runs. It preserves console inheritance and does not add `CREATE_NO_WINDOW` or `CREATE_NEW_CONSOLE`, which can fail DLL initialization under the restricted token. Existing parent console windows are not hidden.
+
 The Windows ACL sandbox adds SID, DACL, grant, workspace, and public child policy above these primitives.
 
+- **Inherited control descriptor** — Job creation accepts an optional fd-7 pipe. `STARTUPINFO.cbReserved2/lpReserved2` carries an eight-slot CRT descriptor table with standard handles, closed slots 3–6, and the control pipe at slot 7. The table is allocated until CreateProcess returns; temporary handle inheritance is reset on success and failure. Initializing the slot before Node starts avoids overwriting descriptors Node has already allocated.
+
 <a id="header-verification"></a>
 ## Header verification
 

package/README.zh.md

@@ -9,33 +9,37 @@ kind: "package-library"
 
 ## 概述
 
-供 Windows ACL 沙箱与普通子进程 Job runner 消费的底层 Win32 进程库。它唯一拥有仓库中可复用 process、stdio 与 Job Object 操作的 Koffi 绑定表；它不是 Cordis 服务，也不决定沙箱策略或公共 child 行为。维护任一原生进程路径或检查 handle 生命周期限制时，请阅读本页。
+供 Windows ACL 沙箱与普通子进程 Job runner 消费的底层 Win32 进程库。它唯一拥有仓库中可复用 process、stdio 与 Job Object 操作的 Koffi 绑定表；它不是 Cordis 服务，也不决定沙箱策略或公共 child 行为。维护任一原生进程路径或检查句柄生命周期限制时，请阅读本页。
 
 ## 目录
 
-- [Behavior](#behavior)
-- [头部验证](#header-verification)
-- [Model Experience](#model-experience)
-- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [行为](#behavior)
+- [头文件验证](#header-verification)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
 - [开发备注](#dev-note)
 
 -----
 
 <a id="behavior"></a>
-## Behavior
+## 行为
 
-- **唯一可复用 ABI owner** — `abi.ts` 拥有两条 process 路径消费的 Win32 常量与 x64 布局值。`ffi.ts` 懒加载 `kernel32.dll` 与 `advapi32.dll`，核验 `STARTUPINFOW` 和 `PROCESS_INFORMATION`，提供带类型的操作与错误格式化，并让 sandbox policy 通过同一组已加载库绑定剩余 API。
-- **restricted-token 创建** — `RestrictedProcessSpawnOptions` 要求 sandbox 的 primary token，并使用 `CreateProcessAsUserW`。pipe 与 inherited-stdio 路径共用命令行引用、cwd、restricted-token 空环境策略、返回值检查与句柄清理。
+- **唯一可复用 ABI owner** — `abi.ts` 拥有两条 process 路径消费的 Win32 常量与 x64 布局值。`ffi.ts` 懒加载 `kernel32.dll` 与 `advapi32.dll`，核验 `STARTUPINFOW` 和 `PROCESS_INFORMATION`，提供带类型的操作与错误格式化，并让沙箱策略通过同一组已加载库绑定剩余 API。
+- **restricted-token 创建** — `RestrictedProcessSpawnOptions` 要求沙箱的 primary token，并使用 `CreateProcessAsUserW`。pipe 与 inherited-stdio 路径共用命令行引号处理、cwd、restricted-token null 环境策略、返回值检查与句柄清理。
 - **管道进程原语** — `spawnPipedProcess()` 创建匿名 stdin/stdout/stderr 管道，立即关闭 stdin，并返回两个读取端；调用方负责等待进程与排空管道。任一局部失败都会关闭该操作已经拥有的句柄，并在各自 Win32 生命周期结束后释放每个 Koffi 输出槽与结构体分配。
 - **继承 stdio 的 Job 原语** — `spawnInheritedJobProcess()` 创建一个 kill-on-close Job，临时把当前 stdio 句柄设为可继承，以 suspended 状态创建 restricted child，把它分配给 Job，再恢复初始线程。目标代码不会在 Job 分配前运行；受控的分配或恢复失败会终止 suspended child，或在释放全部已拥有句柄前关闭已分配的 Job。
-- **ordinary Job runner 原语** — `CurrentTokenProcessSpawnOptions` 要求已解析的 `applicationName`、完整 target 环境，以及三个专用于 target stdin、stdout 与 stderr 的 runner CRT 描述符。`spawnCurrentTokenJobProcess()` 通过 Node 导出的 `uv_get_osfhandle()` 把这些描述符映射为 OS handle，拒绝无效结果，临时把 handle 设为可继承，并通过 `STARTF_USESTDHANDLES` 传入。它使用 `CREATE_UNICODE_ENVIRONMENT` 传入排序后的 UTF-16LE 环境块，再以 suspended 状态通过 `CreateProcessW` 创建 target、把它分配给 unnamed kill-on-close Job，并只在分配后恢复。原始命令行 argv 项保持不变，runner 也可以关闭自己的 carrier 描述符，而不触碰 Node 自身的标准流。
-- **ordinary 停稳操作** — `pollProcessExit()` 单独发布 direct exit，`isJobEmpty()` 则读取 `QueryInformationJobObject(JobObjectBasicAccountingInformation)`，直到 `ActiveProcesses` 归零。带检查的 Job 终止与 handle 关闭使 runner 保持唯一 native owner。
-- **显式结算归属** — `waitForProcessExit()` 等待并关闭 sandbox process handle；ordinary runner 的 process polling、Job accounting 与 checked Job termination/closure 是独立操作。`drainPipe()` 在排空期间复用一个 native count slot，释放该分配并关闭管道读取句柄。每个调用方拥有自己的 result 组合与返回 handle。
+- **ordinary Job runner 原语** — `CurrentTokenProcessSpawnOptions` 要求已解析的 `applicationName`、完整 target 环境，以及三个专用于 target stdin、stdout 与 stderr 的 runner CRT 描述符。`spawnCurrentTokenJobProcess()` 通过 Node 导出的 `uv_get_osfhandle()` 把这些描述符映射为 OS 句柄，拒绝无效结果，临时把句柄设为可继承，并通过 `STARTF_USESTDHANDLES` 传入。它使用 `CREATE_UNICODE_ENVIRONMENT` 传入排序后的 UTF-16LE 环境块，再以 suspended 状态通过 `CreateProcessW` 创建 target、把它分配给 unnamed kill-on-close Job，并只在分配后恢复。原始命令行 argv 项保持不变，runner 也可以关闭自己的 carrier 描述符，而不触碰 Node 自身的标准流。
+- **ordinary 结算操作** — `pollProcessExit()` 单独发布 direct exit，`isJobEmpty()` 则读取 `QueryInformationJobObject(JobObjectBasicAccountingInformation)`，直到 `ActiveProcesses` 归零。带检查的 Job 终止与句柄关闭使 runner 保持唯一 native owner。
+- **显式结算归属** — `waitForProcessExit()` 等待并关闭沙箱 process 句柄；ordinary runner 的 process polling、Job accounting 与 checked Job termination/closure 是独立操作。`drainPipe()` 在排空期间复用一个 native count slot，释放该分配并关闭管道读取句柄。每个调用方拥有自己的 result 组合与返回句柄。
 
-Windows ACL 沙箱在这些原语上增加 SID、DACL、grant、workspace 与公共 child policy。
+进程创建在目标代码运行前设置 `STARTF_USESHOWWINDOW` 和 `SW_HIDE`。它保留控制台继承，不添加可能导致受限令牌下 DLL 初始化失败的 `CREATE_NO_WINDOW` 或 `CREATE_NEW_CONSOLE`。已有的父进程控制台窗口不会被隐藏。
+
+Windows ACL 沙箱在这些原语上增加 SID、DACL、grant、workspace 与公共 child 策略。
+
+- **继承控制描述符**——Job 创建接受可选的 fd-7 管道。`STARTUPINFO.cbReserved2/lpReserved2` 携带八槽 CRT 描述符表，其中包含标准句柄、关闭的槽 3–6，以及槽 7 的控制管道。该表保留到 CreateProcess 返回；临时句柄继承在成功和失败时均恢复。在 Node 启动前初始化该槽可避免覆盖 Node 已分配的描述符。
 
 <a id="header-verification"></a>
-## 头部验证
+## 头文件验证
 
 process、stdio 与 Job 的常量以及选定结构体的大小和偏移由 [`verify/abi-probe.cpp`](verify/abi-probe.cpp) 对照 MinGW Windows 头文件检查：
 
@@ -43,16 +47,16 @@ process、stdio 与 Job 的常量以及选定结构体的大小和偏移由 [`ve
 g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp && ./abi-probe.exe
 ```
 
-Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载时断言各自的 64 位大小。该探针还固定指针与 handle 宽度、Unicode 环境标志，以及用于判断停稳的基础 Job accounting record 大小与 `ActiveProcesses` 偏移；其余已记录偏移和常量也由该探针提供证据。
+Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载时断言各自的 64 位大小。该探针还固定指针与句柄宽度、Unicode 环境标志，以及用于判断完全停稳的基础 Job accounting record 大小与 `ActiveProcesses` 偏移；其余已记录偏移和常量也由该探针提供证据。
 
 <a id="model-experience"></a>
-## Model Experience
+## 模型体验
 
 ### 进程原语
 
 #### 模型看到什么
 
-没有直接内容。本包向 sandbox 与 ordinary runner 提供 `Win32ProcessBindings`、`CurrentTokenProcessBindings` 与进程原语；两者拥有全部模型可见工具、输出与诊断，本包不贡献提示词或工具 schema。
+没有直接内容。本包向沙箱与 ordinary runner 提供 `Win32ProcessBindings`、`CurrentTokenProcessBindings` 与进程原语；两者拥有全部模型可见工具、输出与诊断，本包不贡献提示词或工具 schema。
 
 #### Token 影响
 
@@ -62,14 +66,14 @@ Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载
 
 本包不贡献稳定请求前缀，因此不会使模型 KV Cache 失效。
 
-## Known Limitations and Deferred Work
+## 已知限制与延期工作
 
 <a id="known-limitations-and-deferred-work"></a>
 
 - **仅在 Windows 原生加载** — 导入通用类型可跨平台进行，但解析绑定表会加载 Windows DLL，并在其他宿主失败。跨平台测试注入绑定表，不加载原生 API。
-- **没有公共进程服务** — 本包刻意不把原语包装成 Cordis 或 Node streams。消费方必须拥有自己的策略、异步调度、输出上限、取消与最终句柄关闭。
-- **restricted-token 空环境** — `CreateProcessAsUserW` sandbox 原语传入空环境块，并先通过 `SetEnvironmentVariableW` 建立改动，因为经 Koffi 传入显式环境块会以 `ERROR_INVALID_PARAMETER` 失败。ordinary `CreateProcessW` runner 则要求完整 target 环境，并传入排序、双 NUL 结尾的 UTF-16LE 块，其中包括 `=X:` 驱动器条目，而不修改自身环境。
-- **没有 standalone process API** — 本包只暴露当前 sandbox 与 ordinary-runner consumer 所需的操作，不拥有 Node streams、公共 handle、output policy、cancellation 或 durable state。
+- **没有公共进程服务** — 本包刻意不把原语包装成 Cordis 或 Node 流。消费方必须拥有自己的策略、异步调度、输出上限、取消与最终句柄关闭。
+- **restricted-token null 环境** — `CreateProcessAsUserW` 沙箱原语传入 null 环境块，并先通过 `SetEnvironmentVariableW` 建立改动，因为经 Koffi 传入显式环境块会以 `ERROR_INVALID_PARAMETER` 失败。ordinary `CreateProcessW` runner 则要求完整 target 环境，并传入排序、双 NUL 结尾的 UTF-16LE 块，其中包括 `=X:` 驱动器条目，而不修改自身环境。
+- **没有 standalone process API** — 本包只暴露当前沙箱与 ordinary-runner 消费方所需的操作，不拥有 Node 流、公共句柄、输出策略、取消或 durable state。
 - **创建到分配之间的中断** — 目标以 suspended 状态启动，不能在 Job 分配前执行，但 runner 若在进程创建到分配之间的极窄区间被外力终止，可能留下 suspended target。本包不声明原子 Job 附加保证。
 - **header 证据限定架构** — 已提交的 ABI probe 与布局常量覆盖仓库当前 64 位 Windows 目标。支持新的指针宽度或不兼容 Windows ABI 前，必须先更新 probe。
 
@@ -84,4 +88,4 @@ Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载
 
 </details>
 
-**运行时不变式：** 不发布伴生入口。操作只持有调用内的 native handle。
+**运行时不变式：** 不发布伴生入口。操作只持有调用内的原生句柄。

package/lib/index.js

@@ -1,4 +1,4 @@
-import koffi from "koffi";
+import { createLazyRequire } from "@deepseek-ai/dsh-lazy-require";
 /** Win32 code reporting a caller-provided buffer is too small. */
 const ERROR_INSUFFICIENT_BUFFER = 122;
 /** Job limit that terminates every member when the final Job handle closes. */
@@ -19,10 +19,13 @@ var Win32Error = class extends Error {
 	}
 };
 //#endregion
+//#region lib/types/koffi.js
+/** Process-realm lazy access to Koffi's CommonJS entry. */
+/** Load Koffi on the first Win32 native operation. */
+const requireKoffi = createLazyRequire("koffi", import.meta.url);
+//#endregion
 //#region lib/types/ffi.js
 /** Lazy Koffi bindings for generic Win32 process, stdio, and Job operations. */
-const PVOID = koffi.pointer("void");
-const PPVOID = koffi.pointer(PVOID);
 /**
 * Return whether a Koffi pointer represents NULL.
 * @param value - pointer value returned by Koffi or a Win32 call.
@@ -31,51 +34,64 @@ const PPVOID = koffi.pointer(PVOID);
 function isNullPtr(value) {
 	return value === null || value === void 0 || value === 0n;
 }
-/** Koffi STARTUPINFOW layout. */
-const STARTUPINFOW = koffi.struct("DSH_STARTUPINFOW", {
-	cb: "uint32",
-	lpReserved: "str16",
-	lpDesktop: "str16",
-	lpTitle: "str16",
-	dwX: "uint32",
-	dwY: "uint32",
-	dwXSize: "uint32",
-	dwYSize: "uint32",
-	dwXCountChars: "uint32",
-	dwYCountChars: "uint32",
-	dwFillAttribute: "uint32",
-	dwFlags: "uint32",
-	wShowWindow: "uint16",
-	cbReserved2: "uint16",
-	lpReserved2: koffi.pointer("uint8"),
-	hStdInput: PVOID,
-	hStdOutput: PVOID,
-	hStdError: PVOID
-});
-/** Koffi PROCESS_INFORMATION layout. */
-const PROCESS_INFORMATION = koffi.struct("DSH_PROCESS_INFORMATION", {
-	hProcess: PVOID,
-	hThread: PVOID,
-	dwProcessId: "uint32",
-	dwThreadId: "uint32"
-});
-/* v8 ignore start -- ABI guards are pinned by native header probes. */
-if (STARTUPINFOW.size !== 104) throw new Error(`STARTUPINFOW layout mismatch: koffi computed ${STARTUPINFOW.size}, expected 104`);
-if (PROCESS_INFORMATION.size !== 24) throw new Error(`PROCESS_INFORMATION layout mismatch: koffi computed ${PROCESS_INFORMATION.size}, expected 24`);
-/* v8 ignore stop */
+let cachedTypes;
+/** Resolve Koffi pointer and process layouts on the first native operation. */
+function win32Types() {
+	if (cachedTypes !== void 0) return cachedTypes;
+	const koffi = requireKoffi();
+	const PVOID = koffi.pointer("void");
+	const PPVOID = koffi.pointer(PVOID);
+	const STARTUPINFOW = koffi.struct("DSH_STARTUPINFOW", {
+		cb: "uint32",
+		lpReserved: "str16",
+		lpDesktop: "str16",
+		lpTitle: "str16",
+		dwX: "uint32",
+		dwY: "uint32",
+		dwXSize: "uint32",
+		dwYSize: "uint32",
+		dwXCountChars: "uint32",
+		dwYCountChars: "uint32",
+		dwFillAttribute: "uint32",
+		dwFlags: "uint32",
+		wShowWindow: "uint16",
+		cbReserved2: "uint16",
+		lpReserved2: koffi.pointer("uint8"),
+		hStdInput: PVOID,
+		hStdOutput: PVOID,
+		hStdError: PVOID
+	});
+	const PROCESS_INFORMATION = koffi.struct("DSH_PROCESS_INFORMATION", {
+		hProcess: PVOID,
+		hThread: PVOID,
+		dwProcessId: "uint32",
+		dwThreadId: "uint32"
+	});
+	/* v8 ignore start -- ABI guards are pinned by native header probes. */
+	if (STARTUPINFOW.size !== 104) throw new Error(`STARTUPINFOW layout mismatch: koffi computed ${STARTUPINFOW.size}, expected 104`);
+	if (PROCESS_INFORMATION.size !== 24) throw new Error(`PROCESS_INFORMATION layout mismatch: koffi computed ${PROCESS_INFORMATION.size}, expected 24`);
+	/* v8 ignore stop */
+	return cachedTypes = {
+		PVOID,
+		PPVOID,
+		STARTUPINFOW,
+		PROCESS_INFORMATION
+	};
+}
 /**
 * Allocate a pointer-sized out-parameter slot.
 * @returns allocated native slot.
 */
 function allocPtrSlot() {
-	return koffi.alloc(PVOID, 1);
+	const { PVOID } = win32Types();
+	return requireKoffi().alloc(PVOID, 1);
 }
 /**
 * Allocate a uint32 out-parameter slot.
 * @returns allocated native slot.
 */
 function allocUint32() {
-	return koffi.alloc("uint32", 1);
+	return requireKoffi().alloc("uint32", 1);
 }
 /**
 * Decode a pointer out-parameter.
@@ -83,7 +99,7 @@ function allocUint32() {
 * @returns decoded pointer, or null for address zero.
 */
 function decodePtr(slot) {
-	const value = koffi.decode(slot, PVOID);
+	const value = requireKoffi().decode(slot, win32Types().PVOID);
 	return isNullPtr(value) ? null : value;
 }
 /**
@@ -92,14 +108,14 @@ function decodePtr(slot) {
 * @returns decoded unsigned value.
 */
 function decodeUint32(slot) {
-	return koffi.decode(slot, "uint32");
+	return requireKoffi().decode(slot, "uint32");
 }
 /**
 * Allocate a zeroed STARTUPINFOW.
 * @returns allocated struct pointer.
 */
 function allocStartupInfo() {
-	return koffi.alloc(STARTUPINFOW, 1);
+	return requireKoffi().alloc(win32Types().STARTUPINFOW, 1);
 }
 /**
 * Encode the stdio-bearing STARTUPINFOW fields.
@@ -107,14 +123,14 @@ function allocStartupInfo() {
 * @param fields - fields required for inherited stdio.
 */
 function encodeStartupInfo(startupInfo, fields) {
-	koffi.encode(startupInfo, STARTUPINFOW, fields);
+	requireKoffi().encode(startupInfo, win32Types().STARTUPINFOW, fields);
 }
 /**
 * Allocate a zeroed PROCESS_INFORMATION.
 * @returns allocated struct pointer.
 */
 function allocProcessInfo() {
-	return koffi.alloc(PROCESS_INFORMATION, 1);
+	return requireKoffi().alloc(win32Types().PROCESS_INFORMATION, 1);
 }
 /**
 * Decode PROCESS_INFORMATION.
@@ -122,13 +138,14 @@ function allocProcessInfo() {
 * @returns process/thread handles and ids.
 */
 function decodeProcessInfo(processInfo) {
-	return koffi.decode(processInfo, PROCESS_INFORMATION);
+	return requireKoffi().decode(processInfo, win32Types().PROCESS_INFORMATION);
 }
 let cachedContext;
 let cached;
 /* v8 ignore start -- exercised by native Windows ABI and sandbox jobs. */
 function bindingContext() {
 	if (cachedContext !== void 0) return cachedContext;
+	const koffi = requireKoffi();
 	const kernel32 = koffi.load("kernel32.dll");
 	const advapi32 = koffi.load("advapi32.dll");
 	const bind = (lib, name, result, args) => lib.func("__stdcall", name, result, args);
@@ -141,11 +158,14 @@ function bindingContext() {
 }
 function bindings() {
 	if (cached !== void 0) return cached;
+	const koffi = requireKoffi();
+	const { PVOID, PPVOID, STARTUPINFOW, PROCESS_INFORMATION } = win32Types();
 	const { kernel32, advapi32, bind } = bindingContext();
 	const node = koffi.load(null);
 	cached = {
 		closeHandle: bind(kernel32, "CloseHandle", "int", [PVOID]),
 		getLastError: bind(kernel32, "GetLastError", "uint32", []),
+		getFileType: bind(kernel32, "GetFileType", "uint32", [PVOID]),
 		formatMessageW: bind(kernel32, "FormatMessageW", "uint32", [
 			"uint32",
 			PVOID,
@@ -284,6 +304,44 @@ function throwWin32(api, name, win32Code, detail) {
 	throw new Win32Error(name, win32Code, detail ?? errorText(api, win32Code));
 }
 //#endregion
+//#region lib/types/control-stdio.js
+/** Windows CRT startup descriptors for a Node payload with one inherited control pipe. */
+const HANDLE_BYTES = 8;
+const INVALID_HANDLE = 18446744073709551615n;
+const FOPEN = 1;
+const FPIPE = 8;
+const FDEV = 64;
+const FILE_TYPE_CHAR = 2;
+const FILE_TYPE_PIPE = 3;
+/**
+* Encode the CRT's descriptor table before the child runtime allocates descriptors.
+* Supported Windows targets use 64-bit handles. Empty slots remain closed, and the
+* backing Buffer must remain alive until CreateProcess returns.
+* @param api - native file-type inspection for inherited handles.
+* @param stdio - standard handles and the provider-owned fd-7 control pipe.
+* @returns descriptor count, flag bytes, and handle values for STARTUPINFO's reserved CRT fields.
+*/
+function inheritedControlStdio(api, stdio) {
+	const count = stdio.control.fileDescriptor + 1;
+	const handleOffset = 4 + count;
+	const bytes = Buffer.alloc(handleOffset + count * HANDLE_BYTES);
+	bytes.writeUInt32LE(count, 0);
+	for (let index = 0; index < count; index++) bytes.writeBigUInt64LE(INVALID_HANDLE, handleOffset + index * HANDLE_BYTES);
+	const entries = [
+		[0, stdio.stdin],
+		[1, stdio.stdout],
+		[2, stdio.stderr],
+		[stdio.control.fileDescriptor, stdio.control.handle]
+	];
+	for (const [fd, handle] of entries) {
+		const kind = api.getFileType(handle);
+		if (fd === stdio.control.fileDescriptor && kind !== FILE_TYPE_PIPE) throw new Error("subprocess control descriptor is not a Windows pipe");
+		bytes[4 + fd] = FOPEN | (kind === FILE_TYPE_PIPE ? FPIPE : kind === FILE_TYPE_CHAR ? FDEV : 0);
+		bytes.writeBigUInt64LE(handle, handleOffset + fd * HANDLE_BYTES);
+	}
+	return bytes;
+}
+//#endregion
 //#region lib/types/process.js
 /** Typed Win32 process operations over the shared binding table. */
 /**
@@ -326,7 +384,7 @@ function encodeWindowsEnvironment(env) {
 	return Buffer.from(`${strings.join("\0")}\0\0`, "utf16le");
 }
 function freeNative(pointer) {
-	if (pointer !== void 0) koffi.free(pointer);
+	if (pointer !== void 0) requireKoffi().free(pointer);
 }
 function closeBestEffort(api, handle) {
 	if (!isNullPtr(handle)) api.closeHandle(handle);
@@ -352,7 +410,7 @@ function createPipe(api, owned) {
 		};
 	} finally {
 		freeNative(writeSlot);
-		koffi.free(readSlot);
+		requireKoffi().free(readSlot);
 	}
 }
 function closeOwned(api, owned, handle) {
@@ -369,6 +427,7 @@ function createRestrictedProcess(api, options, commandLine, creationFlags, start
 }
 /**
 * Spawn a process with anonymous-pipe stdout/stderr and immediate stdin EOF.
+* New console windows start hidden without changing console inheritance.
 * @param api - active binding table.
 * @param options - command, cwd, args, and restricted primary token.
 * @returns caller-owned process and pipe read handles.
@@ -389,7 +448,8 @@ function spawnPipedProcess(api, options) {
 		startupInfo = allocStartupInfo();
 		encodeStartupInfo(startupInfo, {
 			cb: 104,
-			dwFlags: 256,
+			dwFlags: 257,
+			wShowWindow: 0,
 			hStdInput: stdIn.read,
 			hStdOutput: stdOut.write,
 			hStdError: stdErr.write
@@ -488,7 +548,7 @@ function createKillOnCloseJob(api) {
 }
 const UV_INVALID_OS_FILE_HANDLE = 18446744073709551615n;
 const UV_INVALID_FILE_DESCRIPTOR = 18446744073709551614n;
-function inheritedStandardHandles(api) {
+function inheritedStandardHandles(api, controlFileDescriptor) {
 	const get = (selector, label) => {
 		const handle = api.getStdHandle(selector);
 		if (!isNullPtr(handle)) return handle;
@@ -497,19 +557,27 @@ function inheritedStandardHandles(api) {
 	return {
 		stdin: get(-10, "stdin"),
 		stdout: get(-11, "stdout"),
-		stderr: get(-12, "stderr")
+		stderr: get(-12, "stderr"),
+		...controlFileDescriptor === void 0 ? {} : { control: {
+			fileDescriptor: controlFileDescriptor,
+			handle: descriptorHandle(api, controlFileDescriptor, "control")
+		} }
 	};
 }
+function descriptorHandle(api, fileDescriptor, label) {
+	const handle = api.uvGetOsfhandle(fileDescriptor);
+	if (isNullPtr(handle) || handle === UV_INVALID_OS_FILE_HANDLE || handle === UV_INVALID_FILE_DESCRIPTOR) throw new Error(`uv_get_osfhandle returned an invalid handle for target ${label} fd ${String(fileDescriptor)}`);
+	return handle;
+}
 function targetCarrierHandles(api, descriptors) {
-	const get = (fileDescriptor, label) => {
-		const handle = api.uvGetOsfhandle(fileDescriptor);
-		if (isNullPtr(handle) || handle === UV_INVALID_OS_FILE_HANDLE || handle === UV_INVALID_FILE_DESCRIPTOR) throw new Error(`uv_get_osfhandle returned an invalid handle for target ${label} fd ${String(fileDescriptor)}`);
-		return handle;
-	};
 	return {
-		stdin: get(descriptors.stdin, "stdin"),
-		stdout: get(descriptors.stdout, "stdout"),
-		stderr: get(descriptors.stderr, "stderr")
+		stdin: descriptorHandle(api, descriptors.stdin, "stdin"),
+		stdout: descriptorHandle(api, descriptors.stdout, "stdout"),
+		stderr: descriptorHandle(api, descriptors.stderr, "stderr"),
+		...descriptors.control === void 0 ? {} : { control: {
+			fileDescriptor: descriptors.control,
+			handle: descriptorHandle(api, descriptors.control, "control")
+		} }
 	};
 }
 /** Shared suspended-create, Job-assignment, and resume lifecycle. */
@@ -518,25 +586,45 @@ function spawnJobProcess(api, options, resolveStdio, createName, create) {
 	const enabled = [];
 	let startupInfo;
 	let processInfo;
+	let controlDescriptorBlock;
 	let created = 0;
 	let createFailureCode = 0;
 	try {
 		const stdio = resolveStdio();
-		for (const [handle, label] of [
+		const inherited = [
 			[stdio.stdin, "stdin"],
 			[stdio.stdout, "stdout"],
 			[stdio.stderr, "stderr"]
-		]) {
+		];
+		if (stdio.control !== void 0) inherited.push([stdio.control.handle, "control"]);
+		for (const [handle, label] of inherited) {
 			if (api.setHandleInformation(handle, 1, 1) === 0) throwLastError(api, "SetHandleInformation", `${label} (enable inherit)`);
 			enabled.push(handle);
 		}
+		const controlBytes = stdio.control === void 0 ? void 0 : inheritedControlStdio(api, {
+			...stdio,
+			control: stdio.control
+		});
+		if (controlBytes !== void 0) {
+			const koffi = requireKoffi();
+			controlDescriptorBlock = {
+				pointer: koffi.alloc("uint8", controlBytes.length),
+				length: controlBytes.length
+			};
+			koffi.encode(controlDescriptorBlock.pointer, "uint8", controlBytes, controlBytes.length);
+		}
 		startupInfo = allocStartupInfo();
 		encodeStartupInfo(startupInfo, {
 			cb: 104,
-			dwFlags: 256,
+			dwFlags: 257,
+			wShowWindow: 0,
 			hStdInput: stdio.stdin,
 			hStdOutput: stdio.stdout,
-			hStdError: stdio.stderr
+			hStdError: stdio.stderr,
+			...controlDescriptorBlock === void 0 ? {} : {
+				cbReserved2: controlDescriptorBlock.length,
+				lpReserved2: controlDescriptorBlock.pointer
+			}
 		});
 		processInfo = allocProcessInfo();
 		created = create(startupInfo, processInfo);
@@ -547,6 +635,7 @@ function spawnJobProcess(api, options, resolveStdio, createName, create) {
 		throw error;
 	} finally {
 		freeNative(startupInfo);
+		freeNative(controlDescriptorBlock?.pointer);
 		for (const handle of enabled) api.setHandleInformation(handle, 1, 0);
 	}
 	if (created === 0) {
@@ -590,7 +679,7 @@ function spawnJobProcess(api, options, resolveStdio, createName, create) {
 	};
 }
 /**
-* Spawn a restricted-token process suspended, assign its Job, then resume it.
+* Spawn a restricted-token process suspended with hidden initial windows, assign its Job, then resume it.
 * @param api - active binding table.
 * @param options - command, cwd, args, and restricted primary token.
 * @returns caller-owned process and Job handles after successful resume.
@@ -601,10 +690,10 @@ function spawnJobProcess(api, options, resolveStdio, createName, create) {
 */
 function spawnInheritedJobProcess(api, options) {
 	const commandLine = buildCommandLine(options.command, options.args);
-	return spawnJobProcess(api, options, () => inheritedStandardHandles(api), "CreateProcessAsUserW", (startupInfo, processInfo) => createRestrictedProcess(api, options, commandLine, 4, startupInfo, processInfo));
+	return spawnJobProcess(api, options, () => inheritedStandardHandles(api, options.controlFileDescriptor), "CreateProcessAsUserW", (startupInfo, processInfo) => createRestrictedProcess(api, options, commandLine, 4, startupInfo, processInfo));
 }
 /**
-* Spawn an ordinary process suspended, assign its Job, then resume it.
+* Spawn an ordinary process suspended with hidden initial windows, assign its Job, then resume it.
 * @param api - active binding table.
 * @param options - command, cwd, argv, and target carrier descriptors.
 * @returns caller-owned process and Job handles after successful resume.
@@ -636,7 +725,7 @@ function pollProcessExit(api, process) {
 		if (api.getExitCodeProcess(process, exitCodeSlot) === 0) throwLastError(api, "GetExitCodeProcess");
 		return decodeUint32(exitCodeSlot);
 	} finally {
-		koffi.free(exitCodeSlot);
+		requireKoffi().free(exitCodeSlot);
 	}
 }
 /**

package/lib/types/abi.d.ts

@@ -1,6 +1,10 @@
 /** Generic Win32 process, stdio, and Job Object constants verified on x64. */
 /** STARTUPINFOW uses the standard input, output, and error handles. */
 export declare const STARTF_USESTDHANDLES = 256;
+/** STARTUPINFOW applies wShowWindow when creating a console window. */
+export declare const STARTF_USESHOWWINDOW = 1;
+/** Initial window visibility that preserves the child's console attachment. */
+export declare const SW_HIDE = 0;
 /** HandleInformation flag that permits child inheritance. */
 export declare const HANDLE_FLAG_INHERIT = 1;
 /** Infinite WaitForSingleObject timeout. */

package/lib/types/control-stdio.d.ts

@@ -0,0 +1,22 @@
+/** Windows CRT startup descriptors for a Node payload with one inherited control pipe. */
+import type { NativePtr, Win32ProcessBindings } from './ffi.ts';
+/** Native stdio handles plus the single additional descriptor selected by the launcher. */
+export interface InheritedControlStdio {
+    stdin: NativePtr;
+    stdout: NativePtr;
+    stderr: NativePtr;
+    control: {
+        fileDescriptor: 7;
+        handle: NativePtr;
+    };
+}
+/**
+ * Encode the CRT's descriptor table before the child runtime allocates descriptors.
+ * Supported Windows targets use 64-bit handles. Empty slots remain closed, and the
+ * backing Buffer must remain alive until CreateProcess returns.
+ * @param api - native file-type inspection for inherited handles.
+ * @param stdio - standard handles and the provider-owned fd-7 control pipe.
+ * @returns descriptor count, flag bytes, and handle values for STARTUPINFO's reserved CRT fields.
+ */
+export declare function inheritedControlStdio(api: Pick<Win32ProcessBindings, 'getFileType'>, stdio: InheritedControlStdio): Buffer;
+//# sourceMappingURL=control-stdio.d.ts.map

package/lib/types/ffi.d.ts

@@ -1,19 +1,19 @@
 /** Lazy Koffi bindings for generic Win32 process, stdio, and Job operations. */
-import koffi from 'koffi';
+import { type Koffi } from './koffi.ts';
 declare const nativePtr: unique symbol;
 /** Koffi native pointer branded against accidental numeric use. */
 export type NativePtr = bigint & {
     readonly [nativePtr]: true;
 };
-type Ptr = ReturnType<typeof koffi.pointer>;
+type Ptr = ReturnType<Koffi['pointer']>;
 /** Loaded Win32 libraries and the shared stdcall binder used by process extensions. */
 export interface Win32BindingContext {
     /** Kernel process, handle, pipe, and Job APIs. */
-    readonly kernel32: ReturnType<typeof koffi.load>;
+    readonly kernel32: ReturnType<Koffi['load']>;
     /** Token and security APIs. */
-    readonly advapi32: ReturnType<typeof koffi.load>;
+    readonly advapi32: ReturnType<Koffi['load']>;
     /** Bind one stdcall function from a loaded Win32 library. */
-    readonly bind: (library: ReturnType<typeof koffi.load>, name: string, result: Ptr | string, args: Array<Ptr | string>) => unknown;
+    readonly bind: (library: ReturnType<Koffi['load']>, name: string, result: Ptr | string, args: Array<Ptr | string>) => unknown;
 }
 /**
  * Return whether a Koffi pointer represents NULL.
@@ -25,9 +25,12 @@ export declare function isNullPtr(value: NativePtr | null | undefined): value is
 export interface StartupInfoInput {
     cb: number;
     dwFlags: number;
+    wShowWindow: number;
     hStdInput: NativePtr;
     hStdOutput: NativePtr;
     hStdError: NativePtr;
+    cbReserved2?: number;
+    lpReserved2?: NativePtr;
 }
 /** Decoded PROCESS_INFORMATION result. */
 export interface ProcessInfoOutput {
@@ -40,6 +43,8 @@ export interface ProcessInfoOutput {
 export interface Win32ProcessBindings {
     closeHandle(handle: NativePtr): number;
     getLastError(): number;
+    getFileType(handle: NativePtr): number;
+    uvGetOsfhandle(fileDescriptor: number): NativePtr | null;
     formatMessageW(flags: number, source: null, messageId: number, languageId: number, buffer: Buffer, size: number, args: null): number;
     createPipe(readHandle: NativePtr, writeHandle: NativePtr, attributes: null, size: number): number;
     setHandleInformation(handle: NativePtr, mask: number, flags: number): number;
@@ -62,10 +67,16 @@ export interface Win32ProcessBindings {
 export interface CurrentTokenProcessBindings extends Win32ProcessBindings {
     uvGetOsfhandle(fileDescriptor: number): NativePtr | null;
 }
-/** Koffi STARTUPINFOW layout. */
-export declare const STARTUPINFOW: import("koffi").TypeObject;
-/** Koffi PROCESS_INFORMATION layout. */
-export declare const PROCESS_INFORMATION: import("koffi").TypeObject;
+/**
+ * Materialize the Koffi STARTUPINFOW layout on first native use.
+ * @returns the cached native struct type.
+ */
+export declare function startupInfoType(): ReturnType<Koffi['struct']>;
+/**
+ * Materialize the Koffi PROCESS_INFORMATION layout on first native use.
+ * @returns the cached native struct type.
+ */
+export declare function processInformationType(): ReturnType<Koffi['struct']>;
 /**
  * Allocate a pointer-sized out-parameter slot.
  * @returns allocated native slot.

package/lib/types/koffi.d.ts

@@ -0,0 +1,49 @@
+/** Process-realm lazy access to Koffi's CommonJS entry. */
+import type koffi from 'koffi';
+/** Koffi runtime export type. */
+export type Koffi = typeof koffi;
+/** Load Koffi on the first Win32 native operation. */
+export declare const requireKoffi: () => {
+    LibraryHandle: import("koffi").LibraryHandle;
+    TypeObject: import("koffi").TypeObject;
+    Union: import("koffi").Union;
+    address: typeof import("koffi").address;
+    alias: typeof import("koffi").alias;
+    alignof: typeof import("koffi").alignof;
+    alloc: typeof import("koffi").alloc;
+    array: typeof import("koffi").array;
+    as: typeof import("koffi").as;
+    call: typeof import("koffi").call;
+    config: typeof import("koffi").config;
+    decode: typeof import("koffi").decode;
+    disposable: typeof import("koffi").disposable;
+    encode: typeof import("koffi").encode;
+    enumeration: typeof import("koffi").enumeration;
+    errno: typeof import("koffi").errno;
+    extension: typeof import("koffi").extension;
+    free: typeof import("koffi").free;
+    inout: typeof import("koffi").inout;
+    introspect: typeof import("koffi").introspect;
+    load: typeof import("koffi").load;
+    node: typeof import("koffi").node;
+    offsetof: typeof import("koffi").offsetof;
+    opaque: typeof import("koffi").opaque;
+    os: typeof import("koffi").os;
+    out: typeof import("koffi").out;
+    pack: typeof import("koffi").pack;
+    pointer: typeof import("koffi").pointer;
+    proto: typeof import("koffi").proto;
+    register: typeof import("koffi").register;
+    reset: typeof import("koffi").reset;
+    resolve: typeof import("koffi").resolve;
+    sizeof: typeof import("koffi").sizeof;
+    stats: typeof import("koffi").stats;
+    struct: typeof import("koffi").struct;
+    type: typeof import("koffi").type;
+    types: typeof import("koffi").types;
+    union: typeof import("koffi").union;
+    unregister: typeof import("koffi").unregister;
+    version: typeof import("koffi").version;
+    view: typeof import("koffi").view;
+};
+//# sourceMappingURL=koffi.d.ts.map

package/lib/types/process.d.ts

@@ -35,11 +35,15 @@ export interface CurrentTokenStdioFileDescriptors {
     stdin: number;
     stdout: number;
     stderr: number;
+    /** Optional carrier and target descriptor for the inherited control pipe. */
+    control?: 7;
 }
 /** Restricted-token process creation inputs owned by the Windows ACL sandbox. */
 export interface RestrictedProcessSpawnOptions extends ProcessSpawnOptions {
     /** Restricted primary token supplied by sandbox policy. */
     token: NativePtr;
+    /** Optional control pipe inherited at the same descriptor in the payload. */
+    controlFileDescriptor?: 7;
 }
 /** Piped child resources whose process and read handles remain caller-owned. */
 export interface SpawnedPipedProcess {
@@ -63,6 +67,7 @@ export interface SpawnedJobProcess {
 }
 /**
  * Spawn a process with anonymous-pipe stdout/stderr and immediate stdin EOF.
+ * New console windows start hidden without changing console inheritance.
  * @param api - active binding table.
  * @param options - command, cwd, args, and restricted primary token.
  * @returns caller-owned process and pipe read handles.
@@ -84,7 +89,7 @@ export declare function drainPipe(api: Win32ProcessBindings, handle: NativePtr):
  */
 export declare function waitForProcessExit(api: Win32ProcessBindings, process: NativePtr): number;
 /**
- * Spawn a restricted-token process suspended, assign its Job, then resume it.
+ * Spawn a restricted-token process suspended with hidden initial windows, assign its Job, then resume it.
  * @param api - active binding table.
  * @param options - command, cwd, args, and restricted primary token.
  * @returns caller-owned process and Job handles after successful resume.
@@ -95,7 +100,7 @@ export declare function waitForProcessExit(api: Win32ProcessBindings, process: N
  */
 export declare function spawnInheritedJobProcess(api: Win32ProcessBindings, options: RestrictedProcessSpawnOptions): SpawnedJobProcess;
 /**
- * Spawn an ordinary process suspended, assign its Job, then resume it.
+ * Spawn an ordinary process suspended with hidden initial windows, assign its Job, then resume it.
  * @param api - active binding table.
  * @param options - command, cwd, argv, and target carrier descriptors.
  * @returns caller-owned process and Job handles after successful resume.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-win32-process",
   "description": "Shared low-level Win32 process, stdio, and Job Object primitives",
-  "version": "0.1.5-rc.2",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -30,7 +30,8 @@
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
-    "koffi": "^3.1.0"
+    "koffi": "^3.1.0",
+    "@deepseek-ai/dsh-lazy-require": "^0.1.6-alpha.2"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2"