@qlzt/dsh-subprocess-local 0.0.0-stage → 0.2.1-alpha.2

package/lib/runner.js

@@ -0,0 +1,436 @@
+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 "@qlzt/dsh-subprocess/control";
+import { Win32Error, closeHandleChecked, isJobEmpty, loadWin32ProcessBindings, pollProcessExit, spawnCurrentTokenJobProcess, terminateJob } from "@qlzt/dsh-win32-process";
+//#region lib/types/spawn-runner.js
+/** One-shot Linux exec bootstrap and Windows Job-owning subprocess runner. */
+const defaultInternals = {
+	/* v8 ignore next -- source/built/packaged subprocess smoke executes this only in a replaceable child process. */
+	execve: (file, argv, env, control) => loadLinuxExecve()(file, argv, env, control),
+	loadWin32ProcessBindings,
+	spawnCurrentTokenJobProcess,
+	closeFileDescriptor: closeSync,
+	resolveWindowsExecutable,
+	pollProcessExit,
+	isJobEmpty,
+	terminateJob,
+	closeHandleChecked
+};
+const NODE_SPAWN_DETAIL_CODES = new Set(["EACCES", "ENOENT"]);
+const WINDOWS_SPAWN_ERROR_CODES = new Map([
+	[2, "ENOENT"],
+	[3, "ENOENT"],
+	[267, "ENOENT"],
+	[5, "EPERM"],
+	[193, "EFTYPE"],
+	[740, "EACCES"]
+]);
+function nodeSpawnError(syscall, code, path) {
+	return {
+		name: "Error",
+		message: `${syscall} ${code}`,
+		code,
+		syscall,
+		...path === void 0 ? {} : { path }
+	};
+}
+function asSpawnError(error, program) {
+	const serialized = serializeRunnerError(error);
+	if (!(error instanceof Win32Error)) return serialized.code === void 0 ? serialized : nodeSpawnError(`spawn ${program}`, serialized.code, program);
+	const code = WINDOWS_SPAWN_ERROR_CODES.get(error.win32Code) ?? "UNKNOWN";
+	if (NODE_SPAWN_DETAIL_CODES.has(code)) return nodeSpawnError(`spawn ${program}`, code, program);
+	return nodeSpawnError("spawn", code);
+}
+function windowsPathNotFoundError(program) {
+	return nodeSpawnError(`spawn ${program}`, "ENOENT", program);
+}
+function windowsStartCancelledError() {
+	return {
+		name: "Error",
+		message: "subprocess target start was cancelled"
+	};
+}
+function linuxPathNotFoundError(program) {
+	return Object.assign(/* @__PURE__ */ new Error(`spawn ${program} ENOENT`), {
+		code: "ENOENT",
+		errno: -2,
+		syscall: `spawn ${program}`,
+		path: program,
+		spawnargs: []
+	});
+}
+function execLinuxFile(file, argv, env, internals, control) {
+	try {
+		return control === void 0 ? internals.execve(file, argv, env) : internals.execve(file, argv, env, control);
+	} catch (error) {
+		if (error.code !== "ENOEXEC") throw error;
+		return control === void 0 ? internals.execve("/bin/sh", [
+			"/bin/sh",
+			file,
+			...argv.slice(1)
+		], env) : internals.execve("/bin/sh", [
+			"/bin/sh",
+			file,
+			...argv.slice(1)
+		], env, control);
+	}
+}
+function execLinuxTarget(request, argv, internals) {
+	const program = argv[0];
+	if (program.includes("/")) return execLinuxFile(program, argv, request.env, internals, request.control);
+	const path = request.env.PATH ?? "/usr/bin:/bin";
+	let permissionFailure;
+	for (const directory of path.split(":")) {
+		const root = directory.startsWith("/") ? directory : `${request.cwd}${request.cwd.endsWith("/") ? "" : "/"}${directory}`;
+		const candidate = `${root}${root.endsWith("/") ? "" : "/"}${program}`;
+		try {
+			return execLinuxFile(candidate, argv, request.env, internals, request.control);
+		} catch (error) {
+			const code = error.code;
+			if (code === "EACCES") {
+				permissionFailure ??= error;
+				continue;
+			}
+			if (code === "ENOENT" || code === "ENOTDIR") continue;
+			throw error;
+		}
+	}
+	throw permissionFailure ?? linuxPathNotFoundError(program);
+}
+function runLinux(locator, argv, host, internals) {
+	const files = linuxLaunchFilesFromLocator(locator);
+	let request;
+	try {
+		request = consumeLinuxLaunchRequest(files.requestPath);
+	} catch (error) {
+		writeLinuxStartupError(files, {
+			type: "error",
+			error: serializeRunnerError(error)
+		});
+		host.exitCode = 127;
+		return;
+	}
+	try {
+		host.chdir(request.cwd);
+		execLinuxTarget({
+			...request,
+			cwd: host.cwd()
+		}, argv, internals);
+	} catch (error) {
+		writeLinuxStartupError(files, {
+			type: "error",
+			error: asSpawnError(error, argv[0])
+		});
+		host.exitCode = 127;
+	}
+}
+function sendMessage(host, result) {
+	return new Promise((resolve, reject) => {
+		if (!host.connected || host.send === void 0) {
+			reject(/* @__PURE__ */ new Error("subprocess runner IPC is not connected"));
+			return;
+		}
+		try {
+			host.send(result, (error) => {
+				if (error === null) resolve();
+				else reject(error);
+			});
+		} catch (error) {
+			reject(error instanceof Error ? error : new Error(String(error)));
+		}
+	});
+}
+var WindowsJobRunner = class {
+	argv;
+	host;
+	internals;
+	api;
+	processHandle;
+	jobHandle;
+	pollTimer;
+	startSeen = false;
+	terminateRequested = false;
+	resultStarted = false;
+	resultDelivered = false;
+	finished = false;
+	completion = Promise.withResolvers();
+	constructor(argv, host, internals) {
+		this.argv = argv;
+		this.host = host;
+		this.internals = internals;
+	}
+	run() {
+		if (!this.host.connected || this.host.send === void 0) {
+			this.finish(127);
+			return this.completion.promise;
+		}
+		this.host.on("message", this.onMessage);
+		this.host.once("disconnect", this.onDisconnect);
+		return this.completion.promise;
+	}
+	onMessage = (value) => {
+		if (this.finished) return;
+		if (isWindowsTerminateRequest(value)) {
+			this.requestTermination();
+			return;
+		}
+		if (this.startSeen) {
+			this.runnerFailure(/* @__PURE__ */ new Error("subprocess runner received more than one Windows start request"));
+			return;
+		}
+		let request;
+		try {
+			request = parseWindowsStartRequest(value);
+		} catch (error) {
+			this.runnerFailure(error);
+			return;
+		}
+		this.startSeen = true;
+		this.start(request);
+	};
+	onDisconnect = () => {
+		if (this.finished) return;
+		this.releaseOwnedJob();
+		this.finish(127, false);
+	};
+	async start(request) {
+		if (this.terminateRequested) {
+			await this.publishTerminalResult({
+				type: "error",
+				error: windowsStartCancelledError()
+			}, 0);
+			return;
+		}
+		await new Promise((resolveImmediate) => {
+			setImmediate(resolveImmediate);
+		});
+		if (this.finished) return;
+		if (this.terminateRequested) {
+			await this.publishTerminalResult({
+				type: "error",
+				error: windowsStartCancelledError()
+			}, 0);
+			return;
+		}
+		try {
+			const [command, ...args] = this.argv;
+			const applicationName = this.internals.resolveWindowsExecutable(command, request.cwd, request.env, void 0, { ...this.host.env });
+			if (applicationName === void 0) {
+				await this.publishTerminalResult({
+					type: "error",
+					error: windowsPathNotFoundError(command)
+				}, 0);
+				return;
+			}
+			this.api = this.internals.loadWin32ProcessBindings();
+			const spawned = this.internals.spawnCurrentTokenJobProcess(this.api, {
+				command,
+				applicationName,
+				args,
+				cwd: request.cwd,
+				env: request.env,
+				stdio: {
+					stdin: 4,
+					stdout: 5,
+					stderr: 6,
+					...request.control === "pipe" ? { control: SUBPROCESS_CONTROL_FD } : {}
+				}
+			});
+			this.processHandle = spawned.process;
+			this.jobHandle = spawned.job;
+			for (const fileDescriptor of request.control === "pipe" ? [
+				4,
+				5,
+				6,
+				SUBPROCESS_CONTROL_FD
+			] : [
+				4,
+				5,
+				6
+			]) this.internals.closeFileDescriptor(fileDescriptor);
+			this.pollTimer = setInterval(() => {
+				this.poll();
+			}, 10);
+		} catch (error) {
+			if (this.jobHandle === void 0 && error instanceof Win32Error && error.api === "CreateProcessW") {
+				await this.publishTerminalResult({
+					type: "error",
+					error: asSpawnError(error, this.argv[0])
+				}, 0);
+				return;
+			}
+			await this.runnerFailure(error);
+		}
+	}
+	requestTermination() {
+		if (this.terminateRequested) return;
+		this.terminateRequested = true;
+		try {
+			this.terminateOwnedJob();
+		} catch (error) {
+			this.runnerFailure(error);
+		}
+	}
+	terminateOwnedJob() {
+		const job = this.jobHandle;
+		if (job === void 0) return;
+		/* v8 ignore next -- a Job handle is assigned only after the bindings are loaded;
+		* the guard above is the only reachable empty-owner state. */
+		if (this.api === void 0) return;
+		this.internals.terminateJob(this.api, job, 1);
+	}
+	poll() {
+		if (this.finished) return;
+		/* v8 ignore next -- poll is installed only after start() stores the bindings; retained as a defensive invariant guard. */
+		if (this.api === void 0) return;
+		try {
+			if (this.processHandle !== void 0) {
+				const exitCode = this.internals.pollProcessExit(this.api, this.processHandle);
+				if (exitCode !== void 0) {
+					this.internals.closeHandleChecked(this.api, this.processHandle, "ordinary direct process");
+					this.processHandle = void 0;
+					this.publishTerminalResult({
+						type: "target-exit",
+						exitCode
+					});
+				}
+			}
+			if (this.jobHandle !== void 0 && this.internals.isJobEmpty(this.api, this.jobHandle)) {
+				this.internals.closeHandleChecked(this.api, this.jobHandle, "ordinary process Job");
+				this.jobHandle = void 0;
+				if (this.resultDelivered) this.finish(0);
+			}
+		} catch (error) {
+			this.runnerFailure(error);
+		}
+	}
+	async publishTerminalResult(result, exitCode) {
+		/* v8 ignore next -- each state transition has a single result call site; the guard contains only re-entrant internal defects. */
+		if (this.finished || this.resultStarted) return;
+		this.resultStarted = true;
+		try {
+			await sendMessage(this.host, result);
+			this.resultDelivered = true;
+		} catch {
+			this.releaseOwnedJob();
+			this.finish(127, false);
+			return;
+		}
+		if (exitCode !== void 0) {
+			this.finish(exitCode);
+			return;
+		}
+		if (this.jobHandle === void 0) this.finish(0);
+	}
+	async runnerFailure(error) {
+		/* v8 ignore next -- callers stop/detach on finish; this guard contains only an already-queued internal callback. */
+		if (this.finished) return;
+		if (!this.resultStarted) {
+			this.resultStarted = true;
+			try {
+				await sendMessage(this.host, {
+					type: "error",
+					error: serializeRunnerError(error)
+				});
+				this.resultDelivered = true;
+			} catch {}
+		}
+		this.releaseOwnedJob();
+		this.finish(127);
+	}
+	releaseOwnedJob() {
+		if (this.pollTimer !== void 0) clearInterval(this.pollTimer);
+		this.pollTimer = void 0;
+		const api = this.api;
+		if (api === void 0) return;
+		if (this.jobHandle !== void 0) {
+			try {
+				this.internals.terminateJob(api, this.jobHandle, 1);
+			} catch {}
+			try {
+				this.internals.closeHandleChecked(api, this.jobHandle, "ordinary process Job cleanup");
+			} catch {}
+			this.jobHandle = void 0;
+		}
+		if (this.processHandle !== void 0) {
+			try {
+				this.internals.closeHandleChecked(api, this.processHandle, "ordinary direct process cleanup");
+			} catch {}
+			this.processHandle = void 0;
+		}
+	}
+	finish(exitCode, disconnect = true) {
+		if (this.finished) return;
+		this.finished = true;
+		if (this.pollTimer !== void 0) clearInterval(this.pollTimer);
+		this.pollTimer = void 0;
+		this.host.off("message", this.onMessage);
+		this.host.off("disconnect", this.onDisconnect);
+		this.host.exitCode = exitCode;
+		if (disconnect && this.host.connected) this.host.disconnect();
+		this.completion.resolve();
+	}
+};
+/**
+* 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.
+*/
+async function runSpawnRunner(selection, argv, host = process, internals = defaultInternals) {
+	Reflect.deleteProperty(host.env, SUBPROCESS_RUNNER_ENV);
+	const targetArgv = parseRunnerTargetArgv(argv);
+	if (selection === "windows") {
+		await new WindowsJobRunner(targetArgv, host, internals).run();
+		return;
+	}
+	runLinux(selection, targetArgv, host, internals);
+}
+/**
+* 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.
+*/
+async function reportSpawnRunnerFailure(selection, error, host = process) {
+	if (selection === "windows") {
+		try {
+			await sendMessage(host, {
+				type: "error",
+				error: serializeRunnerError(error)
+			});
+		} catch {}
+		host.exitCode = 127;
+		if (host.connected) host.disconnect();
+		return;
+	}
+	if (selection !== void 0) try {
+		writeLinuxStartupError(linuxLaunchFilesFromLocator(selection), {
+			type: "error",
+			error: serializeRunnerError(error)
+		});
+	} catch {}
+	host.exitCode = 127;
+}
+//#endregion
+//#region lib/types/bin.js
+/** Thin executable/importable entry for the provider-private runner core. */
+/**
+* Run a selector already removed by a packaging bootstrap.
+* @param selection - private runner selector or Linux launch-request locator.
+*/
+async function runSelectedSubprocessRunner(selection) {
+	try {
+		await runSpawnRunner(selection, process.argv.slice(2));
+	} catch (error) {
+		await reportSpawnRunnerFailure(selection, error);
+	}
+}
+if (import.meta.main) {
+	const selection = consumeRunnerSelection();
+	if (selection === void 0) process.exitCode = 127;
+	else runSelectedSubprocessRunner(selection);
+}
+//#endregion
+export { runSelectedSubprocessRunner };

