@deepseek-ai/dsh-win32-process 0.1.2-alpha.5 → 0.1.3-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: c9652b542dc7d08851508619d663e750c115f3ec
-README.zh.md: 6eb0b2e26092fc593c8d3d5088110a935bd8c0be
+README.md: 7a4d12f7fe6ef553113e0f202886fd42e8a313a2
+README.zh.md: 8ebc614d38ea206cba792b90a2f118c028bf0447

package/README.md

@@ -1,5 +1,5 @@
 ---
-description: "Low-level Win32 process primitives for maintainers implementing or debugging the Windows ACL sandbox."
+description: "Low-level Win32 process primitives for maintainers implementing or debugging the Windows ACL sandbox and ordinary subprocess Job runner."
 kind: "package-library"
 ---
 
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Low-level Win32 process library consumed by the Windows ACL sandbox. It owns the repository's one Koffi binding table for reusable restricted-process, stdio, and Job Object operations; it is not a Cordis service and does not choose sandbox policy or public child behavior. Read this page when maintaining the sandbox's native process path or checking its handle-lifetime limits.
+This low-level Win32 process library is consumed by the Windows ACL sandbox and the ordinary subprocess Job runner. It owns the repository's one Koffi binding table for reusable process, stdio, and Job Object operations; it is not a Cordis service and does not choose sandbox policy or public child behavior. Read this page when maintaining either native process path or checking its handle-lifetime limits.
 
 ## Table of Contents
 
@@ -24,16 +24,16 @@ Low-level Win32 process library consumed by the Windows ACL sandbox. It owns the
 <a id="behavior"></a>
 ## Behavior
 
-- **One reusable ABI owner** — `abi.ts` owns the Win32 constants and x64 layout values consumed by the sandbox process paths. `ffi.ts` lazily loads `kernel32.dll` and `advapi32.dll`, verifies `STARTUPINFOW` and `PROCESS_INFORMATION`, exposes typed operations and error formatting, and lets sandbox policy bind its remaining APIs through the same loaded libraries.
-- **Restricted-token creation** — `RestrictedProcessSpawnOptions` requires the sandbox's primary token and uses `CreateProcessAsUserW`. Piped and inherited-stdio paths share command-line quoting, cwd, the inherited environment block, checked return values, and handle cleanup.
+- **One reusable ABI owner** — `abi.ts` owns the Win32 constants and x64 layout values consumed by both process paths. `ffi.ts` lazily loads `kernel32.dll` and `advapi32.dll`, verifies `STARTUPINFOW` and `PROCESS_INFORMATION`, exposes typed operations and error formatting, and lets sandbox policy bind its remaining APIs through the same loaded libraries.
+- **Restricted-token creation** — `RestrictedProcessSpawnOptions` requires the sandbox's primary token and uses `CreateProcessAsUserW`. Piped and inherited-stdio paths share command-line quoting, cwd, the restricted-token null-environment policy, checked return values, and handle cleanup.
 - **Piped process primitive** — `spawnPipedProcess()` creates anonymous stdin/stdout/stderr pipes, closes stdin immediately, returns the two read ends, and leaves process waiting and pipe draining to the caller. Every partial failure closes the handles already owned by the operation, and every Koffi out-parameter or struct allocation is freed after its Win32 lifetime.
 - **Inherited-stdio Job primitive** — `spawnInheritedJobProcess()` creates one kill-on-close Job, temporarily marks the current stdio handles inheritable, creates the restricted child suspended, assigns it to the Job, and then resumes its initial thread. Target code cannot run before Job assignment; controlled assignment or resume failures terminate the suspended child or close the assigned Job before releasing every owned handle.
-- **Explicit settlement ownership** — `waitForProcessExit()` waits and closes the process handle. `drainPipe()` reuses one native count slot while draining, frees it, and closes the pipe read handle. The sandbox retains its existing scheduling, result composition, and caller-owned Job closure.
+- **Ordinary Job runner primitive** — `CurrentTokenProcessSpawnOptions` requires a resolved `applicationName`, the complete target environment, and three runner CRT descriptors dedicated to target stdin, stdout, and stderr. `spawnCurrentTokenJobProcess()` maps those descriptors to OS handles through Node's exported `uv_get_osfhandle()`, rejects invalid results, temporarily marks the handles inheritable, and passes them through `STARTF_USESTDHANDLES`. It sends a sorted UTF-16LE environment block with `CREATE_UNICODE_ENVIRONMENT`, creates the target suspended through `CreateProcessW`, assigns it to an unnamed kill-on-close Job, and resumes it only after assignment. The original command-line argv entry remains unchanged, and the runner can close its carrier descriptors without touching Node's own standard streams.
+- **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.
 
 The Windows ACL sandbox adds SID, DACL, grant, workspace, and public child policy above these primitives.
 
