Merge pull request #2714 from deepseek-harness/codex/subprocess-win32-process-primitives

refactor(win32-process): share native process primitives

.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.md
+2026-08-19-shared-win32-process-primitives.md: 8765e5f7350dab56ad42169f6e16b55679ca8982
+2026-08-19-shared-win32-process-primitives.zh.md: b21ece8445e8863c08818c42d6c9bf7672813823

.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.md

@@ -0,0 +1,35 @@
+# Agent Note: Windows sandbox process primitives have one low-level owner
+
+Status: implemented
+
+English | [中文](2026-08-19-shared-win32-process-primitives.zh.md)
+
+## Problem
+
+The Windows ACL sandbox owns restricted-token, SID, DACL, grant, and workspace policy, but its process launch path also carried the generic Koffi ABI, command-line quoting, anonymous pipes, inherited stdio, Job setup, waits, and HANDLE cleanup. A second Windows process consumer would otherwise have to depend on sandbox policy or copy native resource logic, while fixes to allocation and failure cleanup would need to remain synchronized.
+
+## Decision
+
+`@deepseek-ai/dsh-win32-process` owns the reusable Win32 process ABI and native resource operations currently consumed by `sandbox-windows-acl`. The package lazily loads `kernel32.dll` and `advapi32.dll`, verifies the x64 `STARTUPINFOW` and `PROCESS_INFORMATION` layouts, quotes argv for `CreateProcessAsUserW`, and exposes checked restricted-token pipe and inherited-stdio Job operations.
+
+The Windows ACL sandbox remains the only owner of restricted-token creation, SID and DACL policy, grants, writable-path decisions, temporary-directory policy, and the public sandbox child result. It extends the shared binding context with policy-specific APIs, supplies the primary token, combines pipe drains and waits, and closes the caller-owned Job at its lifecycle boundary.
+
+Every native allocation and HANDLE has one owner within each shared operation. A process operation frees its Koffi out-parameters and closes every pipe, thread, process, or Job handle it acquired before a controlled failure. Successful pipe creation returns the process plus stdout/stderr read handles to the sandbox. Inherited-stdio creation starts the target suspended, assigns it to the kill-on-close Job, and resumes it only after assignment, so target code cannot run outside the Job. Assignment failure terminates the suspended target before releasing its handles; resume failure closes the assigned Job. The sandbox retains its existing pipe-drain, direct-wait, result, and returned-Job lifecycle.
+
+The package exports only operations used by the sandbox production path. Ordinary `CreateProcessW`, exact `applicationName`, parent-stdio release, and whole-Job settlement remain absent until an ordinary process consumer needs them. The package is a library, not a Cordis service or a public Windows SDK.
+
+## Verification
+
+The shared suite covers x64 ABI values, command-line quoting, binding extension, pipe EOF and drain allocation reuse, restricted-token process creation, suspended creation followed by Job assignment and resume, wait and exit-code reads, native allocation release, and the acquired-resource failure paths. Sandbox tests retain restricted-token, fail-closed, pipe/inherit, result, and disposal composition without duplicating the low-level matrix. The committed header probes and Windows package tests cover the migrated ABI and native paths; Wine supplies the emulated Windows package and composition signal.
+
+## Alternatives considered
+
+**Keep process primitives inside the sandbox package.** Rejected because a process consumer would inherit ACL/token policy or duplicate the native ABI and cleanup paths.
+
+**Copy the Koffi implementation into each consumer.** Rejected because struct layouts, error capture, and partial-failure cleanup would have multiple owners.
+
+**Publish ordinary-runner operations before a current consumer exists.** Rejected because unused `CreateProcessW`, application-name, parent-stdio, and Job-settlement APIs would freeze speculative obligations and enlarge the failure matrix.
+
+## Consequences
+
+The sandbox keeps its public behavior while generic Win32 resource ownership has one package and one test home. The package boundary adds one workspace dependency and a published library, and callers must explicitly own policy, scheduling, result composition, and returned HANDLE closure. Suspended creation guarantees that target code starts only after Job assignment, but it does not make the runner's create-to-assignment interval atomic against external termination. Future process consumers extend the low-level package only when their production path exists.

.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.zh.md

@@ -0,0 +1,35 @@
+# Agent Note：Windows sandbox process primitives 只有一个低层 owner
+
+Status: implemented
+
+[English](2026-08-19-shared-win32-process-primitives.md) | 中文
+
+## Problem
+
+Windows ACL sandbox 拥有 restricted token、SID、DACL、grant 与 workspace policy，但其进程启动路径还同时承载通用 Koffi ABI、命令行引用、匿名管道、继承 stdio、Job 设置、wait 与 HANDLE 清理。第二个 Windows process consumer 否则只能依赖 sandbox policy 或复制 native resource 逻辑，而 allocation 与失败清理修复也必须在多份实现间保持同步。
+
+## Decision
+
+`@deepseek-ai/dsh-win32-process` 拥有 `sandbox-windows-acl` 当前消费的可复用 Win32 process ABI 与 native resource 操作。该包惰性加载 `kernel32.dll` 和 `advapi32.dll`，核验 x64 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 布局，为 `CreateProcessAsUserW` 引用 argv，并提供带检查的 restricted-token pipe 与 inherited-stdio Job 操作。
+
+Windows ACL sandbox 继续唯一拥有 restricted-token 创建、SID 与 DACL policy、grants、可写路径裁定、临时目录 policy 和公共 sandbox child result。它通过共享 binding context 扩展 policy-specific API，提供 primary token，组合 pipe drain 与 wait，并在自己的生命周期边界关闭调用方拥有的 Job。
+
+每项 native allocation 与 HANDLE 在各个 shared operation 内只有一个 owner。process operation 会释放 Koffi out-parameter，并在受控失败前关闭它已经取得的每个 pipe、thread、process 或 Job handle。pipe 创建成功时，把 process 与 stdout/stderr read handles 返回给 sandbox。inherited-stdio 创建以 suspended 状态启动目标，把它分配给 kill-on-close Job，并只在分配后恢复，因此目标代码不会在 Job 外运行。分配失败会先终止 suspended target 再释放句柄；恢复失败会关闭已经分配的 Job。sandbox 保留既有 pipe-drain、direct-wait、result 与返回 Job 的生命周期。
+
+该包只导出 sandbox 生产路径已使用的操作。ordinary `CreateProcessW`、精确 `applicationName`、parent-stdio release 与 whole-Job settlement 在 ordinary process consumer 出现前保持缺席。该包是 library，不是 Cordis service 或公共 Windows SDK。
+
+## Verification
+
+shared suite 覆盖 x64 ABI 值、命令行引用、binding extension、pipe EOF 与 drain allocation 复用、restricted-token process 创建、suspended 创建后的 Job 分配与恢复、wait 与 exit-code 读取、native allocation 释放，以及已取得资源的失败路径。sandbox 测试保留 restricted-token、fail-closed、pipe/inherit、result 与 disposal 组合行为，不重复低层矩阵。已提交的 header probe 与 Windows package 测试覆盖迁移后的 ABI 和 native 路径；Wine 提供模拟 Windows package 与组合信号。
+
+## Alternatives considered
+
+**把 process primitives 留在 sandbox package。** 拒绝，因为 process consumer 将被迫继承 ACL/token policy，或复制 native ABI 与清理路径。
+
+**为每个 consumer 复制 Koffi 实现。** 拒绝，因为 struct layout、错误捕获与局部失败清理会出现多个 owner。
+
+**在当前 consumer 出现前发布 ordinary-runner operations。** 拒绝，因为未使用的 `CreateProcessW`、application-name、parent-stdio 与 Job-settlement API 会冻结推测性义务，并扩大失败矩阵。
+
+## Consequences
+
+sandbox 保持公共行为，而通用 Win32 resource ownership 只有一个 package 与一个测试归属。该 package boundary 增加一个 workspace dependency 和发布 library；调用方必须显式拥有 policy、调度、result 组合与返回 HANDLE 的关闭责任。suspended 创建保证目标代码只在 Job 分配后启动，但不会让 runner 的 create-to-assignment 区间对外部终止具备原子性。后续 process consumer 只在其生产路径存在时扩展低层 package。

AGENTS.md

@@ -17,7 +17,7 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   llm/         LLM capability: Service Definition/Consumer + DeepSeek providers
   e2b/         E2B POC: sandbox + FS/subprocess adapters
   shell/        bash capability: Service Definition + local/pwsh providers + shell Consumers
-  subprocess/  subprocess capability + local process-tree provider
+  subprocess/  subprocess capability + local process-tree provider + shared Win32 library
   terminal/         persistent sessions
   fs/          filesystem capability + policy
   lsp/         language-server capability

docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: bc79f900e863fa9ef357a533fe4ba857a20a8bcb
-config-catalog.zh.md: cfddaf2620dd8c3dba05ccd785c6aeceb14a9bba
+config-catalog.md: a41538ffc2fc18939e015e8c08676868f588d897
+config-catalog.zh.md: 9481cb2b4db13d7d91c11e323e8d1118184f5bfe

docs/config-catalog.md

@@ -3353,3 +3353,4 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-typert-protocol` ([`packages/typert/protocol/src/index.ts`](../packages/typert/protocol/src/index.ts))
 - `@deepseek-ai/dsh-typert-registry` ([`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts))
 - `@deepseek-ai/dsh-util-crypto` ([`packages/util/crypto/src/index.ts`](../packages/util/crypto/src/index.ts))
+- `@deepseek-ai/dsh-win32-process` ([`packages/subprocess/win32-process/src/index.ts`](../packages/subprocess/win32-process/src/index.ts))

docs/config-catalog.zh.md