package/lib/types/bin.d.ts

@@ -0,0 +1,7 @@
+/** Thin executable/importable entry for the provider-private runner core. */
+/**
+ * Run a selector already removed by a packaging bootstrap.
+ * @param selection - private runner selector or Linux launch-request locator.
+ */
+export declare function runSelectedSubprocessRunner(selection: string): Promise<void>;
+//# sourceMappingURL=bin.d.ts.map

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

@@ -0,0 +1,19 @@
+/** Parent-side setup for one explicitly requested inherited control pipe. */
+import type { Duplex, Readable, Writable } from 'node:stream';
+/**
+ * Read the optional extra pipe from Node's stdio tuple.
+ * @param child - child whose requested extra pipe was allocated by Node.
+ * @param control - requested transport, or undefined when absent.
+ * @returns the parent duplex endpoint, absent when not requested or native startup failed.
+ */
+export declare function controlPipe(child: {
+    readonly stdio: ReadonlyArray<Readable | Writable | null | undefined>;
+}, control?: 'pipe'): Duplex | undefined;
+/**
+ * Stamp the private marker on a fresh child environment after rejecting a caller override.
+ * @param env - newly materialized child environment, owned by the caller.
+ * @param control - requested control transport, or undefined when absent.
+ * @returns the same environment with the provider-owned launch marker when requested.
+ */
+export declare function controlEnvironment<T extends NodeJS.ProcessEnv>(env: T, control?: 'pipe'): T;
+//# sourceMappingURL=control-spawn.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Local Service Provider for the subprocess capability seam. Each spawn owns a
+ * platform-selected managed range with the spec's per-stream stdio dispositions.
+ * Normal disposal terminates and joins live ranges; Node's synchronous exit
+ * phase force-stops any ranges the service still owns. It has no config: every
+ * disposition and limit arrives on the spec, so deployment-varying choices
+ * stay with the caller's config (the bash executor's, the LSP host's, …).
+ * @module @qlzt/dsh-subprocess-local
+ */
+import { Context } from '@deepseek-ai/cordis';
+import { SubprocessRuntime } from '@qlzt/dsh-subprocess';
+import type { SubprocessHandle, SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalEnvironment, SubprocessTerminalSpawnSpec } from '@qlzt/dsh-subprocess';
+import type { SpawnInternals } from './spawn.ts';
+import type { ProcessInspector } from './process-inspector.ts';
+/**
+ * Local subprocess service: platform-selected managed ranges, Node-shaped stdio
+ * dispositions (raw pipes, inherit, bounded tail-keep collection with spill
+ * files), credential-scrubbed environment, and provider-owned range signalling.
+ * POSIX paths stage TERM before KILL; Windows paths terminate immediately.
+ * JavaScript-observable host exit also performs synchronous final termination.
+ */
+export declare class LocalSubprocessRuntime extends SubprocessRuntime {
+    /** Live handles retained for normal disposal and synchronous host-exit finalization. */
+    private live;
+    /** Live terminals retained through normal quiescence or host-exit finalization. */
+    private terminals;
+    /** Caller endpoints retained until close, independently of managed process lifetime. */
+    private controlChannels;
+    /** Test hook: process, spill, and platform operations forwarded to spawnSubprocess. */
+    internals: SpawnInternals;
+    /** Provider-lifetime latch suppressing repeated weaker-containment warnings. */
+    private fallbackWarningIssued;
+    /** Positive-only cache for the expensive Linux bootstrap and scope probe. */
+    private linuxDeepProbePassed;
+    /** 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>;
+    private executableCandidates;
+    spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+    private selectContainmentMode;
+    private warnFallback;
+    /** @inheritdoc */
+    terminalEnvironment(signal?: AbortSignal): Promise<SubprocessTerminalEnvironment>;
+    spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>;
+}
+export default LocalSubprocessRuntime;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/linux-execve.d.ts