-<a id="header-verification"></a>
-
 <a id="header-verification"></a>
 ## Header verification
 
@@ -43,7 +43,7 @@ The process, stdio, and Job constants plus selected structure sizes and offsets
 g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp && ./abi-probe.exe
 ```
 
-The Koffi `STARTUPINFOW` and `PROCESS_INFORMATION` definitions also assert their 64-bit sizes at module load. The probe remains the evidence for the other recorded offsets and constants.
+The Koffi `STARTUPINFOW` and `PROCESS_INFORMATION` definitions also assert their 64-bit sizes at module load. The probe additionally fixes pointer and handle widths, the Unicode-environment flag, and the basic Job accounting record size and `ActiveProcesses` offset used to determine quiescence; it remains the evidence for the other recorded offsets and constants.
 
 <a id="model-experience"></a>
 ## Model Experience
@@ -52,7 +52,7 @@ The Koffi `STARTUPINFOW` and `PROCESS_INFORMATION` definitions also assert their
 
 #### What the model sees
 
-Nothing directly. The package exposes `Win32ProcessBindings` and process primitives to the sandbox, which owns all model-visible tools, output, and diagnostics; this package contributes no prompt text or tool schema.
+Nothing directly. The package exposes `Win32ProcessBindings`, `CurrentTokenProcessBindings`, and process primitives to the sandbox and ordinary runner, which own all model-visible tools, output, and diagnostics; this package contributes no prompt text or tool schema.
 
 #### Token effect
 
@@ -68,8 +68,8 @@ The package contributes no stable request prefix, so it does not invalidate mode
 
 - **Windows-only native loading** — importing the generic types is portable, but resolving the binding table loads Windows DLLs and fails on other hosts. Cross-platform tests inject a binding table instead of loading native APIs.
 - **No public process service** — the package intentionally does not wrap its primitives in Cordis or Node streams. A consumer must own its policy, async scheduling, output limits, cancellation, and final handle closure.
-- **Inherited environment only** — process creation passes a null environment block. The sandbox establishes changes through `SetEnvironmentVariableW` first because passing an explicit block through Koffi makes `CreateProcessAsUserW` fail with `ERROR_INVALID_PARAMETER`. Other callers that need environment changes must establish them before invoking the primitive or use their own runner process.
-- **Restricted-token consumer only** — ordinary `CreateProcessW`, exact `applicationName`, parent-stdio release, and whole-Job settlement are absent until an ordinary process consumer requires them.
+- **Restricted-token null environment** — the `CreateProcessAsUserW` sandbox primitives pass a null environment block and establish changes through `SetEnvironmentVariableW` first because an explicit block through Koffi fails with `ERROR_INVALID_PARAMETER`. The ordinary `CreateProcessW` runner instead requires a complete target environment and passes a sorted, double-NUL-terminated UTF-16LE block, including `=X:` drive entries, without mutating its own environment.
+- **No standalone process API** — the package exposes the operations current sandbox and ordinary-runner consumers need, but it does not own Node streams, public handles, output policy, cancellation, or durable state.
 - **Create-to-assignment interruption** — the target starts suspended and cannot execute before Job assignment, but an external termination of the runner in the narrow interval between process creation and assignment can leave the suspended target behind. The package does not claim atomic Job attachment.
 - **Header evidence is architecture-specific** — the committed ABI probe and layout constants cover the repository's current 64-bit Windows targets. A new pointer width or incompatible Windows ABI requires updating the probe before support is claimed.
 

package/README.zh.md

@@ -1,5 +1,5 @@
 ---
-description: "面向实现或排查 Windows ACL 沙箱的维护者，说明底层 Win32 进程原语。"
+description: "面向实现或排查 Windows ACL 沙箱与普通子进程 Job runner 的维护者，说明底层 Win32 进程原语。"
 kind: "package-library"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-library"
 
 ## 概述
 
-供 Windows ACL 沙箱消费的底层 Win32 进程库。它唯一拥有仓库中可复用 restricted-process、stdio 与 Job Object 操作的 Koffi 绑定表；它不是 Cordis 服务，也不决定沙箱策略或公共 child 行为。维护沙箱原生进程路径或检查 handle 生命周期限制时，请阅读本页。
+供 Windows ACL 沙箱与普通子进程 Job runner 消费的底层 Win32 进程库。它唯一拥有仓库中可复用 process、stdio 与 Job Object 操作的 Koffi 绑定表；它不是 Cordis 服务，也不决定沙箱策略或公共 child 行为。维护任一原生进程路径或检查 handle 生命周期限制时，请阅读本页。
 
 ## 目录
 
@@ -24,16 +24,16 @@ kind: "package-library"
 <a id="behavior"></a>
 ## Behavior
 
-- **唯一可复用 ABI owner** — `abi.ts` 拥有 sandbox 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、继承环境块、返回值检查与句柄清理。
+- **唯一可复用 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 空环境策略、返回值检查与句柄清理。
 - **管道进程原语** — `spawnPipedProcess()` 创建匿名 stdin/stdout/stderr 管道，立即关闭 stdin，并返回两个读取端；调用方负责等待进程与排空管道。任一局部失败都会关闭该操作已经拥有的句柄，并在各自 Win32 生命周期结束后释放每个 Koffi 输出槽与结构体分配。
 - **继承 stdio 的 Job 原语** — `spawnInheritedJobProcess()` 创建一个 kill-on-close Job，临时把当前 stdio 句柄设为可继承，以 suspended 状态创建 restricted child，把它分配给 Job，再恢复初始线程。目标代码不会在 Job 分配前运行；受控的分配或恢复失败会终止 suspended child，或在释放全部已拥有句柄前关闭已分配的 Job。
-- **显式结算归属** — `waitForProcessExit()` 等待并关闭进程句柄。`drainPipe()` 在排空期间复用一个 native count slot，释放该分配并关闭管道读取句柄。sandbox 保留既有调度、result 组合与调用方拥有的 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。
 
 Windows ACL 沙箱在这些原语上增加 SID、DACL、grant、workspace 与公共 child policy。
 
-<a id="header-verification"></a>
-
 <a id="header-verification"></a>
 ## 头部验证
 
@@ -43,7 +43,7 @@ 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 位大小；其余已记录偏移和常量由该探针提供证据。
+Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载时断言各自的 64 位大小。该探针还固定指针与 handle 宽度、Unicode 环境标志，以及用于判断停稳的基础 Job accounting record 大小与 `ActiveProcesses` 偏移；其余已记录偏移和常量也由该探针提供证据。
 
 <a id="model-experience"></a>
 ## Model Experience
@@ -52,7 +52,7 @@ Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载
 
 #### 模型看到什么
 
-没有直接内容。本包向 sandbox 提供 `Win32ProcessBindings` 与进程原语；sandbox 拥有全部模型可见工具、输出与诊断，本包不贡献提示词或工具 schema。
+没有直接内容。本包向 sandbox 与 ordinary runner 提供 `Win32ProcessBindings`、`CurrentTokenProcessBindings` 与进程原语；两者拥有全部模型可见工具、输出与诊断，本包不贡献提示词或工具 schema。
 
 #### Token 影响
 
@@ -68,8 +68,8 @@ Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载
 
 - **仅在 Windows 原生加载** — 导入通用类型可跨平台进行，但解析绑定表会加载 Windows DLL，并在其他宿主失败。跨平台测试注入绑定表，不加载原生 API。
 - **没有公共进程服务** — 本包刻意不把原语包装成 Cordis 或 Node streams。消费方必须拥有自己的策略、异步调度、输出上限、取消与最终句柄关闭。
-- **只继承环境** — 进程创建传入空环境块。sandbox 会先通过 `SetEnvironmentVariableW` 建立改动，因为经 Koffi 传入显式环境块会使 `CreateProcessAsUserW` 以 `ERROR_INVALID_PARAMETER` 失败。其他需要改写环境的调用方必须在调用原语前建立环境，或使用自己的 runner 进程。
-- **只有 restricted-token 消费方** — ordinary `CreateProcessW`、精确 `applicationName`、parent-stdio release 与 whole-Job settlement 在 ordinary process 消费方出现前均不提供。
+- **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。
 - **创建到分配之间的中断** — 目标以 suspended 状态启动，不能在 Job 分配前执行，但 runner 若在进程创建到分配之间的极窄区间被外力终止，可能留下 suspended target。本包不声明原子 Job 附加保证。
 - **header 证据限定架构** — 已提交的 ABI probe 与布局常量覆盖仓库当前 64 位 Windows 目标。支持新的指针宽度或不兼容 Windows ABI 前，必须先更新 probe。
 

package/lib/index.js

@@ -142,6 +142,7 @@ function bindingContext() {
 function bindings() {
 	if (cached !== void 0) return cached;
 	const { kernel32, advapi32, bind } = bindingContext();
+	const node = koffi.load(null);
 	cached = {
 		closeHandle: bind(kernel32, "CloseHandle", "int", [PVOID]),
 		getLastError: bind(kernel32, "GetLastError", "uint32", []),
@@ -178,6 +179,18 @@ function bindings() {
 			koffi.pointer(STARTUPINFOW),
 			koffi.pointer(PROCESS_INFORMATION)
 		]),
+		createProcessW: bind(kernel32, "CreateProcessW", "int", [
+			"str16",
+			"str16",
+			PVOID,
+			PVOID,
+			"int",
+			"uint32",
+			PVOID,
+			"str16",
+			koffi.pointer(STARTUPINFOW),
+			koffi.pointer(PROCESS_INFORMATION)
+		]),
 		readFile: bind(kernel32, "ReadFile", "int", [
 			PVOID,
 			PVOID,
@@ -202,10 +215,19 @@ function bindings() {
 			PVOID,
 			"uint32"
 		]),
+		queryInformationJobObject: bind(kernel32, "QueryInformationJobObject", "int", [
+			PVOID,
+			"int",
+			PVOID,
+			"uint32",
+			PVOID
+		]),
 		assignProcessToJobObject: bind(kernel32, "AssignProcessToJobObject", "int", [PVOID, PVOID]),
 		resumeThread: bind(kernel32, "ResumeThread", "uint32", [PVOID]),
 		terminateProcess: bind(kernel32, "TerminateProcess", "int", [PVOID, "uint32"]),
-		getStdHandle: bind(kernel32, "GetStdHandle", PVOID, ["int"])
+		terminateJobObject: bind(kernel32, "TerminateJobObject", "int", [PVOID, "uint32"]),
+		getStdHandle: bind(kernel32, "GetStdHandle", PVOID, ["int"]),
+		uvGetOsfhandle: node.func("uv_get_osfhandle", PVOID, ["int"])
 	};
 	return cached;
 }
@@ -220,6 +242,13 @@ function extendWin32ProcessBindings(create) {
 		...create(bindingContext())
 	};
 }
+/**
+* Load the generic process binding table without policy-specific extensions.
+* @returns shared Win32 process, stdio, and Job operations.
+*/
+function loadWin32ProcessBindings() {
+	return bindings();
+}
 /* v8 ignore stop */
 /**
 * Format a Win32 error code through FormatMessageW.
@@ -287,6 +316,15 @@ function quoteArg(argument) {
 function buildCommandLine(program, args) {
 	return [program, ...args].map(quoteArg).join(" ");
 }
+function compareWindowsEnvironmentKeys([left], [right]) {
+	const foldedLeft = left.toUpperCase();
+	const foldedRight = right.toUpperCase();
+	return foldedLeft < foldedRight ? -1 : foldedLeft > foldedRight ? 1 : 0;
+}
+function encodeWindowsEnvironment(env) {
+	const strings = Object.entries(env).sort(compareWindowsEnvironmentKeys).map(([key, value]) => `${key}=${value}`);
+	return Buffer.from(`${strings.join("\0")}\0\0`, "utf16le");
+}
 function freeNative(pointer) {
 	if (pointer !== void 0) koffi.free(pointer);
 }
@@ -448,38 +486,46 @@ function createKillOnCloseJob(api) {
 	}
 	return job;
 }
-/**
-* Spawn suspended, assign the child to a kill-on-close 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.
-* @remarks Node clears stdio handle inheritability at startup through
-* uv_disable_stdio_inheritance. This operation temporarily restores the bits
-* required by STARTF_USESTDHANDLES. Restoring them afterward is best-effort:
-* failure must not replace the already-created child's outcome.
-*/
-function spawnInheritedJobProcess(api, options) {
-	const job = createKillOnCloseJob(api);
-	const getStdHandle = (selector, label) => {
+const UV_INVALID_OS_FILE_HANDLE = 18446744073709551615n;
+const UV_INVALID_FILE_DESCRIPTOR = 18446744073709551614n;
+function inheritedStandardHandles(api) {
+	const get = (selector, label) => {
 		const handle = api.getStdHandle(selector);
 		if (!isNullPtr(handle)) return handle;
-		const win32Code = api.getLastError();
-		api.closeHandle(job);
-		throwWin32(api, "GetStdHandle", win32Code, `null ${label} handle`);
+		throwLastError(api, "GetStdHandle", `null ${label} handle`);
+	};
+	return {
+		stdin: get(-10, "stdin"),
+		stdout: get(-11, "stdout"),
+		stderr: get(-12, "stderr")
+	};
+}
+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")
 	};
-	const stdIn = getStdHandle(-10, "stdin");
-	const stdOut = getStdHandle(-11, "stdout");
-	const stdErr = getStdHandle(-12, "stderr");
+}
+/** Shared suspended-create, Job-assignment, and resume lifecycle. */
+function spawnJobProcess(api, options, resolveStdio, createName, create) {
+	const job = createKillOnCloseJob(api);
 	const enabled = [];
 	let startupInfo;
 	let processInfo;
 	let created = 0;
 	let createFailureCode = 0;
 	try {
+		const stdio = resolveStdio();
 		for (const [handle, label] of [
-			[stdIn, "stdin"],
-			[stdOut, "stdout"],
-			[stdErr, "stderr"]
+			[stdio.stdin, "stdin"],
+			[stdio.stdout, "stdout"],
+			[stdio.stderr, "stderr"]
 		]) {
 			if (api.setHandleInformation(handle, 1, 1) === 0) throwLastError(api, "SetHandleInformation", `${label} (enable inherit)`);
 			enabled.push(handle);
@@ -488,12 +534,12 @@ function spawnInheritedJobProcess(api, options) {
 		encodeStartupInfo(startupInfo, {
 			cb: 104,
 			dwFlags: 256,
-			hStdInput: stdIn,
-			hStdOutput: stdOut,
-			hStdError: stdErr
+			hStdInput: stdio.stdin,
+			hStdOutput: stdio.stdout,
+			hStdError: stdio.stderr
 		});
 		processInfo = allocProcessInfo();
-		created = createRestrictedProcess(api, options, buildCommandLine(options.command, options.args), 4, startupInfo, processInfo);
+		created = create(startupInfo, processInfo);
 		if (created === 0) createFailureCode = api.getLastError();
 	} catch (error) {
 		freeNative(processInfo);
@@ -506,7 +552,7 @@ function spawnInheritedJobProcess(api, options) {
 	if (created === 0) {
 		freeNative(processInfo);
 		api.closeHandle(job);
-		throwWin32(api, "CreateProcessAsUserW", createFailureCode, `command: ${options.command}, cwd: ${options.cwd}`);
+		throwWin32(api, createName, createFailureCode, `command: ${options.command}, cwd: ${options.cwd}`);
 	}
 	let info;
 	try {
@@ -519,7 +565,7 @@ function spawnInheritedJobProcess(api, options) {
 		api.closeHandle(job);
 		closeBestEffort(api, info.hThread);
 		closeBestEffort(api, info.hProcess);
-		throw new Error(`CreateProcessAsUserW succeeded but returned null process/thread handles (pid ${info.dwProcessId})`);
+		throw new Error(`${createName} succeeded but returned null process/thread handles (pid ${info.dwProcessId})`);
 	}
 	if (api.assignProcessToJobObject(job, info.hProcess) === 0) {
 		const win32Code = api.getLastError();
@@ -543,5 +589,84 @@ function spawnInheritedJobProcess(api, options) {
 		job
 	};
 }
+/**
+* Spawn a restricted-token process suspended, 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.
+* @remarks Node clears stdio handle inheritability at startup through
+* uv_disable_stdio_inheritance. This operation temporarily restores the bits
+* required by STARTF_USESTDHANDLES. Restoring them afterward is best-effort:
+* failure must not replace the already-created child's outcome.
+*/
+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));
+}
+/**
+* Spawn an ordinary process suspended, 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.
+*/
+function spawnCurrentTokenJobProcess(api, options) {
+	const commandLine = buildCommandLine(options.command, options.args);
+	const environment = encodeWindowsEnvironment(options.env);
+	return spawnJobProcess(api, options, () => targetCarrierHandles(api, options.stdio), "CreateProcessW", (startupInfo, processInfo) => api.createProcessW(options.applicationName, commandLine, null, null, 1, 1028, environment, options.cwd, startupInfo, processInfo));
+}
+/**
+* Verify that an unnamed kill-on-close Job can be created and released now.
+* @param api - active binding table.
+*/
+function probeCurrentTokenJobSupport(api) {
+	closeHandleChecked(api, createKillOnCloseJob(api), "current-token Job capability probe");
+}
+/**
+* Poll one process handle without blocking the runner event loop.
+* @param api - active binding table.
+* @param process - caller-owned process handle.
+* @returns the direct exit code when signalled, or undefined while running.
+*/
+function pollProcessExit(api, process) {
+	const waitResult = api.waitForSingleObject(process, 0);
+	if (waitResult === 258) return void 0;
+	if (waitResult === 4294967295) throwLastError(api, "WaitForSingleObject");
+	const exitCodeSlot = allocUint32();
+	try {
+		if (api.getExitCodeProcess(process, exitCodeSlot) === 0) throwLastError(api, "GetExitCodeProcess");
+		return decodeUint32(exitCodeSlot);
+	} finally {
+		koffi.free(exitCodeSlot);
+	}
+}
+/**
+* Return whether a Job has no active processes.
+* @param api - active binding table.
+* @param job - caller-owned Job handle.
+* @returns true once the Job reports zero active processes.
+*/
+function isJobEmpty(api, job) {
+	const information = Buffer.alloc(48);
+	if (api.queryInformationJobObject(job, 1, information, information.length, null) === 0) throwLastError(api, "QueryInformationJobObject", "active process count");
+	return information.readUInt32LE(40) === 0;
+}
+/**
+* Terminate every process in a Job.
+* @param api - active binding table.
+* @param job - caller-owned Job handle.
+* @param exitCode - direct Windows exit code assigned to members.
+*/
+function terminateJob(api, job, exitCode) {
+	if (api.terminateJobObject(job, exitCode) === 0) throwLastError(api, "TerminateJobObject");
+}
+/**
+* Close a caller-owned handle and report a labelled Win32 failure.
+* @param api - active binding table.
+* @param handle - handle to close.
+* @param detail - lifecycle label for diagnostics.
+*/
+function closeHandleChecked(api, handle, detail) {
+	if (api.closeHandle(handle) === 0) throwLastError(api, "CloseHandle", detail);
+}
 //#endregion
-export { ERROR_INSUFFICIENT_BUFFER, Win32Error, allocPtrSlot, allocUint32, decodePtr, decodeUint32, drainPipe, extendWin32ProcessBindings, isNullPtr, spawnInheritedJobProcess, spawnPipedProcess, throwLastError, throwWin32, waitForProcessExit };
+export { ERROR_INSUFFICIENT_BUFFER, Win32Error, allocPtrSlot, allocUint32, closeHandleChecked, decodePtr, decodeUint32, drainPipe, extendWin32ProcessBindings, isJobEmpty, isNullPtr, loadWin32ProcessBindings, pollProcessExit, probeCurrentTokenJobSupport, spawnCurrentTokenJobProcess, spawnInheritedJobProcess, spawnPipedProcess, terminateJob, throwLastError, throwWin32, waitForProcessExit };

package/lib/types/abi.d.ts

@@ -5,8 +5,12 @@ export declare const STARTF_USESTDHANDLES = 256;
 export declare const HANDLE_FLAG_INHERIT = 1;
 /** Infinite WaitForSingleObject timeout. */
 export declare const INFINITE = 4294967295;
+/** WaitForSingleObject returned because a zero-time probe is not signalled. */
+export declare const WAIT_TIMEOUT = 258;
 /** CreateProcess flag that prevents user code from running before resume. */
 export declare const CREATE_SUSPENDED = 4;
+/** CreateProcess flag selecting a UTF-16 environment block. */
+export declare const CREATE_UNICODE_ENVIRONMENT = 1024;
 /** GetStdHandle selector for standard input. */
 export declare const STD_INPUT_HANDLE = -10;
 /** GetStdHandle selector for standard output. */
@@ -25,8 +29,14 @@ export declare const ERROR_BROKEN_PIPE = 109;
 export declare const ERROR_NO_DATA = 232;
 /** Job limit that terminates every member when the final Job handle closes. */
 export declare const JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 8192;
+/** QueryInformationJobObject class for basic accounting and active-process count. */
+export declare const JobObjectBasicAccountingInformation = 1;
 /** SetInformationJobObject class for JOBOBJECT_EXTENDED_LIMIT_INFORMATION. */
 export declare const JobObjectExtendedLimitInformation = 9;
+/** x64 JOBOBJECT_BASIC_ACCOUNTING_INFORMATION byte size. */
+export declare const JOBOBJECT_BASIC_ACCOUNTING_SIZE = 48;
+/** Byte offset of ActiveProcesses in JOBOBJECT_BASIC_ACCOUNTING_INFORMATION. */
+export declare const JOBOBJECT_BASIC_ACCOUNTING_ACTIVE_PROCESSES_OFFSET = 40;
 /** x64 JOBOBJECT_EXTENDED_LIMIT_INFORMATION byte size. */
 export declare const JOBOBJECT_EXTENDED_LIMIT_SIZE = 144;
 /** Byte offset of BasicLimitInformation.LimitFlags in the extended Job record. */

package/lib/types/ffi.d.ts

@@ -43,18 +43,25 @@ export interface Win32ProcessBindings {
     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;
-    createProcessAsUserW(token: NativePtr, applicationName: null, commandLine: string, processAttributes: null, threadAttributes: null, inheritHandles: number, creationFlags: number, environment: null, currentDirectory: string | null, startupInfo: NativePtr, processInfo: NativePtr): number;
+    createProcessAsUserW(token: NativePtr, applicationName: string | null, commandLine: string, processAttributes: null, threadAttributes: null, inheritHandles: number, creationFlags: number, environment: null, currentDirectory: string | null, startupInfo: NativePtr, processInfo: NativePtr): number;
+    createProcessW(applicationName: string | null, commandLine: string, processAttributes: null, threadAttributes: null, inheritHandles: number, creationFlags: number, environment: Buffer | null, currentDirectory: string | null, startupInfo: NativePtr, processInfo: NativePtr): number;
     readFile(file: NativePtr, buffer: Buffer, count: number, bytesRead: NativePtr, overlapped: null): number;
     peekNamedPipe(pipe: NativePtr, buffer: null, size: number, bytesRead: NativePtr | null, totalAvail: NativePtr, leftThisMessage: NativePtr | null): number;
     waitForSingleObject(handle: NativePtr, milliseconds: number): number;
     getExitCodeProcess(process: NativePtr, exitCode: NativePtr): number;
     createJobObjectW(attributes: null, name: null): NativePtr;
     setInformationJobObject(job: NativePtr, cls: number, information: Buffer, length: number): number;
+    queryInformationJobObject(job: NativePtr, cls: number, information: Buffer, length: number, returnLength: null): number;
     assignProcessToJobObject(job: NativePtr, process: NativePtr): number;
     resumeThread(thread: NativePtr): number;
     terminateProcess(process: NativePtr, exitCode: number): number;
+    terminateJobObject(job: NativePtr, exitCode: number): number;
     getStdHandle(stdHandle: number): NativePtr;
 }
+/** Generic Win32 calls plus Node's libuv descriptor-to-handle bridge. */
+export interface CurrentTokenProcessBindings extends Win32ProcessBindings {
+    uvGetOsfhandle(fileDescriptor: number): NativePtr | null;
+}
 /** Koffi STARTUPINFOW layout. */
 export declare const STARTUPINFOW: import("koffi").TypeObject;
 /** Koffi PROCESS_INFORMATION layout. */
@@ -108,7 +115,12 @@ export declare function decodeProcessInfo(processInfo: NativePtr): ProcessInfoOu
  * @param create - binds only the caller-specific operations from the shared libraries.
  * @returns generic process bindings combined with the caller-specific operations.
  */
-export declare function extendWin32ProcessBindings<Extension extends object>(create: (context: Win32BindingContext) => Extension): Win32ProcessBindings & Extension;
+export declare function extendWin32ProcessBindings<Extension extends object>(create: (context: Win32BindingContext) => Extension): CurrentTokenProcessBindings & Extension;
+/**
+ * Load the generic process binding table without policy-specific extensions.
+ * @returns shared Win32 process, stdio, and Job operations.
+ */
+export declare function loadWin32ProcessBindings(): CurrentTokenProcessBindings;
 /**
  * Format a Win32 error code through FormatMessageW.
  * @param api - active binding table.

package/lib/types/index.d.ts

@@ -1,8 +1,8 @@
-/** Low-level Win32 process, stdio, and Job Object primitives used by the Windows ACL sandbox. */
+/** Shared low-level Win32 process, stdio, and Job Object primitives. */
 export { ERROR_INSUFFICIENT_BUFFER } from './abi.ts';
 export * from './errors.ts';
-export { allocPtrSlot, allocUint32, decodePtr, decodeUint32, extendWin32ProcessBindings, isNullPtr, throwLastError, throwWin32, } from './ffi.ts';
-export type { NativePtr, Win32ProcessBindings, } from './ffi.ts';
-export { drainPipe, spawnInheritedJobProcess, spawnPipedProcess, waitForProcessExit, } from './process.ts';
-export type { SpawnedJobProcess, SpawnedPipedProcess, } from './process.ts';
+export { allocPtrSlot, allocUint32, decodePtr, decodeUint32, extendWin32ProcessBindings, isNullPtr, loadWin32ProcessBindings, throwLastError, throwWin32, } from './ffi.ts';
+export type { CurrentTokenProcessBindings, NativePtr, Win32ProcessBindings, } from './ffi.ts';
+export { closeHandleChecked, drainPipe, isJobEmpty, pollProcessExit, probeCurrentTokenJobSupport, spawnInheritedJobProcess, spawnCurrentTokenJobProcess, spawnPipedProcess, terminateJob, waitForProcessExit, } from './process.ts';
+export type { CurrentTokenStdioFileDescriptors, CurrentTokenProcessSpawnOptions, SpawnedJobProcess, SpawnedPipedProcess, } from './process.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/types/process.d.ts

@@ -1,5 +1,5 @@
 /** Typed Win32 process operations over the shared binding table. */
-import type { NativePtr, Win32ProcessBindings } from './ffi.ts';
+import type { CurrentTokenProcessBindings, NativePtr, Win32ProcessBindings } from './ffi.ts';
 /**
  * Quote one argument according to CommandLineToArgvW parsing.
  * @param argument - one argv entry.
@@ -13,14 +13,31 @@ export declare function quoteArg(argument: string): string;
  * @returns joined Win32 command line.
  */
 export declare function buildCommandLine(program: string, args: readonly string[]): string;
-/** Restricted-token process creation inputs owned by the Windows ACL sandbox. */
-export interface RestrictedProcessSpawnOptions {
-    /** Executable argv entry passed through CreateProcessAsUserW. */
+interface ProcessSpawnOptions {
+    /** Executable argv entry passed through CreateProcess. */
     command: string;
     /** Arguments excluding the executable. */
     args: readonly string[];
     /** Existing child working directory. */
     cwd: string;
+}
+/** Ordinary process creation inputs used by the local Win32 runner. */
+export interface CurrentTokenProcessSpawnOptions extends ProcessSpawnOptions {
+    /** Resolved executable path passed separately from the preserved argv entry. */
+    applicationName: string;
+    /** Complete target environment passed without mutating the runner. */
+    env: Readonly<Record<string, string>>;
+    /** Runner CRT descriptors carrying target stdin, stdout, and stderr. */
+    stdio: CurrentTokenStdioFileDescriptors;
+}
+/** Runner CRT descriptors whose OS handles become the target standard handles. */
+export interface CurrentTokenStdioFileDescriptors {
+    stdin: number;
+    stdout: number;
+    stderr: number;
+}
+/** 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;
 }
@@ -67,7 +84,7 @@ export declare function drainPipe(api: Win32ProcessBindings, handle: NativePtr):
  */
 export declare function waitForProcessExit(api: Win32ProcessBindings, process: NativePtr): number;
 /**
- * Spawn suspended, assign the child to a kill-on-close Job, then resume it.
+ * Spawn a restricted-token process suspended, 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.
@@ -77,4 +94,45 @@ export declare function waitForProcessExit(api: Win32ProcessBindings, process: N
  * failure must not replace the already-created child's outcome.
  */
 export declare function spawnInheritedJobProcess(api: Win32ProcessBindings, options: RestrictedProcessSpawnOptions): SpawnedJobProcess;
+/**
+ * Spawn an ordinary process suspended, 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.
+ */
+export declare function spawnCurrentTokenJobProcess(api: CurrentTokenProcessBindings, options: CurrentTokenProcessSpawnOptions): SpawnedJobProcess;
+/**
+ * Verify that an unnamed kill-on-close Job can be created and released now.
+ * @param api - active binding table.
+ */
+export declare function probeCurrentTokenJobSupport(api: CurrentTokenProcessBindings): void;
+/**
+ * Poll one process handle without blocking the runner event loop.
+ * @param api - active binding table.
+ * @param process - caller-owned process handle.
+ * @returns the direct exit code when signalled, or undefined while running.
+ */
+export declare function pollProcessExit(api: Win32ProcessBindings, process: NativePtr): number | undefined;
+/**
+ * Return whether a Job has no active processes.
+ * @param api - active binding table.
+ * @param job - caller-owned Job handle.
+ * @returns true once the Job reports zero active processes.
+ */
+export declare function isJobEmpty(api: Win32ProcessBindings, job: NativePtr): boolean;
+/**
+ * Terminate every process in a Job.
+ * @param api - active binding table.
+ * @param job - caller-owned Job handle.
+ * @param exitCode - direct Windows exit code assigned to members.
+ */
+export declare function terminateJob(api: Win32ProcessBindings, job: NativePtr, exitCode: number): void;
+/**
+ * Close a caller-owned handle and report a labelled Win32 failure.
+ * @param api - active binding table.
+ * @param handle - handle to close.
+ * @param detail - lifecycle label for diagnostics.
+ */
+export declare function closeHandleChecked(api: Win32ProcessBindings, handle: NativePtr, detail: string): void;
+export {};
 //# sourceMappingURL=process.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-win32-process",
-  "description": "Low-level Win32 process, stdio, and Job Object primitives for the DeepSeek Harness Windows sandbox",
-  "version": "0.1.2-alpha.5",
+  "description": "Shared low-level Win32 process, stdio, and Job Object primitives",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },