@deepseek-ai/dsh-subprocess-local 0.1.6-alpha.2 → 0.1.7-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subprocess/subprocess-local/README.md
-README.md: 24480565de2f324a451dfdb40101eb50703b30b6
-README.zh.md: c86a7eb930834d960fa25dd7b5d175af63d0b31a
+README.md: 0e5423aecd46a18cde79437ca5707be5ee58d59b
+README.zh.md: 32a1b937e5768ad87d72914fb6c8a90a33c5899f

package/README.md

@@ -44,7 +44,7 @@ Windows ordinary subprocesses start the private Job runner with `windowsHide` an
 
 ### Collecting output
 
-Collect mode keeps the last `maxBytes` of a stream in memory — errors and final results cluster at the end — and, when a `spill` cap is configured, appends the complete stream to a private file under a per-process directory in the OS temp dir (a `0700` directory, `0600` random-named files). A stream larger than the spill cap discards its incomplete spill and returns only the marked truncated tail. Reads are offset-based and non-consuming, so background and batch readers coexist before and after exit.
+Collect mode keeps the last `maxBytes` of a stream in memory — errors and final results cluster at the end — and, when a `spill` cap is configured, appends the complete stream to a private file under a per-process directory in the OS temp dir (a `0700` directory, `0600` random-named files). A stream larger than the spill cap discards its incomplete spill and returns only the marked truncated tail. Spilling is best-effort: when the spill file cannot be opened or appended (the per-process directory removed by a temporary-file cleaner, `EACCES`, `EMFILE`, `ENOSPC`), the collector discards the spill, logs one `error` through the plugin logger, and keeps collecting the in-memory tail, so the result is truncated with no spill path. Reads are offset-based and non-consuming, so background and batch readers coexist before and after exit.
 
 The `./output` export shares this collector and retained-spill storage with process adapters. `snapshot()` returns the retained raw bytes and total byte count, allowing remote adapters to preserve offsets without forwarding the complete stream.
 
@@ -109,7 +109,7 @@ A spawn synchronously validates the final argv, cwd, and environment, selects co
 
 ### Safety invariants
 
-Spill files are opened `0600` with `O_EXCL` and random names under a `0700` per-process directory, defeating symlink planting in shared temp dirs; a failed final close withholds the spill path. Fallback process identities carry start times, so cleanup never follows PID reuse. A selected native failure is reported instead of replaying argv through fallback, and a range is removed from the live set only after cleanup completes or the failure remains observable. Host-exit finalization creates no promises or timers, preserves the host exit code and diagnostic, contains each target's failure, and does not claim quiescence.
+Spill files are opened `0600` with `O_EXCL` and random names under a `0700` per-process directory, defeating symlink planting in shared temp dirs; a failed open, append, or final close withholds the spill path and never interrupts collection, because collection runs inside the stream's `'data'` listener where a thrown error would kill the host process. Fallback process identities carry start times, so cleanup never follows PID reuse. A selected native failure is reported instead of replaying argv through fallback, and a range is removed from the live set only after cleanup completes or the failure remains observable. Host-exit finalization creates no promises or timers, preserves the host exit code and diagnostic, contains each target's failure, and does not claim quiescence.
 
 </details>
 
@@ -155,6 +155,7 @@ These limits define when the provider is a poor fit or needs special operational
 - **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 (for example `*PASSPHRASE*`) pass through, and a whitelist for over-scrubbed variables is noted future work.
 - **Completed spill files are not deleted** — bounded full-output recovery files accumulate under the OS tmpdir until something external cleans them; the private per-process spill directory is removed at a JavaScript-observable exit only when it holds no completed spill file.
+- **A removed spill directory is not recreated** — the private per-process directory is created once; after an external cleaner removes it, every later spill in that process degrades to the in-memory tail with an `error` log until the host restarts. Recreating a fresh random directory on `ENOENT` is deferred work.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -44,7 +44,7 @@ Windows 普通子进程通过 `windowsHide` 启动私有 Job runner，并为原
 
 ### 收集输出
 
