@deepseek-ai/dsh-subprocess-local 0.1.0-rc.7 → 0.1.0-rc.8

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subprocess/subprocess-local/README.md
-README.md: a88eab6776c7259bb8ee8fdad2d6002d8f57e133
-README.zh.md: ce088557875daceb5643f13bef78d6ea9a61e12f
+README.md: 0935bb309bd10dec7503a74708a28442223bf296
+README.zh.md: e2e6c67e4dbe1890bcb5532594a62b650bfed85d

package/README.md

@@ -11,7 +11,7 @@ Local Service Provider for the [`@deepseek-ai/dsh-subprocess`](../subprocess/REA
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
 - **Executable lookup** — `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions; relative paths containing separators are rejected at the seam, and relative PATH entries resolve from the host process cwd.
-- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
+- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. On Windows the koffi-backed inspector enumerates the process table through Toolhelp32, combines GetProcessTimes start identities with zero-time process-handle waits for liveness, reports the shell pid as the pseudo foreground group (Windows has no POSIX groups), and teardown verifies the shell's termination because externally taskkilled shells may never fire node-pty's exit notification. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles so its own disposal can escalate every running tree and await its exit; quiescent and spawn-failed handles leave the live set after whole-tree or terminal-session cleanup finishes.
 - **Synchronous host-exit finalization** — while the service effect is active, a Node `exit` listener force-terminates every ordinary tree and observable terminal session still in the same live sets. The local-only operations send POSIX SIGKILL to the managed group, run Windows `taskkill /T /F`, and synchronously signal captured/current terminal identities around the PTY root kill; they create no promise or timer, preserve the host's exit code and diagnostic, contain each target's failure, and do not claim quiescence. Normal disposal keeps the awaited graceful path above. See the [host-exit cleanup decision](../../../.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.md).
 
@@ -26,7 +26,7 @@ No direct invalidation; the named consumers own any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **Windows tree support is best-effort** — termination routes through `taskkill /PID <pid> /T /F` with all outcomes contained (absent tree, races, missing binary), and liveness falls back to the direct-child boundary.
-- **Terminal process inspection is Linux/macOS only** — the terminal primitive fails when its inspector has no supported platform implementation; Linux exact probes cover x64 and arm64, while macOS uses `ps` snapshots.
+- **Windows terminal signalling is console-wide** — SIGINT is delivered as a `\x03` Ctrl-C input write that conhost turns into a console-wide CTRL_C event; SIGTSTP and SIGHUP are rejected as unavailable; a `taskkill` without `/F` does not terminate console processes, so the teardown TERM tier is a grace wait before the `/F` escalation. Windows readiness has no exact stdin-wait tier: the prompt-marker fast path compares the shell pid as the pseudo foreground group, and silence/timing tiers cover the rest.
 - **A daemonized terminal descendant can still escape the observable boundary** — on macOS, a child that reparents before any foreground-inspection snapshot is no longer discoverable from the `node-pty` root; on Linux, a child that calls `setsid` leaves both the tree and owned terminal session. The local provider does not add a continuous process-table monitor.
 - **In-process cleanup requires a JavaScript-observable exit** — direct `process.exit()`, default uncaught exceptions, and default unhandled rejections emit Node's synchronous `exit` event. The default OS disposition for an unhandled `SIGTERM`, `SIGINT`, or `SIGHUP` bypasses that event; an application covers those signals only by installing a handler that performs normal disposal or calls `process.exit()`. `SIGKILL`, fatal OOM, `process.abort()`, native crashes, power loss, and any failure that cannot run JavaScript require an external supervisor, container init, or equivalent OS owner.
 - **The credential scrub is a name heuristic** — `*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSPHRASE*`) pass through, and a whitelist for over-scrubbed vars is noted future work.

package/README.zh.md

@@ -11,7 +11,7 @@
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 - **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
 - **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；含分隔符的相对路径在该 seam 处被拒绝，相对 PATH 条目从宿主进程 cwd 解析。
-- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
+- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。在 Windows 上，基于 koffi 的检查器通过 Toolhelp32 枚举进程表，把 GetProcessTimes 启动身份与进程句柄零时等待结合起来判断存活状态，并把 shell pid 作为伪前台进程组（Windows 没有 POSIX 进程组）。拆卸会验证 shell 已终止，因为被外部 taskkill 的 shell 可能永远不会触发 node-pty 的退出通知。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
 - **先终止再等待退出的 dispose（资源释放）**：服务保留存活句柄，使自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；完全停稳与 spawn 失败的句柄会在整棵进程树或 terminal session 清理完成后离开存活集合。
 - **同步宿主退出最终清理**：服务 effect 仍有效时，Node `exit` listener 会强制终止同一组存活集合中仍存在的每棵普通进程树和可观察 terminal session。这些仅供本地实现使用的操作会向受管 POSIX 进程组发送 SIGKILL、在 Windows 运行 `taskkill /T /F`，并在终止 PTY root 前后同步向已捕获及当前可观察的 terminal 身份发送信号；它们不会创建 Promise 或 timer，不改变宿主退出码与诊断，会分别包含每个目标的失败，也不会声称已经完全停稳。正常 dispose 仍使用上面的须等待温和路径。参见[宿主退出清理决策](../../../.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.md)。
 
@@ -26,7 +26,7 @@
 ## 已知限制与暂缓事项
 
 - **Windows 进程树支持仅为尽力而为**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界。
-- **终端进程检查仅支持 Linux／macOS**：检查器没有受支持的平台实现时，终端原语会失败；Linux 精确探针覆盖 x64 与 arm64，macOS 则使用 `ps` 快照。
+- **Windows 终端信号是控制台级的**：SIGINT 以 `\x03` Ctrl-C 输入写入投递，由 conhost 转为控制台级 CTRL_C 事件；SIGTSTP 与 SIGHUP 被拒绝（不可用）；不带 `/F` 的 `taskkill` 无法终止控制台进程，因此拆卸的 TERM 档是 `/F` 升级前的宽限等待。Windows 就绪没有精确的 stdin-wait 档：prompt-marker 快路径把 shell pid 作为伪前台进程组比较，其余由静默/计时档覆盖。
 - **守护化的终端后代仍可能逃出可观察边界**：在 macOS 上，子进程如果在任何前台检查快照之前重新设定父进程，将无法再从 `node-pty` 根进程发现；在 Linux 上，调用 `setsid` 的子进程会同时离开进程树与自有终端会话。本地提供方不会新增持续进程表监视器。
 - **进程内清理要求退出阶段仍能执行 JavaScript**：直接 `process.exit()`、默认未捕获异常和默认未处理 rejection 会发出 Node 同步 `exit` 事件。未安装 handler 时，`SIGTERM`、`SIGINT` 或 `SIGHUP` 的默认 OS 处置不会发出该事件；应用只有安装执行正常 dispose 或调用 `process.exit()` 的 handler 才能覆盖这些信号。`SIGKILL`、fatal OOM、`process.abort()`、native crash、断电，以及任何无法运行 JavaScript 的故障，都需要外部 supervisor、容器 init 或等价的 OS 所有者负责。
 - **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSPHRASE*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。

package/lib/index.js

@@ -8,8 +8,256 @@ import { randomBytes } from "node:crypto";
 import { constants as constants$1, tmpdir } from "node:os";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
+import koffi from "koffi";
 import { Buffer as Buffer$1 } from "node:buffer";
 import { PassThrough } from "node:stream";
+//#region lib/types/windows-inspector.js
+/**
+* Windows process-table operations for terminal readiness, signalling, and
+* teardown: Toolhelp32 snapshot enumeration with GetProcessTimes creation-time
+* identity and process-handle wait-state liveness, the shell pid as a pseudo
+* process group (Windows has no POSIX groups), and taskkill tree signalling.
+* The koffi bindings load lazily so
+* non-Windows processes never touch Win32 libraries; all decision logic takes
+* an injectable internals boundary so suites can pin it on any host.
+* @module dsh-subprocess-local/windows-inspector
+*/
+/**
+* Walk a process table from one root in children-first order, retaining only
+* members whose start identity is readable (unreadable members are detector
+* misses, exactly like an unreadable `/proc` entry on Linux).
+* @param entries - the process table snapshot.
+* @param rootPid - the tree root to descend from.
+* @param started - creation-time identity resolver for one member.
+* @returns the root and its current transitive descendants, children first.
+*/
+function windowsProcessTree(entries, rootPid, started) {
+	const root = new Map(entries.map((entry) => [entry.pid, entry])).get(rootPid);
+	if (root === void 0) return [];
+	const byParent = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const children = byParent.get(entry.parentPid) ?? [];
+		children.push(entry);
+		byParent.set(entry.parentPid, children);
+	}
+	const visited = /* @__PURE__ */ new Set();
+	const result = [];
+	const visit = (entry) => {
+		if (visited.has(entry.pid)) return;
+		visited.add(entry.pid);
+		for (const child of byParent.get(entry.pid) ?? []) visit(child);
+		const identity = started(entry.pid);
+		if (identity !== void 0) result.push({
+			pid: entry.pid,
+			started: identity
+		});
+	};
+	visit(root);
+	return result;
+}
+/**
+* Windows {@link ProcessInspector}. The shell pid stands in for a foreground
+* process group: it is a stable pseudo-group that lets the prompt-marker
+* readiness path compare foreground identities, while every actual signal
+* targets the console-wide tree through taskkill (SIGINT is delivered by the
+* terminal handle as a `\x03` input write and never reaches this layer).
+*/
+var WindowsProcessInspector = class {
+	internals;
+	constructor(internals = defaultWindowsProcessInternals()) {
+		this.internals = internals;
+	}
+	foregroundPgid(shellPid) {
+		return shellPid;
+	}
+	isStdinWaiting(_pgid) {
+		return false;
+	}
+	processTree(rootPid) {
+		return windowsProcessTree(this.internals.snapshot(), rootPid, (pid) => this.internals.processState(pid)?.started);
+	}
+	processSession(_sessionId) {
+		return [];
+	}
+	isAlive(identity) {
+		const state = this.internals.processState(identity.pid);
+		return state?.active === true && state.started === identity.started;
+	}
+	signalGroup(pgid, signal) {
+		this.internals.taskkill(pgid, signal === "SIGKILL");
+	}
+	signalProcess(identity, signal) {
+		if (this.isAlive(identity)) this.internals.taskkill(identity.pid, signal === "SIGKILL");
+	}
+};
+/**
+* Create the Windows process inspector.
+* @param internals - injectable process operations; defaults to the koffi-backed table.
+* @returns the Windows inspector.
+*/
+function createWindowsProcessInspector(internals = defaultWindowsProcessInternals()) {
+	return new WindowsProcessInspector(internals);
+}
+/** Terminate one Windows process tree with taskkill, contained like POSIX group signalling. */
+function taskkillTree(pid, force) {
+	if (pid <= 0) return;
+	spawnSync("taskkill", [
+		"/PID",
+		String(pid),
+		"/T",
+		...force ? ["/F"] : []
+	], { stdio: "ignore" });
+}
+/**
+* True for NULL and INVALID_HANDLE_VALUE returns from Win32 handle APIs.
+* @param value - a handle as koffi may hand it back (pointer, null, or 0n).
+* @returns whether the value signals an invalid handle.
+*/
+function isInvalidHandle(value) {
+	if (value === null || value === void 0) return true;
+	const asBigInt = value;
+	return asBigInt === 0n || asBigInt === 18446744073709551615n || asBigInt === -1n;
+}
+const PVOID = koffi.pointer("void");
+/**
+* Resolve the koffi Win32 struct types once. Registration is lazy and cached
+* because koffi's type registry is global per process: test runners that
+* re-evaluate this module (a hoisted `vi.mock` re-imports the graph) must not
+* re-register the names.
+*/
+function win32Structs() {
+	if (cachedStructs !== void 0) return cachedStructs;
+	const PROCESSENTRY32W = koffi.struct("PROCESSENTRY32W", {
+		dwSize: "uint32",
+		cntUsage: "uint32",
+		th32ProcessID: "uint32",
+		th32DefaultHeapID: PVOID,
+		th32ModuleID: "uint32",
+		cCntThreads: "uint32",
+		th32ParentProcessID: "uint32",
+		pcPriClassBase: "int32",
+		dwFlags: "uint32",
+		szExeFile: koffi.array("char16", 260)
+	});
+	const FILETIME = koffi.struct("FILETIME", {
+		dwLowDateTime: "uint32",
+		dwHighDateTime: "uint32"
+	});
+	/* v8 ignore start -- a layout-mismatch guard fires only on ABI breakage; the windows-native suites exercise the real struct. */
+	if (PROCESSENTRY32W.size !== 568) throw new Error(`PROCESSENTRY32W layout mismatch: koffi computed ${PROCESSENTRY32W.size}, Windows headers say 568`);
+	/* v8 ignore stop */
+	cachedStructs = {
+		PROCESSENTRY32W,
+		FILETIME
+	};
+	return cachedStructs;
+}
+let cachedStructs;
+const TH32CS_SNAPPROCESS = 2;
+const WAIT_OBJECT_0 = 0;
+const WAIT_TIMEOUT = 258;
+let cachedBindings;
+/**
+* Resolve the lazy Win32 bindings (throws the first binding failure, fail-closed).
+* @returns the cached binding table.
+*/
+function win32Bindings() {
+	if (cachedBindings !== void 0) return cachedBindings;
+	const { PROCESSENTRY32W, FILETIME } = win32Structs();
+	const kernel32 = koffi.load("kernel32.dll");
+	const bind = (name, result, args) => kernel32.func("__stdcall", name, result, args);
+	cachedBindings = {
+		createToolhelp32Snapshot: bind("CreateToolhelp32Snapshot", PVOID, ["uint32", "uint32"]),
+		process32FirstW: bind("Process32FirstW", "int", [PVOID, koffi.pointer(PROCESSENTRY32W)]),
+		process32NextW: bind("Process32NextW", "int", [PVOID, koffi.pointer(PROCESSENTRY32W)]),
+		openProcess: bind("OpenProcess", PVOID, [
+			"uint32",
+			"int",
+			"uint32"
+		]),
+		getProcessTimes: bind("GetProcessTimes", "int", [
+			PVOID,
+			koffi.pointer(FILETIME),
+			koffi.pointer(FILETIME),
+			koffi.pointer(FILETIME),
+			koffi.pointer(FILETIME)
+		]),
+		waitForSingleObject: bind("WaitForSingleObject", "uint32", [PVOID, "uint32"]),
+		closeHandle: bind("CloseHandle", "int", [PVOID])
+	};
+	return cachedBindings;
+}
+/**
+* Allocate koffi memory as a branded {@link NativePtr}; koffi's TS types are
+* `any`, so the cast goes through `unknown` to keep the unsafe surface here.
+* @param type - the koffi type to allocate.
+* @param count - element count.
+* @returns the branded allocation pointer.
+*/
+function allocNative(type, count) {
+	return koffi.alloc(type, count);
+}
+/** Enumerate the current process table through Toolhelp32. */
+function snapshotWindowsProcesses(bindings) {
+	const { PROCESSENTRY32W } = win32Structs();
+	const snapshot = bindings.createToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0);
+	/* v8 ignore next -- an invalid snapshot for the process flag is not producible through the public API;
+	the guard mirrors POSIX's unreadable-proc tolerance and isInvalidHandle is unit-tested. */
+	if (isInvalidHandle(snapshot)) return [];
+	const entries = [];
+	try {
+		const entry = allocNative(PROCESSENTRY32W, 1);
+		koffi.encode(entry, "uint32", PROCESSENTRY32W.size);
+		let ok = bindings.process32FirstW(snapshot, entry);
+		while (ok !== 0) {
+			const record = koffi.decode(entry, PROCESSENTRY32W);
+			entries.push({
+				pid: record.th32ProcessID,
+				parentPid: record.th32ParentProcessID
+			});
+			ok = bindings.process32NextW(snapshot, entry);
+		}
+	} finally {
+		bindings.closeHandle(snapshot);
+	}
+	return entries;
+}
+/** Read one process's creation identity and current wait state. */
+function windowsProcessState(bindings, pid) {
+	const { FILETIME } = win32Structs();
+	const handle = bindings.openProcess(1052672, 0, pid);
+	if (isInvalidHandle(handle)) return void 0;
+	try {
+		const creation = allocNative(FILETIME, 1);
+		const exit = allocNative(FILETIME, 1);
+		const kernel = allocNative(FILETIME, 1);
+		const user = allocNative(FILETIME, 1);
+		/* v8 ignore next -- a GetProcessTimes failure after a successful open races process exit and
+		cannot be staged deterministically; the absent-process path is covered and the caller
+		treats undefined as a detector miss. */
+		if (bindings.getProcessTimes(handle, creation, exit, kernel, user) === 0) return void 0;
+		const record = koffi.decode(creation, FILETIME);
+		const wait = bindings.waitForSingleObject(handle, 0);
+		/* v8 ignore next -- an opened process handle has exactly one of these two
+		zero-time wait states; an unexpected Win32 failure is an unreadable process. */
+		if (wait !== WAIT_OBJECT_0 && wait !== WAIT_TIMEOUT) return void 0;
+		return {
+			started: `${record.dwHighDateTime}:${record.dwLowDateTime}`,
+			active: wait === WAIT_TIMEOUT
+		};
+	} finally {
+		bindings.closeHandle(handle);
+	}
+}
+/** The koffi-backed default internals; bindings resolve lazily on first use. */
+function defaultWindowsProcessInternals() {
+	return {
+		snapshot: () => snapshotWindowsProcesses(win32Bindings()),
+		processState: (pid) => windowsProcessState(win32Bindings(), pid),
+		taskkill: taskkillTree
+	};
+}
+//#endregion
 //#region lib/types/process-inspector.js
 /** Platform process-table inspection for terminal readiness, signals, and teardown. */
 /* v8 ignore start -- thin OS bindings; injected logic is unit-tested and real platform composition exercises them. */
@@ -295,6 +543,7 @@ var MacProcessInspector = class extends PosixProcessInspector {
 function createProcessInspector(platform = process.platform, arch = process.arch, internals = DEFAULT_INTERNALS) {
 	if (platform === "linux") return new LinuxProcessInspector(arch, internals);
 	if (platform === "darwin") return new MacProcessInspector(internals);
+	if (platform === "win32") return createWindowsProcessInspector();
 	throw new Error(`subprocess-local: terminal inspection is unsupported on platform ${platform}`);
 }
 //#endregion
@@ -724,6 +973,7 @@ var LocalTerminalHandle = class {
 	terminal;
 	inspector;
 	graceMs;
+	platform;
 	pid;
 	output = new PassThrough();
 	done;
@@ -739,11 +989,13 @@ var LocalTerminalHandle = class {
 	* @param terminal - allocated node-pty process.
 	* @param inspector - platform process/session operations.
 	* @param graceMs - TERM-to-KILL and exit-wait grace.
+	* @param platform - host platform; defaults to the running platform, injectable for deterministic tests.
 	*/
-	constructor(terminal, inspector, graceMs) {
+	constructor(terminal, inspector, graceMs, platform = process.platform) {
 		this.terminal = terminal;
 		this.inspector = inspector;
 		this.graceMs = graceMs;
+		this.platform = platform;
 		this.pid = terminal.pid;
 		this.rootIdentity = inspector.processTree(this.pid).find((member) => member.pid === this.pid);
 		this.done = this.outcome.promise;
@@ -777,6 +1029,13 @@ var LocalTerminalHandle = class {
 		const foreground = await this.inspectForeground();
 		if (foreground === void 0) throw new Error(`cannot resolve foreground process group for terminal ${this.pid}`);
 		if (signal === "SIGKILL" && foreground.processGroupId === this.pid) throw new Error("refusing to SIGKILL the terminal shell; terminate the terminal session instead");
+		if (this.platform === "win32") {
+			if (signal === "SIGINT") {
+				this.terminal.write("");
+				return foreground.processGroupId;
+			}
+			if (signal === "SIGTSTP" || signal === "SIGHUP") throw new Error(`signal ${signal} is unsupported on Windows; only SIGINT, SIGTERM, and SIGKILL are available`);
+		}
 		this.inspector.signalGroup(foreground.processGroupId, signal);
 		return foreground.processGroupId;
 	}
@@ -862,6 +1121,10 @@ var LocalTerminalHandle = class {
 		return this.survivors(this.unionMembers(survivors, this.descendants()));
 	}
 	async stopShell() {
+		if (this.platform === "win32") {
+			await this.stopShellWindows();
+			return;
+		}
 		if (!this.exited) {
 			try {
 				this.terminal.kill("SIGTERM");
@@ -876,15 +1139,54 @@ var LocalTerminalHandle = class {
 		}
 		if (!this.exited) throw new Error(`terminal cleanup failed; surviving pid: ${this.pid}`);
 	}
+	async stopShellWindows() {
+		const shellGone = () => this.exited || this.rootIdentity !== void 0 && !this.inspector.isAlive(this.rootIdentity);
+		if (!shellGone() && this.rootIdentity !== void 0) {
+			this.inspector.signalProcess(this.rootIdentity, "SIGTERM");
+			await this.waitForWindowsShellExit();
+		}
+		if (!shellGone() && this.rootIdentity === void 0) {
+			try {
+				this.terminal.kill();
+			} catch (_topLevelAlreadyExitedDuringKill) {}
+			await Promise.race([this.done.then(() => void 0), delay(this.graceMs)]);
+		}
+		if (!shellGone() && this.rootIdentity !== void 0) {
+			this.inspector.signalProcess(this.rootIdentity, "SIGKILL");
+			await this.waitForWindowsShellExit();
+		}
+		if (!shellGone()) throw new Error(`terminal cleanup failed; surviving pid: ${this.pid}`);
+	}
+	async waitForWindowsShellExit() {
+		const until = Date.now() + this.graceMs;
+		while (!this.exited && Date.now() < until) {
+			if (this.rootIdentity !== void 0 && !this.inspector.isAlive(this.rootIdentity)) return;
+			await delay(Math.min(25, Math.max(1, until - Date.now())));
+		}
+	}
 	async closeOnce() {
 		let survivors = await this.stopDescendants();
 		if (survivors.length > 0) throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map((member) => member.pid).join(", ")}`);
 		await this.stopShell();
 		survivors = await this.stopDescendants();
 		if (survivors.length > 0) throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map((member) => member.pid).join(", ")}`);
+		this.settleExitIfGone();
 		this.dataDisposable.dispose();
 		this.exitDisposable.dispose();
 	}
+	settleExitIfGone() {
+		if (this.platform !== "win32") return;
+		if (this.exited) return;
+		/* v8 ignore next -- stopShellWindows() verified the shell is gone or threw;
+		the identity re-check is a defensive fence for a future caller. */
+		if (this.rootIdentity !== void 0 && this.inspector.isAlive(this.rootIdentity)) return;
+		this.exited = true;
+		this.output.end();
+		this.outcome.resolve({
+			exitCode: null,
+			signal: null
+		});
+	}
 };
 //#endregion
 //#region lib/types/index.js

package/lib/types/terminal.d.ts

@@ -15,6 +15,7 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
     private readonly terminal;
     private readonly inspector;
     private readonly graceMs;
+    private readonly platform;
     readonly pid: number;
     readonly output: PassThrough;
     readonly done: Promise<SubprocessOutcome>;
@@ -30,8 +31,9 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
      * @param terminal - allocated node-pty process.
      * @param inspector - platform process/session operations.
      * @param graceMs - TERM-to-KILL and exit-wait grace.
+     * @param platform - host platform; defaults to the running platform, injectable for deterministic tests.
      */
-    constructor(terminal: IPty, inspector: ProcessInspector, graceMs: number);
+    constructor(terminal: IPty, inspector: ProcessInspector, graceMs: number, platform?: NodeJS.Platform);
     write(data: string): Promise<void>;
     inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
     signalForeground(signal: SubprocessTerminalSignal): Promise<number>;
@@ -50,6 +52,9 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
     private unionMembers;
     private stopDescendants;
     private stopShell;
+    private stopShellWindows;
+    private waitForWindowsShellExit;
     private closeOnce;
+    private settleExitIfGone;
 }
 //# sourceMappingURL=terminal.d.ts.map

package/lib/types/windows-inspector.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Windows process-table operations for terminal readiness, signalling, and
+ * teardown: Toolhelp32 snapshot enumeration with GetProcessTimes creation-time
+ * identity and process-handle wait-state liveness, the shell pid as a pseudo
+ * process group (Windows has no POSIX groups), and taskkill tree signalling.
+ * The koffi bindings load lazily so
+ * non-Windows processes never touch Win32 libraries; all decision logic takes
+ * an injectable internals boundary so suites can pin it on any host.
+ * @module dsh-subprocess-local/windows-inspector
+ */
+import type { SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess';
+import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts';
+/** One Toolhelp32 process-table row. */
+export interface ProcessEntry {
+    pid: number;
+    parentPid: number;
+}
+/** Creation identity plus the process object's current wait state. */
+export interface WindowsProcessState {
+    /** GetProcessTimes creation identity used to fence PID reuse. */
+    started: string;
+    /** Whether a zero-time process-handle wait reports the process still running. */
+    active: boolean;
+}
+/** Injectable Windows process operations used by one local PTY session. */
+export interface WindowsProcessInspectorInternals {
+    /** Enumerate the current process table (pid/parent pairs). */
+    snapshot(): ProcessEntry[];
+    /** Return one process's creation identity and wait state, or undefined when unreadable. */
+    processState(pid: number): WindowsProcessState | undefined;
+    /** Terminate one process tree; `force` maps to taskkill `/F`. */
+    taskkill(pid: number, force: boolean): void;
+}
+/**
+ * Walk a process table from one root in children-first order, retaining only
+ * members whose start identity is readable (unreadable members are detector
+ * misses, exactly like an unreadable `/proc` entry on Linux).
+ * @param entries - the process table snapshot.
+ * @param rootPid - the tree root to descend from.
+ * @param started - creation-time identity resolver for one member.
+ * @returns the root and its current transitive descendants, children first.
+ */
+export declare function windowsProcessTree(entries: ProcessEntry[], rootPid: number, started: (pid: number) => string | undefined): ProcessIdentity[];
+/**
+ * Windows {@link ProcessInspector}. The shell pid stands in for a foreground
+ * process group: it is a stable pseudo-group that lets the prompt-marker
+ * readiness path compare foreground identities, while every actual signal
+ * targets the console-wide tree through taskkill (SIGINT is delivered by the
+ * terminal handle as a `\x03` input write and never reaches this layer).
+ */
+export declare class WindowsProcessInspector implements ProcessInspector {
+    private readonly internals;
+    constructor(internals?: WindowsProcessInspectorInternals);
+    foregroundPgid(shellPid: number): number;
+    isStdinWaiting(_pgid: number): boolean;
+    processTree(rootPid: number): ProcessIdentity[];
+    processSession(_sessionId: number): ProcessIdentity[];
+    isAlive(identity: ProcessIdentity): boolean;
+    signalGroup(pgid: number, signal: SubprocessTerminalSignal): void;
+    signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void;
+}
+/**
+ * Create the Windows process inspector.
+ * @param internals - injectable process operations; defaults to the koffi-backed table.
+ * @returns the Windows inspector.
+ */
+export declare function createWindowsProcessInspector(internals?: WindowsProcessInspectorInternals): WindowsProcessInspector;
+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 and INVALID_HANDLE_VALUE returns from Win32 handle APIs.
+ * @param value - a handle as koffi may hand it back (pointer, null, or 0n).
+ * @returns whether the value signals an invalid handle.
+ */
+export declare function isInvalidHandle(value: NativePtr | null | undefined): boolean;
+export {};
+//# sourceMappingURL=windows-inspector.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subprocess-local",
   "description": "Local-subprocess implementation of the DeepSeek Harness subprocess seam",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
   "publishConfig": {
     "access": "public"
   },
@@ -33,20 +33,21 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.7",
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7"
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.8",
+    "@deepseek-ai/cordis": "^4.0.1"
   },
   "dependencies": {
+    "koffi": "^3.1.0",
     "node-pty": "1.2.0-beta.15"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-loader-smoke": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.7",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-loader-smoke": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.8",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.8"
   },
   "scripts": {
     "postinstall": "node scripts/ensure-spawn-helper.mjs"