@deepseek-ai/dsh-subprocess-local 0.1.6-alpha.1 → 0.1.6-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: 5379aff31cdcf036614a6664ce59330d319bd459
-README.zh.md: f61596ac94b7f1270275cb93593c90a281c9ca90
+README.md: 24480565de2f324a451dfdb40101eb50703b30b6
+README.zh.md: c86a7eb930834d960fa25dd7b5d175af63d0b31a

package/README.md

@@ -40,6 +40,8 @@ Load the provider in the same composition as its consumers. It has no config fie
 
 Absolute executable paths are verified; bare names resolve against the scrubbed PATH with platform-aware executable extensions (`.COM`/`.EXE`/`.BAT`/`.CMD` on Windows). Relative paths containing separators are rejected — provide an absolute path or a bare PATH name — and relative PATH entries resolve from the host process cwd.
 
+Windows ordinary subprocesses start the private Job runner with `windowsHide` and request hidden initial windows for native targets. Standard streams and Job ownership remain independent of window visibility; commands that explicitly create their own windows are outside this guarantee.
+
 ### 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.
@@ -50,10 +52,15 @@ The `./output` export shares this collector and retained-spill storage with proc
 
 An ordinary spawn can request the [subprocess control pipe](../subprocess/README.md#using-a-control-pipe). A Node target receives fd 7 on every supported host; Windows descriptor numbering requires CRT initialization. POSIX runners preserve that descriptor across `execve`; Windows Job and ACL runners establish it in the child's CRT startup table before Node initializes and close their own carrier copies after spawning. Standard streams and the runner's private management channel remain independent.
 
+<a id="running-terminal-sessions"></a>
 ### Running terminal sessions
 
 `spawnTerminal` allocates a real PTY and bridges UTF-8 text; you can inspect and signal the current foreground process group and await one `terminate()` operation. On supported Linux hosts, the original terminal argv runs directly inside a user-systemd scope, preserving the node-pty PID, session leader, controlling terminal, foreground `inputWaiting`, and readiness while the scope owns reparented or `setsid` descendants. On fallback hosts, cleanup retains exact identities from the rooted tree and observable session but cannot recover every escaped descendant. An exact Linux input wait requires a foreground thread whose fd 0 identifies the shell's controlling terminal and whose current syscall waits on that fd; if the kernel denies the syscall probe, the higher PTY backend uses its idle inference instead. On Windows, SIGINT is delivered as a Ctrl-C input write, SIGTSTP and SIGHUP are unsupported, and teardown verifies the shell's termination through the process table because an externally killed shell may never fire the PTY exit notification.
 
+With `shellActivity: true`, plain non-login `bash -i` and `zsh -i` launches install private lifecycle records while retaining user startup files and prompt configuration. Bash requires version 4.4 or later and writable prompt hooks; Zsh observes an empty top-level ZLE prompt, excluding `vared`, selection and continuation prompts. Input, shell transitions and changed process observations advance activity revisions. Foreground, background and stopped descendants block idle; native Linux also requires exactly one task in the systemd scope, including ownership beyond the process tree; incomplete process-table scans, custom traps and Zsh asynchronous descriptor handlers yield unknown. A failure to enumerate the process table rejects the observation; activity remains unknown and cleanup retains ownership until a readable table permits verification. Private files are removed after successful process cleanup. Other shells, Windows, custom arguments and sandbox-wrapped executables remain usable with unknown activity.
+
+Opted-in root exit does not terminate surviving descendants. A confirmed empty Linux managed range or complete empty Linux session can authorize reclamation of its retained record; macOS cannot confirm an unobserved process range after root exit and keeps that record unknown. The existing fallback visibility limits still apply: shell lifecycle records do not make escaped, unobserved descendants discoverable. Lifecycle records coordinate ordinary shell behavior, not hostile same-user processes.
+
 ### Shutdown behavior
 
 Normal disposal terminates every running managed range and terminal session and awaits quiescence. During a JavaScript-observable host exit — direct `process.exit()`, default uncaught exceptions, default unhandled rejections — synchronous finalization asks a Linux scope to kill its members, kills each Windows runner so its sole Job handle closes, and uses the existing PGID, `taskkill`, or captured-identity operation for fallbacks. It creates no promises or timers and does not claim quiescence. The same exit removes the private per-process spill directory when it holds no completed spill file; completed spill files remain as full-output recovery artifacts until an external cleanup. Unhandled `SIGTERM`/`SIGINT`/`SIGHUP`, `SIGKILL`, fatal OOM, native crashes, and power loss need an external supervisor.

package/README.zh.md

@@ -40,6 +40,8 @@ kind: "package-reference"
 
 绝对可执行文件路径会被验证；裸名称根据清理后的 PATH 并以平台感知的可执行文件扩展名（Windows 上为 `.COM`/`.EXE`/`.BAT`/`.CMD`）解析。含分隔符的相对路径会被拒绝——请提供绝对路径或裸 PATH 名称——相对 PATH 条目从宿主进程 cwd 解析。
 
+Windows 普通子进程通过 `windowsHide` 启动私有 Job runner，并为原生目标请求隐藏初始窗口。标准流和 Job 归属不依赖窗口可见性；显式创建自身窗口的命令不在此保证范围内。
+
 ### 收集输出
 
 收集模式在内存中保留一条流的最后 `maxBytes`——错误与最终结果通常聚集在末尾——并在配置了 `spill` 上限时把完整流追加到 OS 临时目录下每进程目录中的私有文件（`0700` 目录、`0600` 随机命名文件）。某条流大于 spill 上限时，会丢弃不完整的 spill，只返回带截断标记的尾部。读取基于偏移量且从不消费，因此后台读取与批量读取在退出前后都可以共存。
@@ -50,10 +52,15 @@ kind: "package-reference"
 
 普通 spawn 可以请求 [subprocess 控制管道](../subprocess/README.zh.md#using-a-control-pipe)。Node 目标在所有受支持的宿主上均收到 fd 7；Windows 描述符编号依赖 CRT 初始化。POSIX runner 在 `execve` 时保留该描述符；Windows Job 和 ACL runner 在 Node 初始化前通过子进程的 CRT 启动表建立它，并在 spawn 后关闭自身的承载副本。标准流与 runner 的私有管理通道保持独立。
 
+<a id="running-terminal-sessions"></a>
 ### 运行终端会话
 
 `spawnTerminal` 分配真实 PTY 并桥接 UTF-8 文本；你可以检查当前前台进程组并向其发送信号，还可以等待一次 `terminate()` 操作。在受支持的 Linux 宿主上，原始终端 argv 直接在 user-systemd scope 内运行；node-pty PID、会话 leader、控制终端、前台 `inputWaiting` 与就绪状态保持不变，而 scope 会拥有已重新设定父进程或调用 `setsid` 的后代。在 fallback 宿主上，清理会保留根进程树和可观察会话中的精确身份，但无法重新发现每个已经逃逸的后代。Linux 的精确输入等待要求前台线程的 fd 0 标识 shell 的控制终端，且线程当前的 syscall 正在等待该 fd；如果内核拒绝 syscall 探测，上层 PTY 后端会改用空闲推断。在 Windows 上，SIGINT 以 Ctrl-C 输入写入投递，SIGTSTP 与 SIGHUP 不受支持，拆卸会通过进程表验证 shell 已终止，因为被外部终止的 shell 可能永远不会触发 PTY 退出通知。
 
+使用 `shellActivity: true` 时，普通非登录的 `bash -i` 与 `zsh -i` 会安装私有生命周期记录，同时保留用户启动文件和提示符配置。Bash 需要 4.4 或更高版本，并允许写入提示符 hook；Zsh 观察空的顶层 ZLE 提示符，排除 `vared`、选择和续行提示符。输入、shell 状态迁移和进程观察变化都会推进活动 revision。前台、后台及停止的后代任务阻止空闲判断；原生 Linux 还要求 systemd scope 中恰好只有一个 task，覆盖进程树以外仍归其所有的工作；进程表扫描不完整、自定义 trap 和 Zsh 异步文件描述符 handler 会返回 unknown。进程表枚举失败会拒绝本次观察；活动保持 unknown，清理保留所有权，直到进程表可读并能完成验证。进程清理成功后删除私有文件。其他 shell、Windows、自定义参数以及经 sandbox 包装的可执行文件仍可使用，但活动为 unknown。
+
+启用后，根进程退出不会终止仍在运行的后代。明确为空的 Linux 受管范围或完整且为空的 Linux 会话可允许回收保留的记录；macOS 无法在根进程退出后确认未观察到的进程范围，会将该记录保持为 unknown。原有 fallback 可见性限制仍然适用：shell 生命周期记录不能让已逃逸且未观察到的后代变得可发现。这些记录协调普通 shell 行为，不用于防御同一用户的恶意进程。
+
 ### 关闭行为
 
 正常 dispose 会终止每个仍在运行的受管范围与终端会话并等待其完全停稳。在 JavaScript 可观察的宿主退出期间——直接 `process.exit()`、默认未捕获异常、默认未处理 rejection——同步最终清理会请求 Linux scope 终止其成员，同步终止每个 Windows runner 以关闭其唯一 Job handle，并为 fallback 使用既有 PGID、`taskkill` 或已捕获身份操作。它不创建 Promise 或定时器，也不声称已经完全停稳。同一退出阶段会删除未持有任何已完成 spill 文件的每进程私有 spill 目录；已完成的 spill 文件作为完整输出恢复产物保留，直到外部机制清理。未处理的 `SIGTERM`/`SIGINT`/`SIGHUP`、`SIGKILL`、fatal OOM、native crash 与断电需要外部 supervisor。

package/lib/index.js

@@ -1,10 +1,10 @@
-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-BnjugUhn.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-DGV26RBf.js";
 import { prepareManagedProcessBinding } from "./output.js";
-import { closeSync, constants, existsSync, openSync } from "node:fs";
+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, userInfo } from "node:os";
-import { delimiter, extname, isAbsolute, resolve } from "node:path";
-import * as nodePty from "node-pty";
+import { constants as constants$1, devNull, tmpdir, userInfo } from "node:os";
+import { basename, delimiter, extname, isAbsolute, join, resolve } from "node:path";
+import { createLazyRequire } from "@deepseek-ai/dsh-lazy-require";
 import { SubprocessExecutableNotFoundError, SubprocessRuntime } from "@deepseek-ai/dsh-subprocess";
 import { execFile, spawn, spawnSync } from "node:child_process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
@@ -159,6 +159,23 @@ var SystemdScopeOwner = class {
 		this.query = query;
 		this.sleep = sleep;
 	}
+	inspectTaskCount() {
+		const result = this.runSync(this.systemctl, [
+			"--user",
+			"show",
+			"--property=LoadState",
+			"--property=ActiveState",
+			"--property=TasksCurrent",
+			this.unit
+		], {
+			encoding: "utf8",
+			env: managerEnvironment(),
+			timeout: SYSTEMCTL_TIMEOUT_MS
+		});
+		if (result.error !== void 0 || result.status !== 0 || typeof result.stdout !== "string") return void 0;
+		const state = this.parseUnitState(result.stdout);
+		return state.loadState === "loaded" && state.activeState === "active" ? state.tasksCurrent : void 0;
+	}
 	signal(signal) {
 		if (this.stopped) return;
 		this.terminationRequested = true;
@@ -580,6 +597,7 @@ function launchWindowsJob(spec, targetEnv, internals = {}) {
 			...spec.argv
 		], {
 			cwd: process.cwd(),
+			windowsHide: true,
 			env: runnerEnvironment(WINDOWS_RUNNER_SELECTION, invocation),
 			stdio: runnerStdio(spec, true, ignoredStdinFd ?? "pipe")
 		});
@@ -723,6 +741,9 @@ var LocalTerminalHandle = class {
 	platform;
 	managedOwner;
 	resolveManagedOutcome;
+	shellActivity;
+	onQuiescence;
+	observeShellExit;
 	pid;
 	output = new PassThrough();
 	done;
@@ -734,6 +755,10 @@ var LocalTerminalHandle = class {
 	exited = false;
 	outputPaused = false;
 	trackedDescendants = [];
+	activityRevision = 0;
+	activityKey = "";
+	quiescent = false;
+	managedRangeEmpty = false;
 	/** The spawned shell's start identity; scans stop adopting members once the root pid no longer carries it. */
 	rootIdentity;
 	/**
@@ -742,15 +767,22 @@ var LocalTerminalHandle = class {
 	* @param graceMs - TERM-to-KILL and exit-wait grace.
 	* @param platform - host platform; defaults to the running platform, injectable for deterministic tests.
 	*/
-	constructor(terminal, inspector, graceMs, platform = process.platform, managedOwner, resolveManagedOutcome) {
+	constructor(terminal, inspector, graceMs, platform = process.platform, managedOwner, resolveManagedOutcome, shellActivity, onQuiescence, observeShellExit = false) {
 		this.terminal = terminal;
 		this.inspector = inspector;
 		this.graceMs = graceMs;
 		this.platform = platform;
 		this.managedOwner = managedOwner;
 		this.resolveManagedOutcome = resolveManagedOutcome;
+		this.shellActivity = shellActivity;
+		this.onQuiescence = onQuiescence;
+		this.observeShellExit = observeShellExit;
 		this.pid = terminal.pid;
-		this.rootIdentity = inspector.snapshot().tree(this.pid).find((member) => member.pid === this.pid);
+		try {
+			this.rootIdentity = inspector.snapshot().tree(this.pid).find((member) => member.pid === this.pid);
+		} catch (_rootIdentityUnavailable) {
+			this.rootIdentity = void 0;
+		}
 		this.done = this.outcome.promise;
 		const resume = () => {
 			if (!this.outputPaused) return;
@@ -770,6 +802,9 @@ var LocalTerminalHandle = class {
 		this.exitDisposable = terminal.onExit(({ exitCode, signal: exitSignal }) => {
 			if (this.exited) return;
 			this.exited = true;
+			if (this.managedOwner !== void 0 && this.observeShellExit) this.managedOwner.waitForExit().then(() => {
+				this.managedRangeEmpty = true;
+			}).catch(() => {});
 			this.output.end();
 			const outcome = {
 				exitCode: exitSignal === void 0 || exitSignal === 0 ? exitCode : null,
@@ -788,6 +823,7 @@ var LocalTerminalHandle = class {
 	}
 	async write(data) {
 		if (this.exited) throw new Error("terminal process has exited");
+		this.shellActivity?.invalidate();
 		this.terminal.write(data);
 	}
 	async resize(cols, rows) {
@@ -803,7 +839,44 @@ var LocalTerminalHandle = class {
 			inputWaiting: this.inspector.isStdinWaiting(processGroupId, this.pid)
 		};
 	}
+	async inspectActivity() {
+		let state = this.quiescent ? "idle" : "unknown";
+		let revision = 0;
+		if (!this.quiescent) try {
+			const shell = this.shellActivity?.inspect(this.pid) ?? {
+				state: "unknown",
+				revision: 0
+			};
+			revision = shell.revision;
+			const observed = this.inspector.snapshot();
+			const descendants = this.descendants(observed);
+			const root = observed.tree(this.pid).find((member) => member.pid === this.pid);
+			if (this.exited && this.managedRangeEmpty) state = "idle";
+			else if (descendants.length > 0) state = "busy";
+			else if (this.exited && this.managedOwner === void 0 && this.platform === "linux" && observed.complete === true && root === void 0) state = observed.session(this.pid).some((member) => observed.alive(member)) ? "busy" : "idle";
+			else if (observed.complete === true && root?.started === this.rootIdentity?.started && root !== void 0) {
+				const foreground = this.inspector.foregroundPgid(this.pid);
+				state = foreground === void 0 ? "unknown" : foreground === this.pid ? shell.state : "busy";
+				if (state === "idle" && this.managedOwner !== void 0) {
+					const tasks = this.managedOwner.inspectTaskCount?.();
+					state = tasks === void 0 || tasks < 1 ? "unknown" : tasks === 1 ? "idle" : "busy";
+				}
+			}
+		} catch (_incompleteActivityObservation) {
+			state = "unknown";
+		}
+		const key = `${revision}:${state}`;
+		if (key !== this.activityKey) {
+			this.activityKey = key;
+			this.activityRevision++;
+		}
+		return {
+			state,
+			revision: this.activityRevision
+		};
+	}
 	async signalForeground(signal) {
+		this.shellActivity?.invalidate();
 		const foreground = await this.inspectForeground();
 		if (foreground === void 0) throw new Error(`cannot resolve foreground process group for terminal ${this.pid}`);
 		if (signal === "SIGKILL" && foreground.processGroupId === this.pid) throw new Error("refusing to SIGKILL the terminal shell; terminate the terminal session instead");
@@ -823,7 +896,11 @@ var LocalTerminalHandle = class {
 			this.outputPaused = false;
 			this.terminal.resume();
 		}
-		const cleanup = this.closeOnce();
+		const cleanup = this.closeOnce().then(() => {
+			this.quiescent = true;
+			this.shellActivity?.dispose();
+			this.onQuiescence?.();
+		});
 		this.cleanup = cleanup;
 		cleanup.catch(() => {
 			this.cleanup = void 0;
@@ -1013,6 +1090,164 @@ var LocalTerminalHandle = class {
 	}
 };
 //#endregion
+//#region lib/types/shell-activity.js
+/** Private shell lifecycle files; ordinary output never authorizes terminal reclamation. */
+function quote(value) {
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+/** Opt-in startup integration and revision tracking for one ordinary interactive shell. */
+var ShellActivity = class {
+	directory;
+	argv;
+	env;
+	revision = 0;
+	observed = "";
+	invalidated;
+	state = "unknown";
+	/**
+	* @param directory - private startup and status file directory.
+	* @param argv - shell launch preserving supported user startup files.
+	* @param env - environment with any temporary startup redirect.
+	*/
+	constructor(directory, argv, env) {
+		this.directory = directory;
+		this.argv = argv;
+		this.env = env;
+	}
+	/** Invalidate prompt evidence before delivering input or a foreground signal. */
+	invalidate() {
+		this.invalidated = this.read();
+		this.revision++;
+		this.state = "unknown";
+	}
+	/**
+	* Read the latest top-level shell transition, fenced against input since that transition.
+	* @param pid - original shell process id.
+	* @returns lifecycle evidence; process ownership must be checked separately.
+	*/
+	inspect(pid) {
+		const record = this.read();
+		if (record !== this.observed) {
+			this.observed = record;
+			this.revision++;
+		}
+		const match = /^(\d+):(\d+):(idle|busy)\n?$/u.exec(record);
+		this.state = record === this.invalidated || match?.[1] !== String(pid) ? "unknown" : match[3];
+		return {
+			state: this.state,
+			revision: this.revision
+		};
+	}
+	/** Remove private startup and status files after process quiescence. */
+	dispose() {
+		rmSync(this.directory, {
+			recursive: true,
+			force: true
+		});
+	}
+	read() {
+		try {
+			return readFileSync(join(this.directory, "state"), "utf8");
+		} catch (_unavailableShellObservation) {
+			return "";
+		}
+	}
+};
+/**
+* Prepare optional Bash or Zsh integration for a plain, non-login interactive launch.
+* @param spec - terminal request; custom arguments and wrapped executables remain unmodified.
+* @param env - scrubbed target environment.
+* @param platform - execution platform.
+* @returns private integration, or undefined for unsupported launches.
+*/
+function prepareShellActivity(spec, env, platform) {
+	if (spec.shellActivity !== true || platform === "win32" || spec.argv.length !== 2 || spec.argv[1] !== "-i") return void 0;
+	const shell = basename(spec.argv[0]);
+	if (shell !== "bash" && shell !== "zsh") return void 0;
+	const directory = mkdtempSync(join(tmpdir(), "dsh-shell-"));
+	const state = quote(join(directory, "state"));
+	const guards = quote(join(directory, "guards"));
+	try {
+		if (shell === "bash") {
+			const rc = join(directory, "bashrc");
+			writeFileSync(rc, [
+				"[[ ! -r ~/.bashrc ]] || builtin source ~/.bashrc",
+				"if (( BASH_VERSINFO[0] > 4 || (BASH_VERSINFO[0] == 4 && BASH_VERSINFO[1] >= 4) )) && [[ ! $(declare -p PROMPT_COMMAND PS0 2>/dev/null) =~ declare\\ -[^[:space:]]*r ]]; then",
+				"  __dsh_shell_pid=$BASHPID; __dsh_shell_sequence=0",
+				"  __dsh_shell_idle() {",
+				"    local result=$?",
+				"    if [[ $BASHPID == \"$__dsh_shell_pid\" ]]; then",
+				"      (( ++__dsh_shell_sequence ))",
+				"      local activity=idle",
+				`      builtin trap -p >| ${guards}`,
+				`      [[ ! -s ${guards} ]] || activity=unknown`,
+				`      builtin printf '%s:%s:%s\\n' "$BASHPID" "$__dsh_shell_sequence" "$activity" >| ${state}`,
+				"    fi",
+				"    return \"$result\"",
+				"  }",
+				"  if [[ $(declare -p PROMPT_COMMAND 2>/dev/null) == \"declare -a \"* ]]; then",
+				"    PROMPT_COMMAND+=(__dsh_shell_idle)",
+				"  else",
+				"    PROMPT_COMMAND=\"${PROMPT_COMMAND}\"$'\\n'\"__dsh_shell_idle\"",
+				"  fi",
+				`  PS0+=${quote(`$(builtin printf '%s:%s:busy' "$__dsh_shell_pid" "$__dsh_shell_sequence" >| ${state})`)}`,
+				"fi",
+				""
+			].join("\n"), {
+				mode: 384,
+				flag: "wx"
+			});
+			return new ShellActivity(directory, [
+				spec.argv[0],
+				"--rcfile",
+				rc,
+				"-i"
+			], env);
+		}
+		writeFileSync(join(directory, ".zshenv"), [
+			env.ZDOTDIR === void 0 ? "unset ZDOTDIR" : `ZDOTDIR=${quote(env.ZDOTDIR)}`,
+			"[[ ! -r ${ZDOTDIR:-$HOME}/.zshenv ]] || builtin source \"${ZDOTDIR:-$HOME}/.zshenv\"",
+			"typeset -g __dsh_shell_pid=$$ __dsh_shell_sequence=0",
+			"__dsh_shell_activity() {",
+			"  (( ZSH_SUBSHELL == 0 && $$ == __dsh_shell_pid )) || return",
+			"  (( ++__dsh_shell_sequence ))",
+			`  builtin printf '%s:%s:%s\\n' "$$" "$__dsh_shell_sequence" "$1" >| ${state}`,
+			"  return 0",
+			"}",
+			"__dsh_shell_idle() {",
+			`  { builtin trap; zle -F; } >| ${guards}`,
+			"  if [[ $CONTEXT != start || -n $BUFFER ]]; then __dsh_shell_activity busy",
+			`  elif [[ -s ${guards} || -n \${(k)functions[(I)TRAP*]} ]]; then __dsh_shell_activity unknown`,
+			"  else __dsh_shell_activity idle; fi",
+			"}",
+			"__dsh_shell_busy() { __dsh_shell_activity busy }",
+			"__dsh_shell_init() {",
+			"  autoload -Uz add-zle-hook-widget add-zsh-hook",
+			"  add-zle-hook-widget line-init __dsh_shell_idle",
+			"  add-zle-hook-widget line-finish __dsh_shell_busy",
+			"  add-zsh-hook preexec __dsh_shell_busy",
+			"  precmd_functions=(${precmd_functions:#__dsh_shell_init})",
+			"}",
+			"typeset -ga precmd_functions",
+			"precmd_functions+=(__dsh_shell_init)",
+			""
+		].join("\n"), {
+			mode: 384,
+			flag: "wx"
+		});
+		return new ShellActivity(directory, spec.argv, {
+			...env,
+			ZDOTDIR: directory
+		});
+	} catch (error) {
+		rmSync(directory, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Local Service Provider for the subprocess capability seam. Each spawn owns a
@@ -1023,6 +1258,7 @@ var LocalTerminalHandle = class {
 * stay with the caller's config (the bash executor's, the LSP host's, …).
 * @module @deepseek-ai/dsh-subprocess-local
 */
+const requireNodePty = createLazyRequire("node-pty", import.meta.url);
 /**
 * Local subprocess service: platform-selected managed ranges, Node-shaped stdio
 * dispositions (raw pipes, inherit, bounded tail-keep collection with spill
@@ -1174,32 +1410,41 @@ var LocalSubprocessRuntime = class extends SubprocessRuntime {
 		const file = spec.argv[0];
 		if (file === void 0 || file.length === 0) throw new Error("subprocess-local: terminal argv must contain a program");
 		spec.signal?.throwIfAborted();
+		const inspector = this.terminalInspector ?? createProcessInspector();
+		const containmentMode = this.selectContainmentMode("terminal");
 		const env = targetEnvironment(spec);
+		const activity = prepareShellActivity(spec, env, this.internals.platform ?? process.platform);
+		const launch = activity === void 0 ? spec : {
+			...spec,
+			argv: activity.argv,
+			env: activity.env
+		};
 		const options = {
 			name: spec.terminalType,
 			rows: spec.rows,
 			cols: spec.cols,
 			cwd: spec.cwd,
 			env: {
-				...env,
+				...activity?.env ?? env,
 				TERM: spec.terminalType
 			}
 		};
-		const inspector = this.terminalInspector ?? createProcessInspector();
-		const scope = this.selectContainmentMode("terminal") === "linux-scope" ? prepareLinuxTerminalScope(spec, {
-			...env,
-			PWD: spec.cwd,
-			TERM: spec.terminalType
-		}) : void 0;
-		if (scope !== void 0) {
-			options.cwd = scope.cwd;
-			options.env = scope.env;
-		}
+		let scope;
 		let terminal;
 		try {
-			terminal = nodePty.spawn(scope?.command ?? file, scope?.args ?? [...spec.argv.slice(1)], options);
+			scope = containmentMode === "linux-scope" ? prepareLinuxTerminalScope(launch, {
+				...activity?.env ?? env,
+				PWD: spec.cwd,
+				TERM: spec.terminalType
+			}) : void 0;
+			if (scope !== void 0) {
+				options.cwd = scope.cwd;
+				options.env = scope.env;
+			}
+			terminal = requireNodePty().spawn(scope?.command ?? file, scope?.args ?? [...launch.argv.slice(1)], options);
 		} catch (error) {
 			scope?.cleanup();
+			activity?.dispose();
 			throw error;
 		}
 		let handle;
@@ -1209,10 +1454,13 @@ var LocalSubprocessRuntime = class extends SubprocessRuntime {
 			settled: directSettlement.promise,
 			signal: (signal) => signalLinuxDirectProcess(terminal.pid, () => process.kill(terminal.pid, signal))
 		});
-		handle = new LocalTerminalHandle(terminal, inspector, spec.graceMs, this.internals.platform ?? process.platform, owner, scope?.resolveOutcome);
+		handle = new LocalTerminalHandle(terminal, inspector, spec.graceMs, this.internals.platform ?? process.platform, owner, scope?.resolveOutcome, activity, () => {
+			this.terminals.delete(handle);
+		}, spec.shellActivity === true);
 		this.terminals.add(handle);
 		const release = async () => {
 			directSettlement.resolve();
+			if (spec.shellActivity === true) return;
 			await handle.terminate();
 			this.terminals.delete(handle);
 		};

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

@@ -2,12 +2,12 @@ import { OutputCollector, prepareManagedProcessBinding } from "./output.js";
 import { accessSync, chmodSync, closeSync, constants, existsSync, lstatSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, extname, isAbsolute, join } from "node:path";
+import { createLazyRequire } from "@deepseek-ai/dsh-lazy-require";
 import { scrubbedParentEnv } from "@deepseek-ai/dsh-subprocess";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
 import { SUBPROCESS_CONTROL_ENV, SUBPROCESS_CONTROL_FD } from "@deepseek-ai/dsh-subprocess/control";
-import koffi from "koffi";
 import { getSystemErrorMessage, getSystemErrorName, inspect } from "node:util";
 import { fileURLToPath } from "node:url";
 //#region lib/types/managed-owner.js
@@ -74,6 +74,7 @@ function controlEnvironment(env, control) {
 * an injectable internals boundary so suites can pin it on any host.
 * @module dsh-subprocess-local/windows-inspector
 */
+const requireKoffi$1 = createLazyRequire("koffi", import.meta.url);
 /**
 * Walk a process table from one root in children-first order, retaining only
 * members whose start identity is readable (unreadable members are detector
@@ -175,7 +176,6 @@ function isInvalidHandle(value) {
 	const asBigInt = value;
 	return asBigInt === 0n || asBigInt === 18446744073709551615n || asBigInt === -1n;
 }
-const PVOID = koffi.pointer("void");
 /**
 * Resolve the koffi Win32 struct types once. Registration is lazy and cached
 * because koffi's type registry is global per process: test runners that
@@ -184,6 +184,8 @@ const PVOID = koffi.pointer("void");
 */
 function win32Structs() {
 	if (cachedStructs !== void 0) return cachedStructs;
+	const koffi = requireKoffi$1();
+	const PVOID = koffi.pointer("void");
 	const PROCESSENTRY32W = koffi.struct("PROCESSENTRY32W", {
 		dwSize: "uint32",
 		cntUsage: "uint32",
@@ -204,6 +206,7 @@ function win32Structs() {
 	if (PROCESSENTRY32W.size !== 568) throw new Error(`PROCESSENTRY32W layout mismatch: koffi computed ${PROCESSENTRY32W.size}, Windows headers say 568`);
 	/* v8 ignore stop */
 	cachedStructs = {
+		PVOID,
 		PROCESSENTRY32W,
 		FILETIME
 	};
@@ -220,7 +223,8 @@ let cachedBindings;
 */
 function win32Bindings() {
 	if (cachedBindings !== void 0) return cachedBindings;
-	const { PROCESSENTRY32W, FILETIME } = win32Structs();
+	const koffi = requireKoffi$1();
+	const { PVOID, PROCESSENTRY32W, FILETIME } = win32Structs();
 	const kernel32 = koffi.load("kernel32.dll");
 	const bind = (name, result, args) => kernel32.func("__stdcall", name, result, args);
 	cachedBindings = {
@@ -252,10 +256,11 @@ function win32Bindings() {
 * @returns the branded allocation pointer.
 */
 function allocNative(type, count) {
-	return koffi.alloc(type, count);
+	return requireKoffi$1().alloc(type, count);
 }
 /** Enumerate the current process table through Toolhelp32. */
 function snapshotWindowsProcesses(bindings) {
+	const koffi = requireKoffi$1();
 	const { PROCESSENTRY32W } = win32Structs();
 	const snapshot = bindings.createToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0);
 	/* v8 ignore next -- an invalid snapshot for the process flag is not producible through the public API;
@@ -281,6 +286,7 @@ function snapshotWindowsProcesses(bindings) {
 }
 /** Read one process's creation identity and current wait state. */
 function windowsProcessState(bindings, pid) {
+	const koffi = requireKoffi$1();
 	const { FILETIME } = win32Structs();
 	const handle = bindings.openProcess(1052672, 0, pid);
 	if (isInvalidHandle(handle)) return void 0;
@@ -417,7 +423,7 @@ function numericEntries(internals, path) {
 	try {
 		return internals.readDir(path).filter((entry) => /^\d+$/.test(entry)).map(Number);
 	} catch (_unreadableProcDirectory) {
-		return [];
+		return;
 	}
 }
 function readSyscall(internals, pid, tid) {
@@ -516,9 +522,11 @@ function quiescent(state) {
 }
 var PosixProcessSnapshot = class {
 	rows;
+	complete;
 	byPid;
-	constructor(rows) {
+	constructor(rows, complete) {
 		this.rows = rows;
+		this.complete = complete;
 		this.byPid = new Map(rows.map((row) => [row.pid, row]));
 	}
 	tree(rootPid) {
@@ -575,10 +583,10 @@ var LinuxProcessInspector = class extends PosixProcessInspector {
 		if (shell === void 0) return false;
 		const terminalDevice = readLinuxTerminalDevice(this.internals, shellPid, shell.ttyDevice);
 		if (terminalDevice === void 0) return false;
-		for (const pid of numericEntries(this.internals, "/proc")) {
+		for (const pid of numericEntries(this.internals, "/proc") ?? []) {
 			const process = readLinuxStat(this.internals, pid);
 			if (process?.pgrp !== pgid) continue;
-			for (const tid of numericEntries(this.internals, `/proc/${pid}/task`)) {
+			for (const tid of numericEntries(this.internals, `/proc/${pid}/task`) ?? []) {
 				const syscall = readSyscall(this.internals, pid, tid);
 				if (syscall !== void 0 && syscallWaitsOnStdin(this.internals, pid, tid, syscall, tables) && readLinuxTerminalDevice(this.internals, pid, process.ttyDevice, tid) === terminalDevice) return true;
 			}
@@ -590,8 +598,12 @@ var LinuxProcessInspector = class extends PosixProcessInspector {
 		return stat?.started === identity.started && !quiescent(stat.state);
 	}
 	snapshot() {
-		return new PosixProcessSnapshot(numericEntries(this.internals, "/proc").flatMap((pid) => {
+		const pids = numericEntries(this.internals, "/proc");
+		if (pids === void 0) throw new Error("Cannot inspect processes: /proc directory is unreadable");
+		let complete = true;
+		return new PosixProcessSnapshot(pids.flatMap((pid) => {
 			const stat = readLinuxStat(this.internals, pid);
+			if (stat === void 0) complete = false;
 			return stat === void 0 ? [] : [{
 				pid,
 				parentPid: stat.parentPid,
@@ -599,21 +611,28 @@ var LinuxProcessInspector = class extends PosixProcessInspector {
 				session: stat.session,
 				state: stat.state
 			}];
-		}));
+		}), complete);
 	}
 };
 function macProcessTable(internals) {
-	return internals.exec("/bin/ps", ["-axo", "pid=,ppid=,lstart="]).split("\n").flatMap((line) => {
-		const match = /^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/.exec(line);
-		if (match?.[1] === void 0 || match[2] === void 0 || match[3] === void 0) return [];
-		return [{
-			pid: Number(match[1]),
-			parentPid: Number(match[2]),
-			started: match[3],
-			session: void 0,
-			state: void 0
-		}];
-	});
+	let complete = true;
+	return {
+		rows: internals.exec("/bin/ps", ["-axo", "pid=,ppid=,lstart="]).split("\n").flatMap((line) => {
+			const match = /^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/.exec(line);
+			if (match?.[1] === void 0 || match[2] === void 0 || match[3] === void 0) {
+				if (line.trim().length > 0) complete = false;
+				return [];
+			}
+			return [{
+				pid: Number(match[1]),
+				parentPid: Number(match[2]),
+				started: match[3],
+				session: void 0,
+				state: void 0
+			}];
+		}),
+		complete
+	};
 }
 var MacProcessInspector = class extends PosixProcessInspector {
 	foregroundPgid(shellPid) {
@@ -633,10 +652,11 @@ var MacProcessInspector = class extends PosixProcessInspector {
 		return false;
 	}
 	isAlive(identity) {
-		return macProcessTable(this.internals).some((entry) => entry.pid === identity.pid && entry.started === identity.started);
+		return macProcessTable(this.internals).rows.some((entry) => entry.pid === identity.pid && entry.started === identity.started);
 	}
 	snapshot() {
-		return new PosixProcessSnapshot(macProcessTable(this.internals));
+		const table = macProcessTable(this.internals);
+		return new PosixProcessSnapshot(table.rows, table.complete);
 	}
 };
 /**
@@ -1028,6 +1048,7 @@ function spawnSubprocess(spec, internals = {}) {
 //#endregion
 //#region lib/types/linux-execve.js
 /** Lazy libc execve and descriptor bindings used by the one-shot Linux bootstrap. */
+const requireKoffi = createLazyRequire("koffi", import.meta.url);
 const STANDARD_FILE_DESCRIPTORS = [
 	0,
 	1,
@@ -1055,6 +1076,7 @@ function systemError(errno, syscall, path) {
 */
 function loadLinuxExecve() {
 	if (cachedExecve !== void 0) return cachedExecve;
+	const koffi = requireKoffi();
 	const libc = koffi.load(null);
 	const nativeExecve = libc.func("int execve(const char *pathname, const char **argv, const char **envp)");
 	const nativeFcntl = libc.func("int fcntl(int fd, int cmd, int arg)");

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-BnjugUhn.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-DGV26RBf.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/managed-owner.d.ts

@@ -7,6 +7,11 @@ export interface BoundProcessOwner {
     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. */

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

@@ -25,6 +25,8 @@ interface FileStatus {
  * is the fence a signal takes, because it reads current state instead.
  */
 export interface ProcessSnapshot {
+    /** Whether the process-table scan omitted no unreadable rows; absent means unverified. */
+    readonly complete?: boolean;
     /**
      * Return the root and its transitive descendants as observed, children first.
      * @param rootPid - tree root to descend from.
@@ -58,6 +60,7 @@ export interface ProcessInspector {
     /**
      * Read the process table once and answer tree, session, and liveness from it.
      * @returns A process-table observation whose reads are shared.
+     * @throws when the platform process table cannot be enumerated.
      */
     snapshot(): ProcessSnapshot;
     /**

package/lib/types/shell-activity.d.ts

@@ -0,0 +1,37 @@
+import type { SubprocessTerminalActivity, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/** Opt-in startup integration and revision tracking for one ordinary interactive shell. */
+export declare class ShellActivity {
+    private readonly directory;
+    readonly argv: readonly string[];
+    readonly env: Record<string, string>;
+    private revision;
+    private observed;
+    private invalidated;
+    private state;
+    /**
+     * @param directory - private startup and status file directory.
+     * @param argv - shell launch preserving supported user startup files.
+     * @param env - environment with any temporary startup redirect.
+     */
+    constructor(directory: string, argv: readonly string[], env: Record<string, string>);
+    /** Invalidate prompt evidence before delivering input or a foreground signal. */
+    invalidate(): void;
+    /**
+     * Read the latest top-level shell transition, fenced against input since that transition.
+     * @param pid - original shell process id.
+     * @returns lifecycle evidence; process ownership must be checked separately.
+     */
+    inspect(pid: number): SubprocessTerminalActivity;
+    /** Remove private startup and status files after process quiescence. */
+    dispose(): void;
+    private read;
+}
+/**
+ * Prepare optional Bash or Zsh integration for a plain, non-login interactive launch.
+ * @param spec - terminal request; custom arguments and wrapped executables remain unmodified.
+ * @param env - scrubbed target environment.
+ * @param platform - execution platform.
+ * @returns private integration, or undefined for unsupported launches.
+ */
+export declare function prepareShellActivity(spec: SubprocessTerminalSpawnSpec, env: Record<string, string>, platform: NodeJS.Platform): ShellActivity | undefined;
+//# sourceMappingURL=shell-activity.d.ts.map

package/lib/types/terminal.d.ts

@@ -1,9 +1,10 @@
 /** Local node-pty terminal-process implementation for the subprocess seam. */
 import { PassThrough } from 'node:stream';
 import type { IPty } from 'node-pty';
-import type { SubprocessOutcome, SubprocessTerminalForeground, SubprocessTerminalHandle, SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess';
+import type { SubprocessOutcome, SubprocessTerminalActivity, SubprocessTerminalForeground, SubprocessTerminalHandle, SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess';
 import type { BoundProcessOwner } from './managed-owner.ts';
 import type { ProcessInspector } from './process-inspector.ts';
+import type { ShellActivity } from './shell-activity.ts';
 /**
  * A local terminal whose native managed range or fallback process-session
  * ownership stays below the PTY backend.
@@ -20,6 +21,9 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
     private readonly platform;
     private readonly managedOwner?;
     private readonly resolveManagedOutcome?;
+    private readonly shellActivity?;
+    private readonly onQuiescence?;
+    private readonly observeShellExit;
     readonly pid: number;
     readonly output: PassThrough;
     readonly done: Promise<SubprocessOutcome>;
@@ -31,6 +35,10 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
     private exited;
     private outputPaused;
     private trackedDescendants;
+    private activityRevision;
+    private activityKey;
+    private quiescent;
+    private managedRangeEmpty;
     /** The spawned shell's start identity; scans stop adopting members once the root pid no longer carries it. */
     private readonly rootIdentity;
     /**
@@ -39,12 +47,13 @@ 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, managedOwner?: BoundProcessOwner | undefined, resolveManagedOutcome?: ((outcome: SubprocessOutcome) => SubprocessOutcome) | undefined);
+    constructor(terminal: IPty, inspector: ProcessInspector, graceMs: number, platform?: NodeJS.Platform, managedOwner?: BoundProcessOwner | undefined, resolveManagedOutcome?: ((outcome: SubprocessOutcome) => SubprocessOutcome) | undefined, shellActivity?: Pick<ShellActivity, "inspect" | "invalidate" | "dispose"> | undefined, onQuiescence?: (() => void) | undefined, observeShellExit?: boolean);
     /** Whether node-pty has not yet published the top-level exit event. */
     get running(): boolean;
     write(data: string): Promise<void>;
     resize(cols: number, rows: number): Promise<void>;
     inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
+    inspectActivity(): Promise<SubprocessTerminalActivity>;
     signalForeground(signal: SubprocessTerminalSignal): Promise<number>;
     terminate(): Promise<void>;
     /**

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