-收集模式在内存中保留一条流的最后 `maxBytes`——错误与最终结果通常聚集在末尾——并在配置了 `spill` 上限时把完整流追加到 OS 临时目录下每进程目录中的私有文件（`0700` 目录、`0600` 随机命名文件）。某条流大于 spill 上限时，会丢弃不完整的 spill，只返回带截断标记的尾部。读取基于偏移量且从不消费，因此后台读取与批量读取在退出前后都可以共存。
+收集模式在内存中保留一条流的最后 `maxBytes`——错误与最终结果通常聚集在末尾——并在配置了 `spill` 上限时把完整流追加到 OS 临时目录下每进程目录中的私有文件（`0700` 目录、`0600` 随机命名文件）。某条流大于 spill 上限时，会丢弃不完整的 spill，只返回带截断标记的尾部。spill 是尽力而为：当 spill 文件无法打开或追加（每进程目录被临时文件清理工具删除、`EACCES`、`EMFILE`、`ENOSPC`）时，收集器丢弃该 spill，通过插件 logger 记录一条 `error`，并继续收集内存尾部，因此结果带截断标记且没有 spill 路径。读取基于偏移量且从不消费，因此后台读取与批量读取在退出前后都可以共存。
 
 `./output` 导出向进程适配器共享该收集器与保留 spill 的存储。`snapshot()` 返回保留的原始字节及总字节数，使远程适配器能够保留偏移量，而无需转发完整的流。
 
@@ -109,7 +109,7 @@ Linux 普通进程和终端进程即使在 bootstrap 消费启动请求前被取
 
 ### 安全不变式
 
-spill 文件以 `0600` 权限、`O_EXCL` 与随机名称在 `0700` 每进程目录下创建，可抵御共享临时目录中的符号链接植入；最终关闭失败时不公布 spill 路径。fallback 进程身份携带启动时间，因此清理绝不会跟随 PID 复用。选定的 native 路径失败时会报告错误，而不会通过 fallback 重放 argv；受管范围只有在清理完成后才从存活集合移除，否则失败仍保持可观察。宿主退出最终清理不创建 Promise 或定时器，保留宿主退出码与诊断，分别包含每个目标的失败，也不会声称已经完全停稳。
+spill 文件以 `0600` 权限、`O_EXCL` 与随机名称在 `0700` 每进程目录下创建，可抵御共享临时目录中的符号链接植入；打开、追加或最终关闭失败时不公布 spill 路径，且绝不中断收集，因为收集运行在流的 `'data'` 监听器内，抛出的错误会杀死宿主进程。fallback 进程身份携带启动时间，因此清理绝不会跟随 PID 复用。选定的 native 路径失败时会报告错误，而不会通过 fallback 重放 argv；受管范围只有在清理完成后才从存活集合移除，否则失败仍保持可观察。宿主退出最终清理不创建 Promise 或定时器，保留宿主退出码与诊断，分别包含每个目标的失败，也不会声称已经完全停稳。
 
 </details>
 