@@ -3354,3 +3354,4 @@ export interface Config {
 - `@deepseek-ai/dsh-typert-protocol`（[`packages/typert/protocol/src/index.ts`](../packages/typert/protocol/src/index.ts)）
 - `@deepseek-ai/dsh-typert-registry`（[`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts)）
 - `@deepseek-ai/dsh-util-crypto`（[`packages/util/crypto/src/index.ts`](../packages/util/crypto/src/index.ts)）
+- `@deepseek-ai/dsh-win32-process`（[`packages/subprocess/win32-process/src/index.ts`](../packages/subprocess/win32-process/src/index.ts)）

docs/module-graph.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 docs/module-graph.md
-module-graph.md: edc3adfa3badf075abbd1167de6acc4a6f1d0037
-module-graph.zh.md: fc2d6e0d9a77012c38b2b3bc6a1434ac8700fa59
+module-graph.md: fb65171fab57b9030e5783486bdc487558d6c4f4
+module-graph.zh.md: 5532393b35e08cbdc3c9caa4a055d3dc63640915

docs/module-graph.md

@@ -308,6 +308,7 @@ flowchart TD
   subgraph group_subprocess["packages/subprocess"]
     pkg_subprocess["subprocess"]
     pkg_subprocess_local["subprocess-local"]
+    pkg_win32_process["win32-process"]
   end
   subgraph group_terminal["packages/terminal"]
     pkg_terminal["terminal"]
@@ -363,6 +364,7 @@ flowchart TD
   pkg_sandbox_windows_acl --> pkg_invariants
   pkg_storage --> pkg_invariants
   pkg_subprocess --> pkg_invariants
+  pkg_win32_process --> pkg_invariants
   pkg_llm_mock_server --> pkg_invariants
   pkg_typert_generator --> pkg_invariants
   pkg_typert_protocol --> pkg_invariants
@@ -1499,6 +1501,7 @@ flowchart TD
 | [`sandbox-windows-acl`](../packages/sandbox/sandbox-windows-acl) | `sandbox` | [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`storage`](../packages/storage/storage) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`subprocess`](../packages/subprocess/subprocess) | `subprocess` | [`invariants`](../packages/runtime-diagnostics/invariants) |
+| [`win32-process`](../packages/subprocess/win32-process) | `subprocess` | [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`llm-mock-server`](../packages/test-support/llm-mock-server) | `test-support` | [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`typert-generator`](../packages/typert/generator) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`typert-protocol`](../packages/typert/protocol) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants) |

docs/module-graph.zh.md

@@ -310,6 +310,7 @@ flowchart TD
   subgraph group_subprocess["packages/subprocess"]
     pkg_subprocess["subprocess"]
     pkg_subprocess_local["subprocess-local"]
+    pkg_win32_process["win32-process"]
   end
   subgraph group_terminal["packages/terminal"]
     pkg_terminal["terminal"]
@@ -365,6 +366,7 @@ flowchart TD
   pkg_sandbox_windows_acl --> pkg_invariants
   pkg_storage --> pkg_invariants
   pkg_subprocess --> pkg_invariants
+  pkg_win32_process --> pkg_invariants
   pkg_llm_mock_server --> pkg_invariants
   pkg_typert_generator --> pkg_invariants
   pkg_typert_protocol --> pkg_invariants
@@ -1501,6 +1503,7 @@ flowchart TD
 | [`sandbox-windows-acl`](../packages/sandbox/sandbox-windows-acl) | `sandbox` | [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`storage`](../packages/storage/storage) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`subprocess`](../packages/subprocess/subprocess) | `subprocess` | [`invariants`](../packages/runtime-diagnostics/invariants) |
+| [`win32-process`](../packages/subprocess/win32-process) | `subprocess` | [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`llm-mock-server`](../packages/test-support/llm-mock-server) | `test-support` | [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`typert-generator`](../packages/typert/generator) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`typert-protocol`](../packages/typert/protocol) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants) |

packages/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/README.md
-README.md: c455feb38489400b6e96101661103dfdeb0d2083
-README.zh.md: 1ce6ca2f019c2cab35fe33e911dcddf20f8589a5
+README.md: ad88e895cec423b71dbc3c0e961ddb8901e0f66d
+README.zh.md: 81557ab3b9f3d7a00af6a5ad45a9e04cc7ea063b

packages/README.md

@@ -19,7 +19,7 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
 | [`identity/`](identity/README.md) | Shared anonymous identity | Product — stable API |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable API |
 | [`e2b/`](e2b/README.md) | E2B providers | POC |
-| [`subprocess/`](subprocess/README.md) | Subprocess capability family: Service Definition + local process-tree provider | Product — stable API |
+| [`subprocess/`](subprocess/README.md) | Subprocess capability family: Service Definition, local process-tree provider, and shared Win32 process library | Product — stable API |
 | [`shell/`](shell/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable API |
 | [`terminal/`](terminal/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable API |
 | [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: Service Definition + worker-thread provider + Code Mode Consumer | Product — stable API |

packages/README.zh.md

@@ -19,7 +19,7 @@ npm scope 为 `@deepseek-ai/dsh-*`；Cordis `Service` 子类和函数插件通
 | [`identity/`](identity/README.zh.md) | 共享匿名身份 | 产品：稳定 API |
 | [`llm/`](llm/README.zh.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定 API |
 | [`e2b/`](e2b/README.zh.md) | E2B 提供方 | POC |
-| [`subprocess/`](subprocess/README.zh.md) | 子进程能力系列：Service Definition + 本地进程树提供方 | 产品：稳定 API |
+| [`subprocess/`](subprocess/README.zh.md) | 子进程能力系列：Service Definition、本地进程树提供方与共享 Win32 进程库 | 产品：稳定 API |
 | [`shell/`](shell/README.zh.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定 API |
 | [`terminal/`](terminal/README.zh.md) | 持久 PTY 能力系列：限定所有者范围的会话、本地实现和面向模型的工具 | 产品：稳定 API |
 | [`code-runtime/`](code-runtime/README.zh.md) | 代码执行能力系列：Service Definition + worker 线程提供方 + Code Mode Consumer | 产品：稳定 API |

packages/sandbox/sandbox-local/tests/packed-install.e2e.ts

@@ -32,6 +32,7 @@ const WORKSPACE_CLOSURE = [
   // consumer resolves it like any other @deepseek-ai peer (koffi arrives
   // from the registry).
   'packages/sandbox/sandbox-windows-acl',
+  'packages/subprocess/win32-process',
   'packages/sandbox/sandbox',
   'packages/core/session',
   'packages/core/scope',

packages/sandbox/sandbox-windows-acl/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/sandbox/sandbox-windows-acl/README.md
-README.md: a78f334342196ec1848a4a360e5c60b375a28057
-README.zh.md: dc7f4d4c080d4e2204103afb8b1a2defcfb306c7
+README.md: 2cf79c8eede0943630f79bea717c9e072226fa7f
+README.zh.md: 0e2ed516c84268c9b44a7a3987cbb90bcc2d7696

packages/sandbox/sandbox-windows-acl/README.md

@@ -38,7 +38,7 @@ sandbox.dispose() // revokes the revocable (temp) grant, keeps the standing work
 rmSync(tempDir, { recursive: true, force: true })
 ```
 
-A direct `AclSandbox` requires an explicit private temp directory (or `tempDir: null`; the ambient temp root is never an implicit grant), grants the workspace ACEs STANDING (dispose() leaves them — they are the cross-instance reuse cache), and grants the distinct temp SID revocably. The server-side reuse is the `AclWriteGrant` class: `add(path, standing)` per directory, `dispose()` revokes the revocable paths and frees the SID — see the runner contract below. Every Win32 API call in this package is checked; failures throw `Win32Error` carrying the API name, the exact Win32 code, the `FormatMessageW` system text, and the failing path/context. This is deliberate: the POC ignored every return value and, when `CreateRestrictedToken` failed, silently ran the child with the FULL unrestricted token (fail-open). This port fails closed by construction.
+A direct `AclSandbox` requires an explicit private temp directory (or `tempDir: null`; the ambient temp root is never an implicit grant), grants the workspace ACEs STANDING (dispose() leaves them — they are the cross-instance reuse cache), and grants the distinct temp SID revocably. The server-side reuse is the `AclWriteGrant` class: `add(path, standing)` per directory, `dispose()` revokes the revocable paths and frees the SID — see the runner contract below. Every policy-specific Win32 call and every process primitive from [`dsh-win32-process`](../../subprocess/win32-process/README.md) is checked; failures throw `Win32Error` carrying the API name, the exact Win32 code, the `FormatMessageW` system text, and the failing path/context. This is deliberate: the POC ignored every return value and, when `CreateRestrictedToken` failed, silently ran the child with the FULL unrestricted token (fail-open). This port fails closed by construction.
 
 ## The confinement runner
 
@@ -62,14 +62,12 @@ The `AclSandbox` class (explicit private `tempDir` + `tempWriteSid`, or `tempDir
 
 ## Header verification
 
-All constants, signatures, and struct layouts were verified against the Windows headers on the development machine (MinGW `winnt.h` / `accctrl.h` / `aclapi.h` / `securitybaseapi.h` / `sddl.h` / `processthreadsapi.h` / `fileapi.h` / `namedpipeapi.h` / `synchapi.h` / `winbase.h`) and are cross-checked at runtime by [`verify/abi-probe.cpp`](verify/abi-probe.cpp) (sizes, offsets, enum values, static asserts):
+The sandbox-owned SID, ACL, token, file, and lock constants and layouts were verified against the Windows headers on the development machine (MinGW `winnt.h` / `accctrl.h` / `aclapi.h` / `securitybaseapi.h` / `sddl.h` / `fileapi.h`) and are cross-checked by [`verify/abi-probe.cpp`](verify/abi-probe.cpp). The shared process, stdio, and Job ABI is owned and verified by [`@deepseek-ai/dsh-win32-process`](../../subprocess/win32-process/README.md#header-verification).
 
 ```sh
 g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp -ladvapi32 && ./abi-probe.exe
 ```
 
-The koffi struct definitions assert their sizes against the probe at module load, so a header/koffi layout drift fails loudly instead of corrupting memory.
-
 ## Verified boundaries (inherent to restricted tokens, not this port)
 
 - **Everyone grants remain ambient write authority.** Everyone must stay in both restricting lists: removing it breaks early DLL initialization and CNG. An external NTFS object whose normal DACL grants Everyone a requested write right therefore clears both access checks and stays writable under both modes. The real runner suite provisions an external `Everyone:Modify` directory and pins that behavior; the provider reports `enforcement: 'partial'` so callers can reject or surface the weaker boundary.

packages/sandbox/sandbox-windows-acl/README.zh.md

@@ -38,7 +38,7 @@ sandbox.dispose() // revokes the revocable (temp) grant, keeps the standing work
 rmSync(tempDir, { recursive: true, force: true })
 ```
 
-直接使用 `AclSandbox` 时，必须显式提供私有临时目录（或通过 `tempDir: null` 禁用临时写入；环境临时根目录绝不会被隐式授权），工作区 ACE 以**常驻**方式授予（`dispose()` 保留它们——它们是跨实例的复用缓存），不同的临时 SID 则以**可回收**方式授予。服务端复用则是 `AclWriteGrant` 类：每个目录一次 `add(path, standing)`，`dispose()` 撤销可回收路径并释放 SID——见下方 runner 契约。本包中的每个 Win32 API 调用都有检查；失败抛出 `Win32Error`，携带 API 名、精确 Win32 错误码、`FormatMessageW` 系统文本和失败的路径/上下文。这是刻意的：POC 忽略每个返回值，当 `CreateRestrictedToken` 失败时用完整无限制令牌静默运行子进程（fail-open）。本移植从构造上 fail-closed。
+直接使用 `AclSandbox` 时，必须显式提供私有临时目录（或通过 `tempDir: null` 禁用临时写入；环境临时根目录绝不会被隐式授权），工作区 ACE 以**常驻**方式授予（`dispose()` 保留它们——它们是跨实例的复用缓存），不同的临时 SID 则以**可回收**方式授予。服务端复用则是 `AclWriteGrant` 类：每个目录一次 `add(path, standing)`，`dispose()` 撤销可回收路径并释放 SID——见下方 runner 契约。每个 policy-specific Win32 调用和 [`dsh-win32-process`](../../subprocess/win32-process/README.zh.md) 提供的 process primitive 都有检查；失败抛出 `Win32Error`，携带 API 名、精确 Win32 错误码、`FormatMessageW` 系统文本和失败的路径/上下文。这是刻意的：POC 忽略每个返回值，当 `CreateRestrictedToken` 失败时用完整无限制令牌静默运行子进程（fail-open）。本移植从构造上 fail-closed。
 
 <a id="the-confinement-runner"></a>
 
@@ -64,14 +64,12 @@ Authenticated Users 在**两种**列表中都不存在——WMI 命名空间安
 
 ## 头部验证
 
-所有常量、签名与结构体布局都在开发机上对照 Windows 头文件（MinGW `winnt.h` / `accctrl.h` / `aclapi.h` / `securitybaseapi.h` / `sddl.h` / `processthreadsapi.h` / `fileapi.h` / `namedpipeapi.h` / `synchapi.h` / `winbase.h`）验证过，并在运行时由 [`verify/abi-probe.cpp`](verify/abi-probe.cpp)（大小、偏移、枚举值、静态断言）交叉检查：
+sandbox 自有的 SID、ACL、token、文件与锁常量和布局均已在开发机上对照 Windows 头文件（MinGW `winnt.h` / `accctrl.h` / `aclapi.h` / `securitybaseapi.h` / `sddl.h` / `fileapi.h`）验证，并由 [`verify/abi-probe.cpp`](verify/abi-probe.cpp) 交叉检查。共享的 process、stdio 与 Job ABI 由 [`@deepseek-ai/dsh-win32-process`](../../subprocess/win32-process/README.zh.md#header-verification) 归属并验证。
 
 ```sh
 g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp -ladvapi32 && ./abi-probe.exe
 ```
 
-koffi 结构体定义在模块加载时对照探针断言其大小，因此头文件/koffi 布局漂移会大声失败而不是破坏内存。
-
 ## 已验证边界（受限令牌固有，非本移植引入）
 
 - **Everyone 授权仍是环境中的写权限来源。** Everyone 必须保留在两种 restricting 列表中：移除它会破坏早期 DLL 初始化与 CNG。因此，如果外部 NTFS 对象的正常 DACL 向 Everyone 授予所请求的写权限，它就会同时通过两次访问检查，并在两种模式下保持可写。真实 runner 套件配置一个外部 `Everyone:Modify` 目录并钉住该行为；提供方报告 `enforcement: 'partial'`，使调用方能够拒绝或向上暴露这项较弱的边界。

packages/sandbox/sandbox-windows-acl/package.json

@@ -42,6 +42,7 @@
     "@deepseek-ai/cordis": "workspace:^"
   },
   "dependencies": {
+    "@deepseek-ai/dsh-win32-process": "workspace:^",
     "koffi": "^3.1.0"
   },
   "devDependencies": {

packages/sandbox/sandbox-windows-acl/src/errors.ts

@@ -1,21 +0,0 @@
-/**
- * Fail-closed Win32 error type. Every backend API failure raises this with the
- * API name and the exact Win32 code; the original POC silently ignored every
- * failed call and would run children UNRESTRICTED (fail-open) — that is the
- * failure mode this class exists to prevent.
- * @module @deepseek-ai/dsh-sandbox-windows-acl/errors
- */
-
-export class Win32Error extends Error {
-  /** The failing Win32 API name, e.g. `CreateRestrictedToken`. */
-  readonly api: string
-  /** The Win32 error code (`GetLastError` for BOOL APIs, the HRESULT-style return for ACL APIs). */
-  readonly win32Code: number
-
-  constructor(api: string, win32Code: number, detail?: string) {
-    super(`${api} failed (Win32 ${win32Code})${detail === undefined ? '' : `: ${detail}`}`)
-    this.name = 'Win32Error'
-    this.api = api
-    this.win32Code = win32Code
-  }
-}

packages/sandbox/sandbox-windows-acl/src/ffi.ts

@@ -1,512 +1,299 @@
-/**
- * Lazy koffi bindings for the Win32 ACL-sandbox backend. Koffi loads lazily so
- * non-Windows processes never open Win32 libraries. Every function signature
- * below was verified against the MinGW Windows headers on this machine
- * (winnt.h / accctrl.h / aclapi.h / securitybaseapi.h / sddl.h /
- * processthreadsapi.h / fileapi.h / namedpipeapi.h / synchapi.h / winbase.h);
- * struct layouts are asserted at load time against verify/abi-probe.cpp.
- * @module @deepseek-ai/dsh-sandbox-windows-acl/ffi
- */
+/** ACL/token bindings layered on the shared Win32 process owner. */
 
 import koffi from 'koffi'
-import { Win32Error } from './errors.ts'
+import {
+  ERROR_INSUFFICIENT_BUFFER,
+  Win32Error,
+  extendWin32ProcessBindings,
+  isNullPtr,
+  throwLastError,
+} from '@deepseek-ai/dsh-win32-process'
+import type { NativePtr, Win32ProcessBindings } from '@deepseek-ai/dsh-win32-process'
 import * as abi from './win32-abi.ts'
 
-/** Branded koffi 3 native pointer. Koffi 3 pointers are BigInt values; the brand keeps them out of numeric contexts. */
-declare const nativePtr: unique symbol
-/** Koffi 3 native pointer (a BigInt address), branded so it cannot silently enter numeric contexts. */
-export type NativePtr = bigint & { readonly [nativePtr]: true }
-
-/**
- * True for NULL pointers, however koffi returns them (null or 0n).
- * @param value - a pointer as koffi may hand it back (pointer, null, or 0n).
- * @returns a type guard narrowing to the NULL shapes.
- */
-export function isNullPtr(value: NativePtr | null | undefined): value is null | undefined {
-  return value === null || value === undefined || (value as bigint) === 0n
-}
-
-/**
- * True for CreateFileW's INVALID_HANDLE_VALUE failure marker (-1, which
- * koffi hands back as the unsigned 64-bit all-ones pointer).
- * @param handle - the handle CreateFileW returned.
- * @returns whether the handle signals failure.
- */
-export function isInvalidHandle(handle: NativePtr | null | undefined): boolean {
-  if (isNullPtr(handle)) return true
-  return (handle as bigint) === 0xFFFFFFFFFFFFFFFFn || (handle as bigint) === -1n
-}
+export {
+  allocPtrSlot,
+  allocUint32,
+  decodePtr,
+  decodeUint32,
+  isNullPtr,
+  throwLastError,
+  throwWin32,
+} from '@deepseek-ai/dsh-win32-process'
+export type { NativePtr } from '@deepseek-ai/dsh-win32-process'
 
 type Ptr = ReturnType<typeof koffi.pointer>
+const PVOID: Ptr = koffi.pointer('void')
+const PPVOID: Ptr = koffi.pointer(PVOID)
 
-/** Field subset written into a zeroed STARTUPINFOW (layout verified: size 104). */
-export interface StartupInfoInput {
-  cb: number
-  dwFlags: number
-  hStdInput: NativePtr
-  hStdOutput: NativePtr
-  hStdError: NativePtr
-}
-
-/** Decoded PROCESS_INFORMATION (layout verified: size 24). */
-export interface ProcessInfoOutput {
-  hProcess: NativePtr | null
-  hThread: NativePtr | null
-  dwProcessId: number
-  dwThreadId: number
-}
-
-/** The lazy koffi binding table: every Win32 call the ACL backend uses, signature-verified against the real headers. */
-export interface Win32Bindings {
-  // ---- process / token handles --------------------------------------------
+/** ACL/token calls composed with the generic Win32 process binding table. */
+export interface Win32Bindings extends Win32ProcessBindings {
   openProcess(desiredAccess: number, inheritHandle: number, pid: number): NativePtr
   openProcessToken(process: NativePtr, desiredAccess: number, tokenHandle: NativePtr): number
-  closeHandle(handle: NativePtr): number
-  // ---- errors / diagnostics ------------------------------------------------
-  getLastError(): number
-  formatMessageW(flags: number, source: null, messageId: number, languageId: number, buffer: Buffer, size: number, args: null): number
-  // ---- memory --------------------------------------------------------------
   localAlloc(flags: number, bytes: number): NativePtr
   localFree(memory: NativePtr): NativePtr
-  // ---- SIDs ----------------------------------------------------------------
   convertStringSidToSidW(stringSid: string, sid: NativePtr): number
   createWellKnownSid(type: number, domainSid: null, sid: NativePtr, size: NativePtr): number
   isValidSid(sid: NativePtr): number
   getLengthSid(sid: NativePtr): number
   copySid(length: number, destination: NativePtr, source: NativePtr): number
-  // ---- token information ---------------------------------------------------
   getTokenInformation(token: NativePtr, cls: number, info: Buffer | null, length: number, needed: NativePtr): number
   setTokenInformation(token: NativePtr, cls: number, info: Buffer, length: number): number
-  // ---- restricted token ----------------------------------------------------
   createRestrictedToken(
-    existing: NativePtr, flags: number,
-    disableCount: number, disableSids: null,
-    deletePrivilegeCount: number, privilegesToDelete: null,
-    restrictCount: number, restrictingSids: Buffer,
+    existing: NativePtr,
+    flags: number,
+    disableCount: number,
+    disableSids: null,
+    deletePrivilegeCount: number,
+    privilegesToDelete: null,
+    restrictCount: number,
+    restrictingSids: Buffer,
     newToken: NativePtr,
   ): number
-  // ---- ACL editing ---------------------------------------------------------
   setEntriesInAclW(count: number, entries: Buffer, oldAcl: NativePtr | null, newAcl: NativePtr): number
   setNamedSecurityInfoW(
-    path: string, objectType: number, information: number,
-    owner: null, group: null, dacl: NativePtr | null, sacl: null,
+    path: string,
+    objectType: number,
+    information: number,
+    owner: null,
+    group: null,
+    dacl: NativePtr | null,
+    sacl: null,
   ): number
   getNamedSecurityInfoW(
-    path: string, objectType: number, information: number,
-    owner: NativePtr, group: NativePtr, dacl: NativePtr, sacl: NativePtr, descriptor: NativePtr,
+    path: string,
+    objectType: number,
+    information: number,
+    owner: NativePtr,
+    group: NativePtr,
+    dacl: NativePtr,
+    sacl: NativePtr,
+    descriptor: NativePtr,
   ): number
-  // ---- environment / io ----------------------------------------------------
   getTempPathW(length: number, buffer: Buffer): number
+  setEnvironmentVariableW(name: string, value: string): number
+  setConsoleCtrlHandler(handler: null, add: number): number
   createFileW(
-    fileName: string, desiredAccess: number, shareMode: number, attributes: null,
-    creationDisposition: number, flagsAndAttributes: number, templateFile: null,
+    fileName: string,
+    desiredAccess: number,
+    shareMode: number,
+    attributes: null,
+    creationDisposition: number,
+    flagsAndAttributes: number,
+    templateFile: null,
   ): NativePtr
-  lockFileEx(file: NativePtr, flags: number, reserved: number, bytesLow: number, bytesHigh: number, overlapped: NativePtr): number
-  unlockFileEx(file: NativePtr, reserved: number, bytesLow: number, bytesHigh: number, overlapped: NativePtr): 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,
+  lockFileEx(
+    file: NativePtr,
+    flags: number,
+    reserved: number,
+    bytesLow: number,
+    bytesHigh: number,
+    overlapped: NativePtr,
   ): number
-  setEnvironmentVariableW(name: string, value: string): number
-  readFile(file: NativePtr, buffer: Buffer, count: number, bytesRead: NativePtr, overlapped: null): number
-  peekNamedPipe(
-    pipe: NativePtr, buffer: null, size: number,
-    bytesRead: NativePtr, totalAvail: NativePtr, leftThisMessage: NativePtr,
+  unlockFileEx(
+    file: NativePtr,
+    reserved: number,
+    bytesLow: number,
+    bytesHigh: number,
+    overlapped: NativePtr,
   ): number
-  waitForSingleObject(handle: NativePtr, milliseconds: number): number
-  getExitCodeProcess(process: NativePtr, exitCode: NativePtr): number
-  resumeThread(thread: NativePtr): number
-  // ---- job object (runner kill-on-close) -----------------------------------
-  createJobObjectW(attributes: null, name: null): NativePtr
-  setInformationJobObject(job: NativePtr, cls: number, information: Buffer, length: number): number
-  assignProcessToJobObject(job: NativePtr, process: NativePtr): number
-  // Terminate a suspended child that could not be placed in the kill-on-close
-  // job — closing handles alone would leave it hanging forever.
-  terminateProcess(process: NativePtr, exitCode: number): number
-  // ---- console -------------------------------------------------------------
-  // HandlerRoutine=null + add=1 makes this process ignore CTRL+C (wincon.h):
-  // the runner survives console Ctrl+C so the child handles its own and the
-  // runner can clean up grants after the child exits.
-  setConsoleCtrlHandler(handler: null, add: number): number
-  getStdHandle(stdHandle: number): NativePtr
 }
 
-const PVOID: Ptr = koffi.pointer('void')
-const PPVOID: Ptr = koffi.pointer(PVOID)
-
-/** koffi STARTUPINFOW layout; its size is asserted against abi.STARTUPINFOW_SIZE at load. */
-export const STARTUPINFOW = koffi.struct('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; its size is asserted against abi.PROCESS_INFORMATION_SIZE at load. */
-export const PROCESS_INFORMATION = koffi.struct('PROCESS_INFORMATION', {
-  hProcess: PVOID,
-  hThread: PVOID,
-  dwProcessId: 'uint32',
-  dwThreadId: 'uint32',
-})
-
-/* v8 ignore start -- layout-mismatch guards fire only on ABI breakage; verify/abi-probe.cpp pins both sizes. */
-if (STARTUPINFOW.size !== abi.STARTUPINFOW_SIZE) {
-  throw new Error(`STARTUPINFOW layout mismatch: koffi computed ${STARTUPINFOW.size}, header probe says ${abi.STARTUPINFOW_SIZE}`)
-}
-if (PROCESS_INFORMATION.size !== abi.PROCESS_INFORMATION_SIZE) {
-  throw new Error(`PROCESS_INFORMATION layout mismatch: koffi computed ${PROCESS_INFORMATION.size}, header probe says ${abi.PROCESS_INFORMATION_SIZE}`)
-}
-/* v8 ignore stop */
-
 /**
- * Allocate one pointer-sized slot (for `T **` out-parameters).
- * @returns the allocated slot pointer.
+ * Return whether CreateFileW produced INVALID_HANDLE_VALUE.
+ * @param handle - handle returned by CreateFileW.
+ * @returns true for null, zero, or the all-bits-one sentinel.
  */
-export function allocPtrSlot(): NativePtr {
-  const value: unknown = koffi.alloc(PVOID, 1)
-  return value as NativePtr
-}
-
-/**
- * Allocate one uint32 slot.
- * @returns the allocated slot pointer.
- */
-export function allocUint32(): NativePtr {
-  const value: unknown = koffi.alloc('uint32', 1)
-  return value as NativePtr
+export function isInvalidHandle(handle: NativePtr | null | undefined): boolean {
+  if (isNullPtr(handle)) return true
+  return (handle as bigint) === 0xFFFFFFFFFFFFFFFFn || (handle as bigint) === -1n
 }
 
 /**
- * Write a uint32 value into a slot pointer.
- * @param slot - the slot allocated by {@link allocUint32}.
- * @param value - the uint32 to encode.
+ * Encode a uint32 into an allocated slot.
+ * @param slot - slot allocated by allocUint32.
+ * @param value - unsigned value to store.
  */
 export function encodeUint32(slot: NativePtr, value: number): void {
   koffi.encode(slot, 'uint32', value)
 }
 
 /**
- * Decode the pointer stored in a pointer-sized slot (NULL becomes null).
- * @param slot - the pointer-sized slot holding the out-parameter value.
- * @returns the decoded pointer, or null for NULL.
- */
-export function decodePtr(slot: NativePtr): NativePtr | null {
-  const value: unknown = koffi.decode(slot, PVOID)
-  if (isNullPtr(value as NativePtr | null | undefined)) return null
-  return value as NativePtr
-}
-
-/**
- * Decode a uint32 at a slot pointer.
- * @param slot - the uint32 slot holding the out-parameter value.
- * @returns the decoded uint32.
- */
-export function decodeUint32(slot: NativePtr): number {
-  const value: unknown = koffi.decode(slot, 'uint32')
-  return value as number
-}
-
-/**
- * Cast a koffi pointer to its numeric address (bigint, used for raw struct packing).
- * @param ptr - the koffi pointer.
- * @returns the pointer's numeric address.
+ * Return a Koffi pointer's numeric address for struct packing.
+ * @param ptr - native pointer.
+ * @returns pointer address.
  */
 export function ptrAddress(ptr: NativePtr): bigint {
   return koffi.address(ptr)
 }
 
 /**
- * Allocate a raw byte block (used for SID copies and variable-length arrays).
- * @param length - the block size in bytes.
- * @returns the allocated block pointer.
+ * Allocate a raw byte block.
+ * @param length - byte count.
+ * @returns allocated pointer.
  */
 export function allocBytes(length: number): NativePtr {
-  const value: unknown = koffi.alloc('uint8', length)
-  return value as NativePtr
+  return koffi.alloc('uint8', length) as NativePtr
 }
 
 /**
- * Allocate one zeroed OVERLAPPED (32 bytes on x64: Internal@0, InternalHigh@8,
- * Offset@16, OffsetHigh@20, hEvent@24). LockFileEx/UnlockFileEx receive this
- * instead of a NULL lpOverlapped: koffi 3.1.1 crashes on NULL there, and a
- * zeroed OVERLAPPED on a synchronous file handle is the documented equivalent
- * (the byte range locks from offset 0, hEvent stays NULL).
- * @returns the zeroed block pointer.
+ * Allocate one zeroed x64 OVERLAPPED record.
+ * @returns allocated pointer.
+ * @remarks Koffi 3.1.1 crashes when LockFileEx or UnlockFileEx receives NULL;
+ * a zeroed OVERLAPPED is equivalent for the synchronous lock-file handle.
  */
 export function allocOverlapped(): NativePtr {
   return allocBytes(32)
 }
 
 /**
- * Decode a pointer VALUE stored in memory at `buffer[offset]` (e.g. TOKEN_GROUPS entries).
- * @param buffer - the buffer holding the pointer value.
- * @param offset - byte offset of the pointer inside the buffer.
- * @returns the decoded pointer, or null for NULL.
+ * Decode a pointer value from a Buffer field.
+ * @param buffer - encoded native record.
+ * @param offset - pointer field byte offset.
+ * @returns decoded pointer, or null for address zero.
  */
 export function decodePtrAt(buffer: Buffer, offset: number): NativePtr | null {
-  const value: unknown = koffi.decode(buffer, offset, PVOID)
-  if (isNullPtr(value as NativePtr | null | undefined)) return null
-  return value as NativePtr
+  const value = koffi.decode(buffer, offset, PVOID) as NativePtr | null
+  return isNullPtr(value) ? null : value
 }
 
 /**
- * Decode a uint8 at a native pointer plus byte offset — the ACL walk's
- * field-read primitive (koffi.decode with an offset, no memcpy, no pointer
- * arithmetic).
- * @param ptr - the native pointer to read from.
- * @param offset - byte offset from the pointer.
- * @returns the decoded uint8.
+ * Decode a uint8 field at a native pointer offset.
+ * @param ptr - native record pointer.
+ * @param offset - field byte offset.
+ * @returns decoded value.
  */
 export function decodeUint8At(ptr: NativePtr, offset: number): number {
-  const value: unknown = koffi.decode(ptr, offset, 'uint8')
-  return value as number
+  return koffi.decode(ptr, offset, 'uint8') as number
 }
 
 /**
- * Decode a uint16 at a native pointer plus byte offset (see {@link decodeUint8At}).
- * @param ptr - the native pointer to read from.
- * @param offset - byte offset from the pointer.
- * @returns the decoded uint16.
+ * Decode a uint16 field at a native pointer offset.
+ * @param ptr - native record pointer.
+ * @param offset - field byte offset.
+ * @returns decoded value.
  */
 export function decodeUint16At(ptr: NativePtr, offset: number): number {
-  const value: unknown = koffi.decode(ptr, offset, 'uint16')
-  return value as number
+  return koffi.decode(ptr, offset, 'uint16') as number
 }
 
 /**
- * Decode a uint32 at a native pointer plus byte offset (see {@link decodeUint8At}).
- * @param ptr - the native pointer to read from.
- * @param offset - byte offset from the pointer.
- * @returns the decoded uint32.
+ * Decode a uint32 field at a native pointer offset.
+ * @param ptr - native record pointer.
+ * @param offset - field byte offset.
+ * @returns decoded value.
  */
 export function decodeUint32At(ptr: NativePtr, offset: number): number {
-  const value: unknown = koffi.decode(ptr, offset, 'uint32')
-  return value as number
+  return koffi.decode(ptr, offset, 'uint32') as number
 }
 
 /**
- * Compare two SIDs field-by-field via BOUNDED offset reads (revision, count,
- * identifier authority, subauthorities up to the count) — never a fixed-size
- * struct decode, which would read past a short SID allocation (a SID with
- * fewer than 8 subauthorities is smaller than `SID_STRUCT`). An implausible
- * subauthority count reads as unequal.
- * @param left - pointer to one SID (offset 0).
- * @param leftOffset - byte offset of the SID structure within `left`.
- * @param right - pointer to the other SID.
- * @param rightOffset - byte offset of the SID structure within `right`.
- * @returns whether the SIDs are identical.
+ * Compare two in-memory SID records without allocating strings.
+ * @param left - first native buffer.
+ * @param leftOffset - first SID byte offset.
+ * @param right - second native buffer.
+ * @param rightOffset - second SID byte offset.
+ * @returns true when revision, authority, and every sub-authority match.
  */
-export function sameSidAt(left: NativePtr, leftOffset: number, right: NativePtr, rightOffset: number): boolean {
-  const leftRevision = decodeUint8At(left, leftOffset)
-  const rightRevision = decodeUint8At(right, rightOffset)
-  if (leftRevision !== rightRevision) return false
+export function sameSidAt(
+  left: NativePtr,
+  leftOffset: number,
+  right: NativePtr,
+  rightOffset: number,
+): boolean {
+  if (decodeUint8At(left, leftOffset) !== decodeUint8At(right, rightOffset)) return false
   const leftCount = decodeUint8At(left, leftOffset + 1)
   const rightCount = decodeUint8At(right, rightOffset + 1)
   if (leftCount !== rightCount || leftCount > abi.SID_MAX_SUB_AUTHORITIES) return false
-  for (let index = 0; index < 6; index++) {
-    if (decodeUint8At(left, leftOffset + 2 + index) !== decodeUint8At(right, rightOffset + 2 + index)) return false
+  for (let index = 0; index < 6; index += 1) {
+    if (decodeUint8At(left, leftOffset + 2 + index) !== decodeUint8At(right, rightOffset + 2 + index)) {
+      return false
+    }
   }
-  for (let index = 0; index < leftCount; index++) {
-    if (decodeUint32At(left, leftOffset + 8 + index * 4) !== decodeUint32At(right, rightOffset + 8 + index * 4)) return false
+  for (let index = 0; index < leftCount; index += 1) {
+    if (decodeUint32At(left, leftOffset + 8 + index * 4) !==
+      decodeUint32At(right, rightOffset + 8 + index * 4)) return false
   }
   return true
 }
 
-/**
- * Allocate a zeroed STARTUPINFOW.
- * @returns the allocated struct pointer.
- */
-export function allocStartupInfo(): NativePtr {
-  const value: unknown = koffi.alloc(STARTUPINFOW, 1)
-  return value as NativePtr
-}
-
-/**
- * Write the stdio-relevant fields into a zeroed STARTUPINFOW (others stay default-initialized).
- * @param startupInfo - the allocated STARTUPINFOW to encode into.
- * @param fields - the field subset to write.
- */
-export function encodeStartupInfo(startupInfo: NativePtr, fields: StartupInfoInput): void {
-  koffi.encode(startupInfo, STARTUPINFOW, fields)
-}
-
-/**
- * Allocate a zeroed PROCESS_INFORMATION.
- * @returns the allocated struct pointer.
- */
-export function allocProcessInfo(): NativePtr {
-  const value: unknown = koffi.alloc(PROCESS_INFORMATION, 1)
-  return value as NativePtr
-}
-
-/**
- * Decode a PROCESS_INFORMATION after CreateProcessAsUserW.
- * @param processInfo - the PROCESS_INFORMATION filled by the spawn call.
- * @returns the decoded handle/id fields.
- */
-export function decodeProcessInfo(processInfo: NativePtr): ProcessInfoOutput {
-  const value: unknown = koffi.decode(processInfo, PROCESS_INFORMATION)
-  return value as ProcessInfoOutput
-}
-
 let cached: Win32Bindings | undefined
 
 function bindings(): Win32Bindings {
   if (cached !== undefined) return cached
-  const kernel32 = koffi.load('kernel32.dll')
-  const advapi32 = koffi.load('advapi32.dll')
-
-  // Each binding shape is verified by verify/abi-probe.cpp against the real
-  // Windows headers and exercised end-to-end by tests/probe.spec.ts; the
-  // single cast keeps the per-binding noise out of this table.
-  const bind = (lib: ReturnType<typeof koffi.load>, name: string, result: Ptr | string, args: Array<Ptr | string>): unknown =>
-    lib.func('__stdcall', name, result, args)
-
-  cached = {
+  cached = extendWin32ProcessBindings(({ kernel32, advapi32, bind }) => ({
     openProcess: bind(kernel32, 'OpenProcess', PVOID, ['uint32', 'int', 'uint32']),
     openProcessToken: bind(advapi32, 'OpenProcessToken', 'int', [PVOID, 'uint32', PPVOID]),
-    closeHandle: bind(kernel32, 'CloseHandle', 'int', [PVOID]),
-    getLastError: bind(kernel32, 'GetLastError', 'uint32', []),
-    formatMessageW: bind(kernel32, 'FormatMessageW', 'uint32', ['uint32', PVOID, 'uint32', 'uint32', PVOID, 'uint32', PVOID]),
     localAlloc: bind(kernel32, 'LocalAlloc', PVOID, ['uint32', 'size_t']),
     localFree: bind(kernel32, 'LocalFree', PVOID, [PVOID]),
     convertStringSidToSidW: bind(advapi32, 'ConvertStringSidToSidW', 'int', ['str16', PPVOID]),
-    createWellKnownSid: bind(advapi32, 'CreateWellKnownSid', 'int', ['int', PVOID, PVOID, koffi.pointer('uint32')]),
+    createWellKnownSid: bind(advapi32, 'CreateWellKnownSid', 'int', [
+      'int', PVOID, PVOID, koffi.pointer('uint32'),
+    ]),
     isValidSid: bind(advapi32, 'IsValidSid', 'int', [PVOID]),
     getLengthSid: bind(advapi32, 'GetLengthSid', 'uint32', [PVOID]),
     copySid: bind(advapi32, 'CopySid', 'int', ['uint32', PVOID, PVOID]),
-    getTokenInformation: bind(advapi32, 'GetTokenInformation', 'int', [PVOID, 'int', PVOID, 'uint32', koffi.pointer('uint32')]),
+    getTokenInformation: bind(advapi32, 'GetTokenInformation', 'int', [
+      PVOID, 'int', PVOID, 'uint32', koffi.pointer('uint32'),
+    ]),
     setTokenInformation: bind(advapi32, 'SetTokenInformation', 'int', [PVOID, 'int', PVOID, 'uint32']),
-    createRestrictedToken: bind(advapi32, 'CreateRestrictedToken', 'int', [PVOID, 'uint32', 'uint32', PVOID, 'uint32', PVOID, 'uint32', PVOID, PPVOID]),
+    createRestrictedToken: bind(advapi32, 'CreateRestrictedToken', 'int', [
+      PVOID, 'uint32', 'uint32', PVOID, 'uint32', PVOID, 'uint32', PVOID, PPVOID,
+    ]),
     setEntriesInAclW: bind(advapi32, 'SetEntriesInAclW', 'uint32', ['uint32', PVOID, PVOID, PPVOID]),
-    setNamedSecurityInfoW: bind(advapi32, 'SetNamedSecurityInfoW', 'uint32', ['str16', 'int', 'uint32', PVOID, PVOID, PVOID, PVOID]),
-    getNamedSecurityInfoW: bind(advapi32, 'GetNamedSecurityInfoW', 'uint32', ['str16', 'int', 'uint32', PPVOID, PPVOID, PPVOID, PPVOID, PPVOID]),
-    getTempPathW: bind(kernel32, 'GetTempPathW', 'uint32', ['uint32', PVOID]),
-    // fileapi.h line ~64: HANDLE CreateFileW(LPCWSTR, DWORD, DWORD,
-    // LPSECURITY_ATTRIBUTES, DWORD, DWORD, HANDLE).
-    createFileW: bind(kernel32, 'CreateFileW', PVOID, ['str16', 'uint32', 'uint32', PVOID, 'uint32', 'uint32', PVOID]),
-    // fileapi.h lines ~177/~185: BOOL LockFileEx(HANDLE, DWORD, DWORD, DWORD,
-    // DWORD, LPOVERLAPPED); BOOL UnlockFileEx(HANDLE, DWORD, DWORD, DWORD,
-    // LPOVERLAPPED). lpOverlapped is NULL for synchronous locking.
-    lockFileEx: bind(kernel32, 'LockFileEx', 'int', [PVOID, 'uint32', 'uint32', 'uint32', 'uint32', PVOID]),
-    unlockFileEx: bind(kernel32, 'UnlockFileEx', 'int', [PVOID, 'uint32', 'uint32', 'uint32', PVOID]),
-    createPipe: bind(kernel32, 'CreatePipe', 'int', [PPVOID, PPVOID, PVOID, 'uint32']),
-    setHandleInformation: bind(kernel32, 'SetHandleInformation', 'int', [PVOID, 'uint32', 'uint32']),
-    createProcessAsUserW: bind(advapi32, 'CreateProcessAsUserW', 'int', [
-      PVOID, 'str16', 'str16', PVOID, PVOID, 'int', 'uint32', PVOID, 'str16',
-      koffi.pointer(STARTUPINFOW), koffi.pointer(PROCESS_INFORMATION),
+    setNamedSecurityInfoW: bind(advapi32, 'SetNamedSecurityInfoW', 'uint32', [
+      'str16', 'int', 'uint32', PVOID, PVOID, PVOID, PVOID,
+    ]),
+    getNamedSecurityInfoW: bind(advapi32, 'GetNamedSecurityInfoW', 'uint32', [
+      'str16', 'int', 'uint32', PPVOID, PPVOID, PPVOID, PPVOID, PPVOID,
     ]),
+    getTempPathW: bind(kernel32, 'GetTempPathW', 'uint32', ['uint32', PVOID]),
     setEnvironmentVariableW: bind(kernel32, 'SetEnvironmentVariableW', 'int', ['str16', 'str16']),
-    readFile: bind(kernel32, 'ReadFile', 'int', [PVOID, PVOID, 'uint32', koffi.pointer('uint32'), PVOID]),
-    peekNamedPipe: bind(kernel32, 'PeekNamedPipe', 'int', [PVOID, PVOID, 'uint32', koffi.pointer('uint32'), koffi.pointer('uint32'), koffi.pointer('uint32')]),
-    waitForSingleObject: bind(kernel32, 'WaitForSingleObject', 'uint32', [PVOID, 'uint32']),
-    getExitCodeProcess: bind(kernel32, 'GetExitCodeProcess', 'int', [PVOID, koffi.pointer('uint32')]),
-    resumeThread: bind(kernel32, 'ResumeThread', 'uint32', [PVOID]),
-    createJobObjectW: bind(kernel32, 'CreateJobObjectW', PVOID, [PVOID, 'str16']),
-    setInformationJobObject: bind(kernel32, 'SetInformationJobObject', 'int', [PVOID, 'int', PVOID, 'uint32']),
-    assignProcessToJobObject: bind(kernel32, 'AssignProcessToJobObject', 'int', [PVOID, PVOID]),
-    terminateProcess: bind(kernel32, 'TerminateProcess', 'int', [PVOID, 'uint32']),
     setConsoleCtrlHandler: bind(kernel32, 'SetConsoleCtrlHandler', 'int', [PVOID, 'int']),
-    getStdHandle: bind(kernel32, 'GetStdHandle', PVOID, ['int']),
-  } as unknown as Win32Bindings
+    createFileW: bind(kernel32, 'CreateFileW', PVOID, [
+      'str16', 'uint32', 'uint32', PVOID, 'uint32', 'uint32', PVOID,
+    ]),
+    lockFileEx: bind(kernel32, 'LockFileEx', 'int', [
+      PVOID, 'uint32', 'uint32', 'uint32', 'uint32', PVOID,
+    ]),
+    unlockFileEx: bind(kernel32, 'UnlockFileEx', 'int', [
+      PVOID, 'uint32', 'uint32', 'uint32', PVOID,
+    ]),
+  })) as unknown as Win32Bindings
   return cached
 }
 
 /**
- * Resolve the lazy Win32 bindings (throws the first binding failure, fail-closed).
- * @returns the cached binding table.
+ * Resolve the cached ACL/token binding table asynchronously.
+ * @returns generic process plus ACL/token bindings.
  */
 export function win32(): Promise<Win32Bindings> {
   return Promise.resolve(bindings())
 }
 
 /**
- * Resolve the lazy Win32 bindings SYNCHRONOUSLY — the sandbox seam's
- * server-side per-session grant materializes ACEs inside the synchronous
- * `confine()` call, which cannot await. Same cached table as {@link win32}
- * (the underlying koffi loads are synchronous; the async wrapper exists for
- * the runner's await-shaped call sites).
- * @returns the cached binding table.
+ * Resolve the cached ACL/token binding table synchronously.
+ * @returns generic process plus ACL/token bindings.
  */
 export function win32Sync(): Win32Bindings {
   return bindings()
 }
 
 /**
- * Turn a Win32 error code into readable text via FormatMessageW.
- * @param api - the binding table.
- * @param win32Code - the error code to format.
- * @returns the formatted message text, or '' when formatting fails.
- */
-export function errorText(api: Win32Bindings, win32Code: number): string {
-  const buffer = Buffer.alloc(1024)
-  const length = api.formatMessageW(
-    abi.FORMAT_MESSAGE_FROM_SYSTEM | abi.FORMAT_MESSAGE_IGNORE_INSERTS,
-    null, win32Code, 0, buffer, buffer.length / 2, null,
-  )
-  if (length === 0) return ''
-  return buffer.subarray(0, length * 2).toString('utf16le').trim()
-}
-
-/**
- * Read the process temp directory via GetTempPathW (fileapi.h line ~188).
- * Defensive against an overlong system temp path: GetTempPathW reports the
- * REQUIRED length (including NUL) without writing the buffer when it is too
- * small, so a reported length beyond the buffer's capacity means the buffer
- * was never filled and must not be decoded.
- * @param api - the binding table.
- * @returns the NUL-terminated temp path decoded as a string.
+ * Resolve the current Windows temporary directory.
+ * @param api - active ACL/token binding table.
+ * @returns UTF-16 path reported by GetTempPathW.
  */
 export function getTempPath(api: Win32Bindings): string {
   const buffer = Buffer.alloc((abi.MAX_PATH + 1) * 2)
   const length = api.getTempPathW(buffer.length / 2, buffer)
   if (length === 0) throwLastError(api, 'GetTempPathW')
   if (length > buffer.length / 2) {
-    throw new Win32Error('GetTempPathW', abi.ERROR_INSUFFICIENT_BUFFER, `required ${length} chars exceed the ${buffer.length / 2}-char buffer; nothing was written`)
+    throw new Win32Error(
+      'GetTempPathW',
+      ERROR_INSUFFICIENT_BUFFER,
+      `required ${length} chars exceed the ${buffer.length / 2}-char buffer; nothing was written`,
+    )
   }
   return buffer.subarray(0, length * 2).toString('utf16le')
 }
-
-/**
- * Throw a Win32Error for a BOOL-style API failure. MUST be called immediately
- * after the failed call so GetLastError is not clobbered by other Win32 calls.
- * @param api - the binding table.
- * @param name - the failed API's name for the error message.
- * @param detail - optional detail overriding the formatted system message.
- * @returns never — always throws.
- */
-export function throwLastError(api: Win32Bindings, name: string, detail?: string): never {
-  const win32Code = api.getLastError()
-  throw new Win32Error(name, win32Code, detail ?? errorText(api, win32Code))
-}
-
-/**
- * Throw a Win32Error for an HRESULT-style API return value (the value IS the error code).
- * @param api - the binding table.
- * @param name - the failed API's name for the error message.
- * @param win32Code - the API's returned error code.
- * @param detail - optional detail overriding the formatted system message.
- * @returns never — always throws.
- */
-export function throwWin32(api: Win32Bindings, name: string, win32Code: number, detail?: string): never {
-  throw new Win32Error(name, win32Code, detail ?? errorText(api, win32Code))
-}

packages/sandbox/sandbox-windows-acl/src/index.ts

@@ -42,9 +42,9 @@
 
 import { existsSync, statSync } from 'node:fs'
 import { resolve } from 'node:path'
+import { Win32Error } from '@deepseek-ai/dsh-win32-process'
 
 import { grantWrite, revokeWrite } from './acl.ts'
-import { Win32Error } from './errors.ts'
 import { allocPtrSlot, decodePtr, isNullPtr, throwLastError, win32 } from './ffi.ts'
 import type { NativePtr, Win32Bindings } from './ffi.ts'
 import { assertPrivateTempDisjoint } from './path-boundary.ts'
@@ -52,12 +52,9 @@ import { drainPipe, spawnSandboxed, spawnSandboxedInherited, waitForExit } from
 import { createRestrictedToken, findLogonSid, makeWellKnownSid, openCurrentProcessToken, setTokenDefaultDaclGrant } from './token.ts'
 import * as abi from './win32-abi.ts'
 
-export { quoteArg } from './spawn.ts'
 export { AclWriteGrant } from './grant.ts'
 export { assertTempRootOutsideWorkspace } from './path-boundary.ts'
 export { tempWriteSid, workspaceWriteSid } from './workspace-sid.ts'
-export { Win32Error } from './errors.ts'
-
 /** Construction options: the workspace/temp allowlists and their distinct SID identities. */
 export interface AclSandboxOptions {
   /** Directories the confined child may write into (must exist and be caller-owned). */

packages/sandbox/sandbox-windows-acl/src/spawn.ts

@@ -1,357 +1,60 @@
-/**
- * Restricted-process spawning: anonymous pipes for stdio, STARTUPINFOW with
- * STARTF_USESTDHANDLES, CreateProcessAsUserW under the restricted token, then
- * asynchronous pipe draining and exit waiting. Console isolation
- * (CREATE_NO_WINDOW / CREATE_NEW_CONSOLE) is intentionally absent: under this
- * restriction scheme hidden-console children die with STATUS_DLL_INIT_FAILED
- * (0xC0000142) — verified empirically, see win32-abi.ts. Stdio redirection is
- * pipe-based and unaffected; the child shares the host console.
- * @module @deepseek-ai/dsh-sandbox-windows-acl/spawn
- */
-
-import { allocPtrSlot, allocProcessInfo, allocStartupInfo, allocUint32, decodePtr, decodeProcessInfo, decodeUint32, encodeStartupInfo, isNullPtr, throwLastError, throwWin32 } from './ffi.ts'
-import type { NativePtr, Win32Bindings } from './ffi.ts'
-import * as abi from './win32-abi.ts'
-
-/**
- * Quote one argument per the CommandLineToArgvW parsing rules: backslashes
- * are doubled only before a quote character — including the closing quote
- * this function appends, so a trailing backslash run is doubled as well
- * (otherwise an odd run would escape the closing quote into a literal
- * character and corrupt the rest of the command line). Mirrors the CRT
- * ArgvQuote behavior Microsoft documents for command-line arguments.
- * @param argument - one argv entry to quote.
- * @returns the quoted entry (bare when quoting is unnecessary).
- */
-export function quoteArg(argument: string): string {
-  if (argument === '') return '""'
-  if (!/[\s"]/u.test(argument)) return argument
-  let quoted = '"'
-  for (let index = 0; index < argument.length; index++) {
-    let backslashes = 0
-    while (index < argument.length && argument.charAt(index) === '\\') {
-      backslashes++
-      index++
-    }
-    if (index === argument.length) {
-      // Trailing backslash run: doubled so it cannot escape the closing quote.
-      quoted += '\\'.repeat(backslashes * 2)
-    } else if (argument.charAt(index) === '"') {
-      quoted += '\\'.repeat(backslashes * 2 + 1) + '"'
-    } else {
-      quoted += '\\'.repeat(backslashes) + argument.charAt(index)
-    }
-  }
-  return quoted + '"'
-}
-
-/**
- * Build the single command line CreateProcess parses from program + argv.
- * @param program - the executable (argv[0]).
- * @param args - the remaining argv entries.
- * @returns the joined, quoted command line.
- */
-export function buildCommandLine(program: string, args: readonly string[]): string {
-  return [program, ...args].map(quoteArg).join(' ')
-}
-
-interface PipePair {
-  read: NativePtr
-  write: NativePtr
-}
-
-function createPipe(api: Win32Bindings): PipePair {
-  const readSlot = allocPtrSlot()
-  const writeSlot = allocPtrSlot()
-  if (api.createPipe(readSlot, writeSlot, null, 0) === 0) throwLastError(api, 'CreatePipe')
-  const read = decodePtr(readSlot)
-  const write = decodePtr(writeSlot)
-  if (read === null || write === null) throwLastError(api, 'CreatePipe', 'null pipe handle')
-  return { read, write }
-}
-
-function setInheritable(api: Win32Bindings, handle: NativePtr, label: string): void {
-  if (api.setHandleInformation(handle, abi.HANDLE_FLAG_INHERIT, abi.HANDLE_FLAG_INHERIT) === 0) {
-    throwLastError(api, 'SetHandleInformation', label)
-  }
-}
-
-/** A confined child spawned with piped stdio: process handle plus the pipe read ends to drain. */
-export interface SpawnedNative {
-  pid: number
-  process: NativePtr
-  stdoutRead: NativePtr
-  stderrRead: NativePtr
-}
-
-/**
- * Create a process under the restricted token with piped stdio. The child's
- * stdin is closed immediately (EOF), matching the POC; stdout/stderr read ends
- * are returned for draining. The child inherits the caller's environment block
- * (lpEnvironment NULL); the caller rewrites entries through
- * SetEnvironmentVariableW before spawning (the runner's per-session temp
- * contract) — passing an explicit block through koffi trips
- * ERROR_INVALID_PARAMETER in CreateProcessAsUserW (verified empirically).
- * @param api - the binding table.
- * @param token - the restricted token the child runs under.
+/** Restricted-token adapters over the shared Win32 process owner. */
+
+import {
+  spawnInheritedJobProcess,
+  spawnPipedProcess,
+  waitForProcessExit,
+} from '@deepseek-ai/dsh-win32-process'
+import type {
+  NativePtr,
+  SpawnedJobProcess,
+  SpawnedPipedProcess,
+} from '@deepseek-ai/dsh-win32-process'
+import type { Win32Bindings } from './ffi.ts'
+
+export { drainPipe } from '@deepseek-ai/dsh-win32-process'
+
+/** Restricted-token child with piped stdio resources. */
+export interface SpawnedNative extends SpawnedPipedProcess {}
+/** Restricted-token child assigned to a kill-on-close Job. */
+export interface SpawnedInherited extends SpawnedJobProcess {}
+
+/**
+ * Spawn a restricted-token child with piped stdout/stderr.
+ * @param api - ACL/token binding table.
+ * @param token - restricted primary token.
  * @param options - command, args, and working directory.
- * @returns the spawned child's handles.
+ * @returns process and caller-owned pipe handles.
  */
 export function spawnSandboxed(
   api: Win32Bindings,
   token: NativePtr,
   options: { command: string; args: readonly string[]; cwd: string },
 ): SpawnedNative {
-  const stdIn = createPipe(api)
-  const stdOut = createPipe(api)
-  const stdErr = createPipe(api)
-  // Child side of each pipe must be inheritable (POC lines 262-268).
-  setInheritable(api, stdIn.read, 'stdin read end')
-  setInheritable(api, stdOut.write, 'stdout write end')
-  setInheritable(api, stdErr.write, 'stderr write end')
-
-  const startupInfo = allocStartupInfo()
-  encodeStartupInfo(startupInfo, {
-    cb: abi.STARTUPINFOW_SIZE,
-    dwFlags: abi.STARTF_USESTDHANDLES,
-    hStdInput: stdIn.read,
-    hStdOutput: stdOut.write,
-    hStdError: stdErr.write,
-  })
-
-  const processInfo = allocProcessInfo()
-  const commandLine = buildCommandLine(options.command, options.args)
-  const created = api.createProcessAsUserW(
-    token, null, commandLine,
-    null, null,
-    1, // bInheritHandles: required for redirection
-    0, // no creation flags: suspended/no-window variants are unusable under the restriction
-    null, options.cwd,
-    startupInfo, processInfo,
-  )
-  // Capture the failure before CloseHandle calls clobber GetLastError, then
-  // close every pipe handle created so far — the six-close contract this test
-  // surface pins (tests/failure-paths.spec.ts).
-  if (created === 0) {
-    const win32Code = api.getLastError()
-    api.closeHandle(stdIn.read)
-    api.closeHandle(stdIn.write)
-    api.closeHandle(stdOut.read)
-    api.closeHandle(stdOut.write)
-    api.closeHandle(stdErr.read)
-    api.closeHandle(stdErr.write)
-    throwWin32(api, 'CreateProcessAsUserW', win32Code, `command: ${options.command}, cwd: ${options.cwd}`)
-  }
-
-  const info = decodeProcessInfo(processInfo)
-  const processHandle = info.hProcess
-  const threadHandle = info.hThread
-  if (processHandle === null || threadHandle === null) {
-    throw new Error(`CreateProcessAsUserW succeeded but returned null process/thread handles (pid ${info.dwProcessId})`)
-  }
-
-  // Host-side cleanup: child handles are now duplicated in the child; the
-  // host closes its copies so ReadFile sees EOF when the child exits.
-  api.closeHandle(stdIn.read)
-  api.closeHandle(stdOut.write)
-  api.closeHandle(stdErr.write)
-  api.closeHandle(stdIn.write)
-  api.closeHandle(threadHandle)
-
-  return {
-    pid: info.dwProcessId,
-    process: processHandle,
-    stdoutRead: stdOut.read,
-    stderrRead: stdErr.read,
-  }
+  return spawnPipedProcess(api, { ...options, token })
 }
 
 /**
- * Drain one pipe read end to a Buffer via non-blocking PeekNamedPipe polling.
- * @param api - the binding table.
- * @param handle - the pipe read end to drain (closed when done).
- * @returns the complete pipe contents.
- */
-export async function drainPipe(api: Win32Bindings, handle: NativePtr): Promise<Buffer> {
-  const chunks: Buffer[] = []
-  for (;;) {
-    const bytesReadSlot = allocUint32()
-    const totalAvailSlot = allocUint32()
-    const leftThisMessageSlot = allocUint32()
-    const peeked = api.peekNamedPipe(handle, null, 0, bytesReadSlot, totalAvailSlot, leftThisMessageSlot)
-    if (peeked === 0) {
-      const win32Code = api.getLastError()
-      if (win32Code === abi.ERROR_BROKEN_PIPE || win32Code === abi.ERROR_NO_DATA) break // child closed its end: clean EOF
-      throwLastError(api, 'PeekNamedPipe', `drain failure after ${chunks.length} chunk(s)`)
-    }
-    const available = decodeUint32(totalAvailSlot)
-    if (available > 0) {
-      const chunk = Buffer.alloc(available)
-      const readSlot = allocUint32()
-      if (api.readFile(handle, chunk, chunk.length, readSlot, null) === 0) {
-        throwLastError(api, 'ReadFile', `drain failure after ${chunks.length} chunk(s)`)
-      }
-      chunks.push(chunk.subarray(0, decodeUint32(readSlot)))
-    }
-    // Small backoff instead of setImmediate: a bare next-tick would busy-poll
-    // the pipe at full event-loop speed while the child produces no output.
-    await new Promise<void>(resolve => setTimeout(resolve, 1))
-  }
-  api.closeHandle(handle)
-  return Buffer.concat(chunks)
-}
-
-/**
- * Wait for process exit and return its exit code. Call only after both drains
- * have resolved — the drains finish when the child closed its pipe ends, i.e.
- * the child has already exited, so this wait returns immediately. Calling it
- * earlier would block the event loop and starve the drains (the pipe-buffer
- * deadlock the POC comments warn about).
- * @param api - the binding table.
- * @param process - the child process handle (closed when done).
- * @returns the child's exit code.
- */
-export function waitForExit(api: Win32Bindings, process: NativePtr): number {
-  const waitResult = api.waitForSingleObject(process, abi.INFINITE)
-  if (waitResult === 0xFFFFFFFF) throwLastError(api, 'WaitForSingleObject')
-  const exitCodeSlot = allocUint32()
-  if (api.getExitCodeProcess(process, exitCodeSlot) === 0) throwLastError(api, 'GetExitCodeProcess')
-  api.closeHandle(process)
-  return decodeUint32(exitCodeSlot)
-}
-
-/**
- * Create a kill-on-close job object (JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE at
- * LimitFlags offset 16 of JOBOBJECT_EXTENDED_LIMIT_INFORMATION, layout
- * verified by abi-probe.cpp). When the caller dies with the job handle open,
- * Windows terminates every process in the job — the orphan-child backstop.
- * The caller keeps the returned handle open for the child's lifetime.
- */
-function createKillOnCloseJob(api: Win32Bindings): NativePtr {
-  const job = api.createJobObjectW(null, null)
-  if (isNullPtr(job)) throwLastError(api, 'CreateJobObjectW')
-  const information = Buffer.alloc(abi.JOBOBJECT_EXTENDED_LIMIT_SIZE)
-  information.writeUInt32LE(abi.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE, abi.JOBOBJECT_EXTENDED_LIMIT_FLAGS_OFFSET)
-  if (api.setInformationJobObject(job, abi.JobObjectExtendedLimitInformation, information, information.length) === 0) {
-    const win32Code = api.getLastError()
-    api.closeHandle(job)
-    throwWin32(api, 'SetInformationJobObject', win32Code)
-  }
-  return job
-}
-
-/** A confined child spawned with inherited stdio: process handle plus its kill-on-close job. */
-export interface SpawnedInherited {
-  pid: number
-  process: NativePtr
-  /** Kill-on-close job the child was placed in; caller closes it after the child exits. */
-  job: NativePtr
-}
-
-/**
- * Create a process under the restricted token whose stdio passes straight
- * through to the caller's pipes. This is the runner shape: the harness spawns
- * the runner with piped stdio, and the runner's confined child writes to
- * those same pipes.
- *
- * Node clears the inheritability of its stdio handles at startup
- * (uv_disable_stdio_inheritance), so raw spawns must re-enable the inherit
- * bit around the call (libuv instead duplicates the handles; re-enabling is
- * equivalent here and cheaper) and pass them explicitly via
- * STARTF_USESTDHANDLES — otherwise the child receives INVALID std handles
- * ("The handle is invalid", verified the hard way). The child starts
- * suspended so it can be assigned to a kill-on-close job before it runs.
- * @param api - the binding table.
- * @param token - the restricted token the child runs under.
+ * Spawn a restricted-token child in a kill-on-close Job with inherited stdio.
+ * @param api - ACL/token binding table.
+ * @param token - restricted primary token.
  * @param options - command, args, and working directory.
- * @returns the spawned child's handles and job.
+ * @returns process and Job handles after assignment and resume.
  */
 export function spawnSandboxedInherited(
   api: Win32Bindings,
   token: NativePtr,
   options: { command: string; args: readonly string[]; cwd: string },
 ): SpawnedInherited {
-  const job = createKillOnCloseJob(api)
-  const stdIn = api.getStdHandle(abi.STD_INPUT_HANDLE)
-  const stdOut = api.getStdHandle(abi.STD_OUTPUT_HANDLE)
-  const stdErr = api.getStdHandle(abi.STD_ERROR_HANDLE)
-  if (isNullPtr(stdIn) || isNullPtr(stdOut) || isNullPtr(stdErr)) {
-    api.closeHandle(job)
-    throwLastError(api, 'GetStdHandle', 'null standard handle')
-  }
-
-  const makeInheritable = (handle: NativePtr, label: string): void => {
-    if (api.setHandleInformation(handle, abi.HANDLE_FLAG_INHERIT, abi.HANDLE_FLAG_INHERIT) === 0) {
-      throwLastError(api, 'SetHandleInformation', `${label} (enable inherit)`)
-    }
-  }
-  const restoreInherit = (handle: NativePtr): void => {
-    // Best-effort hygiene: the runner spawns nothing else; failures here must
-    // not mask the child outcome, so the result is deliberately unchecked.
-    api.setHandleInformation(handle, abi.HANDLE_FLAG_INHERIT, 0)
-  }
-  makeInheritable(stdIn, 'stdin')
-  makeInheritable(stdOut, 'stdout')
-  makeInheritable(stdErr, 'stderr')
-
-  const startupInfo = allocStartupInfo()
-  encodeStartupInfo(startupInfo, {
-    cb: abi.STARTUPINFOW_SIZE,
-    dwFlags: abi.STARTF_USESTDHANDLES,
-    hStdInput: stdIn,
-    hStdOutput: stdOut,
-    hStdError: stdErr,
-  })
-
-  const processInfo = allocProcessInfo()
-  const commandLine = buildCommandLine(options.command, options.args)
-  const created = api.createProcessAsUserW(
-    token, null, commandLine,
-    null, null,
-    1, // bInheritHandles: the re-enabled std handles must be inheritable
-    abi.CREATE_SUSPENDED, // suspended so job assignment precedes any execution
-    null, options.cwd,
-    startupInfo, processInfo,
-  )
-  restoreInherit(stdIn)
-  restoreInherit(stdOut)
-  restoreInherit(stdErr)
-  if (created === 0) {
-    const win32Code = api.getLastError()
-    api.closeHandle(job)
-    throwWin32(api, 'CreateProcessAsUserW', win32Code, `command: ${options.command}, cwd: ${options.cwd}`)
-  }
-
-  const info = decodeProcessInfo(processInfo)
-  const processHandle = info.hProcess
-  const threadHandle = info.hThread
-  if (processHandle === null || threadHandle === null) {
-    api.closeHandle(job)
-    throw new Error(`CreateProcessAsUserW succeeded but returned null process/thread handles (pid ${info.dwProcessId})`)
-  }
-
-  if (api.assignProcessToJobObject(job, processHandle) === 0) {
-    // The child was created suspended and is NOT in the kill-on-close job:
-    // closing handles would leave it suspended forever. Terminate it first,
-    // then drop the handles and throw.
-    const win32Code = api.getLastError()
-    api.terminateProcess(processHandle, 1)
-    api.closeHandle(threadHandle)
-    api.closeHandle(processHandle)
-    api.closeHandle(job)
-    throwWin32(api, 'AssignProcessToJobObject', win32Code, `pid ${info.dwProcessId}`)
-  }
-  if (api.resumeThread(threadHandle) === 0xFFFFFFFF) {
-    // Closing the job triggers kill-on-close, so the suspended child dies
-    // instead of hanging until this process exits; the process/thread handles
-    // must go too.
-    const win32Code = api.getLastError()
-    api.closeHandle(threadHandle)
-    api.closeHandle(processHandle)
-    api.closeHandle(job)
-    throwWin32(api, 'ResumeThread', win32Code, `pid ${info.dwProcessId}`)
-  }
-  api.closeHandle(threadHandle)
+  return spawnInheritedJobProcess(api, { ...options, token })
+}
 
-  return { pid: info.dwProcessId, process: processHandle, job }
+/**
+ * Wait for a restricted child and close its process handle.
+ * @param api - ACL/token binding table.
+ * @param process - caller-owned process handle.
+ * @returns direct process exit code.
+ */
+export function waitForExit(api: Win32Bindings, process: NativePtr): number {
+  return waitForProcessExit(api, process)
 }

packages/sandbox/sandbox-windows-acl/src/token.ts

@@ -180,8 +180,9 @@ export interface RestrictingSidSet {
  * `AU:(AD)` + `AU:(OI)(CI)(IO)(M)` ACEs) is closed in both — documented in
  * README. INTERACTIVE/LOCAL are absent from BOTH lists too — the host's
  * Public tree grants write to INTERACTIVE, so removing it closes that
- * escape. S-1-2-1 (console logon) is intentionally absent: see win32-abi.ts
- * for the verified failure modes. FAILS CLOSED: any failure throws — never
+ * escape. S-1-2-1 (console logon) is intentionally absent: the package
+ * README's "Console isolation is unavailable" entry records the verified
+ * failure modes. FAILS CLOSED: any failure throws — never
  * spawn unrestricted.
  * @param api - the binding table.
  * @param currentToken - the process token to restrict.

packages/sandbox/sandbox-windows-acl/src/win32-abi.ts

@@ -1,258 +1,98 @@
-/**
- * Windows ABI constants for the ACL-sandbox backend.
- *
- * Every value was verified against the actual MinGW Windows headers on this
- * machine (C:\Strawberry\c\x86_64-w64-mingw32\include\) and cross-checked at
- * runtime by verify/abi-probe.cpp (same numbers; static_asserts passed).
- * Regenerate the probe with:
- *   g++ -std=c++20 -municode -O2 -o abi-probe.exe abi-probe.cpp -ladvapi32 && .\abi-probe.exe
- *
- * The port intentionally excludes two pieces of the original POC
- * (github.com/huoyaoyuan/windows-acl-restrict-poc @ 10e4dfb), both verified
- * empirically on Windows 11 build 26200:
- *  - S-1-2-1 (console logon SID) in the restricting list: the POC created it
- *    via CreateWellKnownSid(WinLocalLogonSid) which fails here with
- *    ERROR_INVALID_PARAMETER (87), leaving a garbage SID that makes
- *    CreateRestrictedToken fail with ERROR_INVALID_SID (1337); using the
- *    correct WinConsoleLogonSid does produce a valid S-1-2-1, but the child
- *    then still dies with STATUS_DLL_INIT_FAILED (0xC0000142) whenever
- *    CREATE_NO_WINDOW / CREATE_NEW_CONSOLE is used.
- *  - Console isolation: under this restriction scheme a hidden console is not
- *    attainable, so children share the host console (stdio redirection is
- *    pipe-based and unaffected).
- * @module @deepseek-ai/dsh-sandbox-windows-acl/win32-abi
- */
-
-// ---- winnt.h ---------------------------------------------------------------
+/** ACL/token-specific Win32 constants. */
 
-// TOKEN_* access rights (winnt.h lines ~3928)
-/** TOKEN_ASSIGN_PRIMARY: required to create a process with the token (CreateProcessAsUser). */
+/** OpenProcess access required to query the current process token. */
+export const PROCESS_QUERY_INFORMATION = 0x0400
+/** Token right required by CreateProcessAsUserW. */
 export const TOKEN_ASSIGN_PRIMARY = 0x0001
-/** TOKEN_DUPLICATE: required to duplicate a token (DuplicateTokenEx). */
+/** Token right required by DuplicateTokenEx. */
 export const TOKEN_DUPLICATE = 0x0002
-/** TOKEN_QUERY: required to read token information (GetTokenInformation). */
+/** Token right required to read token information. */
 export const TOKEN_QUERY = 0x0008
-/** TOKEN_ADJUST_DEFAULT: required to change a token's default DACL. */
+/** Token right required to replace the token default DACL. */
 export const TOKEN_ADJUST_DEFAULT = 0x0080
-
-// SID_AND_ATTRIBUTES.Attributes flags (winnt.h lines ~3446)
-/**
- * SE_GROUP_LOGON_ID: marks a token group SID as the logon SID (compared with
- * `>>> 0` — the flag's high bit makes it negative as a signed 32-bit number).
- */
+/** Group attribute identifying the token logon SID. */
 export const SE_GROUP_LOGON_ID = 0xC0000000
-
-// Generic file access (winnt.h lines ~5893-5913):
-// FILE_GENERIC_WRITE = STANDARD_RIGHTS_WRITE | FILE_WRITE_DATA | FILE_WRITE_ATTRIBUTES
-//                      | FILE_WRITE_EA | FILE_APPEND_DATA | SYNCHRONIZE
-/** STANDARD_RIGHTS_WRITE (== READ_CONTROL): the standard-rights component of generic write access. */
-export const STANDARD_RIGHTS_WRITE = 0x00020000 // == READ_CONTROL
-/** FILE_GENERIC_WRITE: every file-write permission bit plus SYNCHRONIZE. */
+/** Standard-rights portion excluded from the write capability grant. */
+export const STANDARD_RIGHTS_WRITE = 0x00020000
+/** Generic file write access bits. */
 export const FILE_GENERIC_WRITE = 0x00120116
-/** DELETE: remove or rename the object (winnt.h line ~3009). */
+/** Delete or rename an object. */
 export const DELETE = 0x00010000
-/** FILE_DELETE_CHILD: remove or rename a directory's children (winnt.h line ~5907). */
+/** Delete or rename a directory child. */
 export const FILE_DELETE_CHILD = 0x0040
-// The POC granted FILE_GENERIC_WRITE minus READ_CONTROL, which displays as
-// "Write" in Explorer/icacls (windows-acl-restrict-poc.cpp line 16). The
-// sandbox grant adds DELETE and FILE_DELETE_CHILD so confined
-// delete/rename/git operations inside the granted trees pass the token's
-// access check too; Write+DELETE displays as "Modify" in icacls.
-// WRITE_DAC/WRITE_OWNER stay OUT deliberately — granting them would let the
-// child take ownership or rewrite DACLs and escape the allowlist (the
-// security boundary).
-/**
- * GRANT_MASK: FILE_GENERIC_WRITE minus READ_CONTROL plus DELETE and
- * FILE_DELETE_CHILD — the write+delete access mask the capability-SID ACEs grant
- * (displays as "Modify" in Explorer/icacls). WRITE_DAC/WRITE_OWNER are
- * deliberately excluded: they would let the confined child take ownership or
- * rewrite DACLs.
- */
-export const GRANT_MASK = (FILE_GENERIC_WRITE | DELETE | FILE_DELETE_CHILD) & ~STANDARD_RIGHTS_WRITE // 0x00110156
-
 /**
- * FILE_ALL_ACCESS (winnt.h line ~2789: STANDARD_RIGHTS_REQUIRED | SYNCHRONIZE
- * | 0x1FF): full file-object access. The mask of the ACE merged into the
- * restricted token's DEFAULT DACL — the token holder must keep full access to
- * every NEW object it creates (pipes included), and the ACE must name a
- * restricting SID so the write pass-2 check passes at creation.
+ * Capability-SID access mask granting write, delete, and child deletion.
+ * WRITE_DAC and WRITE_OWNER stay excluded so a confined child cannot rewrite
+ * DACLs or take ownership to escape the allowlist.
  */
+export const GRANT_MASK = (FILE_GENERIC_WRITE | DELETE | FILE_DELETE_CHILD) & ~STANDARD_RIGHTS_WRITE
+/** Full access used in the restricted token default DACL. */
 export const FILE_ALL_ACCESS = 0x1F01FF
-
-// CreateRestrictedToken flags (winnt.h lines ~4284)
-/** DISABLE_MAX_PRIVILEGE: strip the token's maximum-privilege elevation so the confined child cannot escalate. */
+/** CreateRestrictedToken flag that disables maximum privileges. */
 export const DISABLE_MAX_PRIVILEGE = 0x1
-/** LUA_TOKEN: produce a limited-user (filtered admin) token. */
+/** CreateRestrictedToken limited-user flag. */
 export const LUA_TOKEN = 0x4
-/** WRITE_RESTRICTED: intersect write access with the restricting SIDs' ACL grants — the sandbox's core mechanism. */
+/** Restrict write access to the listed restricting SIDs. */
 export const WRITE_RESTRICTED = 0x8
-
-// WELL_KNOWN_SID_TYPE (winnt.h lines ~3369-3407)
-/** WinWorldSid: S-1-1-0 (Everyone) — the only well-known SID the restricted tokens use (keep-alive group; see token.ts). */
+/** WELL_KNOWN_SID_TYPE value for Everyone. */
 export const WinWorldSid = 1
-
-// TOKEN_INFORMATION_CLASS (winnt.h line ~3963: TokenUser=1, TokenGroups=2)
-/** TokenGroups: GetTokenInformation class returning the token's group SIDs. */
+/** TOKEN_INFORMATION_CLASS value for token groups. */
 export const TokenGroups = 2
-/** TokenDefaultDacl: the token's default DACL — the DACL every NEW object created without an explicit SD takes. */
+/** TOKEN_INFORMATION_CLASS value for the token default DACL. */
 export const TokenDefaultDacl = 6
-
-// SECURITY_INFORMATION (winnt.h line ~4293)
-/** DACL_SECURITY_INFORMATION: read/write only the DACL of a security descriptor. */
+/** SECURITY_INFORMATION flag selecting the DACL. */
 export const DACL_SECURITY_INFORMATION = 0x00000004
-
-// PROCESS access rights (winnt.h lines ~4364)
-/** PROCESS_QUERY_INFORMATION: read exit status and times of a process handle. */
-export const PROCESS_QUERY_INFORMATION = 0x0400
-
-// ---- accctrl.h -------------------------------------------------------------
-
-// SE_OBJECT_TYPE (accctrl.h line ~22: SE_UNKNOWN_OBJECT_TYPE=0, SE_FILE_OBJECT=1)
-/** SE_FILE_OBJECT: the trustee path names a filesystem object. */
+/** SE_OBJECT_TYPE value for filesystem objects. */
 export const SE_FILE_OBJECT = 1
-
-// TRUSTEE_FORM / TRUSTEE_TYPE (accctrl.h lines ~38-55): both enums start at 0
-/** TRUSTEE_IS_UNKNOWN: TRUSTEE_TYPE unknown (TrusteeForm carries the shape). */
+/** TRUSTEE_TYPE value used when trustee classification is unknown. */
 export const TRUSTEE_IS_UNKNOWN = 0
-/** TRUSTEE_IS_SID: TRUSTEE_FORM — Trustee.ptstrName is a SID pointer. */
+/** TRUSTEE_FORM value indicating a SID pointer. */
 export const TRUSTEE_IS_SID = 0
-/** NO_MULTIPLE_TRUSTEE: Trustee.pMultipleTrustee is null. */
+/** Trustee record has no chained trustee. */
 export const NO_MULTIPLE_TRUSTEE = 0
-
-// ACCESS_MODE (accctrl.h line ~127: NOT_USED_ACCESS=0, GRANT_ACCESS=1, REVOKE_ACCESS=4)
-/** GRANT_ACCESS: SetEntriesInAclW adds the entry as an allow ACE. */
+/** EXPLICIT_ACCESS mode that grants access. */
 export const GRANT_ACCESS = 1
-/** REVOKE_ACCESS: SetEntriesInAclW removes the matching allow ACE. */
+/** EXPLICIT_ACCESS mode that revokes access. */
 export const REVOKE_ACCESS = 4
-
-// grfInheritance (accctrl.h lines ~137-142)
-/**
- * SUB_CONTAINERS_AND_OBJECTS_INHERIT: the ACE applies to the directory, its
- * subdirectories, and files (OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE).
- */
-export const SUB_CONTAINERS_AND_OBJECTS_INHERIT = 0x3 // == OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE
-
-// ---- winbase.h -------------------------------------------------------------
-
-/**
- * STARTF_USESTDHANDLES: STARTUPINFOW dwFlags — the child uses the hStd*
- * handles, required because Node clears stdio inheritability at startup.
- */
-export const STARTF_USESTDHANDLES = 0x00000100
-/** HANDLE_FLAG_INHERIT: SetHandleInformation flag re-enabling handle inheritance for the spawned child's stdio handles. */
-export const HANDLE_FLAG_INHERIT = 0x1
-/** INFINITE: never-timeout wait value. */
-export const INFINITE = 0xFFFFFFFF
-/** MAX_PATH: legacy path length bound. */
+/** ACE inheritance flags for child containers and objects. */
+export const SUB_CONTAINERS_AND_OBJECTS_INHERIT = 0x3
+/** Legacy Win32 maximum path character count used by GetTempPathW. */
 export const MAX_PATH = 260
-// winbase.h line ~410: the confined child starts suspended so the runner can
-// assign it to the kill-on-close job before any of its code runs.
-/** CREATE_SUSPENDED: create the child with its primary thread suspended until ResumeThread. */
-export const CREATE_SUSPENDED = 0x4
-// winbase.h lines ~497-499: GetStdHandle selectors.
-/** STD_INPUT_HANDLE: GetStdHandle selector for the standard input. */
-export const STD_INPUT_HANDLE = -10
-/** STD_OUTPUT_HANDLE: GetStdHandle selector for the standard output. */
-export const STD_OUTPUT_HANDLE = -11
-/** STD_ERROR_HANDLE: GetStdHandle selector for the standard error. */
-export const STD_ERROR_HANDLE = -12
-
-// FormatMessageW flags (winbase.h lines ~1446-1469)
-/** FORMAT_MESSAGE_FROM_SYSTEM: format the message from the system message table. */
-export const FORMAT_MESSAGE_FROM_SYSTEM = 0x00001000
-/** FORMAT_MESSAGE_IGNORE_INSERTS: skip insert-sequence substitution. */
-export const FORMAT_MESSAGE_IGNORE_INSERTS = 0x00000200
-
-// ---- error codes -----------------------------------------------------------
-
-/** ERROR_SUCCESS: the operation succeeded. */
+/** Successful Win32 status code. */
 export const ERROR_SUCCESS = 0
-/** ERROR_INSUFFICIENT_BUFFER: a size-probe call succeeded but needs a larger buffer. */
-export const ERROR_INSUFFICIENT_BUFFER = 122
-/** ERROR_BROKEN_PIPE: the pipe's other end has closed. */
-export const ERROR_BROKEN_PIPE = 109
-/** ERROR_NO_DATA: the pipe is being closed. */
-export const ERROR_NO_DATA = 232
-/** ERROR_LOCK_VIOLATION: a byte-range lock conflicts with an existing lock (winerror.h line ~78). */
+/** Win32 error reported when an immediate byte-range lock cannot be obtained. */
 export const ERROR_LOCK_VIOLATION = 33
-
-// ---- lock files (fileapi.h / minwinbase.h / winnt.h) -----------------------
-
-// CreateFileW dwDesiredAccess for the ACL lock files: plain read+write is
-// enough to take byte-range locks.
-/** GENERIC_READ: generic read access (winnt.h line ~3028). */
+/** Generic read access bit. */
 export const GENERIC_READ = 0x80000000
-/** GENERIC_WRITE: generic write access (winnt.h line ~3029). */
+/** Generic write access bit. */
 export const GENERIC_WRITE = 0x40000000
-// CreateFileW dwShareMode: the lock file is shared for read/write but NOT
-// for delete — if a locked file could be deleted and recreated underneath the
-// lock holder, two processes could hold "the same" lock on different files.
-/** FILE_SHARE_READ: other opens may read (winnt.h line ~5949). */
+/** CreateFile share-read flag. */
 export const FILE_SHARE_READ = 0x00000001
-/** FILE_SHARE_WRITE: other opens may write (winnt.h line ~5950). */
+/** CreateFile share-write flag. */
 export const FILE_SHARE_WRITE = 0x00000002
-/** FILE_SHARE_DELETE: other opens may delete (winnt.h line ~5951) — deliberately NOT used for lock files. */
+/** CreateFile share-delete flag. */
 export const FILE_SHARE_DELETE = 0x00000004
-/** OPEN_ALWAYS: create the lock file if absent, open it otherwise (fileapi.h line ~21). */
+/** CreateFile disposition that opens or creates the file. */
 export const OPEN_ALWAYS = 4
-// LockFileEx dwFlags (minwinbase.h lines ~180-181, included by winbase.h).
-/** LOCKFILE_EXCLUSIVE_LOCK: request an exclusive byte-range lock. */
+/** LockFileEx exclusive-lock flag. */
 export const LOCKFILE_EXCLUSIVE_LOCK = 0x2
-/** LOCKFILE_FAIL_IMMEDIATELY: fail with ERROR_LOCK_VIOLATION instead of waiting. */
+/** LockFileEx immediate-failure flag. */
 export const LOCKFILE_FAIL_IMMEDIATELY = 0x1
-
-// ACE_HEADER.AceType (winnt.h lines ~3449-3463)
-/** ACCESS_ALLOWED_ACE_TYPE: an access-allowed ACE granting the mask to the trustee. */
+/** ACE type for an allowed-access entry. */
 export const ACCESS_ALLOWED_ACE_TYPE = 0
-
-// SID structure (winnt.h line ~280 SID_IDENTIFIER_AUTHORITY; line ~286
-// #define SID_MAX_SUB_AUTHORITIES 15).
-/** SID_MAX_SUB_AUTHORITIES: the most subauthorities a SID may carry. */
+/** Maximum SID sub-authority count. */
 export const SID_MAX_SUB_AUTHORITIES = 15
-
-// ACE_HEADER.AceFlags (winnt.h lines ~3477-3524): inherited ACEs shown when
-// reading a DACL are marked with this bit and are not part of the explicit
-// DACL edits this module makes.
-/** INHERITED_ACE: the ACE was inherited from the parent object, not stored explicitly. */
+/** ACE flag marking inherited entries. */
 export const INHERITED_ACE = 0x10
-
-// ---- job object (winnt.h lines ~4859-4866, ~5138, ~5190-5199) --------------
-
-// JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE: the child dies when the runner's last
-// job handle closes — the orphan-child backstop for the runner design.
-/** JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE: the child dies when the runner's last job handle closes — the orphan-child backstop. */
-export const JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000
-// JOBOBJECTINFOCLASS: JobObjectBasicAccountingInformation=1, ..., ExtendedLimit=9.
-/** JobObjectExtendedLimitInformation: JOBOBJECTINFOCLASS for the extended limit structure. */
-export const JobObjectExtendedLimitInformation = 9
-// sizeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION), verified by abi-probe.
-/** sizeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION), verified by abi-probe. */
-export const JOBOBJECT_EXTENDED_LIMIT_SIZE = 144
-// LimitFlags offset inside JOBOBJECT_EXTENDED_LIMIT_INFORMATION
-// (BasicLimitInformation@0 + PerProcessUserTimeLimit@0 + PerJobUserTimeLimit@8),
-// verified by abi-probe.
-/**
- * LimitFlags offset inside JOBOBJECT_EXTENDED_LIMIT_INFORMATION
- * (BasicLimitInformation@0 + PerProcessUserTimeLimit@0 +
- * PerJobUserTimeLimit@8), verified by abi-probe.
- */
-export const JOBOBJECT_EXTENDED_LIMIT_FLAGS_OFFSET = 16
-
-// ---- ABI layout, verified by verify/abi-probe.cpp (x64) --------------------
-
-/** SECURITY_MAX_SID_SIZE: maximum SID byte size. */
+/** Maximum SID allocation size in bytes. */
 export const SECURITY_MAX_SID_SIZE = 68
-/** SID_AND_ATTRIBUTES stride: { PSID Sid @0 (8); DWORD Attributes @8 (4) } + pad. */
+/** x64 SID_AND_ATTRIBUTES byte size. */
 export const SID_AND_ATTRIBUTES_SIZE = 16
-/** TOKEN_GROUPS.Groups[] starts at offset 8 (GroupCount @0 + alignment). */
+/** x64 TOKEN_GROUPS offset of the first group entry. */
 export const TOKEN_GROUPS_OFFSET = 8
-/** sizeof(EXPLICIT_ACCESS_W): perms@0 mode@4 inheritance@8 Trustee@16. */
+/** x64 EXPLICIT_ACCESS_W byte size. */
 export const EXPLICIT_ACCESS_W_SIZE = 48
-/** Trustee offset inside EXPLICIT_ACCESS_W. */
+/** x64 offset of TRUSTEE_W inside EXPLICIT_ACCESS_W. */
 export const TRUSTEE_W_OFFSET = 16
-/** ptstrName offset inside TRUSTEE_W (=> 40 inside EXPLICIT_ACCESS_W). */
+/** x64 offset of ptstrName inside TRUSTEE_W. */
 export const TRUSTEE_W_PTSTRNAME_OFFSET = 24
-/** sizeof(STARTUPINFOW), verified by abi-probe. */
-export const STARTUPINFOW_SIZE = 104
-/** sizeof(PROCESS_INFORMATION), verified by abi-probe. */
-export const PROCESS_INFORMATION_SIZE = 24

packages/sandbox/sandbox-windows-acl/tests/acl-failure-paths.spec.ts

@@ -1,6 +1,6 @@
 /**
- * ACL failure-path tests with stub binding tables (the failure-paths.spec.ts
- * pattern): every checked Win32 call in the lock, read-merge-write, and
+ * ACL failure-path tests with minimal stub binding tables: every checked
+ * Win32 call in the lock, read-merge-write, and
  * grant-skip sequence has a failing counterpart, and each failure closes the
  * handles it created before throwing. The exact-ACE skip and the DACL-walk
  * defenses are driven through crafted in-memory ACL/SID buffers. Pure
@@ -9,13 +9,13 @@
  */
 
 import { tmpdir } from 'node:os'
+import { Win32Error } from '@deepseek-ai/dsh-win32-process'
 import { describe, expect, it, vi } from 'vitest'
 import koffi from 'koffi'
 
 import { grantWrite, revokeWrite, withPathLock } from '../src/acl.ts'
 import { allocBytes, ptrAddress } from '../src/ffi.ts'
 import type { NativePtr, Win32Bindings } from '../src/ffi.ts'
-import { Win32Error } from '../src/errors.ts'
 import * as abi from '../src/win32-abi.ts'
 
 const PVOID = koffi.pointer('void')

packages/sandbox/sandbox-windows-acl/tests/ffi.spec.ts

@@ -1,8 +1,7 @@
 /**
- * FFI helper tests with stub binding tables (the failure-paths.spec.ts
- * pattern): error formatting and temp-path decoding defenses, the
- * last-error throwers' detail fallback, pointer decode NULL handling, and
- * the bounded SID comparison's early exits. Pure stubs — no real Win32
+ * Sandbox-specific FFI tests with stub binding tables: temp-path decoding,
+ * invalid-handle checks, pointer-at-offset decoding, and the bounded SID
+ * comparison's early exits. Pure stubs — no real Win32
  * calls, so these run on every platform; the real-FFI round-trip lives in
  * acl.spec.ts and probe.spec.ts (win32 only).
  */
@@ -10,17 +9,15 @@
 import { describe, expect, it, vi } from 'vitest'
 import koffi from 'koffi'
 
-import { Win32Error } from '../src/errors.ts'
+import { Win32Error } from '@deepseek-ai/dsh-win32-process'
 import {
-  allocBytes, decodePtr, decodePtrAt, errorText, getTempPath,
-  isInvalidHandle, isNullPtr, sameSidAt, throwLastError, throwWin32,
+  allocBytes, decodePtrAt, getTempPath,
+  isInvalidHandle, sameSidAt,
 } from '../src/ffi.ts'
 import type { NativePtr, Win32Bindings } from '../src/ffi.ts'
 import * as abi from '../src/win32-abi.ts'
 
-const PVOID = koffi.pointer('void')
-
-/** A stub whose formatMessageW writes real UTF-16 text (the errorText round-trip). */
+/** A stub whose formatMessageW supplies text to the GetTempPath failure path. */
 function formatApi(): { api: Win32Bindings; formatMessageW: ReturnType<typeof vi.fn> } {
   const formatMessageW = vi.fn((_flags: number, _source: null, _id: number, _lang: number, buffer: Buffer, _size: number, _args: null) => {
     const text = 'access denied'
@@ -48,18 +45,6 @@ function craftSid(revision: number, count: number, authority: number[] = [0, 0,
   return sid
 }
 
-describe('errorText', () => {
-  it('decodes the formatted UTF-16 message and trims it', () => {
-    const { api } = formatApi()
-    expect(errorText(api, 5)).toBe('access denied')
-  })
-
-  it('returns an empty string when FormatMessageW formats nothing', () => {
-    const api = { formatMessageW: vi.fn(() => 0) } as unknown as Win32Bindings
-    expect(errorText(api, 5)).toBe('')
-  })
-})
-
 describe('getTempPath', () => {
   it('decodes the NUL-terminated temp path GetTempPathW wrote', () => {
     const api = {
@@ -83,55 +68,14 @@ describe('getTempPath', () => {
     expect(caught).toBeInstanceOf(Win32Error)
     expect((caught as Win32Error).api).toBe('GetTempPathW')
   })
-})
-
-describe('throwLastError and throwWin32', () => {
-  it('throwLastError formats the system message when no detail is given', () => {
-    const { api } = formatApi()
-    let caught: unknown
-    try {
-      throwLastError(api, 'Probe')
-    } catch (error) {
-      caught = error
-    }
-    expect(caught).toBeInstanceOf(Win32Error)
-    expect((caught as Win32Error).message).toContain('Probe failed (Win32 5): access denied')
-  })
-
-  it('throwWin32 formats the system message when no detail is given', () => {
-    const { api } = formatApi()
-    let caught: unknown
-    try {
-      throwWin32(api, 'Probe', 5)
-    } catch (error) {
-      caught = error
-    }
-    expect(caught).toBeInstanceOf(Win32Error)
-    expect((caught as Win32Error).message).toContain('Probe failed (Win32 5): access denied')
-  })
-
-  it('Win32Error appends the detail when one is given', () => {
-    const error = new Win32Error('Probe', 5, 'the lock file path')
-    expect(error.name).toBe('Win32Error')
-    expect(error.api).toBe('Probe')
-    expect(error.win32Code).toBe(5)
-    expect(error.message).toBe('Probe failed (Win32 5): the lock file path')
-  })
 
-  it('Win32Error omits the detail suffix when none is given', () => {
-    const error = new Win32Error('Probe', 5)
-    expect(error.message).toBe('Probe failed (Win32 5)')
+  it('rejects a required length larger than the fixed buffer', () => {
+    const api = { getTempPathW: vi.fn(() => 300) } as unknown as Win32Bindings
+    expect(() => getTempPath(api)).toThrow(/GetTempPathW failed \(Win32 122\): required 300/u)
   })
 })
 
-describe('pointer NULL handling', () => {
-  it('isNullPtr accepts null, undefined, and the zero pointer', () => {
-    expect(isNullPtr(null)).toBe(true)
-    expect(isNullPtr(undefined)).toBe(true)
-    expect(isNullPtr(0n as NativePtr)).toBe(true)
-    expect(isNullPtr(42n as NativePtr)).toBe(false)
-  })
-
+describe('sandbox pointer handling', () => {
   it('isInvalidHandle treats NULL as failure', () => {
     expect(isInvalidHandle(null)).toBe(true)
     expect(isInvalidHandle(undefined)).toBe(true)
@@ -150,11 +94,6 @@ describe('pointer NULL handling', () => {
     buffer.writeBigUInt64LE(42n, 0)
     expect(decodePtrAt(buffer, 0)).toBe(42n)
   })
-
-  it('decodePtr returns null for an unset out-parameter slot', () => {
-    const slot = koffi.alloc(PVOID, 1) as unknown as NativePtr
-    expect(decodePtr(slot)).toBeNull()
-  })
 })
 
 describe('sameSidAt bounded comparison', () => {

packages/sandbox/sandbox-windows-acl/tests/grant-failure-paths.spec.ts

@@ -1,6 +1,6 @@
 /**
- * AclWriteGrant failure-path tests with stub binding tables (the
- * failure-paths.spec.ts pattern): create fails closed on SID-parse failure,
+ * AclWriteGrant failure-path tests with minimal stub binding tables: create
+ * fails closed on SID-parse failure,
  * dispose aggregates revocation and SID-free failures into an
  * AggregateError. Pure stubs — no real Win32 calls, so these run on every
  * platform; the real-FFI round-trip lives in grant.spec.ts (win32 only).

packages/sandbox/sandbox-windows-acl/tests/index-failure-paths.spec.ts

@@ -11,12 +11,13 @@
 import { mkdtempSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
+import { Win32Error } from '@deepseek-ai/dsh-win32-process'
+import { ERROR_BROKEN_PIPE } from '@deepseek-ai/dsh-win32-process/src/abi.ts'
+import { PROCESS_INFORMATION } from '@deepseek-ai/dsh-win32-process/src/ffi.ts'
 import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest'
 import koffi from 'koffi'
 
-import { PROCESS_INFORMATION } from '../src/ffi.ts'
 import type { NativePtr, Win32Bindings } from '../src/ffi.ts'
-import { Win32Error } from '../src/errors.ts'
 import { AclSandbox } from '../src/index.ts'
 import * as abi from '../src/win32-abi.ts'
 
@@ -146,10 +147,11 @@ function happyStubs(): HappyStubs {
   const setInformationJobObject = vi.fn(() => 1)
   const assignProcessToJobObject = vi.fn(() => 1)
   const resumeThread = vi.fn(() => 0)
+  const terminateProcess = vi.fn(() => 1)
   const getStdHandle = vi.fn(() => fresh())
   const localFree = vi.fn(() => 0n)
   const closeHandle = vi.fn(() => 1)
-  const getLastError = vi.fn(() => abi.ERROR_BROKEN_PIPE) // the drains' clean EOF
+  const getLastError = vi.fn(() => ERROR_BROKEN_PIPE) // the drains' clean EOF
   const formatMessageW = vi.fn(() => 0)
 
   const api = {
@@ -159,7 +161,8 @@ function happyStubs(): HappyStubs {
     getLengthSid, copySid, createWellKnownSid, isValidSid, createRestrictedToken,
     setTokenInformation, createPipe, setHandleInformation, createProcessAsUserW,
     peekNamedPipe, readFile, waitForSingleObject, getExitCodeProcess, createJobObjectW,
-    setInformationJobObject, assignProcessToJobObject, resumeThread, getStdHandle,
+    setInformationJobObject, assignProcessToJobObject, resumeThread, terminateProcess,
+    getStdHandle,
     localFree, closeHandle, getLastError, formatMessageW,
   } as unknown as Win32Bindings
   return {

packages/sandbox/sandbox-windows-acl/tests/quote.spec.ts

@@ -1,88 +0,0 @@
-/**
- * quoteArg unit tests plus a round-trip through the REAL CommandLineToArgvW
- * parser (shell32.dll, shellapi.h line ~867:
- * `LPWSTR *CommandLineToArgvW(LPCWSTR lpCmdLine, int *pNumArgs)`) on win32.
- *
- * CommandLineToArgvW applies the documented backslash rule (2n backslashes
- * before a quote produce n backslashes and toggle quoting; 2n+1 produce n
- * backslashes and a literal quote) to every token EXCEPT the first — the
- * first token is parsed with backslashes literal and quotes toggling
- * (verified empirically on this machine, Windows 11 build 26200). The
- * round-trip therefore prepends a plain program token, exactly like
- * buildCommandLine's real callers do, so the arguments under test land on
- * the rule-applying tokens.
- *
- * Reading argv from CommandLineToArgvW: koffi cannot decode the returned
- * LPWSTR* contents directly (the pointed-to strings are not koffi-registered
- * references), so each string is copied with lstrcpynW (winbase.h line
- * ~1500) into a Node Buffer and read as UTF-16LE; lengths come from
- * lstrlenW (winbase.h line ~1506); the argv block is freed with LocalFree
- * (winbase.h line ~1127) — CommandLineToArgvW's documented contract.
- */
-
-import { describe, expect, it } from 'vitest'
-
-import { buildCommandLine, quoteArg } from '../src/spawn.ts'
-
-const isWin32 = process.platform === 'win32'
-
-/**
- * Table cases: input argv entry → the exact command-line fragment quoteArg
- * must produce. Trailing-backslash inputs are the regression: the closing
- * quote must be preceded by DOUBLED backslashes, or the parser reads them as
- * escaping the closing quote.
- */
-const cases: Array<[input: string, quoted: string]> = [
-  ['', '""'],
-  ['a', 'a'],
-  ['a b', '"a b"'],
-  ['a"b', '"a\\"b"'],
-  ['a\\b', 'a\\b'],
-  ['a b\\', '"a b\\\\"'],
-  ['a b\\\\', '"a b\\\\\\\\"'],
-  ['a b\\\\\\', '"a b\\\\\\\\\\\\"'],
-  ['a\\\\"b', '"a\\\\\\\\\\"b"'],
-]
-
-describe('quoteArg', () => {
-  it.each(cases)('quotes %j as %j', (input, quoted) => {
-    expect(quoteArg(input)).toBe(quoted)
-  })
-})
-
-describe.skipIf(!isWin32)('CommandLineToArgvW round-trip', () => {
-  it('parses quoteArg+join back to the exact original argv', async () => {
-    const { default: koffi } = await import('koffi')
-    const PVOID = koffi.pointer('void')
-    const shell32 = koffi.load('shell32.dll')
-    const kernel32 = koffi.load('kernel32.dll')
-    const commandLineToArgvW = shell32.func('__stdcall', 'CommandLineToArgvW', PVOID, ['str16', koffi.pointer('int')])
-    const lstrcpynW = kernel32.func('__stdcall', 'lstrcpynW', PVOID, [PVOID, PVOID, 'int'])
-    const lstrlenW = kernel32.func('__stdcall', 'lstrlenW', 'int', [PVOID])
-    const localFree = kernel32.func('__stdcall', 'LocalFree', PVOID, [PVOID])
-
-    const parse = (commandLine: string): string[] => {
-      const countSlot = koffi.alloc('int', 1) as unknown
-      const argvBlock = commandLineToArgvW(commandLine, countSlot) as unknown
-      try {
-        if (argvBlock === null) throw new Error('CommandLineToArgvW returned NULL')
-        const count = koffi.decode(countSlot, 0, 'int') as number
-        const table = Buffer.from(koffi.view(argvBlock, count * 8))
-        const parsed: string[] = []
-        for (let index = 0; index < count; index++) {
-          const stringAddress = table.readBigUInt64LE(index * 8)
-          const copied = Buffer.alloc(2048)
-          lstrcpynW(copied, stringAddress, copied.length / 2)
-          const length = lstrlenW(copied) as number
-          parsed.push(copied.subarray(0, length * 2).toString('utf16le'))
-        }
-        return parsed
-      } finally {
-        localFree(argvBlock)
-      }
-    }
-
-    const argv = ['', 'a', 'a b', 'a"b', 'a\\b', 'a b\\', 'a b\\\\', 'a b\\\\\\', 'a\\\\"b']
-    expect(parse(buildCommandLine('prog.exe', argv))).toEqual(['prog.exe', ...argv])
-  })
-})

packages/sandbox/sandbox-windows-acl/tests/token-failure-paths.spec.ts

@@ -1,6 +1,6 @@
 /**
- * Restricted-token failure-path tests with stub binding tables (the
- * failure-paths.spec.ts pattern): every checked Win32 call in the token
+ * Restricted-token failure-path tests with minimal stub binding tables: every
+ * checked Win32 call in the token
  * pipeline — open, logon-SID scan, well-known SID creation, default-DACL
  * merge, restricted-token creation — has a failing counterpart, and each
  * failure closes or frees what it created before throwing. Pure stubs — no
@@ -8,12 +8,12 @@
  * lives in acl.spec.ts (win32 only).
  */
 
+import { Win32Error } from '@deepseek-ai/dsh-win32-process'
 import { describe, expect, it, vi } from 'vitest'
 import koffi from 'koffi'
 
 import { allocBytes, isNullPtr } from '../src/ffi.ts'
 import type { NativePtr, Win32Bindings } from '../src/ffi.ts'
-import { Win32Error } from '../src/errors.ts'
 import {
   createRestrictedToken, findLogonSid, makeWellKnownSid, openCurrentProcessToken, setTokenDefaultDaclGrant,
 } from '../src/token.ts'

packages/sandbox/sandbox-windows-acl/tsconfig.json

@@ -17,6 +17,9 @@
     },
     {
       "path": "../../runtime-diagnostics/invariants"
+    },
+    {
+      "path": "../../subprocess/win32-process"
     }
   ]
 }

packages/sandbox/sandbox-windows-acl/verify/abi-probe.cpp

@@ -1,6 +1,3 @@
-// ABI probe: prints sizeof/offsetof/enum values from the actual MinGW Windows
-// headers on this machine. These numbers are the source of truth for the
-// koffi FFI definitions in the Node.js port.
 #include <Windows.h>
 #include <sddl.h>
 #include <AclAPI.h>
@@ -11,185 +8,67 @@
 
 int wmain()
 {
-	P(sizeof(void*));
-	P(sizeof(HANDLE));
-	P(sizeof(DWORD));
-	P(sizeof(WORD));
-	P(sizeof(BOOL));
-
-	P(sizeof(STARTUPINFOW));
-	P(offsetof(STARTUPINFOW, cb));
-	P(offsetof(STARTUPINFOW, lpReserved));
-	P(offsetof(STARTUPINFOW, lpDesktop));
-	P(offsetof(STARTUPINFOW, lpTitle));
-	P(offsetof(STARTUPINFOW, dwX));
-	P(offsetof(STARTUPINFOW, dwY));
-	P(offsetof(STARTUPINFOW, dwXSize));
-	P(offsetof(STARTUPINFOW, dwYSize));
-	P(offsetof(STARTUPINFOW, dwXCountChars));
-	P(offsetof(STARTUPINFOW, dwYCountChars));
-	P(offsetof(STARTUPINFOW, dwFillAttribute));
-	P(offsetof(STARTUPINFOW, dwFlags));
-	P(offsetof(STARTUPINFOW, wShowWindow));
-	P(offsetof(STARTUPINFOW, cbReserved2));
-	P(offsetof(STARTUPINFOW, lpReserved2));
-	P(offsetof(STARTUPINFOW, hStdInput));
-	P(offsetof(STARTUPINFOW, hStdOutput));
-	P(offsetof(STARTUPINFOW, hStdError));
-
-	P(sizeof(PROCESS_INFORMATION));
-	P(offsetof(PROCESS_INFORMATION, hProcess));
-	P(offsetof(PROCESS_INFORMATION, hThread));
-	P(offsetof(PROCESS_INFORMATION, dwProcessId));
-	P(offsetof(PROCESS_INFORMATION, dwThreadId));
-
-	P(sizeof(SECURITY_ATTRIBUTES));
-	P(offsetof(SECURITY_ATTRIBUTES, nLength));
-	P(offsetof(SECURITY_ATTRIBUTES, lpSecurityDescriptor));
-	P(offsetof(SECURITY_ATTRIBUTES, bInheritHandle));
-
-	P(sizeof(TRUSTEE_W));
-	P(offsetof(TRUSTEE_W, pMultipleTrustee));
-	P(offsetof(TRUSTEE_W, MultipleTrusteeOperation));
-	P(offsetof(TRUSTEE_W, TrusteeForm));
-	P(offsetof(TRUSTEE_W, TrusteeType));
-	P(offsetof(TRUSTEE_W, ptstrName));
-
-	P(sizeof(EXPLICIT_ACCESS_W));
-	P(offsetof(EXPLICIT_ACCESS_W, grfAccessPermissions));
-	P(offsetof(EXPLICIT_ACCESS_W, grfAccessMode));
-	P(offsetof(EXPLICIT_ACCESS_W, grfInheritance));
-	P(offsetof(EXPLICIT_ACCESS_W, Trustee));
-
-	P(sizeof(SID_AND_ATTRIBUTES));
-	P(offsetof(SID_AND_ATTRIBUTES, Sid));
-	P(offsetof(SID_AND_ATTRIBUTES, Attributes));
-
-	P(sizeof(TOKEN_GROUPS));
-	P(offsetof(TOKEN_GROUPS, GroupCount));
-	P(offsetof(TOKEN_GROUPS, Groups));
-
-	P(sizeof(TOKEN_MANDATORY_LABEL));
-
-	P(sizeof(SID));
-	P(SECURITY_MAX_SID_SIZE);
-	P(SID_MAX_SUB_AUTHORITIES);
-	P(SID_REVISION);
-
-	P(TOKEN_ASSIGN_PRIMARY);
-	P(TOKEN_DUPLICATE);
-	P(TOKEN_QUERY);
-	P(TOKEN_ADJUST_DEFAULT);
-
-	P(SE_GROUP_LOGON_ID);
-	P(SE_GROUP_INTEGRITY);
-	P(SE_GROUP_INTEGRITY_ENABLED);
-
-	P(FILE_GENERIC_WRITE);
-	P((FILE_GENERIC_WRITE & ~STANDARD_RIGHTS_WRITE));
-	P(STANDARD_RIGHTS_WRITE);
-	P(DELETE);
-	P(FILE_DELETE_CHILD);
-	P(((FILE_GENERIC_WRITE | DELETE | FILE_DELETE_CHILD) & ~STANDARD_RIGHTS_WRITE));
-
-	P(FILE_SHARE_READ);
-	P(FILE_SHARE_WRITE);
-	P(FILE_SHARE_DELETE);
-	P(GENERIC_READ);
-	P(GENERIC_WRITE);
-	P(OPEN_ALWAYS);
-	P(LOCKFILE_EXCLUSIVE_LOCK);
-	P(LOCKFILE_FAIL_IMMEDIATELY);
-	P(ERROR_LOCK_VIOLATION);
-	P(INHERITED_ACE);
-
-	P(DISABLE_MAX_PRIVILEGE);
-	P(SANDBOX_INERT);
-	P(LUA_TOKEN);
-	P(WRITE_RESTRICTED);
-
-	P((int)WinWorldSid);
-	P((int)WinLocalLogonSid);
-	P((int)WinConsoleLogonSid);
-
-	P((int)TokenUser);
-	P((int)TokenGroups);
-	P((int)TokenIntegrityLevel);
-
-	P((int)SE_FILE_OBJECT);
-	P(DACL_SECURITY_INFORMATION);
-
-	P((int)TRUSTEE_IS_UNKNOWN);
-	P((int)TRUSTEE_IS_SID);
-	P((int)NOT_USED_ACCESS);
-	P((int)GRANT_ACCESS);
-	P((int)REVOKE_ACCESS);
-	P(SUB_CONTAINERS_AND_OBJECTS_INHERIT);
-	P(OBJECT_INHERIT_ACE);
-	P(CONTAINER_INHERIT_ACE);
-
-	P(CREATE_SUSPENDED);
-	P(CREATE_NO_WINDOW);
-	P(DETACHED_PROCESS);
-	P(CREATE_NEW_CONSOLE);
-	P(STARTF_USESTDHANDLES);
-	P(HANDLE_FLAG_INHERIT);
-	P(INFINITE);
-
-	P(LMEM_FIXED);
-	P(LMEM_ZEROINIT);
-	P(LPTR);
-
-	P(FORMAT_MESSAGE_ALLOCATE_BUFFER);
-	P(FORMAT_MESSAGE_FROM_SYSTEM);
-	P(FORMAT_MESSAGE_IGNORE_INSERTS);
-	P(MAX_PATH);
-
-	P(ERROR_SUCCESS);
-	P(ERROR_INSUFFICIENT_BUFFER);
-	P(ERROR_NO_MORE_ITEMS);
-	P(ERROR_INVALID_PARAMETER);
-	P(ERROR_INVALID_SID);
-	P(ERROR_NONE_MAPPED);
-	P(ERROR_BROKEN_PIPE);
-
-	// Job object (runner kill-on-close hardening)
-	P(sizeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION));
-	P(sizeof(JOBOBJECT_BASIC_LIMIT_INFORMATION));
-	P(sizeof(IO_COUNTERS));
-	P(offsetof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION, BasicLimitInformation));
-	P(offsetof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION, BasicLimitInformation) + offsetof(JOBOBJECT_BASIC_LIMIT_INFORMATION, LimitFlags));
-	P(offsetof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION, ProcessMemoryLimit));
-	P((int)JobObjectExtendedLimitInformation);
-	P(JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE);
-
-	// static assertions for the values the koffi module will hardcode
-	static_assert(sizeof(STARTUPINFOW) == 104, "STARTUPINFOW size");
-	static_assert(sizeof(PROCESS_INFORMATION) == 24, "PROCESS_INFORMATION size");
-	static_assert(sizeof(SECURITY_ATTRIBUTES) == 24, "SECURITY_ATTRIBUTES size");
-	static_assert(sizeof(EXPLICIT_ACCESS_W) == 48, "EXPLICIT_ACCESS_W size");
-	static_assert(sizeof(TRUSTEE_W) == 32, "TRUSTEE_W size");
-	static_assert(sizeof(SID_AND_ATTRIBUTES) == 16, "SID_AND_ATTRIBUTES size");
-	static_assert(SECURITY_MAX_SID_SIZE == 68, "SECURITY_MAX_SID_SIZE");
-	static_assert(TOKEN_QUERY == 0x8 && TOKEN_DUPLICATE == 0x2 && TOKEN_ADJUST_DEFAULT == 0x80 && TOKEN_ASSIGN_PRIMARY == 0x1, "token rights");
-	static_assert(SE_GROUP_LOGON_ID == 0xC0000000, "logon id attr");
-	static_assert(FILE_GENERIC_WRITE == 0x120116, "generic write");
-	static_assert((FILE_GENERIC_WRITE & ~STANDARD_RIGHTS_WRITE) == 0x100116, "poc grant mask");
-	static_assert(DELETE == 0x10000 && FILE_DELETE_CHILD == 0x40, "delete rights");
-	static_assert(((FILE_GENERIC_WRITE | DELETE | FILE_DELETE_CHILD) & ~STANDARD_RIGHTS_WRITE) == 0x110156, "sandbox grant mask");
-	static_assert(FILE_SHARE_READ == 0x1 && FILE_SHARE_WRITE == 0x2 && FILE_SHARE_DELETE == 0x4, "share modes");
-	static_assert(OPEN_ALWAYS == 4, "open always");
-	static_assert(LOCKFILE_EXCLUSIVE_LOCK == 0x2 && LOCKFILE_FAIL_IMMEDIATELY == 0x1, "lockfile flags");
-	static_assert(ERROR_LOCK_VIOLATION == 33, "lock violation");
-	static_assert(INHERITED_ACE == 0x10, "inherited ace flag");
-	static_assert(GRANT_ACCESS == 1 && REVOKE_ACCESS == 4, "access modes");
-	static_assert(SUB_CONTAINERS_AND_OBJECTS_INHERIT == 0x3, "inheritance");
-	static_assert(CREATE_NO_WINDOW == 0x08000000, "create no window");
-	static_assert(STARTF_USESTDHANDLES == 0x100, "std handles flag");
-	static_assert(sizeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION) == 144, "job extended limit size");
-	static_assert(offsetof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION, BasicLimitInformation) + offsetof(JOBOBJECT_BASIC_LIMIT_INFORMATION, LimitFlags) == 16, "job LimitFlags offset");
-	static_assert(JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE == 0x2000, "kill on job close flag");
-	static_assert(JobObjectExtendedLimitInformation == 9, "extended limit class");
-	printf("\nstatic_asserts passed\n");
-	return 0;
+  P(sizeof(TRUSTEE_W));
+  P(offsetof(TRUSTEE_W, ptstrName));
+  P(sizeof(EXPLICIT_ACCESS_W));
+  P(offsetof(EXPLICIT_ACCESS_W, Trustee));
+  P(sizeof(SID_AND_ATTRIBUTES));
+  P(offsetof(SID_AND_ATTRIBUTES, Attributes));
+  P(sizeof(TOKEN_GROUPS));
+  P(offsetof(TOKEN_GROUPS, Groups));
+  P(SECURITY_MAX_SID_SIZE);
+  P(SID_MAX_SUB_AUTHORITIES);
+  P(TOKEN_ASSIGN_PRIMARY);
+  P(TOKEN_DUPLICATE);
+  P(TOKEN_QUERY);
+  P(TOKEN_ADJUST_DEFAULT);
+  P(SE_GROUP_LOGON_ID);
+  P(FILE_GENERIC_WRITE);
+  P(STANDARD_RIGHTS_WRITE);
+  P(DELETE);
+  P(FILE_DELETE_CHILD);
+  P(((FILE_GENERIC_WRITE | DELETE | FILE_DELETE_CHILD) & ~STANDARD_RIGHTS_WRITE));
+  P(FILE_SHARE_READ);
+  P(FILE_SHARE_WRITE);
+  P(FILE_SHARE_DELETE);
+  P(GENERIC_READ);
+  P(GENERIC_WRITE);
+  P(OPEN_ALWAYS);
+  P(LOCKFILE_EXCLUSIVE_LOCK);
+  P(LOCKFILE_FAIL_IMMEDIATELY);
+  P(ERROR_LOCK_VIOLATION);
+  P(INHERITED_ACE);
+  P(DISABLE_MAX_PRIVILEGE);
+  P(LUA_TOKEN);
+  P(WRITE_RESTRICTED);
+  P((int)WinWorldSid);
+  P((int)TokenGroups);
+  P((int)SE_FILE_OBJECT);
+  P(DACL_SECURITY_INFORMATION);
+  P((int)TRUSTEE_IS_UNKNOWN);
+  P((int)TRUSTEE_IS_SID);
+  P((int)GRANT_ACCESS);
+  P((int)REVOKE_ACCESS);
+  P(SUB_CONTAINERS_AND_OBJECTS_INHERIT);
+  P(MAX_PATH);
+  P(ERROR_SUCCESS);
+
+  static_assert(sizeof(EXPLICIT_ACCESS_W) == 48, "EXPLICIT_ACCESS_W size");
+  static_assert(sizeof(TRUSTEE_W) == 32, "TRUSTEE_W size");
+  static_assert(sizeof(SID_AND_ATTRIBUTES) == 16, "SID_AND_ATTRIBUTES size");
+  static_assert(SECURITY_MAX_SID_SIZE == 68, "SECURITY_MAX_SID_SIZE");
+  static_assert(TOKEN_QUERY == 0x8 && TOKEN_DUPLICATE == 0x2 && TOKEN_ADJUST_DEFAULT == 0x80 && TOKEN_ASSIGN_PRIMARY == 0x1, "token rights");
+  static_assert(SE_GROUP_LOGON_ID == 0xC0000000, "logon id attr");
+  static_assert(FILE_GENERIC_WRITE == 0x120116, "generic write");
+  static_assert(DELETE == 0x10000 && FILE_DELETE_CHILD == 0x40, "delete rights");
+  static_assert(((FILE_GENERIC_WRITE | DELETE | FILE_DELETE_CHILD) & ~STANDARD_RIGHTS_WRITE) == 0x110156, "sandbox grant mask");
+  static_assert(FILE_SHARE_READ == 0x1 && FILE_SHARE_WRITE == 0x2 && FILE_SHARE_DELETE == 0x4, "share modes");
+  static_assert(OPEN_ALWAYS == 4, "open always");
+  static_assert(LOCKFILE_EXCLUSIVE_LOCK == 0x2 && LOCKFILE_FAIL_IMMEDIATELY == 0x1, "lockfile flags");
+  static_assert(ERROR_LOCK_VIOLATION == 33, "lock violation");
+  static_assert(INHERITED_ACE == 0x10, "inherited ace flag");
+  static_assert(GRANT_ACCESS == 1 && REVOKE_ACCESS == 4, "access modes");
+  static_assert(SUB_CONTAINERS_AND_OBJECTS_INHERIT == 0x3, "inheritance");
+  printf("\nstatic_asserts passed\n");
+  return 0;
 }

packages/subprocess/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/README.md
-README.md: 72a30775f45a8140935a013c63e9427e9cbd94d6
-README.zh.md: 790fa35412e5fd6cd14500d9deab6f8d3d603af0
+README.md: 790db2c3c82fc9e359cae6a0ff1eab156b2776b5
+README.zh.md: 4a01d23b4e409edb6d6ad914351c7a7b95b3c744

packages/subprocess/README.md

@@ -8,6 +8,7 @@ The shared process substrate for one execution world: executable lookup, fully-s
 |---|---|---|
 | [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | Service Definition: executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
 | [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | Local Service Provider: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
+| [`win32-process`](win32-process/README.md) (`@deepseek-ai/dsh-win32-process`) | — | Windows-only low-level library: the single Koffi owner for restricted process creation, inherited/anonymous-pipe stdio, suspended Job assignment, waits, and handle cleanup |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
 

packages/subprocess/README.zh.md

@@ -8,6 +8,7 @@
 |---|---|---|
 | [`subprocess`](subprocess/README.zh.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | Service Definition：可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
 | [`subprocess-local`](subprocess-local/README.zh.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地 Service Provider：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的 dispose（资源释放） |
+| [`win32-process`](win32-process/README.zh.md)（`@deepseek-ai/dsh-win32-process`） | 无 | 仅限 Windows 的底层库：restricted process creation、继承／匿名管道 stdio、suspended Job 分配、wait 与句柄清理的唯一 Koffi owner |
 
 即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
 

packages/subprocess/win32-process/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/subprocess/win32-process/README.md
+README.md: 208a31741098c5c4d76d846b3a1345b24b6fc135
+README.zh.md: 3c403efa8cdf389539663e79d95b766fb8ba0fcf

packages/subprocess/win32-process/README.md

@@ -0,0 +1,50 @@
+# @deepseek-ai/dsh-win32-process
+
+English | [中文](README.zh.md)
+
+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.
+
+## 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.
+- **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.
+
+The Windows ACL sandbox adds SID, DACL, grant, workspace, and public child policy above these primitives.
+
+## Header verification
+
+The process, stdio, and Job constants plus selected structure sizes and offsets are checked against the MinGW Windows headers by [`verify/abi-probe.cpp`](verify/abi-probe.cpp):
+
+```sh
+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.
+
+## Model Experience
+
+### Process primitives
+
+#### 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.
+
+#### Token effect
+
+None directly. Consumers decide whether process output enters a tool result or later model request.
+
+#### KV Cache effect
+
+The package contributes no stable request prefix, so it does not invalidate model KV caches.
+
+## Known Limitations and Deferred Work
+
+- **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.
+- **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.

packages/subprocess/win32-process/README.zh.md

@@ -0,0 +1,52 @@
+# @deepseek-ai/dsh-win32-process
+
+[English](README.md) | 中文
+
+供 Windows ACL 沙箱消费的底层 Win32 进程库。它唯一拥有仓库中可复用 restricted-process、stdio 与 Job Object 操作的 Koffi 绑定表；它不是 Cordis 服务，也不决定沙箱策略或公共 child 行为。
+
+## 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、继承环境块、返回值检查与句柄清理。
+- **管道进程原语** — `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 关闭行为。
+
+Windows ACL 沙箱在这些原语上增加 SID、DACL、grant、workspace 与公共 child policy。
+
+<a id="header-verification"></a>
+
+## 头部验证
+
+process、stdio 与 Job 的常量以及选定结构体的大小和偏移由 [`verify/abi-probe.cpp`](verify/abi-probe.cpp) 对照 MinGW Windows 头文件检查：
+
+```sh
+g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp && ./abi-probe.exe
+```
+
+Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载时断言各自的 64 位大小；其余已记录偏移和常量由该探针提供证据。
+
+## Model Experience
+
+### 进程原语
+
+#### 模型看到什么
+
+没有直接内容。本包向 sandbox 提供 `Win32ProcessBindings` 与进程原语；sandbox 拥有全部模型可见工具、输出与诊断，本包不贡献提示词或工具 schema。
+
+#### Token 影响
+
+没有直接影响。消费方决定进程输出是否进入工具结果或后续模型请求。
+
+#### KV Cache 影响
+
+本包不贡献稳定请求前缀，因此不会使模型 KV Cache 失效。
+
+## Known Limitations and Deferred Work
+
+- **仅在 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 消费方出现前均不提供。
+- **创建到分配之间的中断** — 目标以 suspended 状态启动，不能在 Job 分配前执行，但 runner 若在进程创建到分配之间的极窄区间被外力终止，可能留下 suspended target。本包不声明原子 Job 附加保证。
+- **header 证据限定架构** — 已提交的 ABI probe 与布局常量覆盖仓库当前 64 位 Windows 目标。支持新的指针宽度或不兼容 Windows ABI 前，必须先更新 probe。

packages/subprocess/win32-process/package.json

@@ -0,0 +1,45 @@
+{
+  "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.1-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/subprocess/win32-process"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/cordis": "workspace:^"
+  },
+  "dependencies": {
+    "koffi": "^3.1.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/cordis": "workspace:^"
+  }
+}

packages/subprocess/win32-process/src/abi.ts

@@ -0,0 +1,38 @@
+/** Generic Win32 process, stdio, and Job Object constants verified on x64. */
+
+/** STARTUPINFOW uses the standard input, output, and error handles. */
+export const STARTF_USESTDHANDLES = 0x00000100
+/** HandleInformation flag that permits child inheritance. */
+export const HANDLE_FLAG_INHERIT = 0x1
+/** Infinite WaitForSingleObject timeout. */
+export const INFINITE = 0xFFFFFFFF
+/** CreateProcess flag that prevents user code from running before resume. */
+export const CREATE_SUSPENDED = 0x4
+/** GetStdHandle selector for standard input. */
+export const STD_INPUT_HANDLE = -10
+/** GetStdHandle selector for standard output. */
+export const STD_OUTPUT_HANDLE = -11
+/** GetStdHandle selector for standard error. */
+export const STD_ERROR_HANDLE = -12
+/** FormatMessage reads the operating system message table. */
+export const FORMAT_MESSAGE_FROM_SYSTEM = 0x00001000
+/** FormatMessage leaves insertion placeholders uninterpreted. */
+export const FORMAT_MESSAGE_IGNORE_INSERTS = 0x00000200
+/** Win32 code reporting a caller-provided buffer is too small. */
+export const ERROR_INSUFFICIENT_BUFFER = 122
+/** Win32 code reporting that the other pipe end closed. */
+export const ERROR_BROKEN_PIPE = 109
+/** Win32 code reporting that a pipe has no remaining data. */
+export const ERROR_NO_DATA = 232
+/** Job limit that terminates every member when the final Job handle closes. */
+export const JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000
+/** SetInformationJobObject class for JOBOBJECT_EXTENDED_LIMIT_INFORMATION. */
+export const JobObjectExtendedLimitInformation = 9
+/** x64 JOBOBJECT_EXTENDED_LIMIT_INFORMATION byte size. */
+export const JOBOBJECT_EXTENDED_LIMIT_SIZE = 144
+/** Byte offset of BasicLimitInformation.LimitFlags in the extended Job record. */
+export const JOBOBJECT_EXTENDED_LIMIT_FLAGS_OFFSET = 16
+/** x64 STARTUPINFOW byte size verified by the native probe. */
+export const STARTUPINFOW_SIZE = 104
+/** x64 PROCESS_INFORMATION byte size verified by the native probe. */
+export const PROCESS_INFORMATION_SIZE = 24

packages/subprocess/win32-process/src/errors.ts

@@ -0,0 +1,14 @@
+/** Win32 call failure with the exact API name and error code. */
+export class Win32Error extends Error {
+  /** Win32 function whose checked result failed. */
+  readonly api: string
+  /** Exact GetLastError value or direct Win32 API error code. */
+  readonly win32Code: number
+
+  constructor(api: string, win32Code: number, detail?: string) {
+    super(`${api} failed (Win32 ${win32Code})${detail === undefined ? '' : `: ${detail}`}`)
+    this.name = 'Win32Error'
+    this.api = api
+    this.win32Code = win32Code
+  }
+}

packages/subprocess/win32-process/src/ffi.ts

@@ -0,0 +1,319 @@
+/** Lazy Koffi bindings for generic Win32 process, stdio, and Job operations. */
+
+import koffi from 'koffi'
+import * as abi from './abi.ts'
+import { Win32Error } from './errors.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>
+const PVOID: Ptr = koffi.pointer('void')
+const PPVOID: Ptr = koffi.pointer(PVOID)
+
+/** 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>
+  /** Token and security APIs. */
+  readonly advapi32: ReturnType<typeof 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
+}
+
+/**
+ * Return whether a Koffi pointer represents NULL.
+ * @param value - pointer value returned by Koffi or a Win32 call.
+ * @returns true for null, undefined, or address zero.
+ */
+export function isNullPtr(value: NativePtr | null | undefined): value is null | undefined {
+  return value === null || value === undefined || (value as bigint) === 0n
+}
+
+/** STARTUPINFOW fields used by inherited or piped stdio launches. */
+export interface StartupInfoInput {
+  cb: number
+  dwFlags: number
+  hStdInput: NativePtr
+  hStdOutput: NativePtr
+  hStdError: NativePtr
+}
+
+/** Decoded PROCESS_INFORMATION result. */
+export interface ProcessInfoOutput {
+  hProcess: NativePtr | null
+  hThread: NativePtr | null
+  dwProcessId: number
+  dwThreadId: number
+}
+
+/** Generic Win32 calls consumed by restricted-token sandbox process operations. */
+export interface Win32ProcessBindings {
+  closeHandle(handle: NativePtr): number
+  getLastError(): number
+  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
+  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
+  assignProcessToJobObject(job: NativePtr, process: NativePtr): number
+  resumeThread(thread: NativePtr): number
+  terminateProcess(process: NativePtr, exitCode: number): number
+  getStdHandle(stdHandle: number): NativePtr
+}
+
+/** Koffi STARTUPINFOW layout. */
+export 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. */
+export 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 !== abi.STARTUPINFOW_SIZE) {
+  throw new Error(`STARTUPINFOW layout mismatch: koffi computed ${STARTUPINFOW.size}, expected ${abi.STARTUPINFOW_SIZE}`)
+}
+if (PROCESS_INFORMATION.size !== abi.PROCESS_INFORMATION_SIZE) {
+  throw new Error(`PROCESS_INFORMATION layout mismatch: koffi computed ${PROCESS_INFORMATION.size}, expected ${abi.PROCESS_INFORMATION_SIZE}`)
+}
+/* v8 ignore stop */
+
+/**
+ * Allocate a pointer-sized out-parameter slot.
+ * @returns allocated native slot.
+ */
+export function allocPtrSlot(): NativePtr {
+  return koffi.alloc(PVOID, 1) as NativePtr
+}
+
+/**
+ * Allocate a uint32 out-parameter slot.
+ * @returns allocated native slot.
+ */
+export function allocUint32(): NativePtr {
+  return koffi.alloc('uint32', 1) as NativePtr
+}
+
+/**
+ * Decode a pointer out-parameter.
+ * @param slot - pointer-sized slot filled by Win32.
+ * @returns decoded pointer, or null for address zero.
+ */
+export function decodePtr(slot: NativePtr): NativePtr | null {
+  const value = koffi.decode(slot, PVOID) as NativePtr | null
+  return isNullPtr(value) ? null : value
+}
+
+/**
+ * Decode a uint32 out-parameter.
+ * @param slot - uint32 slot filled by Win32.
+ * @returns decoded unsigned value.
+ */
+export function decodeUint32(slot: NativePtr): number {
+  return koffi.decode(slot, 'uint32') as number
+}
+
+/**
+ * Allocate a zeroed STARTUPINFOW.
+ * @returns allocated struct pointer.
+ */
+export function allocStartupInfo(): NativePtr {
+  return koffi.alloc(STARTUPINFOW, 1) as NativePtr
+}
+
+/**
+ * Encode the stdio-bearing STARTUPINFOW fields.
+ * @param startupInfo - allocated STARTUPINFOW pointer.
+ * @param fields - fields required for inherited stdio.
+ */
+export function encodeStartupInfo(startupInfo: NativePtr, fields: StartupInfoInput): void {
+  koffi.encode(startupInfo, STARTUPINFOW, fields)
+}
+
+/**
+ * Allocate a zeroed PROCESS_INFORMATION.
+ * @returns allocated struct pointer.
+ */
+export function allocProcessInfo(): NativePtr {
+  return koffi.alloc(PROCESS_INFORMATION, 1) as NativePtr
+}
+
+/**
+ * Decode PROCESS_INFORMATION.
+ * @param processInfo - struct pointer filled by CreateProcess.
+ * @returns process/thread handles and ids.
+ */
+export function decodeProcessInfo(processInfo: NativePtr): ProcessInfoOutput {
+  return koffi.decode(processInfo, PROCESS_INFORMATION) as ProcessInfoOutput
+}
+
+let cachedContext: Win32BindingContext | undefined
+let cached: Win32ProcessBindings | undefined
+
+/* v8 ignore start -- exercised by native Windows ABI and sandbox jobs. */
+function bindingContext(): Win32BindingContext {
+  if (cachedContext !== undefined) return cachedContext
+  const kernel32 = koffi.load('kernel32.dll')
+  const advapi32 = koffi.load('advapi32.dll')
+  const bind = (
+    lib: ReturnType<typeof koffi.load>,
+    name: string,
+    result: Ptr | string,
+    args: Array<Ptr | string>,
+  ): unknown => lib.func('__stdcall', name, result, args)
+  cachedContext = { kernel32, advapi32, bind }
+  return cachedContext
+}
+
+function bindings(): Win32ProcessBindings {
+  if (cached !== undefined) return cached
+  const { kernel32, advapi32, bind } = bindingContext()
+  cached = {
+    closeHandle: bind(kernel32, 'CloseHandle', 'int', [PVOID]),
+    getLastError: bind(kernel32, 'GetLastError', 'uint32', []),
+    formatMessageW: bind(kernel32, 'FormatMessageW', 'uint32', [
+      'uint32', PVOID, 'uint32', 'uint32', PVOID, 'uint32', PVOID,
+    ]),
+    createPipe: bind(kernel32, 'CreatePipe', 'int', [PPVOID, PPVOID, PVOID, 'uint32']),
+    setHandleInformation: bind(kernel32, 'SetHandleInformation', 'int', [PVOID, 'uint32', 'uint32']),
+    createProcessAsUserW: bind(advapi32, 'CreateProcessAsUserW', 'int', [
+      PVOID, 'str16', 'str16', PVOID, PVOID, 'int', 'uint32', PVOID, 'str16',
+      koffi.pointer(STARTUPINFOW), koffi.pointer(PROCESS_INFORMATION),
+    ]),
+    readFile: bind(kernel32, 'ReadFile', 'int', [PVOID, PVOID, 'uint32', koffi.pointer('uint32'), PVOID]),
+    peekNamedPipe: bind(kernel32, 'PeekNamedPipe', 'int', [
+      PVOID, PVOID, 'uint32', koffi.pointer('uint32'), koffi.pointer('uint32'), koffi.pointer('uint32'),
+    ]),
+    waitForSingleObject: bind(kernel32, 'WaitForSingleObject', 'uint32', [PVOID, 'uint32']),
+    getExitCodeProcess: bind(kernel32, 'GetExitCodeProcess', 'int', [PVOID, koffi.pointer('uint32')]),
+    createJobObjectW: bind(kernel32, 'CreateJobObjectW', PVOID, [PVOID, 'str16']),
+    setInformationJobObject: bind(kernel32, 'SetInformationJobObject', 'int', [PVOID, 'int', PVOID, 'uint32']),
+    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']),
+  } as unknown as Win32ProcessBindings
+  return cached
+}
+
+/**
+ * Extend the shared process table with caller-owned Win32 API families.
+ * @param create - binds only the caller-specific operations from the shared libraries.
+ * @returns generic process bindings combined with the caller-specific operations.
+ */
+export function extendWin32ProcessBindings<Extension extends object>(
+  create: (context: Win32BindingContext) => Extension,
+): Win32ProcessBindings & Extension {
+  return { ...bindings(), ...create(bindingContext()) }
+}
+/* v8 ignore stop */
+
+/**
+ * Format a Win32 error code through FormatMessageW.
+ * @param api - active binding table.
+ * @param win32Code - captured GetLastError value.
+ * @returns trimmed system message, or an empty string when unavailable.
+ */
+export function errorText(api: Win32ProcessBindings, win32Code: number): string {
+  const buffer = Buffer.alloc(1024)
+  const length = api.formatMessageW(
+    abi.FORMAT_MESSAGE_FROM_SYSTEM | abi.FORMAT_MESSAGE_IGNORE_INSERTS,
+    null,
+    win32Code,
+    0,
+    buffer,
+    buffer.length / 2,
+    null,
+  )
+  return length === 0 ? '' : buffer.subarray(0, length * 2).toString('utf16le').trim()
+}
+
+/**
+ * Throw the current GetLastError value.
+ * @param api - active binding table.
+ * @param name - failing Win32 operation.
+ * @param detail - optional operation context.
+ * @returns never; always throws Win32Error.
+ */
+export function throwLastError(api: Win32ProcessBindings, name: string, detail?: string): never {
+  const win32Code = api.getLastError()
+  throw new Win32Error(name, win32Code, detail ?? errorText(api, win32Code))
+}
+
+/**
+ * Throw an explicitly captured Win32 error code.
+ * @param api - active binding table.
+ * @param name - failing Win32 operation.
+ * @param win32Code - error captured before cleanup.
+ * @param detail - optional operation context.
+ * @returns never; always throws Win32Error.
+ */
+export function throwWin32(
+  api: Win32ProcessBindings,
+  name: string,
+  win32Code: number,
+  detail?: string,
+): never {
+  throw new Win32Error(name, win32Code, detail ?? errorText(api, win32Code))
+}

packages/subprocess/win32-process/src/index.ts

@@ -0,0 +1,28 @@
+/** Low-level Win32 process, stdio, and Job Object primitives used by the Windows ACL sandbox. */
+
+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'

packages/subprocess/win32-process/src/invariant.ts

@@ -0,0 +1,17 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-win32-process`. */
+
+/* jscpd:ignore-start */
+import type { Context } from '@deepseek-ai/cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-win32-process'
+
+export const name = 'win32-process-invariant'
+export const inject = ['invariants']
+
+/** No runtime invariant: operations own only call-local native handles. */
+const install: InvariantInstaller = () => {}
+
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/subprocess/win32-process/src/process.ts

@@ -0,0 +1,429 @@
+/** Typed Win32 process operations over the shared binding table. */
+
+import koffi from 'koffi'
+import * as abi from './abi.ts'
+import {
+  allocProcessInfo,
+  allocPtrSlot,
+  allocStartupInfo,
+  allocUint32,
+  decodeProcessInfo,
+  decodePtr,
+  decodeUint32,
+  encodeStartupInfo,
+  isNullPtr,
+  throwLastError,
+  throwWin32,
+} from './ffi.ts'
+import type { NativePtr, Win32ProcessBindings } from './ffi.ts'
+
+/**
+ * Quote one argument according to CommandLineToArgvW parsing.
+ * @param argument - one argv entry.
+ * @returns bare or quoted command-line segment.
+ */
+export function quoteArg(argument: string): string {
+  if (argument === '') return '""'
+  if (!/[\s"]/u.test(argument)) return argument
+  let quoted = '"'
+  for (let index = 0; index < argument.length; index++) {
+    let backslashes = 0
+    while (index < argument.length && argument.charAt(index) === '\\') {
+      backslashes += 1
+      index += 1
+    }
+    if (index === argument.length) {
+      quoted += '\\'.repeat(backslashes * 2)
+    } else if (argument.charAt(index) === '"') {
+      quoted += '\\'.repeat(backslashes * 2 + 1) + '"'
+    } else {
+      quoted += '\\'.repeat(backslashes) + argument.charAt(index)
+    }
+  }
+  return quoted + '"'
+}
+
+/**
+ * Build the mutable command line accepted by CreateProcessAsUserW.
+ * @param program - executable argv entry.
+ * @param args - remaining argv entries.
+ * @returns joined Win32 command line.
+ */
+export function buildCommandLine(program: string, args: readonly string[]): string {
+  return [program, ...args].map(quoteArg).join(' ')
+}
+
+/** Restricted-token process creation inputs owned by the Windows ACL sandbox. */
+export interface RestrictedProcessSpawnOptions {
+  /** Executable argv entry passed through CreateProcessAsUserW. */
+  command: string
+  /** Arguments excluding the executable. */
+  args: readonly string[]
+  /** Existing child working directory. */
+  cwd: string
+  /** Restricted primary token supplied by sandbox policy. */
+  token: NativePtr
+}
+
+/** Piped child resources whose process and read handles remain caller-owned. */
+export interface SpawnedPipedProcess {
+  /** Direct child process id. */
+  pid: number
+  /** Process handle closed by waitForProcessExit. */
+  process: NativePtr
+  /** Stdout pipe read end closed by drainPipe. */
+  stdoutRead: NativePtr
+  /** Stderr pipe read end closed by drainPipe. */
+  stderrRead: NativePtr
+}
+
+/** Suspended child assigned to one caller-owned kill-on-close Job before resume. */
+export interface SpawnedJobProcess {
+  /** Direct child process id. */
+  pid: number
+  /** Process handle closed by waitForProcessExit. */
+  process: NativePtr
+  /** Job handle closed by the lifecycle owner. */
+  job: NativePtr
+}
+
+interface PipePair {
+  read: NativePtr
+  write: NativePtr
+}
+
+function freeNative(pointer: NativePtr | undefined): void {
+  if (pointer !== undefined) koffi.free(pointer)
+}
+
+function closeBestEffort(api: Win32ProcessBindings, handle: NativePtr | null | undefined): void {
+  if (!isNullPtr(handle)) api.closeHandle(handle)
+}
+
+function createPipe(api: Win32ProcessBindings, owned: Set<NativePtr>): PipePair {
+  const readSlot = allocPtrSlot()
+  let writeSlot: NativePtr | undefined
+  try {
+    writeSlot = allocPtrSlot()
+    if (api.createPipe(readSlot, writeSlot, null, 0) === 0) throwLastError(api, 'CreatePipe')
+    const read = decodePtr(readSlot)
+    const write = decodePtr(writeSlot)
+    if (read === null || write === null) {
+      closeBestEffort(api, read)
+      closeBestEffort(api, write)
+      throwLastError(api, 'CreatePipe', 'null pipe handle')
+    }
+    owned.add(read)
+    owned.add(write)
+    return { read, write }
+  } finally {
+    freeNative(writeSlot)
+    koffi.free(readSlot)
+  }
+}
+
+function closeOwned(api: Win32ProcessBindings, owned: Set<NativePtr>, handle: NativePtr): void {
+  /* v8 ignore next -- each successfully decoded pipe end is uniquely owned. */
+  if (!owned.delete(handle)) return
+  api.closeHandle(handle)
+}
+
+function closeAllOwned(api: Win32ProcessBindings, owned: Set<NativePtr>): void {
+  for (const handle of owned) api.closeHandle(handle)
+  owned.clear()
+}
+
+function createRestrictedProcess(
+  api: Win32ProcessBindings,
+  options: RestrictedProcessSpawnOptions,
+  commandLine: string,
+  creationFlags: number,
+  startupInfo: NativePtr,
+  processInfo: NativePtr,
+): number {
+  // The sandbox mutates its process environment before this call. Passing an
+  // explicit block through Koffi makes CreateProcessAsUserW reject the request
+  // with ERROR_INVALID_PARAMETER, so lpEnvironment remains NULL.
+  return api.createProcessAsUserW(
+    options.token,
+    null,
+    commandLine,
+    null,
+    null,
+    1,
+    creationFlags,
+    null,
+    options.cwd,
+    startupInfo,
+    processInfo,
+  )
+}
+
+/**
+ * Spawn a process with anonymous-pipe stdout/stderr and immediate stdin EOF.
+ * @param api - active binding table.
+ * @param options - command, cwd, args, and restricted primary token.
+ * @returns caller-owned process and pipe read handles.
+ */
+export function spawnPipedProcess(
+  api: Win32ProcessBindings,
+  options: RestrictedProcessSpawnOptions,
+): SpawnedPipedProcess {
+  const owned = new Set<NativePtr>()
+  let startupInfo: NativePtr | undefined
+  let processInfo: NativePtr | undefined
+  try {
+    const stdIn = createPipe(api, owned)
+    const stdOut = createPipe(api, owned)
+    const stdErr = createPipe(api, owned)
+    for (const [handle, label] of [
+      [stdIn.read, 'stdin read end'],
+      [stdOut.write, 'stdout write end'],
+      [stdErr.write, 'stderr write end'],
+    ] as const) {
+      if (api.setHandleInformation(handle, abi.HANDLE_FLAG_INHERIT, abi.HANDLE_FLAG_INHERIT) === 0) {
+        throwLastError(api, 'SetHandleInformation', label)
+      }
+    }
+    startupInfo = allocStartupInfo()
+    encodeStartupInfo(startupInfo, {
+      cb: abi.STARTUPINFOW_SIZE,
+      dwFlags: abi.STARTF_USESTDHANDLES,
+      hStdInput: stdIn.read,
+      hStdOutput: stdOut.write,
+      hStdError: stdErr.write,
+    })
+    processInfo = allocProcessInfo()
+    const created = createRestrictedProcess(
+      api,
+      options,
+      buildCommandLine(options.command, options.args),
+      0,
+      startupInfo,
+      processInfo,
+    )
+    if (created === 0) {
+      const win32Code = api.getLastError()
+      throwWin32(api, 'CreateProcessAsUserW', win32Code, `command: ${options.command}, cwd: ${options.cwd}`)
+    }
+    const info = decodeProcessInfo(processInfo)
+    if (info.hProcess === null || info.hThread === null) {
+      if (info.hProcess !== null) api.terminateProcess(info.hProcess, 1)
+      closeBestEffort(api, info.hThread)
+      closeBestEffort(api, info.hProcess)
+      throw new Error(`CreateProcessAsUserW succeeded but returned null process/thread handles (pid ${info.dwProcessId})`)
+    }
+    closeOwned(api, owned, stdIn.read)
+    closeOwned(api, owned, stdIn.write)
+    closeOwned(api, owned, stdOut.write)
+    closeOwned(api, owned, stdErr.write)
+    closeBestEffort(api, info.hThread)
+    owned.delete(stdOut.read)
+    owned.delete(stdErr.read)
+    return {
+      pid: info.dwProcessId,
+      process: info.hProcess,
+      stdoutRead: stdOut.read,
+      stderrRead: stdErr.read,
+    }
+  } catch (error) {
+    closeAllOwned(api, owned)
+    throw error
+  } finally {
+    freeNative(processInfo)
+    freeNative(startupInfo)
+  }
+}
+
+/**
+ * Drain one anonymous pipe until the writer closes it.
+ * @param api - active binding table.
+ * @param handle - caller-owned pipe read end.
+ * @returns complete bytes read before EOF; the handle is always closed.
+ * @throws when a Win32 pipe operation fails.
+ */
+export async function drainPipe(
+  api: Win32ProcessBindings,
+  handle: NativePtr,
+): Promise<Buffer> {
+  const chunks: Buffer[] = []
+  let countSlot: NativePtr | undefined
+  try {
+    countSlot = allocUint32()
+    for (;;) {
+      const peeked = api.peekNamedPipe(handle, null, 0, null, countSlot, null)
+      if (peeked === 0) {
+        const win32Code = api.getLastError()
+        if (win32Code === abi.ERROR_BROKEN_PIPE || win32Code === abi.ERROR_NO_DATA) break
+        throwLastError(api, 'PeekNamedPipe', `drain failure after ${chunks.length} chunk(s)`)
+      }
+      const available = decodeUint32(countSlot)
+      if (available > 0) {
+        const chunk = Buffer.alloc(available)
+        if (api.readFile(handle, chunk, chunk.length, countSlot, null) === 0) {
+          throwLastError(api, 'ReadFile', `drain failure after ${chunks.length} chunk(s)`)
+        }
+        chunks.push(chunk.subarray(0, decodeUint32(countSlot)))
+      }
+      await new Promise<void>(resolve => setTimeout(resolve, 1))
+    }
+    return Buffer.concat(chunks)
+  } finally {
+    freeNative(countSlot)
+    api.closeHandle(handle)
+  }
+}
+
+/**
+ * Wait for a process and always close its handle.
+ * @param api - active binding table.
+ * @param process - caller-owned process handle.
+ * @returns direct process exit code.
+ */
+export function waitForProcessExit(api: Win32ProcessBindings, process: NativePtr): number {
+  let exitCodeSlot: NativePtr | undefined
+  try {
+    if (api.waitForSingleObject(process, abi.INFINITE) === 0xFFFFFFFF) {
+      throwLastError(api, 'WaitForSingleObject')
+    }
+    exitCodeSlot = allocUint32()
+    if (api.getExitCodeProcess(process, exitCodeSlot) === 0) throwLastError(api, 'GetExitCodeProcess')
+    return decodeUint32(exitCodeSlot)
+  } finally {
+    freeNative(exitCodeSlot)
+    api.closeHandle(process)
+  }
+}
+
+function createKillOnCloseJob(api: Win32ProcessBindings): NativePtr {
+  const job = api.createJobObjectW(null, null)
+  if (isNullPtr(job)) throwLastError(api, 'CreateJobObjectW')
+  const information = Buffer.alloc(abi.JOBOBJECT_EXTENDED_LIMIT_SIZE)
+  information.writeUInt32LE(
+    abi.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
+    abi.JOBOBJECT_EXTENDED_LIMIT_FLAGS_OFFSET,
+  )
+  if (api.setInformationJobObject(
+    job,
+    abi.JobObjectExtendedLimitInformation,
+    information,
+    information.length,
+  ) === 0) {
+    const win32Code = api.getLastError()
+    api.closeHandle(job)
+    throwWin32(api, 'SetInformationJobObject', win32Code)
+  }
+  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.
+ */
+export function spawnInheritedJobProcess(
+  api: Win32ProcessBindings,
+  options: RestrictedProcessSpawnOptions,
+): SpawnedJobProcess {
+  const job = createKillOnCloseJob(api)
+  const getStdHandle = (selector: number, label: string): NativePtr => {
+    const handle = api.getStdHandle(selector)
+    if (!isNullPtr(handle)) return handle
+    const win32Code = api.getLastError()
+    api.closeHandle(job)
+    throwWin32(api, 'GetStdHandle', win32Code, `null ${label} handle`)
+  }
+  const stdIn = getStdHandle(abi.STD_INPUT_HANDLE, 'stdin')
+  const stdOut = getStdHandle(abi.STD_OUTPUT_HANDLE, 'stdout')
+  const stdErr = getStdHandle(abi.STD_ERROR_HANDLE, 'stderr')
+  const enabled: NativePtr[] = []
+  let startupInfo: NativePtr | undefined
+  let processInfo: NativePtr | undefined
+  let created = 0
+  let createFailureCode = 0
+  try {
+    for (const [handle, label] of [
+      [stdIn, 'stdin'],
+      [stdOut, 'stdout'],
+      [stdErr, 'stderr'],
+    ] as const) {
+      if (api.setHandleInformation(handle, abi.HANDLE_FLAG_INHERIT, abi.HANDLE_FLAG_INHERIT) === 0) {
+        throwLastError(api, 'SetHandleInformation', `${label} (enable inherit)`)
+      }
+      enabled.push(handle)
+    }
+    startupInfo = allocStartupInfo()
+    encodeStartupInfo(startupInfo, {
+      cb: abi.STARTUPINFOW_SIZE,
+      dwFlags: abi.STARTF_USESTDHANDLES,
+      hStdInput: stdIn,
+      hStdOutput: stdOut,
+      hStdError: stdErr,
+    })
+    processInfo = allocProcessInfo()
+    created = createRestrictedProcess(
+      api,
+      options,
+      buildCommandLine(options.command, options.args),
+      abi.CREATE_SUSPENDED,
+      startupInfo,
+      processInfo,
+    )
+    if (created === 0) createFailureCode = api.getLastError()
+  } catch (error) {
+    freeNative(processInfo)
+    api.closeHandle(job)
+    throw error
+  } finally {
+    freeNative(startupInfo)
+    for (const handle of enabled) {
+      // The runner spawns nothing else; cleanup failure must not mask the child.
+      api.setHandleInformation(handle, abi.HANDLE_FLAG_INHERIT, 0)
+    }
+  }
+  if (created === 0) {
+    freeNative(processInfo)
+    api.closeHandle(job)
+    throwWin32(
+      api,
+      'CreateProcessAsUserW',
+      createFailureCode,
+      `command: ${options.command}, cwd: ${options.cwd}`,
+    )
+  }
+  let info: ReturnType<typeof decodeProcessInfo>
+  try {
+    info = decodeProcessInfo(processInfo)
+  } finally {
+    freeNative(processInfo)
+  }
+  if (info.hProcess === null || info.hThread === null) {
+    if (info.hProcess !== null) api.terminateProcess(info.hProcess, 1)
+    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})`)
+  }
+  if (api.assignProcessToJobObject(job, info.hProcess) === 0) {
+    const win32Code = api.getLastError()
+    api.terminateProcess(info.hProcess, 1)
+    closeBestEffort(api, info.hThread)
+    closeBestEffort(api, info.hProcess)
+    api.closeHandle(job)
+    throwWin32(api, 'AssignProcessToJobObject', win32Code, `pid ${info.dwProcessId}`)
+  }
+  if (api.resumeThread(info.hThread) === 0xFFFFFFFF) {
+    const win32Code = api.getLastError()
+    closeBestEffort(api, info.hThread)
+    closeBestEffort(api, info.hProcess)
+    api.closeHandle(job)
+    throwWin32(api, 'ResumeThread', win32Code, `pid ${info.dwProcessId}`)
+  }
+  closeBestEffort(api, info.hThread)
+  return { pid: info.dwProcessId, process: info.hProcess, job }
+}

packages/subprocess/win32-process/tests/ffi.spec.ts

@@ -0,0 +1,45 @@
+import koffi from 'koffi'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  Win32Error,
+  allocPtrSlot,
+  decodePtr,
+  isNullPtr,
+  throwLastError,
+} from '../src/index.ts'
+import { PROCESS_INFORMATION_SIZE, STARTUPINFOW_SIZE } from '../src/abi.ts'
+import { PROCESS_INFORMATION, STARTUPINFOW, errorText } from '../src/ffi.ts'
+import type { NativePtr, Win32ProcessBindings } from '../src/index.ts'
+
+describe('shared Win32 process ABI', () => {
+  it('matches the verified x64 structure sizes', () => {
+    expect(STARTUPINFOW.size).toBe(STARTUPINFOW_SIZE)
+    expect(PROCESS_INFORMATION.size).toBe(PROCESS_INFORMATION_SIZE)
+  })
+
+  it('handles NULL pointer out-parameters', () => {
+    const slot = allocPtrSlot()
+    expect(decodePtr(slot)).toBeNull()
+    expect(isNullPtr(0n as NativePtr)).toBe(true)
+    expect(isNullPtr(1n as NativePtr)).toBe(false)
+  })
+
+  it('formats and throws the exact Win32 error', () => {
+    const api = {
+      getLastError: vi.fn(() => 5),
+      formatMessageW: vi.fn((_flags, _source, _id, _language, buffer: Buffer) => {
+        buffer.write('access denied', 'utf16le')
+        return 'access denied'.length
+      }),
+    } as unknown as Win32ProcessBindings
+    expect(errorText(api, 5)).toBe('access denied')
+    expect(() => throwLastError(api, 'Probe')).toThrow(Win32Error)
+    expect(new Win32Error('CloseHandle', 6).message).toBe('CloseHandle failed (Win32 6)')
+  })
+
+  it('decodes a pointer stored by Koffi', () => {
+    const slot = allocPtrSlot()
+    koffi.encode(slot, koffi.pointer('void'), 42n)
+    expect(decodePtr(slot)).toBe(42n)
+  })
+})

packages/subprocess/win32-process/tests/invariant.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it, vi } from 'vitest'
+import { apply, inject, name } from '../src/invariant.ts'
+
+describe('win32-process invariant companion', () => {
+  it('registers the package-owned empty invariant', async () => {
+    const dispose = vi.fn()
+    const register = vi.fn((_packageName: string, _installer: () => void) => dispose)
+    const ctx = { invariants: { register } } as never
+    await expect(apply(ctx)).resolves.toBe(dispose)
+    expect(name).toBe('win32-process-invariant')
+    expect(inject).toEqual(['invariants'])
+    expect(register).toHaveBeenCalledWith('@deepseek-ai/dsh-win32-process', expect.any(Function))
+    const installer = register.mock.calls[0]![1]
+    installer()
+  })
+})

packages/subprocess/win32-process/tests/process-allocation-failure.spec.ts

@@ -0,0 +1,145 @@
+import koffi from 'koffi'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  drainPipe,
+  spawnInheritedJobProcess,
+  spawnPipedProcess,
+  waitForProcessExit,
+} from '../src/index.ts'
+import * as ffi from '../src/ffi.ts'
+import { PROCESS_INFORMATION } from '../src/ffi.ts'
+import type { NativePtr, Win32ProcessBindings } from '../src/ffi.ts'
+
+vi.mock('../src/ffi.ts', { spy: true })
+
+const PVOID = koffi.pointer('void')
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('spawnInheritedJobProcess allocation cleanup', () => {
+  it('frees startup info when process-info allocation throws', () => {
+    const api = {
+      createJobObjectW: vi.fn(() => 50n),
+      setInformationJobObject: vi.fn(() => 1),
+      getStdHandle: vi.fn((selector: number) => BigInt(100 - selector)),
+      setHandleInformation: vi.fn(() => 1),
+      closeHandle: vi.fn(() => 1),
+      getLastError: vi.fn(() => 5),
+      formatMessageW: vi.fn(() => 0),
+    } as unknown as Win32ProcessBindings
+    const free = vi.spyOn(koffi, 'free')
+    vi.mocked(ffi.allocProcessInfo).mockImplementationOnce(() => { throw new Error('process-info allocation failed') })
+    expect(() => spawnInheritedJobProcess(api, {
+      command: 'cmd.exe',
+      args: [],
+      cwd: 'C:\\',
+      token: 70n as NativePtr,
+    })).toThrow('process-info allocation failed')
+    expect(free).toHaveBeenCalledOnce()
+  })
+
+  it('frees process info after a successful inherited spawn', () => {
+    const api = {
+      createJobObjectW: vi.fn(() => 50n),
+      setInformationJobObject: vi.fn(() => 1),
+      getStdHandle: vi.fn((selector: number) => BigInt(100 - selector)),
+      setHandleInformation: vi.fn(() => 1),
+      createProcessAsUserW: vi.fn((_token, _app, _line, _pa, _ta, _inherit, _flags, _env, _cwd, _startup, info) => {
+        koffi.encode(info, PROCESS_INFORMATION, {
+          hProcess: 60n,
+          hThread: 61n,
+          dwProcessId: 1234,
+          dwThreadId: 5678,
+        })
+        return 1
+      }),
+      assignProcessToJobObject: vi.fn(() => 1),
+      resumeThread: vi.fn(() => 0),
+      closeHandle: vi.fn(() => 1),
+      getLastError: vi.fn(() => 5),
+      formatMessageW: vi.fn(() => 0),
+    } as unknown as Win32ProcessBindings
+    const free = vi.spyOn(koffi, 'free')
+    expect(spawnInheritedJobProcess(api, {
+      command: 'cmd.exe',
+      args: [],
+      cwd: 'C:\\',
+      token: 70n as NativePtr,
+    })).toEqual({ pid: 1234, process: 60n, job: 50n })
+    expect(free).toHaveBeenCalledTimes(2)
+  })
+})
+
+describe('shared process allocation cleanup', () => {
+  it('frees pipe slots and process structs after a successful piped spawn', () => {
+    let nextHandle = 10n
+    const api = {
+      createPipe: vi.fn((readSlot: NativePtr, writeSlot: NativePtr) => {
+        koffi.encode(readSlot, PVOID, nextHandle++)
+        koffi.encode(writeSlot, PVOID, nextHandle++)
+        return 1
+      }),
+      setHandleInformation: vi.fn(() => 1),
+      createProcessAsUserW: vi.fn((_token, _app, _line, _pa, _ta, _inherit, _flags, _env, _cwd, _startup, info) => {
+        koffi.encode(info, PROCESS_INFORMATION, {
+          hProcess: 60n,
+          hThread: 61n,
+          dwProcessId: 1234,
+          dwThreadId: 5678,
+        })
+        return 1
+      }),
+      closeHandle: vi.fn(() => 1),
+      getLastError: vi.fn(() => 5),
+      formatMessageW: vi.fn(() => 0),
+    } as unknown as Win32ProcessBindings
+    const free = vi.spyOn(koffi, 'free')
+    expect(spawnPipedProcess(api, {
+      command: 'cmd.exe',
+      args: [],
+      cwd: 'C:\\',
+      token: 70n as NativePtr,
+    })).toMatchObject({ pid: 1234, process: 60n })
+    expect(free).toHaveBeenCalledTimes(8)
+  })
+
+  it('reuses one drain count slot and frees it at EOF', async () => {
+    let peeks = 0
+    const api = {
+      peekNamedPipe: vi.fn((_pipe, _buffer, _size, _read, totalAvail: NativePtr) => {
+        peeks += 1
+        if (peeks > 1) return 0
+        koffi.encode(totalAvail, 'uint32', 1)
+        return 1
+      }),
+      readFile: vi.fn((_file, buffer: Buffer, _count, readSlot: NativePtr) => {
+        buffer[0] = 0x61
+        koffi.encode(readSlot, 'uint32', 1)
+        return 1
+      }),
+      getLastError: vi.fn(() => 109),
+      closeHandle: vi.fn(() => 1),
+    } as unknown as Win32ProcessBindings
+    const alloc = vi.spyOn(koffi, 'alloc')
+    const free = vi.spyOn(koffi, 'free')
+    await expect(drainPipe(api, 70n as NativePtr)).resolves.toEqual(Buffer.from('a'))
+    expect(alloc).toHaveBeenCalledOnce()
+    expect(free).toHaveBeenCalledOnce()
+  })
+
+  it('frees the exit-code slot after reading a process result', () => {
+    const api = {
+      waitForSingleObject: vi.fn(() => 0),
+      getExitCodeProcess: vi.fn((_process, exitCode: NativePtr) => {
+        koffi.encode(exitCode, 'uint32', 42)
+        return 1
+      }),
+      closeHandle: vi.fn(() => 1),
+    } as unknown as Win32ProcessBindings
+    const free = vi.spyOn(koffi, 'free')
+    expect(waitForProcessExit(api, 60n as NativePtr)).toBe(42)
+    expect(free).toHaveBeenCalledOnce()
+  })
+})

packages/sandbox/sandbox-windows-acl/tests/failure-paths.spec.ts → packages/subprocess/win32-process/tests/process-failure-paths.spec.ts

@@ -1,23 +1,28 @@
 /**
  * Failure-path unit tests with minimal stub binding tables: the spawn
  * helpers must close every handle they created before throwing, and
- * getTempPath must refuse to decode a buffer GetTempPathW never wrote.
+ * every generic process failure remains owned by the shared package.
  * Pure stubs — no real Win32 calls, so these run on every platform.
  */
 
 import { describe, expect, it, vi } from 'vitest'
 import koffi from 'koffi'
 
-import { PROCESS_INFORMATION, getTempPath } from '../src/ffi.ts'
-import type { NativePtr, Win32Bindings } from '../src/ffi.ts'
-import { Win32Error } from '../src/errors.ts'
-import { drainPipe, spawnSandboxed, spawnSandboxedInherited, waitForExit } from '../src/spawn.ts'
-import * as abi from '../src/win32-abi.ts'
+import {
+  Win32Error,
+  drainPipe,
+  spawnInheritedJobProcess,
+  spawnPipedProcess,
+  waitForProcessExit,
+} from '../src/index.ts'
+import type { NativePtr, Win32ProcessBindings } from '../src/index.ts'
+import * as abi from '../src/abi.ts'
+import { PROCESS_INFORMATION } from '../src/ffi.ts'
 
 const PVOID = koffi.pointer('void')
 
 /** The stub the CreateProcessAsUserW failure branch needs: pipes "succeed", the spawn fails with Win32 5. */
-function pipeFailureApi(): { api: Win32Bindings; closed: bigint[]; closeHandle: ReturnType<typeof vi.fn> } {
+function pipeFailureApi(): { api: Win32ProcessBindings; closed: bigint[]; closeHandle: ReturnType<typeof vi.fn> } {
   const closed: bigint[] = []
   let next = 1n
   const closeHandle = vi.fn((handle: NativePtr) => {
@@ -35,36 +40,7 @@ function pipeFailureApi(): { api: Win32Bindings; closed: bigint[]; closeHandle:
     getLastError: vi.fn(() => 5), // ERROR_ACCESS_DENIED: the failure the branch reports
     closeHandle,
     formatMessageW: vi.fn(() => 0),
-  } as unknown as Win32Bindings
-  return { api, closed, closeHandle }
-}
-
-/** The stub the ResumeThread failure branch needs: everything succeeds until ResumeThread returns 0xFFFFFFFF. */
-function resumeFailureApi(): { api: Win32Bindings; closed: bigint[]; closeHandle: ReturnType<typeof vi.fn> } {
-  const closed: bigint[] = []
-  let std = 50n
-  const closeHandle = vi.fn((handle: NativePtr) => {
-    closed.push(handle)
-    return 1
-  })
-  const api = {
-    createJobObjectW: vi.fn(() => 100n),
-    setInformationJobObject: vi.fn(() => 1),
-    getStdHandle: vi.fn(() => std++),
-    setHandleInformation: vi.fn(() => 1),
-    createProcessAsUserW: vi.fn((
-      _token: unknown, _app: unknown, _cmd: unknown, _pa: unknown, _ta: unknown,
-      _inherit: unknown, _flags: unknown, _env: unknown, _cwd: unknown, _si: unknown, processInfo: NativePtr,
-    ) => {
-      koffi.encode(processInfo, PROCESS_INFORMATION, { hProcess: 200n, hThread: 201n, dwProcessId: 1234, dwThreadId: 5678 })
-      return 1
-    }),
-    assignProcessToJobObject: vi.fn(() => 1),
-    resumeThread: vi.fn(() => 0xFFFFFFFF),
-    getLastError: vi.fn(() => 5),
-    closeHandle,
-    formatMessageW: vi.fn(() => 0),
-  } as unknown as Win32Bindings
+  } as unknown as Win32ProcessBindings
   return { api, closed, closeHandle }
 }
 
@@ -72,11 +48,11 @@ describe('spawn failure paths close their handles', () => {
   // A dummy token value; the stubbed spawn never reads it.
   const token = 1n as NativePtr
 
-  it('spawnSandboxed closes all six pipe handles before throwing when CreateProcessAsUserW fails', () => {
+  it('closes all six pipe handles before throwing when CreateProcessAsUserW fails', () => {
     const { api, closed, closeHandle } = pipeFailureApi()
     let caught: unknown
     try {
-      spawnSandboxed(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' })
+      spawnPipedProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token })
     } catch (error) {
       caught = error
     }
@@ -87,60 +63,11 @@ describe('spawn failure paths close their handles', () => {
     expect(closed).toEqual([1n, 2n, 3n, 4n, 5n, 6n])
   })
 
-  it('spawnSandboxedInherited closes thread, process, and kill-on-close job before throwing when ResumeThread fails', () => {
-    const { api, closed, closeHandle } = resumeFailureApi()
-    let caught: unknown
-    try {
-      spawnSandboxedInherited(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' })
-    } catch (error) {
-      caught = error
-    }
-    expect(caught).toBeInstanceOf(Win32Error)
-    expect((caught as Win32Error).api).toBe('ResumeThread')
-    expect((caught as Win32Error).win32Code).toBe(5)
-    // thread, process, job — closing the job triggers kill-on-close so the
-    // suspended child dies instead of hanging until this process exits.
-    expect(closeHandle).toHaveBeenCalledTimes(3)
-    expect(closed).toEqual([201n, 200n, 100n])
-  })
-
-  it('spawnSandboxedInherited TERMINATES the suspended child before closing handles when AssignProcessToJobObject fails', () => {
-    // The child is created suspended and is NOT in the kill-on-close job when
-    // the assignment fails: closing the job cannot kill it, so the failure
-    // branch must TerminateProcess first or every failure strands a hanging
-    // orphan forever.
-    const { api: baseApi, closeHandle } = resumeFailureApi()
-    type JobFailureApi = Win32Bindings & {
-      assignProcessToJobObject: ReturnType<typeof vi.fn>
-      terminateProcess: ReturnType<typeof vi.fn>
-    }
-    const api = baseApi as JobFailureApi
-    api.assignProcessToJobObject = vi.fn(() => 0)
-    api.terminateProcess = vi.fn(() => 1)
-    let caught: unknown
-    try {
-      spawnSandboxedInherited(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' })
-    } catch (error) {
-      caught = error
-    }
-    expect(caught).toBeInstanceOf(Win32Error)
-    expect((caught as Win32Error).api).toBe('AssignProcessToJobObject')
-    expect(api.terminateProcess).toHaveBeenCalledExactlyOnceWith(200n, 1)
-    // thread, process, job — and the child is already dead before they close.
-    expect(closeHandle).toHaveBeenCalledTimes(3)
-  })
-})
-
-describe('getTempPath buffer defense', () => {
-  it('throws a clear error instead of decoding a buffer GetTempPathW never wrote', () => {
-    const api = { getTempPathW: vi.fn(() => 300) } as unknown as Win32Bindings // 300 > the 261-char buffer
-    expect(() => getTempPath(api)).toThrow(/GetTempPathW failed \(Win32 122\): required 300/u)
-  })
 })
 
 /** The stub the pipe-happy path needs: CreatePipe fills both out slots with fresh handles. */
-function pipeOkApi(overrides: Partial<Win32Bindings> = {}): {
-  api: Win32Bindings
+function pipeOkApi(overrides: Partial<Win32ProcessBindings> = {}): {
+  api: Win32ProcessBindings
   closed: bigint[]
   closeHandle: ReturnType<typeof vi.fn>
 } {
@@ -168,18 +95,22 @@ function pipeOkApi(overrides: Partial<Win32Bindings> = {}): {
     closeHandle,
     formatMessageW: vi.fn(() => 0),
     ...overrides,
-  } as unknown as Win32Bindings
+  } as unknown as Win32ProcessBindings
   return { api, closed, closeHandle }
 }
 
 describe('spawn pipe failures close their handles', () => {
   const token = 1n as NativePtr
 
-  it('spawnSandboxed reports a CreatePipe failure', () => {
-    const api = { createPipe: vi.fn(() => 0), getLastError: vi.fn(() => 5), formatMessageW: vi.fn(() => 0) } as unknown as Win32Bindings
+  it('reports a CreatePipe failure', () => {
+    const api = {
+      createPipe: vi.fn(() => 0),
+      getLastError: vi.fn(() => 5),
+      formatMessageW: vi.fn(() => 0),
+    } as unknown as Win32ProcessBindings
     let caught: unknown
     try {
-      spawnSandboxed(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' })
+      spawnPipedProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token })
     } catch (error) {
       caught = error
     }
@@ -187,11 +118,15 @@ describe('spawn pipe failures close their handles', () => {
     expect((caught as Win32Error).api).toBe('CreatePipe')
   })
 
-  it('spawnSandboxed reports a NULL pipe handle after CreatePipe succeeds', () => {
-    const api = { createPipe: vi.fn(() => 1), getLastError: vi.fn(() => 5), formatMessageW: vi.fn(() => 0) } as unknown as Win32Bindings
+  it('reports a NULL pipe handle after CreatePipe succeeds', () => {
+    const api = {
+      createPipe: vi.fn(() => 1),
+      getLastError: vi.fn(() => 5),
+      formatMessageW: vi.fn(() => 0),
+    } as unknown as Win32ProcessBindings
     let caught: unknown
     try {
-      spawnSandboxed(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' })
+      spawnPipedProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token })
     } catch (error) {
       caught = error
     }
@@ -199,11 +134,11 @@ describe('spawn pipe failures close their handles', () => {
     expect((caught as Win32Error).api).toBe('CreatePipe')
   })
 
-  it('spawnSandboxed reports a SetHandleInformation failure', () => {
+  it('reports a SetHandleInformation failure', () => {
     const { api } = pipeOkApi({ setHandleInformation: vi.fn(() => 0) })
     let caught: unknown
     try {
-      spawnSandboxed(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' })
+      spawnPipedProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token })
     } catch (error) {
       caught = error
     }
@@ -211,7 +146,7 @@ describe('spawn pipe failures close their handles', () => {
     expect((caught as Win32Error).api).toBe('SetHandleInformation')
   })
 
-  it('spawnSandboxed rejects NULL process/thread handles after a successful spawn', () => {
+  it('rejects NULL process/thread handles after a successful spawn', () => {
     const { api } = pipeOkApi({
       createProcessAsUserW: vi.fn((
         _token: unknown, _app: unknown, _cmd: unknown, _pa: unknown, _ta: unknown,
@@ -221,17 +156,17 @@ describe('spawn pipe failures close their handles', () => {
         return 1
       }),
     })
-    expect(() => spawnSandboxed(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' }))
+    expect(() => spawnPipedProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token }))
       .toThrow(/null process\/thread handles/u)
   })
 })
 
-describe('spawnSandboxedInherited failure paths', () => {
+describe('spawnInheritedJobProcess failure paths', () => {
   const token = 1n as NativePtr
 
   /** The stub the inherited-happy path needs; overrides flip one call per test. */
-  function inheritedApi(overrides: Partial<Win32Bindings> = {}): {
-    api: Win32Bindings
+  function inheritedApi(overrides: Partial<Win32ProcessBindings> = {}): {
+    api: Win32ProcessBindings
     closed: bigint[]
     closeHandle: ReturnType<typeof vi.fn>
   } {
@@ -255,11 +190,12 @@ describe('spawnSandboxedInherited failure paths', () => {
       }),
       assignProcessToJobObject: vi.fn(() => 1),
       resumeThread: vi.fn(() => 0),
+      terminateProcess: vi.fn(() => 1),
       getLastError: vi.fn(() => 5),
       closeHandle,
       formatMessageW: vi.fn(() => 0),
       ...overrides,
-    } as unknown as Win32Bindings
+    } as unknown as Win32ProcessBindings
     return { api, closed, closeHandle }
   }
 
@@ -267,7 +203,7 @@ describe('spawnSandboxedInherited failure paths', () => {
     const { api, closeHandle } = inheritedApi({ getStdHandle: vi.fn(() => 0n as NativePtr) })
     let caught: unknown
     try {
-      spawnSandboxedInherited(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' })
+      spawnInheritedJobProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token })
     } catch (error) {
       caught = error
     }
@@ -280,7 +216,7 @@ describe('spawnSandboxedInherited failure paths', () => {
     const { api } = inheritedApi({ setHandleInformation: vi.fn(() => 0) })
     let caught: unknown
     try {
-      spawnSandboxedInherited(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' })
+      spawnInheritedJobProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token })
     } catch (error) {
       caught = error
     }
@@ -292,7 +228,7 @@ describe('spawnSandboxedInherited failure paths', () => {
     const { api, closeHandle } = inheritedApi({ createProcessAsUserW: vi.fn(() => 0) })
     let caught: unknown
     try {
-      spawnSandboxedInherited(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' })
+      spawnInheritedJobProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token })
     } catch (error) {
       caught = error
     }
@@ -311,16 +247,51 @@ describe('spawnSandboxedInherited failure paths', () => {
         return 1
       }),
     })
-    expect(() => spawnSandboxedInherited(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' }))
+    expect(() => spawnInheritedJobProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token }))
       .toThrow(/null process\/thread handles/u)
     expect(closeHandle).toHaveBeenCalledWith(100n)
   })
 
+  it('terminates the suspended child before closing handles when Job assignment fails', () => {
+    const terminateProcess = vi.fn(() => 1)
+    const { api, closeHandle, closed } = inheritedApi({
+      assignProcessToJobObject: vi.fn(() => 0),
+      terminateProcess,
+    })
+    let caught: unknown
+    try {
+      spawnInheritedJobProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token })
+    } catch (error) {
+      caught = error
+    }
+    expect(caught).toMatchObject({ api: 'AssignProcessToJobObject', win32Code: 5 })
+    expect(terminateProcess).toHaveBeenCalledWith(200n, 1)
+    expect(closeHandle).toHaveBeenCalledWith(201n)
+    expect(closeHandle).toHaveBeenCalledWith(200n)
+    expect(closeHandle).toHaveBeenCalledWith(100n)
+    expect(closed).toEqual([201n, 200n, 100n])
+  })
+
+  it('closes the assigned child and Job when ResumeThread fails', () => {
+    const { api, closeHandle, closed } = inheritedApi({ resumeThread: vi.fn(() => 0xFFFFFFFF) })
+    let caught: unknown
+    try {
+      spawnInheritedJobProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token })
+    } catch (error) {
+      caught = error
+    }
+    expect(caught).toMatchObject({ api: 'ResumeThread', win32Code: 5 })
+    expect(closeHandle).toHaveBeenCalledWith(201n)
+    expect(closeHandle).toHaveBeenCalledWith(200n)
+    expect(closeHandle).toHaveBeenCalledWith(100n)
+    expect(closed).toEqual([201n, 200n, 100n])
+  })
+
   it('closes the job and reports when SetInformationJobObject fails', () => {
     const { api, closeHandle } = inheritedApi({ setInformationJobObject: vi.fn(() => 0) })
     let caught: unknown
     try {
-      spawnSandboxedInherited(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' })
+      spawnInheritedJobProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token })
     } catch (error) {
       caught = error
     }
@@ -333,7 +304,7 @@ describe('spawnSandboxedInherited failure paths', () => {
     const { api } = inheritedApi({ createJobObjectW: vi.fn(() => 0n as NativePtr) })
     let caught: unknown
     try {
-      spawnSandboxedInherited(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' })
+      spawnInheritedJobProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token })
     } catch (error) {
       caught = error
     }
@@ -342,8 +313,10 @@ describe('spawnSandboxedInherited failure paths', () => {
   })
 
   it('returns the pid, process handle, and kill-on-close job when every call succeeds', () => {
-    const { api, closeHandle } = inheritedApi()
-    const spawned = spawnSandboxedInherited(api, token, { command: 'probe.exe', args: [], cwd: 'C:\\' })
+    const assignProcessToJobObject = vi.fn(() => 1)
+    const resumeThread = vi.fn(() => 0)
+    const { api, closeHandle } = inheritedApi({ assignProcessToJobObject, resumeThread })
+    const spawned = spawnInheritedJobProcess(api, { command: 'probe.exe', args: [], cwd: 'C:\\', token })
     expect(spawned.pid).toBe(1234)
     expect(spawned.process).toBe(200n)
     expect(spawned.job).toBe(100n)
@@ -351,6 +324,8 @@ describe('spawnSandboxedInherited failure paths', () => {
     expect(closeHandle).toHaveBeenCalledWith(201n)
     expect(closeHandle).not.toHaveBeenCalledWith(200n)
     expect(closeHandle).not.toHaveBeenCalledWith(100n)
+    expect(assignProcessToJobObject).toHaveBeenCalledWith(100n, 200n)
+    expect(resumeThread).toHaveBeenCalledWith(201n)
   })
 })
 
@@ -362,7 +337,7 @@ describe('drainPipe', () => {
       getLastError: vi.fn(() => abi.ERROR_NO_DATA),
       closeHandle,
       formatMessageW: vi.fn(() => 0),
-    } as unknown as Win32Bindings
+    } as unknown as Win32ProcessBindings
     return drainPipe(api, 30n as NativePtr).then((buffer) => {
       expect(buffer.length).toBe(0)
       expect(closeHandle).toHaveBeenCalledWith(30n)
@@ -370,13 +345,15 @@ describe('drainPipe', () => {
   })
 
   it('reports a PeekNamedPipe failure that is not a clean EOF', () => {
+    const closeHandle = vi.fn(() => 1)
     const api = {
       peekNamedPipe: vi.fn(() => 0),
       getLastError: vi.fn(() => 5),
-      closeHandle: vi.fn(() => 1),
+      closeHandle,
       formatMessageW: vi.fn(() => 0),
-    } as unknown as Win32Bindings
+    } as unknown as Win32ProcessBindings
     return expect(drainPipe(api, 30n as NativePtr)).rejects.toMatchObject({ api: 'PeekNamedPipe' })
+      .then(() => { expect(closeHandle).toHaveBeenCalledWith(30n) })
   })
 
   it('reports a ReadFile failure after data was reported available', () => {
@@ -389,7 +366,7 @@ describe('drainPipe', () => {
       getLastError: vi.fn(() => 5),
       closeHandle: vi.fn(() => 1),
       formatMessageW: vi.fn(() => 0),
-    } as unknown as Win32Bindings
+    } as unknown as Win32ProcessBindings
     return expect(drainPipe(api, 30n as NativePtr)).rejects.toMatchObject({ api: 'ReadFile' })
   })
 
@@ -410,31 +387,37 @@ describe('drainPipe', () => {
       getLastError: vi.fn(() => abi.ERROR_BROKEN_PIPE),
       closeHandle: vi.fn(() => 1),
       formatMessageW: vi.fn(() => 0),
-    } as unknown as Win32Bindings
+    } as unknown as Win32ProcessBindings
     return drainPipe(api, 30n as NativePtr).then((buffer) => {
       expect(buffer.toString('utf8')).toBe('ab')
     })
   })
 })
 
-describe('waitForExit', () => {
+describe('waitForProcessExit', () => {
   it('reports a WaitForSingleObject failure', () => {
+    const closeHandle = vi.fn(() => 1)
     const api = {
       waitForSingleObject: vi.fn(() => 0xFFFFFFFF),
       getLastError: vi.fn(() => 5),
+      closeHandle,
       formatMessageW: vi.fn(() => 0),
-    } as unknown as Win32Bindings
-    expect(() => waitForExit(api, 200n as NativePtr)).toThrow(Win32Error)
+    } as unknown as Win32ProcessBindings
+    expect(() => waitForProcessExit(api, 200n as NativePtr)).toThrow(Win32Error)
+    expect(closeHandle).toHaveBeenCalledWith(200n)
   })
 
   it('reports a GetExitCodeProcess failure', () => {
+    const closeHandle = vi.fn(() => 1)
     const api = {
       waitForSingleObject: vi.fn(() => 0),
       getExitCodeProcess: vi.fn(() => 0),
       getLastError: vi.fn(() => 5),
+      closeHandle,
       formatMessageW: vi.fn(() => 0),
-    } as unknown as Win32Bindings
-    expect(() => waitForExit(api, 200n as NativePtr)).toThrow(Win32Error)
+    } as unknown as Win32ProcessBindings
+    expect(() => waitForProcessExit(api, 200n as NativePtr)).toThrow(Win32Error)
+    expect(closeHandle).toHaveBeenCalledWith(200n)
   })
 
   it('returns the exit code and closes the process handle', () => {
@@ -447,8 +430,8 @@ describe('waitForExit', () => {
       }),
       closeHandle,
       formatMessageW: vi.fn(() => 0),
-    } as unknown as Win32Bindings
-    expect(waitForExit(api, 200n as NativePtr)).toBe(42)
+    } as unknown as Win32ProcessBindings
+    expect(waitForProcessExit(api, 200n as NativePtr)).toBe(42)
     expect(closeHandle).toHaveBeenCalledWith(200n)
   })
 })

packages/subprocess/win32-process/tests/process.spec.ts

@@ -0,0 +1,244 @@
+import koffi from 'koffi'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  Win32Error,
+  drainPipe,
+  spawnInheritedJobProcess,
+  spawnPipedProcess,
+} from '../src/index.ts'
+import { CREATE_SUSPENDED } from '../src/abi.ts'
+import { PROCESS_INFORMATION } from '../src/ffi.ts'
+import type { NativePtr, Win32ProcessBindings } from '../src/index.ts'
+
+const PVOID = koffi.pointer('void')
+
+function inheritedApi(overrides: Partial<Win32ProcessBindings> = {}): {
+  api: Win32ProcessBindings
+  events: string[]
+  createProcessAsUserW: ReturnType<typeof vi.fn>
+  assignProcessToJobObject: ReturnType<typeof vi.fn>
+  resumeThread: ReturnType<typeof vi.fn>
+} {
+  const events: string[] = []
+  const createProcessAsUserWImpl: Win32ProcessBindings['createProcessAsUserW'] =
+    overrides.createProcessAsUserW
+    ?? ((_token, _app, _line, _pa, _ta, _inherit, _flags, _env, _cwd, _startup, info) => {
+      events.push('create')
+      koffi.encode(info, PROCESS_INFORMATION, {
+        hProcess: 60n,
+        hThread: 61n,
+        dwProcessId: 1234,
+        dwThreadId: 5678,
+      })
+      return 1
+    })
+  const createProcessAsUserW = vi.fn(createProcessAsUserWImpl)
+  const assignProcessToJobObject = vi.fn(() => {
+    events.push('assign')
+    return 1
+  })
+  const resumeThread = vi.fn(() => {
+    events.push('resume')
+    return 1
+  })
+  const api = {
+    createJobObjectW: vi.fn(() => 50n),
+    setInformationJobObject: vi.fn(() => 1),
+    getStdHandle: vi.fn((selector: number) => BigInt(100 - selector)),
+    setHandleInformation: vi.fn((_handle: NativePtr, _mask: number, flags: number) => {
+      events.push(flags === 0 ? 'restore' : 'inherit')
+      return 1
+    }),
+    assignProcessToJobObject,
+    resumeThread,
+    terminateProcess: vi.fn(() => 1),
+    closeHandle: vi.fn((handle: NativePtr) => { events.push(`close:${handle}`); return 1 }),
+    getLastError: vi.fn(() => 5),
+    formatMessageW: vi.fn(() => 0),
+    ...overrides,
+    createProcessAsUserW,
+  } as unknown as Win32ProcessBindings
+  return {
+    api,
+    events,
+    createProcessAsUserW,
+    assignProcessToJobObject,
+    resumeThread,
+  }
+}
+
+describe('spawnInheritedJobProcess', () => {
+  const token = 70n as NativePtr
+
+  it('creates suspended, assigns the Job, then resumes the restricted child', () => {
+    const {
+      api,
+      events,
+      createProcessAsUserW,
+      assignProcessToJobObject,
+      resumeThread,
+    } = inheritedApi()
+    const child = spawnInheritedJobProcess(api, {
+      command: 'cmd.exe',
+      args: ['/c', 'exit', '0'],
+      cwd: 'C:\\work',
+      token,
+    })
+    expect(child).toEqual({ pid: 1234, process: 60n, job: 50n })
+    expect(events.indexOf('create')).toBeLessThan(events.indexOf('assign'))
+    expect(events.indexOf('assign')).toBeLessThan(events.indexOf('resume'))
+    expect(assignProcessToJobObject).toHaveBeenCalledWith(50n, 60n)
+    expect(resumeThread).toHaveBeenCalledWith(61n)
+    expect(createProcessAsUserW).toHaveBeenCalledWith(
+      token,
+      null,
+      'cmd.exe /c exit 0',
+      null,
+      null,
+      1,
+      CREATE_SUSPENDED,
+      null,
+      'C:\\work',
+      expect.anything(),
+      expect.anything(),
+    )
+  })
+
+  it('restores already-enabled stdio and closes the Job when inheritance setup fails', () => {
+    let calls = 0
+    const closeHandle = vi.fn((_handle: NativePtr) => 1)
+    const setHandleInformation = vi.fn((_handle: NativePtr, _mask: number, flags: number) => {
+      if (flags === 0) return 1
+      calls += 1
+      return calls === 2 ? 0 : 1
+    })
+    const { api } = inheritedApi({ closeHandle, setHandleInformation })
+    expect(() => spawnInheritedJobProcess(api, {
+      command: 'cmd.exe',
+      args: [],
+      cwd: 'C:\\work',
+      token,
+    })).toThrow(Win32Error)
+    expect(setHandleInformation).toHaveBeenCalledWith(expect.anything(), 1, 0)
+    expect(closeHandle).toHaveBeenCalledWith(50n)
+  })
+
+  it('captures a GetStdHandle error before Job cleanup changes last-error', () => {
+    let lastError = 123
+    const { api } = inheritedApi({
+      getStdHandle: vi.fn(() => 0n as NativePtr),
+      getLastError: vi.fn(() => lastError),
+      closeHandle: vi.fn(() => { lastError = 999; return 1 }),
+    })
+    let caught: unknown
+    try {
+      spawnInheritedJobProcess(api, { command: 'cmd.exe', args: [], cwd: 'C:\\work', token })
+    } catch (error) {
+      caught = error
+    }
+    expect(caught).toMatchObject({ api: 'GetStdHandle', win32Code: 123 })
+  })
+
+  it('captures a CreateProcess error before inheritance restoration changes last-error', () => {
+    let lastError = 87
+    const { api } = inheritedApi({
+      createProcessAsUserW: vi.fn(() => 0),
+      getLastError: vi.fn(() => lastError),
+      setHandleInformation: vi.fn((_handle, _mask, flags) => {
+        if (flags === 0) lastError = 999
+        return 1
+      }),
+      closeHandle: vi.fn(() => { lastError = 998; return 1 }),
+    })
+    let caught: unknown
+    try {
+      spawnInheritedJobProcess(api, { command: 'cmd.exe', args: [], cwd: 'C:\\work', token })
+    } catch (error) {
+      caught = error
+    }
+    expect(caught).toMatchObject({ api: 'CreateProcessAsUserW', win32Code: 87 })
+  })
+
+  it('terminates the suspended process and closes the Job when CreateProcessAsUserW returns a null thread handle', () => {
+    const closeHandle = vi.fn((_handle: NativePtr) => 1)
+    const terminateProcess = vi.fn(() => 1)
+    const { api } = inheritedApi({
+      closeHandle,
+      terminateProcess,
+      createProcessAsUserW: vi.fn((_token, _app, _line, _pa, _ta, _inherit, _flags, _env, _cwd, _startup, info) => {
+        koffi.encode(info, PROCESS_INFORMATION, {
+          hProcess: 60n,
+          hThread: 0n,
+          dwProcessId: 1234,
+          dwThreadId: 0,
+        })
+        return 1
+      }),
+    })
+    expect(() => spawnInheritedJobProcess(api, {
+      command: 'cmd.exe',
+      args: [],
+      cwd: 'C:\\work',
+      token,
+    })).toThrow('null process/thread handles')
+    expect(terminateProcess).toHaveBeenCalledWith(60n, 1)
+    expect(closeHandle).toHaveBeenCalledWith(50n)
+    expect(closeHandle).toHaveBeenCalledWith(60n)
+  })
+
+})
+
+describe('wait and pipe cleanup', () => {
+  const token = 70n as NativePtr
+
+  it('waits when a pipe is temporarily empty before observing EOF', async () => {
+    const closeHandle = vi.fn(() => 1)
+    let peeks = 0
+    const api = {
+      peekNamedPipe: vi.fn((_handle, _buffer, _size, _read, available) => {
+        peeks += 1
+        if (peeks === 1) {
+          koffi.encode(available, 'uint32', 0)
+          return 1
+        }
+        return 0
+      }),
+      getLastError: vi.fn(() => 109),
+      closeHandle,
+    } as unknown as Win32ProcessBindings
+    await expect(drainPipe(api, 80n as NativePtr)).resolves.toEqual(Buffer.alloc(0))
+    expect(closeHandle).toHaveBeenCalledWith(80n)
+  })
+
+  it('terminates a piped child when CreateProcess returns a null thread handle', () => {
+    let nextPipe = 10n
+    const terminateProcess = vi.fn(() => 1)
+    const closeHandle = vi.fn(() => 1)
+    const api = {
+      createPipe: vi.fn((readSlot, writeSlot) => {
+        koffi.encode(readSlot, PVOID, nextPipe++)
+        koffi.encode(writeSlot, PVOID, nextPipe++)
+        return 1
+      }),
+      setHandleInformation: vi.fn(() => 1),
+      createProcessAsUserW: vi.fn((_token, _app, _line, _pa, _ta, _inherit, _flags, _env, _cwd, _startup, info) => {
+        koffi.encode(info, PROCESS_INFORMATION, {
+          hProcess: 60n,
+          hThread: 0n,
+          dwProcessId: 1234,
+          dwThreadId: 0,
+        })
+        return 1
+      }),
+      terminateProcess,
+      closeHandle,
+    } as unknown as Win32ProcessBindings
+    expect(() => spawnPipedProcess(api, {
+      command: 'cmd.exe',
+      args: [],
+      cwd: 'C:\\work',
+      token,
+    })).toThrow('null process/thread handles')
+    expect(terminateProcess).toHaveBeenCalledWith(60n, 1)
+  })
+})

packages/subprocess/win32-process/tests/quote.spec.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+import { buildCommandLine, quoteArg } from '../src/process.ts'
+
+const isWin32 = process.platform === 'win32'
+
+const cases: Array<[string, string]> = [
+  ['', '""'],
+  ['a', 'a'],
+  ['a b', '"a b"'],
+  ['a"b', '"a\\"b"'],
+  ['a\\b', 'a\\b'],
+  ['a b\\', '"a b\\\\"'],
+  ['a b\\\\', '"a b\\\\\\\\"'],
+  ['a\\\\"b', '"a\\\\\\\\\\"b"'],
+]
+
+describe('quoteArg', () => {
+  it.each(cases)('quotes %j as %j', (input, expected) => {
+    expect(quoteArg(input)).toBe(expected)
+  })
+
+  it('builds one CreateProcess command line without shell interpretation', () => {
+    expect(buildCommandLine('C:\\Program Files\\tool.exe', ['a b', 'c'])).toBe(
+      '"C:\\Program Files\\tool.exe" "a b" c',
+    )
+  })
+})
+
+describe.skipIf(!isWin32)('CommandLineToArgvW round-trip', () => {
+  it('parses the shared command line back to the original argv', async () => {
+    const { default: koffi } = await import('koffi')
+    const PVOID = koffi.pointer('void')
+    const shell32 = koffi.load('shell32.dll')
+    const kernel32 = koffi.load('kernel32.dll')
+    const commandLineToArgvW = shell32.func(
+      '__stdcall',
+      'CommandLineToArgvW',
+      PVOID,
+      ['str16', koffi.pointer('int')],
+    )
+    const lstrcpynW = kernel32.func('__stdcall', 'lstrcpynW', PVOID, [PVOID, PVOID, 'int'])
+    const lstrlenW = kernel32.func('__stdcall', 'lstrlenW', 'int', [PVOID])
+    const localFree = kernel32.func('__stdcall', 'LocalFree', PVOID, [PVOID])
+    const parse = (commandLine: string): string[] => {
+      const countSlot = koffi.alloc('int', 1) as unknown
+      const argvBlock = commandLineToArgvW(commandLine, countSlot) as unknown
+      try {
+        if (argvBlock === null) throw new Error('CommandLineToArgvW returned NULL')
+        const count = koffi.decode(countSlot, 0, 'int') as number
+        const table = Buffer.from(koffi.view(argvBlock, count * 8))
+        return Array.from({ length: count }, (_, index) => {
+          const stringAddress = table.readBigUInt64LE(index * 8)
+          const copied = Buffer.alloc(2048)
+          lstrcpynW(copied, stringAddress, copied.length / 2)
+          const length = lstrlenW(copied) as number
+          return copied.subarray(0, length * 2).toString('utf16le')
+        })
+      } finally {
+        localFree(argvBlock)
+      }
+    }
+    const argv = ['', 'a', 'a b', 'a"b', 'a\\b', 'a b\\', 'a b\\\\', 'a\\\\"b']
+    expect(parse(buildCommandLine('prog.exe', argv))).toEqual(['prog.exe', ...argv])
+  })
+})

packages/subprocess/win32-process/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../runtime-diagnostics/invariants"
+    }
+  ]
+}

packages/subprocess/win32-process/verify/abi-probe.cpp

@@ -0,0 +1,48 @@
+#include <Windows.h>
+#include <cstdio>
+#include <cstddef>
+
+#define P(expr) printf("%-52s = %llu\n", #expr, (unsigned long long)(expr))
+
+int wmain()
+{
+  P(sizeof(void*));
+  P(sizeof(HANDLE));
+  P(sizeof(STARTUPINFOW));
+  P(offsetof(STARTUPINFOW, dwFlags));
+  P(offsetof(STARTUPINFOW, hStdInput));
+  P(offsetof(STARTUPINFOW, hStdOutput));
+  P(offsetof(STARTUPINFOW, hStdError));
+  P(sizeof(PROCESS_INFORMATION));
+  P(offsetof(PROCESS_INFORMATION, hProcess));
+  P(offsetof(PROCESS_INFORMATION, hThread));
+  P(offsetof(PROCESS_INFORMATION, dwProcessId));
+  P(CREATE_SUSPENDED);
+  P(STARTF_USESTDHANDLES);
+  P(HANDLE_FLAG_INHERIT);
+  P(INFINITE);
+  P(STD_INPUT_HANDLE);
+  P(STD_OUTPUT_HANDLE);
+  P(STD_ERROR_HANDLE);
+  P(FORMAT_MESSAGE_FROM_SYSTEM);
+  P(FORMAT_MESSAGE_IGNORE_INSERTS);
+  P(ERROR_INSUFFICIENT_BUFFER);
+  P(ERROR_BROKEN_PIPE);
+  P(ERROR_NO_DATA);
+  P(sizeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION));
+  P(offsetof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION, BasicLimitInformation) + offsetof(JOBOBJECT_BASIC_LIMIT_INFORMATION, LimitFlags));
+  P((int)JobObjectExtendedLimitInformation);
+  P(JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE);
+
+  static_assert(sizeof(STARTUPINFOW) == 104, "STARTUPINFOW size");
+  static_assert(sizeof(PROCESS_INFORMATION) == 24, "PROCESS_INFORMATION size");
+  static_assert(CREATE_SUSPENDED == 0x4, "suspended process flag");
+  static_assert(STARTF_USESTDHANDLES == 0x100, "std handles flag");
+  static_assert(HANDLE_FLAG_INHERIT == 0x1, "inherit flag");
+  static_assert(sizeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION) == 144, "job extended limit size");
+  static_assert(offsetof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION, BasicLimitInformation) + offsetof(JOBOBJECT_BASIC_LIMIT_INFORMATION, LimitFlags) == 16, "job LimitFlags offset");
+  static_assert(JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE == 0x2000, "kill on job close flag");
+  static_assert(JobObjectExtendedLimitInformation == 9, "extended limit class");
+  printf("\nstatic_asserts passed\n");
+  return 0;
+}

pnpm-lock.yaml

@@ -6103,6 +6103,9 @@ importers:
 
   packages/sandbox/sandbox-windows-acl:
     dependencies:
+      '@deepseek-ai/dsh-win32-process':
+        specifier: workspace:^
+        version: link:../../subprocess/win32-process
       koffi:
         specifier: ^3.1.0
         version: 3.1.1
@@ -7987,6 +7990,19 @@ importers:
         specifier: workspace:^
         version: link:../../util/timeout
 
+  packages/subprocess/win32-process:
+    dependencies:
+      koffi:
+        specifier: ^3.1.0
+        version: 3.1.1
+    devDependencies:
+      '@deepseek-ai/cordis':
+        specifier: workspace:^
+        version: link:../../../vendor/cordis
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../runtime-diagnostics/invariants
+
   packages/terminal/terminal:
     devDependencies:
       '@deepseek-ai/cordis':

tsconfig.host.json

@@ -202,6 +202,7 @@
     { "path": "./packages/examples/agent-spine-demo" },
     { "path": "./packages/subprocess/subprocess" },
     { "path": "./packages/subprocess/subprocess-local" },
+    { "path": "./packages/subprocess/win32-process" },
     { "path": "./packages/e2b/e2b" },
     { "path": "./packages/e2b/subprocess-e2b" },
     { "path": "./packages/shell/shell" },