@deepseek-ai/dsh-subprocess-local 0.1.2-alpha.5 → 0.1.3-alpha.2

package/lib/types/runner-protocol.d.ts

@@ -0,0 +1,109 @@
+/** Closed private transports shared by the native subprocess runner. */
+/** Target state restored by the Linux bootstrap after systemd establishes the scope. */
+export interface LinuxLaunchRequest {
+    cwd: string;
+    env: Record<string, string>;
+}
+/** Bounded Node-shaped error fields allowed across a private runner boundary. */
+export interface SerializedRunnerError {
+    name: string;
+    message: string;
+    code?: string;
+    syscall?: string;
+    path?: string;
+}
+/** A Linux pre-exec failure published beside its consumed request. */
+export type LinuxStartupError = {
+    type: 'error';
+    error: SerializedRunnerError;
+};
+/** The only parent-to-runner start message on Windows. */
+export interface WindowsStartRequest {
+    type: 'start';
+    cwd: string;
+    env: Record<string, string>;
+}
+/** The only parent-to-runner control message on Windows. */
+export interface WindowsTerminateRequest {
+    type: 'terminate';
+}
+/** Exactly one direct-result branch is sent by a connected Windows runner. */
+export type WindowsRunnerResult = {
+    type: 'target-exit';
+    exitCode: number;
+} | {
+    type: 'error';
+    error: SerializedRunnerError;
+};
+/** Private paths owned by one Linux ordinary or PTY spawn. */
+export interface LinuxLaunchFiles {
+    directory: string;
+    requestPath: string;
+    startupErrorPath: string;
+}
+/**
+ * Create a private 0700 directory and one complete 0600 launch request.
+ * @param request - target cwd and complete environment for the bootstrap.
+ * @returns private paths owned by this launch.
+ */
+export declare function createLinuxLaunchFiles(request: LinuxLaunchRequest): LinuxLaunchFiles;
+/**
+ * Derive the only permitted startup-error path from an absolute request locator.
+ * @param requestPath - absolute path to the private launch-request file.
+ * @returns validated sibling paths for this launch.
+ */
+export declare function linuxLaunchFilesFromLocator(requestPath: string): LinuxLaunchFiles;
+/**
+ * Strictly read and remove a one-shot Linux launch request.
+ * @param requestPath - private launch-request path to consume.
+ * @returns validated target cwd and environment.
+ */
+export declare function consumeLinuxLaunchRequest(requestPath: string): LinuxLaunchRequest;
+/**
+ * Publish one strict 0600 Linux pre-exec error.
+ * @param files - private paths for this launch.
+ * @param error - bounded spawn or runner failure to publish.
+ */
+export declare function writeLinuxStartupError(files: LinuxLaunchFiles, error: LinuxStartupError): void;
+/**
+ * Read the Linux pre-exec error, if the bootstrap published one.
+ * @param path - expected startup-error path.
+ * @returns the validated failure, or undefined when none was published.
+ */
+export declare function readLinuxStartupError(path: string): LinuxStartupError | undefined;
+/**
+ * Strictly parse the single Windows start message.
+ * @param value - untrusted IPC payload.
+ * @returns validated target start request.
+ */
+export declare function parseWindowsStartRequest(value: unknown): WindowsStartRequest;
+/**
+ * Return true only for the exact, payload-free Windows terminate control.
+ * @param value - untrusted IPC payload.
+ * @returns whether the payload is the exact terminate request.
+ */
+export declare function isWindowsTerminateRequest(value: unknown): value is WindowsTerminateRequest;
+/**
+ * Strictly parse one of the two Windows direct-result branches.
+ * @param value - untrusted IPC payload.
+ * @returns validated direct-result message.
+ */
+export declare function parseWindowsRunnerResult(value: unknown): WindowsRunnerResult;
+/**
+ * Convert an unknown failure into the bounded cross-process error record.
+ * @param error - failure caught at the process boundary.
+ * @returns bounded serializable error fields.
+ */
+export declare function serializeRunnerError(error: unknown): SerializedRunnerError;
+/**
+ * Rebuild a Node-shaped Error from a strict runner record.
+ * @param serialized - validated bounded error fields.
+ * @returns reconstructed Error with supported Node fields.
+ */
+export declare function deserializeRunnerError(serialized: SerializedRunnerError): Error;
+/**
+ * Best-effort removal of only the private paths created for this Linux spawn.
+ * @param files - exact private paths owned by this launch.
+ */
+export declare function cleanupLinuxLaunchFiles(files: LinuxLaunchFiles): void;
+//# sourceMappingURL=runner-protocol.d.ts.map