@@ -0,0 +1,9 @@
+/** Lazy libc execve and descriptor bindings used by the one-shot Linux bootstrap. */
+/** Replace the current process image while preserving the supplied argv and environment. */
+export type LinuxExecve = (file: string, argv: string[], env: Record<string, string>, control?: 'pipe') => never;
+/**
+ * Load libc's execve and fcntl symbols on first use and retain the native bindings.
+ * @returns a process-replacing execve operation that throws Node-style errors on failure.
+ */
+export declare function loadLinuxExecve(): LinuxExecve;
+//# sourceMappingURL=linux-execve.d.ts.map

package/lib/types/linux-scope.d.ts

@@ -0,0 +1,91 @@
+/** Linux user-systemd scope launch and managed-range ownership. */
+import { spawn, spawnSync } from 'node:child_process';
+import type { SubprocessOutcome, SubprocessSpawnSpec, SubprocessTerminalSpawnSpec } from '@qlzt/dsh-subprocess';
+import { loadLinuxExecve } from './linux-execve.ts';
+import type { BoundProcessOwner, ManagedProcessLaunch } from './managed-owner.ts';
+import type { RunnerInvocation } from './runner-launch.ts';
+/** Test seams for systemd command execution. */
+export interface LinuxScopeInternals {
+    spawn?: typeof spawn;
+    spawnSync?: typeof spawnSync;
+    systemctlQuery?: (command: string, args: readonly string[]) => Promise<SystemctlResult>;
+    systemdRun?: string;
+    systemctl?: string;
+    runnerInvocation?: RunnerInvocation;
+    resolveRunnerInvocation?: () => RunnerInvocation;
+    runnerAvailable?: (invocation: RunnerInvocation) => boolean;
+    loadLinuxExecve?: typeof loadLinuxExecve;
+    sleep?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+}
+interface SystemctlResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+/**
+ * Confirm this exact runner entry and libc execve binding without a probe mode.
+ * @param internals - optional runner and libc-binding seams used by tests.
+ * @returns whether the bootstrap can enter the final target.
+ */
+export declare function probeLinuxBootstrap(internals?: LinuxScopeInternals): boolean;
+/**
+ * Confirm current literal-argv transient-scope support before selecting native launch.
+ * @param internals - optional systemd command seams used by tests.
+ * @returns whether the current user manager supports the required scope invocation.
+ */
+export declare function probeLinuxScope(internals?: LinuxScopeInternals): boolean;
+/**
+ * Confirm that the current user manager remains reachable after a positive deep probe.
+ * @param internals - optional systemctl seam used by tests.
+ * @returns whether one lightweight manager query succeeds.
+ */
+export declare function probeLinuxManager(internals?: LinuxScopeInternals): boolean;
+/**
+ * Re-check every Linux native prerequisite for one eligible spawn.
+ * @param internals - optional native capability seams used by tests.
+ * @returns whether the Linux native containment path is currently available.
+ */
+export declare function probeLinuxNative(internals?: LinuxScopeInternals): boolean;
+interface DirectRange {
+    running(): boolean;
+    /** True for group TERM delivery, direct signal submission, or proven direct-PID absence. */
+    signal(signal: 'SIGTERM' | 'SIGKILL'): boolean;
+    /** Direct exit/error settlement, independent of output drain and managed-range completion. */
+    settled: Promise<unknown>;
+}
+/**
+ * Send a direct-process signal, distinguishing an absent PID from failed delivery.
+ * @param pid - owned direct-process identity whose exit notification can still be pending.
+ * @param send - platform signal operation; true means the signal was submitted.
+ * @returns whether the signal was submitted or the owned PID is already absent.
+ */
+export declare function signalLinuxDirectProcess(pid: number, send: () => boolean): boolean;
+/** Linux PTY invocation and owner for the exact one-shot scope/bootstrap. */
+export interface LinuxTerminalScopeLaunch {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    bindOwner: (direct: DirectRange) => BoundProcessOwner;
+    resolveOutcome: (outcome: SubprocessOutcome) => SubprocessOutcome;
+    cleanup: () => void;
+}
+/**
+ * Prepare one Linux PTY scope using the same launch request and bootstrap core.
+ * @param spec - terminal target request.
+ * @param targetEnv - validated complete target environment.
+ * @param internals - optional runner and systemd seams used by tests.
+ * @returns invocation and ownership callbacks; requested termination preserves the observed signal even before bootstrap consumption.
+ */
+export declare function prepareLinuxTerminalScope(spec: SubprocessTerminalSpawnSpec, targetEnv: Record<string, string>, internals?: LinuxScopeInternals): LinuxTerminalScopeLaunch;
+/**
+ * Launch one ordinary target inside a transient user scope.
+ * @param spec - ordinary target request.
+ * @param targetEnv - validated complete target environment.
+ * @param internals - optional runner and systemd seams used by tests.
+ * @returns streams, result, and scope owner; requested termination preserves the observed signal even before bootstrap consumption.
+ */
+export declare function launchLinuxScope(spec: SubprocessSpawnSpec, targetEnv: Record<string, string>, internals?: LinuxScopeInternals): ManagedProcessLaunch;
+export {};
+//# sourceMappingURL=linux-scope.d.ts.map

