@qlzt/dsh-subprocess-local 0.2.1-alpha.3 → 0.2.1-rc.2

package/README.i18n.yaml

@@ -42,8 +42,8 @@
   en: 531a48766c666ea0
   zh: b40df533a2fd7244
 /deepseek-ai-dsh-subprocess-local/understand-the-implementation/design-concept:
-  en: c1f9a5ee756547b9
-  zh: d47d9f6175f5cbc9
+  en: e4958ac8e71de757
+  zh: 713114f106717f9a
 /deepseek-ai-dsh-subprocess-local/understand-the-implementation/source-map:
   en: 3d5fd99e4ad1f7af
   zh: 241490c1052f415c
@@ -63,8 +63,8 @@
   en: e290ccc9b3c92c08
   zh: d75d48f485447a74
 /deepseek-ai-dsh-subprocess-local/known-limitations-and-deferred-work:
-  en: aca923fe6b461acb
-  zh: ee19a96907134d85
+  en: 4b45e4e4ca67af72
+  zh: 5185485974cd3fa0
 /deepseek-ai-dsh-subprocess-local/known-limitations-and-deferred-work/dev-note:
   en: e67f633dc6fe7773
   zh: 3bb0c20c93f16f98

package/README.md

@@ -83,7 +83,7 @@ This section explains the design decisions behind the provider and points at the
 
 ### Design concept
 
-Each spawn selects one owner for both signalling and quiescence. Supported Linux ordinary and terminal launches use transient user-systemd scopes, while supported Windows ordinary launches use a helper-owned kill-on-close Job. macOS, older or unavailable user-systemd, and unavailable Windows native support use the existing detached process-group, `taskkill`, or terminal-session observations with one warning. The provider never replays a command through fallback after a native path may have started it.
+Each spawn selects one owner for both signalling and quiescence. Supported Linux ordinary and terminal launches use transient user-systemd scopes, while supported Windows ordinary launches use a helper-owned kill-on-close Job. macOS, unavailable user-systemd, and unavailable Windows native support use the existing detached process-group, `taskkill`, or terminal-session observations with one warning. The provider never replays a command through fallback after a native path may have started it.
 
 ### Source map
 
@@ -146,8 +146,8 @@ No direct invalidation; the named consumers own any request-prefix changes.
 These limits define when the provider is a poor fit or needs special operational care. They are current package constraints, not a general platform comparison or a task backlog.
 
 - **Linux direct exit has no independent deadline** — after direct `SIGKILL` is acknowledged, uninterruptible kernel I/O can keep disposal pending indefinitely; `graceMs` and scope-query polling budgets do not bound this wait.
