@deepseek-ai/dsh-win32-process 0.1.6-alpha.1 → 0.1.7-alpha.1

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: e3009bb207e0436b4d4113d7bf1ea677ab191abc
-README.zh.md: 65f834b447a2d9f4db94130fe3f7070456aab351
+README.md: 155ca3807791a83fef437af67312b3480ce7d2a2
+README.zh.md: f0c4439af27ef45c88d73bcba54851d789da063d

package/README.md

@@ -32,6 +32,8 @@ 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.

package/README.zh.md

@@ -32,6 +32,8 @@ kind: "package-library"
 - **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 组合与返回句柄。
 
+进程创建在目标代码运行前设置 `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 已分配的描述符。

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,6 +158,8 @@ 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 = {
@@ -365,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);
@@ -391,7 +410,7 @@ function createPipe(api, owned) {
 		};
 	} finally {
 		freeNative(writeSlot);
-		koffi.free(readSlot);
+		requireKoffi().free(readSlot);
 	}
 }
 function closeOwned(api, owned, handle) {
@@ -408,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.
@@ -428,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
@@ -585,6 +606,7 @@ function spawnJobProcess(api, options, resolveStdio, createName, create) {
 			control: stdio.control
 		});
 		if (controlBytes !== void 0) {
+			const koffi = requireKoffi();
 			controlDescriptorBlock = {
 				pointer: koffi.alloc("uint8", controlBytes.length),
 				length: controlBytes.length
@@ -594,7 +616,8 @@ function spawnJobProcess(api, options, resolveStdio, createName, create) {
 		startupInfo = allocStartupInfo();
 		encodeStartupInfo(startupInfo, {
 			cb: 104,
-			dwFlags: 256,
+			dwFlags: 257,
+			wShowWindow: 0,
 			hStdInput: stdio.stdin,
 			hStdOutput: stdio.stdout,
 			hStdError: stdio.stderr,
@@ -656,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.
@@ -670,7 +693,7 @@ function spawnInheritedJobProcess(api, options) {
 	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.
@@ -702,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/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,6 +25,7 @@ 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;
@@ -66,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

@@ -67,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.
@@ -88,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.
@@ -99,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.6-alpha.1",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,12 +27,13 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.3"
   },
   "dependencies": {
-    "koffi": "^3.1.0"
+    "koffi": "^3.1.0",
+    "@deepseek-ai/dsh-lazy-require": "^0.1.7-alpha.1"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.3"
   }
 }