package/lib/types/spawn-runner.d.ts

@@ -0,0 +1,36 @@
+/** One-shot Linux exec bootstrap and Windows Job-owning subprocess runner. */
+import { closeHandleChecked, isJobEmpty, pollProcessExit, spawnCurrentTokenJobProcess, terminateJob } from '@deepseek-ai/dsh-win32-process';
+import type { CurrentTokenProcessBindings } from '@deepseek-ai/dsh-win32-process';
+import { resolveWindowsExecutable } from './runner-launch.ts';
+type RunnerHost = Pick<NodeJS.Process, 'env' | 'exitCode' | 'connected' | 'cwd' | 'chdir' | 'on' | 'off' | 'once' | 'disconnect'> & {
+    send?: NodeJS.Process['send'];
+};
+/** Injectable operations used by the protocol-owner tests. */
+export interface SpawnRunnerInternals {
+    execve(file: string, argv: string[], env: Record<string, string>): never;
+    loadWin32ProcessBindings(): CurrentTokenProcessBindings;
+    spawnCurrentTokenJobProcess: typeof spawnCurrentTokenJobProcess;
+    closeFileDescriptor(fileDescriptor: number): void;
+    resolveWindowsExecutable: typeof resolveWindowsExecutable;
+    pollProcessExit: typeof pollProcessExit;
+    isJobEmpty: typeof isJobEmpty;
+    terminateJob: typeof terminateJob;
+    closeHandleChecked: typeof closeHandleChecked;
+}
+/**
+ * Execute the selected Linux bootstrap or Windows Job runner.
+ * @param selection - Windows sentinel or Linux launch-request locator.
+ * @param argv - private runner arguments beginning with the target delimiter.
+ * @param host - process transport and lifecycle host.
+ * @param internals - native and filesystem operations used by the runner.
+ */
+export declare function runSpawnRunner(selection: string, argv: readonly string[], host?: RunnerHost, internals?: SpawnRunnerInternals): Promise<void>;
+/**
+ * Best-effort reporting for failures before the selected runner established its owner.
+ * @param selection - Windows sentinel, Linux launch-request locator, or no selection.
+ * @param error - failure raised before normal runner settlement.
+ * @param host - process transport and lifecycle host.
+ */
+export declare function reportSpawnRunnerFailure(selection: string | undefined, error: unknown, host?: RunnerHost): Promise<void>;
+export {};
+//# sourceMappingURL=spawn-runner.d.ts.map

package/lib/types/spawn.d.ts

@@ -1,12 +1,16 @@
 /**
- * Process plumbing for the local subprocess service: detached process-tree
- * spawn with per-stream stdio dispositions, tail-keep collection with spill
- * files, tree-scoped signalling (POSIX groups; Windows taskkill), and the
- * SIGTERM→SIGKILL escalation. This layer reacts to an abort signal; callers
- * own deadlines, teardown ladders, and cause classification.
+ * Process plumbing for the local subprocess service: ordinary process launch
+ * with per-stream stdio dispositions, tail-keep collection with spill
+ * files, provider-owned range signalling, and common termination scheduling.
+ * POSIX owners stage TERM before KILL; Windows owners terminate immediately.
+ * This layer reacts to an abort signal; callers own deadlines, teardown
+ * ladders, and cause classification.
  * @module dsh-subprocess-local/spawn
  */
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
 import type { CollectedOutput, SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import type { ManagedProcessLaunch } from './managed-owner.ts';
+type SpawnProcess = (program: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
 /**
  * Build a child environment: explicit caller entries override the scrubbed
  * parent base using the target platform's environment-key semantics. A string
@@ -16,8 +20,10 @@ import type { CollectedOutput, SubprocessHandle, SubprocessSpawnSpec } from '@de
  * @returns the environment to hand to `spawn` for the child process.
  */
 export declare function childEnv(extra?: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv;
-/** Injectable knobs so tests can exercise spill and platform behavior deterministically. */
+/** Injectable process, spill, and platform operations. */
 export interface SpawnInternals {
+    /** Process spawner (defaults to `node:child_process` `spawn`). */
+    spawn?: SpawnProcess;
     /** Directory for spill files (defaults to the OS temp dir). */
     spillDir?: string;
     /** Windows tree-termination runner (defaults to `taskkill /PID <pid> /T /F`). */
@@ -36,6 +42,14 @@ export interface LocalSubprocessHandle extends SubprocessHandle {
     /** Force-terminate the current tree synchronously without starting timers or waits. */
     terminateForHostExit(): void;
 }
+/**
+ * Prepare fallible output storage before starting a managed native process.
+ * @param internals - optional caller-owned spill directory.
+ * @returns binding inputs whose spill directory is ready for use.
+ */
+export declare function prepareManagedProcessBinding(internals?: Pick<SpawnInternals, 'spillDir'>): {
+    spillDir: string;
+};
 /**
  * Collects one stream with a bounded in-memory tail. With a spill cap, on
  * first overflow a spill file is created and every chunk (including those
@@ -104,27 +118,39 @@ export declare class OutputCollector {
 /**
  * Send `sig` to a detached POSIX process group. Never throws: delivery races
  * process exit and may run in a timer callback, so failures are contained and
- * a non-positive pid is a no-op.
- * @param pid - the group leader's pid; non-positive means the spawn failed and the call is a no-op.
+ * a missing pid is a no-op.
+ * @param pid - the group leader's pid, when the spawn published one.
  * @param sig - the signal to deliver to the whole group.
  */
-export declare function killGroup(pid: number, sig: NodeJS.Signals): void;
+export declare function killGroup(pid: number | undefined, sig: NodeJS.Signals): void;
 /**
  * Terminate one Windows process tree with `taskkill /T /F`. Contained like
  * POSIX group signalling — delivery races tree exit, so an absent tree, a
  * nonzero status, or a missing taskkill binary must not break idempotent
  * teardown.
- * @param pid - root process id; non-positive is a no-op.
+ * @param pid - root process id, when the spawn published one.
+ */
+export declare function taskkillProcessTree(pid: number | undefined): void;
+/**
+ * Validate the synchronous portion of one ordinary spawn request.
+ * @param spec - exact target request.
+ * @throws when grace, cancellation, or argv is invalid before launch.
+ */
+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.
+ * @returns live subprocess handle.
  */
-export declare function taskkillProcessTree(pid: number): void;
+export declare function bindManagedProcess(spec: SubprocessSpawnSpec, launch: ManagedProcessLaunch, internals?: Pick<SpawnInternals, 'spillDir'>): LocalSubprocessHandle;
 /**
- * Spawn one isolated detached process tree with the spec's per-stream stdio
- * dispositions. Runtime exits resolve `done` as {@link SubprocessOutcome};
- * only spawn failures reject.
+ * Spawn one detached PGID/taskkill fallback and bind the common lifecycle.
  * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment.
  * @param internals - test-only spill-directory, platform, and taskkill overrides.
  * @returns live subprocess handle.
- * @throws when `graceMs` cannot be represented by one Node timer.
  */
 export declare function spawnSubprocess(spec: SubprocessSpawnSpec, internals?: SpawnInternals): LocalSubprocessHandle;
+export {};
 //# sourceMappingURL=spawn.d.ts.map

package/lib/types/terminal.d.ts

@@ -2,9 +2,11 @@
 import { PassThrough } from 'node:stream';
 import type { IPty } from 'node-pty';
 import type { SubprocessOutcome, SubprocessTerminalForeground, SubprocessTerminalHandle, SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess';
+import type { BoundProcessOwner } from './managed-owner.ts';
 import type { ProcessInspector } from './process-inspector.ts';
 /**
- * A local terminal whose process-session ownership stays below the PTY backend.
+ * A local terminal whose native managed range or fallback process-session
+ * ownership stays below the PTY backend.
  * The seam's terminate() promise — no write, inspection, or signal in flight
  * after settlement — holds here without operation tracking only because every
  * handle call completes synchronously under the hood (node-pty write, ps-based
@@ -16,6 +18,8 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
     private readonly inspector;
     private readonly graceMs;
     private readonly platform;
+    private readonly managedOwner?;
+    private readonly resolveManagedOutcome?;
     readonly pid: number;
     readonly output: PassThrough;
     readonly done: Promise<SubprocessOutcome>;
@@ -23,6 +27,7 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
     private readonly dataDisposable;
     private readonly exitDisposable;
     private cleanup;
+    private managedOwnerCleaned;
     private exited;
     private trackedDescendants;
     /** The spawned shell's start identity; scans stop adopting members once the root pid no longer carries it. */
@@ -33,7 +38,9 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
      * @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, platform?: NodeJS.Platform);
+    constructor(terminal: IPty, inspector: ProcessInspector, graceMs: number, platform?: NodeJS.Platform, managedOwner?: BoundProcessOwner | undefined, resolveManagedOutcome?: ((outcome: SubprocessOutcome) => SubprocessOutcome) | undefined);
+    /** Whether node-pty has not yet published the top-level exit event. */
+    get running(): boolean;
     write(data: string): Promise<void>;
     inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
     signalForeground(signal: SubprocessTerminalSignal): Promise<number>;
@@ -55,6 +62,8 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
     private stopShellWindows;
     private waitForWindowsShellExit;
     private closeOnce;
+    private cleanupManagedOwner;
+    private closeManagedRange;
     private settleExitIfGone;
 }
 //# sourceMappingURL=terminal.d.ts.map

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

@@ -0,0 +1,30 @@
+/** Windows parent-side launch and ownership for the private Job runner. */
+import { spawn } from 'node:child_process';
+import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import { loadWin32ProcessBindings, probeCurrentTokenJobSupport } from '@deepseek-ai/dsh-win32-process';
+import type { ManagedProcessLaunch } from './managed-owner.ts';
+import type { RunnerInvocation } from './runner-launch.ts';
+/** Test seams for runner launch and dynamic capability checks. */
+export interface WindowsJobInternals {
+    spawn?: typeof spawn;
+    runnerInvocation?: RunnerInvocation;
+    resolveRunnerInvocation?: () => RunnerInvocation;
+    runnerAvailable?: (invocation: RunnerInvocation) => boolean;
+    loadWin32ProcessBindings?: typeof loadWin32ProcessBindings;
+    probeCurrentTokenJobSupport?: typeof probeCurrentTokenJobSupport;
+}
+/**
+ * Re-check the runner entry, bindings, and current Job capability for every spawn.
+ * @param internals - optional runner and Win32 capability seams used by tests.
+ * @returns whether the Windows native containment path is currently available.
+ */
+export declare function probeWindowsJob(internals?: WindowsJobInternals): boolean;
+/**
+ * Launch one target through a runner that uniquely owns its Job handle.
+ * @param spec - ordinary target request.
+ * @param targetEnv - validated complete target environment.
+ * @param internals - optional runner launch seams used by tests.
+ * @returns direct streams, result, and runner-owned managed range.
+ */
+export declare function launchWindowsJob(spec: SubprocessSpawnSpec, targetEnv: Record<string, string>, internals?: WindowsJobInternals): ManagedProcessLaunch;
+//# sourceMappingURL=windows-job.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.2-alpha.5",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -18,28 +18,35 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./runner": {
+      "types": "./lib/types/bin.d.ts",
+      "default": "./lib/runner.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
+    "lib/runner.js",
+    "lib/runner-*.js",
     "scripts/ensure-spawn-helper.mjs",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.5",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.5"
+    "@deepseek-ai/dsh-subprocess": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.3-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
     "koffi": "^3.1.0",
-    "node-pty": "1.2.0-beta.15"
+    "node-pty": "1.2.0-beta.15",
+    "@deepseek-ai/dsh-win32-process": "^0.1.3-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-loader-smoke": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-loader-smoke": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.3-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "scripts": {