package/lib/types/managed-owner.d.ts

@@ -0,0 +1,36 @@
+/** Minimal managed-range ownership bound to one ordinary subprocess handle. */
+import type { Duplex, Readable, Writable } from 'node:stream';
+import type { SubprocessOutcome } from '@qlzt/dsh-subprocess';
+/** Platform owner used by termination and whole-range settlement. */
+export interface BoundProcessOwner {
+    /** Signal the managed range; `cancellationReason` is used only before Windows target commit. */
+    signal(signal: 'SIGTERM' | 'SIGKILL', cancellationReason?: unknown): void;
+    /** Wait for the same managed range to become empty; reject when it cannot be observed. */
+    waitForExit(): Promise<void>;
+    /**
+     * Count tasks in the native range, including descendants outside the observable process tree.
+     * @returns the current count, or undefined when observation is unavailable.
+     */
+    inspectTaskCount?(): number | undefined;
+    /** Synchronously force final termination during JavaScript-observable host exit. */
+    terminateForHostExit(): void;
+    /** Release provider-private protocol artifacts after outcome and range settlement. */
+    cleanup?(): void;
+}
+/** Platform launch facts consumed by the common stdio and result lifecycle. */
+export interface ManagedProcessLaunch {
+    stdin: Writable | null;
+    stdout: Readable | null;
+    stderr: Readable | null;
+    control?: Duplex | undefined;
+    direct: Promise<SubprocessOutcome>;
+    owner: BoundProcessOwner;
+}
+/**
+ * Apply an optional abort bound to one shared wait promise.
+ * @param pending - managed-range wait shared by all callers.
+ * @param signal - optional caller cancellation signal.
+ * @returns whether the managed-range wait completed before cancellation.
+ */
+export declare function waitWithAbort(pending: Promise<void>, signal?: AbortSignal): Promise<boolean>;
+//# sourceMappingURL=managed-owner.d.ts.map