@@ -155,6 +155,7 @@ spill 文件以 `0600` 权限、`O_EXCL` 与随机名称在 `0700` 每进程目
 - **进程内清理要求退出阶段仍能执行 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 owner 负责。
 - **凭据清除依赖名称启发式规则**——只匹配 `*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSPHRASE*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
 - **不会删除已完成的 spill 文件**——有界的完整输出恢复文件会在 OS tmpdir 下累积，直到外部机制进行清理；每进程私有 spill 目录仅在未持有任何已完成 spill 文件时于 JavaScript 可观察的退出阶段删除。
+- **被删除的 spill 目录不会重建**——每进程私有目录只创建一次；被外部清理工具删除后，该进程内之后的每次 spill 都降级为内存尾部并记录一条 `error`，直到宿主重启。在 `ENOENT` 时重新创建一个新的随机目录是待办工作。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -1,5 +1,5 @@
-import { C as bindManagedProcess, D as createProcessInspector, E as validateSubprocessSpec, O as controlPipe, S as loadLinuxExecve, T as spawnSubprocess, _ as parseWindowsRunnerResult, c as runnerStdio, d as cleanupLinuxLaunchFiles, l as spawnRunnerInvocation, m as deserializeRunnerError, n as WINDOWS_RUNNER_SELECTION, o as runnerEnvironment, p as createLinuxLaunchFiles, s as runnerInvocationAvailable, u as targetEnvironment, w as childEnv, y as readLinuxStartupError } from "./runner-launch-DGV26RBf.js";
-import { prepareManagedProcessBinding } from "./output.js";
+import { C as bindManagedProcess, D as createProcessInspector, E as validateSubprocessSpec, O as controlPipe, S as loadLinuxExecve, T as spawnSubprocess, _ as parseWindowsRunnerResult, c as runnerStdio, d as cleanupLinuxLaunchFiles, l as spawnRunnerInvocation, m as deserializeRunnerError, n as WINDOWS_RUNNER_SELECTION, o as runnerEnvironment, p as createLinuxLaunchFiles, s as runnerInvocationAvailable, u as targetEnvironment, w as childEnv, y as readLinuxStartupError } from "./runner-launch-B2zsQ1Dz.js";
+import { logSpillFailure, prepareManagedProcessBinding } from "./output.js";
 import { closeSync, constants, existsSync, mkdtempSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { access, stat } from "node:fs/promises";
 import { constants as constants$1, devNull, tmpdir, userInfo } from "node:os";
@@ -1294,6 +1294,8 @@ var LocalSubprocessRuntime = class extends SubprocessRuntime {
 			};
 		}, "local subprocess teardown");
 	}
+	/** Spill failures reach the plugin logger; the log line is the only trace of why a result has no spill path. */
+	reportSpillFailure = logSpillFailure(this.ctx.logger, "subprocess-local");
 	terminateForHostExit() {
 		for (const handle of this.live) try {
 			handle.terminateForHostExit();
@@ -1356,9 +1358,13 @@ var LocalSubprocessRuntime = class extends SubprocessRuntime {
 		const env = targetEnvironment(spec);
 		const containmentMode = this.selectContainmentMode("ordinary");
 		let handle;
-		if (containmentMode === "fallback") handle = spawnSubprocess(spec, this.internals);
+		const internals = {
+			...this.internals,
+			onSpillFailure: this.reportSpillFailure
+		};
+		if (containmentMode === "fallback") handle = spawnSubprocess(spec, internals);
 		else {
-			const binding = prepareManagedProcessBinding(this.internals);
+			const binding = prepareManagedProcessBinding(internals);
 			handle = bindManagedProcess(spec, containmentMode === "linux-scope" ? launchLinuxScope(spec, env) : launchWindowsJob(spec, env), binding);
 		}
 		this.live.add(handle);

package/lib/output.js

@@ -9,10 +9,13 @@ let defaultSpillDir;
 /**
 * The default spill location: a private (0700) per-process directory under
 * the OS tmpdir, created lazily. Predictable world-readable paths would let
-* other local users read command output or pre-create symlinks. At a
-* JavaScript-observable process exit the directory is removed only when it
-* holds no completed spill file (spill files are retained as full-output
-* recovery artifacts until an external cleanup).
+* other local users read command output or pre-create symlinks. The directory
+* is created once per process and never recreated: when an external
+* temporary-file cleaner removes it while empty, the next spill open fails and
+* the collector degrades to its in-memory tail. At a JavaScript-observable
+* process exit the directory is removed only when it holds no completed spill
+* file (spill files are retained as full-output recovery artifacts until an
+* external cleanup).
 */
 function privateSpillDir() {
 	defaultSpillDir ??= mkdtempSync(join(tmpdir(), "dsh-subprocess-"));
@@ -26,28 +29,62 @@ process.once("exit", () => {
 	} catch {}
 });
 /**
+* The stderr reporter used when no owner supplies one: a bare
+* {@link prepareManagedProcessBinding} caller has no plugin logger, and the
+* failure must still reach the process diagnostics.
+* @param error - the spill failure.
+* @param label - the failed stream label.
+*/
+function reportSpillFailureToStderr(error, label) {
+	process.stderr.write(`dsh-subprocess-local: ${label} spill failed; only the in-memory tail is retained: ${String(error)}\n`);
+}
+/**
+* Build the reporter an owner passes as {@link SpillOptions.onFailure}: one
+* error-level log line naming the owner and stream, with the failure appended
+* so its `code`, `syscall`, and `path` reach the log.
+* @param logger - the owner's plugin logger.
+* @param owner - the component named in the line.
+* @returns the reporter.
+*/
+function logSpillFailure(logger, owner) {
+	return (error, label) => {
+		const removedDirectory = error.code === "ENOENT";
+		logger.error(`${owner} could not write the complete ${label} stream to its spill file; the result keeps only the in-memory tail and reports no full-output path.` + (removedDirectory ? " The spill directory no longer exists; a temporary-file cleaner removing it while empty is the usual cause." : ""), error);
+	};
+}
+/**
 * Prepare fallible output storage before starting a managed native process.
-* @param internals - optional caller-owned spill directory.
+* This is the explicit resolve step for spill inputs: the spill directory
+* defaults to the private per-process directory, and the failure reporter
+* defaults to a stderr line when the caller has no logger.
+* @param internals - optional caller-owned spill directory and failure reporter.
 * @returns binding inputs whose spill directory is ready for use.
 */
 function prepareManagedProcessBinding(internals = {}) {
-	return { spillDir: internals.spillDir ?? privateSpillDir() };
+	return {
+		spillDir: internals.spillDir ?? privateSpillDir(),
+		onSpillFailure: internals.onSpillFailure ?? reportSpillFailureToStderr
+	};
 }
 /**
-* Collects one stream with a bounded in-memory tail. With a spill cap, on
+* Collects one stream with a bounded in-memory tail. With spill options, on
 * first overflow a spill file is created and every chunk (including those
 * already collected) is appended there while the full stream remains within
-* the cap; without one, only the in-memory tail is ever retained (the
+* the cap; without them, only the in-memory tail is ever retained (the
 * diagnostic-tail shape — a language server's stderr).
 *
+* Spilling is best-effort: a spill open or write failure discards the spill,
+* reports once through {@link SpillOptions.onFailure}, and never interrupts
+* in-memory collection, because `push()` runs inside the stream's `'data'`
+* listener where a thrown error would become an uncaught exception.
+*
 * Tail-keep rationale (pi/OpenCode): errors and final results cluster at the
 * end of command output; the spill file covers the head.
 */
 var OutputCollector = class {
 	maxBytes;
-	maxSpillBytes;
 	label;
-	spillDir;
+	spill;
 	chunks = [];
 	bytes = 0;
 	dropped = false;
@@ -56,12 +93,16 @@ var OutputCollector = class {
 	spillDisabled;
 	/** Total bytes ever pushed (not just retained). */
 	total = 0;
-	constructor(maxBytes, maxSpillBytes, label, spillDir) {
+	/**
+	* @param maxBytes - in-memory tail cap in bytes.
+	* @param label - stream label used in spill file names and failure reports.
+	* @param spill - spill storage; omit for tail-only collection.
+	*/
+	constructor(maxBytes, label, spill) {
 		this.maxBytes = maxBytes;
-		this.maxSpillBytes = maxSpillBytes;
 		this.label = label;
-		this.spillDir = spillDir;
-		this.spillDisabled = maxSpillBytes === void 0;
+		this.spill = spill;
+		this.spillDisabled = spill === void 0;
 	}
 	/**
 	* Ingest one stream chunk, counting it toward the whole-stream total. On
@@ -74,7 +115,8 @@ var OutputCollector = class {
 	push(chunk) {
 		this.total += chunk.length;
 		const overflows = this.bytes + chunk.length > this.maxBytes;
-		if (!this.spillDisabled && (overflows || this.spillFd !== void 0)) this.spillAll(chunk);
+		const spill = this.spill;
+		if (spill !== void 0 && !this.spillDisabled && (overflows || this.spillFd !== void 0)) this.spillAll(spill, chunk);
 		this.chunks.push(chunk);
 		this.bytes += chunk.length;
 		while (this.bytes > this.maxBytes) {
@@ -90,18 +132,34 @@ var OutputCollector = class {
 			this.dropped = true;
 		}
 	}
-	/** Open the spill file lazily and append `chunk` (and any prior chunks once). */
-	spillAll(chunk) {
-		if (this.maxSpillBytes !== void 0 && this.total > this.maxSpillBytes) {
+	/**
+	* Open the spill file lazily and append `chunk` (and any prior chunks once).
+	* Runs inside the stream's `'data'` listener, so every filesystem failure is
+	* contained here: the spill is discarded, reported once, and collection
+	* continues with the in-memory tail alone.
+	*/
+	spillAll(spill, chunk) {
+		if (this.total > spill.maxBytes) {
 			this.discardSpill();
 			return;
 		}
-		if (this.spillFd === void 0) {
-			this.spillFile = join(this.spillDir, `dsh-subprocess-${process.pid}-${++spillCounter}-${randomBytes(6).toString("hex")}-${this.label}.log`);
-			this.spillFd = openSync(this.spillFile, "wx", 384);
-			for (const prior of this.chunks) writeSync(this.spillFd, prior);
+		try {
+			if (this.spillFd === void 0) {
+				const file = join(spill.dir, `dsh-subprocess-${process.pid}-${++spillCounter}-${randomBytes(6).toString("hex")}-${this.label}.log`);
+				const fd = openSync(file, "wx", 384);
+				this.spillFile = file;
+				this.spillFd = fd;
+				for (const prior of this.chunks) writeSync(fd, prior);
+			}
+			writeSync(this.spillFd, chunk);
+		} catch (error) {
+			this.discardSpill();
+			try {
+				spill.onFailure(error, this.label);
+			} catch (reporterFailure) {
+				process.stderr.write(`dsh-subprocess-local: spill failure reporter threw: ${String(reporterFailure)}\n`);
+			}
 		}
-		writeSync(this.spillFd, chunk);
 	}
 	/** Stop spilling and remove the file once it can no longer hold the complete stream. */
 	discardSpill() {
@@ -178,4 +236,4 @@ var OutputCollector = class {
 	}
 };
 //#endregion
-export { OutputCollector, prepareManagedProcessBinding };
+export { OutputCollector, logSpillFailure, prepareManagedProcessBinding };

package/lib/{runner-launch-DGV26RBf.js → runner-launch-B2zsQ1Dz.js}

@@ -846,11 +846,11 @@ function fallbackOwner(platform, pid, child, taskkill, linuxGroupHasLiveMembers,
 * Bind platform launch facts to the existing stdio, outcome, abort, and termination lifecycle.
 * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment.
 * @param launch - platform streams, direct outcome, and managed-range owner.
-* @param internals - test-only spill-directory override.
+* @param internals - spill-directory override and spill failure reporter.
 * @returns live subprocess handle.
 */
 function bindManagedProcess(spec, launch, internals = {}) {
-	const { spillDir } = prepareManagedProcessBinding(internals);
+	const { spillDir, onSpillFailure } = prepareManagedProcessBinding(internals);
 	const { stdin, stdout, stderr } = launch;
 	const isCollect = (mode) => mode !== "pipe" && mode !== "inherit";
 	const outMode = spec.stdio.stdout;
@@ -858,7 +858,11 @@ function bindManagedProcess(spec, launch, internals = {}) {
 	const stdinMode = spec.stdio.stdin;
 	const collectStream = (mode, stream, label) => {
 		if (!isCollect(mode) || stream === null) return void 0;
-		const collector = new OutputCollector(mode.maxBytes, mode.spill?.maxBytes, label, spillDir);
+		const collector = new OutputCollector(mode.maxBytes, label, mode.spill === void 0 ? void 0 : {
+			maxBytes: mode.spill.maxBytes,
+			dir: spillDir,
+			onFailure: onSpillFailure
+		});
 		stream.on("data", (chunk) => {
 			collector.push(chunk);
 		});

package/lib/runner.js

@@ -1,4 +1,4 @@
-import { S as loadLinuxExecve, a as resolveWindowsExecutable, b as serializeRunnerError, f as consumeLinuxLaunchRequest, g as linuxLaunchFilesFromLocator, h as isWindowsTerminateRequest, i as parseRunnerTargetArgv, r as consumeRunnerSelection, t as SUBPROCESS_RUNNER_ENV, v as parseWindowsStartRequest, x as writeLinuxStartupError } from "./runner-launch-DGV26RBf.js";
+import { S as loadLinuxExecve, a as resolveWindowsExecutable, b as serializeRunnerError, f as consumeLinuxLaunchRequest, g as linuxLaunchFilesFromLocator, h as isWindowsTerminateRequest, i as parseRunnerTargetArgv, r as consumeRunnerSelection, t as SUBPROCESS_RUNNER_ENV, v as parseWindowsStartRequest, x as writeLinuxStartupError } from "./runner-launch-B2zsQ1Dz.js";
 import { closeSync } from "node:fs";
 import { SUBPROCESS_CONTROL_FD } from "@deepseek-ai/dsh-subprocess/control";
 import { Win32Error, closeHandleChecked, isJobEmpty, loadWin32ProcessBindings, pollProcessExit, spawnCurrentTokenJobProcess, terminateJob } from "@deepseek-ai/dsh-win32-process";

package/lib/types/index.d.ts

@@ -35,6 +35,8 @@ export declare class LocalSubprocessRuntime extends SubprocessRuntime {
     /** Test hook for platform process inspection; production resolves lazily on terminal spawn. */
     terminalInspector: ProcessInspector | undefined;
     constructor(ctx: Context);
+    /** Spill failures reach the plugin logger; the log line is the only trace of why a result has no spill path. */
+    private readonly reportSpillFailure;
     private terminateForHostExit;
     private disposeManagedProcesses;
     resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;

package/lib/types/output.d.ts

@@ -1,29 +1,71 @@
 import type { CollectedOutput } from '@deepseek-ai/dsh-subprocess';
+/**
+ * Receives one spill failure so the owner can log it through its own logger.
+ * Called at most once per collector, after the spill has been discarded and
+ * the in-memory tail has kept collecting. A reporter that throws is contained
+ * and its failure written to stderr.
+ * @param error - the `node:fs` failure from opening or appending the spill file.
+ * @param label - the stream label of the collector that failed.
+ */
+export type SpillFailureReporter = (error: unknown, label: string) => void;
+/** Spill storage for one collected stream; `undefined` means tail-only collection. */
+export interface SpillOptions {
+    /** Whole-stream byte cap beyond which an incomplete spill is discarded. */
+    maxBytes: number;
+    /** Private directory receiving the spill file. */
+    dir: string;
+    /** Owner-side report of a spill open or write failure. */
+    onFailure: SpillFailureReporter;
+}
+/**
+ * Build the reporter an owner passes as {@link SpillOptions.onFailure}: one
+ * error-level log line naming the owner and stream, with the failure appended
+ * so its `code`, `syscall`, and `path` reach the log.
+ * @param logger - the owner's plugin logger.
+ * @param owner - the component named in the line.
+ * @returns the reporter.
+ */
+export declare function logSpillFailure(logger: {
+    error(message: string, ...detail: unknown[]): void;
+}, owner: string): SpillFailureReporter;
+/** Inputs a managed native process needs before its output streams are bound. */
+export interface ManagedProcessBinding {
+    /** Directory receiving spill files. */
+    spillDir: string;
+    /** Receives a spill open or write failure. */
+    onSpillFailure: SpillFailureReporter;
+}
 /**
  * Prepare fallible output storage before starting a managed native process.
- * @param internals - optional caller-owned spill directory.
+ * This is the explicit resolve step for spill inputs: the spill directory
+ * defaults to the private per-process directory, and the failure reporter
+ * defaults to a stderr line when the caller has no logger.
+ * @param internals - optional caller-owned spill directory and failure reporter.
  * @returns binding inputs whose spill directory is ready for use.
  */
 export declare function prepareManagedProcessBinding(internals?: {
     spillDir?: string;
-}): {
-    spillDir: string;
-};
+    onSpillFailure?: SpillFailureReporter;
+}): ManagedProcessBinding;
 /**
- * Collects one stream with a bounded in-memory tail. With a spill cap, on
+ * Collects one stream with a bounded in-memory tail. With spill options, on
  * first overflow a spill file is created and every chunk (including those
  * already collected) is appended there while the full stream remains within
- * the cap; without one, only the in-memory tail is ever retained (the
+ * the cap; without them, only the in-memory tail is ever retained (the
  * diagnostic-tail shape — a language server's stderr).
  *
+ * Spilling is best-effort: a spill open or write failure discards the spill,
+ * reports once through {@link SpillOptions.onFailure}, and never interrupts
+ * in-memory collection, because `push()` runs inside the stream's `'data'`
+ * listener where a thrown error would become an uncaught exception.
+ *
  * Tail-keep rationale (pi/OpenCode): errors and final results cluster at the
  * end of command output; the spill file covers the head.
  */
 export declare class OutputCollector {
     private readonly maxBytes;
-    private readonly maxSpillBytes;
     private readonly label;
-    private readonly spillDir;
+    private readonly spill;
     private chunks;
     private bytes;
     private dropped;
@@ -32,7 +74,12 @@ export declare class OutputCollector {
     private spillDisabled;
     /** Total bytes ever pushed (not just retained). */
     private total;
-    constructor(maxBytes: number, maxSpillBytes: number | undefined, label: string, spillDir: string);
+    /**
+     * @param maxBytes - in-memory tail cap in bytes.
+     * @param label - stream label used in spill file names and failure reports.
+     * @param spill - spill storage; omit for tail-only collection.
+     */
+    constructor(maxBytes: number, label: string, spill: SpillOptions | undefined);
     /**
      * Ingest one stream chunk, counting it toward the whole-stream total. On
      * first overflow of the in-memory cap a spill file is opened (when spilling
@@ -42,7 +89,12 @@ export declare class OutputCollector {
      * @param chunk - the raw bytes from one stream 'data' event.
      */
     push(chunk: Buffer): void;
-    /** Open the spill file lazily and append `chunk` (and any prior chunks once). */
+    /**
+     * Open the spill file lazily and append `chunk` (and any prior chunks once).
+     * Runs inside the stream's `'data'` listener, so every filesystem failure is
+     * contained here: the spill is discarded, reported once, and collection
+     * continues with the in-memory tail alone.
+     */
     private spillAll;
     /** Stop spilling and remove the file once it can no longer hold the complete stream. */
     private discardSpill;

package/lib/types/spawn.d.ts

@@ -10,6 +10,7 @@
 import { type ChildProcess, type SpawnOptions } from 'node:child_process';
 import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
 import type { ManagedProcessLaunch } from './managed-owner.ts';
+import { type SpillFailureReporter } from './output.ts';
 type SpawnProcess = (program: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
 /**
  * Build a child environment: explicit caller entries override the scrubbed
@@ -26,6 +27,8 @@ export interface SpawnInternals {
     spawn?: SpawnProcess;
     /** Directory for spill files (defaults to the OS temp dir). */
     spillDir?: string;
+    /** Receives spill open/write failures; the runtime supplies its plugin logger, bare callers get a stderr line. */
+    onSpillFailure?: SpillFailureReporter;
     /** Windows tree-termination runner (defaults to `taskkill /PID <pid> /T /F`). */
     taskkill?: (pid: number) => void;
     /** Host platform override for signalling decisions. */
@@ -68,10 +71,10 @@ export declare function validateSubprocessSpec(spec: SubprocessSpawnSpec): void;
  * Bind platform launch facts to the existing stdio, outcome, abort, and termination lifecycle.
  * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment.
  * @param launch - platform streams, direct outcome, and managed-range owner.
- * @param internals - test-only spill-directory override.
+ * @param internals - spill-directory override and spill failure reporter.
  * @returns live subprocess handle.
  */
-export declare function bindManagedProcess(spec: SubprocessSpawnSpec, launch: ManagedProcessLaunch, internals?: Pick<SpawnInternals, 'spillDir'>): LocalSubprocessHandle;
+export declare function bindManagedProcess(spec: SubprocessSpawnSpec, launch: ManagedProcessLaunch, internals?: Pick<SpawnInternals, 'spillDir' | 'onSpillFailure'>): LocalSubprocessHandle;
 /**
  * Spawn one detached PGID/taskkill fallback and bind the common lifecycle.
  * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment.

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.6-alpha.2",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -39,21 +39,21 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.6-alpha.2"
+    "@deepseek-ai/dsh-timeout": "0.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-subprocess": "0.1.7-alpha.2"
   },
   "dependencies": {
     "koffi": "^3.1.0",
     "node-pty": "1.2.0-beta.15",
-    "@deepseek-ai/dsh-lazy-require": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-win32-process": "^0.1.6-alpha.2"
+    "@deepseek-ai/dsh-win32-process": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-lazy-require": "0.1.7-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-loader-smoke": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.6-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-loader-smoke": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-timeout": "0.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "scripts": {
     "postinstall": "node scripts/ensure-spawn-helper.mjs"