-- **Native ownership has explicit host requirements** — Linux needs a readable user manager and `systemd-run --expand-environment=no`; older systemd versions use the warned PGID fallback. macOS always uses that fallback because no supported public persistent owner exists.
-- **Native selection has bounded per-spawn costs** — Linux repeats the bootstrap entry, libc `execve`/`fcntl` bindings, live user manager, and literal-argv scope probe until it first succeeds; later eligible ordinary or terminal spawns recheck only the live user manager. Windows rechecks the runner entry, bindings, and current Job support before every ordinary spawn. Successful Linux deep-probe state and fallback-warning de-duplication persist for the provider lifetime. All probes finish before the user command can run, and child-process probes have a 5-second timeout. Each Linux launch creates a private request directory, checks unresolved scope establishment every 50 milliseconds, then exponentially backs off an established active scope to at most 5 seconds between queries; a Windows ordinary launch keeps one runner and IPC channel until the Job reports zero active processes. Target standard handles are inherited directly, with no named-pipe stdio or result files.
+- **Native ownership has explicit host requirements** — Linux needs a readable user manager whose `systemd-run` supports `--collect` (systemd 236 and later) and keeps scope arguments literal: version 254 and later receive `--expand-environment=no`, and earlier versions, whose scope mode never expands arguments, run without it. Hosts without a usable user manager use the warned PGID fallback. macOS always uses that fallback because no supported public persistent owner exists.
+- **Native selection has bounded per-spawn costs** — Linux checks the bootstrap entry, libc `execve`/`fcntl` bindings, reachable user manager, and literal-argv scope probe on the first eligible ordinary or terminal spawn and keeps that verdict, including a failed or timed-out probe. The user manager is identified by the process listening on `$XDG_RUNTIME_DIR/systemd/private`, the socket `systemd-run --user` connects through, as listed in the kernel's unix socket table (`/proc/net/unix`) for the same network namespace; reading the table costs time proportional to its size. After a positive verdict, each eligible spawn probes again when the `systemd-run` found through `PATH` has a different device, inode, size, or modification time, and otherwise confirms the manager: a listener confirms it without a child process; otherwise one `systemctl --user show` query decides, and that spawn uses the fallback when the query fails. A scope launch whose bootstrap never consumed its launch request, such as one sent to a hung manager that still listens, fails that command, as do scope launches issued before that failure arrives, and the next eligible spawn probes again. After a negative verdict, the provider probes again only when a different listener appears, so a manager that starts later is used without a restart. Windows rechecks the runner entry, bindings, and current Job support before every ordinary spawn. Fallback-warning de-duplication also persists for the provider lifetime. All probes finish before the user command can run; each child-process probe has a 5-second timeout, and a `systemd-run` that rejects `--expand-environment=no` is probed once more without it. Each Linux launch creates a private request directory, checks unresolved scope establishment every 50 milliseconds, then exponentially backs off an established active scope to at most 5 seconds between queries; a Windows ordinary launch keeps one runner and IPC channel until the Job reports zero active processes. Target standard handles are inherited directly, with no named-pipe stdio or result files.
 - **Windows Job inheritance has defined exclusions** — ordinary descendants inherit the Job by default, but breakaway processes are outside the guarantee. The target starts only after Job assignment; external termination of the runner in the narrow create-to-assignment interval can leave a suspended target behind.
 - **Windows terminal signalling is console-wide** — SIGINT is delivered as a `\x03` Ctrl-C input write that the console host turns into a console-wide CTRL_C event (on Windows that host is node-pty's bundled OpenConsole); 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.
 - **Windows terminal allocation requires node-pty's bundled console host assets** — every Windows terminal is spawned with `useConptyDll: true`, so allocation resolves `conpty/conpty.dll` and `OpenConsole.exe` relative to node-pty's own addon; an asset that is missing or unpacked wrong makes `spawnTerminal` throw instead of falling back to the operating system console host. node-pty marks the option experimental, so a node-pty upgrade can change this behaviour. See the [bundled console host note](../../../.agents/notes/implemented/bug-fix/2026-09-28-pty-bundled-console-host.md).

package/README.zh.md

@@ -83,7 +83,7 @@ Linux 普通进程和终端进程即使在 bootstrap 消费启动请求前被取
 
 ### 设计理念
 
-每次 spawn 都为信号发送与完全停稳选择同一个 owner。受支持的 Linux 普通命令与终端启动使用临时 user-systemd scope，受支持的 Windows 普通命令使用由 helper 持有、关闭时终止成员的 Job。macOS、旧版或不可用的 user-systemd，以及不可用的 Windows 原生支持使用既有 detached 进程组、`taskkill` 或终端会话观察，并只告警一次。native 路径可能已经启动命令后，本提供方绝不会通过 fallback 重放该命令。
+每次 spawn 都为信号发送与完全停稳选择同一个 owner。受支持的 Linux 普通命令与终端启动使用临时 user-systemd scope，受支持的 Windows 普通命令使用由 helper 持有、关闭时终止成员的 Job。macOS、不可用的 user-systemd，以及不可用的 Windows 原生支持使用既有 detached 进程组、`taskkill` 或终端会话观察，并只告警一次。native 路径可能已经启动命令后，本提供方绝不会通过 fallback 重放该命令。
 
 ### 源码地图
 
@@ -146,8 +146,8 @@ spill 文件以 `0600` 权限、`O_EXCL` 与随机名称在 `0700` 每进程目
 这些限制说明本提供方何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是通用平台对比或任务积压。
 
 - **Linux 直接进程退出没有独立截止时间**——直接 `SIGKILL` 获得确认后，不可中断的内核 I/O 可能让 dispose 无限期等待；`graceMs` 和 scope 查询的轮询预算不限制此等待。
-- **native ownership 有明确宿主要求**——Linux 需要可读的 user manager 与 `systemd-run --expand-environment=no`；旧版 systemd 使用带告警的 PGID fallback。macOS 因没有受支持的公开 persistent owner，始终使用该 fallback。
-- **native 选择具有有界的每次 spawn 成本**——Linux 会重复检查 bootstrap 入口、libc `execve`/`fcntl` bindings、存活的 user manager 与 literal-argv scope 支持，直到这套完整探测首次成功；后续符合条件的普通命令或终端 spawn 只重新检查存活的 user manager。Windows 会在每次普通 spawn 前重新检查 runner 入口、bindings 与当前 Job 支持。Linux 深度探测的成功状态与 fallback 告警去重会在提供方生命周期内持续保留。所有探测都会在用户命令可能运行前完成，子进程探测的超时为 5 秒。每次 Linux 启动都会创建私有请求目录，以 50 毫秒间隔检查尚未确定的 scope 建立状态；scope 已建立且仍 active 后，查询间隔按指数增长，最多为 5 秒。Windows 普通命令会保留一个 runner 与一条 IPC 通道，直到 Job 报告活动进程数为零。目标会直接继承标准句柄，不使用 named-pipe stdio 或结果文件。
+- **native ownership 有明确宿主要求**——Linux 需要可读的 user manager，且其 `systemd-run` 支持 `--collect`（systemd 236 及以上）并保持 scope 参数按字面传递：254 及以上版本传入 `--expand-environment=no`，更早版本的 scope 模式从不展开参数，因此不传该选项。没有可用 user manager 的宿主使用带告警的 PGID fallback。macOS 因没有受支持的公开 persistent owner，始终使用该 fallback。
+- **native 选择具有有界的每次 spawn 成本**——Linux 在第一次符合条件的普通命令或终端 spawn 时检查 bootstrap 入口、libc `execve`/`fcntl` bindings、可连接的 user manager 与 literal-argv scope 支持，并保留这一结论，探测失败或超时的结论也是如此。user manager 以内核 unix socket 表（`/proc/net/unix`）中同一网络命名空间里在 `$XDG_RUNTIME_DIR/systemd/private`（`systemd-run --user` 连接 manager 所用的 socket）上监听的进程来识别；读取该表的耗时与表的大小成正比。结论为可用时，若经 `PATH` 找到的 `systemd-run` 的设备号、inode、大小或修改时间发生变化，下一次符合条件的 spawn 会重新探测；否则每次都会确认 manager：有监听者时无需子进程即可确认；否则由一次 `systemctl --user show` 查询决定，查询失败时这次 spawn 使用 fallback。bootstrap 从未消费 launch request 的 scope 启动（例如发给卡死但仍在监听的 manager）会让这条命令失败，在该失败到达之前发起的 scope 启动也会失败，下一次符合条件的 spawn 会重新探测。结论为不可用时，只有出现不同的监听者才会重新探测，因此之后才启动的 manager 无需重启即可被使用。Windows 会在每次普通 spawn 前重新检查 runner 入口、bindings 与当前 Job 支持。fallback 告警去重同样在提供方生命周期内持续保留。所有探测都会在用户命令可能运行前完成；每次子进程探测的超时为 5 秒，`systemd-run` 拒绝 `--expand-environment=no` 时会去掉该选项再探测一次。每次 Linux 启动都会创建私有请求目录，以 50 毫秒间隔检查尚未确定的 scope 建立状态；scope 已建立且仍 active 后，查询间隔按指数增长，最多为 5 秒。Windows 普通命令会保留一个 runner 与一条 IPC 通道，直到 Job 报告活动进程数为零。目标会直接继承标准句柄，不使用 named-pipe stdio 或结果文件。
 - **Windows Job inheritance 有明确排除项**——普通后代默认继承 Job，但 breakaway 进程不在保证范围。目标只在 Job 分配后启动；runner 若在 create-to-assignment 极窄区间遭外力终止，可能留下 suspended target。
 - **Windows 终端信号是控制台级的**——SIGINT 以 `\x03` Ctrl-C 输入写入投递，由控制台宿主（Windows 上为 node-pty 自带的 OpenConsole）转为控制台级 CTRL_C 事件；SIGTSTP 与 SIGHUP 被拒绝（不可用）；不带 `/F` 的 `taskkill` 无法终止控制台进程，因此拆卸的 TERM 档是 `/F` 升级前的宽限等待。Windows 就绪没有精确的 stdin-wait 档：prompt-marker 快路径把 shell pid 作为伪前台进程组比较，其余由静默与计时档覆盖。
 - **Windows 终端分配依赖 node-pty 自带的控制台宿主资产**——每个 Windows 终端都以 `useConptyDll: true` 启动，分配时按 node-pty 自身 addon 的相对位置解析 `conpty/conpty.dll` 与 `OpenConsole.exe`；资产缺失或解包错误会让 `spawnTerminal` 抛错，而不是回退到操作系统控制台宿主。node-pty 把该选项标为实验性，升级 node-pty 可能改变这一行为。见[自带控制台宿主说明](../../../.agents/notes/implemented/bug-fix/2026-09-28-pty-bundled-console-host.zh.md)。

package/lib/index.js

@@ -1,6 +1,6 @@
 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 { closeSync, constants, existsSync, mkdtempSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { access, stat } from "node:fs/promises";
 import { constants as constants$1, devNull, tmpdir, userInfo } from "node:os";
 import { basename, delimiter, extname, isAbsolute, join, resolve } from "node:path";
@@ -17,6 +17,11 @@ import { PassThrough } from "node:stream";
 const SYSTEMCTL_TIMEOUT_MS = 5e3;
 const SCOPE_INITIAL_POLL_INTERVAL_MS = 50;
 const MISSING_UNIT = /\bunit\b[^\r\n]*(?:could not be found|not found|not loaded)/iu;
+const LITERAL_ARGV_OPTION = "--expand-environment=no";
+const LITERAL_ARGV_OPTION_REJECTED = /unrecognized option\b.*expand-environment/u;
+const KILL_ALL_MEMBERS = "--kill-who=all";
+/** Flags bit that /proc/net/unix sets on a listening socket (__SO_ACCEPTCON). */
+const UNIX_SOCKET_ACCEPTING = 65536;
 function managerEnvironment() {
 	const environment = childEnv({ LC_ALL: "C" });
 	delete environment.SYSTEMD_LOG_TARGET;
@@ -68,35 +73,57 @@ function probeLinuxBootstrap(internals = {}) {
 /**
 * 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.
+* @returns the options that keep target argv literal, or undefined when the user manager cannot create the scope.
 */
 function probeLinuxScope(internals = {}) {
-	const unitBase = unitStem("dsh-subprocess-probe");
-	const result = (internals.spawnSync ?? spawnSync)(internals.systemdRun ?? "systemd-run", [
-		"--user",
-		"--scope",
-		"--quiet",
-		"--collect",
-		"--expand-environment=no",
-		`--unit=${unitBase}`,
-		"--",
-		internals.systemctl ?? "systemctl",
-		"--user",
-		"show",
-		`${unitBase}.scope`,
-		"--property=ActiveState",
-		"--value"
-	], {
-		env: quietSystemdEnvironment(),
-		stdio: "ignore",
-		timeout: SYSTEMCTL_TIMEOUT_MS
-	});
-	return result.error === void 0 && result.status === 0;
+	const attempt = (literalArgv) => {
+		const unitBase = unitStem("dsh-subprocess-probe");
+		const result = (internals.spawnSync ?? spawnSync)(internals.systemdRun ?? "systemd-run", [
+			"--user",
+			"--scope",
+			"--quiet",
+			"--collect",
+			...literalArgv,
+			`--unit=${unitBase}`,
+			"--",
+			internals.systemctl ?? "systemctl",
+			"--user",
+			"show",
+			`${unitBase}.scope`,
+			"--property=ActiveState",
+			"--value"
+		], {
+			encoding: "utf8",
+			env: quietSystemdEnvironment(),
+			stdio: [
+				"ignore",
+				"ignore",
+				"pipe"
+			],
+			timeout: SYSTEMCTL_TIMEOUT_MS
+		});
+		return {
+			created: result.error === void 0 && result.status === 0,
+			stderr: result.stderr
+		};
+	};
+	const current = attempt([LITERAL_ARGV_OPTION]);
+	if (current.created) return [LITERAL_ARGV_OPTION];
+	if (!LITERAL_ARGV_OPTION_REJECTED.test(current.stderr)) return void 0;
+	return attempt([]).created ? [] : void 0;
+}
+/**
+* Check every Linux native prerequisite on each call.
+* @param internals - optional native capability seams used by tests.
+* @returns the literal-argv scope options when Linux native containment is available, otherwise undefined.
+*/
+function probeLinuxNative(internals = {}) {
+	return probeLinuxBootstrap(internals) ? probeLinuxScope(internals) : void 0;
 }
 /**
-* Confirm that the current user manager remains reachable after a positive deep probe.
+* Query the user manager once through systemctl.
 * @param internals - optional systemctl seam used by tests.
-* @returns whether one lightweight manager query succeeds.
+* @returns whether the query succeeds.
 */
 function probeLinuxManager(internals = {}) {
 	const result = (internals.spawnSync ?? spawnSync)(internals.systemctl ?? "systemctl", [
@@ -112,13 +139,69 @@ function probeLinuxManager(internals = {}) {
 	return result.error === void 0 && result.status === 0;
 }
 /**
-* 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.
+* Find the socket a process in this network namespace listens on at path. The kernel lists a
+* bound socket only while a process holds it open, so a socket file that a stopped or crashed
+* listener left behind does not count.
 */
-function probeLinuxNative(internals = {}) {
-	return probeLinuxBootstrap(internals) && probeLinuxScope(internals);
+function unixSocketListener(path, table) {
+	let text;
+	try {
+		text = readFileSync(table, "utf8");
+	} catch (_unreadableSocketTable) {
+		return;
+	}
+	const suffix = ` ${path}`;
+	for (const line of text.split("\n")) {
+		if (!line.endsWith(suffix)) continue;
+		const fields = line.trim().split(/\s+/u);
+		if (fields.slice(7).join(" ") === path && (Number.parseInt(String(fields[3]), 16) & UNIX_SOCKET_ACCEPTING) !== 0) return String(fields[6]);
+	}
 }
+/**
+* Identify the user manager's listener on `$XDG_RUNTIME_DIR/systemd/private`, the socket
+* `systemd-run --user` connects through.
+* @param internals - optional socket-table seam used by tests.
+* @returns the listening socket's inode from the kernel socket table, or undefined when
+*   XDG_RUNTIME_DIR is unset or nothing in this network namespace listens there.
+*/
+function linuxManagerListener(internals = {}) {
+	const runtimeDirectory = childEnv().XDG_RUNTIME_DIR;
+	if (runtimeDirectory === void 0 || runtimeDirectory === "") return void 0;
+	return unixSocketListener(join(runtimeDirectory, "systemd", "private"), internals.unixSocketTable ?? "/proc/net/unix");
+}
+/**
+* Identify the systemd-run binary that scope launches resolve through PATH, so a package upgrade
+* that replaces it triggers another probe of its literal-argv options.
+* @param internals - optional systemd-run seam used by tests.
+* @returns the device, inode, size, and modification time of the first match, or undefined when none resolves.
+*/
+function systemdRunIdentity(internals = {}) {
+	const command = internals.systemdRun ?? "systemd-run";
+	const candidates = command.includes("/") ? [command] : (childEnv().PATH ?? "").split(":").filter((directory) => directory !== "").map((directory) => join(directory, command));
+	for (const candidate of candidates) {
+		let stats;
+		try {
+			stats = statSync(candidate, { throwIfNoEntry: false });
+		} catch (_unreadableCandidate) {
+			continue;
+		}
+		if (stats?.isFile() === true) return `${String(stats.dev)}:${String(stats.ino)}:${String(stats.size)}:${String(stats.mtimeMs)}`;
+	}
+}
+/**
+* Confirm the user manager before a scope launch. A listener on its private socket confirms it
+* without a child process; otherwise one systemctl query decides. A hung manager that still
+* listens passes, and its scope launch fails with LinuxScopeNotStartedError.
+* @param internals - optional socket-table and systemctl seams used by tests.
+* @returns whether a scope launch can reach the user manager.
+*/
+function confirmLinuxManager(internals = {}) {
+	return linuxManagerListener(internals) !== void 0 || probeLinuxManager(internals);
+}
+/** A scope launch whose bootstrap never consumed its launch request, so its target never ran. */
+var LinuxScopeNotStartedError = class extends Error {
+	name = "LinuxScopeNotStartedError";
+};
 var LinuxScopeStartup = class {
 	files;
 	kind;
@@ -130,7 +213,7 @@ var LinuxScopeStartup = class {
 	resolveOutcome(outcome) {
 		const startup = readLinuxStartupError(this.files.startupErrorPath);
 		if (startup !== void 0) throw deserializeRunnerError(startup.error);
-		if (existsSync(this.files.requestPath) && !(outcome.signal !== null && this.terminationSignals.has(outcome.signal))) throw new Error(`${this.kind} scope exited before its bootstrap consumed the launch request`);
+		if (existsSync(this.files.requestPath) && !(outcome.signal !== null && this.terminationSignals.has(outcome.signal))) throw new LinuxScopeNotStartedError(`${this.kind} scope exited before its bootstrap consumed the launch request; the provider probes native containment again before its next command`);
 		return outcome;
 	}
 };
@@ -187,7 +270,7 @@ var SystemdScopeOwner = class {
 		const result = this.runSync(this.systemctl, [
 			"--user",
 			"kill",
-			"--kill-whom=all",
+			KILL_ALL_MEMBERS,
 			`--signal=${signal}`,
 			this.unit
 		], {
@@ -221,7 +304,7 @@ var SystemdScopeOwner = class {
 			this.runSync(this.systemctl, [
 				"--user",
 				"kill",
-				"--kill-whom=all",
+				KILL_ALL_MEMBERS,
 				"--signal=SIGKILL",
 				this.unit
 			], {
@@ -380,13 +463,13 @@ var SystemdScopeOwner = class {
 		cleanupLinuxLaunchFiles(this.startup.files);
 	}
 };
-function scopeArgs(unitBase, invocation, argv) {
+function scopeArgs(unitBase, literalArgv, invocation, argv) {
 	return [
 		"--user",
 		"--scope",
 		"--quiet",
 		"--collect",
-		"--expand-environment=no",
+		...literalArgv,
 		`--unit=${unitBase}`,
 		"--",
 		...invocation,
@@ -445,10 +528,11 @@ function signalChildGroup(child, signal) {
 * 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 literalArgv - options from the provider's positive scope probe.
 * @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.
 */
-function prepareLinuxTerminalScope(spec, targetEnv, internals = {}) {
+function prepareLinuxTerminalScope(spec, targetEnv, literalArgv, internals = {}) {
 	const invocation = internals.runnerInvocation ?? spawnRunnerInvocation();
 	const files = createLinuxLaunchFiles({
 		cwd: spec.cwd,
@@ -458,7 +542,7 @@ function prepareLinuxTerminalScope(spec, targetEnv, internals = {}) {
 	const unitBase = unitStem("dsh-terminal");
 	return {
 		command: internals.systemdRun ?? "systemd-run",
-		args: scopeArgs(unitBase, invocation, spec.argv),
+		args: scopeArgs(unitBase, literalArgv, invocation, spec.argv),
 		cwd: process.cwd(),
 		env: runnerEnvironment(files.requestPath, invocation),
 		bindOwner: (direct) => new SystemdScopeOwner(`${unitBase}.scope`, startup, direct, internals.systemctl ?? "systemctl", internals.spawnSync ?? spawnSync, internals.systemctlQuery ?? querySystemctl, internals.sleep ?? sleepWithAbort),
@@ -472,10 +556,11 @@ function prepareLinuxTerminalScope(spec, targetEnv, internals = {}) {
 * Launch one ordinary target inside a transient user scope.
 * @param spec - ordinary target request.
 * @param targetEnv - validated complete target environment.
+* @param literalArgv - options from the provider's positive scope probe.
 * @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.
 */
-function launchLinuxScope(spec, targetEnv, internals = {}) {
+function launchLinuxScope(spec, targetEnv, literalArgv, internals = {}) {
 	const invocation = internals.runnerInvocation ?? spawnRunnerInvocation();
 	const files = createLinuxLaunchFiles({
 		cwd: spec.cwd,
@@ -486,7 +571,7 @@ function launchLinuxScope(spec, targetEnv, internals = {}) {
 	const unitBase = unitStem("dsh-subprocess");
 	let child;
 	try {
-		child = (internals.spawn ?? spawn)(internals.systemdRun ?? "systemd-run", scopeArgs(unitBase, invocation, spec.argv), {
+		child = (internals.spawn ?? spawn)(internals.systemdRun ?? "systemd-run", scopeArgs(unitBase, literalArgv, invocation, spec.argv), {
 			cwd: process.cwd(),
 			env: runnerEnvironment(files.requestPath, invocation),
 			stdio: runnerStdio(spec, false),
@@ -512,6 +597,102 @@ function launchLinuxScope(spec, targetEnv, internals = {}) {
 	};
 }
 //#endregion
+//#region lib/types/linux-scope-selector.js
+/** Linux native containment decisions over injected host observations. */
+/**
+* Provider-lifetime Linux scope selection. A probe runs on the first selection and again only after
+* a scope launch never started its target, a different user-manager listener appears under a
+* negative verdict, or the systemd-run binary changes under a positive one. A positive verdict
+* confirms the user manager on every selection. Selection is synchronous, so a decision stays
+* valid for the launch that follows it.
+*/
+var LinuxScopeSelector = class {
+	observe;
+	state = {
+		kind: "unprobed",
+		trigger: "first"
+	};
+	generation = 0;
+	/** @param observe - host checks consulted by each selection. */
+	constructor(observe) {
+		this.observe = observe;
+	}
+	/**
+	* Choose containment for one eligible launch.
+	* @returns the decision and the branch that produced it.
+	*/
+	select() {
+		const state = this.state;
+		if (state.kind === "unprobed") return this.probe(state.trigger);
+		if (state.kind === "available") {
+			if (this.observe.launcherIdentity() !== state.launcher) return this.probe("launcher-changed");
+			return this.observe.confirmManager() ? {
+				kind: "scope",
+				reason: "manager-confirmed",
+				literalArgv: state.literalArgv,
+				generation: this.generation,
+				probe: void 0
+			} : {
+				kind: "fallback",
+				reason: "manager-unconfirmed",
+				probe: void 0
+			};
+		}
+		const listener = this.observe.managerListener();
+		if (listener === void 0) return {
+			kind: "fallback",
+			reason: "no-listener",
+			probe: void 0
+		};
+		if (listener === state.listener) return {
+			kind: "fallback",
+			reason: "same-listener",
+			probe: void 0
+		};
+		return this.probe("new-listener");
+	}
+	/**
+	* Record that a scope launched under generation exited before its bootstrap started the target,
+	* so the next selection probes again. Launches from a superseded probe are ignored.
+	* @param generation - generation of the scope decision that launched it.
+	*/
+	scopeNotStarted(generation) {
+		if (generation === this.generation) this.state = {
+			kind: "unprobed",
+			trigger: "scope-not-started"
+		};
+	}
+	probe(trigger) {
+		this.generation += 1;
+		const listener = this.observe.managerListener();
+		const launcher = this.observe.launcherIdentity();
+		const literalArgv = this.observe.probe();
+		if (literalArgv === void 0) {
+			this.state = {
+				kind: "unavailable",
+				listener
+			};
+			return {
+				kind: "fallback",
+				reason: "probe-unavailable",
+				probe: trigger
+			};
+		}
+		this.state = {
+			kind: "available",
+			literalArgv,
+			launcher
+		};
+		return {
+			kind: "scope",
+			reason: "probe-available",
+			literalArgv,
+			generation: this.generation,
+			probe: trigger
+		};
+	}
+};
+//#endregion
 //#region lib/types/windows-job.js
 /** Windows parent-side launch and ownership for the private Job runner. */
 function isWindowsStartCancellationError(error) {
@@ -1277,8 +1458,18 @@ var LocalSubprocessRuntime = class extends SubprocessRuntime {
 	internals = {};
 	/** Provider-lifetime latch suppressing repeated weaker-containment warnings. */
 	fallbackWarningIssued = false;
-	/** Positive-only cache for the expensive Linux bootstrap and scope probe. */
-	linuxDeepProbePassed = false;
+	/**
+	* Linux native containment decisions. Each probe is a spawnSync that blocks the event loop and forks the
+	* host, so the selector reruns it only after an event invalidates the previous verdict.
+	*/
+	linuxScope = new LinuxScopeSelector({
+		probe: () => probeLinuxNative(),
+		managerListener: () => linuxManagerListener(),
+		confirmManager: () => confirmLinuxManager(),
+		launcherIdentity: () => systemdRunIdentity()
+	});
+	/** Scope decision of the launch in progress; selectContainmentMode sets it immediately before the launch reads it. */
+	linuxScopeDecision;
 	/** Test hook for platform process inspection; production resolves lazily on terminal spawn. */
 	terminalInspector;
 	constructor(ctx) {
@@ -1365,7 +1556,9 @@ var LocalSubprocessRuntime = class extends SubprocessRuntime {
 		if (containmentMode === "fallback") handle = spawnSubprocess(spec, internals);
 		else {
 			const binding = prepareManagedProcessBinding(internals);
-			handle = bindManagedProcess(spec, containmentMode === "linux-scope" ? launchLinuxScope(spec, env) : launchWindowsJob(spec, env), binding);
+			const linuxScope = containmentMode === "linux-scope" ? this.linuxScopeDecision : void 0;
+			handle = bindManagedProcess(spec, linuxScope === void 0 ? launchWindowsJob(spec, env) : launchLinuxScope(spec, env, linuxScope.literalArgv), binding);
+			if (linuxScope !== void 0) this.watchLinuxScopeStart(handle.done, linuxScope.generation);
 		}
 		this.live.add(handle);
 		const control = handle.control;
@@ -1381,13 +1574,23 @@ var LocalSubprocessRuntime = class extends SubprocessRuntime {
 		handle.done.then(release, release).catch(() => {});
 		return handle;
 	}
+	/** Probe again before the next launch when a scope launched under generation never started its target. */
+	watchLinuxScopeStart(done, generation) {
+		done.catch((error) => {
+			if (error instanceof LinuxScopeNotStartedError) this.linuxScope.scopeNotStarted(generation);
+		});
+	}
 	selectContainmentMode(kind) {
 		const platform = this.internals.platform ?? process.platform;
 		let fallbackReason;
 		if (platform === "linux") {
-			const available = this.linuxDeepProbePassed ? probeLinuxManager() : probeLinuxNative();
-			if (available) this.linuxDeepProbePassed = true;
-			if (available) return "linux-scope";
+			const decision = this.linuxScope.select();
+			const probe = decision.probe === void 0 ? "" : `, probed after ${decision.probe}`;
+			this.ctx.logger.debug(`linux native containment: ${decision.kind} (${decision.reason}${probe})`);
+			if (decision.kind === "scope") {
+				this.linuxScopeDecision = decision;
+				return "linux-scope";
+			}
 			fallbackReason = "the current user-systemd scope or private bootstrap is unavailable";
 		}
 		if (kind === "ordinary" && platform === "win32") {
@@ -1437,14 +1640,15 @@ var LocalSubprocessRuntime = class extends SubprocessRuntime {
 			},
 			...platform === "win32" ? { useConptyDll: true } : {}
 		};
+		const linuxScope = containmentMode === "linux-scope" ? this.linuxScopeDecision : void 0;
 		let scope;
 		let terminal;
 		try {
-			scope = containmentMode === "linux-scope" ? prepareLinuxTerminalScope(launch, {
+			scope = linuxScope === void 0 ? void 0 : prepareLinuxTerminalScope(launch, {
 				...activity?.env ?? env,
 				PWD: spec.cwd,
 				TERM: spec.terminalType
-			}) : void 0;
+			}, linuxScope.literalArgv);
 			if (scope !== void 0) {
 				options.cwd = scope.cwd;
 				options.env = scope.env;
@@ -1466,6 +1670,7 @@ var LocalSubprocessRuntime = class extends SubprocessRuntime {
 			this.terminals.delete(handle);
 		}, spec.shellActivity === true);
 		this.terminals.add(handle);
+		if (linuxScope !== void 0) this.watchLinuxScopeStart(handle.done, linuxScope.generation);
 		const release = async () => {
 			directSettlement.resolve();
 			if (spec.shellActivity === true) return;

package/lib/types/index.d.ts

@@ -30,8 +30,13 @@ export declare class LocalSubprocessRuntime extends SubprocessRuntime {
     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;
+    /**
+     * Linux native containment decisions. Each probe is a spawnSync that blocks the event loop and forks the
+     * host, so the selector reruns it only after an event invalidates the previous verdict.
+     */
+    private readonly linuxScope;
+    /** Scope decision of the launch in progress; selectContainmentMode sets it immediately before the launch reads it. */
+    private linuxScopeDecision;
     /** Test hook for platform process inspection; production resolves lazily on terminal spawn. */
     terminalInspector: ProcessInspector | undefined;
     constructor(ctx: Context);
@@ -42,6 +47,8 @@ export declare class LocalSubprocessRuntime extends SubprocessRuntime {
     resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;
     private executableCandidates;
     spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+    /** Probe again before the next launch when a scope launched under generation never started its target. */
+    private watchLinuxScopeStart;
     private selectContainmentMode;
     private warnFallback;
     /** @inheritdoc */

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

@@ -0,0 +1,60 @@
+/** Linux native containment decisions over injected host observations. */
+import type { LiteralArgvOptions } from './linux-scope.ts';
+/** Host observations behind each decision; the runtime supplies the real checks and tests script them. */
+export interface LinuxScopeObservations {
+    /** Run the deep transient-scope probe: literal-argv options when a scope can start, otherwise undefined. */
+    probe(): LiteralArgvOptions | undefined;
+    /** Identify the process listening on the user manager's private socket, or undefined when none listens. */
+    managerListener(): string | undefined;
+    /** Confirm the user manager before a launch under a positive verdict. */
+    confirmManager(): boolean;
+    /** Identify the systemd-run binary scope launches resolve, or undefined when none resolves. */
+    launcherIdentity(): string | undefined;
+}
+/** Event that made the selector probe: the first selection or one that invalidated the previous verdict. */
+export type LinuxProbeTrigger = 'first' | 'scope-not-started' | 'new-listener' | 'launcher-changed';
+/** One containment decision and the branch that produced it. */
+export type LinuxScopeDecision = {
+    readonly kind: 'scope';
+    /** A probe found scope support, or a positive verdict confirmed the user manager. */
+    readonly reason: 'probe-available' | 'manager-confirmed';
+    readonly literalArgv: LiteralArgvOptions;
+    /** Probe count when the verdict was made; pass it to scopeNotStarted for a failed launch. */
+    readonly generation: number;
+    readonly probe: LinuxProbeTrigger | undefined;
+} | {
+    readonly kind: 'fallback';
+    /**
+     * A probe found no scope support; a positive verdict failed to confirm the manager for this launch;
+     * or a negative verdict saw no listener or the listener present at the failed probe.
+     */
+    readonly reason: 'probe-unavailable' | 'manager-unconfirmed' | 'no-listener' | 'same-listener';
+    readonly probe: LinuxProbeTrigger | undefined;
+};
+/**
+ * Provider-lifetime Linux scope selection. A probe runs on the first selection and again only after
+ * a scope launch never started its target, a different user-manager listener appears under a
+ * negative verdict, or the systemd-run binary changes under a positive one. A positive verdict
+ * confirms the user manager on every selection. Selection is synchronous, so a decision stays
+ * valid for the launch that follows it.
+ */
+export declare class LinuxScopeSelector {
+    private readonly observe;
+    private state;
+    private generation;
+    /** @param observe - host checks consulted by each selection. */
+    constructor(observe: LinuxScopeObservations);
+    /**
+     * Choose containment for one eligible launch.
+     * @returns the decision and the branch that produced it.
+     */
+    select(): LinuxScopeDecision;
+    /**
+     * Record that a scope launched under generation exited before its bootstrap started the target,
+     * so the next selection probes again. Launches from a superseded probe are ignored.
+     * @param generation - generation of the scope decision that launched it.
+     */
+    scopeNotStarted(generation: number): void;
+    private probe;
+}
+//# sourceMappingURL=linux-scope-selector.d.ts.map

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

@@ -16,6 +16,8 @@ export interface LinuxScopeInternals {
     runnerAvailable?: (invocation: RunnerInvocation) => boolean;
     loadLinuxExecve?: typeof loadLinuxExecve;
     sleep?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+    /** Kernel unix socket table read by the user-manager confirmation; defaults to /proc/net/unix. */
+    unixSocketTable?: string;
 }
 interface SystemctlResult {
     status: number | null;
@@ -23,6 +25,8 @@ interface SystemctlResult {
     stderr: string;
     error?: Error;
 }
+/** systemd-run options that keep target argv literal; empty where scope mode never expands argv. */
+export type LiteralArgvOptions = readonly string[];
 /**
  * Confirm this exact runner entry and libc execve binding without a probe mode.
  * @param internals - optional runner and libc-binding seams used by tests.
@@ -32,21 +36,44 @@ export declare function probeLinuxBootstrap(internals?: LinuxScopeInternals): bo
 /**
  * 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.
+ * @returns the options that keep target argv literal, or undefined when the user manager cannot create the scope.
  */
-export declare function probeLinuxScope(internals?: LinuxScopeInternals): boolean;
+export declare function probeLinuxScope(internals?: LinuxScopeInternals): LiteralArgvOptions | undefined;
 /**
- * Confirm that the current user manager remains reachable after a positive deep probe.
+ * Check every Linux native prerequisite on each call.
+ * @param internals - optional native capability seams used by tests.
+ * @returns the literal-argv scope options when Linux native containment is available, otherwise undefined.
+ */
+export declare function probeLinuxNative(internals?: LinuxScopeInternals): LiteralArgvOptions | undefined;
+/**
+ * Query the user manager once through systemctl.
  * @param internals - optional systemctl seam used by tests.
- * @returns whether one lightweight manager query succeeds.
+ * @returns whether the 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.
+ * Identify the user manager's listener on `$XDG_RUNTIME_DIR/systemd/private`, the socket
+ * `systemd-run --user` connects through.
+ * @param internals - optional socket-table seam used by tests.
+ * @returns the listening socket's inode from the kernel socket table, or undefined when
+ *   XDG_RUNTIME_DIR is unset or nothing in this network namespace listens there.
  */
-export declare function probeLinuxNative(internals?: LinuxScopeInternals): boolean;
+export declare function linuxManagerListener(internals?: LinuxScopeInternals): string | undefined;
+/**
+ * Identify the systemd-run binary that scope launches resolve through PATH, so a package upgrade
+ * that replaces it triggers another probe of its literal-argv options.
+ * @param internals - optional systemd-run seam used by tests.
+ * @returns the device, inode, size, and modification time of the first match, or undefined when none resolves.
+ */
+export declare function systemdRunIdentity(internals?: LinuxScopeInternals): string | undefined;
+/**
+ * Confirm the user manager before a scope launch. A listener on its private socket confirms it
+ * without a child process; otherwise one systemctl query decides. A hung manager that still
+ * listens passes, and its scope launch fails with LinuxScopeNotStartedError.
+ * @param internals - optional socket-table and systemctl seams used by tests.
+ * @returns whether a scope launch can reach the user manager.
+ */
+export declare function confirmLinuxManager(internals?: LinuxScopeInternals): boolean;
 interface DirectRange {
     running(): boolean;
     /** True for group TERM delivery, direct signal submission, or proven direct-PID absence. */
@@ -54,6 +81,10 @@ interface DirectRange {
     /** Direct exit/error settlement, independent of output drain and managed-range completion. */
     settled: Promise<unknown>;
 }
+/** A scope launch whose bootstrap never consumed its launch request, so its target never ran. */
+export declare class LinuxScopeNotStartedError extends Error {
+    readonly name = "LinuxScopeNotStartedError";
+}
 /**
  * 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.
@@ -75,17 +106,19 @@ export interface LinuxTerminalScopeLaunch {
  * 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 literalArgv - options from the provider's positive scope probe.
  * @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;
+export declare function prepareLinuxTerminalScope(spec: SubprocessTerminalSpawnSpec, targetEnv: Record<string, string>, literalArgv: LiteralArgvOptions, internals?: LinuxScopeInternals): LinuxTerminalScopeLaunch;
 /**
  * Launch one ordinary target inside a transient user scope.
  * @param spec - ordinary target request.
  * @param targetEnv - validated complete target environment.
+ * @param literalArgv - options from the provider's positive scope probe.
  * @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 declare function launchLinuxScope(spec: SubprocessSpawnSpec, targetEnv: Record<string, string>, literalArgv: LiteralArgvOptions, internals?: LinuxScopeInternals): ManagedProcessLaunch;
 export {};
 //# sourceMappingURL=linux-scope.d.ts.map

package/locale/en.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "subprocess-local"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "本地子进程",
+    "description": "为其他插件提供本地进程的启动和管理能力。"
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qlzt/dsh-subprocess-local",
   "description": "Local-subprocess implementation of the DeepSeek Harness subprocess seam",
-  "version": "0.2.1-alpha.3",
+  "version": "0.2.1-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,9 +27,11 @@
     "./output": {
       "types": "./lib/types/output.d.ts",
       "default": "./lib/output.js"
-    }
+    },
+    "./locale/*.json": "./locale/*.json"
   },
   "files": [
+    "locale/*.json",
     "lib/index.js",
     "lib/runner.js",
     "lib/runner-*.js",
@@ -39,21 +41,21 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@qlzt/dsh-subprocess": "0.2.1-alpha.3",
-    "@qlzt/dsh-timeout": "0.2.1-alpha.3",
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
+    "@qlzt/dsh-subprocess": "0.2.1-rc.2",
+    "@qlzt/dsh-timeout": "0.2.1-rc.2",
+    "@deepseek-ai/cordis": "~4.0.5"
   },
   "dependencies": {
-    "@qlzt/dsh-lazy-require": "0.2.1-alpha.3",
-    "@qlzt/dsh-win32-process": "0.2.1-alpha.3",
+    "@qlzt/dsh-lazy-require": "0.2.1-rc.2",
+    "@qlzt/dsh-win32-process": "0.2.1-rc.2",
     "koffi": "3.1.1",
     "node-pty": "1.2.0-beta.15"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-loader-smoke": "0.2.1-alpha.3",
-    "@deepseek-ai/dsh-subprocess": "0.2.1-alpha.3",
-    "@deepseek-ai/dsh-timeout": "0.2.1-alpha.3",
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
+    "@deepseek-ai/dsh-loader-smoke": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-subprocess": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-timeout": "0.2.1-rc.2",
+    "@deepseek-ai/cordis": "~4.0.5"
   },
   "scripts": {
     "postinstall": "node scripts/ensure-spawn-helper.mjs"