diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml index 0fe306f43a..83638635ad 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.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 .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md -2026-07-10-single-file-executable-sdk-runtime-distribution.md: 6fbf4ba0c303f8d39a11dfe91ef3ee77f0f31904 -2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: d027d7e015a831d63402de3bfd02694fa542cb90 +2026-07-10-single-file-executable-sdk-runtime-distribution.md: c152345772826ec4e2dbfd238726c429418c7897 +2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: ea5e457afd761cb5071f8b584ef10fa7ffaa8210 diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md index 6fbf4ba0c3..c152345772 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md +++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md @@ -28,7 +28,7 @@ Terminology reminder: pkg's `/snapshot` VFS has nothing to do with this repo's t The deterministic serving surface is a plugin selected by the packaged `dsh` application: - [`packages/sdk/server`](../../../../packages/sdk/server/README.md) (`@deepseek-ai/dsh-sdk-jsonrpc-server`): the pure protocol plugin; on apply it mounts `HarnessSdkJsonRpcServer` plus a line-delimited JSON-RPC transport on the process stdio, with disposal through `ctx.effect()`. Whether to serve is decided by `cordis.yml`; a yml that does not mount it is a legitimate process that does not serve. Protocol-level exit belongs to the plugin (after answering and flushing the `shutdown` response it disposes the root runtime so persistence drains, then `exit(0)`; an HMR-style unload only stops the service without exiting the process). -- [`apps/cli`](../../../../apps/cli/README.md) (`@deepseek-ai/dsh`): the packaged application entry; its `sdk` profile mounts `dsh-sdk-jsonrpc-server`, and the CLI owns environment layering, profile composition, stdin/signal shutdown, and process exit. Before normal argument parsing, the packaged CLI recognizes one reserved private runner argument and dispatches it to `dsh-subprocess-local`, allowing native subprocess containment to re-enter the same executable without assuming `process.execPath` is a general Node binary. +- [`apps/cli`](../../../../apps/cli/README.md) (`@deepseek-ai/dsh`): the packaged application entry; its `sdk` profile mounts `dsh-sdk-jsonrpc-server`, and the CLI owns environment layering, profile composition, stdin/signal shutdown, and process exit. The Python client supplies an explicit Harness home and selects the `sdk` profile plus ordered patch files. A missing home, profile, bundle, or server row fails loudly; there is no external complete-config fallback. The [Python profile-runtime decision](2026-08-23-python-sdk-dsh-profile-runtime.md) owns this application surface. @@ -44,7 +44,7 @@ The deploy root includes `@deepseek-ai/dsh-mcp-client` as an explicitly supporte [`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts): runtime closure verification → `pnpm run build` → (after clearing) `pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **directly into** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/` → restore direct workspace packages omitted by legacy deploy and reject any remaining manifest gap → replace staged dependency symlinks with their target bytes, remove package-manager `.bin` links, and fail if any symlink remains → inject pkg configuration whose bin is `node_modules/@deepseek-ai/dsh/lib/bin.js` and whose assets cover dynamic profile, bundle, frontend, preset, native-library, and configuration reads → stage the target `node-pty` addon → invoke `pkg --sea` once per target → write `deepseek-harness-sdk-runtime--` under `dist-exe/` and copy it into the runtime directory. Linux CI rebuilds `pty.node` inside the matching manylinux 2.28 container because legacy deploy omits that install side effect. Every target copies its native `@vscode/ripgrep` binary beside the executable as the required `-rg` sidecar; pkg runtimes select that sidecar through `process.pkg`, while ordinary Node execution uses `@vscode/ripgrep` directly. macOS uses its target prebuild and also emits the required `-spawn-helper`. All four deploy flags are grounded in measurement: `--legacy` is the mandatory path with inject-workspace-packages off; hoisted gives pkg a stable single-instance layout that the explicit materialization pass makes symlink-free; disabling automatic peer installation prevents undeclared peers from expanding the closure; link-workspace-packages selects direct workspace dependencies. [`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) overrides the transitive `@deepseek-ai/cosmokit` and `@deepseek-ai/schemastery` semver requests to the pinned vendor sources so legacy deploy never resolves those unpublished names from a registry. -CI: [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml) is called for all four targets by the [installed-wheel Python runtime pull-request validation](../testing/2026-08-23-installed-python-wheel-black-box-ci.md) and the [public publication workflow](../process/2026-08-11-python-publication-workflow.md); `workflow_dispatch` can still select a subset. Native builds run on linux-x64 / linux-arm64 (`ubuntu-24.04-arm`) / macos-arm64 / win-x64 (`windows-2025`), with `~/.pkg-cache` cached where applicable, and pkg handles macOS ad-hoc signing. Each leg installs the release-shaped SDK and runtime wheels into a clean venv outside the checkout, proves their package and executable provenance, then drives the complete keyless scenario set through the public SDK and direct NDJSON JSON-RPC; that set invokes the private subprocess runner through the installed single-file executable before exercising application profiles. Trusted pull requests additionally run a real DeepSeek two-turn tool smoke on every target; fork and Dependabot heads receive no key. Linux inspects the executable and native addon's GLIBC requirements and runs an additional manylinux 2.28 smoke, while macOS verifies that the executable's deployment target fits the wheel tag. A full four-target run retains five artifacts, each containing one release file: the platform-independent SDK wheel and four native runtime wheels; a subset dispatch retains the SDK wheel and selected runtime wheels. Bare executables and source bundles remain intermediate test inputs. [`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) accepts `python-v` tag pipelines whose version matches the root `package.json`, builds one SDK wheel and four native runtime wheels, then a single serialized job checks and publishes all five to the project PyPI registry. The [Windows x64 runtime decision](2026-08-23-python-sdk-windows-x64-runtime.md) owns the fourth target and the explicit exclusion of Windows arm64. +CI: [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml) is called for all four targets by the [installed-wheel Python runtime pull-request validation](../testing/2026-08-23-installed-python-wheel-black-box-ci.md) and the [public publication workflow](../process/2026-08-11-python-publication-workflow.md); `workflow_dispatch` can still select a subset. Native builds run on linux-x64 / linux-arm64 (`ubuntu-24.04-arm`) / macos-arm64 / win-x64 (`windows-2025`), with `~/.pkg-cache` cached where applicable, and pkg handles macOS ad-hoc signing. Each leg installs the release-shaped SDK and runtime wheels into a clean venv outside the checkout, proves their package and executable provenance, then drives the complete keyless scenario set through the public SDK and direct NDJSON JSON-RPC. Trusted pull requests additionally run a real DeepSeek two-turn tool smoke on every target; fork and Dependabot heads receive no key. Linux inspects the executable and native addon's GLIBC requirements and runs an additional manylinux 2.28 smoke, while macOS verifies that the executable's deployment target fits the wheel tag. A full four-target run retains five artifacts, each containing one release file: the platform-independent SDK wheel and four native runtime wheels; a subset dispatch retains the SDK wheel and selected runtime wheels. Bare executables and source bundles remain intermediate test inputs. [`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) accepts `python-v` tag pipelines whose version matches the root `package.json`, builds one SDK wheel and four native runtime wheels, then a single serialized job checks and publishes all five to the project PyPI registry. The [Windows x64 runtime decision](2026-08-23-python-sdk-windows-x64-runtime.md) owns the fourth target and the explicit exclusion of Windows arm64. ### Python SDK distribution: two carriers, exe for production, node for development diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md index d027d7e015..ea5e457afd 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md @@ -28,7 +28,7 @@ exe 使用 [@yao-pkg/pkg](https://github.com/yao-pkg/pkg)（vercel/pkg 归档后 确定性服务接口由打包后的 `dsh` 应用选择为插件： - [`packages/sdk/server`](../../../../packages/sdk/server/README.zh.md)（`@deepseek-ai/dsh-sdk-jsonrpc-server`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkJsonRpcServer` 与按行分隔的 JSON-RPC 传输层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答并确保 `shutdown` 响应发送完毕后，对根运行时执行 dispose（资源释放），让待处理的持久化操作完成，再调用 `exit(0)`；HMR（热模块替换）式卸载只停止服务，不退出进程）。 -- [`apps/cli`](../../../../apps/cli/README.zh.md)（`@deepseek-ai/dsh`）：打包后的应用入口；其 `sdk` profile 挂载 `dsh-sdk-jsonrpc-server`，CLI 负责环境分层、profile 组合、stdin／signal 关闭与进程退出。在正常参数解析之前，打包后的 CLI 会识别一个保留的私有 runner 参数并转入 `dsh-subprocess-local`，使 native subprocess containment 可以重新进入同一个可执行文件，而不假定 `process.execPath` 是通用 Node 二进制。 +- [`apps/cli`](../../../../apps/cli/README.zh.md)（`@deepseek-ai/dsh`）：打包后的应用入口；其 `sdk` profile 挂载 `dsh-sdk-jsonrpc-server`，CLI 负责环境分层、profile 组合、stdin／signal 关闭与进程退出。 Python 客户端提供显式 Harness home，并选择 `sdk` profile 与有序 patch 文件。缺失 home、profile、bundle 或 server 配置项都会明确失败；不存在外部完整配置回退。[Python profile 运行时决策](2026-08-23-python-sdk-dsh-profile-runtime.zh.md)负责该应用接口。 @@ -44,7 +44,7 @@ exe 的 VFS 内是**构建产物形态的真实包树**（各包的 `lib/` + 真 [`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts)：运行时闭包校验 → `pnpm run build` →（清空后）`pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **直接写入** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/` → 恢复 legacy deploy 遗漏的直接工作区包，并拒绝剩余的 manifest 缺口 → 将暂存依赖中的符号链接替换为目标文件内容，删除包管理器的 `.bin` 链接，并在仍有任何符号链接时失败 → 注入 pkg 配置，其中 bin 为 `node_modules/@deepseek-ai/dsh/lib/bin.js`，assets 覆盖动态读取的 profile、bundle、前端、preset、原生库与配置文件 → 暂存目标平台的 `node-pty` addon → 每个构建目标调用一次 `pkg --sea` → 将 `deepseek-harness-sdk-runtime--` 写入 `dist-exe/` 并拷回运行时目录。Linux CI 会在匹配的 manylinux 2.28 容器中重新构建 `pty.node`，因为 legacy deploy 会遗漏这一安装副作用。每个目标都会把对应的原生 `@vscode/ripgrep` 二进制复制到可执行文件旁，作为必需的 `-rg` 伴随文件；pkg 运行时通过 `process.pkg` 选择该伴随文件，普通 Node 执行则直接使用 `@vscode/ripgrep`。macOS 使用对应目标的预构建产物，并额外生成所需的 `-spawn-helper`。四个部署标志都有实测依据：未启用 `inject-workspace-packages` 时必须使用 `--legacy`；`hoisted` 为 pkg 提供稳定的单实例布局，再由显式物化步骤消除符号链接；关闭对等依赖自动安装可防止未声明的对等依赖扩大闭包；`link-workspace-packages` 选择直接工作区依赖。[`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) 将传递的 `@deepseek-ai/cosmokit` 与 `@deepseek-ai/schemastery` semver 请求覆盖到固定的 vendor 源码，使 legacy deploy 不会从注册表解析这些未发布名称。 -CI 使用 [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml)：[安装后 wheel Python 运行时拉取请求验证](../testing/2026-08-23-installed-python-wheel-black-box-ci.zh.md)与[公开发布工作流](../process/2026-08-11-python-publication-workflow.zh.md)都会调用它构建全部四个目标；`workflow_dispatch` 仍可选择部分目标。linux-x64、linux-arm64（`ubuntu-24.04-arm`）、macos-arm64 与 win-x64（`windows-2025`）分别进行原生构建，并在适用平台缓存 `~/.pkg-cache`；macOS 的 ad-hoc 签名由 pkg 处理。每个平台都把发布形态的 SDK wheel 包与运行时 wheel 包安装到 checkout 外的干净 venv，证明包与可执行文件来源，再通过公开 SDK 与直接 NDJSON JSON-RPC 运行完整 keyless 场景；该场景集会先通过安装后的单文件可执行程序调用私有 subprocess runner，再验证应用 profile。可信拉取请求还会在每个目标上运行真实 DeepSeek 双轮工具冒烟测试；fork 与 Dependabot head 不会获得密钥。Linux 会检查可执行文件和原生 addon 各自的 GLIBC 依赖，并额外运行 manylinux 2.28 冒烟测试；macOS 则验证可执行文件的部署目标符合 wheel 包标签。完整构建四个目标时保留 5 个产物，每个产物只含一个发布文件：平台无关的 SDK wheel 包与 4 个原生运行时 wheel 包；手动选择部分目标时保留 SDK wheel 与所选运行时 wheel。裸 exe 与源码包只作为测试中间输入。[`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) 只接受版本与根目录 `package.json` 匹配的 `python-v` 标签流水线，构建一个 SDK wheel 包和 4 个原生运行时 wheel 包，再由单个串行任务校验并将这 5 个文件发布到项目的 PyPI 注册表。[Windows x64 运行时决策](2026-08-23-python-sdk-windows-x64-runtime.zh.md)负责第四个目标及对 Windows arm64 的明确排除。 +CI 使用 [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml)：[安装后 wheel Python 运行时拉取请求验证](../testing/2026-08-23-installed-python-wheel-black-box-ci.zh.md)与[公开发布工作流](../process/2026-08-11-python-publication-workflow.zh.md)都会调用它构建全部四个目标；`workflow_dispatch` 仍可选择部分目标。linux-x64、linux-arm64（`ubuntu-24.04-arm`）、macos-arm64 与 win-x64（`windows-2025`）分别进行原生构建，并在适用平台缓存 `~/.pkg-cache`；macOS 的 ad-hoc 签名由 pkg 处理。每个平台都把发布形态的 SDK wheel 包与运行时 wheel 包安装到 checkout 外的干净 venv，证明包与可执行文件来源，再通过公开 SDK 与直接 NDJSON JSON-RPC 运行完整 keyless 场景。可信拉取请求还会在每个目标上运行真实 DeepSeek 双轮工具冒烟测试；fork 与 Dependabot head 不会获得密钥。Linux 会检查可执行文件和原生 addon 各自的 GLIBC 依赖，并额外运行 manylinux 2.28 冒烟测试；macOS 则验证可执行文件的部署目标符合 wheel 包标签。完整构建四个目标时保留 5 个产物，每个产物只含一个发布文件：平台无关的 SDK wheel 包与 4 个原生运行时 wheel 包；手动选择部分目标时保留 SDK wheel 与所选运行时 wheel。裸 exe 与源码包只作为测试中间输入。[`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) 只接受版本与根目录 `package.json` 匹配的 `python-v` 标签流水线，构建一个 SDK wheel 包和 4 个原生运行时 wheel 包，再由单个串行任务校验并将这 5 个文件发布到项目的 PyPI 注册表。[Windows x64 运行时决策](2026-08-23-python-sdk-windows-x64-runtime.zh.md)负责第四个目标及对 Windows arm64 的明确排除。 ### Python SDK 分发：双载体，exe 用于生产，`node` 用于开发 diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml index 166541f1f2..b31d6baf7e 100644 --- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md -2026-07-26-subprocess-seam.md: 92d36bf6d522ab939ef6c0de1063e0accea2946f -2026-07-26-subprocess-seam.zh.md: d271ad95ce84bb34256d3bf2ee6d793e21623d2b +2026-07-26-subprocess-seam.md: b892c43a4027815692dcc8082d4a2cc9feea18c7 +2026-07-26-subprocess-seam.zh.md: 78e290a14bc0cdf50434462dd854bdc1355d4938 diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md index 92d36bf6d5..b892c43a40 100644 --- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md +++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md @@ -12,8 +12,8 @@ English | [中文](2026-07-26-subprocess-seam.zh.md) A new `subprocess/` capability family owns "run and manage a process"; the bash family keeps "run a bash command" and consumes it: -- **`@deepseek-ai/dsh-subprocess` (Service Definition)** — the abstract `SubprocessRuntime` owning `ctx.subprocess`: executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The Service Definition also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted. -- **`@deepseek-ai/dsh-subprocess-local` (Service Provider)** — `LocalSubprocessRuntime` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: bounded collection and private spill files, executable lookup, foreground/session inspection, and disposal that terminates and joins every managed process. Ordinary Linux commands use a user-systemd scope when the host can preserve literal argv and read scope state; ordinary Windows commands start suspended in a kill-on-close Job. `terminate()` and `waitForExit()` use that same OS range, while `.done` remains the direct command result. Unsupported hosts retain the disclosed PGID or `taskkill /T` fallback. Ordinary and terminal spawns apply the Service Definition's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The provider has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their Consumers. +- **`@deepseek-ai/dsh-subprocess` (Service Definition)** — the abstract `SubprocessRuntime` owning `ctx.subprocess`: executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. An ordinary handle exposes streams, collection, `.done`, `terminate()`, and `waitForExit()` without publishing a PID; the terminal handle retains its stable PID. The Service Definition also owns the shared scrub and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted. +- **`@deepseek-ai/dsh-subprocess-local` (Service Provider)** — `LocalSubprocessRuntime` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: bounded collection and private spill files, executable lookup, foreground/session inspection, and disposal that terminates and joins every managed process. The [native-containment decision](2026-08-28-subprocess-native-containment.md) owns its current platform mechanism: eligible Linux ordinary and PTY launches use user-systemd scopes, eligible Windows ordinary launches use a private runner-owned kill-on-close Job, and unsupported hosts retain the disclosed PGID, `taskkill /T`, or PTY-observation fallback. `terminate()` and `waitForExit()` use the selected range, while `.done` remains the direct command result. Ordinary and terminal spawns apply the Service Definition's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The provider has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their Consumers. - **`dsh-bash-local` (Consumer)** — `inject: ['subprocess']`; maps each resolved `ShellExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path. - **`dsh-shell` (Service Definition)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash Consumer changes an import; `ShellExecRequest`/`ShellExecSpec`/`ShellProcess` and the sandbox facts remain bash-owned. diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md index d271ad95ce..78e290a14b 100644 --- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md @@ -12,8 +12,8 @@ Status: implemented 新的 `subprocess/` 能力家族拥有「运行并管理一个进程」；bash 家族保留「运行一条 bash 命令」，并成为前者的消费方： -- **`@deepseek-ai/dsh-subprocess`（Service Definition）**——拥有 `ctx.subprocess` 的抽象 `SubprocessRuntime`：可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.zh.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 Service Definition 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。 -- **`@deepseek-ai/dsh-subprocess-local`（Service Provider）**——`LocalSubprocessRuntime` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：有界收集与私有 spill 文件、可执行文件查找、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。普通 Linux 命令在宿主能保留 literal argv 并读取 scope 状态时使用 user-systemd scope；普通 Windows 命令以 suspended 状态进入 kill-on-close Job。`terminate()` 与 `waitForExit()` 使用同一 OS range，而 `.done` 仍是 direct command result。不支持的宿主保留已披露的 PGID 或 `taskkill /T` fallback。普通与终端 spawn 都先应用 Service Definition 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该 Service Provider 没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自 Consumer 所有。 +- **`@deepseek-ai/dsh-subprocess`（Service Definition）**——拥有 `ctx.subprocess` 的抽象 `SubprocessRuntime`：可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.zh.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。普通句柄公开流、收集结果、`.done`、`terminate()` 与 `waitForExit()`，但不发布 PID；终端句柄保留稳定 PID。该 Service Definition 还拥有共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。 +- **`@deepseek-ai/dsh-subprocess-local`（Service Provider）**——`LocalSubprocessRuntime` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：有界收集与私有 spill 文件、可执行文件查找、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。[原生收容决策](2026-08-28-subprocess-native-containment.zh.md)拥有当前平台机制：符合条件的 Linux 普通命令与 PTY 使用 user-systemd scope，符合条件的 Windows 普通命令使用由私有 runner 拥有的 kill-on-close Job，不支持的宿主保留已披露的 PGID、`taskkill /T` 或 PTY 观察式 fallback。`terminate()` 与 `waitForExit()` 使用所选 range，而 `.done` 仍是 direct command result。普通与终端 spawn 都先应用 Service Definition 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该 Service Provider 没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自 Consumer 所有。 - **`dsh-bash-local`（Consumer）**——`inject: ['subprocess']`；把每个解析后的 `ShellExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。 - **`dsh-shell`（Service Definition）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash Consumer 需要改动导入；`ShellExecRequest`/`ShellExecSpec`/`ShellProcess` 与沙箱事实仍归 bash 所有。 diff --git a/.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.i18n.yaml index 221d51c183..643453c53b 100644 --- a/.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.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 .agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.md -2026-08-19-shared-win32-process-primitives.md: f9d876acdc385b0dfae8319091655722b24d4981 -2026-08-19-shared-win32-process-primitives.zh.md: 37ba5cae7f2d194f6e641164b72478fefab6428e +2026-08-19-shared-win32-process-primitives.md: 7de80e15ef8b42e72187af40e5ee0646e80f071d +2026-08-19-shared-win32-process-primitives.zh.md: ebd9c437d617761cb7faef873f952443eca3f6ad diff --git a/.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.md b/.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.md index f9d876acdc..7de80e15ef 100644 --- a/.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.md +++ b/.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.md @@ -10,17 +10,17 @@ The Windows ACL sandbox owns restricted-token, SID, DACL, grant, and workspace p ## Decision -`@deepseek-ai/dsh-win32-process` owns the reusable Win32 process ABI and native resource operations consumed by `sandbox-windows-acl` and the ordinary subprocess Job runner. The package lazily loads `kernel32.dll` and `advapi32.dll`, verifies the x64 `STARTUPINFOW` and `PROCESS_INFORMATION` layouts, quotes argv for `CreateProcessAsUserW` or `CreateProcessW`, and exposes checked anonymous/named-pipe, Job, wait, polling, termination, and handle operations. +`@deepseek-ai/dsh-win32-process` owns the reusable Win32 process ABI and native resource operations consumed by `sandbox-windows-acl` and the ordinary subprocess Job runner. The package lazily loads `kernel32.dll` and `advapi32.dll`, verifies the x64 `STARTUPINFOW` and `PROCESS_INFORMATION` layouts, quotes argv for `CreateProcessAsUserW` or `CreateProcessW`, and exposes checked anonymous-pipe, inherited-stdio, Job, wait, polling, termination, and handle operations. The Windows ACL sandbox remains the only owner of restricted-token creation, SID and DACL policy, grants, writable-path decisions, temporary-directory policy, and the public sandbox child result. It extends the shared binding context with policy-specific APIs, supplies the primary token, combines pipe drains and waits, and closes the caller-owned Job at its lifecycle boundary. -Every native allocation and HANDLE has one owner within each shared operation. A process operation frees its Koffi out-parameters and closes every pipe, thread, process, or Job handle it acquired before a controlled failure. Successful anonymous-pipe creation returns the process plus stdout/stderr read handles to the sandbox. The ordinary runner opens target-side named-pipe handles supplied by its parent and closes those handles after target creation. Restricted and ordinary creation both start the target suspended, assign it to the kill-on-close Job, and resume it only after assignment, so target code cannot run outside the Job. The sandbox retains its existing pipe-drain and direct-wait lifecycle; the ordinary runner retains the original direct-process handle and unnamed Job, polls direct exit, and closes the Job only after it is empty. +Every native allocation and HANDLE has one owner within each shared operation. A process operation frees its Koffi out-parameters and closes every pipe, thread, process, or Job handle it acquired before a controlled failure. Successful anonymous-pipe creation returns the process plus stdout/stderr read handles to the sandbox. The ordinary runner temporarily restores inheritability on its own standard handles, passes those exact handles through `STARTF_USESTDHANDLES`, then closes its copies after target creation so target exit can produce EOF at the parent. Restricted and ordinary creation both start the target suspended, assign it to the kill-on-close Job, and resume it only after assignment, so target code cannot run outside the Job. The sandbox retains its existing pipe-drain and direct-wait lifecycle; the [native-containment runner](2026-08-28-subprocess-native-containment.md) uniquely retains the ordinary direct-process handle and unnamed Job, polls direct exit and active-process count, and closes the Job only after it is empty. -The package exports only operations used by the two production consumers. Exact `applicationName`, parent-owned Node streams, public process handles, and backend selection remain outside. The package is a library, not a Cordis service or a public Windows SDK. +The current-token API is named `CurrentTokenProcessSpawnOptions` and `spawnCurrentTokenJobProcess`; no `Ordinary*` or `Unrestricted*` aliases preserve ambiguous semantics. The package exports only operations used by the two production consumers. Exact `applicationName`, parent-owned Node streams and IPC, public process handles, and backend selection remain outside. The package is a library, not a Cordis service or a public Windows SDK. ## Verification -The shared suite covers x64 ABI values, command-line quoting, binding extension, anonymous-pipe EOF and drain allocation reuse, stream-specific named-pipe opens, explicit ordinary stdio handles, restricted and ordinary process creation, suspended creation followed by Job assignment and resume, blocking and zero-time exit reads, Job-empty probes and termination, native allocation release, and acquired-resource failure paths. Sandbox tests retain restricted-token, fail-closed, pipe/inherit, result, and disposal composition without duplicating the low-level matrix. The committed header probes and Windows package tests cover the native paths; Wine supplies the emulated Windows package and composition signal. +The shared suite covers x64 ABI values, command-line quoting, binding extension, anonymous-pipe EOF and drain allocation reuse, inherited ordinary standard handles, restricted and current-token process creation, suspended creation followed by Job assignment and resume, blocking and zero-time exit reads, Job-empty probes and termination, native allocation release, and acquired-resource failure paths. Sandbox tests retain restricted-token, fail-closed, pipe/inherit, result, and disposal composition without duplicating the low-level matrix. The committed header probes and Windows package tests cover the native paths; Wine supplies the emulated Windows package and composition signal. ## Alternatives considered diff --git a/.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.zh.md b/.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.zh.md index 37ba5cae7f..ebd9c437d6 100644 --- a/.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-19-shared-win32-process-primitives.zh.md @@ -10,17 +10,17 @@ Windows ACL sandbox 拥有 restricted token、SID、DACL、grant 与 workspace p ## Decision -`@deepseek-ai/dsh-win32-process` 拥有 `sandbox-windows-acl` 与 ordinary subprocess Job runner 消费的可复用 Win32 process ABI 与 native resource 操作。该包惰性加载 `kernel32.dll` 和 `advapi32.dll`，核验 x64 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 布局，为 `CreateProcessAsUserW` 或 `CreateProcessW` 引用 argv，并提供带检查的 anonymous/named-pipe、Job、wait、polling、termination 与 handle 操作。 +`@deepseek-ai/dsh-win32-process` 拥有 `sandbox-windows-acl` 与 ordinary subprocess Job runner 消费的可复用 Win32 process ABI 与 native resource 操作。该包惰性加载 `kernel32.dll` 和 `advapi32.dll`，核验 x64 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 布局，为 `CreateProcessAsUserW` 或 `CreateProcessW` 引用 argv，并提供带检查的 anonymous pipe、继承 stdio、Job、wait、polling、termination 与 handle 操作。 Windows ACL sandbox 继续唯一拥有 restricted-token 创建、SID 与 DACL policy、grants、可写路径裁定、临时目录 policy 和公共 sandbox child result。它通过共享 binding context 扩展 policy-specific API，提供 primary token，组合 pipe drain 与 wait，并在自己的生命周期边界关闭调用方拥有的 Job。 -每项 native allocation 与 HANDLE 在各个 shared operation 内只有一个 owner。process operation 会释放 Koffi out-parameter，并在受控失败前关闭它已经取得的每个 pipe、thread、process 或 Job handle。anonymous pipe 创建成功时，把 process 与 stdout/stderr read handles 返回给 sandbox。ordinary runner 打开 parent 提供的 target-side named-pipe handle，并在 target 创建后关闭这些 handle。restricted 与 ordinary 创建都会以 suspended 状态启动目标，把它分配给 kill-on-close Job，并只在分配后恢复，因此目标代码不会在 Job 外运行。sandbox 保留既有 pipe-drain 与 direct-wait 生命周期；ordinary runner 保留原始 direct-process handle 与 unnamed Job，轮询 direct exit，并只在 Job 为空后关闭它。 +每项 native allocation 与 HANDLE 在各个 shared operation 内只有一个 owner。process operation 会释放 Koffi out-parameter，并在受控失败前关闭它已经取得的每个 pipe、thread、process 或 Job handle。anonymous pipe 创建成功时，把 process 与 stdout/stderr read handles 返回给 sandbox。ordinary runner 临时恢复自身标准句柄的可继承位，通过 `STARTF_USESTDHANDLES` 原样传递这些句柄，并在目标创建后关闭自身副本，使目标退出可以让 parent 观察到 EOF。restricted 与 ordinary 创建都会以 suspended 状态启动目标，把它分配给 kill-on-close Job，并只在分配后恢复，因此目标代码不会在 Job 外运行。sandbox 保留既有 pipe-drain 与 direct-wait 生命周期；[原生收容 runner](2026-08-28-subprocess-native-containment.zh.md)唯一保留 ordinary direct-process handle 与 unnamed Job，轮询 direct exit 和 active-process count，并只在 Job 为空后关闭它。 -该包只导出两个生产 consumer 已使用的操作。精确 `applicationName`、parent-owned Node stream、公共 process handle 与 backend selection 仍留在外部。该包是 library，不是 Cordis service 或公共 Windows SDK。 +current-token API 直接命名为 `CurrentTokenProcessSpawnOptions` 与 `spawnCurrentTokenJobProcess`；不保留语义含糊的 `Ordinary*` 或 `Unrestricted*` 别名。该包只导出两个生产消费方已使用的操作。精确 `applicationName`、parent 自有的 Node stream 与 IPC、公共 process handle 以及后端选择仍留在外部。该包是 library，不是 Cordis service 或公共 Windows SDK。 ## Verification -shared suite 覆盖 x64 ABI 值、命令行引用、binding extension、anonymous-pipe EOF 与 drain allocation 复用、按流划分 access 的 named-pipe open、显式 ordinary stdio handle、restricted 与 ordinary process 创建、suspended 创建后的 Job 分配与恢复、blocking 与 zero-time exit 读取、Job-empty probe 与 termination、native allocation 释放，以及已取得资源的失败路径。sandbox 测试保留 restricted-token、fail-closed、pipe/inherit、result 与 disposal 组合行为，不重复低层矩阵。已提交的 header probe 与 Windows package 测试覆盖 native 路径；Wine 提供模拟 Windows package 与组合信号。 +shared suite 覆盖 x64 ABI 值、命令行引用、binding extension、anonymous-pipe EOF 与 drain allocation 复用、继承的 ordinary 标准句柄、restricted 与 current-token process 创建、suspended 创建后的 Job 分配与恢复、blocking 与 zero-time exit 读取、Job-empty probe 与 termination、native allocation 释放，以及已取得资源的失败路径。sandbox 测试保留 restricted-token、fail-closed、pipe/inherit、result 与 disposal 组合行为，不重复低层矩阵。已提交的 header probe 与 Windows package 测试覆盖 native 路径；Wine 提供模拟 Windows package 与组合信号。 ## Alternatives considered diff --git a/.agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.i18n.yaml index e02c19ea8c..d649a92344 100644 --- a/.agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.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 .agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.md -2026-08-23-python-sdk-dsh-profile-runtime.md: 4af7812db6818b65c754a43ec1a7f973d1cbcbf9 -2026-08-23-python-sdk-dsh-profile-runtime.zh.md: 155e7d2ae0b0ba3e4163dd85a31de90bef9d588a +2026-08-23-python-sdk-dsh-profile-runtime.md: e6dbe4c5a81093201edfb476a8f1b9594a923903 +2026-08-23-python-sdk-dsh-profile-runtime.zh.md: 888fcb097d592d295df88c56f11cca3e4dec81c2 diff --git a/.agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.md b/.agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.md index 4af7812db6..e6dbe4c5a8 100644 --- a/.agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.md +++ b/.agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.md @@ -30,7 +30,7 @@ The runtime wheel installs a `dsh` console command. Ordinary profile and SDK exe ### Executable packaging -The zero-code deployment manifest is `dsh-python-runtime-closure`. It packages `node_modules/@deepseek-ai/dsh/lib/bin.js` and profile, bundle, preset, native-addon, and shared-library assets into `deepseek-harness-sdk-runtime--`. The wheel distribution names, Python import modules, JSON-RPC messages, and wire-stable `serverInfo.name = deepseek-harness-sdk-runtime` remain unchanged. +The zero-code deployment manifest is `dsh-python-runtime-closure`. It packages `node_modules/@deepseek-ai/dsh/lib/runtime-bootstrap.js` and profile, bundle, preset, native-addon, and shared-library assets into `deepseek-harness-sdk-runtime--`. That packaging-owned bootstrap imports the ordinary public CLI when no private selection is present; for a selected subprocess runner it consumes the one private environment value and enters `@deepseek-ai/dsh-subprocess-local/runner` without parsing a hidden CLI argument or adding a second Node executable. The [native-containment decision](2026-08-28-subprocess-native-containment.md) owns that private dispatch and runner protocol. The wheel distribution names, Python import modules, JSON-RPC messages, and wire-stable `serverInfo.name = deepseek-harness-sdk-runtime` remain unchanged. Plain Node profiles use symlinks in `$DSH_HOME/profiles/node_modules` to share installation packages with external plugins. An operating-system symlink cannot traverse pkg's `/snapshot` filesystem, so the packaged CLI writes small real ESM proxy packages instead. Each proxy resolves the source package's explicit ESM export map directly under Node import conditions, exposes targets that exist in the installation, and re-exports their virtual module URLs. Export rows without an ESM runtime target and executable-only or declaration-only packages produce no unusable proxy entry; malformed export maps fail startup. A complete matching generation returns without acquiring the cross-process writer lock. A missing or stale entry acquires the lock, rechecks the generation, and repairs it without exposing partial proxies; either carrier can replace the other carrier's managed entry. Loader rows and external plugin peers therefore resolve through the normal profile parent walk while retaining one Cordis and one instance of each bundled module. diff --git a/.agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.zh.md b/.agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.zh.md index 155e7d2ae0..888fcb097d 100644 --- a/.agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.zh.md @@ -30,7 +30,7 @@ Python SDK 分发一个私有 Node 应用，直接启动完整外部 `cordis.yml ### 可执行程序打包 -零代码部署 manifest 是 `dsh-python-runtime-closure`。它把 `node_modules/@deepseek-ai/dsh/lib/bin.js` 以及 profile、bundle、preset、原生 addon 与共享库资源打包进 `deepseek-harness-sdk-runtime--`。Wheel distribution 名称、Python import 模块、JSON-RPC 消息和协议稳定的 `serverInfo.name = deepseek-harness-sdk-runtime` 保持不变。 +零代码部署 manifest 是 `dsh-python-runtime-closure`。它把 `node_modules/@deepseek-ai/dsh/lib/runtime-bootstrap.js` 以及 profile、bundle、preset、原生 addon 与共享库资源打包进 `deepseek-harness-sdk-runtime--`。没有私有选择值时，这个由打包层拥有的 bootstrap 会导入普通公共 CLI；选择了 subprocess runner 时，它会消费唯一的私有环境值并进入 `@deepseek-ai/dsh-subprocess-local/runner`，不解析隐藏 CLI 参数，也不增加第二个 Node 可执行程序。[原生收容决策](2026-08-28-subprocess-native-containment.zh.md)拥有这项私有分派与 runner 协议。Wheel distribution 名称、Python import 模块、JSON-RPC 消息和协议稳定的 `serverInfo.name = deepseek-harness-sdk-runtime` 保持不变。 普通 Node profile 在 `$DSH_HOME/profiles/node_modules` 中使用符号链接，让外部插件共享安装包。操作系统符号链接无法进入 pkg 的 `/snapshot` 文件系统，因此打包 CLI 改为写入小型真实 ESM 代理包。每个代理直接按 Node import 条件解析源包的显式 ESM exports map，公开安装中实际存在的目标，并重新导出其虚拟模块 URL。没有 ESM 运行时目标的 export 项以及仅含可执行入口或类型声明入口的包不会产生不可用的代理条目；格式错误的 exports map 会导致启动失败。完整且匹配的 generation 不会获取跨进程写入锁。缺失或过期的配置项会获取该锁、重新检查 generation，并在不暴露半成品代理的前提下修复；任一载体都可以替换另一载体留下的受管配置项。Loader 配置项和外部插件 peer 因而可以通过普通 profile 逐级向上查找解析，同时保留一个 Cordis 和每个内置模块的单一实例。 diff --git a/.agents/notes/implemented/bug-fix/2026-08-20-subprocess-native-containment.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.i18n.yaml similarity index 56% rename from .agents/notes/implemented/bug-fix/2026-08-20-subprocess-native-containment.i18n.yaml rename to .agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.i18n.yaml index ef14983ff5..21f604876d 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-20-subprocess-native-containment.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 .agents/notes/implemented/bug-fix/2026-08-20-subprocess-native-containment.md -2026-08-20-subprocess-native-containment.md: 4ed116f5db247278771575549e216b1aa91c97fb -2026-08-20-subprocess-native-containment.zh.md: 95fdd1c73c1b7d5f53360389e8aef31c5b4ca979 +# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.md +2026-08-28-subprocess-native-containment.md: 4423494f784218f01005034dd0305098823ee7fe +2026-08-28-subprocess-native-containment.zh.md: 724c017a681a35f4c8d0ddecea46c28cb5301a76 diff --git a/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.md b/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.md new file mode 100644 index 0000000000..4423494f78 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.md @@ -0,0 +1,80 @@ +# Agent Note: Native owners contain escaped subprocess descendants + +Status: implemented + +English | [中文](2026-08-28-subprocess-native-containment.zh.md) + +## Problem + +Detached POSIX process groups, Windows direct-parent traversal, and PTY descendant scans describe only members that remain observable through one process relationship. A child can call `setsid`, reparent, or outlive its direct parent and leave those ranges, so terminating the apparent tree can return while work, ports, or files remain active. A direct target result also does not prove that every descendant has stopped. + +The ordinary subprocess handle cannot solve this gap by publishing a PID. Linux scope setup and the Windows Job runner establish target identity asynchronously, a PID does not name the complete managed range, and consumers would be forced to infer whether startup committed. The public result, range ownership, private startup protocol, and packaged entry therefore need separate owners. + +## Decision + +`LocalSubprocessRuntime` selects one provider-private managed-range owner before a target can execute. Eligible Linux ordinary and PTY launches enter a transient user-systemd scope; eligible Windows ordinary launches enter an unnamed kill-on-close Job owned by a private runner. Unsupported hosts use the existing weaker fallback with one provider-lifetime warning. The provider never replays a target after a selected native path may have executed it. + +An ordinary `SubprocessHandle` has no PID or public startup state. `.done` reports the direct target result or startup/provider failure, `terminate()` signals the selected range, and `waitForExit()` succeeds only after that same range is proven empty. `SubprocessTerminalHandle.pid` remains part of the terminal contract because PTY identity and foreground inspection require it. + +### Linux scope and one-shot bootstrap + +Every eligible Linux ordinary or PTY spawn rechecks the exact runner entry, `process.execve()`, the readable user manager, and literal-argv transient-scope support. A positive result is not cached. Once selected, a scope, protocol, state-query, or pre-exec failure is reported through that launch and never switches to fallback. + +The parent creates one 0700 directory with a complete 0600 `launch-request.json` containing the final target cwd and environment. The private `DSH_SUBPROCESS_RUNNER` value locates that request while the runner starts from the provider cwd and a bootstrap-safe environment. `systemd-run --user --scope --quiet --collect --expand-environment=no` registers its process in the scope, then the one-shot bootstrap removes and validates the request, changes to the target cwd, restores the complete target environment, resolves a bare executable with the target PATH rules, and calls `execve()` with the original argv. The bootstrap becomes the target in place; it does not remain as a supervisor. + +Request consumption or a manager observation of the unit establishes scope ownership. Unit absence before either fact remains unresolved; direct-child exit with an unconsumed request is establishment failure. After establishment, an inactive, failed, or collected-away unit proves the range empty. Unknown states and unreadable manager results reject `waitForExit()` instead of claiming quiescence. A strict sibling `startup-error.json` carries only request/bootstrap or target pre-exec failure, and the parent removes this spawn's private paths at observable lifecycle completion. + +The ordinary target result still comes from the same child process. The PTY path uses the same request and bootstrap without a resident runner, so the `node-pty` PID, process group, session leader, controlling terminal, foreground `inputWaiting`, `/dev/tty`, readiness, and direct terminal outcome retain their existing meanings while scope membership covers `setsid` and reparented descendants. + +### Windows runner and Job + +The Windows parent starts the provider runner from a bootstrap cwd and environment, gives it the original target argv after a private `--` delimiter, and uses Node IPC for exactly one start request, idempotent terminate control, and exactly one direct-result branch. Target stdin, stdout, and stderr remain real Node-created standard handles: the runner temporarily makes its inherited handles inheritable, creates the target with `STARTF_USESTDHANDLES`, and closes its own copies after target creation. User bytes never pass through IPC. + +The runner is the sole owner of the target process handle and unnamed Job handle. `spawnCurrentTokenJobProcess` creates the target suspended, assigns it to a kill-on-close Job that disallows active breakaway, and resumes it only after assignment. The runner polls the direct process for the target exit code and the Job for active-process count. It exits successfully only after the direct result has been delivered through the IPC send callback and the Job has reported zero active processes; the parent maps only that clean exit to successful `waitForExit()`. + +The parent settles `.done` only after a strict direct-result message and the existing stdout/stderr close or bounded-drain barrier. A later Job query or range-settlement failure rejects only `waitForExit()`. IPC loss before that `.done` barrier rejects `.done` as runner infrastructure failure; IPC loss afterward leaves the completed direct result unchanged but still rejects range settlement. On disconnect or result-send failure, the runner stops protocol work, terminates and closes its only Job handle, and exits nonzero. Closing the last Job handle kills remaining members but does not convert the disconnected path into a successful quiescence proof. + +### Private dispatch and protocol + +Source launches execute the package runner entry through the TypeScript source launcher, built launches resolve the `@deepseek-ai/dsh-subprocess-local/runner` export, and the Python SDK single-file executable enters through `@deepseek-ai/dsh`'s packaging-owned `runtime-bootstrap.js`. That bootstrap imports the public CLI when the private selector is absent; otherwise it removes the selector and dispatches to the same subprocess runner core. The public `dsh` argument parser has no hidden runner mode, and packaging ships no second Node executable. + +The selector is a per-spawn locator or sentinel, not a credential or persistent format. Linux uses one strict request plus one optional strict startup-error file; Windows uses one IPC channel with closed start, terminate, `target-exit`, `spawn-error`, `runner-error`, and `start-cancelled` messages. Errors carry only bounded Node-shaped fields. Missing, extra, mistyped, or unknown fields fail closed. Target environments may contain the selector name, including Windows case variants, because the provider transmits target state separately and restores it only after private selection is consumed. + +### Fallback and cleanup + +Linux falls back before target execution when the exact bootstrap, modern readable user-systemd manager, or literal-argv scope is unavailable. Windows ordinary launch falls back when the runner entry, Win32 bindings, or current-token Job probe is unavailable. macOS ordinary launch, Windows ConPTY, and other unsupported hosts retain their existing PGID, `taskkill /T`, or identity-fenced PTY observation. The warning states that descendants escaping those observable relationships are not guaranteed to terminate or delay `waitForExit()`. + +Normal Cordis disposal starts direct-result and range observation independently, requests termination, and waits for every owned range. Consumer teardown does not inspect an ordinary PID; it retains the original operation or startup error while attempting terminate and final wait, and preserves cleanup failures in the consumer's existing error order. A confirmed empty range permanently disables later signalling against stale identities. + +During a JavaScript-observable host exit, `LocalSubprocessRuntime` synchronously force-terminates every still-live handle without promises or timers. Linux sends the existing direct fallback kill and the exact scope kill; Windows kills the runner so its only Job handle closes; PTY fallback scans remain best effort. Per-handle failures are contained and do not change the host's exit result. Termination modes in which JavaScript cannot run remain outside this listener's guarantee. + +## Existing decisions and supersession + +This note owns the current native-containment mechanism. It partially updates the provider and no-PID facts in the [subprocess seam](2026-07-26-subprocess-seam.md), the Linux teardown facts in [persistent PTY sessions](../feature/2026-07-16-persistent-pty-sessions.md), the native targets used by [synchronous host-exit cleanup](../bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.md), the ordinary consumer of [shared Win32 process primitives](2026-08-19-shared-win32-process-primitives.md), and the private entry selected by the [Python SDK profile runtime](2026-08-23-python-sdk-dsh-profile-runtime.md). Each note retains its other decision and remains active. + +## Verification + +- Provider and protocol suites pin synchronous NUL rejection before launch side effects, strict request/result decoding, target cwd and complete environment restoration, private-variable collision, Linux PATH lookup with preserved argv, pre-exec error ownership, the three scope-establishment states, all four Windows result branches, start cancellation, result-send and IPC-disconnect failures, stdio settlement, active-process quiescence, and unique handle cleanup. +- Real Linux user-systemd tests run one ordinary and one `node-pty` `setsid`/reparent scenario through the production entry. They prove scope signalling and collection, bare executable lookup, escaped-descendant termination, range settlement, and unchanged PTY PID, session, controlling-terminal, foreground-input, `/dev/tty`, readiness, and startup-failure semantics. +- Native Windows tests prove suspended creation, Job assignment before resume, inherited stdio, default descendant inheritance, direct result, termination, active-process zero, abnormal/disconnected runner cleanup, kill-on-close, and synchronous host-exit termination. Source, built, and Python packaged smokes enter the same runner core. +- Public seam types, local and E2B providers, LSP and subagent consumers, shell fixtures, READMEs, the Cordis catalog, and the keyless subprocess API snapshot contain no ordinary PID; terminal PID remains. + +## Alternatives considered + +**Keep PID, make it optional, or add a public `started` promise.** Rejected because each representation exposes an asynchronous provider identity that does not name the managed range and invites consumers to infer startup or quiescence from the wrong fact. + +**Extend process-group, session, parent-tree, or PID scanning.** Rejected because a process can leave each observed relationship; broader SID signalling can also reach unrelated processes when a PTY helper shares a launcher session. Native OS membership is persistent and independently queryable. + +**Let the parent own or reopen the Windows Job.** Rejected because copied handles, named Jobs, `OpenJobObject`, process-handle handoff, and completion ports create multiple lifecycle owners without improving the direct-result contract. One runner can own target creation, Job membership, result production, and final handle closure. + +**Carry control or results through target stdio or files on Windows.** Rejected because user bytes and EOF must remain authoritative to existing Node streams, while result files or polling introduce a second result owner. One IPC channel separates control from target stdio. + +**Parse a hidden runner argument in the public CLI or ship another Node executable.** Rejected because either choice expands the public application grammar or distribution surface. A packaging-only bootstrap keeps one physical executable and two private logical entries. + +**Cache successful native probes or recover a failed native launch by replaying the command.** Rejected because user-manager, entry, and Job availability can change between spawns, while replay can execute a command twice after an ambiguous failure. + +## Consequences + +Supported Linux ordinary and PTY launches and Windows ordinary launches retain descendants through process-group escape and direct-parent exit, while direct target results remain independent from range quiescence. The cost is a per-spawn Linux scope/request or Windows runner/IPC/Job lifecycle, plus explicit failure when the selected owner cannot prove settlement. + +Fallback hosts continue to run commands but carry a visible weaker guarantee. Windows ConPTY, macOS native containment, active breakaway descendants, old or absent user-systemd environments, target replay, persistent runner recovery, and termination paths where JavaScript cannot execute remain outside this decision. diff --git a/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.zh.md b/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.zh.md new file mode 100644 index 0000000000..724c017a68 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.zh.md @@ -0,0 +1,80 @@ +# Agent Note: 原生 owner 收容逃逸的 subprocess 后代 + +Status: implemented + +[English](2026-08-28-subprocess-native-containment.md) | 中文 + +## Problem + +detached POSIX 进程组、Windows direct-parent 遍历与 PTY 后代扫描只能描述仍可通过某种进程关系观察到的成员。子进程可以调用 `setsid`、发生 reparent，或比 direct parent 存活更久并离开这些 range，因此终止表面进程树后，工作、端口或文件仍可能保持活跃。direct target result 也不能证明全部后代已经停止。 + +普通 subprocess 句柄无法通过发布 PID 解决这个缺口。Linux scope setup 与 Windows Job runner 会异步建立 target identity，PID 不表示完整 managed range，消费方也会被迫推断 startup 是否已经提交。因此，公共结果、range ownership、私有启动协议与打包入口需要各自明确的 owner。 + +## Decision + +`LocalSubprocessRuntime` 会在 target 执行前选择一个 provider 私有的 managed-range owner。符合条件的 Linux 普通命令与 PTY 进入临时 user-systemd scope；符合条件的 Windows 普通命令进入由私有 runner 拥有的 unnamed kill-on-close Job。不支持的宿主使用既有较弱 fallback，并在 provider 生命周期内只警告一次。选定的 native 路径一旦可能已经执行 target，provider 绝不重放 target。 + +普通 `SubprocessHandle` 没有 PID 或公共 startup 状态。`.done` 报告 direct target result 或 startup／provider failure，`terminate()` 向所选 range 发送信号，`waitForExit()` 只有在同一 range 被证明为空后才成功。`SubprocessTerminalHandle.pid` 继续属于终端约定，因为 PTY identity 与前台检查需要它。 + +### Linux scope 与 one-shot bootstrap + +每次符合条件的 Linux 普通或 PTY spawn 都会重新检查准确 runner 入口、`process.execve()`、可读的 user manager 与保留 literal argv 的 transient-scope 支持。正向结果不缓存。native 路径一旦选定，scope、协议、状态查询或 pre-exec failure 都由本次启动报告，绝不切换到 fallback。 + +parent 创建一个 0700 目录，其中的完整 0600 `launch-request.json` 保存最终 target cwd 与环境。私有 `DSH_SUBPROCESS_RUNNER` 值负责定位该 request，runner 则从 provider cwd 与 bootstrap-safe 环境启动。`systemd-run --user --scope --quiet --collect --expand-environment=no` 先把自身进程注册到 scope，再由 one-shot bootstrap 删除并校验 request、切换到 target cwd、恢复完整 target 环境、按 target PATH 规则解析裸可执行文件，并使用原始 argv 调用 `execve()`。bootstrap 会原地成为 target，不作为常驻 supervisor。 + +request 被消费或 manager 已观察到 unit 都能建立 scope ownership。在这两项事实出现前，unit absence 仍是未决状态；direct child 在 request 尚未消费时退出表示建立失败。建立之后，inactive、failed 或已经被 collect 卸载的 unit 可以证明 range 为空。未知状态与不可读的 manager 结果会使 `waitForExit()` reject，而不是宣称完全停稳。严格的同目录 `startup-error.json` 只承载 request／bootstrap 或 target pre-exec failure，parent 会在可观察生命周期完成时移除本次 spawn 的私有路径。 + +普通 target result 仍来自同一个 child process。PTY 路径复用同一 request 与 bootstrap，但不增加常驻 runner，因此 `node-pty` PID、进程组、session leader、控制终端、前台 `inputWaiting`、`/dev/tty`、readiness 与 direct terminal outcome 保留既有含义，同时 scope membership 覆盖 `setsid` 与 reparent 后代。 + +### Windows runner 与 Job + +Windows parent 从 bootstrap cwd 与环境启动 provider runner，把原始 target argv 放在私有 `--` 分隔符之后，并通过 Node IPC 传递恰好一条 start request、幂等 terminate control 与恰好一个 direct-result 分支。target stdin、stdout 与 stderr 继续使用 Node 创建的真实标准句柄：runner 临时把继承的句柄设为可继承，通过 `STARTF_USESTDHANDLES` 原样传递，并在 target 创建后关闭自身副本。用户字节绝不经过 IPC。 + +runner 是 target process handle 与 unnamed Job handle 的唯一 owner。`spawnCurrentTokenJobProcess` 以 suspended 状态创建 target，把它分配给不允许 active breakaway 的 kill-on-close Job，并只在分配后恢复。runner 轮询 direct process 获取 target exit code，并轮询 Job 获取 active-process count。只有 direct result 已通过 IPC send callback 交付且 Job 已报告零 active process 后，runner 才成功退出；parent 只把这次 clean exit 映射成成功的 `waitForExit()`。 + +parent 只有在收到严格 direct-result message，并且既有 stdout／stderr close 或有界 drain barrier 完成后才结算 `.done`。后续 Job query 或 range settlement failure 只会使 `waitForExit()` reject。在该 `.done` barrier 之前发生 IPC loss 会使 `.done` 以 runner infrastructure failure reject；之后发生 IPC loss 会保留已经完成的 direct result，但仍使 range settlement reject。disconnect 或 result-send failure 会让 runner 停止协议工作、终止并关闭自己唯一的 Job handle，然后以非零状态退出。最后一个 Job handle 关闭会终止剩余成员，但不会把 disconnected 路径改写成成功的完全停稳证明。 + +### 私有分派与协议 + +source 启动通过 TypeScript source launcher 执行包内 runner 入口，built 启动解析 `@deepseek-ai/dsh-subprocess-local/runner` export，Python SDK 单文件可执行程序则从 `@deepseek-ai/dsh` 由打包层拥有的 `runtime-bootstrap.js` 进入。私有 selector 不存在时，该 bootstrap 导入公共 CLI；否则会删除 selector，并分派到同一 subprocess runner core。公共 `dsh` 参数解析器没有隐藏 runner mode，打包也不提供第二个 Node 可执行程序。 + +selector 是 per-spawn locator 或 sentinel，不是凭据或持久格式。Linux 使用一个严格 request 与一个可选严格 startup-error 文件；Windows 使用一条 IPC channel，承载闭合集 start、terminate、`target-exit`、`spawn-error`、`runner-error` 与 `start-cancelled` 消息。错误只携带有界的 Node-shaped 字段。缺失、额外、类型错误或未知字段都会 fail closed。target 环境可以包含 selector 名称及其 Windows 大小写变体，因为 provider 会单独传递 target 状态，并且只在私有选择值消费后才恢复该状态。 + +### Fallback 与 cleanup + +准确 bootstrap、现代且可读的 user-systemd manager，或保留 literal argv 的 scope 不可用时，Linux 会在 target 执行前进入 fallback。runner 入口、Win32 bindings 或 current-token Job probe 不可用时，Windows 普通启动会进入 fallback。macOS 普通启动、Windows ConPTY 与其他不受支持的宿主保留既有 PGID、`taskkill /T` 或带身份围栏的 PTY 观察机制。warning 会明确说明：逃离这些可观察关系的后代不保证被终止，也不保证延迟 `waitForExit()`。 + +正常 Cordis dispose 会独立启动 direct-result 与 range observation、请求终止，并等待每个自有 range。消费方 teardown 不检查普通 PID；它会保留原始 operation 或 startup error，同时尝试 terminate 与 final wait，并按消费方既有错误顺序保留 cleanup failure。range 一旦被确认为空，就会永久禁止后续向陈旧 identity 发送信号。 + +在 JavaScript 可观察的 host exit 期间，`LocalSubprocessRuntime` 会同步强制终止每个仍存活的句柄，不使用 Promise 或 timer。Linux 会发送既有 direct fallback kill 与准确 scope kill；Windows 会终止 runner，使其唯一 Job handle 关闭；PTY fallback 扫描仍是 best effort。每个句柄的失败相互隔离，也不改变宿主退出结果。JavaScript 无法运行的终止形态不属于该 listener 的保证。 + +## Existing decisions and supersession + +本 Note 拥有当前 native containment 机制。它局部更新了[subprocess seam](2026-07-26-subprocess-seam.zh.md)中的 provider 与 no-PID 事实、[持久化 PTY 会话](../feature/2026-07-16-persistent-pty-sessions.zh.md)中的 Linux teardown 事实、[宿主退出同步清理](../bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.zh.md)使用的 native target、[共享 Win32 process primitives](2026-08-19-shared-win32-process-primitives.zh.md)的 ordinary 消费方，以及[Python SDK profile 运行时](2026-08-23-python-sdk-dsh-profile-runtime.zh.md)选择的私有入口。每份 Note 都保留其余决策并继续处于 active 状态。 + +## Verification + +- provider 与协议测试套件固定同步 NUL 拒绝发生在启动副作用之前、严格 request／result 解码、target cwd 与完整环境恢复、私有变量碰撞、保留 argv 的 Linux PATH 查找、pre-exec error ownership、三种 scope 建立状态、全部 4 个 Windows result 分支、startup cancellation、result-send 与 IPC-disconnect failure、stdio settlement、active-process 完全停稳，以及唯一 handle cleanup。 +- 真实 Linux user-systemd 测试会分别通过生产入口运行一条普通命令与一条 `node-pty` `setsid`／reparent 场景。它们证明 scope signalling 与 collection、裸可执行文件查找、逃逸后代终止、range settlement，以及不变的 PTY PID、session、控制终端、前台输入、`/dev/tty`、readiness 与 startup-failure 语义。 +- native Windows 测试证明 suspended creation、resume 前 Job assignment、继承 stdio、默认后代继承、direct result、termination、active-process zero、异常／disconnected runner cleanup、kill-on-close 与同步 host-exit termination。source、built 与 Python packaged 冒烟测试进入同一 runner core。 +- 公共 seam 类型、local 与 E2B provider、LSP 与 subagent 消费方、shell fixture、README、Cordis catalog 与 keyless subprocess API snapshot 都不包含普通 PID；terminal PID 保留。 + +## Alternatives considered + +**保留 PID、把它改成可选值，或增加公共 `started` Promise。**不予采用，因为这些表示都会暴露不表示 managed range 的异步 provider identity，并诱导消费方从错误事实推断 startup 或完全停稳。 + +**扩展进程组、session、parent tree 或 PID 扫描。**不予采用，因为进程可以离开每一种观察关系；当 PTY helper 与 launcher 共用 session 时，更宽的 SID signalling 还可能命中无关进程。native OS membership 会持续存在，并且可以独立查询。 + +**让 parent 拥有或重新打开 Windows Job。**不予采用，因为复制 handle、named Job、`OpenJobObject`、process-handle handoff 与 completion port 会制造多个 lifecycle owner，却不能改善 direct-result 约定。一个 runner 可以统一拥有 target creation、Job membership、result production 与最终 handle closure。 + +**在 Windows 上通过 target stdio 或文件传递 control／result。**不予采用，因为用户字节与 EOF 必须继续以既有 Node stream 为权威，而 result file 或 polling 会制造第二个 result owner。一条 IPC channel 可以把 control 与 target stdio 分开。 + +**在公共 CLI 中解析隐藏 runner 参数，或发布另一个 Node 可执行程序。**不予采用，因为前者扩张公共应用语法，后者扩张分发面。packaging-only bootstrap 保留一个物理可执行程序与两个私有逻辑入口。 + +**缓存成功的 native probe，或在 native launch 失败后重放命令。**不予采用，因为 user-manager、入口与 Job availability 可以在两次 spawn 之间变化，而一次含糊 failure 之后的 replay 可能执行命令两次。 + +## Consequences + +受支持的 Linux 普通与 PTY 启动、Windows 普通启动会在后代逃离进程组或 direct parent 退出后继续拥有它们，同时 direct target result 与 range 完全停稳保持独立。代价是每次 spawn 都需要一个 Linux scope／request 或 Windows runner／IPC／Job 生命周期，而且所选 owner 无法证明 settlement 时会显式失败。 + +fallback 宿主继续运行命令，但携带可见的较弱保证。Windows ConPTY、macOS native containment、active breakaway 后代、旧版或缺失的 user-systemd 环境、target replay、持久 runner recovery，以及 JavaScript 无法执行的终止路径均不属于本决策。 diff --git a/.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.i18n.yaml index 2d351c09e4..126b306b78 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.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 .agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.md -2026-08-11-synchronous-subprocess-exit-cleanup.md: 1a6664c03ce0ae90b94d210645ac1401e078fae0 -2026-08-11-synchronous-subprocess-exit-cleanup.zh.md: 4c08847b24422d58025b6563785579d84c3ba6a7 +2026-08-11-synchronous-subprocess-exit-cleanup.md: 0914fdd51434f1f818e02484e652ab56236efb84 +2026-08-11-synchronous-subprocess-exit-cleanup.zh.md: 45f46fab6800db7b49be03b71419e1935459ae6e diff --git a/.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.md b/.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.md index 1a6664c03c..0914fdd514 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.md +++ b/.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.md @@ -17,7 +17,7 @@ The public subprocess seam correctly promises awaited quiescence during normal d The listener uses local-only final operations that are absent from the public `SubprocessHandle` and `SubprocessTerminalHandle` interfaces: - An ordinary handle synchronously signals its bound native scope or Job runner when available; the disclosed fallback sends SIGKILL to its detached POSIX process group or runs `taskkill /PID /T /F` on Windows. -- A terminal handle with a native Linux owner synchronously signals that scope with SIGKILL. A fallback terminal instead signals every captured and currently observable descendant, kills the PTY root, then rescans once for members that became observable during that boundary. +- A terminal handle synchronously signals every captured and currently observable descendant, kills the PTY root, then rescans once for members that became observable during that boundary. A native Linux handle then also signals its exact scope with SIGKILL; a fallback terminal ends after the observational sequence. - The service contains each target's failure and continues with the remaining handles. The callback creates no promise or timer, writes no diagnostic, and does not change the original exit code or error. Normal disposal remains the [subprocess seam's](../architecture/2026-07-26-subprocess-seam.md) terminate-and-join path: POSIX ordinary ranges receive TERM, the configured grace, then KILL; Windows ordinary ranges terminate immediately; and every ordinary or terminal cleanup is awaited to quiescence. The synchronous path requests final termination but does not publish a completion result or claim the OS range is already gone when the callback returns. Remote providers retain their own sandbox ownership and do not inherit a local Node listener. @@ -48,4 +48,4 @@ Unit evidence pins synchronous native-owner and fallback delivery, native termin Each active local subprocess service contributes one process-global exit listener. Successful disposal removes it with the service effect; failed disposal retains it with the targets that still require final termination. Fatal exit gives up grace, output draining, and an in-process quiescence proof in exchange for issuing the strongest available local termination before the host disappears. Normal disposal keeps those guarantees and costs unchanged. -The listener cannot cover failures that do not execute JavaScript. Supported Linux terminals signal the scope described by the [containment decision](2026-08-20-subprocess-native-containment.md); fallback terminals still cannot discover a descendant that escaped before the provider observed it. +The listener cannot cover failures that do not execute JavaScript. Supported Linux terminals signal the scope described by the [native-containment decision](../architecture/2026-08-28-subprocess-native-containment.md); fallback terminals still cannot discover a descendant that escaped before the provider observed it. diff --git a/.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.zh.md b/.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.zh.md index 4c08847b24..45f46fab68 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.zh.md @@ -17,7 +17,7 @@ Status: implemented 该 listener使用本地实现私有的最终操作；公共 `SubprocessHandle`和 `SubprocessTerminalHandle`接口不包含这些操作： - 普通 handle在可用时同步向绑定的 native scope 或 Job runner 发信号；已披露的 fallback 会向 detached POSIX进程组发送 SIGKILL，或在 Windows运行 `taskkill /PID /T /F`。 -- 具有 native Linux owner 的 terminal handle 会同步向该 scope 发送 SIGKILL。fallback terminal 则向全部已捕获及当前可观察的后代发送信号，终止 PTY root，然后再扫描一次并终止在该边界期间变得可观察的成员。 +- terminal handle 会同步向全部已捕获及当前可观察的后代发送信号，终止 PTY root，然后再扫描一次并终止在该边界期间变得可观察的成员。具有 native Linux owner 的 handle 随后还会向其准确 scope 发送 SIGKILL；fallback terminal 则在观察序列后结束。 - 服务分别包含每个目标的失败并继续处理其余 handle。回调不会创建 Promise或 timer，不写诊断，也不改变原始退出码或错误。 正常 dispose继续使用[subprocess seam](../architecture/2026-07-26-subprocess-seam.zh.md)的先终止再等待退出路径：POSIX ordinary range 先接收 TERM，经过配置的宽限期后再接收 KILL；Windows ordinary range 立即终止；每个 ordinary 或 terminal 清理都会等待完全停稳。同步路径只请求最终终止，不发布完成结果，也不声称回调返回时 OS range 已经消失。远程 provider继续由其 sandbox独立拥有，不继承本地 Node listener。 @@ -48,4 +48,4 @@ Status: implemented 每个有效的本地 subprocess service都会贡献一个进程全局 exit listener。成功的 dispose会随服务 effect移除它；失败的 dispose会让它与仍需最终终止的目标一起保留。致命退出放弃宽限、输出排空与进程内停稳证明，以换取宿主消失前发出本地可用的最强终止操作。正常 dispose的保证与成本保持不变。 -listener 无法覆盖不执行 JavaScript 的故障。受支持的 Linux terminal 会向[containment decision](2026-08-20-subprocess-native-containment.zh.md)所述的 scope 发出信号；fallback terminal 仍无法发现 provider 首次观察前已经逃逸的后代。 +listener 无法覆盖不执行 JavaScript 的故障。受支持的 Linux terminal 会向[原生收容决策](../architecture/2026-08-28-subprocess-native-containment.zh.md)所述的 scope 发出信号；fallback terminal 仍无法发现 provider 首次观察前已经逃逸的后代。 diff --git a/.agents/notes/implemented/bug-fix/2026-08-20-subprocess-native-containment.md b/.agents/notes/implemented/bug-fix/2026-08-20-subprocess-native-containment.md deleted file mode 100644 index 4ed116f5db..0000000000 --- a/.agents/notes/implemented/bug-fix/2026-08-20-subprocess-native-containment.md +++ /dev/null @@ -1,43 +0,0 @@ -# Agent Note: Local subprocesses use native managed ranges where supported - -Status: implemented - -English | [中文](2026-08-20-subprocess-native-containment.zh.md) - -## Problem - -The local subprocess provider treated a POSIX process group or a Windows direct-parent tree as the managed range. A descendant could call `setsid`, double-fork, or outlive the direct parent, so `terminate()` could miss work that `waitForExit()` had already declared gone. The direct command result and the complete managed range are different lifecycle facts and must not be collapsed into one wrapper exit code. - -## Decision - -`LocalSubprocessRuntime` selects containment before every eligible ordinary or terminal user command. Linux rechecks the live user manager for every launch; successful stable systemd-scope and ordinary-runner probes are cached for the provider lifetime, failed probes are retried, and terminal selection never probes the ordinary runner. Windows likewise caches only a successful Job-runner probe. The weaker-path warning is emitted at most once per provider. Linux uses a transient user-systemd scope only when the user manager is readable and `systemd-run` supports `--expand-environment=no`. Windows ordinary launch uses a local runner backed by `@deepseek-ai/dsh-win32-process`; it creates the target suspended, assigns it to a kill-on-close Job, and resumes it only after assignment. Each native launch binds a package-private owner with only `signal()` and `waitForExit()` responsibilities. - -The common spawn lifecycle still owns stdio dispositions, bounded collection, direct outcome, abort handling, termination scheduling, and host-exit registration. Linux scope and POSIX process-group owners deliver TERM and then KILL after the configured grace; Windows Job and `taskkill` owners force-terminate on the first request. `.done` comes from the target process. A private `0600` single-spawn request/event transport lets the Linux or Windows runner report Node-shaped target spawn failures and the target exit independently of the scope or Job lifetime. `waitForExit()` succeeds only after the same owner used by `terminate()` confirms that the OS range is empty; once confirmed, the owner permanently ignores later signals. - -Linux ordinary user argv never enters the `systemd-run` command line. The runner consumes it from the private request, spawns the target with the exact cwd and scrubbed-plus-explicit environment, and reports the direct result. The packaged carrier re-enters its executable through the private dispatch owned by the [single-file runtime](../architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md), and the Linux capability probe invokes that same runner entry before selecting native mode. Scope TERM leaves the runner alive long enough to report a TERM-trapping target. If scope KILL prevents a final target event, the Linux launch reports `SIGKILL` only after that KILL was attempted and the owner proves the scope empty; an unrelated runner or manager failure still rejects. - -Linux terminal launch passes `systemd-run --user --scope --quiet --collect --expand-environment=no -- ` directly to `node-pty`; `systemd-run --scope` replaces itself with the target, so node-pty continues to observe the target PID, session leader, process group, controlling terminal, foreground input wait, and prompt readiness. The terminal handle binds the same scope owner for normal termination and host-exit KILL, so a descendant that reparents or creates a new session remains in the managed range without a second PTY runner or a continuous process-table monitor. - -On Windows the parent creates private named-pipe endpoints for non-inherited streams, while the runner opens only the target-side handles. That runner creates the target suspended, assigns it to its unnamed kill-on-close Job, resumes it, appends the target identity to the private event file, and closes its pipe handles before processing control messages. The parent returns the handle immediately with `pid` undefined and publishes that identity when its asynchronous event reader observes the record. The runner retains the original target process handle and Job until it has reported direct exit and `QueryInformationJobObject` reports zero active members. The parent never opens the target process or Job; IPC termination and disconnect remain the only control path into the runner. - -When native capability is unavailable before target execution, the provider warns once and uses the existing PGID or `taskkill /T` fallback. macOS always takes that path because it has no supported public persistent process owner. After native launch is selected, any runner, manager, or result-transport failure is reported; the user command is never replayed through fallback. - -## Verification - -Linux native evidence on Ubuntu 24.04 x86_64 with systemd 255.4 runs separate ordinary and node-pty `setsid`/reparenting scenarios plus Node-shaped spawn failures without replay. The PTY scenario pins the node-pty PID, process group, session leader, controlling terminal, `/dev/tty` input, foreground `inputWaiting`, and termination of the escaped descendant. Windows native evidence covers one default-inheritance descendant scenario plus raw stdin, direct stdout/stderr EOF, direct result versus Job quiescence, and target spawn failures. Shared tests pin literal argv, one-time fallback warnings, unreadable-owner rejection, no post-stop signals, abort and host-exit routing, and source, built, and packaged-executable runner entries. - -## Alternatives considered - -**Scan the process table for escaped descendants.** Rejected because parent and PID snapshots do not provide a persistent ownership fact and can follow PID reuse. - -**Expose a public backend selector or generic launch framework.** Rejected because callers need one subprocess contract, while systemd and Job creation have different launch mechanics. Only the signal/wait owner is common. - -**Move the Windows Job or direct-process observation into the parent.** Rejected because a named Job, cross-process open, release handshake, or second process handle would duplicate runner-owned lifecycle facts without producing a second user result. The parent owns only public stdio endpoints and runner control. - -**Support legacy systemd argument expansion.** Rejected because shell-style expansion can change user argv. Hosts without the literal-argument option use the disclosed fallback. - -**Use private macOS coalition APIs.** Rejected because no supported public owner gives the required membership and settlement contract. - -## Consequences - -Supported Linux and Windows hosts retain descendants after session changes or reparenting, and termination and settlement read one OS-owned range. Linux pays one live-manager probe before every eligible ordinary or terminal target; stable scope and ordinary-runner probes stop after their first success, retry after failure, and carry a 5-second bound per command. Terminal launch never runs the ordinary-runner probe. Windows repeats its bounded Job-runner probe only until the first success. A native ordinary handle has no per-launch target-publication handshake or timeout: it returns with `pid` undefined, and the asynchronous 100 ms event-file poll publishes the PID or settles `.done`. A runner that remains alive without a terminal event therefore leaves those facts pending until it exits or the range is terminated. Each native ordinary range retains one runner process until settlement; Linux PTY launch adds no runner. Windows also creates private per-spawn named-pipe endpoints, but no named Job or parent target-process handle. Systemd state reads use asynchronous 200 ms polling rather than blocking the host event loop. Windows managed ranges terminate immediately; `graceMs` still bounds collected-pipe draining. The private runner adds one built entry and short-lived private files but no public configuration or durable format. Windows breakaway descendants remain outside the guarantee, and external termination in the narrow CreateProcess-to-Job-assignment interval can leave a suspended target. Fallback hosts remain usable with an explicit weaker guarantee. diff --git a/.agents/notes/implemented/bug-fix/2026-08-20-subprocess-native-containment.zh.md b/.agents/notes/implemented/bug-fix/2026-08-20-subprocess-native-containment.zh.md deleted file mode 100644 index 95fdd1c73c..0000000000 --- a/.agents/notes/implemented/bug-fix/2026-08-20-subprocess-native-containment.zh.md +++ /dev/null @@ -1,43 +0,0 @@ -# Agent Note: Local subprocesses use native managed ranges where supported - -Status: implemented - -[English](2026-08-20-subprocess-native-containment.md) | 中文 - -## Problem - -本地 subprocess provider 把 POSIX 进程组或 Windows direct-parent tree 当作 managed range。descendant 可以调用 `setsid`、double-fork 或活得比 direct parent 更久，导致 `terminate()` 漏掉的工作已经被 `waitForExit()` 宣布消失。direct command result 与完整 managed range 是不同的生命周期事实，不能压成一个 wrapper exit code。 - -## Decision - -`LocalSubprocessRuntime` 会在每次符合条件的 ordinary 或 terminal 用户命令前选择 containment。Linux 会在每次 launch 时重查 live user manager；稳定的 systemd scope 与 ordinary runner 探测只在成功后按 provider 生命周期缓存，失败探测会重试，而且 terminal 选择绝不会探测 ordinary runner。Windows 同样只缓存成功的 Job runner 探测。较弱路径的告警由每个 provider 至多发出一次。Linux 只在 user manager 可读且 `systemd-run` 支持 `--expand-environment=no` 时使用 transient user-systemd scope。Windows ordinary launch 使用由 `@deepseek-ai/dsh-win32-process` 支撑的本地 runner；它以 suspended 状态创建目标，把目标分配给 kill-on-close Job，并只在分配后恢复。每次 native launch 只绑定一个提供 `signal()` 与 `waitForExit()` 职责的 package-private owner。 - -common spawn lifecycle 继续拥有 stdio disposition、有界收集、direct outcome、abort 处理、termination scheduling 与 host-exit 注册。Linux scope 与 POSIX 进程组 owner 先投递 TERM，并在配置的 grace 后投递 KILL；Windows Job 与 `taskkill` owner 在首次请求时立即强制终止。`.done` 来自 target process。private `0600` single-spawn request/event transport 让 Linux 或 Windows runner 分别报告 Node-shaped target spawn failure 与 target exit，不依赖 scope 或 Job 生命周期。`waitForExit()` 只在 `terminate()` 使用的同一 owner 确认 OS range 为空后成功；首次确认后，该 owner 永久忽略后续 signal。 - -Linux ordinary user argv 从不进入 `systemd-run` 命令行。runner 从 private request 消费 argv，以精确 cwd 和 scrubbed-plus-explicit environment 启动目标，并报告 direct result。打包载体通过[单文件运行时](../architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md)拥有的 private dispatch 重新进入自身 executable；Linux capability probe 在选择 native mode 前调用同一个 runner entry。scope TERM 会让 runner 存活足够久，以便报告 trap TERM 的目标。若 scope KILL 阻止最终 target event，Linux launch 只会在该 KILL 已尝试且 owner 证明 scope 为空后报告 `SIGKILL`；无关的 runner 或 manager failure 仍会拒绝。 - -Linux terminal launch 会把 `systemd-run --user --scope --quiet --collect --expand-environment=no -- <原始 argv>` 直接交给 `node-pty`；`systemd-run --scope` 会以 target 替换自身，因此 node-pty 继续观察 target PID、session leader、process group、控制终端、前台 input wait 与 prompt readiness。terminal handle 会为正常终止与 host-exit KILL 绑定同一个 scope owner，因此已 reparent 或新建 session 的 descendant 仍留在 managed range 内，无需第二个 PTY runner 或持续进程表 monitor。 - -Windows parent 为非继承流创建 private named-pipe endpoint，runner 只打开 target 侧 handle。该 runner 以 suspended 状态创建目标，把目标分配给自身 unnamed kill-on-close Job，恢复目标，把 target identity 追加到 private event file，并在处理 control message 前关闭自身 pipe handle。parent 会立即返回 `pid` 为 `undefined` 的 handle，并在异步 event reader 观察到该记录后发布 identity。runner 会保留原始 target process handle 与 Job，直到报告 direct exit 且 `QueryInformationJobObject` 报告 active member 归零。parent 不打开 target process 或 Job；IPC termination 与 disconnect 是进入 runner 的唯一控制路径。 - -native capability 在目标执行前不可用时，provider 只告警一次并使用既有 PGID 或 `taskkill /T` fallback。macOS 因没有受支持的公开 persistent process owner，始终进入该路径。native launch 一旦被选择，runner、manager 或 result transport 的任何失败都会直接报告；用户命令绝不会经 fallback 重放。 - -## Verification - -Linux native 证据在 Ubuntu 24.04 x86_64、systemd 255.4 环境分别运行 ordinary 与 node-pty `setsid`/reparenting 场景，并覆盖不重放的 Node-shaped spawn failure。PTY 场景固定 node-pty PID、process group、session leader、控制终端、`/dev/tty` 输入、前台 `inputWaiting`，以及 escaped descendant 的终止。Windows native 证据运行一个默认继承 descendant 场景，并覆盖 raw stdin、direct stdout/stderr EOF、direct result 与 Job quiescence 的区别，以及 target spawn failure。shared tests 固定 literal argv、一次性 fallback warning、owner 不可读时拒绝、停稳后不再发 signal、abort 与 host-exit 路由，以及 source、built 和 packaged-executable runner entry。 - -## Alternatives considered - -**扫描进程表寻找 escaped descendant。** 拒绝，因为 parent 与 PID snapshot 不提供持续所有权事实，还可能跟随 PID reuse。 - -**暴露公共 backend selector 或通用 launch framework。** 拒绝，因为调用方只需要一个 subprocess contract，而 systemd 与 Job creation 具有不同 launch mechanics；只有 signal/wait owner 是共同部分。 - -**把 Windows Job 或 direct-process observation 移到 parent。** 拒绝，因为 named Job、cross-process open、release handshake 或第二个 process handle 会重复 runner 已拥有的生命周期事实，却不会产生第二个用户结果。parent 只拥有公共 stdio endpoint 与 runner control。 - -**支持 legacy systemd argument expansion。** 拒绝，因为 shell-style expansion 会改变 user argv；缺少 literal-argument option 的宿主使用已披露的 fallback。 - -**使用 private macOS coalition API。** 拒绝，因为没有受支持的公开 owner 能提供所需 membership 与 settlement contract。 - -## Consequences - -受支持的 Linux 与 Windows 宿主会在 session 变化或 reparent 后继续拥有 descendant，termination 与 settlement 读取同一个 OS-owned range。Linux 会在每个符合条件的 ordinary 或 terminal target 前执行一次 live manager 探测；稳定的 scope 与 ordinary runner 探测会在首次成功后停止，失败后则重试，每条命令的上限为 5 秒。terminal launch 绝不会运行 ordinary runner 探测。Windows 的有界 Job runner 探测也只重复到首次成功。native ordinary handle 没有每次 launch 的 target publication 握手或超时：它以 `pid` 为 `undefined` 的状态返回，再由每 100 ms 异步读取一次的 event file 发布 PID 或结算 `.done`。runner 如果保持存活却始终没有 terminal event，这些事实会保持待定，直到 runner 退出或该范围被终止。每个 native ordinary range 会保留一个 runner process 直到 settlement；Linux PTY launch 不增加 runner。Windows 还会创建 private per-spawn named-pipe endpoint，但不会创建 named Job 或 parent target-process handle。systemd state 每 200 ms 异步读取一次，不会阻塞宿主事件循环。Windows managed range 会立即终止；`graceMs` 仍用于限制 collected-pipe 排空。private runner 增加一个 built entry 和短期 private files，但不增加公共配置或 durable format。Windows breakaway descendant 仍不在保证范围；runner 在 CreateProcess 到 Job assignment 的极窄区间遭外力终止时可能留下 suspended target。fallback 宿主继续可用，但保证会被明确削弱。 diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml index d4e5b38da7..18130686dc 100644 --- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md -2026-07-16-persistent-pty-sessions.md: 08ccf64586034b5a0524889f33da89213ac7275d -2026-07-16-persistent-pty-sessions.zh.md: 5225d781fc8eba1fb4a6c7f4d3b5d4d87547b71d +2026-07-16-persistent-pty-sessions.md: 8128e4466c0845ee9749c8bff7d8e982a9780133 +2026-07-16-persistent-pty-sessions.zh.md: ad7ac3c4a51bd01fc20408197fdf857cac036e33 diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md index 08ccf64586..8128e4466c 100644 --- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md +++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md @@ -45,7 +45,7 @@ A registered `shell` backend constrains how a terminal starts; it does not const Sandboxing confines local process effects but does not make arbitrary shell input safe: network calls and other external side effects remain governed by deployment policy. Tool descriptions state that PTY sessions are less auditable than one-shot tools and should be used only when persistence or interactive stdin is necessary. -The local subprocess terminal primitive uses only public `node-pty` capabilities: child PID, `data` and `exit` notifications, `write`, and `kill`. It does not assume access to the native master fd or call `waitpid` from TypeScript. Platform process inspectors below that primitive derive foreground process groups and parent/child identity from `/proc` on Linux and `ps` on macOS. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns this process/consumer split. +The local subprocess terminal primitive uses only public `node-pty` capabilities: child PID, `data` and `exit` notifications, `write`, and `kill`. It does not assume access to the native master fd or call `waitpid` from TypeScript. On supported Linux hosts the [native-containment owner](../architecture/2026-08-28-subprocess-native-containment.md) starts that same PTY command inside a user-systemd scope without changing its PID, session, controlling terminal, foreground-group, or readiness semantics. Platform process inspectors below the primitive still derive foreground process groups and fallback parent/child identity from `/proc` on Linux and `ps` on macOS. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns this process/consumer split. ### Six model-facing tools @@ -92,7 +92,9 @@ Background sends use the existing task completion notice and `job_output` result ### Process-tree teardown -The subprocess terminal handle owns the top-level terminal process and its session. On close it snapshots transitive descendants by parent PID in children-first order, sends `SIGTERM`, waits, rescans for children forked during shutdown, sends `SIGKILL` to the union, and verifies every non-zombie descendant left the process table before stopping the top-level process. A matching Linux zombie has no executable work and therefore counts as quiescent. Every captured PID includes process-start identity so reuse cannot redirect escalation. +On supported Linux hosts, the subprocess terminal handle binds the top-level PTY process to its transient user-systemd scope. Close sends `SIGTERM` to the direct PTY and the scope, waits for the manager to prove that range empty, and escalates to `SIGKILL` after the configured grace. Scope membership continues to include descendants that call `setsid` or reparent, while the PTY's direct exit notification remains the terminal outcome. + +Fallback hosts retain observational process-session cleanup. The handle snapshots transitive descendants by parent PID in children-first order, sends `SIGTERM`, waits, rescans for children forked during shutdown, sends `SIGKILL` to the union, and verifies every non-zombie descendant left the process table before stopping the top-level process. A matching Linux zombie has no executable work and therefore counts as quiescent. Every captured PID includes process-start identity so reuse cannot redirect escalation. Teardown reports top-level exit and survivor cleanup independently. The PTY session does not claim success merely because the shell exited: it calls `SubprocessTerminalHandle.terminate()` and awaits whole-session quiescence, propagating a cleanup failure that names survivors. A failed close is not cached forever: the registry and local session clear the fence only when it still names that failed attempt, so a later explicit or lifecycle close retries without disturbing a newer concurrent attempt. Service disposal still clears its backend, reservation, and owner-detacher registries when a close fails. @@ -158,7 +160,7 @@ The package ships concise tool guidance explaining persistent state, owner isola - Per-file coverage pins owner fencing, concurrent reservations, cancellation during pre-write inspection, unpublished-spawn cancellation and awaited teardown, sandbox-mode change rejection, retriable lifecycle cleanup, readiness tiers, rejection of pre-write stdin waits and delayed earlier prompts, the configured handoff grace holding the idle fallback past one poll and its rejection below `pollIntervalMs`, sanitizer carry state, complete UTF-8 bounds, task integration, schemas, and exact render intents. - Subprocess process fixtures cover non-leader and non-main-thread stdin waits, thread-local fd tables, the `/dev/tty` alias, supported kernel ABIs under user-mode emulation, rejection of fd 0 backed by a pipe, zombie quiescence, unreadable process state, unsupported architectures, and other false-positive rejection; macOS inspector logic is injected into the same unit suite. -- Real `node-pty` and PTY-consumer tests jointly exercise shell state, controlling-terminal input through `/dev/tty`, the exact attribution when process syscalls are readable, its bounded idle fallback when host policy denies them, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT`, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts. +- Real `node-pty` and PTY-consumer tests jointly exercise shell state, controlling-terminal input through `/dev/tty`, the exact attribution when process syscalls are readable, its bounded idle fallback when host policy denies them, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT`, a TERM-ignoring descendant, and immediate post-disposal quiescence. The Linux native smoke keeps the PTY PID, session leader, controlling terminal, foreground `inputWaiting`, and readiness while a reparented `setsid` descendant remains owned by the scope; fallback suites retain identity-fenced observational cleanup coverage. - A Loader-driven `cordis.yml` test mounts the real three-package composition and verifies that delayed pipeline output returns with the completed command instead of being classified as terminal-input readiness. The SDK minimal snapshot pins that output through the persistent Bash tool; ACP and headless snapshots pin the six terminal schemas, bounded results, and errors through opt-in overlays; TUI snapshots pin terminal and generic card presentation. - Package contracts, the architecture map, subsystem pages, generated catalogs, and the website API describe the same shipped surface. @@ -172,7 +174,7 @@ The package ships concise tool guidance explaining persistent state, owner isola **Persistent state can drift from the model's belief.** The model may forget its cwd or active REPL. Session summaries and retained output help recovery, but no prompt can make state persistence deterministic. -**A daemonized descendant can leave the local provider's captured tree.** A process that reparents before teardown is no longer discoverable from the `node-pty` root. The local terminal primitive accepts that cleanup gap instead of risking SID-wide signals to unrelated processes. +**Native Linux ownership closes the process-tree observation gap; fallback ownership does not.** A supported user-systemd scope retains a daemonized or reparented descendant as a member until the scope becomes empty. On macOS, Windows ConPTY, and Linux hosts that cannot establish the scope, a process that escapes before observational teardown can still evade the captured tree; the fallback accepts that gap instead of risking SID-wide signals to unrelated processes. **A shell can cause external side effects.** Session sandboxing and environment scrubbing reduce local exposure but do not undo pushes, API calls, or messages. Deployments that cannot tolerate those effects must omit PTY or add network policy. diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md index 5225d781fc..ad7ac3c4a5 100644 --- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md +++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md @@ -45,7 +45,7 @@ agent scope dispose（资源释放）时先撤销注册，再等待全部所属 沙箱限制本地进程副作用，但不会让任意 shell 输入自动安全：网络调用和其他外部副作用仍由部署策略治理。工具描述会说明 PTY 会话比一次性工具更难审计，只应在确实需要持久状态或交互式 stdin 时使用。 -本地子进程终端原语只使用 `node-pty` 的公开能力：子进程 PID、`data` 与 `exit` 通知、`write` 和 `kill`。它不假设能访问原生 master fd，也不从 TypeScript 调用 `waitpid`。该原语下的平台进程检查器在 Linux 上通过 `/proc`、在 macOS 上通过 `ps` 推导前台进程组和父子进程身份。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.zh.md)负责定义这种进程／消费方拆分。 +本地子进程终端原语只使用 `node-pty` 的公开能力：子进程 PID、`data` 与 `exit` 通知、`write` 和 `kill`。它不假设能访问原生 master fd，也不从 TypeScript 调用 `waitpid`。在受支持的 Linux 宿主上，[原生收容 owner](../architecture/2026-08-28-subprocess-native-containment.zh.md)会在 user-systemd scope 内启动同一条 PTY 命令，同时保持 PID、session、控制终端、前台进程组与就绪语义。该原语下的平台进程检查器仍在 Linux 上通过 `/proc`、在 macOS 上通过 `ps` 推导前台进程组和 fallback 父子进程身份。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.zh.md)负责定义这种进程／消费方拆分。 ### 6 个面向模型的工具 @@ -92,7 +92,9 @@ Tier 2 在持续 `idleSilenceMs` 没有输出后返回 `inferred_idle`，因此 ### 进程树 teardown -子进程终端句柄拥有顶层终端进程及其会话。关闭时，它按父 PID 以子进程优先顺序捕获传递后代、发送 `SIGTERM` 并等待，然后重新扫描关停期间 fork 出的子进程，向二者并集发送 `SIGKILL`，并在停止顶层进程前验证每个非僵尸后代都已离开进程表。身份匹配的 Linux 僵尸进程已无可执行工作，因此视为完全停稳。每个捕获的 PID 都包含进程启动身份，避免 PID 复用把升级信号发给无关进程。 +在受支持的 Linux 宿主上，subprocess 终端句柄会把顶层 PTY 进程绑定到临时 user-systemd scope。close 会向 direct PTY 与 scope 发送 `SIGTERM`，等待 manager 证明该 range 为空，并在配置的宽限期后升级到 `SIGKILL`。调用 `setsid` 或发生 reparent 的后代仍属于 scope，而 PTY 的 direct exit 通知继续作为终端结果。 + +fallback 宿主保留观察式进程 session 清理。句柄会按父 PID 以子进程优先顺序捕获传递后代、发送 `SIGTERM` 并等待，然后重新扫描关停期间 fork 出的子进程，向二者并集发送 `SIGKILL`，并在停止顶层进程前验证每个非僵尸后代都已离开进程表。身份匹配的 Linux 僵尸进程已无可执行工作，因此视为完全停稳。每个捕获的 PID 都包含进程启动身份，避免 PID 复用把升级信号发给无关进程。 teardown 独立报告顶层进程退出与存活进程清理。PTY 会话不会只因 shell 退出就声称成功：它会调用 `SubprocessTerminalHandle.terminate()` 并等待整个会话完全停稳，若清理失败则向外传播并列出存活者。失败的 close 不会永久缓存：注册表与本地会话各自仅在关闭围栏仍指向该次失败尝试时才将其清除，因此后续的显式 close 或生命周期 close 会重试，且不会干扰较新的并发尝试。即使某个 close 失败，服务 dispose 仍会清空其后端、预留与 owner detacher 注册表。 @@ -158,7 +160,7 @@ plugins: - 逐文件覆盖测试锁定了 owner 隔离、并发预留、写入前检查期间的取消、未发布 spawn 的取消与等待式 teardown、沙箱模式变更拒绝、可重试的生命周期清理、就绪层级、对写入前 stdin 等待与延迟到达的先前 prompt 的拒绝、配置化交接宽限把 idle fallback 顶过一次轮询以及低于 `pollIntervalMs` 时的拒绝、sanitizer carry state、完整 UTF-8 结果上限、task 集成、schema 和精确 render intent。 - 子进程 fixture（测试前置数据）覆盖非 leader 与非主线程的 stdin 等待、线程本地 fd 表、`/dev/tty` 别名、用户态模拟下受支持的内核 ABI、拒绝把指向管道的 fd 0 当作终端输入、僵尸进程完全停稳、不可读进程状态、不支持的架构和其他误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。 -- 真实 `node-pty` 与 PTY 消费方测试共同在受支持宿主上覆盖 shell 状态、通过 `/dev/tty` 读取控制终端输入、进程 syscall 可读时的精确归因、宿主策略拒绝读取时的有界 idle fallback、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。 +- 真实 `node-pty` 与 PTY 消费方测试共同覆盖 shell 状态、通过 `/dev/tty` 读取控制终端输入、进程 syscall 可读时的精确归因、宿主策略拒绝读取时的有界 idle fallback、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。Linux native 冒烟测试会在一个 reparent 的 `setsid` 后代仍由 scope 拥有时，保持 PTY PID、session leader、控制终端、前台 `inputWaiting` 与 readiness；fallback 测试套件继续覆盖带身份围栏的观察式清理。 - Loader 驱动的 `cordis.yml` 测试挂载真实三包组合，并验证延迟到达的流水线输出随已完成命令返回，而不会被归类为终端输入就绪。SDK minimal 快照通过持久 Bash 工具固定该输出；ACP 与 headless 快照通过 opt-in overlay 固定 6 个终端 schema、有界结果和错误；TUI 快照固定 terminal 与 generic 卡片展示。 - 包约定、架构图、子系统页面、生成目录和 website API 描述同一个已发布接口。 @@ -172,7 +174,7 @@ plugins: **持久状态可能偏离模型认知。**模型可能忘记 cwd 或活跃 REPL。会话摘要和保留输出有助恢复，但任何提示词都无法让状态持久化变成确定行为。 -**daemonized 后代进程可能离开本地提供方捕获的进程树。**在 teardown 前 reparent 的进程无法再从 `node-pty` 根进程发现。本地终端原语接受这个清理缺口，不冒险按 SID 向无关进程发送信号。 +**Linux native ownership 消除了进程树观察缺口，fallback ownership 没有。**受支持的 user-systemd scope 会持续保有 daemonized 或 reparent 后代，直到 scope 为空。在 macOS、Windows ConPTY，以及无法建立 scope 的 Linux 宿主上，观察式 teardown 开始前已经逃逸的进程仍可能避开捕获树；fallback 接受这个缺口，不冒险按 SID 向无关进程发送信号。 **Shell 可以造成外部副作用。**会话沙箱和环境清洗降低本地暴露，但无法撤销 push、API 调用或消息发送。无法容忍这些副作用的部署必须省略 PTY 或增加网络策略。 diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml index 491c5f953f..dcc666c622 100644 --- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.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 .agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md -2026-07-22-cross-platform-test-fixtures.md: 36df88153cf9419f6eb5ce58195d2c62fd56cc71 -2026-07-22-cross-platform-test-fixtures.zh.md: 8785ef6bbc4e7715dcaf25fe0a241e596e1159d1 +2026-07-22-cross-platform-test-fixtures.md: 9114481543d6cae1661cbed70868eddb2faa09fc +2026-07-22-cross-platform-test-fixtures.zh.md: 710ec5887f02b5c3c71d69f16ab726323501ac92 diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md index 36df88153c..9114481543 100644 --- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md +++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md @@ -16,7 +16,7 @@ Tests of platform-neutral behavior construct absolute paths and `file:` URIs wit Transport-failure tests inject the connection's message writer and deliver the same asynchronous write callback error that a real Node stream would report. The production writer still writes framed messages to child stdin. This keeps a real child alive while the test deterministically distinguishes transport failure from process exit without reaching into platform-specific pipe handles. -Language-server teardown delegates to the subprocess provider's managed range: supported local Linux uses a user-systemd scope and Windows uses a kill-on-close Job, while explicit fallbacks use a negative process-group id or synchronous `taskkill /T /F`. See the [ordinary subprocess native-containment decision](../bug-fix/2026-08-20-subprocess-native-containment.md). Windows fallback treats every taskkill result as best-effort and ignores command, permission, absent-tree, and other status failures. A read-only provider query retries once only when its selected pooled transport fails before or during that query; errors from a still-live server are not replayed. Terminal tests wait for their observable rendered output instead of assuming one event-loop turn is sufficient. +Language-server teardown targets the whole descendant tree through a negative process-group id on POSIX and synchronous `taskkill /T /F` on Windows. Windows suppresses only taskkill's already-absent-tree status; command, permission, and other tree-kill failures remain teardown failures. A read-only provider query retries once only when its selected pooled transport fails before or during that query; errors from a still-live server are not replayed. Terminal tests wait for their observable rendered output instead of assuming one event-loop turn is sufficient. Tests for a genuinely POSIX-only primitive use a narrow Windows exclusion on that case. Adjacent cross-platform cases continue to pin non-regular file rejection, unavailable command rejection, and inaccessible working-directory rejection. Supported Windows paths remain inside the per-file coverage gate rather than being excluded with their test files. @@ -30,4 +30,4 @@ Tests for a genuinely POSIX-only primitive use a narrow Windows exclusion on tha ## Consequences -Portable fixtures are slightly more explicit because expected paths derive from shared native constants and transport failures enter through a narrow writer hook. Platform-only exclusions require a neighboring cross-platform assertion for the product behavior they support. Supported native Windows hosts use Job ownership; fallback Windows teardown makes one synchronous best-effort `taskkill` call after graceful protocol shutdown has failed. Its result is ignored, so the fallback neither reports taskkill failure nor proves descendant exit before cleanup returns. +Portable fixtures are slightly more explicit because expected paths derive from shared native constants and transport failures enter through a narrow writer hook. Platform-only exclusions require a neighboring cross-platform assertion for the product behavior they support. Windows teardown depends on the host `taskkill` command after graceful protocol shutdown has failed; a successful synchronous result keeps disposal bounded and makes descendant exit observable before cleanup returns, while a failed tree kill remains visible to the disposer. diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md index 8785ef6bbc..710ec5887f 100644 --- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md +++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md @@ -16,7 +16,7 @@ Status: implemented 传输故障测试会注入连接的消息写入器，并传入与真实 Node 流相同的异步写入回调错误。生产写入器仍会把分帧消息写入子进程 stdin。这种方式让真实子进程保持存活，使测试无需触及平台特有的管道句柄，也能确定性地区分传输故障与进程退出。 -语言服务器的资源清理会委托给 subprocess provider 的 managed range：受支持的本地 Linux 使用 user-systemd scope，Windows 使用 kill-on-close Job；明确的 fallback 才使用负数进程组 ID 或同步 `taskkill /T /F`。参见[普通子进程 native containment 决策](../bug-fix/2026-08-20-subprocess-native-containment.zh.md)。Windows fallback 把所有 taskkill 结果都视为 best-effort，并忽略命令、权限、进程树不存在及其他状态失败。只读的提供方查询仅在选定的池化传输于该次查询开始前或执行期间失效时重试一次；服务器仍存活时返回的错误不会触发重试。终端测试会等待可观察的渲染输出，不假设一次事件循环轮转已经足够。 +语言服务器的资源清理会终止整棵后代进程树：POSIX 使用负数进程组 ID，Windows 同步执行 `taskkill /T /F`。Windows 只会忽略 taskkill 返回的「进程树已经不存在」状态；命令执行失败、权限错误及其他终止进程树的失败仍属于资源清理失败。只读的提供方查询仅在选定的池化传输于该次查询开始前或执行期间失效时重试一次；服务器仍存活时返回的错误不会触发重试。终端测试会等待可观察的渲染输出，不假设一次事件循环轮转已经足够。 对于真正仅存在于 POSIX 的原语，测试只在该用例上排除 Windows。相邻的跨平台用例仍会固定拒绝非普通文件、不可用命令和无法访问的工作目录的行为。Windows 上受支持的路径仍受逐文件覆盖率门禁约束，不会随测试文件一起排除。 @@ -30,4 +30,4 @@ Status: implemented ## 后果 -可移植 fixture 需要更显式地构造，因为预期路径要从共享的原生常量派生，传输故障则通过狭窄的写入器钩子注入。仅适用于特定平台的排除项必须配有相邻的跨平台断言，以继续覆盖相应的产品行为。受支持的原生 Windows 宿主使用 Job 所有权；fallback Windows 的资源清理则在协议级优雅关停失败后同步发出一次 best-effort `taskkill`。该调用的结果会被忽略，因此 fallback 既不报告 taskkill 失败，也不证明清理返回前后代进程已经退出。 +可移植 fixture 需要更显式地构造，因为预期路径要从共享的原生常量派生，传输故障则通过狭窄的写入器钩子注入。仅适用于特定平台的排除项必须配有相邻的跨平台断言，以继续覆盖相应的产品行为。协议级优雅关停失败后，Windows 上的资源清理依赖宿主的 `taskkill` 命令；命令同步执行成功时，可确保 dispose（资源释放）在有限时间内完成，并确保清理返回前即可观察到后代进程退出；若进程树终止失败，资源释放逻辑仍能观察到该失败。 diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts index 0758c8d32f..321849f2d9 100644 --- a/apps/cli/src/bin.ts +++ b/apps/cli/src/bin.ts @@ -11,8 +11,6 @@ import { fileURLToPath } from 'node:url' import { loadLayeredEnv } from '@deepseek-ai/dsh-app-boot' import { parseDshArgs } from './args.ts' -const PACKAGED_RUNNER_ARG = '--dsh-internal-subprocess-runner' - // Both the source tree (apps/cli/src) and the bundled bin (apps/cli/lib) sit // one directory under apps/cli, so the checked-in manifest resolves with the // same relative hop from either artifact. @@ -23,39 +21,30 @@ function readVersion(): string { return typeof manifest.version === 'string' ? manifest.version : '0.0.0' } -if (process.argv[2] === PACKAGED_RUNNER_ARG) { - process.argv.splice(2, 1) - const runnerEntry = new URL( - './lib/spawn-runner.js', - import.meta.resolve('@deepseek-ai/dsh-subprocess-local/package.json'), - ) - await import(runnerEntry.href) -} else { - const invocation = parseDshArgs(process.argv.slice(2), readVersion()) +const invocation = parseDshArgs(process.argv.slice(2), readVersion()) - switch (invocation.mode) { - case 'profile': { - const { runProfile } = await import('./profile-boot.ts') - await runProfile({ - environment: loadLayeredEnv('dsh'), - profile: invocation.profile, - patchFiles: invocation.patches, - args: invocation.args, - }) - break - } - case 'plugin': { - const { runPlugin } = await import('./plugin.ts') - process.exit(runPlugin(invocation.profile, invocation.args)) - break - } - case 'dump-config': { - const { runDumpConfig } = await import('./dump-config.ts') - runDumpConfig(invocation.profile, invocation.defaultOnly, invocation.patches) - break - } - default: - invocation satisfies never - throw new Error(`dsh: unhandled invocation mode ${JSON.stringify(invocation)}`) +switch (invocation.mode) { + case 'profile': { + const { runProfile } = await import('./profile-boot.ts') + await runProfile({ + environment: loadLayeredEnv('dsh'), + profile: invocation.profile, + patchFiles: invocation.patches, + args: invocation.args, + }) + break } + case 'plugin': { + const { runPlugin } = await import('./plugin.ts') + process.exit(runPlugin(invocation.profile, invocation.args)) + break + } + case 'dump-config': { + const { runDumpConfig } = await import('./dump-config.ts') + runDumpConfig(invocation.profile, invocation.defaultOnly, invocation.patches) + break + } + default: + invocation satisfies never + throw new Error(`dsh: unhandled invocation mode ${JSON.stringify(invocation)}`) } diff --git a/apps/cli/src/runtime-bootstrap.ts b/apps/cli/src/runtime-bootstrap.ts new file mode 100644 index 0000000000..b45fc89f2e --- /dev/null +++ b/apps/cli/src/runtime-bootstrap.ts @@ -0,0 +1,17 @@ +#!/usr/bin/env node +/** Packaging-only entry that keeps private runner dispatch outside the public CLI. */ + +/* v8 ignore file -- packaged-runtime smoke exercises this physical entry. */ + +const selectorName = 'DSH_SUBPROCESS_RUNNER' +const selection = process.env[selectorName] + +export {} + +if (selection === undefined) { + await import('./bin.ts') +} else { + Reflect.deleteProperty(process.env, selectorName) + const { runSelectedSubprocessRunner } = await import('@deepseek-ai/dsh-subprocess-local/runner') + await runSelectedSubprocessRunner(selection) +} diff --git a/apps/cli/tsdown.config.ts b/apps/cli/tsdown.config.ts index 51dec0dc6c..4fb14b0646 100644 --- a/apps/cli/tsdown.config.ts +++ b/apps/cli/tsdown.config.ts @@ -1,13 +1,15 @@ import { defineConfig } from 'tsdown' /** - * The dsh CLI ships one entry: the `bin` referenced by package.json `bin`. - * The root tsdown builds only `lib/types/index.js`, so this override points at - * `lib/types/bin.js` instead; its reachable mode modules bundle with it. + * The public package bin remains `bin`; `runtime-bootstrap` is selected only + * by the Python single-file packaging pipeline. * Declarations come from `tsc -b` (dts: false), matching every package. */ export default defineConfig({ - entry: ['lib/types/bin.js'], + entry: { + bin: 'lib/types/bin.js', + 'runtime-bootstrap': 'lib/types/runtime-bootstrap.js', + }, outDir: 'lib', format: ['esm'], platform: 'node', diff --git a/apps/web/tests/hmr-live.e2e.ts b/apps/web/tests/hmr-live.e2e.ts index 97fe5d5833..044c44ecd8 100644 --- a/apps/web/tests/hmr-live.e2e.ts +++ b/apps/web/tests/hmr-live.e2e.ts @@ -64,7 +64,7 @@ function waitForOutput(child: SubprocessHandle, pattern: RegExp, label: string): async function stopTree(child: SubprocessHandle): Promise { child.terminate() const stopped = await child.waitForExit(AbortSignal.timeout(15_000)) - if (!stopped) throw new Error(`process tree ${String(child.pid)} did not stop after termination escalation`) + if (!stopped) throw new Error('managed process range did not stop after termination escalation') await child.done } diff --git a/docs/subsystems/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml index dbed038726..7a2b2f777b 100644 --- a/docs/subsystems/subprocess.i18n.yaml +++ b/docs/subsystems/subprocess.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 docs/subsystems/subprocess.md -subprocess.md: 2ee79c8d9605ebf8c375e7bfad84063f5e1b17b9 -subprocess.zh.md: 01a837fa7613a714c3ce1d5f4ec4c29d3a632a26 +subprocess.md: 0e2adacbc5dfa4c4fa6ac922a47a81388fd75535 +subprocess.zh.md: 87e88344a7e027ae02557b0aa973f9f2ae7bacf0 diff --git a/docs/subsystems/subprocess.md b/docs/subsystems/subprocess.md index 2ee79c8d96..0e2adacbc5 100644 --- a/docs/subsystems/subprocess.md +++ b/docs/subsystems/subprocess.md @@ -132,7 +132,7 @@ interface SubprocessSpawnSpec { ## Handles: streams, readers, and managed-range termination -A spawn returns a live handle synchronously; the provider may publish its process identity later. Collect-mode readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; piped streams belong to the caller. `terminate()` starts the provider's documented procedure, and `waitForExit()` observes the same provider-managed range; staged providers may use `graceMs`, while immediate providers do not delay. Consumers can build their own teardown ladders over those two operations (the ACP backend's stdin-EOF-first `disposeAcpChild` is the template). +A spawn returns a live handle synchronously while target and managed-range identities remain provider-private. Collect-mode readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; piped streams belong to the caller. `terminate()` starts the provider's documented procedure, and `waitForExit()` observes the same provider-managed range; staged providers may use `graceMs`, while immediate providers do not delay. Consumers can build their own teardown ladders over those two operations (the ACP backend's stdin-EOF-first `disposeAcpChild` is the template). ```ts type-equiv /** @@ -140,12 +140,10 @@ A spawn returns a live handle synchronously; the provider may publish its proces * remains readable after exit; piped streams belong to the caller. * * Termination and {@link SubprocessHandle.waitForExit} use the same managed - * range. Each provider documents the process identity and range it can - * observe. + * range. Each provider documents the range it can observe and its signalling + * and observation limits. */ interface SubprocessHandle { - /** Provider-published target process identifier, or undefined until it is available. */ - readonly pid: number | undefined /** The child's stdin, present iff spawned with `stdin: 'pipe'`. */ readonly stdin: Writable | undefined /** The child's raw stdout, present iff spawned with `stdout: 'pipe'`. */ @@ -282,9 +280,9 @@ Abstract subprocess service. Subclass, implement spawn, and load the subclass as Implementations must honor these semantics: - Executable paths belong to one execution world shared with the mounted filesystem provider. -- spawn returns a live handle synchronously. Its pid is provider-owned and may remain unavailable during asynchronous startup. `done` resolves with the spawned command's exit facts and may reject for spawn or provider failures. +- spawn returns a live handle synchronously. Target identity remains provider-private; `done` resolves with the spawned command's exit facts and may reject for spawn or provider failures. - Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here. -- SubprocessHandle.terminate (and the spec's abort signal) starts the provider's documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its identity, signalling, and observability limits. +- SubprocessHandle.terminate (and the spec's abort signal) starts the provider's documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its signalling and observability limits. - Disposal of the service terminates all still-running managed processes and awaits their exit. - spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits. diff --git a/docs/subsystems/subprocess.zh.md b/docs/subsystems/subprocess.zh.md index 01a837fa76..87e88344a7 100644 --- a/docs/subsystems/subprocess.zh.md +++ b/docs/subsystems/subprocess.zh.md @@ -132,7 +132,7 @@ interface SubprocessSpawnSpec { ## 句柄：流、读取器与 managed-range 终止 -spawn 会同步返回活动句柄；provider 可以稍后发布其进程标识。收集模式的读取器接受全流字节偏移量且从不消费，因此独立读取器不会抢走彼此的增量；管道化的流归调用方所有。`terminate()` 启动 provider 记录的终止过程，`waitForExit()` 观察同一个 provider-managed range；分阶段 provider 可以使用 `graceMs`，立即终止的 provider 不会等待。消费方可以在这两项操作上构建自己的分级清理流程；ACP 后端先关闭 stdin 的 `disposeAcpChild` 是参考实现。 +spawn 会同步返回活动句柄，目标与受管范围标识则保留在 provider 内部。收集模式的读取器接受全流字节偏移量且从不消费，因此独立读取器不会抢走彼此的增量；管道化的流归调用方所有。`terminate()` 启动 provider 记录的终止过程，`waitForExit()` 观察同一个 provider-managed range；分阶段 provider 可以使用 `graceMs`，立即终止的 provider 不会等待。消费方可以在这两项操作上构建自己的分级清理流程；ACP 后端先关闭 stdin 的 `disposeAcpChild` 是参考实现。 ```ts type-equiv /** @@ -140,12 +140,10 @@ spawn 会同步返回活动句柄；provider 可以稍后发布其进程标识 * remains readable after exit; piped streams belong to the caller. * * Termination and {@link SubprocessHandle.waitForExit} use the same managed - * range. Each provider documents the process identity and range it can - * observe. + * range. Each provider documents the range it can observe and its signalling + * and observation limits. */ interface SubprocessHandle { - /** Provider-published target process identifier, or undefined until it is available. */ - readonly pid: number | undefined /** The child's stdin, present iff spawned with `stdin: 'pipe'`. */ readonly stdin: Writable | undefined /** The child's raw stdout, present iff spawned with `stdout: 'pipe'`. */ @@ -282,9 +280,9 @@ Abstract subprocess service. Subclass, implement spawn, and load the subclass as Implementations must honor these semantics: - Executable paths belong to one execution world shared with the mounted filesystem provider. -- spawn returns a live handle synchronously. Its pid is provider-owned and may remain unavailable during asynchronous startup. `done` resolves with the spawned command's exit facts and may reject for spawn or provider failures. +- spawn returns a live handle synchronously. Target identity remains provider-private; `done` resolves with the spawned command's exit facts and may reject for spawn or provider failures. - Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here. -- SubprocessHandle.terminate (and the spec's abort signal) starts the provider's documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its identity, signalling, and observability limits. +- SubprocessHandle.terminate (and the spec's abort signal) starts the provider's documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its signalling and observability limits. - Disposal of the service terminates all still-running managed processes and awaits their exit. - spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits. diff --git a/knip.json b/knip.json index 3a32c320dc..8781df91f4 100644 --- a/knip.json +++ b/knip.json @@ -306,12 +306,7 @@ }, "packages/subprocess/subprocess-local": { "entry": [ - "tests/**/*.spec.ts", "tests/**/*.e2e.ts" - ], - "project": [ - "src/**/*.ts", - "tests/**/*.ts" ] }, "packages/session/session-telemetry-otel": { @@ -682,6 +677,7 @@ }, "apps/cli": { "entry": [ + "src/runtime-bootstrap.ts", "tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/profiles/**/fixtures/**/*.{ts,mjs}", diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml index ae653d10c5..c16a93c533 100644 --- a/packages/e2b/subprocess-e2b/README.i18n.yaml +++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md -README.md: 8d2cea1fff678d64b6a05f686be1838996ec837a -README.zh.md: 06d8c263c890802cde94f2ae50311ed8d4fc0b7a +README.md: ec81bc704ec11db85c43d27a15116c22962fb2f8 +README.zh.md: fe59299e7b737493161dbdb623248e8e76cf812a diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md index 8d2cea1fff..ec81bc704e 100644 --- a/packages/e2b/subprocess-e2b/README.md +++ b/packages/e2b/subprocess-e2b/README.md @@ -29,7 +29,7 @@ Use this package when the agent's shell commands and terminals should run inside ### When to choose it -Choose it when a composition already uses the E2B sandbox and you want commands and terminals to run there. Choose the local subprocess package for host execution. Tooling that needs a process id immediately — for example the ACP child backend — cannot use this package. +Choose it when a composition already uses the E2B sandbox and you want commands and terminals to run there. Choose the local subprocess package for host execution. ### Configuration @@ -71,7 +71,7 @@ This section explains the design decisions behind the provider and points at the ### Design philosophy -- **Deferred remote identity.** The synchronous seam never blocks on the network: public `pid` remains `undefined` because E2B exposes a wrapper process-group identity rather than the requested target PID. Private wrapper files publish that group identity, the direct exit code, and spill validity asynchronously. +- **Provider-private remote identity.** The synchronous seam never blocks on the network. Private wrapper files asynchronously publish a process-group identity for stdin, observation, termination, and quiescence checks, together with the direct exit code and spill validity; that identity is not the requested target PID. - **One teardown ladder.** Termination, rollback, and disposal share one process-group signal path — `SIGTERM`, then `SIGKILL` plus the SDK kill fallback — and treat proven quiescence as final. - **Environment is explicit.** Nothing from the host and nothing credential-shaped enters the sandbox implicitly; every ambient value is scrubbed and every `spec.env` entry is an explicit opt-in. @@ -91,9 +91,9 @@ This section explains the design decisions behind the provider and points at the The bootstrap resolves its own tools from the sandbox PATH, refuses any missing or non-executable path, execs through `env -i` and `setsid --wait`, publishes the process-group id and exit code to private files beneath `ctx.e2b.runtimeRoot/processes`, and redirects stdout and stderr through base64 encoders that emit a reserved completion frame; `tee` and `head -c` bound optional spill files. -### Process identity and publication +### Private process identity and publication -The synchronous seam returns a handle immediately while the command starts asynchronously. Public `pid` remains `undefined`; the wrapper publishes a private process-group ID for stdin, observation, termination, and quiescence checks, but that ID is not the requested target PID. A startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean. +The synchronous seam returns a handle immediately while the command starts asynchronously. The wrapper publishes a private process-group ID for stdin, observation, termination, and quiescence checks, but that ID is not the requested target PID. A startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean. ### Environment boundary @@ -142,7 +142,6 @@ No direct invalidation: the consumer seams own any request-prefix changes; this These limits define when the provider is a poor fit or needs special operational care. They are current package constraints, not a task backlog. - **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate the base64 transport even when this adapter exposes bounded raw-byte tails, so the subprocess seam's normal host-memory bound is not achieved and transport retention is larger than the source stream. -- **Target PID is unavailable** — the public `pid` is always `undefined`; the private wrapper process-group ID is retained only for containment and is not the requested target PID. Consumers that require a numeric target PID cannot use this provider unchanged. - **Private state lives for the sandbox lifetime** — process directories and valid spill files remain under `.dsh-e2b` until the owner deletes the sandbox; this POC supplies no in-sandbox sweep. - **Control state shares the sandbox user's UID** — E2B runs every command as the same default user, so `0700`/`0600` modes cannot isolate `.dsh-e2b` control files from concurrently running sandbox processes; real isolation needs an E2B per-command user or an out-of-band control channel. - **Numeric process identities are not reuse-fenced** — E2B exposes numeric PID/PGID input, signalling, and cleanup operations but no atomic identity-bound alternative; replacement is deferred until E2B adds an identity primitive or a failure demonstrates a narrower protocol. diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md index 06d8c263c8..fe59299e7b 100644 --- a/packages/e2b/subprocess-e2b/README.zh.md +++ b/packages/e2b/subprocess-e2b/README.zh.md @@ -29,7 +29,7 @@ kind: "package-reference" ### 何时选择 -当组合已经使用 E2B 沙箱且希望命令与终端在其中运行时，选择本包。宿主执行请选择本地子进程包。需要立即获得进程 ID 的工具——例如 ACP（Agent Client Protocol）子进程后端——无法使用本包。 +当组合已经使用 E2B 沙箱且希望命令与终端在其中运行时，选择本包。宿主执行请选择本地子进程包。 ### 配置 @@ -71,7 +71,7 @@ agent 可以在沙箱中打开交互式终端、发送输入、读取输出， ### 设计理念 -- **延后的远程身份。** 同步 seam 从不阻塞在网络请求上：公开 `pid` 始终为 `undefined`，因为 E2B 公开的是包装层进程组身份，而不是请求目标的 PID。包装层的私有文件会异步发布该进程组身份、直接退出码与 spill 有效性。 +- **提供方私有的远程身份。** 同步 seam 从不阻塞在网络请求上。包装层的私有文件会异步发布进程组身份，供 stdin、观察、终止与完全停稳检查使用，同时发布直接退出码与 spill 有效性；该身份不是请求目标的 PID。 - **单一终止阶梯。** 终止、回滚与资源释放共享同一条进程组信号路径——先 `SIGTERM`，再 `SIGKILL` 加 SDK kill 回退——并把已证明的完全停稳视为最终状态。 - **环境必须显式。** 宿主内容与形似凭据的内容都不会隐式进入沙箱；每个环境值都会被清理，每个 `spec.env` 条目都是显式选择。 @@ -91,9 +91,9 @@ agent 可以在沙箱中打开交互式终端、发送输入、读取输出， 引导脚本会从沙箱 PATH 解析自身所需的工具，拒绝任何缺失或不可执行的路径，通过 `env -i` 与 `setsid --wait` 执行 exec，把进程组 ID 与退出码发布到 `ctx.e2b.runtimeRoot/processes` 下的私有文件，并把 stdout 与 stderr 重定向到带保留完成帧的 base64 编码器；`tee` 与 `head -c` 约束可选 spill 文件的大小。 -### 进程身份与发布 +### 私有进程身份与发布 -同步 seam 会立即返回句柄，同时命令异步启动。公开 `pid` 始终为 `undefined`；包装层会发布私有进程组 ID，供 stdin、观察、终止与完全停稳检查使用，但该 ID 不是请求目标的 PID。启动信号会在分配前中止环境与私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。 +同步 seam 会立即返回句柄，同时命令异步启动。包装层会发布私有进程组 ID，供 stdin、观察、终止与完全停稳检查使用，但该 ID 不是请求目标的 PID。启动信号会在分配前中止环境与私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。 ### 环境边界 @@ -142,7 +142,6 @@ agent 可以在沙箱中打开交互式终端、发送输入、读取输出， 这些限制说明本提供方何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是任务积压。 - **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界原始字节尾部，E2B `CommandHandle.stdout` 与 `.stderr` 仍会累积 base64 传输内容，因此无法达到子进程 seam 通常提供的宿主内存边界，而且传输保留量大于源数据流。 -- **无法取得目标 PID**：公开 `pid` 始终为 `undefined`；私有包装层进程组 ID 只用于 containment，并不是请求目标的 PID。需要数值目标 PID 的消费方无法原样使用本提供方。 - **私有状态随沙箱生命周期存在**：进程目录与有效的 spill 文件会留在 `.dsh-e2b` 下，直到所有者删除沙箱；本 POC 不提供沙箱内清理。 - **控制状态与沙箱用户同 UID**：E2B 以同一默认用户运行每条命令，因此 `0700`/`0600` 权限无法把 `.dsh-e2b` 控制文件与并发运行的沙箱进程隔离开；真正的隔离需要 E2B 提供按命令用户或带外控制通道。 - **数值进程身份没有复用围栏**：E2B 公开基于数值 PID/PGID 的输入、信号发送与清理操作，却没有与身份原子绑定的替代方案；在 E2B 新增身份原语，或实际故障证明需要更窄的协议之前，替代方案继续延后。 diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts index 641e61e2ac..ce4e91c268 100644 --- a/packages/e2b/subprocess-e2b/src/process.ts +++ b/packages/e2b/subprocess-e2b/src/process.ts @@ -225,11 +225,6 @@ export class E2BSubprocessHandle implements SubprocessHandle { if (spec.signal?.aborted === true) this.terminate() } - /** E2B does not expose the requested target process identity. */ - get pid(): number | undefined { - return undefined - } - /** @inheritdoc */ terminate(): void { if (this.quiescenceProven || this.terminationAttempt !== undefined) return diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts index 8af74a8abf..61b3bc44a6 100644 --- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts +++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts @@ -402,12 +402,10 @@ describe('E2BSubprocessHandle', () => { KEEP: undefined, }, }), '/workspace/.dsh-e2b/processes/one') - expect(handle.pid).toBeUndefined() handle.stdin!.write('hello') handle.stdin!.end() fake.releaseStart() await flush() - expect(handle.pid).toBeUndefined() expect(fake.handle.sent.map(value => String(value))).toEqual(['hello']) expect(fake.handle.closes).toBe(1) const controlEnvs = fake.startOptions?.envs @@ -1166,7 +1164,6 @@ describe('E2BSubprocessHandle', () => { fake.backgroundError = new Error('start failed') const handle = testHandle(runtime(fake), spec(), '/runtime/fail') await expect(handle.done).rejects.toThrow('start failed') - expect(handle.pid).toBeUndefined() expect(fake.removed).toContain('/runtime/fail/environment') expect(fake.removed).toContain('/runtime/fail') await expect(handle.waitForExit()).resolves.toBe(true) @@ -1407,6 +1404,17 @@ describe('E2BSubprocessHandle', () => { await expect(absent.waitForExit()).resolves.toBe(true) }) + it('keeps polling while a running command has not published its process group yet', async () => { + const fake = new FakeSandbox() + fake.processGroupReads.push('', '4242\n') + const handle = testHandle(runtime(fake), spec(), '/runtime/delayed-group-publication', 1) + + await vi.waitFor(() => { expect(fake.processGroupReads).toEqual([]) }) + fake.finish() + await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) + await expect(handle.waitForExit()).resolves.toBe(true) + }) + it('preserves publication failure and reports cleanup that cannot be verified', async () => { const fake = new FakeSandbox() fake.processGroupId = 'not-a-pid\n' @@ -1449,16 +1457,6 @@ describe('E2BSubprocessHandle', () => { await expect(observed.waitForExit()).resolves.toBe(true) }) - it('keeps the public pid unavailable after delayed private process-group publication', async () => { - const fake = new FakeSandbox() - fake.processGroupReads.push('', '4242\n') - const handle = testHandle(runtime(fake), spec(), '/runtime/delayed-group') - await vi.waitFor(() => { expect(fake.processGroupReads).toHaveLength(0) }) - expect(handle.pid).toBeUndefined() - fake.finish() - await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) - }) - it('handles output backpressure and contains a stderr sink failure', async () => { const fake = new FakeSandbox() const handle = testHandle(runtime(fake), spec({ diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 2ae2c2422d..0c7fbe08d3 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -2123,7 +2123,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ { key: 'subprocess', summary: 'Abstract subprocess service.', - description: 'Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis\' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- Executable paths belong to one execution world shared with the mounted filesystem provider.\n- spawn returns a live handle synchronously. Its pid is provider-owned and may remain unavailable during asynchronous startup. `done` resolves with the spawned command\'s exit facts and may reject for spawn or provider failures.\n- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another\'s output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.\n- SubprocessHandle.terminate (and the spec\'s abort signal) starts the provider\'s documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its identity, signalling, and observability limits.\n- Disposal of the service terminates all still-running managed processes and awaits their exit.\n- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.', + description: 'Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis\' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- Executable paths belong to one execution world shared with the mounted filesystem provider.\n- spawn returns a live handle synchronously. Target identity remains provider-private; `done` resolves with the spawned command\'s exit facts and may reject for spawn or provider failures.\n- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another\'s output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.\n- SubprocessHandle.terminate (and the spec\'s abort signal) starts the provider\'s documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its signalling and observability limits.\n- Disposal of the service terminates all still-running managed processes and awaits their exit.\n- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.', methods: [ { signature: 'abstract resolveExecutable( command: string, env?: Readonly>, signal?: AbortSignal, ): Promise', @@ -5182,7 +5182,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SubprocessHandle', - declaration: 'export interface SubprocessHandle {\n readonly pid: number | undefined;\n readonly stdin: Writable | undefined;\n readonly stdout: Readable | undefined;\n readonly stderr: Readable | undefined;\n readonly collected: SubprocessCollectedOutputs;\n readonly done: Promise;\n terminate(): void;\n waitForExit(signal?: AbortSignal): Promise;\n}', + declaration: 'export interface SubprocessHandle {\n readonly stdin: Writable | undefined;\n readonly stdout: Readable | undefined;\n readonly stderr: Readable | undefined;\n readonly collected: SubprocessCollectedOutputs;\n readonly done: Promise;\n terminate(): void;\n waitForExit(signal?: AbortSignal): Promise;\n}', }, { name: 'SubprocessOutcome', diff --git a/packages/lsp/lsp-stdio/src/connection.ts b/packages/lsp/lsp-stdio/src/connection.ts index c3fa006f40..0c70e318bb 100644 --- a/packages/lsp/lsp-stdio/src/connection.ts +++ b/packages/lsp/lsp-stdio/src/connection.ts @@ -131,11 +131,6 @@ export class LspConnection { this.handle.stdout.on('data', (chunk: Buffer) => { this.onStdout(chunk) }) } - /** The child's published pid, or undefined while the provider has none available. */ - get pid(): number | undefined { - return this.handle.pid - } - /** The retained stderr tail, for diagnostics on a failed server. */ get stderrTail(): string { /* v8 ignore next -- the collect disposition always exposes a stderr reader; defensive. */ diff --git a/packages/lsp/lsp-stdio/tests/connection.spec.ts b/packages/lsp/lsp-stdio/tests/connection.spec.ts index 91e4bff909..37a9ef84e6 100644 --- a/packages/lsp/lsp-stdio/tests/connection.spec.ts +++ b/packages/lsp/lsp-stdio/tests/connection.spec.ts @@ -1,10 +1,8 @@ import { afterEach, describe, expect, it } from 'vitest' -import { PassThrough } from 'node:stream' import { fileURLToPath } from 'node:url' import { LspConnection } from '@deepseek-ai/dsh-lsp-stdio' import type { ConnectionWriter } from '@deepseek-ai/dsh-lsp-stdio/src/connection.ts' import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess' -import type { SubprocessHandle, SubprocessOutcome } from '@deepseek-ai/dsh-subprocess' import { spawnSubprocess } from '@deepseek-ai/dsh-subprocess-local/src/spawn.ts' const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url)) @@ -46,39 +44,10 @@ function connect( } describe('LspConnection', () => { - it('completes an initialize request/response round-trip and exposes a pid', async () => { + it('completes an initialize request/response round-trip', async () => { const conn = connect({}) const result = await conn.request('initialize', { capabilities: {} }) expect(result).toMatchObject({ capabilities: { hoverProvider: true } }) - expect(conn.pid).toBeGreaterThan(0) - }) - - it('projects an unavailable subprocess pid as undefined', async () => { - const direct = Promise.withResolvers() - const handle: SubprocessHandle = { - pid: undefined, - stdin: new PassThrough(), - stdout: new PassThrough(), - stderr: undefined, - collected: {}, - done: direct.promise, - terminate: () => {}, - waitForExit: async () => true, - } - const conn = new LspConnection({ - command: 'language-server', - args: [], - cwd: process.cwd(), - env: {}, - maxMessageBytes: 1_000, - maxStderrBytes: 1_000, - killGraceMs: 100, - configuration: null, - }, () => handle, () => Promise.resolve(null)) - - expect(conn.pid).toBeUndefined() - direct.resolve({ exitCode: 0, signal: null }) - await conn.closed }) it('forwards explicit DSH_* env entries to the child', async () => { diff --git a/packages/lsp/lsp-stdio/tests/instance.spec.ts b/packages/lsp/lsp-stdio/tests/instance.spec.ts index ffdd3c74cf..28634053b0 100644 --- a/packages/lsp/lsp-stdio/tests/instance.spec.ts +++ b/packages/lsp/lsp-stdio/tests/instance.spec.ts @@ -233,15 +233,13 @@ describe('LspInstance query and abort', () => { expect(instance.dead).toBe(true) }) - it('awaits process exit before rejecting a request write failure', async () => { + it('finishes teardown before rejecting a request write failure', async () => { const instance = makeInstance({}, { shutdownTimeoutMs: 100, killGraceMs: 100, }, failingWriter('textDocument/definition')) - // The pid is observed only to prove the owned subprocess reached quiescence before rejection. - const pid = (instance as unknown as { connection: { pid: number } }).connection.pid await expect(run(instance, 'goToDefinition')).rejects.toThrow(/fixture textDocument\/definition failure/) - expect(processAlive(pid)).toBe(false) + expect(instance.dead).toBe(true) }) it('rejects when the server lacks the operation capability', async () => { diff --git a/packages/shell/bash-sandbox/tests/sandbox.spec.ts b/packages/shell/bash-sandbox/tests/sandbox.spec.ts index 4fe1a4795f..54b3938f91 100644 --- a/packages/shell/bash-sandbox/tests/sandbox.spec.ts +++ b/packages/shell/bash-sandbox/tests/sandbox.spec.ts @@ -564,7 +564,6 @@ describe('background sandbox facts', () => { readFrom: () => ({ text: '', nextOffset: 0, lossy: false }), } vi.spyOn(ctx.subprocess, 'spawn').mockReturnValue({ - pid: undefined, stdin: undefined, stdout: undefined, stderr: undefined, diff --git a/packages/shell/pwsh-local/tests/executor.spec.ts b/packages/shell/pwsh-local/tests/executor.spec.ts index 51639dd14a..2adf6dddca 100644 --- a/packages/shell/pwsh-local/tests/executor.spec.ts +++ b/packages/shell/pwsh-local/tests/executor.spec.ts @@ -163,7 +163,6 @@ describe('spawn construction (pure, every platform)', () => { override spawn(spec: SubprocessSpawnSpec): SubprocessHandle { this.specs.push(spec) return { - pid: undefined, stdin: undefined, stdout: undefined, stderr: undefined, diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts index a362932b49..ad6335a93f 100644 --- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts +++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts @@ -84,7 +84,6 @@ async function waitForFile(file: string, timeoutMs = 5000): Promise { function rejectFinalExitWait(child: SubprocessHandle, message: string): SubprocessHandle { return { - pid: child.pid, stdin: child.stdin, stdout: child.stdout, stderr: child.stderr, @@ -108,7 +107,6 @@ function rejectFinalExitWaitAfterExit(child: SubprocessHandle, message: string): function tapBoundedExitWait(child: SubprocessHandle, onWait: () => void): SubprocessHandle { return { - pid: child.pid, stdin: child.stdin, stdout: child.stdout, stderr: child.stderr, @@ -130,7 +128,6 @@ function replaceProtocolStreams( if (child.stdin === undefined) throw new Error('expected piped child stdin') stdin.pipe(child.stdin) return { - pid: child.pid, stdin, stdout, stderr: child.stderr, @@ -168,7 +165,6 @@ function closeProtocolOnPrompt(child: SubprocessHandle, onClose: () => void = () function replaceProcessOutcome(child: SubprocessHandle, outcome: SubprocessOutcome): SubprocessHandle { return { - pid: child.pid, stdin: child.stdin, stdout: child.stdout, stderr: child.stderr, @@ -179,19 +175,6 @@ function replaceProcessOutcome(child: SubprocessHandle, outcome: SubprocessOutco } } -function hideProcessPid(child: SubprocessHandle): SubprocessHandle { - return { - pid: undefined, - stdin: child.stdin, - stdout: child.stdout, - stderr: child.stderr, - collected: child.collected, - done: child.done, - terminate: () => { child.terminate() }, - waitForExit: (signal?: AbortSignal) => child.waitForExit(signal), - } -} - describe('acpStopReason', () => { it('maps each ACP stop reason to the harness vocabulary', () => { expect(acpStopReason('end_turn')).toBe('completed') @@ -323,7 +306,6 @@ describe('disposeAcpChild (the backend-owned teardown ladder over seam verbs)', .mockResolvedValueOnce(true) const terminate = vi.fn() const child: SubprocessHandle = { - pid: undefined, stdin: new PassThrough(), stdout: undefined, stderr: undefined, @@ -345,7 +327,6 @@ describe('disposeAcpChild (the backend-owned teardown ladder over seam verbs)', .mockRejectedValueOnce(initialFailure) .mockRejectedValueOnce(finalFailure) const child: SubprocessHandle = { - pid: undefined, stdin: new PassThrough(), stdout: undefined, stderr: undefined, @@ -372,7 +353,6 @@ describe('disposeAcpChild (the backend-owned teardown ladder over seam verbs)', const stdin = new PassThrough() const stdout = new PassThrough() const child: SubprocessHandle = { - pid: undefined, stdin, stdout, stderr: undefined, @@ -747,7 +727,7 @@ describe('dsh-subagent-acp', () => { env: { MOCK_CRASH_ON_INITIALIZE: '1' }, disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS, disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS, - spawn: spec => hideProcessPid(spawnSubprocess(spec)), + spawn: spec => spawnSubprocess(spec), }).catch((cause: unknown) => cause) expect(error).toBeInstanceOf(Error) expect((error as Error).message).toBe( @@ -764,7 +744,7 @@ describe('dsh-subagent-acp', () => { env: {}, disposeEofGraceMs: 50, disposeGraceMs: 50, - spawn: spec => closeProtocolImmediately(hideProcessPid(spawnSubprocess(spec))), + spawn: spec => closeProtocolImmediately(spawnSubprocess(spec)), }).catch((cause: unknown) => cause) expect(error).toBeInstanceOf(Error) expect((error as Error).message).toBe( @@ -785,7 +765,6 @@ describe('dsh-subagent-acp', () => { disposeEofGraceMs: 50, disposeGraceMs: 50, spawn: () => ({ - pid: undefined, stdin, stdout, stderr: undefined, @@ -1196,7 +1175,7 @@ describe('dsh-subagent-acp', () => { env: { MOCK_TEXT: 'partial answer', MOCK_CRASH_AFTER_CHUNK: '1' }, disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS, disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS, - spawn: spec => hideProcessPid(spawnSubprocess(spec)), + spawn: spec => spawnSubprocess(spec), }) const result = await run.result expect(result).toEqual({ @@ -1224,7 +1203,6 @@ describe('dsh-subagent-acp', () => { const child = spawnSubprocess(spec) realChild = child return closeProtocolOnPrompt({ - pid: undefined, stdin: child.stdin, stdout: child.stdout, stderr: child.stderr, diff --git a/packages/subagent/subagent-claude-code/tests/subagent-claude-code.spec.ts b/packages/subagent/subagent-claude-code/tests/subagent-claude-code.spec.ts index 4253308fc0..7e4acd18b0 100644 --- a/packages/subagent/subagent-claude-code/tests/subagent-claude-code.spec.ts +++ b/packages/subagent/subagent-claude-code/tests/subagent-claude-code.spec.ts @@ -100,7 +100,6 @@ function errorCause(value: unknown): Error | undefined { } interface FakeChildOptions { - readonly pid?: number | undefined readonly exitOnTerminate?: boolean readonly waitForExitError?: Error readonly doneError?: Error @@ -169,7 +168,6 @@ function fakeChild(options: FakeChildOptions = {}): FakeChild { }) }) const handle: SubprocessHandle = { - pid: Object.hasOwn(options, 'pid') ? options.pid : 1234, stdin, stdout, stderr: undefined, @@ -829,7 +827,7 @@ describe('official spawn projection', () => { }) it('emits spawn errors', async () => { - const child = fakeChild({ pid: undefined }) + const child = fakeChild() const process = new ManagedClaudeCodeProcess(child.handle) const errorListener = vi.fn() const removed = vi.fn() @@ -1480,7 +1478,6 @@ describe('run publication, cancellation, and settlement', () => { { code: 'EACCES', path: '/sdk/claude' }, ) const failedSpawn = fakeChild({ - pid: undefined, doneError: spawnError, }) const failed = fakeRun([], undefined, failedSpawn) @@ -1495,7 +1492,6 @@ describe('run publication, cancellation, and settlement', () => { const failedSpawnAbort = new AbortController() const cancelledFailedSpawn = fakeChild({ - pid: undefined, doneError: spawnError, }) const cancelledFailedClose = vi.fn() @@ -1515,7 +1511,6 @@ describe('run publication, cancellation, and settlement', () => { throw cancelledFailedSpawnCloseError }) const cancelledFailedSpawnWithCloseFailure = fakeChild({ - pid: undefined, doneError: spawnError, }) const failedSpawnAbortWithCloseFailure = new AbortController() @@ -1548,7 +1543,6 @@ describe('run publication, cancellation, and settlement', () => { const failedSpawnCloseError = new Error('query close failed') const failedSpawnClose = vi.fn(() => { throw failedSpawnCloseError }) const failedSpawnWithCloseFailure = fakeChild({ - pid: undefined, doneError: spawnError, }) queryMock.mockImplementationOnce(({ options }) => { @@ -1602,7 +1596,7 @@ describe('run publication, cancellation, and settlement', () => { new Error('spawn /sdk/claude ENOENT'), { code: 'ENOENT', path: '/sdk/claude' }, ) - const child = fakeChild({ pid: undefined }) + const child = fakeChild() const close = vi.fn() queryMock.mockImplementationOnce(({ options }) => { options.spawnClaudeCodeProcess!(sdkSpawnOptions()) diff --git a/packages/subagent/subagent-codex/tests/subagent-codex.spec.ts b/packages/subagent/subagent-codex/tests/subagent-codex.spec.ts index 57422446ea..c43fd07ed1 100644 --- a/packages/subagent/subagent-codex/tests/subagent-codex.spec.ts +++ b/packages/subagent/subagent-codex/tests/subagent-codex.spec.ts @@ -140,7 +140,6 @@ class ProtocolPeer { } interface FakeChildOptions { - readonly pid?: number | undefined readonly exitOnTerminate?: boolean readonly doneError?: Error readonly waitForExitError?: Error @@ -212,7 +211,6 @@ function fakeChild(options: FakeChildOptions = {}): FakeChild { }) }) const handle: SubprocessHandle = { - pid: Object.hasOwn(options, 'pid') ? options.pid : 1234, stdin: toChild, stdout: fromChild, stderr, @@ -1891,7 +1889,6 @@ describe('run lifecycle and quiescence', () => { await expect(spawnFailure).rejects.not.toThrow('SECRET_TOKEN') const asyncSpawnFailureChild = fakeChild({ - pid: undefined, doneError: new Error('SECRET_TOKEN async spawn failure'), }) const asyncSpawnFailure = startCodexRun( @@ -2277,9 +2274,8 @@ describe('disposeCodexChild', () => { .resolves.toBeUndefined() }) - it('still runs idempotent cleanup when the target pid was never published', async () => { + it('still runs idempotent cleanup when target startup rejects', async () => { const child = fakeChild({ - pid: undefined, doneError: new Error('spawn failed'), }) const wire = defaultWire(child) diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml index 33acf98399..6c586d7e32 100644 --- a/packages/subprocess/subprocess-local/README.i18n.yaml +++ b/packages/subprocess/subprocess-local/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: 5e127164840f9d7f222031c16aba8028c93a4d98 -README.zh.md: 768c64b99b819cd610f3c54f3957f6bb86c04c28 +README.md: eb38e2f45bad8e4b985177c656e5cb2762a86654 +README.zh.md: e7fb4d083bc52c27e39750486d98a41b404121dc diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md index 5e12716484..eb38e2f45b 100644 --- a/packages/subprocess/subprocess-local/README.md +++ b/packages/subprocess/subprocess-local/README.md @@ -50,7 +50,7 @@ Collect mode keeps the last `maxBytes` of a stream in memory — errors and fina ### 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, lets Windows Job ownership close with the runner's parent connection, and uses the existing PGID, `taskkill`, or captured-identity operation for fallbacks. It creates no promises or timers and does not claim quiescence. Unhandled `SIGTERM`/`SIGINT`/`SIGHUP`, `SIGKILL`, fatal OOM, native crashes, and power loss need an external supervisor. +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. Unhandled `SIGTERM`/`SIGINT`/`SIGHUP`, `SIGKILL`, fatal OOM, native crashes, and power loss need an external supervisor. ### What can go wrong @@ -80,9 +80,8 @@ Each spawn selects one owner for both signalling and quiescence. Supported Linux | [`src/linux-scope.ts`](src/linux-scope.ts) | Linux user-systemd capability checks, scope launch, signalling, and quiescence | | [`src/windows-job.ts`](src/windows-job.ts) | Windows Job capability checks and helper launch | | [`src/runner-launch.ts`](src/runner-launch.ts) | Source, built, and packaged private-runner selection | -| [`src/spawn-runner.ts`](src/spawn-runner.ts) | Linux ordinary target runner and Windows Job runner | -| [`src/runner-protocol.ts`](src/runner-protocol.ts) | Private per-spawn launch and result facts | -| [`src/windows-stdio.ts`](src/windows-stdio.ts) | Parent-side named-pipe endpoints for Windows ordinary stdio | +| [`src/spawn-runner.ts`](src/spawn-runner.ts) | Linux one-shot exec bootstrap and Windows Job runner | +| [`src/runner-protocol.ts`](src/runner-protocol.ts) | Strict Linux launch/startup files and Windows IPC messages | | [`src/terminal.ts`](src/terminal.ts) | `node-pty` handle: Linux scope attachment, foreground inspection, and fallback cleanup | | [`src/process-inspector.ts`](src/process-inspector.ts) | POSIX process-tree and session inspection | | [`src/windows-inspector.ts`](src/windows-inspector.ts) | Windows Toolhelp32 process-table inspection via koffi | @@ -90,7 +89,7 @@ Each spawn selects one owner for both signalling and quiescence. Supported Linux ### Main flow -A spawn builds the scrubbed child environment, selects containment before the user command can run, and returns a handle without waiting for native target publication. Linux and Windows ordinary runners publish the real target PID, Node-shaped startup failure, and direct outcome; `pid` remains `undefined` until that target fact exists. `done` settles the direct command after a bounded non-inherited output drain, while `waitForExit()` separately waits for the selected scope, Job, process group, or observed session to become empty. Linux terminal launch passes scoped argv directly to `node-pty` and adds no runner. +A spawn synchronously validates the final argv, cwd, and environment, selects containment before the user command can run, and returns a handle while target identity remains private. Linux ordinary and terminal launches use a private one-shot request whose scoped bootstrap restores the target cwd and environment before replacing itself with the target. Windows ordinary launches use one IPC channel for the start request, termination, and strict direct result; the runner creates the target suspended, assigns it to the Job, and only then resumes it. `done` settles the direct command after its stdio barrier, while `waitForExit()` separately waits for the selected scope, Job, process group, or observed session to become empty. ### Safety invariants @@ -130,7 +129,7 @@ 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. - **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 probe and runner costs** — Linux rechecks the live user manager before every eligible ordinary or terminal spawn. Successful stable systemd-scope and ordinary-runner probes are cached for the provider lifetime, failed probes are retried, and terminal selection never probes the ordinary runner. Windows likewise caches only a successful Job-runner probe. Each synchronous probe command has a 5-second bound and completes before the user command can run. A native ordinary handle returns before target publication: `pid` starts as `undefined` and updates from asynchronously polled runner events, while `done` carries target startup failure or direct outcome. There is no target-publication timeout; a runner that remains alive without a terminal event leaves `pid` undefined and `done` pending until it exits or the range is terminated. Each supported native ordinary command keeps one runner process alive until the OS-owned range is empty, and Windows additionally creates private per-spawn named-pipe endpoints. Linux terminal launch passes the scoped argv directly to `node-pty` and adds no runner. Runner events are polled asynchronously every 100 ms and Linux scope state every 200 ms. +- **Native selection has bounded per-spawn costs** — Linux rechecks the bootstrap entry, live user manager, and literal-argv scope support before every eligible ordinary or terminal spawn; Windows rechecks the runner entry, bindings, and current Job support before every ordinary spawn. Only the fallback warning is retained across spawns. 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 and polls unresolved scope state; 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 conhost turns into a console-wide CTRL_C event; 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. - **Fallback terminal ownership remains observational** — on macOS or Linux without usable user-systemd, a child that reparents before any foreground-inspection snapshot or leaves the owned terminal session can escape the process-table scan. The local provider does not add a continuous process-table monitor; supported Linux native mode instead retains these descendants through scope membership. diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md index 768c64b99b..e7fb4d083b 100644 --- a/packages/subprocess/subprocess-local/README.zh.md +++ b/packages/subprocess/subprocess-local/README.zh.md @@ -50,7 +50,7 @@ kind: "package-reference" ### 关闭行为 -正常 dispose 会终止每个仍在运行的受管范围与终端会话并等待其完全停稳。在 JavaScript 可观察的宿主退出期间——直接 `process.exit()`、默认未捕获异常、默认未处理 rejection——同步最终清理会请求 Linux scope 终止其成员，让 Windows Job 所有权随 runner 的父连接关闭，并为 fallback 使用既有 PGID、`taskkill` 或已捕获身份操作。它不创建 Promise 或定时器，也不声称已经完全停稳。未处理的 `SIGTERM`/`SIGINT`/`SIGHUP`、`SIGKILL`、fatal OOM、native crash 与断电需要外部 supervisor。 +正常 dispose 会终止每个仍在运行的受管范围与终端会话并等待其完全停稳。在 JavaScript 可观察的宿主退出期间——直接 `process.exit()`、默认未捕获异常、默认未处理 rejection——同步最终清理会请求 Linux scope 终止其成员，同步终止每个 Windows runner 以关闭其唯一 Job handle，并为 fallback 使用既有 PGID、`taskkill` 或已捕获身份操作。它不创建 Promise 或定时器，也不声称已经完全停稳。未处理的 `SIGTERM`/`SIGINT`/`SIGHUP`、`SIGKILL`、fatal OOM、native crash 与断电需要外部 supervisor。 ### 可能出错的地方 @@ -80,9 +80,8 @@ kind: "package-reference" | [`src/linux-scope.ts`](src/linux-scope.ts) | Linux user-systemd 能力检查、scope 启动、信号发送与完全停稳 | | [`src/windows-job.ts`](src/windows-job.ts) | Windows Job 能力检查与 helper 启动 | | [`src/runner-launch.ts`](src/runner-launch.ts) | source、built 与 packaged 私有 runner 选择 | -| [`src/spawn-runner.ts`](src/spawn-runner.ts) | Linux 普通命令 target runner 与 Windows Job runner | -| [`src/runner-protocol.ts`](src/runner-protocol.ts) | 每次 spawn 的私有启动与结果事实 | -| [`src/windows-stdio.ts`](src/windows-stdio.ts) | Windows 普通命令 stdio 的 parent 侧 named-pipe endpoint | +| [`src/spawn-runner.ts`](src/spawn-runner.ts) | Linux 一次性 exec bootstrap 与 Windows Job runner | +| [`src/runner-protocol.ts`](src/runner-protocol.ts) | 严格的 Linux 启动／错误文件与 Windows IPC 消息 | | [`src/terminal.ts`](src/terminal.ts) | `node-pty` 终端句柄：Linux scope 绑定、前台检查与 fallback 清理 | | [`src/process-inspector.ts`](src/process-inspector.ts) | POSIX 进程树与会话检查 | | [`src/windows-inspector.ts`](src/windows-inspector.ts) | 经 koffi 的 Windows Toolhelp32 进程表检查 | @@ -90,7 +89,7 @@ kind: "package-reference" ### 主流程 -一次 spawn 会构建清理后的子进程环境，在用户命令可能运行前选择 containment，并在无需等待 native target 发布的情况下返回句柄。Linux 与 Windows 普通 runner 会发布真实 target PID、Node 风格启动失败与 direct outcome；在 target 事实出现前，`pid` 保持 `undefined`。`done` 会在有界的非继承输出排空后结算直接命令，`waitForExit()` 则分别等待所选 scope、Job、进程组或已观察 session 变空。Linux 终端启动把 scoped argv 直接交给 `node-pty`，不增加 runner。 +一次 spawn 会同步校验最终 argv、cwd 与环境，在用户命令可能运行前选择 containment，并在目标身份保持私有的情况下返回句柄。Linux 普通命令与终端启动使用私有的一次性请求；scope 内的 bootstrap 会恢复目标 cwd 与环境，再用目标程序替换自身。Windows 普通命令使用同一条 IPC 通道传递启动请求、终止命令与严格的直接结果；runner 以 suspended 状态创建目标，将其加入 Job 后才恢复运行。`done` 会在直接命令及其 stdio 屏障结算后完成，`waitForExit()` 则分别等待所选 scope、Job、进程组或已观察 session 变空。 ### 安全不变式 @@ -130,7 +129,7 @@ spill 文件以 `0600` 权限、`O_EXCL` 与随机名称在 `0700` 每进程目 这些限制说明本提供方何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是通用平台对比或任务积压。 - **native ownership 有明确宿主要求**——Linux 需要可读的 user manager 与 `systemd-run --expand-environment=no`；旧版 systemd 使用带告警的 PGID fallback。macOS 因没有受支持的公开 persistent owner，始终使用该 fallback。 -- **native 选择具有有界的探测与 runner 成本**——Linux 会在每次符合条件的普通命令或终端 spawn 前重新检查存活的 user manager。稳定的 systemd scope 与普通 runner 探测只在成功后按提供方生命周期缓存，失败探测会重试，而且终端选择绝不会探测普通 runner。Windows 同样只缓存成功的 Job runner 探测。每条同步探测命令的上限为 5 秒，并在用户命令可能运行前完成。native 普通句柄会在 target 发布前返回：`pid` 起初为 `undefined`，随后由异步轮询的 runner 事件更新；`done` 则承载 target 启动失败或 direct outcome。target 发布没有单独的超时；runner 如果保持存活却始终没有终态事件，`pid` 会保持为 `undefined`，`done` 也会保持待定，直到 runner 退出或该范围被终止。每条受支持的 native 普通命令都会保留一个 runner 进程，直到 OS 所有的范围为空；Windows 还会创建私有的每次 spawn named-pipe endpoint。Linux 终端启动会把 scoped argv 直接交给 `node-pty`，不增加 runner。runner 事件每 100 ms、Linux scope 状态每 200 ms 异步轮询。 +- **native 选择具有有界的每次 spawn 成本**——Linux 会在每次符合条件的普通命令或终端 spawn 前重新检查 bootstrap 入口、存活的 user manager 与 literal-argv scope 支持；Windows 会在每次普通 spawn 前重新检查 runner 入口、bindings 与当前 Job 支持。跨 spawn 只保留 fallback 告警。所有探测都会在用户命令可能运行前完成，子进程探测的超时为 5 秒。每次 Linux 启动都会创建私有请求目录，并在 scope 状态尚未确定时轮询；Windows 普通命令会保留一个 runner 与一条 IPC 通道，直到 Job 报告活动进程数为零。目标会直接继承标准句柄，不使用 named-pipe stdio 或结果文件。 - **Windows Job inheritance 有明确排除项**——普通后代默认继承 Job，但 breakaway 进程不在保证范围。目标只在 Job 分配后启动；runner 若在 create-to-assignment 极窄区间遭外力终止，可能留下 suspended target。 - **Windows 终端信号是控制台级的**——SIGINT 以 `\x03` Ctrl-C 输入写入投递，由 conhost 转为控制台级 CTRL_C 事件；SIGTSTP 与 SIGHUP 被拒绝（不可用）；不带 `/F` 的 `taskkill` 无法终止控制台进程，因此拆卸的 TERM 档是 `/F` 升级前的宽限等待。Windows 就绪没有精确的 stdin-wait 档：prompt-marker 快路径把 shell pid 作为伪前台进程组比较，其余由静默与计时档覆盖。 - **fallback 终端 ownership 仍依赖观察**——在 macOS 或缺少可用 user-systemd 的 Linux 上，子进程如果在任何前台检查快照之前重新设定父进程，或离开自有终端 session，就可能逃出进程表扫描。本地提供方不会新增持续进程表监视器；受支持的 Linux native 模式改由 scope membership 持有这些后代。 diff --git a/packages/subprocess/subprocess-local/package.json b/packages/subprocess/subprocess-local/package.json index d207c90f50..d5d181abbb 100644 --- a/packages/subprocess/subprocess-local/package.json +++ b/packages/subprocess/subprocess-local/package.json @@ -22,14 +22,18 @@ "types": "./lib/types/invariant.d.ts", "default": "./lib/invariant.js" }, + "./runner": { + "types": "./lib/types/bin.d.ts", + "default": "./lib/runner.js" + }, "./src/*": "./src/*", "./package.json": "./package.json" }, "files": [ "lib/index.js", "lib/invariant.js", - "lib/spawn-runner.js", - "lib/runner-protocol-*.js", + "lib/runner.js", + "lib/runner-*.js", "scripts/ensure-spawn-helper.mjs", "lib/types/**/*.d.ts" ], diff --git a/packages/subprocess/subprocess-local/src/bin.ts b/packages/subprocess/subprocess-local/src/bin.ts index 0b7e50243b..02393125f8 100644 --- a/packages/subprocess/subprocess-local/src/bin.ts +++ b/packages/subprocess/subprocess-local/src/bin.ts @@ -1,11 +1,36 @@ -/** Thin process entry for the ordinary subprocess native runner. */ +/** Thin executable/importable entry for the provider-private runner core. */ +import { resolve } from 'node:path' +import { pathToFileURL } from 'node:url' +import { consumeRunnerSelection } from './runner-launch.ts' import { reportSpawnRunnerFailure, runSpawnRunner } from './spawn-runner.ts' -const argv = process.argv.slice(2) -try { - await runSpawnRunner(argv) -} catch (error: unknown) { - reportSpawnRunnerFailure(argv, error) - process.exitCode = 127 +/** + * Run a selector already removed by a packaging bootstrap. + * @param selection - private runner selector or Linux launch-request locator. + * @param argv - private runner arguments beginning with the target delimiter. + */ +export async function runSelectedSubprocessRunner( + selection: string, + argv: readonly string[] = process.argv.slice(2), +): Promise { + try { + await runSpawnRunner(selection, argv) + } catch (error) { + await reportSpawnRunnerFailure(selection, error) + } +} + +function isExecutedEntry(): boolean { + const entry = process.argv[1] + return entry !== undefined && pathToFileURL(resolve(entry)).href === import.meta.url +} + +if (isExecutedEntry()) { + const selection = consumeRunnerSelection() + if (selection === undefined) { + process.exitCode = 127 + } else { + await runSelectedSubprocessRunner(selection) + } } diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts index 5d3116a436..39f7f561b7 100644 --- a/packages/subprocess/subprocess-local/src/index.ts +++ b/packages/subprocess/subprocess-local/src/index.ts @@ -32,11 +32,10 @@ import type { LocalSubprocessHandle, SpawnInternals } from './spawn.ts' import { launchLinuxScope, prepareLinuxTerminalScope, - probeLinuxRunner, - probeLinuxScope, - probeLinuxUserManager, + probeLinuxNative, } from './linux-scope.ts' import { launchWindowsJob, probeWindowsJob } from './windows-job.ts' +import { targetEnvironment, validateTerminalTarget } from './runner-launch.ts' import { createProcessInspector } from './process-inspector.ts' import type { ProcessInspector } from './process-inspector.ts' import { LocalTerminalHandle } from './terminal.ts' @@ -57,12 +56,6 @@ export class LocalSubprocessRuntime extends SubprocessRuntime { internals: SpawnInternals = {} /** Provider-lifetime latch suppressing repeated weaker-containment warnings. */ private fallbackWarningIssued = false - /** Stable Linux scope features, cached only after a successful probe. */ - private linuxScopeCapabilityConfirmed = false - /** Stable ordinary-runner availability, cached only after a successful probe. */ - private linuxRunnerCapabilityConfirmed = false - /** Stable Windows Job support, cached only after a successful probe. */ - private windowsJobCapabilityConfirmed = false /** Test hook for platform process inspection; production resolves lazily on terminal spawn. */ terminalInspector: ProcessInspector | undefined @@ -167,13 +160,16 @@ export class LocalSubprocessRuntime extends SubprocessRuntime { spawn(spec: SubprocessSpawnSpec): SubprocessHandle { validateSubprocessSpec(spec) + const env = targetEnvironment(spec) const containmentMode = this.selectContainmentMode('ordinary') let handle: LocalSubprocessHandle if (containmentMode === 'fallback') { handle = spawnSubprocess(spec, this.internals) } else { const binding = prepareManagedProcessBinding(this.internals) - const launch = containmentMode === 'linux-scope' ? launchLinuxScope(spec) : launchWindowsJob(spec) + const launch = containmentMode === 'linux-scope' + ? launchLinuxScope(spec, env) + : launchWindowsJob(spec, env) handle = bindManagedProcess(spec, launch, binding) } this.live.add(handle) @@ -193,24 +189,13 @@ export class LocalSubprocessRuntime extends SubprocessRuntime { const platform = this.internals.platform ?? process.platform let fallbackReason: string | undefined if (platform === 'linux') { - const managerAvailable = probeLinuxUserManager() - if (managerAvailable && !this.linuxScopeCapabilityConfirmed) { - this.linuxScopeCapabilityConfirmed = probeLinuxScope() - } - if (managerAvailable && this.linuxScopeCapabilityConfirmed) { - if (kind === 'terminal') return 'linux-scope' - if (!this.linuxRunnerCapabilityConfirmed) { - this.linuxRunnerCapabilityConfirmed = probeLinuxRunner() - } - if (this.linuxRunnerCapabilityConfirmed) return 'linux-scope' - fallbackReason = 'the private Linux subprocess runner is unavailable' - } + const available = this.internals.linuxNativeAvailable?.() ?? probeLinuxNative() + if (available) return 'linux-scope' + fallbackReason = 'the current user-systemd scope or private bootstrap is unavailable' } if (kind === 'ordinary' && platform === 'win32') { - if (!this.windowsJobCapabilityConfirmed) { - this.windowsJobCapabilityConfirmed = probeWindowsJob() - } - if (this.windowsJobCapabilityConfirmed) return 'windows-job' + const available = this.internals.windowsNativeAvailable?.() ?? probeWindowsJob() + if (available) return 'windows-job' } this.warnFallback(platform, kind, fallbackReason) return 'fallback' @@ -245,32 +230,50 @@ export class LocalSubprocessRuntime extends SubprocessRuntime { throw new Error('subprocess-local: terminal argv must contain a program') } spec.signal?.throwIfAborted() + const env = validateTerminalTarget(spec) const options: IPtyForkOptions = { name: 'dumb', rows: spec.rows, cols: spec.cols, cwd: spec.cwd, - env: childEnv(spec.env), + env, } const inspector = this.terminalInspector ?? createProcessInspector() const containmentMode = this.selectContainmentMode('terminal') const scope = containmentMode === 'linux-scope' - ? prepareLinuxTerminalScope(spec.argv) + ? prepareLinuxTerminalScope(spec, env) : undefined - const terminal = nodePty.spawn( - scope?.command ?? file, - scope?.args ?? [...spec.argv.slice(1)], - options, - ) + if (scope !== undefined) { + options.cwd = scope.cwd + options.env = scope.env + } + let terminal: nodePty.IPty + try { + terminal = nodePty.spawn( + scope?.command ?? file, + scope?.args ?? [...spec.argv.slice(1)], + options, + ) + } catch (error) { + scope?.cleanup() + throw error + } // oxlint-disable-next-line eslint/prefer-const -- The owner can query readiness before the handle is published. let handle: LocalTerminalHandle | undefined - const owner = scope?.bindOwner(() => handle?.running ?? true) + const owner = scope?.bindOwner({ + running: () => handle?.running ?? true, + signal: (signal) => { + try { terminal.kill(signal) } catch { /* Direct process already exited. */ } + }, + }) handle = new LocalTerminalHandle( terminal, inspector, spec.graceMs, this.internals.platform ?? process.platform, owner, + scope?.resolveOutcome, + scope?.cleanup, ) this.terminals.add(handle) const release = async (): Promise => { diff --git a/packages/subprocess/subprocess-local/src/linux-scope.ts b/packages/subprocess/subprocess-local/src/linux-scope.ts index 9683052223..b53a38cad9 100644 --- a/packages/subprocess/subprocess-local/src/linux-scope.ts +++ b/packages/subprocess/subprocess-local/src/linux-scope.ts @@ -1,21 +1,30 @@ /** Linux user-systemd scope launch and managed-range ownership. */ -import { randomBytes } from 'node:crypto' import { execFile, spawn, spawnSync } from 'node:child_process' +import { randomBytes } from 'node:crypto' +import { existsSync } from 'node:fs' import { setTimeout as sleepMs } from 'node:timers/promises' -import type { SubprocessOutcome, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' +import type { + SubprocessOutcome, + SubprocessSpawnSpec, + SubprocessTerminalSpawnSpec, +} from '@deepseek-ai/dsh-subprocess' import type { BoundProcessOwner, ManagedProcessLaunch } from './managed-owner.ts' -import { DirectResultUnavailableError, observeChildLifecycle } from './managed-owner.ts' -import { childEnv } from './spawn.ts' import { - cleanupAfterRunner, - type RunnerInvocation, - runnerDirectResult, - runnerFiles, + cleanupLinuxLaunchFiles, + createLinuxLaunchFiles, + deserializeRunnerError, + readLinuxStartupError, +} from './runner-protocol.ts' +import type { LinuxLaunchFiles } from './runner-protocol.ts' +import { + runnerEnvironment, + runnerInvocationAvailable, runnerStdio, spawnRunnerInvocation, } from './runner-launch.ts' -import { cleanupRunnerFiles } from './runner-protocol.ts' +import type { RunnerInvocation } from './runner-launch.ts' +import { childEnv } from './spawn.ts' /** Test seams for systemd command execution. */ export interface LinuxScopeInternals { @@ -25,6 +34,9 @@ export interface LinuxScopeInternals { systemdRun?: string systemctl?: string runnerInvocation?: RunnerInvocation + resolveRunnerInvocation?: () => RunnerInvocation + runnerAvailable?: (invocation: RunnerInvocation) => boolean + execveAvailable?: boolean } interface SystemctlResult { @@ -35,22 +47,22 @@ interface SystemctlResult { } const SYSTEMCTL_TIMEOUT_MS = 5_000 -const SCOPE_POLL_INTERVAL_MS = 200 +const SCOPE_POLL_INTERVAL_MS = 50 const MISSING_UNIT = /\bunit\b[^\r\n]*(?:could not be found|not found|not loaded)/iu function systemctlEnv(): NodeJS.ProcessEnv { - return childEnv({ LC_ALL: 'C' }) + return childEnv({ LC_ALL: 'C', SYSTEMD_LOG_TARGET: 'null' }) } function querySystemctl(command: string, args: readonly string[]): Promise { - return new Promise((resolve) => { + return new Promise((resolveResult) => { execFile(command, [...args], { encoding: 'utf8', env: systemctlEnv(), timeout: SYSTEMCTL_TIMEOUT_MS, }, (error, stdout, stderr) => { const code = error === null ? 0 : (error as Error & { code?: string | number }).code - resolve({ + resolveResult({ status: typeof code === 'number' ? code : null, stdout, stderr, @@ -61,54 +73,47 @@ function querySystemctl(command: string, args: readonly string[]): Promise | undefined private killFailure: Error | undefined constructor( private readonly unit: string, + private readonly files: LinuxLaunchFiles, + private readonly direct: DirectRange, private readonly systemctl: string, private readonly runSync: typeof spawnSync, private readonly query: (command: string, args: readonly string[]) => Promise, - private readonly launcherRunning: () => boolean, - private readonly onForceKillAttempt: () => void, ) {} signal(signal: 'SIGTERM' | 'SIGKILL'): void { if (this.stopped) return + this.direct.signal(signal) const result = this.runSync(this.systemctl, [ '--user', 'kill', @@ -153,20 +172,38 @@ class SystemdScopeOwner implements BoundProcessOwner { `--signal=${signal}`, this.unit, ], { encoding: 'utf8', env: systemctlEnv(), timeout: SYSTEMCTL_TIMEOUT_MS }) - if (signal === 'SIGKILL' && result.error === undefined) this.onForceKillAttempt() if (result.error === undefined && result.status === 0) { if (signal === 'SIGKILL') this.killFailure = undefined return } if (signal === 'SIGKILL') { const output = `${result.stdout}\n${result.stderr}` - this.killFailure = result.error ?? new Error( - `systemctl could not signal ${this.unit}: ${output.trim() || `exit ${String(result.status)}`}`, - ) + if (!MISSING_UNIT.test(output)) { + this.killFailure = result.error ?? new Error( + `systemctl could not signal ${this.unit}: ${output.trim() || `exit ${String(result.status)}`}`, + ) + } } } - private async active(): Promise { + terminateForHostExit(): void { + if (this.stopped) return + try { this.direct.signal('SIGKILL') } catch { /* Continue with the native owner. */ } + try { + this.runSync(this.systemctl, [ + '--user', + 'kill', + '--kill-whom=all', + '--signal=SIGKILL', + this.unit, + ], { env: systemctlEnv(), stdio: 'ignore', timeout: SYSTEMCTL_TIMEOUT_MS }) + } catch { + // Host exit cannot report one range; the runtime continues with the rest. + } + } + + private async rangeActive(): Promise { + if (!existsSync(this.files.requestPath)) this.established = true const result = await this.query(this.systemctl, [ '--user', 'show', @@ -175,19 +212,23 @@ class SystemdScopeOwner implements BoundProcessOwner { '--value', ]) const output = `${result.stdout}\n${result.stderr}` - if (result.status !== 0) { - if (MISSING_UNIT.test(output)) { - if (!this.launcherRunning()) return false - } else { - if (result.error !== undefined) throw result.error - throw new Error(`systemctl could not read ${this.unit}: ${output.trim() || `exit ${String(result.status)}`}`) - } - } else { + if (result.status === 0) { + this.established = true const state = result.stdout.trim() if (state === 'inactive' || state === 'failed') return false if (state !== 'active' && state !== 'activating' && state !== 'deactivating') { throw new Error(`systemctl returned unknown ActiveState for ${this.unit}: ${JSON.stringify(state)}`) } + if (this.killFailure !== undefined) throw this.killFailure + return true + } + if (!MISSING_UNIT.test(output)) { + if (result.error !== undefined) throw result.error + throw new Error(`systemctl could not read ${this.unit}: ${output.trim() || `exit ${String(result.status)}`}`) + } + if (this.established) return false + if (!this.direct.running() && existsSync(this.files.requestPath)) { + throw new Error(`subprocess scope ${this.unit} ended before consuming its launch request`) } if (this.killFailure !== undefined) throw this.killFailure return true @@ -196,7 +237,7 @@ class SystemdScopeOwner implements BoundProcessOwner { async waitForExit(): Promise { if (this.stopped) return this.observation ??= (async () => { - while (await this.active()) await sleepMs(SCOPE_POLL_INTERVAL_MS) + while (await this.rangeActive()) await sleepMs(SCOPE_POLL_INTERVAL_MS) this.stopped = true })().catch((error: unknown) => { this.observation = undefined @@ -204,119 +245,168 @@ class SystemdScopeOwner implements BoundProcessOwner { }) await this.observation } + + cleanup(): void { + cleanupLinuxLaunchFiles(this.files) + } } -/** Prepared node-pty argv plus the owner for the exact transient scope it enters. */ +function scopeArgs(unitBase: string, invocation: RunnerInvocation, argv: readonly string[]): string[] { + return [ + '--user', + '--scope', + '--quiet', + '--collect', + '--expand-environment=no', + `--unit=${unitBase}`, + '--', + ...invocation, + '--', + ...argv, + ] +} + +function directOutcome( + child: ReturnType, + files: LinuxLaunchFiles, +): Promise { + return new Promise((resolveOutcome, rejectOutcome) => { + let settled = false + child.once('error', (error) => { + if (settled) return + settled = true + rejectOutcome(error) + }) + child.once('exit', (exitCode, signal) => { + if (settled) return + settled = true + try { + const startup = readLinuxStartupError(files.startupErrorPath) + if (startup !== undefined) { + rejectOutcome(deserializeRunnerError(startup.error)) + return + } + if (existsSync(files.requestPath)) { + rejectOutcome(new Error('subprocess scope exited before its bootstrap consumed the launch request')) + return + } + resolveOutcome({ exitCode, signal }) + } catch (error) { + /* v8 ignore next -- Node filesystem operations throw Error instances. */ + const failure = error instanceof Error ? error : new Error(String(error)) + rejectOutcome(failure) + } + }) + }) +} + +function signalChildGroup(child: ReturnType, signal: 'SIGTERM' | 'SIGKILL'): void { + if (child.pid === undefined) return + try { + process.kill(-child.pid, signal) + } catch { + try { child.kill(signal) } catch { /* The direct process already exited. */ } + } +} + +/** Linux PTY invocation and owner for the exact one-shot scope/bootstrap. */ export interface LinuxTerminalScopeLaunch { command: string args: string[] - bindOwner(launcherRunning: () => boolean): BoundProcessOwner + cwd: string + env: NodeJS.ProcessEnv + bindOwner: (direct: DirectRange) => BoundProcessOwner + resolveOutcome: (outcome: SubprocessOutcome) => SubprocessOutcome + cleanup: () => void } /** - * Wrap one terminal argv directly in a transient user-systemd scope. - * @param argv - original terminal command and arguments. - * @param internals - injected systemd commands used by tests. - * @returns the node-pty command, literal arguments, and owner binding for the same unit. + * 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 facts and ownership callbacks for node-pty. */ export function prepareLinuxTerminalScope( - argv: readonly string[], + spec: SubprocessTerminalSpawnSpec, + targetEnv: Record, internals: LinuxScopeInternals = {}, ): LinuxTerminalScopeLaunch { - const runSync = internals.spawnSync ?? spawnSync - const query = internals.systemctlQuery ?? querySystemctl - const systemdRun = internals.systemdRun ?? 'systemd-run' - const systemctl = internals.systemctl ?? 'systemctl' + const invocation = internals.runnerInvocation ?? spawnRunnerInvocation() + const files = createLinuxLaunchFiles({ cwd: spec.cwd, env: targetEnv }) const unitBase = unitStem('dsh-terminal') return { - command: systemdRun, - args: [ - '--user', - '--scope', - '--quiet', - '--collect', - '--expand-environment=no', - `--unit=${unitBase}`, - '--', - ...argv, - ], - bindOwner: launcherRunning => new SystemdScopeOwner( + command: internals.systemdRun ?? 'systemd-run', + args: scopeArgs(unitBase, invocation, spec.argv), + cwd: process.cwd(), + env: runnerEnvironment(files.requestPath), + bindOwner: direct => new SystemdScopeOwner( `${unitBase}.scope`, - systemctl, - runSync, - query, - launcherRunning, - () => {}, + files, + direct, + internals.systemctl ?? 'systemctl', + internals.spawnSync ?? spawnSync, + internals.systemctlQuery ?? querySystemctl, ), + resolveOutcome: (outcome) => { + const startup = readLinuxStartupError(files.startupErrorPath) + if (startup !== undefined) throw deserializeRunnerError(startup.error) + if (existsSync(files.requestPath)) { + throw new Error('terminal scope exited before its bootstrap consumed the launch request') + } + return outcome + }, + cleanup: () => { cleanupLinuxLaunchFiles(files) }, } } /** - * Launch one direct command inside a transient user scope. - * @param spec - exact target argv, cwd, stdio, environment, and lifecycle settings. - * @param internals - injected command runners used by platform tests. - * @returns wrapper streams, target outcome, and the bound scope owner. + * 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 direct streams, result, and managed-scope owner. */ export function launchLinuxScope( spec: SubprocessSpawnSpec, + targetEnv: Record, internals: LinuxScopeInternals = {}, ): ManagedProcessLaunch { - const run = internals.spawn ?? spawn - const runSync = internals.spawnSync ?? spawnSync - const query = internals.systemctlQuery ?? querySystemctl - const systemdRun = internals.systemdRun ?? 'systemd-run' - const systemctl = internals.systemctl ?? 'systemctl' const invocation = internals.runnerInvocation ?? spawnRunnerInvocation() - const files = runnerFiles(spec) + const files = createLinuxLaunchFiles({ cwd: spec.cwd, env: targetEnv }) const unitBase = unitStem('dsh-subprocess') let child: ReturnType try { - child = run(systemdRun, [ - '--user', - '--scope', - '--quiet', - '--collect', - '--expand-environment=no', - `--unit=${unitBase}`, - '--', - ...invocation, - '--mode', - 'node', - '--request', - files.requestPath, - '--events', - files.eventsPath, - ], { - env: childEnv(), - stdio: runnerStdio(spec), + child = (internals.spawn ?? spawn)(internals.systemdRun ?? 'systemd-run', scopeArgs( + unitBase, + invocation, + spec.argv, + ), { + cwd: process.cwd(), + env: runnerEnvironment(files.requestPath), + stdio: runnerStdio(spec, false), + detached: true, }) } catch (error) { - cleanupRunnerFiles(files) + cleanupLinuxLaunchFiles(files) throw error } - const lifecycle = observeChildLifecycle(child) - let forceKillAttempted = false const owner = new SystemdScopeOwner( `${unitBase}.scope`, - systemctl, - runSync, - query, - () => child.pid !== undefined && child.exitCode === null && child.signalCode === null, - () => { forceKillAttempted = true }, + files, + { + running: () => child.pid !== undefined && child.exitCode === null && child.signalCode === null, + signal: (signal) => { signalChildGroup(child, signal) }, + }, + internals.systemctl ?? 'systemctl', + internals.spawnSync ?? spawnSync, + internals.systemctlQuery ?? querySystemctl, ) - const result = runnerDirectResult(child, files, lifecycle.exited) - const direct = result.direct.catch(async (error: unknown): Promise => { - if (!forceKillAttempted || !(error instanceof DirectResultUnavailableError)) throw error - await owner.waitForExit() - return { exitCode: null, signal: 'SIGKILL' } - }) - cleanupAfterRunner(files, direct, lifecycle.closed) return { stdin: child.stdin, stdout: child.stdout, stderr: child.stderr, - get pid() { return result.pid }, - direct, + direct: directOutcome(child, files), owner, } } diff --git a/packages/subprocess/subprocess-local/src/managed-owner.ts b/packages/subprocess/subprocess-local/src/managed-owner.ts index 5d5bd0b58f..da438a37c8 100644 --- a/packages/subprocess/subprocess-local/src/managed-owner.ts +++ b/packages/subprocess/subprocess-local/src/managed-owner.ts @@ -1,20 +1,18 @@ /** Minimal managed-range ownership bound to one ordinary subprocess handle. */ -import type { ChildProcess } from 'node:child_process' import type { Readable, Writable } from 'node:stream' import type { SubprocessOutcome } from '@deepseek-ai/dsh-subprocess' -/** Direct target started, but its runner closed before publishing an exit event. */ -export class DirectResultUnavailableError extends Error { - override name = 'DirectResultUnavailableError' -} - /** Platform owner used by termination and whole-range settlement. */ export interface BoundProcessOwner { - /** Signal the established managed range; a confirmed-stopped owner stays inert. */ - signal(signal: 'SIGTERM' | 'SIGKILL'): void - /** Wait for the same managed range to become empty; reject when its owner cannot be observed. */ + /** 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 + /** 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. */ @@ -22,45 +20,21 @@ export interface ManagedProcessLaunch { stdin: Writable | null stdout: Readable | null stderr: Readable | null - pid: number | undefined direct: Promise owner: BoundProcessOwner -} - -/** - * Observe runner exit separately from inherited stdio closure. - * @param child - native wrapper process. - * @returns promises for wrapper exit/error and full stdio closure. - */ -export function observeChildLifecycle(child: ChildProcess): { - exited: Promise - closed: Promise -} { - const exited = Promise.withResolvers() - const closed = Promise.withResolvers() - child.once('error', () => { - // runnerDirectResult reports the wrapper failure through the handle. - exited.resolve() - }) - child.once('exit', () => { exited.resolve() }) - child.once('close', () => { - exited.resolve() - closed.resolve() - }) - return { exited: exited.promise, closed: closed.promise } + /** Rejects if runner ownership is lost before `.done` completes its stdio barrier. */ + infrastructureFailure?: Promise } /** * Apply an optional abort bound to one shared wait promise. - * @param pending - authoritative platform wait. - * @param signal - optional caller bound. - * @returns true on completion, false when the bound aborts first. + * @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 async function waitWithAbort(pending: Promise, signal?: AbortSignal): Promise { if (signal?.aborted) { - void pending.catch(() => { - // This caller declined the wait; a later caller still observes the cached rejection. - }) + void pending.catch(() => {}) return false } if (signal === undefined) { diff --git a/packages/subprocess/subprocess-local/src/runner-launch.ts b/packages/subprocess/subprocess-local/src/runner-launch.ts index 3ab9f0abdd..699c4ec85c 100644 --- a/packages/subprocess/subprocess-local/src/runner-launch.ts +++ b/packages/subprocess/subprocess-local/src/runner-launch.ts @@ -1,148 +1,151 @@ -/** Parent-side launch and direct-result transport for native runners. */ +/** Parent-side invocation and bootstrap state for the private native runner. */ -import type { ChildProcess, StdioOptions } from 'node:child_process' -import { extname } from 'node:path' +import type { StdioOptions } from 'node:child_process' +import { accessSync, constants as fsConstants } from 'node:fs' +import { extname, isAbsolute } from 'node:path' +import { inspect } from 'node:util' import { fileURLToPath } from 'node:url' -import { setTimeout as sleepMs } from 'node:timers/promises' -import type { SubprocessOutcome, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' -import { - cleanupRunnerFiles, - createRunnerFiles, - deserializeSpawnError, - readRunnerEventsAsync, -} from './runner-protocol.ts' -import type { RunnerEvent, RunnerFiles, RunnerRequest } from './runner-protocol.ts' -import { DirectResultUnavailableError } from './managed-owner.ts' +import type { SubprocessSpawnSpec, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess' import { childEnv } from './spawn.ts' -const RUNNER_EVENT_POLL_MS = 100 -const PACKAGED_RUNNER_ARG = '--dsh-internal-subprocess-runner' +/** The one private environment variable consumed before target state is restored. */ +export const SUBPROCESS_RUNNER_ENV = 'DSH_SUBPROCESS_RUNNER' as const -/** Non-empty command tuple used to launch the private native runner. */ +/** Sentinel used by the packaged bootstrap for the Windows IPC runner. */ +export const WINDOWS_RUNNER_SELECTION = 'windows' as const + +/** Non-empty command tuple used to launch the private runner entry. */ export type RunnerInvocation = [string, ...string[]] /** - * Resolve the runner entry from the current module's source or built plane. - * @returns Node executable and runner argv prefix. + * Resolve the source, built, or packaged entry that calls the same runner core. + * @returns executable and arguments for the active runtime form. */ export function spawnRunnerInvocation(): RunnerInvocation { - if ('pkg' in process) return [process.execPath, PACKAGED_RUNNER_ARG] - /* v8 ignore start -- source-plane coverage cannot execute the bundled module; - the required built-runner smoke executes its private built entry. */ + if ('pkg' in process) return [process.execPath] + /* v8 ignore next -- built-artifact smoke imports the emitted JavaScript runner entry; + * source-unit coverage cannot change import.meta.url. */ if (extname(fileURLToPath(import.meta.url)) !== '.ts') { - const builtEntry = fileURLToPath(new URL('./spawn-runner.js', import.meta.url)) - return [process.execPath, builtEntry] + return [process.execPath, fileURLToPath(import.meta.resolve('@deepseek-ai/dsh-subprocess-local/runner'))] } - /* v8 ignore stop */ - const sourceEntry = fileURLToPath(import.meta.resolve('@deepseek-ai/dsh-subprocess-local/src/bin.ts')) - return [process.execPath, '--import', 'tsx/esm', sourceEntry] -} - -/** - * Build wrapper stdio corresponding to the public target dispositions. - * @param spec - target stdio request. - * @returns child-process stdio configuration. - */ -export function runnerStdio(spec: SubprocessSpawnSpec): StdioOptions { return [ - spec.stdio.stdin === 'ignore' ? 'ignore' : 'pipe', - spec.stdio.stdout === 'inherit' ? 'inherit' : 'pipe', - spec.stdio.stderr === 'inherit' ? 'inherit' : 'pipe', + process.execPath, + '--import', + 'tsx/esm', + fileURLToPath(new URL('./bin.ts', import.meta.url)), ] } /** - * Materialize the exact target request without undefined environment tombstones. - * @param spec - target argv, cwd, and explicit environment. - * @returns private request and event paths. + * Check the concrete runner executable and entry paths without executing a probe mode. + * @param invocation - resolved executable and runner-entry arguments. + * @returns whether every concrete executable or entry path is accessible. */ -export function runnerFiles(spec: SubprocessSpawnSpec): RunnerFiles { +export function runnerInvocationAvailable(invocation: RunnerInvocation = spawnRunnerInvocation()): boolean { + try { + if (isAbsolute(invocation[0])) accessSync(invocation[0], fsConstants.X_OK) + const entry = invocation.at(-1) + if (entry !== undefined && entry !== invocation[0] && isAbsolute(entry)) { + accessSync(entry, fsConstants.R_OK) + } + return true + } catch { + return false + } +} + +/** + * Build the bootstrap-safe environment; target overrides arrive through request/IPC. + * @param selection - private runner selector or Linux launch-request locator. + * @returns environment for the runner before target state is restored. + */ +export function runnerEnvironment(selection: string): NodeJS.ProcessEnv { + return childEnv({ + [SUBPROCESS_RUNNER_ENV]: selection, + SYSTEMD_LOG_TARGET: 'null', + }) +} + +/** + * Read and delete the private selector before importing or restoring target state. + * @param env - mutable environment containing the private selector. + * @returns the consumed selector, or undefined when no runner was requested. + */ +export function consumeRunnerSelection(env: NodeJS.ProcessEnv = process.env): string | undefined { + const selection = env[SUBPROCESS_RUNNER_ENV] + Reflect.deleteProperty(env, SUBPROCESS_RUNNER_ENV) + return selection +} + +/** + * Require the private argv delimiter and at least one target argv entry. + * @param argv - private runner arguments. + * @returns copied target argv after the private delimiter. + */ +export function parseRunnerTargetArgv(argv: readonly string[]): string[] { + if (argv[0] !== '--' || argv.length < 2) { + throw new Error('subprocess runner requires target argv after a private -- delimiter') + } + return [...argv.slice(1)] +} + +/** + * Build the stdio inherited unchanged by the target, optionally with Node IPC on fd 3. + * @param spec - ordinary subprocess request whose stdio modes are preserved. + * @param ipc - whether to append the private Node IPC descriptor. + * @returns child-process stdio options for the runner. + */ +export function runnerStdio( + spec: SubprocessSpawnSpec, + ipc: boolean, +): StdioOptions { + const stdio: StdioOptions = [ + spec.stdio.stdin === 'ignore' ? 'ignore' : 'pipe', + spec.stdio.stdout === 'inherit' ? 'inherit' : 'pipe', + spec.stdio.stderr === 'inherit' ? 'inherit' : 'pipe', + ] + if (ipc) (stdio as Array).push('ipc') + return stdio +} + +function throwNullByteError(property: string, value: string, argument: boolean): never { + const subject = argument ? `The argument '${property}'` : `The property '${property}'` + const error = new TypeError(`${subject} must be a string without null bytes. Received ${inspect(value)}`) + Object.assign(error, { code: 'ERR_INVALID_ARG_VALUE' }) + throw error +} + +function validateNoNullByte(property: string, value: string, argument = false): void { + if (value.includes('\0')) throwNullByteError(property, value, argument) +} + +/** + * Materialize and synchronously validate the final target environment. + * @param spec - final target argv, cwd, and environment overrides. + * @returns complete target environment after Node-equivalent validation. + */ +export function targetEnvironment( + spec: Pick, +): Record { + spec.argv.forEach((value, index) => { + validateNoNullByte(index === 0 ? 'file' : `args[${String(index - 1)}]`, value, true) + }) + validateNoNullByte('options.cwd', spec.cwd) const env = Object.fromEntries( Object.entries(childEnv(spec.env)).filter((entry): entry is [string, string] => entry[1] !== undefined), ) - const request: RunnerRequest = { argv: [...spec.argv], cwd: spec.cwd, env } - return createRunnerFiles(request) -} - -function directTerminalResult( - events: readonly RunnerEvent[], -): { outcome: SubprocessOutcome } | { error: Error } | undefined { - for (const event of events) { - if (event.type === 'exit') { - return { outcome: { exitCode: event.exitCode, signal: event.signal } } - } - if (event.type === 'spawn-error' || event.type === 'runner-error') { - return { error: deserializeSpawnError(event.error) } - } - } - return undefined -} - -async function waitForDirectResult( - child: ChildProcess, - files: RunnerFiles, - exited: Promise, - publishPid: (pid: number) => void, -): Promise { - let seen = 0 - const wrapperState = { exited: false } - void exited.then(() => { wrapperState.exited = true }) - for (;;) { - // A read started before exit may return a stale snapshot after exit has - // become visible. Only a read started after exit can prove no terminal - // event was written before the runner exited. - const exitedBeforeRead = wrapperState.exited - const events = await readRunnerEventsAsync(files.eventsPath) - const added = events.slice(seen) - for (const event of added) { - if (event.type === 'started') publishPid(event.pid) - } - const terminal = directTerminalResult(added) - if (terminal !== undefined) { - if ('error' in terminal) throw terminal.error - return terminal.outcome - } - seen = Math.max(seen, events.length) - if (exitedBeforeRead) { - if (child.pid === undefined) throw new Error('native subprocess runner failed to start') - throw new DirectResultUnavailableError('native subprocess runner exited without a direct-command result') - } - await sleepMs(RUNNER_EVENT_POLL_MS) + for (const [key, value] of Object.entries(env)) { + validateNoNullByte(`options.env['${key}']`, key) + validateNoNullByte(`options.env['${key}']`, value) } + return env } /** - * Bind asynchronous runner events into one direct result and target-pid getter. - * @param child - native wrapper process. - * @param files - private request and result paths. - * @param exited - wrapper exit/error observation attached before event polling. - * @returns a live target-pid view plus the direct result. + * Validate Linux PTY target strings before creating its request or terminal. + * @param spec - terminal subprocess request to validate. + * @returns complete validated target environment. */ -export function runnerDirectResult( - child: ChildProcess, - files: RunnerFiles, - exited: Promise, -): { - readonly pid: number | undefined - direct: Promise -} { - let pid: number | undefined - return { - get pid() { return pid }, - direct: waitForDirectResult(child, files, exited, (published) => { pid = published }), - } -} - -/** - * Remove request/result files after their reader settles and writer closes. - * @param files - private request and result paths. - * @param direct - target result promise. - * @param closed - runner close observation. - */ -export function cleanupAfterRunner( - files: RunnerFiles, - direct: Promise, - closed: Promise, -): void { - void Promise.allSettled([direct, closed]).then(() => { cleanupRunnerFiles(files) }) +export function validateTerminalTarget(spec: SubprocessTerminalSpawnSpec): Record { + return targetEnvironment(spec) } diff --git a/packages/subprocess/subprocess-local/src/runner-protocol.ts b/packages/subprocess/subprocess-local/src/runner-protocol.ts index af54bb8cb4..606bea11e8 100644 --- a/packages/subprocess/subprocess-local/src/runner-protocol.ts +++ b/packages/subprocess/subprocess-local/src/runner-protocol.ts @@ -1,29 +1,32 @@ -/** Private request and result transport shared by native subprocess runners. */ +/** Closed private transports shared by the native subprocess runner. */ import { - appendFileSync, + chmodSync, + existsSync, lstatSync, mkdtempSync, readFileSync, + renameSync, rmdirSync, unlinkSync, writeFileSync, } from 'node:fs' -import { readFile } from 'node:fs/promises' import { constants as osConstants, tmpdir } from 'node:os' -import { join } from 'node:path' +import { basename, dirname, isAbsolute, join } from 'node:path' -/** One direct command request consumed exactly once by the runner. */ -export interface RunnerRequest { - argv: string[] +const STARTUP_ERROR_TEMPORARY = '.startup-error.tmp' + +/** Target state restored by the Linux bootstrap after systemd establishes the scope. */ +export interface LinuxLaunchRequest { cwd: string env: Record } -/** Spawn-error fields preserved across the runner process boundary. */ -export interface SerializedSpawnError { +/** Bounded Node-shaped error fields allowed across a private runner boundary. */ +export interface SerializedRunnerError { name: string message: string + stack?: string code?: string errno?: number syscall?: string @@ -31,191 +34,266 @@ export interface SerializedSpawnError { spawnargs?: string[] } -/** Append-only direct-command facts emitted by the runner. */ -export type RunnerEvent = - | { type: 'started'; pid: number } - | { type: 'exit'; exitCode: number | null; signal: NodeJS.Signals | null } - | { type: 'spawn-error'; error: SerializedSpawnError } - | { type: 'runner-error'; error: SerializedSpawnError } +/** A Linux pre-exec failure published atomically beside its consumed request. */ +export type LinuxStartupError = + | { type: 'spawn-error'; error: SerializedRunnerError } + | { type: 'runner-error'; error: SerializedRunnerError } -/** Private per-spawn files; their directory is created with the host default private mkdtemp mode. */ -export interface RunnerFiles { +/** The only parent-to-runner start message on Windows. */ +export interface WindowsStartRequest { + type: 'start' + cwd: string + env: Record +} + +/** The only parent-to-runner control message on Windows. */ +export interface WindowsTerminateRequest { + type: 'terminate' +} + +/** Exactly one direct-result branch is sent by a connected Windows runner. */ +export type WindowsRunnerResult = + | { type: 'target-exit'; exitCode: number | null; signal: NodeJS.Signals | null } + | { type: 'spawn-error'; error: SerializedRunnerError } + | { type: 'runner-error'; error: SerializedRunnerError } + | { type: 'start-cancelled' } + +/** Private paths owned by one Linux ordinary or PTY spawn. */ +export interface LinuxLaunchFiles { directory: string requestPath: string - eventsPath: string + startupErrorPath: string } function isRecord(value: unknown): value is Record { return value !== null && typeof value === 'object' && !Array.isArray(value) } -function isOptionalString(value: unknown): boolean { - return value === undefined || typeof value === 'string' +function hasExactKeys(value: Record, required: readonly string[], optional: readonly string[] = []): boolean { + const allowed = new Set([...required, ...optional]) + return required.every(key => Object.hasOwn(value, key)) + && Object.keys(value).every(key => allowed.has(key)) } -function isSerializedSpawnError(value: unknown): value is SerializedSpawnError { - return isRecord(value) - && typeof value.name === 'string' +function isStringRecord(value: unknown): value is Record { + return isRecord(value) && Object.values(value).every(entry => typeof entry === 'string') +} + +function isSerializedRunnerError(value: unknown): value is SerializedRunnerError { + if (!isRecord(value) || !hasExactKeys( + value, + ['name', 'message'], + ['stack', 'code', 'errno', 'syscall', 'path', 'spawnargs'], + )) return false + return typeof value.name === 'string' && typeof value.message === 'string' - && isOptionalString(value.code) + && (value.stack === undefined || typeof value.stack === 'string') + && (value.code === undefined || typeof value.code === 'string') && (value.errno === undefined || typeof value.errno === 'number') - && isOptionalString(value.syscall) - && isOptionalString(value.path) + && (value.syscall === undefined || typeof value.syscall === 'string') + && (value.path === undefined || typeof value.path === 'string') && (value.spawnargs === undefined - || (Array.isArray(value.spawnargs) && value.spawnargs.every(item => typeof item === 'string'))) + || (Array.isArray(value.spawnargs) && value.spawnargs.every(entry => typeof entry === 'string'))) } -function parseRunnerEvent(line: string): RunnerEvent { - const event: unknown = JSON.parse(line) - if (!isRecord(event)) throw new Error(`subprocess runner emitted invalid event: ${line}`) - if (event.type === 'started') { - if (typeof event.pid !== 'number' || !Number.isSafeInteger(event.pid) || event.pid <= 0) { - throw new Error(`subprocess runner emitted invalid event: ${line}`) - } - return { type: 'started', pid: event.pid } +function parseErrorResult(value: Record): LinuxStartupError { + if (!hasExactKeys(value, ['type', 'error']) || !isSerializedRunnerError(value.error)) { + throw new Error('subprocess runner emitted an invalid error result') } - if (event.type === 'exit') { - const validExitCode = event.exitCode === null - || (typeof event.exitCode === 'number' && Number.isSafeInteger(event.exitCode) && event.exitCode >= 0) - const validSignal = event.signal === null - || (typeof event.signal === 'string' && Object.hasOwn(osConstants.signals, event.signal)) - if (!validExitCode || !validSignal) throw new Error(`subprocess runner emitted invalid event: ${line}`) - return { - type: 'exit', - exitCode: event.exitCode as number | null, - signal: event.signal as NodeJS.Signals | null, - } + if (value.type !== 'spawn-error' && value.type !== 'runner-error') { + throw new Error('subprocess runner emitted an unknown error result') } - if (event.type === 'spawn-error' || event.type === 'runner-error') { - if (!isSerializedSpawnError(event.error)) throw new Error(`subprocess runner emitted invalid event: ${line}`) - return { type: event.type, error: event.error } - } - throw new Error(`subprocess runner emitted unknown event: ${line}`) + return { type: value.type, error: value.error } } /** - * Materialize one private runner request. - * @param request - exact target argv, cwd, and environment. - * @returns request and event paths owned by this spawn. + * Create a private 0700 directory and one complete 0600 launch request. + * @param request - target cwd and complete environment for the bootstrap. + * @returns private paths owned by this launch. */ -export function createRunnerFiles(request: RunnerRequest): RunnerFiles { - const directory = mkdtempSync(join(tmpdir(), 'dsh-subprocess-runner-')) - const requestPath = join(directory, 'request.json') - const eventsPath = join(directory, 'events.ndjson') - writeFileSync(requestPath, JSON.stringify(request), { flag: 'wx', mode: 0o600 }) - return { directory, requestPath, eventsPath } -} - -/** - * Read and remove the single-use request before target execution. - * @param requestPath - private request file. - * @returns parsed runner request. - */ -export function consumeRunnerRequest(requestPath: string): RunnerRequest { - const parsed: unknown = JSON.parse(readFileSync(requestPath, 'utf8')) - unlinkSync(requestPath) - if (!isRecord(parsed) || !Array.isArray(parsed.argv) || parsed.argv.length === 0 - || !parsed.argv.every(value => typeof value === 'string')) { - throw new Error('subprocess runner request has no executable') +export function createLinuxLaunchFiles(request: LinuxLaunchRequest): LinuxLaunchFiles { + const directory = mkdtempSync(join(tmpdir(), 'dsh-subprocess-launch-')) + const files = { + directory, + requestPath: join(directory, 'launch-request.json'), + startupErrorPath: join(directory, 'startup-error.json'), } - if (typeof parsed.cwd !== 'string' || !isRecord(parsed.env) - || !Object.values(parsed.env).every(value => typeof value === 'string')) { - throw new Error('subprocess runner request has invalid cwd or environment') - } - return { - argv: parsed.argv, - cwd: parsed.cwd, - env: parsed.env as Record, - } -} - -/** - * Append one complete event record. - * @param eventsPath - private append-only event file. - * @param event - direct-command fact. - */ -export function appendRunnerEvent(eventsPath: string, event: RunnerEvent): void { - appendFileSync(eventsPath, `${JSON.stringify(event)}\n`, { mode: 0o600 }) -} - -/** Parse complete newline-terminated runner records. */ -function parseRunnerEvents(content: string): RunnerEvent[] { - const lines = content.split('\n') - if (lines.at(-1) !== '') lines.pop() - return lines.filter(line => line.length > 0).map(parseRunnerEvent) -} - -/** - * Asynchronously parse every complete event record currently present. - * @param eventsPath - private event file. - * @returns complete records in append order. - */ -export async function readRunnerEventsAsync(eventsPath: string): Promise { - let content: string try { - content = await readFile(eventsPath, 'utf8') + chmodSync(directory, 0o700) + writeFileSync(files.requestPath, JSON.stringify(request), { flag: 'wx', mode: 0o600 }) + return files } catch (error) { - if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [] + cleanupLinuxLaunchFiles(files) throw error } - return parseRunnerEvents(content) } /** - * Convert an unknown failure into stable cross-process error fields. - * @param error - failure raised by target or runner launch. - * @returns serializable Node-shaped fields. + * Derive the only permitted startup-error path from an absolute request locator. + * @param requestPath - absolute path to the private launch-request file. + * @returns validated sibling paths for this launch. */ -export function serializeSpawnError(error: unknown): SerializedSpawnError { +export function linuxLaunchFilesFromLocator(requestPath: string): LinuxLaunchFiles { + if (!isAbsolute(requestPath) || basename(requestPath) !== 'launch-request.json') { + throw new Error('subprocess runner received an invalid Linux launch-request locator') + } + const directory = dirname(requestPath) + return { directory, requestPath, startupErrorPath: join(directory, 'startup-error.json') } +} + +/** + * Strictly read and remove a one-shot Linux launch request. + * @param requestPath - private launch-request path to consume. + * @returns validated target cwd and environment. + */ +export function consumeLinuxLaunchRequest(requestPath: string): LinuxLaunchRequest { + const text = readFileSync(requestPath, 'utf8') + unlinkSync(requestPath) + const value: unknown = JSON.parse(text) + if (!isRecord(value) || !hasExactKeys(value, ['cwd', 'env']) + || typeof value.cwd !== 'string' || !isStringRecord(value.env)) { + throw new Error('subprocess runner received an invalid Linux launch request') + } + return { cwd: value.cwd, env: value.env } +} + +/** + * Atomically publish one strict 0600 Linux pre-exec error. + * @param files - private paths for this launch. + * @param error - bounded spawn or runner failure to publish. + */ +export function writeLinuxStartupError(files: LinuxLaunchFiles, error: LinuxStartupError): void { + const temporary = join(files.directory, STARTUP_ERROR_TEMPORARY) + writeFileSync(temporary, JSON.stringify(error), { flag: 'wx', mode: 0o600 }) + renameSync(temporary, files.startupErrorPath) +} + +/** + * Read the Linux pre-exec error, if the bootstrap published one. + * @param path - expected startup-error path. + * @returns the validated failure, or undefined when none was published. + */ +export function readLinuxStartupError(path: string): LinuxStartupError | undefined { + if (!existsSync(path)) return undefined + const value: unknown = JSON.parse(readFileSync(path, 'utf8')) + if (!isRecord(value)) throw new Error('subprocess runner emitted an invalid startup error') + return parseErrorResult(value) +} + +/** + * Strictly parse the single Windows start message. + * @param value - untrusted IPC payload. + * @returns validated target start request. + */ +export function parseWindowsStartRequest(value: unknown): WindowsStartRequest { + if (!isRecord(value) || !hasExactKeys(value, ['type', 'cwd', 'env']) + || value.type !== 'start' || typeof value.cwd !== 'string' || !isStringRecord(value.env)) { + throw new Error('subprocess runner received an invalid Windows start request') + } + return { type: 'start', cwd: value.cwd, env: value.env } +} + +/** + * Return true only for the exact, payload-free Windows terminate control. + * @param value - untrusted IPC payload. + * @returns whether the payload is the exact terminate request. + */ +export function isWindowsTerminateRequest(value: unknown): value is WindowsTerminateRequest { + return isRecord(value) && hasExactKeys(value, ['type']) && value.type === 'terminate' +} + +/** + * Strictly parse one of the four Windows direct-result branches. + * @param value - untrusted IPC payload. + * @returns validated direct-result message. + */ +export function parseWindowsRunnerResult(value: unknown): WindowsRunnerResult { + if (!isRecord(value) || typeof value.type !== 'string') { + throw new Error('subprocess runner emitted an invalid Windows result') + } + if (value.type === 'start-cancelled') { + if (!hasExactKeys(value, ['type'])) throw new Error('subprocess runner emitted an invalid start-cancelled result') + return { type: 'start-cancelled' } + } + if (value.type === 'spawn-error' || value.type === 'runner-error') return parseErrorResult(value) + if (value.type === 'target-exit') { + const validExitCode = value.exitCode === null + || (typeof value.exitCode === 'number' && Number.isSafeInteger(value.exitCode) && value.exitCode >= 0) + const validSignal = value.signal === null + || (typeof value.signal === 'string' && Object.hasOwn(osConstants.signals, value.signal)) + if (!hasExactKeys(value, ['type', 'exitCode', 'signal']) || !validExitCode || !validSignal) { + throw new Error('subprocess runner emitted an invalid target-exit result') + } + return { + type: 'target-exit', + exitCode: value.exitCode as number | null, + signal: value.signal as NodeJS.Signals | null, + } + } + throw new Error(`subprocess runner emitted an unknown Windows result: ${value.type}`) +} + +/** + * Convert an unknown failure into the bounded cross-process error record. + * @param error - failure caught at the process boundary. + * @returns bounded serializable error fields. + */ +export function serializeRunnerError(error: unknown): SerializedRunnerError { const source = error instanceof Error ? error : new Error(String(error)) const node = source as NodeJS.ErrnoException & { path?: string; spawnargs?: string[] } return { name: source.name, message: source.message, + ...typeof source.stack === 'string' ? { stack: source.stack } : {}, ...typeof node.code === 'string' ? { code: node.code } : {}, ...typeof node.errno === 'number' ? { errno: node.errno } : {}, ...typeof node.syscall === 'string' ? { syscall: node.syscall } : {}, ...typeof node.path === 'string' ? { path: node.path } : {}, - ...Array.isArray(node.spawnargs) ? { spawnargs: [...node.spawnargs] } : {}, + ...Array.isArray(node.spawnargs) && node.spawnargs.every(entry => typeof entry === 'string') + ? { spawnargs: [...node.spawnargs] } + : {}, } } /** - * Reconstruct one Node-shaped spawn error for the public done rejection. - * @param serialized - fields received from the runner. - * @returns error with Node spawn properties restored. + * Rebuild a Node-shaped Error from a strict runner record. + * @param serialized - validated bounded error fields. + * @returns reconstructed Error with supported Node fields. */ -export function deserializeSpawnError(serialized: SerializedSpawnError): Error { +export function deserializeRunnerError(serialized: SerializedRunnerError): Error { const error = new Error(serialized.message) error.name = serialized.name + if (serialized.stack !== undefined) error.stack = serialized.stack return Object.assign(error, { ...serialized.code === undefined ? {} : { code: serialized.code }, ...serialized.errno === undefined ? {} : { errno: serialized.errno }, ...serialized.syscall === undefined ? {} : { syscall: serialized.syscall }, ...serialized.path === undefined ? {} : { path: serialized.path }, - ...serialized.spawnargs === undefined ? {} : { spawnargs: serialized.spawnargs }, + ...serialized.spawnargs === undefined ? {} : { spawnargs: [...serialized.spawnargs] }, }) } /** - * Remove only the private directory created for this spawn. - * @param files - private paths returned by createRunnerFiles. + * Best-effort removal of only the private paths created for this Linux spawn. + * @param files - exact private paths owned by this launch. */ -export function cleanupRunnerFiles(files: RunnerFiles): void { +export function cleanupLinuxLaunchFiles(files: LinuxLaunchFiles): void { try { if (lstatSync(files.directory).isSymbolicLink()) { unlinkSync(files.directory) return } - for (const file of [files.requestPath, files.eventsPath]) { - try { - unlinkSync(file) - } catch (error) { + for (const path of [ + files.requestPath, + files.startupErrorPath, + join(files.directory, STARTUP_ERROR_TEMPORARY), + ]) { + try { unlinkSync(path) } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error } } rmdirSync(files.directory) } catch { - // A crash residue remains private and is not reused by later spawns. + // Crash residue remains private and no later spawn reuses this directory. } } diff --git a/packages/subprocess/subprocess-local/src/spawn-runner.ts b/packages/subprocess/subprocess-local/src/spawn-runner.ts index 1e122e88b5..967f98cdbd 100644 --- a/packages/subprocess/subprocess-local/src/spawn-runner.ts +++ b/packages/subprocess/subprocess-local/src/spawn-runner.ts @@ -1,102 +1,72 @@ -/** Native managed-range runner for ordinary local subprocesses. */ +/** One-shot Linux exec bootstrap and Windows Job-owning subprocess runner. */ -import { spawn } from 'node:child_process' +import { delimiter, resolve } from 'node:path' import { + closeCurrentProcessStandardHandles, closeHandleChecked, isJobEmpty, loadWin32ProcessBindings, - openNamedPipeForStdio, pollProcessExit, spawnCurrentTokenJobProcess, terminateJob, - waitForProcessExit, Win32Error, } from '@deepseek-ai/dsh-win32-process' -import type { ChildStdioHandles, NativePtr } from '@deepseek-ai/dsh-win32-process' +import type { NativePtr, Win32ProcessBindings } from '@deepseek-ai/dsh-win32-process' import { - appendRunnerEvent, - consumeRunnerRequest, - serializeSpawnError, + consumeLinuxLaunchRequest, + isWindowsTerminateRequest, + linuxLaunchFilesFromLocator, + parseWindowsStartRequest, + serializeRunnerError, + writeLinuxStartupError, } from './runner-protocol.ts' -import type { RunnerRequest, SerializedSpawnError } from './runner-protocol.ts' +import type { + LinuxLaunchFiles, + SerializedRunnerError, + WindowsRunnerResult, + WindowsStartRequest, +} from './runner-protocol.ts' +import { + parseRunnerTargetArgv, + SUBPROCESS_RUNNER_ENV, + WINDOWS_RUNNER_SELECTION, +} from './runner-launch.ts' -type RunnerArgs = - | { mode: 'probe-node' } - | { mode: 'probe-win32' } - | { mode: 'node'; requestPath: string; eventsPath: string } - | { - mode: 'win32' - requestPath: string - eventsPath: string - stdinPipe?: string - stdoutPipe?: string - stderrPipe?: string - } +type RunnerHost = Pick & { + send?: NodeJS.Process['send'] +} -type RunnerHost = Pick< - NodeJS.Process, - 'env' | 'exitCode' | 'connected' | 'cwd' | 'chdir' | 'on' | 'off' | 'disconnect' -> - -interface RunnerInternals { - spawn: typeof spawn - loadWin32ProcessBindings: typeof loadWin32ProcessBindings - openNamedPipeForStdio: typeof openNamedPipeForStdio +/** Injectable operations used by the protocol-owner tests. */ +export interface SpawnRunnerInternals { + execve(file: string, argv: string[], env: Record): never + loadWin32ProcessBindings(): Win32ProcessBindings spawnCurrentTokenJobProcess: typeof spawnCurrentTokenJobProcess + closeCurrentProcessStandardHandles: typeof closeCurrentProcessStandardHandles pollProcessExit: typeof pollProcessExit isJobEmpty: typeof isJobEmpty terminateJob: typeof terminateJob - waitForProcessExit: typeof waitForProcessExit closeHandleChecked: typeof closeHandleChecked } -const defaultRunnerInternals: RunnerInternals = { - spawn, +const defaultInternals: SpawnRunnerInternals = { + /* v8 ignore next -- source/built/packaged subprocess smoke executes this only in a replaceable child process. */ + execve: (file, argv, env) => (process.execve as NonNullable)(file, argv, env), loadWin32ProcessBindings, - openNamedPipeForStdio, spawnCurrentTokenJobProcess, + closeCurrentProcessStandardHandles, pollProcessExit, isJobEmpty, terminateJob, - waitForProcessExit, closeHandleChecked, } -function parseArgs(argv: string[]): RunnerArgs { - let mode: string | undefined - let requestPath: string | undefined - let eventsPath: string | undefined - let stdinPipe: string | undefined - let stdoutPipe: string | undefined - let stderrPipe: string | undefined - for (let index = 0; index < argv.length; index += 2) { - const key = argv[index] - const value = argv[index + 1] - if (value === undefined) throw new Error(`subprocess runner missing value after ${String(key)}`) - if (key === '--mode') mode = value - else if (key === '--request') requestPath = value - else if (key === '--events') eventsPath = value - else if (key === '--stdin-pipe') stdinPipe = value - else if (key === '--stdout-pipe') stdoutPipe = value - else if (key === '--stderr-pipe') stderrPipe = value - else throw new Error(`subprocess runner unknown argument: ${String(key)}`) - } - if (mode === 'probe-node' || mode === 'probe-win32') return { mode } - if (mode !== 'node' && mode !== 'win32') throw new Error(`subprocess runner unknown mode: ${String(mode)}`) - if (requestPath === undefined || eventsPath === undefined) throw new Error('subprocess runner requires request and event paths') - if (mode === 'node') return { mode, requestPath, eventsPath } - return { - mode, - requestPath, - eventsPath, - ...stdinPipe === undefined ? {} : { stdinPipe }, - ...stdoutPipe === undefined ? {} : { stdoutPipe }, - ...stderrPipe === undefined ? {} : { stderrPipe }, - } +function replaceEnvironment(target: NodeJS.ProcessEnv, env: Record): void { + for (const key of Object.keys(target)) Reflect.deleteProperty(target, key) + Object.assign(target, env) } -function win32SpawnError(error: unknown, request: RunnerRequest): SerializedSpawnError { - const serialized = serializeSpawnError(error) +function asSpawnError(error: unknown, program: string, args: readonly string[]): SerializedRunnerError { + const serialized = serializeRunnerError(error) const code = error instanceof Win32Error ? error.win32Code === 2 || error.win32Code === 3 || error.win32Code === 267 ? 'ENOENT' @@ -107,264 +77,353 @@ function win32SpawnError(error: unknown, request: RunnerRequest): SerializedSpaw : 'UNKNOWN' : serialized.code if (code === undefined) return serialized - const program = request.argv[0] as string return { ...serialized, message: `spawn ${program} ${code}: ${serialized.message}`, code, syscall: `spawn ${program}`, path: program, - spawnargs: request.argv.slice(1), + spawnargs: [...args], } } -async function runNode( - request: RunnerRequest, - eventsPath: string, - host: RunnerHost, - internals: RunnerInternals, -): Promise { - const ignoreScopeSignal = (): void => { /* The target receives the scope signal; the runner reports its outcome. */ } - for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'] as const) { - host.on(signal, ignoreScopeSignal) - } - const [program, ...args] = request.argv - const child = internals.spawn(program as string, args, { - cwd: request.cwd, - env: request.env, - stdio: 'inherit', - detached: true, +function linuxPathNotFoundError(program: string): NodeJS.ErrnoException { + return Object.assign(new Error(`spawn ${program} ENOENT`), { + code: 'ENOENT', + errno: -2, + syscall: `spawn ${program}`, + path: program, + spawnargs: [] as string[], }) - await new Promise((resolve) => { - let started = false - let failed = false - let settled = false - const finish = (): void => { - if (settled) return - settled = true - for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'] as const) host.off(signal, ignoreScopeSignal) - resolve() - } - child.once('spawn', () => { - started = true - appendRunnerEvent(eventsPath, { type: 'started', pid: child.pid as number }) - }) - child.once('error', (error) => { - failed = true - if (!started) appendRunnerEvent(eventsPath, { type: 'spawn-error', error: serializeSpawnError(error) }) - else appendRunnerEvent(eventsPath, { type: 'runner-error', error: serializeSpawnError(error) }) - host.exitCode = 127 - finish() - }) - child.once('exit', (exitCode, signal) => { - if (!failed) { - appendRunnerEvent(eventsPath, { type: 'exit', exitCode, signal }) - host.exitCode = exitCode ?? 1 +} + +function execLinuxTarget( + request: { cwd: string; env: Record }, + argv: string[], + internals: SpawnRunnerInternals, +): never { + const program = argv[0] as string + if (program.includes('/')) return internals.execve(program, argv, request.env) + const path = request.env.PATH ?? '/usr/bin:/bin' + let permissionFailure: Error | undefined + for (const directory of path.split(delimiter)) { + const candidate = resolve(request.cwd, directory, program) + try { + return internals.execve(candidate, argv, request.env) + } catch (error) { + const code = (error as NodeJS.ErrnoException).code + if (code === 'EACCES') { + permissionFailure ??= error as Error + continue } - finish() - }) - }) -} - -function replaceEnvironment(target: NodeJS.ProcessEnv, env: Record): void { - for (const key of Object.keys(target)) Reflect.deleteProperty(target, key) - Object.assign(target, env) -} - -function closeStdioHandles( - api: ReturnType, - handles: Array<{ handle: NativePtr; label: string }>, - reportFailure: boolean, - internals: RunnerInternals, -): void { - let failure: Error | undefined - for (const owned of handles.splice(0)) { - try { - internals.closeHandleChecked(api, owned.handle, owned.label) - } catch (error) { - handles.push(owned) - failure ??= error instanceof Error ? error : new Error(serializeSpawnError(error).message) - } - } - if (reportFailure && failure !== undefined) throw failure -} - -async function runWin32( - request: RunnerRequest, - eventsPath: string, - pipes: Pick, 'stdinPipe' | 'stdoutPipe' | 'stderrPipe'>, - host: RunnerHost, - internals: RunnerInternals, -): Promise { - replaceEnvironment(host.env, request.env) - const api = internals.loadWin32ProcessBindings() - let processHandle: NativePtr | undefined - let jobHandle: NativePtr | undefined - const openedStdio: Array<{ handle: NativePtr; label: string }> = [] - try { - const stdio: ChildStdioHandles = {} - for (const [key, path, access] of [ - ['stdin', pipes.stdinPipe, 'read'], - ['stdout', pipes.stdoutPipe, 'write'], - ['stderr', pipes.stderrPipe, 'write'], - ] as const) { - if (path === undefined) continue - const handle = internals.openNamedPipeForStdio(api, path, access) - stdio[key] = handle - openedStdio.push({ handle, label: `ordinary target ${key} pipe` }) - } - // Match Node's cwd-relative executable lookup and spawn-error attribution. - const runnerCwd = host.cwd() - host.chdir(request.cwd) - const [command, ...args] = request.argv - let spawned: ReturnType - try { - spawned = internals.spawnCurrentTokenJobProcess( - api, - { command: command as string, args, cwd: host.cwd() }, - stdio, - ) - } catch (error) { - try { host.chdir(runnerCwd) } catch { /* Preserve the target startup failure. */ } + if (code === 'ENOENT' || code === 'ENOTDIR') continue throw error } - try { - processHandle = spawned.process - jobHandle = spawned.job - appendRunnerEvent(eventsPath, { type: 'started', pid: spawned.pid }) - } finally { - host.chdir(runnerCwd) - } - closeStdioHandles(api, openedStdio, true, internals) - - await new Promise((resolve, reject) => { - let settled = false - let terminationRequested = false - const settle = (error?: unknown): void => { - if (settled) return - settled = true - clearInterval(timer) - host.off('message', onMessage) - host.off('disconnect', onDisconnect) - if (error === undefined) resolve() - else reject(error instanceof Error ? error : new Error(serializeSpawnError(error).message)) - } - const terminate = (): void => { - if (terminationRequested || jobHandle === undefined) return - terminationRequested = true - try { - internals.terminateJob(api, jobHandle, 1) - } catch (error) { - settle(error) - } - } - const onMessage = (message: unknown): void => { - if (message !== null && typeof message === 'object' && (message as { type?: unknown }).type === 'terminate') { - terminate() - } - } - const onDisconnect = (): void => { terminate() } - host.on('message', onMessage) - host.on('disconnect', onDisconnect) - const timer = setInterval(() => { - try { - if (processHandle !== undefined) { - const exitCode = internals.pollProcessExit(api, processHandle) - if (exitCode !== undefined) { - appendRunnerEvent(eventsPath, { type: 'exit', exitCode, signal: null }) - internals.closeHandleChecked(api, processHandle, 'ordinary direct process') - processHandle = undefined - } - } - if (processHandle === undefined && jobHandle !== undefined && internals.isJobEmpty(api, jobHandle)) { - internals.closeHandleChecked(api, jobHandle, 'ordinary process Job') - jobHandle = undefined - settle() - } - } catch (error) { - settle(error) - } - }, 10) - }) - } catch (error) { - const targetSpawnFailed = (error instanceof Win32Error && error.api === 'CreateProcessW') - || (processHandle === undefined - && error instanceof Error - && (error as NodeJS.ErrnoException).syscall === 'chdir') - appendRunnerEvent(eventsPath, { - type: targetSpawnFailed ? 'spawn-error' : 'runner-error', - error: targetSpawnFailed ? win32SpawnError(error, request) : serializeSpawnError(error), - }) - if (!targetSpawnFailed) host.exitCode = 127 - } finally { - closeStdioHandles(api, openedStdio, false, internals) - if (processHandle !== undefined) { - try { internals.closeHandleChecked(api, processHandle, 'ordinary direct process cleanup') } catch { /* best effort after reported failure */ } - } - if (jobHandle !== undefined) { - try { internals.closeHandleChecked(api, jobHandle, 'ordinary process Job cleanup') } catch { /* best effort after reported failure */ } - } } + throw permissionFailure ?? linuxPathNotFoundError(program) } -function probeWin32Job(host: RunnerHost, internals: RunnerInternals): void { - const command = host.env.ComSpec ?? host.env.COMSPEC - if (command === undefined) throw new Error('subprocess runner cannot probe a Windows Job without ComSpec') - const api = internals.loadWin32ProcessBindings() - const spawned = internals.spawnCurrentTokenJobProcess(api, { - command, - args: ['/d', '/s', '/c', 'exit 0'], - cwd: host.cwd(), - }) - try { - const exitCode = internals.waitForProcessExit(api, spawned.process) - if (exitCode !== 0) throw new Error(`subprocess Windows Job probe exited with code ${String(exitCode)}`) - } finally { - internals.closeHandleChecked(api, spawned.job, 'subprocess Windows Job probe') - } -} - -/** - * Execute one parsed private-runner request. - * @param argv - runner arguments after the executable and entry path. - * @param host - process operations; tests provide an isolated host facade. - * @param internals - platform operations; tests replace native Win32 calls. - * @returns after the requested probe or target lifecycle completes. - */ -export async function runSpawnRunner( +function runLinux( + locator: string, argv: string[], - host: RunnerHost = process, - internals: RunnerInternals = defaultRunnerInternals, -): Promise { - const args = parseArgs(argv) - if (args.mode === 'probe-node') return - if (args.mode === 'probe-win32') { - probeWin32Job(host, internals) + host: RunnerHost, + internals: SpawnRunnerInternals, +): void { + const files = linuxLaunchFilesFromLocator(locator) + let request: ReturnType + try { + request = consumeLinuxLaunchRequest(files.requestPath) + } catch (error) { + writeLinuxStartupError(files, { type: 'runner-error', error: serializeRunnerError(error) }) + host.exitCode = 127 return } - const request = consumeRunnerRequest(args.requestPath) - if (args.mode === 'node') await runNode(request, args.eventsPath, host, internals) - else { - try { - await runWin32(request, args.eventsPath, args, host, internals) - } finally { - if (host.connected) host.disconnect() + try { + host.chdir(request.cwd) + execLinuxTarget(request, argv, internals) + } catch (error) { + writeLinuxStartupError(files, { + type: 'spawn-error', + error: asSpawnError(error, argv[0] as string, argv.slice(1)), + }) + host.exitCode = 127 + } +} + +function sendMessage(host: RunnerHost, result: WindowsRunnerResult): Promise { + return new Promise((resolve, reject) => { + if (!host.connected || host.send === undefined) { + reject(new Error('subprocess runner IPC is not connected')) + return } + try { + host.send(result, (error) => { + if (error === null) resolve() + else reject(error) + }) + } catch (error) { + /* v8 ignore next -- process.send throws Error instances. */ + const failure = error instanceof Error ? error : new Error(String(error)) + reject(failure) + } + }) +} + +class WindowsJobRunner { + private api: Win32ProcessBindings | undefined + private processHandle: NativePtr | undefined + private jobHandle: NativePtr | undefined + private pollTimer: ReturnType | undefined + private startSeen = false + private committed = false + private terminateRequested = false + private resultStarted = false + private resultDelivered = false + private jobEmpty = false + private finished = false + private readonly completion = Promise.withResolvers() + + constructor( + private readonly argv: string[], + private readonly host: RunnerHost, + private readonly internals: SpawnRunnerInternals, + ) {} + + run(): Promise { + if (!this.host.connected || this.host.send === undefined) { + this.finish(127) + return this.completion.promise + } + this.host.on('message', this.onMessage) + this.host.once('disconnect', this.onDisconnect) + return this.completion.promise + } + + private readonly onMessage = (value: unknown): void => { + if (this.finished) return + if (isWindowsTerminateRequest(value)) { + this.requestTermination() + return + } + if (this.startSeen) { + void this.runnerFailure(new Error('subprocess runner received more than one Windows start request')) + return + } + let request: WindowsStartRequest + try { + request = parseWindowsStartRequest(value) + } catch (error) { + void this.runnerFailure(error) + return + } + this.startSeen = true + void this.start(request) + } + + private readonly onDisconnect = (): void => { + if (this.finished) return + this.releaseOwnedJob() + this.finish(127, false) + } + + private async start(request: WindowsStartRequest): Promise { + if (this.terminateRequested) { + await this.publishTerminalResult({ type: 'start-cancelled' }, 0) + return + } + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + if (this.finished) return + if (this.startCancellationPending()) { + await this.publishTerminalResult({ type: 'start-cancelled' }, 0) + return + } + try { + replaceEnvironment(this.host.env, request.env) + this.api = this.internals.loadWin32ProcessBindings() + const [command, ...args] = this.argv + const spawned = this.internals.spawnCurrentTokenJobProcess(this.api, { + command: command as string, + args, + cwd: request.cwd, + }) + this.processHandle = spawned.process + this.jobHandle = spawned.job + this.committed = true + this.internals.closeCurrentProcessStandardHandles(this.api) + if (this.startCancellationPending()) this.terminateOwnedJob() + this.pollTimer = setInterval(() => { this.poll() }, 10) + this.poll() + } catch (error) { + if (!this.committed && error instanceof Win32Error && error.api === 'CreateProcessW') { + await this.publishTerminalResult({ + type: 'spawn-error', + error: asSpawnError(error, this.argv[0] as string, this.argv.slice(1)), + }, 0) + return + } + await this.runnerFailure(error) + } + } + + private requestTermination(): void { + if (this.terminateRequested) return + this.terminateRequested = true + if (this.committed) { + try { + this.terminateOwnedJob() + } catch (error) { + void this.runnerFailure(error) + } + } + } + + private startCancellationPending(): boolean { + return this.terminateRequested + } + + private terminateOwnedJob(): void { + const job = this.jobHandle + if (job === undefined) 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 === undefined) return + this.internals.terminateJob(this.api, job, 1) + } + + private poll(): void { + 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 === undefined) return + try { + if (this.processHandle !== undefined) { + const exitCode = this.internals.pollProcessExit(this.api, this.processHandle) + if (exitCode !== undefined) { + this.internals.closeHandleChecked(this.api, this.processHandle, 'ordinary direct process') + this.processHandle = undefined + void this.publishTerminalResult({ type: 'target-exit', exitCode, signal: null }) + } + } + if (this.jobHandle !== undefined && this.internals.isJobEmpty(this.api, this.jobHandle)) { + this.internals.closeHandleChecked(this.api, this.jobHandle, 'ordinary process Job') + this.jobHandle = undefined + this.jobEmpty = true + if (this.resultDelivered) this.finish(0) + } + } catch (error) { + void this.runnerFailure(error) + } + } + + private async publishTerminalResult(result: WindowsRunnerResult, exitCode?: number): Promise { + /* 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 !== undefined) { + this.finish(exitCode) + return + } + if (this.jobEmpty) this.finish(0) + } + + private async runnerFailure(error: unknown): Promise { + /* 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: 'runner-error', error: serializeRunnerError(error) }) + this.resultDelivered = true + } catch { + // The disconnected parent observes runner infrastructure failure. + } + } + this.releaseOwnedJob() + this.finish(127) + } + + private releaseOwnedJob(): void { + if (this.pollTimer !== undefined) clearInterval(this.pollTimer) + this.pollTimer = undefined + const api = this.api + if (api === undefined) return + if (this.jobHandle !== undefined) { + try { this.internals.terminateJob(api, this.jobHandle, 1) } catch { /* Continue to kill-on-close. */ } + try { this.internals.closeHandleChecked(api, this.jobHandle, 'ordinary process Job cleanup') } catch { /* Best effort after failure. */ } + this.jobHandle = undefined + } + if (this.processHandle !== undefined) { + try { this.internals.closeHandleChecked(api, this.processHandle, 'ordinary direct process cleanup') } catch { /* Best effort after failure. */ } + this.processHandle = undefined + } + } + + private finish(exitCode: number, disconnect = true): void { + if (this.finished) return + this.finished = true + if (this.pollTimer !== undefined) clearInterval(this.pollTimer) + this.pollTimer = undefined + 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() } } /** - * Publish an infrastructure failure when runner arguments still identify an event file. - * @param argv - original runner arguments. - * @param error - uncaught runner failure. + * Execute the selected Linux bootstrap or Windows Job runner. + * @param selection - Windows sentinel or Linux launch-request locator. + * @param argv - private runner arguments beginning with the target delimiter. + * @param host - process transport and lifecycle host. + * @param internals - native and filesystem operations used by the runner. */ -export function reportSpawnRunnerFailure(argv: string[], error: unknown): void { - try { - const args = parseArgs(argv) - if (args.mode !== 'probe-node' && args.mode !== 'probe-win32') { - appendRunnerEvent(args.eventsPath, { type: 'runner-error', error: serializeSpawnError(error) }) - } - } catch { - // No trustworthy transport remains; the parent reports the missing result. +export async function runSpawnRunner( + selection: string, + argv: readonly string[], + host: RunnerHost = process, + internals: SpawnRunnerInternals = defaultInternals, +): Promise { + Reflect.deleteProperty(host.env, SUBPROCESS_RUNNER_ENV) + const targetArgv = parseRunnerTargetArgv(argv) + if (selection === WINDOWS_RUNNER_SELECTION) { + 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. + */ +export async function reportSpawnRunnerFailure( + selection: string | undefined, + error: unknown, + host: RunnerHost = process, +): Promise { + if (selection === WINDOWS_RUNNER_SELECTION) { + try { await sendMessage(host, { type: 'runner-error', error: serializeRunnerError(error) }) } catch { /* No transport remains. */ } + host.exitCode = 127 + if (host.connected) host.disconnect() + return + } + if (selection !== undefined) { + try { + const files: LinuxLaunchFiles = linuxLaunchFilesFromLocator(selection) + writeLinuxStartupError(files, { type: 'runner-error', error: serializeRunnerError(error) }) + } catch { + // The parent will report an unconsumed request or missing runner result. + } + } + host.exitCode = 127 } diff --git a/packages/subprocess/subprocess-local/src/spawn.ts b/packages/subprocess/subprocess-local/src/spawn.ts index 62ed6d24f2..deaf77d2e6 100644 --- a/packages/subprocess/subprocess-local/src/spawn.ts +++ b/packages/subprocess/subprocess-local/src/spawn.ts @@ -59,6 +59,10 @@ export interface SpawnInternals { platform?: NodeJS.Platform /** Linux process-group member probe (defaults to `/proc` inspection). */ linuxProcessGroupHasLiveMembers?: (processGroupId: number) => boolean | undefined + /** Test seam for the per-spawn Linux native prerequisite check. */ + linuxNativeAvailable?: () => boolean + /** Test seam for the per-spawn Windows native prerequisite check. */ + windowsNativeAvailable?: () => boolean } /** @@ -416,6 +420,10 @@ function fallbackOwner( })() await observation }, + terminateForHostExit: () => { + if (stopped) return + signalTree(platform, pid, 'SIGKILL', child, taskkill) + }, } } @@ -489,6 +497,9 @@ export function bindManagedProcess( if (graceTimer !== undefined) clearTimeout(graceTimer) graceTimer = undefined spec.signal?.removeEventListener('abort', onAbort) + if (launch.owner.cleanup !== undefined) { + queueMicrotask(() => { void done.finally(() => { launch.owner.cleanup?.() }).catch(() => {}) }) + } })().catch((error: unknown) => { rangeExitObservation = undefined throw error @@ -496,30 +507,35 @@ export function bindManagedProcess( return rangeExitObservation } - const kill = (sig: 'SIGTERM' | 'SIGKILL'): void => { + const kill = (sig: 'SIGTERM' | 'SIGKILL', cancellationReason?: unknown): void => { if (rangeExitObserved) return - launch.owner.signal(sig) + launch.owner.signal(sig, cancellationReason) } - const terminate = (): void => { + const terminateWithReason = (cancellationReason: unknown): void => { if (rangeExitObserved || graceTimer !== undefined) return // Keep the shared observation rejection available to waitForExit() without // leaking an unhandled rejection when a caller only invokes terminate(). void observeRangeExit().catch(() => {}) - kill('SIGTERM') + kill('SIGTERM', cancellationReason) graceTimer = setTimeout(() => { graceTimer = undefined kill('SIGKILL') }, spec.graceMs) } + const terminate = (): void => { + terminateWithReason(new Error('subprocess terminated before target start')) + } + const terminateForHostExit = (): void => { - kill('SIGKILL') + launch.owner.terminateForHostExit() } // The caller owns timeout classification; this layer only reacts to abort. - const onAbort = (): void => { terminate() } + const onAbort = (): void => { terminateWithReason(spec.signal?.reason) } spec.signal?.addEventListener('abort', onAbort, { once: true }) + if (spec.signal?.aborted === true) onAbort() // Batch stdin is written and closed up front; process exit and captured // output remain authoritative, so write errors (EPIPE) are best-effort. @@ -539,6 +555,17 @@ export function bindManagedProcess( cleanup() resolve(outcome) } + const fail = (error: unknown): void => { + if (settled) return + settled = true + terminate() + stopCollectors() + cleanup() + /* v8 ignore next -- managed launch promises reject with Error instances. */ + const failure = error instanceof Error ? error : new Error(String(error)) + reject(failure) + } + void launch.infrastructureFailure?.catch(fail) launch.direct.then((outcome) => { if (stdoutClosed === undefined && stderrClosed === undefined) { settle(outcome) @@ -546,15 +573,7 @@ export function bindManagedProcess( } pipeDrainTimer = setTimeout(() => { settle(outcome) }, spec.graceMs) void outputStreamsClosed.then(() => { settle(outcome) }) - }, (error: unknown) => { - /* v8 ignore next -- one Promise cannot reject after its fulfillment path has settled this handle. */ - if (settled) return - settled = true - terminate() - stopCollectors() - cleanup() - reject(error instanceof Error ? error : new Error(String(error))) - }) + }, fail) function cleanup(): void { // graceTimer deliberately NOT cleared: forced termination must still // reach range survivors after the spawned command settles. @@ -568,7 +587,6 @@ export function bindManagedProcess( } return { - get pid() { return launch.pid }, /* v8 ignore start -- pipe-mode streams exist on every conforming launch; the null-coalesces guard an internal adapter defect only. */ stdin: stdinMode === 'pipe' ? stdin ?? undefined : undefined, @@ -620,7 +638,6 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter stdin: child.stdin, stdout: child.stdout, stderr: child.stderr, - pid, direct, owner, }, binding) diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts index 81f059d5b5..10025f11e4 100644 --- a/packages/subprocess/subprocess-local/src/terminal.ts +++ b/packages/subprocess/subprocess-local/src/terminal.ts @@ -60,6 +60,8 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle { private readonly graceMs: number, private readonly platform: NodeJS.Platform = process.platform, private readonly managedOwner?: BoundProcessOwner, + private readonly resolveManagedOutcome?: (outcome: SubprocessOutcome) => SubprocessOutcome, + private readonly cleanupManagedProtocol?: () => void, ) { this.pid = terminal.pid this.rootIdentity = inspector.processTree(this.pid).find(member => member.pid === this.pid) @@ -69,10 +71,15 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle { if (this.exited) return this.exited = true this.output.end() - this.outcome.resolve({ + const outcome = { exitCode: exitSignal === undefined || exitSignal === 0 ? exitCode : null, signal: signalName(exitSignal), - }) + } + try { + this.outcome.resolve(this.resolveManagedOutcome?.(outcome) ?? outcome) + } catch (error) { + this.outcome.reject(error) + } }) } @@ -138,13 +145,10 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle { * event. This does not claim quiescence and does not replace terminate(). */ terminateForHostExit(): void { - if (this.managedOwner !== undefined) { - this.managedOwner.signal('SIGKILL') - return - } this.forceStopDescendants() this.forceStopShell() this.forceStopDescendants() + this.managedOwner?.terminateForHostExit() } private forceStopShell(): void { @@ -304,9 +308,13 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle { private async closeOnce(): Promise { if (this.managedOwner !== undefined) { - await this.closeManagedRange(this.managedOwner) - this.dataDisposable.dispose() - this.exitDisposable.dispose() + try { + await this.closeManagedRange(this.managedOwner) + this.dataDisposable.dispose() + this.exitDisposable.dispose() + } finally { + void this.done.finally(() => { this.cleanupManagedProtocol?.() }).catch(() => {}) + } return } let survivors = await this.stopDescendants() diff --git a/packages/subprocess/subprocess-local/src/windows-job.ts b/packages/subprocess/subprocess-local/src/windows-job.ts index 965d035e22..db6c1094b7 100644 --- a/packages/subprocess/subprocess-local/src/windows-job.ts +++ b/packages/subprocess/subprocess-local/src/windows-job.ts @@ -1,152 +1,209 @@ -/** Windows Job runner launch and managed-range ownership. */ +/** Windows parent-side launch and ownership for the private Job runner. */ -import { spawn, spawnSync } from 'node:child_process' -import { randomUUID } from 'node:crypto' -import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' -import type { BoundProcessOwner, ManagedProcessLaunch } from './managed-owner.ts' -import { observeChildLifecycle } from './managed-owner.ts' -import { childEnv } from './spawn.ts' +import { spawn } from 'node:child_process' +import type { SubprocessOutcome, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' import { - cleanupAfterRunner, - type RunnerInvocation, - runnerDirectResult, - runnerFiles, + loadWin32ProcessBindings, + probeCurrentTokenJobSupport, +} from '@deepseek-ai/dsh-win32-process' +import type { BoundProcessOwner, ManagedProcessLaunch } from './managed-owner.ts' +import { + deserializeRunnerError, + parseWindowsRunnerResult, +} from './runner-protocol.ts' +import type { WindowsStartRequest } from './runner-protocol.ts' +import { + runnerEnvironment, + runnerInvocationAvailable, + runnerStdio, spawnRunnerInvocation, + WINDOWS_RUNNER_SELECTION, } from './runner-launch.ts' -import { cleanupRunnerFiles } from './runner-protocol.ts' -import { createWindowsStdioBridge } from './windows-stdio.ts' +import type { RunnerInvocation } from './runner-launch.ts' -/** Test seams for the runner process. */ +/** Test seams for runner launch and dynamic capability checks. */ export interface WindowsJobInternals { spawn?: typeof spawn - spawnSync?: typeof spawnSync runnerInvocation?: RunnerInvocation + resolveRunnerInvocation?: () => RunnerInvocation + runnerAvailable?: (invocation: RunnerInvocation) => boolean + loadWin32ProcessBindings?: typeof loadWin32ProcessBindings + probeCurrentTokenJobSupport?: typeof probeCurrentTokenJobSupport +} + +type RunnerProcess = Omit, 'send'> & { + send?: ReturnType['send'] } /** - * Confirm in a separate process that shared Win32 bindings and the runner entry are available. - * @param internals - injected process runners used by tests. - * @returns true when native launch can be selected before a user command. + * Re-check the runner entry, bindings, and current Job capability for every spawn. + * @param internals - optional runner and Win32 capability seams used by tests. + * @returns whether the Windows native containment path is currently available. */ export function probeWindowsJob(internals: WindowsJobInternals = {}): boolean { - const invocation = internals.runnerInvocation ?? spawnRunnerInvocation() - const [command, ...prefix] = invocation - const result = (internals.spawnSync ?? spawnSync)(command, [...prefix, '--mode', 'probe-win32'], { - env: childEnv(), - stdio: 'ignore', - timeout: 5_000, - }) - return result.error === undefined && result.status === 0 + try { + const invocation = internals.runnerInvocation + ?? (internals.resolveRunnerInvocation ?? spawnRunnerInvocation)() + if (!(internals.runnerAvailable ?? runnerInvocationAvailable)(invocation)) return false + const api = (internals.loadWin32ProcessBindings ?? loadWin32ProcessBindings)() + ;(internals.probeCurrentTokenJobSupport ?? probeCurrentTokenJobSupport)(api) + return true + } catch { + return false + } } class WindowsJobOwner implements BoundProcessOwner { - private stopped = false - private runnerClosed = false - private readonly observation: Promise + private cancellationReason: unknown + private terminationSent = false constructor( - private readonly runner: ReturnType, + private readonly runner: RunnerProcess, + private readonly exited: Promise, + private readonly failInfrastructure: (error: Error) => void, ) { - this.observation = new Promise((resolve, reject) => { - runner.once('close', (exitCode, signal) => { - this.runnerClosed = true - if (this.runner.pid === undefined || (exitCode === 0 && signal === null)) { - this.stopped = true - resolve() - return - } - const status = signal !== null - ? `signal ${signal}` - : exitCode === null - ? 'without an exit status' - : `exit code ${String(exitCode)}` - reject(new Error( - `subprocess-local: Windows Job runner exited with ${status} before proving its managed range empty`, - )) - }) - }) - void this.observation.catch(() => {}) + void this.exited.catch(() => {}) } - signal(_signal: 'SIGTERM' | 'SIGKILL'): void { - if (this.stopped || this.runnerClosed || this.runner.pid === undefined) return - // The runner handles an IPC disconnect as termination and disconnects itself - // after its Win32 cleanup path. Its close status reports whether the Job is empty. - if (!this.runner.connected) return + signal(_signal: 'SIGTERM' | 'SIGKILL', cancellationReason?: unknown): void { + if (this.cancellationReason === undefined) this.cancellationReason = cancellationReason + if (this.terminationSent || !this.runner.connected) return + this.terminationSent = true try { - this.runner.send({ type: 'terminate' }, (error) => { - if (error !== null && this.runner.connected) this.runner.kill() + this.runner.send?.({ type: 'terminate' }, (error) => { + if (error === null) return + this.failInfrastructure(error) + this.terminateForHostExit() }) - } catch { - // oxlint-disable-next-line typescript/no-unnecessary-condition -- ChildProcess.send() may synchronously disconnect before throwing. - if (this.runner.connected) this.runner.kill() + } catch (error) { + this.failInfrastructure(error instanceof Error ? error : new Error(String(error))) + this.terminateForHostExit() } } + startCancellationReason(): unknown { + return this.cancellationReason ?? new Error('subprocess target start was cancelled') + } + async waitForExit(): Promise { - if (this.stopped) return - await this.observation + await this.exited + } + + terminateForHostExit(): void { + try { this.runner.kill('SIGKILL') } catch { /* Host exit continues with other live runners. */ } } } /** - * Launch one direct command through the Job-owning runner. - * @param spec - exact target argv, cwd, stdio, environment, and lifecycle settings. - * @param internals - injected process runner used by tests. - * @returns parent-owned streams, target outcome, and the bound Job owner. + * Launch one target through a runner that uniquely owns its Job handle. + * @param spec - ordinary target request. + * @param targetEnv - validated complete target environment. + * @param internals - optional runner launch seams used by tests. + * @returns direct streams, result, and runner-owned managed range. */ export function launchWindowsJob( spec: SubprocessSpawnSpec, + targetEnv: Record, internals: WindowsJobInternals = {}, ): ManagedProcessLaunch { - const run = internals.spawn ?? spawn const invocation = internals.runnerInvocation ?? spawnRunnerInvocation() const [command, ...prefix] = invocation - const files = runnerFiles(spec) - let stdio: ReturnType - try { - stdio = createWindowsStdioBridge( - spec, - `\\\\.\\pipe\\dsh-subprocess-${String(process.pid)}-${randomUUID()}`, - ) - } catch (error) { - cleanupRunnerFiles(files) - throw error + const child: RunnerProcess = (internals.spawn ?? spawn)(command, [ + ...prefix, + '--', + ...spec.argv, + ], { + cwd: process.cwd(), + env: runnerEnvironment(WINDOWS_RUNNER_SELECTION), + stdio: runnerStdio(spec, true), + }) + + const direct = Promise.withResolvers() + const infrastructure = Promise.withResolvers() + const rangeExit = Promise.withResolvers() + let resultSeen = false + let infrastructureFailed = false + const failInfrastructure = (error: Error): void => { + if (infrastructureFailed) return + infrastructureFailed = true + infrastructure.reject(error) } - let child: ReturnType + void infrastructure.promise.catch(() => {}) + + const owner = new WindowsJobOwner(child, rangeExit.promise, failInfrastructure) + child.on('message', (value: unknown) => { + if (resultSeen) { + const error = new Error('subprocess-local: Windows runner emitted more than one direct result') + failInfrastructure(error) + owner.terminateForHostExit() + return + } + let result: ReturnType + try { + result = parseWindowsRunnerResult(value) + } catch (error) { + /* v8 ignore next -- the closed parser raises Error instances for every malformed shape; + * conversion only defends future internal regressions. */ + const failure = error instanceof Error ? error : new Error(String(error)) + failInfrastructure(failure) + owner.terminateForHostExit() + return + } + resultSeen = true + if (result.type === 'target-exit') { + direct.resolve({ exitCode: result.exitCode, signal: result.signal }) + } else if (result.type === 'start-cancelled') { + direct.reject(owner.startCancellationReason()) + } else { + direct.reject(deserializeRunnerError(result.error)) + } + }) + child.once('error', (error) => { + failInfrastructure(error) + direct.reject(error) + rangeExit.reject(error) + }) + child.once('close', (exitCode, signal) => { + const clean = exitCode === 0 && signal === null && resultSeen && !infrastructureFailed + if (clean) { + rangeExit.resolve() + return + } + const status = signal !== null + ? `signal ${signal}` + : exitCode === null + ? 'without an exit status' + : `exit code ${String(exitCode)}` + const error = new Error( + `subprocess-local: Windows Job runner exited with ${status} before proving its managed range empty`, + ) + failInfrastructure(error) + if (!resultSeen) direct.reject(error) + rangeExit.reject(error) + }) + + const start: WindowsStartRequest = { type: 'start', cwd: spec.cwd, env: targetEnv } try { - child = run(command, [ - ...prefix, - '--mode', - 'win32', - '--request', - files.requestPath, - '--events', - files.eventsPath, - ...stdio.runnerArgs, - ], { - env: childEnv(), - stdio: stdio.runnerStdio, + if (child.send === undefined) throw new Error('subprocess-local: Windows runner has no IPC channel') + child.send(start, (error) => { + if (error === null) return + failInfrastructure(error) + direct.reject(error) + owner.terminateForHostExit() }) } catch (error) { - stdio.dispose() - cleanupRunnerFiles(files) - throw error + const failure = error instanceof Error ? error : new Error(String(error)) + failInfrastructure(failure) + direct.reject(failure) + owner.terminateForHostExit() } - const lifecycle = observeChildLifecycle(child) - const result = runnerDirectResult(child, files, lifecycle.exited) - const owner = new WindowsJobOwner(child) - void result.direct.then( - () => { stdio.closeInput() }, - () => { stdio.dispose() }, - ) - cleanupAfterRunner(files, result.direct, lifecycle.closed) + return { - stdin: stdio.stdin, - stdout: stdio.stdout, - stderr: stdio.stderr, - get pid() { return result.pid }, - direct: result.direct, + stdin: child.stdin, + stdout: child.stdout, + stderr: child.stderr, + direct: direct.promise, owner, + infrastructureFailure: infrastructure.promise, } } diff --git a/packages/subprocess/subprocess-local/src/windows-stdio.ts b/packages/subprocess/subprocess-local/src/windows-stdio.ts deleted file mode 100644 index 79037ee86b..0000000000 --- a/packages/subprocess/subprocess-local/src/windows-stdio.ts +++ /dev/null @@ -1,143 +0,0 @@ -/** Parent-owned named-pipe streams for one Windows native launch. */ - -import type { StdioOptions } from 'node:child_process' -import { createServer } from 'node:net' -import type { Server, Socket } from 'node:net' -import { PassThrough } from 'node:stream' -import type { Readable, Writable } from 'node:stream' -import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' - -interface PipeEndpoint { - readonly path: string - readonly stream: PassThrough - dispose(): void -} - -/** Streams and runner arguments for one Windows launch. */ -export interface WindowsStdioBridge { - readonly stdin: Writable | null - readonly stdout: Readable | null - readonly stderr: Readable | null - readonly runnerArgs: string[] - readonly runnerStdio: StdioOptions - closeInput(): void - dispose(): void -} - -function closeServer(server: Server): void { - try { - server.close() - } catch { - // A listen failure or an already-accepted connection can close first. - } -} - -function createEndpoint(path: string, direction: 'input' | 'output'): PipeEndpoint { - const stream = new PassThrough() - let socket: Socket | undefined - let disposed = false - const server = createServer({ allowHalfOpen: true }) - // Direct-result failure remains authoritative for setup errors. Keep stream - // errors observable without allowing an early server failure to go unhandled. - /* v8 ignore next -- exercised only when the OS listener or socket reports an asynchronous fault. */ - stream.on('error', () => {}) - /* v8 ignore next -- platform-specific listen failures are reported asynchronously. */ - server.once('error', (error) => { stream.destroy(error) }) - server.once('connection', (connection) => { - /* v8 ignore start -- dispose racing an already-queued OS accept is not deterministic in unit tests. */ - if (disposed) { - connection.destroy() - return - } - /* v8 ignore stop */ - socket = connection - closeServer(server) - /* v8 ignore next -- exercised only by an asynchronous OS socket fault. */ - connection.once('error', (error) => { stream.destroy(error) }) - stream.once('close', () => { connection.destroy() }) - if (direction === 'output') { - connection.once('end', () => { connection.end() }) - connection.pipe(stream) - } else { - connection.resume() - stream.pipe(connection) - connection.once('close', () => { stream.destroy() }) - } - }) - try { - server.listen(path) - /* v8 ignore start -- the production path always supplies a validated short pipe name. */ - } catch (error) { - stream.destroy() - closeServer(server) - throw error - } - /* v8 ignore stop */ - return { - path, - stream, - dispose() { - disposed = true - closeServer(server) - socket?.destroy() - stream.destroy() - }, - } -} - -/** - * Create private parent-owned streams whose peer handles are opened by the Windows runner. - * @param spec - target stdio dispositions. - * @param basePath - unique named-pipe base chosen by the launch owner. - * @returns public streams, runner arguments, and cleanup for pre-start failure. - */ -export function createWindowsStdioBridge( - spec: SubprocessSpawnSpec, - basePath: string, -): WindowsStdioBridge { - const endpoints: PipeEndpoint[] = [] - let stdin: PipeEndpoint | undefined - let stdout: PipeEndpoint | undefined - let stderr: PipeEndpoint | undefined - try { - if (spec.stdio.stdin !== 'ignore') { - stdin = createEndpoint(`${basePath}-stdin`, 'input') - endpoints.push(stdin) - } - if (spec.stdio.stdout !== 'inherit') { - stdout = createEndpoint(`${basePath}-stdout`, 'output') - endpoints.push(stdout) - } - if (spec.stdio.stderr !== 'inherit') { - stderr = createEndpoint(`${basePath}-stderr`, 'output') - endpoints.push(stderr) - } - /* v8 ignore start -- only a synchronous Node listener-construction failure reaches this rollback. */ - } catch (error) { - for (const endpoint of endpoints) endpoint.dispose() - throw error - } - /* v8 ignore stop */ - return { - stdin: stdin?.stream ?? null, - stdout: stdout?.stream ?? null, - stderr: stderr?.stream ?? null, - runnerArgs: [ - ...stdin === undefined ? [] : ['--stdin-pipe', stdin.path], - ...stdout === undefined ? [] : ['--stdout-pipe', stdout.path], - ...stderr === undefined ? [] : ['--stderr-pipe', stderr.path], - ], - runnerStdio: [ - 'ignore', - spec.stdio.stdout === 'inherit' ? 'inherit' : 'ignore', - spec.stdio.stderr === 'inherit' ? 'inherit' : 'ignore', - 'ipc', - ], - closeInput() { - stdin?.dispose() - }, - dispose() { - for (const endpoint of endpoints) endpoint.dispose() - }, - } -} diff --git a/packages/subprocess/subprocess-local/tests/fixtures/fake-job-runner.ts b/packages/subprocess/subprocess-local/tests/fixtures/fake-job-runner.ts deleted file mode 100644 index 88d9e282e3..0000000000 --- a/packages/subprocess/subprocess-local/tests/fixtures/fake-job-runner.ts +++ /dev/null @@ -1,33 +0,0 @@ -import { appendRunnerEvent, consumeRunnerRequest } from '../../src/runner-protocol.ts' - -const args = process.argv.slice(2) -const requestPath = args[args.indexOf('--request') + 1] as string -const eventsPath = args[args.indexOf('--events') + 1] as string -const request = consumeRunnerRequest(requestPath) -appendRunnerEvent(eventsPath, { type: 'started', pid: process.pid }) - -const configuredExit = Number(request.argv[1]) -// Events carry target results; zero means the runner completed its own observation. -if (Number.isSafeInteger(configuredExit)) { - setTimeout(() => { - appendRunnerEvent(eventsPath, { type: 'exit', exitCode: configuredExit, signal: null }) - process.exitCode = 0 - }, 10) -} else { - const hold = setInterval(() => {}, 1_000) - let terminated = false - const terminate = (): void => { - if (terminated) return - terminated = true - appendRunnerEvent(eventsPath, { type: 'exit', exitCode: 1, signal: null }) - clearInterval(hold) - setImmediate(() => { - if (process.connected) process.disconnect() - }) - process.exitCode = 0 - } - process.on('message', (message: unknown) => { - if (message !== null && typeof message === 'object' && (message as { type?: unknown }).type === 'terminate') terminate() - }) - process.on('disconnect', terminate) -} diff --git a/packages/subprocess/subprocess-local/tests/linux-scope.spec.ts b/packages/subprocess/subprocess-local/tests/linux-scope.spec.ts index ae25749d10..356b4f5e9c 100644 --- a/packages/subprocess/subprocess-local/tests/linux-scope.spec.ts +++ b/packages/subprocess/subprocess-local/tests/linux-scope.spec.ts @@ -1,561 +1,455 @@ -import { spawn, spawnSync } from 'node:child_process' -import { existsSync } from 'node:fs' -import { dirname } from 'node:path' -import { describe, expect, it, vi } from 'vitest' -import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' +import { EventEmitter } from 'node:events' +import { existsSync, rmSync, unlinkSync, writeFileSync } from 'node:fs' +import { PassThrough } from 'node:stream' +import { afterEach, describe, expect, it, vi } from 'vitest' import { launchLinuxScope, prepareLinuxTerminalScope, - probeLinuxRunner, + probeLinuxBootstrap, + probeLinuxNative, probeLinuxScope, probeLinuxUserManager, } from '../src/linux-scope.ts' -import { spawnRunnerInvocation } from '../src/runner-launch.ts' +import type { LinuxScopeInternals } from '../src/linux-scope.ts' +import { + consumeLinuxLaunchRequest, + linuxLaunchFilesFromLocator, + writeLinuxStartupError, +} from '../src/runner-protocol.ts' +import { SUBPROCESS_RUNNER_ENV } from '../src/runner-launch.ts' -function spec(argv: string[]): SubprocessSpawnSpec { +const childProcessMocks = vi.hoisted(() => ({ + execFile: vi.fn(), + spawn: vi.fn(), + spawnSync: vi.fn(), +})) + +vi.mock('node:child_process', async (importOriginal) => { + const actual = await importOriginal() return { - argv, - cwd: process.cwd(), - stdio: { stdin: 'ignore', stdout: { maxBytes: 1024 }, stderr: { maxBytes: 1024 } }, + ...actual, + execFile: childProcessMocks.execFile as unknown as typeof actual.execFile, + spawn: childProcessMocks.spawn as typeof actual.spawn, + spawnSync: childProcessMocks.spawnSync as typeof actual.spawnSync, + } +}) + +class FakeChild extends EventEmitter { + pid: number | undefined = 321 + exitCode: number | null = null + signalCode: NodeJS.Signals | null = null + stdin = new PassThrough() + stdout = new PassThrough() + stderr = new PassThrough() + kills: NodeJS.Signals[] = [] + + kill(signal: NodeJS.Signals): boolean { + this.kills.push(signal) + return true + } + + exit(exitCode: number | null, signal: NodeJS.Signals | null): void { + this.exitCode = exitCode + this.signalCode = signal + this.emit('exit', exitCode, signal) + } +} + +const directories: string[] = [] + +afterEach(() => { + for (const directory of directories.splice(0)) { + rmSync(directory, { recursive: true, force: true }) + } + vi.restoreAllMocks() + childProcessMocks.execFile.mockReset() + childProcessMocks.spawn.mockReset() + childProcessMocks.spawnSync.mockReset() +}) + +function missingUnit() { + return { status: 1, stdout: '', stderr: 'Unit dsh.scope could not be found.' } +} + +function activeUnit(state = 'active') { + return { status: 0, stdout: `${state}\n`, stderr: '' } +} + +function spec() { + return { + argv: ['tool', 'literal arg'], + cwd: '/target', + stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' }, graceMs: 100, - env: { LITERAL_VALUE: '$HOME ${UNCHANGED}' }, - } + env: { TARGET: 'yes' }, + } as const } -function asyncQuery(runSync: typeof spawnSync) { - return async (command: string, args: readonly string[]) => { - const result = runSync(command, [...args], { encoding: 'utf8', timeout: 5_000 }) - return { - status: result.status, - stdout: typeof result.stdout === 'string' ? result.stdout : '', - stderr: typeof result.stderr === 'string' ? result.stderr : '', - ...result.error === undefined ? {} : { error: result.error }, - } - } +function launch( + query: LinuxScopeInternals['systemctlQuery'], + overrides: LinuxScopeInternals = {}, +) { + const child = new FakeChild() + let options: { env?: NodeJS.ProcessEnv; cwd?: string; detached?: boolean } | undefined + const spawn = vi.fn((_command: string, _args: readonly string[], received: typeof options) => { + options = received + return child + }) + const spawnSync = vi.fn(() => ({ status: 0, stdout: '', stderr: '' })) + const systemctlQuery = overrides.systemctlQuery ?? query + const result = launchLinuxScope(spec(), { TARGET: 'yes' }, { + spawn: overrides.spawn ?? spawn as never, + spawnSync: overrides.spawnSync ?? spawnSync as never, + ...systemctlQuery === undefined ? {} : { systemctlQuery }, + systemdRun: overrides.systemdRun ?? '/bin/systemd-run', + systemctl: overrides.systemctl ?? '/bin/systemctl', + runnerInvocation: overrides.runnerInvocation ?? ['/usr/bin/node', '/runner.js'], + ...overrides.runnerAvailable === undefined ? {} : { runnerAvailable: overrides.runnerAvailable }, + ...overrides.execveAvailable === undefined ? {} : { execveAvailable: overrides.execveAvailable }, + }) + const requestPath = options?.env?.[SUBPROCESS_RUNNER_ENV] + if (requestPath === undefined) throw new Error('launch did not publish a request locator') + directories.push(linuxLaunchFilesFromLocator(requestPath).directory) + return { child, result, requestPath, spawn, spawnSync, options } } -describe.skipIf(process.platform === 'win32')('Linux systemd scope adapter', () => { - it('separates the live manager, stable scope, and ordinary-runner probes', () => { - const secretName = 'DSH_SCOPE_TEST_TOKEN' - const previousSecret = process.env[secretName] - process.env[secretName] = 'secret' - const calls: string[][] = [] - const environments: Array = [] - const runSync = vi.fn((command: string, args: readonly string[], options?: { env?: NodeJS.ProcessEnv }) => { - calls.push([command, ...args]) - environments.push(options?.env) - return { status: 0, error: undefined } - }) as unknown as typeof spawnSync - const runnerInvocation: [string, ...string[]] = ['node-runtime', 'runner-entry.js'] - try { - expect(probeLinuxUserManager({ - spawnSync: runSync, - systemctl: 'systemctl', - })).toBe(true) - expect(probeLinuxRunner({ - spawnSync: runSync, - runnerInvocation, - })).toBe(true) - expect(probeLinuxScope({ - spawnSync: runSync, - systemdRun: 'systemd-run', - systemctl: 'systemctl', - })).toBe(true) - expect(calls[0]).toEqual(['systemctl', '--user', 'show-environment']) - expect(calls[1]).toEqual([...runnerInvocation, '--mode', 'probe-node']) - expect(calls[2]).toContain('--expand-environment=no') - expect(calls[2]).not.toContain('--pipe') - expect(calls[2]).not.toContain('--wait') - const unitArg = calls[2]?.find(arg => arg.startsWith('--unit=')) - if (unitArg === undefined) throw new Error('scope probe did not publish its unit') - const separator = calls[2]?.indexOf('--') ?? -1 - expect(calls[2]?.slice(separator + 1)).toEqual([ - 'systemctl', - '--user', - 'show', - `${unitArg.slice('--unit='.length)}.scope`, - '--property=ActiveState', - '--value', - ]) - expect(environments[0]?.LC_ALL).toBe('C') - for (const environment of environments) expect(environment).not.toHaveProperty(secretName) - } finally { - if (previousSecret === undefined) Reflect.deleteProperty(process.env, secretName) - else process.env[secretName] = previousSecret +describe('Linux native capability selection', () => { + it('rechecks bootstrap, user manager, and literal transient-scope support', () => { + const spawnSync = vi.fn(() => ({ status: 0, error: undefined })) + const runnerAvailable = vi.fn(() => true) + const inputs = { + spawnSync: spawnSync as never, + runnerAvailable, + runnerInvocation: ['/usr/bin/node', '/runner.js'] as [string, ...string[]], + execveAvailable: true, + systemdRun: '/bin/systemd-run', + systemctl: '/bin/systemctl', } + expect(probeLinuxNative(inputs)).toBe(true) + expect(probeLinuxNative(inputs)).toBe(true) + expect(runnerAvailable).toHaveBeenCalledTimes(2) + expect(spawnSync).toHaveBeenCalledTimes(4) + expect(probeLinuxBootstrap({ ...inputs, execveAvailable: false })).toBe(false) + }) - const oldSystemd = vi.fn(() => ({ status: 1, error: undefined })) as unknown as typeof spawnSync - expect(probeLinuxScope({ spawnSync: oldSystemd })).toBe(false) + it('reports each failed dynamic prerequisite without executing a target', () => { + expect(probeLinuxUserManager({ + spawnSync: vi.fn(() => ({ status: 1, error: undefined })) as never, + })).toBe(false) expect(probeLinuxScope({ - spawnSync: vi.fn(() => ({ status: 0, error: new Error('scope failed') })) as unknown as typeof spawnSync, + spawnSync: vi.fn(() => ({ status: null, error: new Error('missing') })) as never, })).toBe(false) - - const failedRunner = vi.fn(() => ({ status: 1, error: undefined })) as unknown as typeof spawnSync - expect(probeLinuxRunner({ - spawnSync: failedRunner, - runnerInvocation: ['node-runtime', 'runner-entry.js'], + expect(probeLinuxBootstrap({ + execveAvailable: true, + runnerInvocation: ['/missing'], + runnerAvailable: () => false, })).toBe(false) - expect(failedRunner).toHaveBeenCalledOnce() - expect(probeLinuxRunner({ - spawnSync: vi.fn(() => ({ status: 0, error: new Error('runner failed') })) as unknown as typeof spawnSync, - runnerInvocation: ['node-runtime', 'runner-entry.js'], - })).toBe(false) - - const managerError = new Error('missing user manager') - expect(probeLinuxUserManager({ - spawnSync: vi.fn(() => ({ error: managerError })) as unknown as typeof spawnSync, - })).toBe(false) - expect(probeLinuxUserManager({ - spawnSync: vi.fn(() => ({ status: 1, error: undefined })) as unknown as typeof spawnSync, + expect(probeLinuxBootstrap({ + execveAvailable: true, + resolveRunnerInvocation: () => { throw new Error('runner resolution failed') }, })).toBe(false) }) - it('removes private runner files when systemd-run throws synchronously', () => { - const failure = new Error('systemd-run threw') - let requestPath: string | undefined - const run = vi.fn((_command: string, args: readonly string[]) => { - const requestIndex = args.indexOf('--request') - requestPath = args[requestIndex + 1] - throw failure - }) as unknown as typeof spawn + it('uses the default command adapters and runner resolution', () => { + childProcessMocks.spawnSync.mockReturnValue({ status: 0, error: undefined }) + expect(probeLinuxUserManager()).toBe(true) + expect(probeLinuxScope()).toBe(true) + expect(childProcessMocks.spawnSync).toHaveBeenCalledTimes(2) + expect(probeLinuxBootstrap({ execveAvailable: true })).toBe(true) + expect(probeLinuxBootstrap({ + runnerInvocation: [process.execPath], + runnerAvailable: () => true, + })).toBe(typeof process.execve === 'function') + }) +}) - expect(() => launchLinuxScope(spec([process.execPath, '-e', '']), { - spawn: run, - runnerInvocation: spawnRunnerInvocation(), - })).toThrow(failure) - expect(requestPath).toBeDefined() - expect(existsSync(dirname(requestPath as string))).toBe(false) +describe('Linux scope establishment and quiescence', () => { + it('does not mistake pre-establishment unit absence for quiescence and rejects after cancellation', async () => { + const { child, result, requestPath, spawnSync } = launch(async () => missingUnit()) + const waiting = result.owner.waitForExit() + result.owner.signal('SIGTERM') + expect(child.kills).toEqual(['SIGTERM']) + expect(spawnSync).toHaveBeenCalledWith('/bin/systemctl', expect.arrayContaining([ + 'kill', '--kill-whom=all', '--signal=SIGTERM', + ]), expect.anything()) + const direct = expect(result.direct).rejects.toThrow('before its bootstrap consumed') + child.exit(null, 'SIGTERM') + await direct + await expect(waiting).rejects.toThrow('ended before consuming its launch request') + expect(existsSync(requestPath)).toBe(true) + result.owner.cleanup?.() }) - it('wraps terminal argv literally and binds signalling and observation to the same scope', async () => { - const signalCalls: Array<[string, readonly string[]]> = [] - const queryCalls: Array<[string, readonly string[]]> = [] - const runSync = vi.fn((command: string, args: readonly string[]) => { - signalCalls.push([command, args]) - return { status: 0, stdout: '', stderr: '', error: undefined } - }) as unknown as typeof spawnSync - const query = vi.fn(async (command: string, args: readonly string[]) => { - queryCalls.push([command, args]) - return { status: 0, stdout: 'inactive\n', stderr: '' } - }) - const argv = ['/bin/bash', '-c', 'printf "%s" "$HOME"'] - const launch = prepareLinuxTerminalScope(argv, { - spawnSync: runSync, - systemdRun: '/usr/bin/systemd-run', - systemctl: '/usr/bin/systemctl', - systemctlQuery: query, - }) - const unitArg = launch.args.find(arg => arg.startsWith('--unit=')) - if (unitArg === undefined) throw new Error('terminal scope did not publish its unit') - const unit = `${unitArg.slice('--unit='.length)}.scope` + it('accepts request consumption followed by rapid --collect unload as stopped', async () => { + const states = [activeUnit(), missingUnit()] + const { child, result, requestPath } = launch(async () => states.shift() ?? missingUnit()) + expect(consumeLinuxLaunchRequest(requestPath)).toEqual({ cwd: '/target', env: { TARGET: 'yes' } }) + const waiting = result.owner.waitForExit() + child.exit(0, null) + await expect(result.direct).resolves.toEqual({ exitCode: 0, signal: null }) + await expect(waiting).resolves.toBeUndefined() + result.owner.signal('SIGKILL') + result.owner.cleanup?.() + expect(existsSync(linuxLaunchFilesFromLocator(requestPath).directory)).toBe(false) + }) - expect(launch.command).toBe('/usr/bin/systemd-run') - expect(launch.args.slice(0, -argv.length)).toEqual([ - '--user', - '--scope', - '--quiet', - '--collect', - '--expand-environment=no', - unitArg, - '--', - ]) - expect(launch.args.slice(-argv.length)).toEqual(argv) + it('uses manager-observed unit existence as establishment proof', async () => { + const { child, result } = launch(async () => activeUnit('inactive')) + await expect(result.owner.waitForExit()).resolves.toBeUndefined() + child.exit(1, null) + await expect(result.direct).rejects.toThrow('before its bootstrap consumed') + result.owner.cleanup?.() + }) - const owner = launch.bindOwner(() => false) - owner.signal('SIGTERM') - owner.signal('SIGKILL') - await owner.waitForExit() + it('keeps waiting while the unit is absent and the direct launcher is still running', async () => { + const states = [missingUnit(), activeUnit('inactive')] + const { child, result } = launch(async () => states.shift() ?? activeUnit('inactive')) + await expect(result.owner.waitForExit()).resolves.toBeUndefined() + child.exit(1, null) + await expect(result.direct).rejects.toThrow('before its bootstrap consumed') + result.owner.cleanup?.() + }) - expect(signalCalls).toEqual([ - [ - '/usr/bin/systemctl', - ['--user', 'kill', '--kill-whom=all', '--signal=SIGTERM', unit], - ], - [ - '/usr/bin/systemctl', - ['--user', 'kill', '--kill-whom=all', '--signal=SIGKILL', unit], - ], - ]) - expect(queryCalls).toEqual([[ - '/usr/bin/systemctl', - ['--user', 'show', unit, '--property=ActiveState', '--value'], - ]]) + it('reports child termination before request consumption to both result and wait', async () => { + const { child, result } = launch(async () => missingUnit()) + child.exit(127, null) + await expect(result.direct).rejects.toThrow('before its bootstrap consumed') + await expect(result.owner.waitForExit()).rejects.toThrow('ended before consuming its launch request') + result.owner.cleanup?.() }) - it('keeps user argv out of systemd-run and reports the direct target outcome', async () => { - let wrapper: ReturnType | undefined - let systemdArgs: readonly string[] = [] - const run = vi.fn((_command: string, args: readonly string[], options: Parameters[2]) => { - systemdArgs = args - const separator = args.indexOf('--') - const command = args[separator + 1] as string - wrapper = spawn(command, args.slice(separator + 2), options) - return wrapper - }) as unknown as typeof spawn - const runSyncMock = vi.fn((command: string, args: readonly string[]) => { - if (command === 'systemctl' && args[1] === 'show') { - const active = wrapper?.exitCode === null && wrapper.signalCode === null - return { status: 0, stdout: active ? 'active\n' : 'inactive\n', stderr: '', error: undefined } - } - return { status: 0, stdout: '', stderr: '', error: undefined } + it('reconstructs a pre-exec startup error instead of exposing bootstrap exit 127', async () => { + const { child, result, requestPath } = launch(async () => missingUnit()) + const files = linuxLaunchFilesFromLocator(requestPath) + unlinkSync(requestPath) + writeLinuxStartupError(files, { + type: 'spawn-error', + error: { name: 'Error', message: 'spawn tool ENOENT', code: 'ENOENT' }, }) - const runSync = runSyncMock as unknown as typeof spawnSync - const launch = launchLinuxScope(spec([process.execPath, '-e', 'process.exit(9)', 'literal $VALUE']), { - spawn: run, - spawnSync: runSync, - systemctlQuery: asyncQuery(runSync), - runnerInvocation: spawnRunnerInvocation(), + child.exit(127, null) + await expect(result.direct).rejects.toMatchObject({ code: 'ENOENT' }) + result.owner.cleanup?.() + }) + + it('retries a failed state query and rejects unknown states or failed final kills', async () => { + const query = vi.fn() + .mockResolvedValueOnce({ status: null, stdout: '', stderr: '', error: new Error('query failed') }) + .mockResolvedValueOnce(missingUnit()) + const { result, requestPath } = launch(query) + unlinkSync(requestPath) + await expect(result.owner.waitForExit()).rejects.toThrow('query failed') + await expect(result.owner.waitForExit()).resolves.toBeUndefined() + result.owner.cleanup?.() + + const unknown = launch(async () => activeUnit('mystery')) + await expect(unknown.result.owner.waitForExit()).rejects.toThrow('unknown ActiveState') + unknown.result.owner.cleanup?.() + + const killFailed = launch(async () => activeUnit(), { + spawnSync: vi.fn(() => ({ status: 1, stdout: '', stderr: 'permission denied' })) as never, }) - await expect(launch.direct).resolves.toEqual({ exitCode: 9, signal: null }) - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - const callsBeforeStaleSignal = runSyncMock.mock.calls.length - launch.owner.signal('SIGKILL') - expect(runSyncMock).toHaveBeenCalledTimes(callsBeforeStaleSignal) - expect(systemdArgs).toContain('--expand-environment=no') - expect(systemdArgs).not.toContain('--pipe') - expect(systemdArgs).not.toContain('--wait') - expect(systemdArgs).not.toContain('literal $VALUE') + killFailed.result.owner.signal('SIGKILL') + await expect(killFailed.result.owner.waitForExit()).rejects.toThrow('could not signal') + killFailed.result.owner.cleanup?.() }) - it('uses a scope KILL after the owner proves the range empty', async () => { - let wrapper: ReturnType | undefined - const run = vi.fn((_command: string, args: readonly string[], options: Parameters[2]) => { - const separator = args.indexOf('--') - const command = args[separator + 1] as string - wrapper = spawn(command, args.slice(separator + 2), { ...options, detached: true }) - return wrapper - }) as unknown as typeof spawn - const runSync = vi.fn((command: string, args: readonly string[]) => { - if (command === 'systemctl' && args[1] === 'kill') { - if (args.includes('--signal=SIGTERM')) { - return { status: 1, stdout: '', stderr: 'Unit could not be found', error: undefined } - } - if (wrapper?.pid !== undefined) process.kill(-wrapper.pid, 'SIGKILL') - return { - status: 1, - stdout: '', - stderr: 'Failed to send signal SIGKILL to auxiliary processes: Invalid argument', - error: undefined, - } - } - if (command === 'systemctl' && args[1] === 'show') { - const active = wrapper?.exitCode === null && wrapper.signalCode === null - return { status: 0, stdout: active ? 'active\n' : 'inactive\n', stderr: '', error: undefined } - } - return { status: 0, stdout: '', stderr: '', error: undefined } - }) as unknown as typeof spawnSync - const launch = launchLinuxScope(spec([process.execPath, '-e', 'setInterval(() => {}, 1000)']), { - spawn: run, - spawnSync: runSync, - systemctlQuery: asyncQuery(runSync), - runnerInvocation: spawnRunnerInvocation(), + it('reports command-query failures from the default systemctl adapter', async () => { + childProcessMocks.execFile.mockImplementationOnce((...args: unknown[]) => { + const callback = args.at(-1) as (error: Error | null, stdout: string, stderr: string) => void + callback(null, 'inactive\n', '') + return new EventEmitter() }) - launch.owner.signal('SIGTERM') - launch.owner.signal('SIGKILL') - await expect(launch.direct).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' }) - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() + const stopped = launch(undefined) + await expect(stopped.result.owner.waitForExit()).resolves.toBeUndefined() + stopped.result.owner.cleanup?.() + + const queryError = Object.assign(new Error('systemctl execution failed'), { code: 'ENOENT' }) + childProcessMocks.execFile.mockImplementationOnce((...args: unknown[]) => { + const callback = args.at(-1) as (error: Error | null, stdout: string, stderr: string) => void + callback(queryError, '', '') + return new EventEmitter() + }) + const failed = launch(undefined) + await expect(failed.result.owner.waitForExit()).rejects.toBe(queryError) + failed.result.owner.cleanup?.() }) - it('retries wait after the selected native owner becomes readable again', async () => { - const run = vi.fn((_command: string, args: readonly string[], options: Parameters[2]) => { - const separator = args.indexOf('--') - return spawn(args[separator + 1] as string, args.slice(separator + 2), options) - }) as unknown as typeof spawn - const failure = new Error('Failed to connect to bus: No such file or directory') - const query = vi.fn() - .mockRejectedValueOnce(failure) - .mockResolvedValue({ status: 0, stdout: 'inactive\n', stderr: '' }) - const launch = launchLinuxScope(spec([process.execPath, '-e', 'process.exit(0)']), { - spawn: run, - spawnSync: vi.fn(() => ({ status: 0, stdout: '', stderr: '', error: undefined })) as unknown as typeof spawnSync, - systemctlQuery: query, - runnerInvocation: spawnRunnerInvocation(), + it('keeps signal failures scoped to final kill proof and stays idempotent after stop', async () => { + const spawnSync = vi.fn() + .mockReturnValueOnce({ status: 1, stdout: '', stderr: '' }) + .mockReturnValueOnce({ status: 1, stderr: 'Unit dsh.scope could not be found.' }) + .mockReturnValueOnce({ status: 1, stdout: '', stderr: '' }) + .mockReturnValueOnce({ status: 0, stdout: '', stderr: '' }) + const states = [activeUnit(), activeUnit('failed')] + const launched = launch(async () => states.shift() ?? missingUnit(), { + spawnSync: spawnSync as never, }) - await expect(launch.direct).resolves.toEqual({ exitCode: 0, signal: null }) - await expect(launch.owner.waitForExit()).rejects.toBe(failure) - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - expect(query).toHaveBeenCalledTimes(2) + launched.child.pid = undefined + unlinkSync(launched.requestPath) + launched.result.owner.signal('SIGTERM') + launched.result.owner.signal('SIGKILL') + launched.result.owner.signal('SIGKILL') + launched.result.owner.signal('SIGKILL') + await expect(launched.result.owner.waitForExit()).resolves.toBeUndefined() + await expect(launched.result.owner.waitForExit()).resolves.toBeUndefined() + launched.result.owner.terminateForHostExit() + expect(spawnSync).toHaveBeenCalledTimes(4) + launched.result.owner.cleanup?.() }) - it('clears a failed KILL result after a later KILL succeeds', async () => { - let killed = false - let killAttempts = 0 - const runSync = vi.fn((_command: string, args: readonly string[]) => { - if (args.includes('--signal=SIGKILL')) { - killAttempts += 1 - if (killAttempts === 1) { - return { status: 1, stdout: '', stderr: 'kill failed', error: undefined } - } - killed = true - } - return { status: 0, stdout: '', stderr: '', error: undefined } - }) as unknown as typeof spawnSync - const query = vi.fn(async () => ({ - status: 0, - stdout: killed ? 'inactive\n' : 'active\n', - stderr: '', + it('reports unreadable manager output and a failed kill before establishment', async () => { + const withOutput = launch(async () => ({ + status: 5, stdout: '', stderr: 'permission denied', })) - const launch = prepareLinuxTerminalScope(['/bin/sh'], { - spawnSync: runSync, - systemctlQuery: query, - }) - const owner = launch.bindOwner(() => true) + await expect(withOutput.result.owner.waitForExit()).rejects.toThrow('permission denied') + withOutput.result.owner.cleanup?.() - owner.signal('SIGKILL') - await expect(owner.waitForExit()).rejects.toThrow('kill failed') - owner.signal('SIGKILL') - await expect(owner.waitForExit()).resolves.toBeUndefined() + const withoutOutput = launch(async () => ({ status: null, stdout: '', stderr: '' })) + await expect(withoutOutput.result.owner.waitForExit()).rejects.toThrow('exit null') + withoutOutput.result.owner.cleanup?.() - expect(query).toHaveBeenCalledTimes(2) + const killFailed = launch(async () => missingUnit(), { + spawnSync: vi.fn(() => ({ status: 1, stdout: '', stderr: 'kill denied' })) as never, + }) + vi.spyOn(process, 'kill').mockImplementation(() => { throw new Error('missing process group') }) + killFailed.result.owner.signal('SIGKILL') + await expect(killFailed.result.owner.waitForExit()).rejects.toThrow('kill denied') + killFailed.result.owner.cleanup?.() }) - it('propagates systemctl execution failures and unknown active states', async () => { - const run = vi.fn((_command: string, args: readonly string[], options: Parameters[2]) => { - const separator = args.indexOf('--') - return spawn(args[separator + 1] as string, args.slice(separator + 2), options) - }) as unknown as typeof spawn - const failure = new Error('systemctl execution failed') - const failedRead = launchLinuxScope(spec([process.execPath, '-e', 'process.exit(0)']), { - spawn: run, - spawnSync: vi.fn(() => ({ error: failure })) as unknown as typeof spawnSync, - systemctlQuery: async () => ({ status: null, stdout: '', stderr: '', error: failure }), - runnerInvocation: spawnRunnerInvocation(), - }) - await expect(failedRead.owner.waitForExit()).rejects.toBe(failure) - await expect(failedRead.direct).resolves.toEqual({ exitCode: 0, signal: null }) + it('settles direct outcomes once and reports malformed startup errors', async () => { + const childError = launch(async () => missingUnit()) + const spawnError = new Error('systemd-run failed') + childError.child.emit('error', spawnError) + childError.child.exit(1, null) + await expect(childError.result.direct).rejects.toBe(spawnError) + childError.result.owner.cleanup?.() - const unknownState = launchLinuxScope(spec([process.execPath, '-e', 'process.exit(0)']), { - spawn: run, - spawnSync: vi.fn(() => ({ status: 0, stdout: 'reloading\n', stderr: '', error: undefined })) as unknown as typeof spawnSync, - systemctlQuery: async () => ({ status: 0, stdout: 'reloading\n', stderr: '' }), - runnerInvocation: spawnRunnerInvocation(), - }) - await expect(unknownState.owner.waitForExit()).rejects.toThrow('unknown ActiveState') - await expect(unknownState.direct).resolves.toEqual({ exitCode: 0, signal: null }) + const lateError = launch(async () => missingUnit()) + consumeLinuxLaunchRequest(lateError.requestPath) + lateError.child.exit(0, null) + lateError.child.emit('error', new Error('late child error')) + await expect(lateError.result.direct).resolves.toEqual({ exitCode: 0, signal: null }) + lateError.result.owner.cleanup?.() - const blankFailure = launchLinuxScope(spec([process.execPath, '-e', 'process.exit(0)']), { - spawn: run, - spawnSync: vi.fn(() => ({ status: 1, stdout: '', stderr: '', error: undefined })) as unknown as typeof spawnSync, - systemctlQuery: async () => ({ status: 1, stdout: '', stderr: '' }), - runnerInvocation: spawnRunnerInvocation(), - }) - await expect(blankFailure.owner.waitForExit()).rejects.toThrow('exit 1') - await expect(blankFailure.direct).resolves.toEqual({ exitCode: 0, signal: null }) + const malformed = launch(async () => missingUnit()) + const files = linuxLaunchFilesFromLocator(malformed.requestPath) + unlinkSync(malformed.requestPath) + writeFileSync(files.startupErrorPath, '{', { mode: 0o600 }) + malformed.child.exit(127, null) + await expect(malformed.result.direct).rejects.toBeInstanceOf(SyntaxError) + malformed.result.owner.cleanup?.() }) - it.each(['activating', 'deactivating', 'failed'])( - 'recognizes the %s scope state', - async (initialState) => { - let wrapper: ReturnType | undefined - let reads = 0 - const run = vi.fn((_command: string, args: readonly string[], options: Parameters[2]) => { - const separator = args.indexOf('--') - wrapper = spawn(args[separator + 1] as string, args.slice(separator + 2), options) - return wrapper - }) as unknown as typeof spawn - const runSync = vi.fn(() => { - reads += 1 - return { - status: 0, - stdout: reads === 1 ? `${initialState}\n` : 'inactive\n', - stderr: '', - error: undefined, - } - }) as unknown as typeof spawnSync - const launch = launchLinuxScope(spec([process.execPath, '-e', 'process.exit(0)']), { - spawn: run, - spawnSync: runSync, - systemctlQuery: asyncQuery(runSync), - runnerInvocation: spawnRunnerInvocation(), - }) - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - await expect(launch.direct).resolves.toEqual({ exitCode: 0, signal: null }) - }, - ) + it('does not signal a direct group before the launcher publishes a pid', async () => { + const launched = launch(async () => activeUnit('inactive')) + launched.child.pid = undefined + const processKill = vi.spyOn(process, 'kill') + launched.result.owner.signal('SIGTERM') + expect(processKill).not.toHaveBeenCalled() + expect(launched.child.kills).toEqual([]) + consumeLinuxLaunchRequest(launched.requestPath) + launched.child.exit(0, null) + await expect(launched.result.direct).resolves.toEqual({ exitCode: 0, signal: null }) + launched.result.owner.cleanup?.() + }) - it('uses runner liveness when systemd has already forgotten the scope', async () => { - const run = vi.fn((_command: string, args: readonly string[], options: Parameters[2]) => { - const separator = args.indexOf('--') - return spawn(args[separator + 1] as string, args.slice(separator + 2), options) - }) as unknown as typeof spawn - const runSyncMock = vi.fn(() => ({ - status: 1, - stdout: '', - stderr: 'Unit could not be found', - error: undefined, - })) - const runSync = runSyncMock as unknown as typeof spawnSync - const launch = launchLinuxScope(spec([process.execPath, '-e', 'setTimeout(() => {}, 40)']), { - spawn: run, - spawnSync: runSync, - systemctlQuery: asyncQuery(runSync), - runnerInvocation: spawnRunnerInvocation(), + it('runs direct fallback before the exact synchronous scope kill on host exit', () => { + const events: string[] = [] + const { child, result } = launch(async () => missingUnit(), { + spawnSync: vi.fn(() => { events.push('scope'); return { status: 0 } }) as never, }) - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - await expect(launch.direct).resolves.toEqual({ exitCode: 0, signal: null }) - expect(runSyncMock.mock.calls.length).toBeGreaterThan(1) + child.kill = vi.fn(() => { events.push('direct'); return true }) + vi.spyOn(process, 'kill').mockImplementation(() => { events.push('direct'); return true }) + result.owner.terminateForHostExit() + expect(events).toEqual(['direct', 'scope']) + result.owner.cleanup?.() }) +}) + +describe('Linux PTY bootstrap reuse', () => { + const terminalSpec = { + argv: ['bash', '--noprofile'], + cwd: '/target', + env: { TARGET: 'yes' }, + rows: 24, + cols: 80, + graceMs: 100, + } as const - it('settles a missing scope immediately when the wrapper never started', async () => { - const launch = launchLinuxScope(spec([process.execPath, '-e', '']), { - systemdRun: `missing-systemd-run-${String(process.pid)}-${String(Date.now())}`, - systemctlQuery: async () => ({ - status: 1, - stdout: '', - stderr: 'Unit dsh-subprocess-missing.scope could not be found', - }), - runnerInvocation: spawnRunnerInvocation(), + it('uses the same request/bootstrap, preserves argv, and cleans after owner settlement', async () => { + const scope = prepareLinuxTerminalScope(terminalSpec, { TARGET: 'yes' }, { + systemdRun: '/bin/systemd-run', + systemctl: '/bin/systemctl', + runnerInvocation: ['/usr/bin/node', '/runner.js'], + spawnSync: vi.fn(() => ({ status: 0 })) as never, + systemctlQuery: async () => missingUnit(), }) - expect(launch.pid).toBeUndefined() - await expect(launch.direct).rejects.toThrow('runner failed to start') - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() + const requestPath = scope.env[SUBPROCESS_RUNNER_ENV] + if (requestPath === undefined) throw new Error('missing PTY request') + expect(scope.args.slice(-3)).toEqual(['--', 'bash', '--noprofile']) + expect(consumeLinuxLaunchRequest(requestPath)).toEqual({ cwd: '/target', env: { TARGET: 'yes' } }) + const owner = scope.bindOwner({ running: () => false, signal: vi.fn() }) + await expect(owner.waitForExit()).resolves.toBeUndefined() + expect(scope.resolveOutcome({ exitCode: 0, signal: null })).toEqual({ exitCode: 0, signal: null }) + scope.cleanup() + expect(existsSync(linuxLaunchFilesFromLocator(requestPath).directory)).toBe(false) }) - it('does not fabricate a direct outcome after a non-forced scope signal', async () => { - let wrapper: ReturnType | undefined - const run = vi.fn((_command: string, args: readonly string[], options: Parameters[2]) => { - const separator = args.indexOf('--') - wrapper = spawn(args[separator + 1] as string, args.slice(separator + 2), { ...options, detached: true }) - return wrapper - }) as unknown as typeof spawn - const runSync = vi.fn((command: string, args: readonly string[]) => { - if (command === 'systemctl' && args[1] === 'kill' && wrapper?.pid !== undefined) { - process.kill(-wrapper.pid, 'SIGKILL') - } - if (command === 'systemctl' && args[1] === 'show') { - const active = wrapper?.exitCode === null && wrapper.signalCode === null - return { status: 0, stdout: active ? 'active\n' : 'inactive\n', stderr: '', error: undefined } - } - return { status: 0, stdout: '', stderr: '', error: undefined } - }) as unknown as typeof spawnSync - const launch = launchLinuxScope(spec([process.execPath, '-e', 'setInterval(() => {}, 1000)']), { - spawn: run, - spawnSync: runSync, - systemctlQuery: asyncQuery(runSync), - runnerInvocation: spawnRunnerInvocation(), + it('surfaces PTY pre-exec errors instead of launcher outcomes', () => { + const scope = prepareLinuxTerminalScope(terminalSpec, { TARGET: 'yes' }) + const requestPath = scope.env[SUBPROCESS_RUNNER_ENV] + if (requestPath === undefined) throw new Error('missing PTY request') + const files = linuxLaunchFilesFromLocator(requestPath) + unlinkSync(requestPath) + writeLinuxStartupError(files, { + type: 'spawn-error', error: { name: 'Error', message: 'bad cwd', code: 'ENOENT' }, }) - launch.owner.signal('SIGTERM') - await expect(launch.direct).rejects.toThrow('exited without a direct-command result') - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() + expect(() => scope.resolveOutcome({ exitCode: 127, signal: null })).toThrow('bad cwd') + scope.cleanup() }) - it.each([ - [ - 'execution error', - { status: null, stdout: '', stderr: '', error: new Error('systemctl execution failed') }, - 'systemctl execution failed', - ], - [ - 'stderr', - { status: 1, stdout: '', stderr: 'Failed to connect to bus', error: undefined }, - 'Failed to connect to bus', - ], - [ - 'exit status', - { status: 1, stdout: '', stderr: '', error: undefined }, - 'exit 1', - ], - ])('reports a failed scope KILL through the shared wait: %s', async (_label, failure, message) => { - let wrapper: ReturnType | undefined - const run = vi.fn((_command: string, args: readonly string[], options: Parameters[2]) => { - const separator = args.indexOf('--') - wrapper = spawn(args[separator + 1] as string, args.slice(separator + 2), options) - return wrapper - }) as unknown as typeof spawn - const runSyncMock = vi.fn(( - command: string, - args: readonly string[], - _options?: { env?: NodeJS.ProcessEnv }, - ) => { - if (command === 'systemctl' && args[1] === 'kill') { - return failure - } - return { status: 0, stdout: 'active\n', stderr: '', error: undefined } - }) - const runSync = runSyncMock as unknown as typeof spawnSync - const launch = launchLinuxScope(spec([process.execPath, '-e', 'setInterval(() => {}, 1000)']), { - spawn: run, - spawnSync: runSync, - systemctlQuery: asyncQuery(runSync), - runnerInvocation: spawnRunnerInvocation(), - }) - void launch.direct.catch(() => {}) - try { - launch.owner.signal('SIGKILL') - await expect(launch.owner.waitForExit()).rejects.toThrow(message) - const killCall = runSyncMock.mock.calls.find(([, args]) => args.includes('--signal=SIGKILL')) - expect(killCall?.[0]).toBe('systemctl') - expect(killCall?.[1]).toContain('kill') - expect(killCall?.[1]).toContain('--kill-whom=all') - expect(killCall?.[2]?.env?.LC_ALL).toBe('C') - } finally { - wrapper?.kill('SIGKILL') - } + it('uses default owner dependencies and rejects an unconsumed request', () => { + const scope = prepareLinuxTerminalScope(terminalSpec, { TARGET: 'yes' }) + const requestPath = scope.env[SUBPROCESS_RUNNER_ENV] + if (requestPath === undefined) throw new Error('missing PTY request') + directories.push(linuxLaunchFilesFromLocator(requestPath).directory) + scope.bindOwner({ running: () => true, signal: vi.fn() }) + expect(() => scope.resolveOutcome({ exitCode: 1, signal: null })).toThrow( + 'before its bootstrap consumed', + ) + scope.cleanup() }) +}) - it('uses the production command defaults when no Linux internals are supplied', async () => { - let wrapper: ReturnType | undefined - let queryFailure: (Error & { code?: string | number }) | undefined - const run = vi.fn() - const runSync = vi.fn() - const runAsync = vi.fn() - const queryEnvironments: Array = [] - vi.resetModules() - vi.doMock('node:child_process', async (importOriginal) => { - const actual = await importOriginal() - run.mockImplementation((_command: string, args: readonly string[], options: Parameters[2]) => { - const separator = args.indexOf('--') - wrapper = actual.spawn(args[separator + 1] as string, args.slice(separator + 2), options) - return wrapper - }) - runSync.mockImplementation((_command: string, _args: readonly string[]) => { - return { status: 0, stdout: '', stderr: '', error: undefined } - }) - runAsync.mockImplementation(( - _command: string, - args: readonly string[], - options: { env?: NodeJS.ProcessEnv }, - callback: (error: Error | null, stdout: string, stderr: string) => void, - ) => { - queryEnvironments.push(options.env) - if (queryFailure !== undefined) { - callback(queryFailure, '', '') - return - } - const active = wrapper?.exitCode === null && wrapper.signalCode === null - callback(null, args[1] === 'show' && active ? 'active\n' : 'inactive\n', '') - }) - return { ...actual, execFile: runAsync, spawn: run, spawnSync: runSync } - }) - try { - const defaults = await import('../src/linux-scope.ts') - expect(defaults.probeLinuxUserManager()).toBe(true) - expect(defaults.probeLinuxRunner()).toBe(true) - expect(defaults.probeLinuxScope()).toBe(true) - const terminalLaunch = defaults.prepareLinuxTerminalScope(['shell', 'literal $HOME']) - expect(terminalLaunch.command).toBe('systemd-run') - expect(terminalLaunch.args.slice(-3)).toEqual(['--', 'shell', 'literal $HOME']) - const launch = defaults.launchLinuxScope(spec([process.execPath, '-e', 'process.exit(0)'])) - await expect(launch.direct).resolves.toEqual({ exitCode: 0, signal: null }) - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - expect(run).toHaveBeenCalledWith('systemd-run', expect.any(Array), expect.any(Object)) - expect(runSync).toHaveBeenCalledWith('systemctl', expect.any(Array), expect.any(Object)) - expect(runAsync).toHaveBeenCalledWith('systemctl', expect.any(Array), expect.any(Object), expect.any(Function)) - expect(queryEnvironments[0]?.LC_ALL).toBe('C') +describe('Linux ordinary launch adapters', () => { + it('uses the default launch dependencies without changing the target request', async () => { + const child = new FakeChild() + childProcessMocks.spawn.mockReturnValue(child) + const result = launchLinuxScope(spec(), { TARGET: 'yes' }) + const call = childProcessMocks.spawn.mock.calls[0] + const options = call?.[2] as { env?: NodeJS.ProcessEnv } | undefined + const requestPath = options?.env?.[SUBPROCESS_RUNNER_ENV] + if (requestPath === undefined) throw new Error('launch did not publish a request locator') + directories.push(linuxLaunchFilesFromLocator(requestPath).directory) + expect(call?.[0]).toBe('systemd-run') + expect(consumeLinuxLaunchRequest(requestPath)).toEqual({ cwd: '/target', env: { TARGET: 'yes' } }) + child.exit(0, null) + await expect(result.direct).resolves.toEqual({ exitCode: 0, signal: null }) + result.owner.cleanup?.() + }) - queryFailure = Object.assign(new Error('numeric systemctl failure'), { code: 17 }) - const numericFailure = defaults.launchLinuxScope(spec([process.execPath, '-e', 'process.exit(0)'])) - await expect(numericFailure.owner.waitForExit()).rejects.toBe(queryFailure) - await expect(numericFailure.direct).resolves.toEqual({ exitCode: 0, signal: null }) - - queryFailure = Object.assign(new Error('named systemctl failure'), { code: 'EQUERY' }) - const namedFailure = defaults.launchLinuxScope(spec([process.execPath, '-e', 'process.exit(0)'])) - await expect(namedFailure.owner.waitForExit()).rejects.toBe(queryFailure) - await expect(namedFailure.direct).resolves.toEqual({ exitCode: 0, signal: null }) - } finally { - vi.doUnmock('node:child_process') - vi.resetModules() - } + it('removes the private launch directory when spawn throws synchronously', () => { + const spawnError = new Error('synchronous spawn failure') + let requestPath: string | undefined + expect(() => launchLinuxScope(spec(), { TARGET: 'yes' }, { + runnerInvocation: ['/usr/bin/node', '/runner.js'], + spawn: vi.fn((_command: string, _args: readonly string[], options: { env?: NodeJS.ProcessEnv }) => { + requestPath = options.env?.[SUBPROCESS_RUNNER_ENV] + throw spawnError + }) as never, + })).toThrow(spawnError) + if (requestPath === undefined) throw new Error('spawn did not receive a request locator') + expect(existsSync(linuxLaunchFilesFromLocator(requestPath).directory)).toBe(false) }) }) diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts index d852b3b101..19b5c62c1b 100644 --- a/packages/subprocess/subprocess-local/tests/local.spec.ts +++ b/packages/subprocess/subprocess-local/tests/local.spec.ts @@ -6,6 +6,17 @@ import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local' import type { SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess' import { childEnv } from '../src/spawn.ts' +function mockWin32ForIsolatedRuntime(): void { + vi.doMock('@deepseek-ai/dsh-win32-process', () => ({ + loadWin32ProcessBindings: vi.fn(), + probeCurrentTokenJobSupport: vi.fn(), + })) +} + +function unmockWin32ForIsolatedRuntime(): void { + vi.doUnmock('@deepseek-ai/dsh-win32-process') +} + function spec(command: string, overrides: Partial = {}): SubprocessSpawnSpec { // Windows has no bash; the suite's simple commands translate to node one-liners. const argv = process.platform === 'win32' @@ -372,6 +383,7 @@ describe('LocalSubprocessRuntime', () => { kill: () => {}, } vi.resetModules() + mockWin32ForIsolatedRuntime() vi.doMock('node-pty', () => ({ spawn: () => terminal })) vi.doMock('../src/process-inspector.ts', async importOriginal => ({ ...await importOriginal(), @@ -394,6 +406,7 @@ describe('LocalSubprocessRuntime', () => { } finally { vi.doUnmock('node-pty') vi.doUnmock('../src/process-inspector.ts') + unmockWin32ForIsolatedRuntime() vi.resetModules() } }) @@ -401,6 +414,8 @@ describe('LocalSubprocessRuntime', () => { it('wraps Linux terminals in the selected scope and binds owner liveness', async () => { let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined let launcherRunning: (() => boolean) | undefined + let launcherSignal: ((signal: 'SIGTERM' | 'SIGKILL') => void) | undefined + const terminalKill = vi.fn(() => { throw new Error('terminal already exited') }) const terminal = { pid: 123, onData: () => ({ dispose: () => {} }), @@ -409,29 +424,31 @@ describe('LocalSubprocessRuntime', () => { return { dispose: () => {} } }, write: () => {}, - kill: () => {}, + kill: terminalKill, } const nodePtySpawn = vi.fn(() => terminal) const owner = { signal: vi.fn(), waitForExit: vi.fn(async () => {}), + terminateForHostExit: vi.fn(), } const launcherStates: boolean[] = [] - const bindOwner = vi.fn((running: () => boolean) => { - launcherRunning = running - launcherStates.push(running()) + const bindOwner = vi.fn((direct: { running(): boolean; signal(signal: 'SIGTERM' | 'SIGKILL'): void }) => { + launcherRunning = () => direct.running() + launcherSignal = (signal) => { direct.signal(signal) } + launcherStates.push(direct.running()) return owner }) - const prepareLinuxTerminalScope = vi.fn((argv: readonly string[]) => ({ + const prepareLinuxTerminalScope = vi.fn(() => ({ command: '/usr/bin/systemd-run', - args: ['--user', '--scope', '--', ...argv], + args: ['--user', '--scope', '--quiet', '--collect', '--', '/usr/bin/node', '/runner.js', '--', 'shell', '--literal'], + cwd: '/bootstrap', + env: { BOOTSTRAP: 'yes' }, bindOwner, + resolveOutcome: (outcome: unknown) => outcome, + cleanup: vi.fn(), })) - const probeLinuxUserManager = vi.fn(() => true) - const probeLinuxScope = vi.fn(() => true) - const probeLinuxRunner = vi.fn(() => { - throw new Error('terminal selection must not probe the ordinary runner') - }) + const probeLinuxNative = vi.fn(() => true) const inspector = { foregroundPgid: () => undefined, isStdinWaiting: () => false, @@ -443,13 +460,12 @@ describe('LocalSubprocessRuntime', () => { } vi.resetModules() + mockWin32ForIsolatedRuntime() vi.doMock('node-pty', () => ({ spawn: nodePtySpawn })) vi.doMock('../src/linux-scope.ts', () => ({ launchLinuxScope: vi.fn(), prepareLinuxTerminalScope, - probeLinuxRunner, - probeLinuxScope, - probeLinuxUserManager, + probeLinuxNative, })) let fiber: { dispose(): Promise } | undefined try { @@ -464,18 +480,21 @@ describe('LocalSubprocessRuntime', () => { argv: ['shell', '--literal'], cwd: process.cwd(), rows: 24, cols: 80, graceMs: 10, }) - expect(probeLinuxUserManager).toHaveBeenCalledOnce() - expect(probeLinuxScope).toHaveBeenCalledOnce() - expect(probeLinuxRunner).not.toHaveBeenCalled() - expect(prepareLinuxTerminalScope).toHaveBeenCalledExactlyOnceWith(['shell', '--literal']) + expect(probeLinuxNative).toHaveBeenCalledOnce() + expect(prepareLinuxTerminalScope).toHaveBeenCalledWith( + expect.objectContaining({ argv: ['shell', '--literal'] }), + expect.any(Object), + ) expect(nodePtySpawn).toHaveBeenCalledWith( '/usr/bin/systemd-run', - ['--user', '--scope', '--', 'shell', '--literal'], - expect.objectContaining({ rows: 24, cols: 80 }), + ['--user', '--scope', '--quiet', '--collect', '--', '/usr/bin/node', '/runner.js', '--', 'shell', '--literal'], + expect.objectContaining({ rows: 24, cols: 80, cwd: '/bootstrap', env: { BOOTSTRAP: 'yes' } }), ) expect(bindOwner).toHaveBeenCalledOnce() expect(launcherStates).toEqual([true]) expect(launcherRunning?.()).toBe(true) + expect(() => { launcherSignal?.('SIGTERM') }).not.toThrow() + expect(terminalKill).toHaveBeenCalledExactlyOnceWith('SIGTERM') exitListener?.({ exitCode: 0 }) expect(launcherRunning?.()).toBe(false) @@ -487,6 +506,60 @@ describe('LocalSubprocessRuntime', () => { await fiber?.dispose() vi.doUnmock('node-pty') vi.doUnmock('../src/linux-scope.ts') + unmockWin32ForIsolatedRuntime() + vi.resetModules() + } + }) + + it('cleans the Linux terminal launch protocol when node-pty throws synchronously', async () => { + const launchFailure = new Error('node-pty launch failed') + const cleanup = vi.fn() + const nodePtySpawn = vi.fn(() => { throw launchFailure }) + const prepareLinuxTerminalScope = vi.fn(() => ({ + command: '/usr/bin/systemd-run', + args: ['--user', '--scope', '--', 'shell'], + cwd: '/bootstrap', + env: { BOOTSTRAP: 'yes' }, + bindOwner: vi.fn(), + resolveOutcome: (outcome: unknown) => outcome, + cleanup, + })) + const inspector = { + foregroundPgid: () => undefined, + isStdinWaiting: () => false, + processTree: () => [{ pid: 123, started: 'shell' }], + processSession: () => [], + isAlive: () => false, + signalGroup: () => {}, + signalProcess: () => {}, + } + + vi.resetModules() + mockWin32ForIsolatedRuntime() + vi.doMock('node-pty', () => ({ spawn: nodePtySpawn })) + vi.doMock('../src/linux-scope.ts', () => ({ + launchLinuxScope: vi.fn(), + prepareLinuxTerminalScope, + probeLinuxNative: () => true, + })) + let fiber: { dispose(): Promise } | undefined + try { + const { default: IsolatedLocalSubprocessRuntime } = await import('../src/index.ts') + const ctx = new Context() + fiber = await ctx.plugin(IsolatedLocalSubprocessRuntime) + const runtime = ctx.subprocess as InstanceType + runtime.internals = { platform: 'linux' } + runtime.terminalInspector = inspector + + await expect(runtime.spawnTerminal({ + argv: ['shell'], cwd: process.cwd(), rows: 24, cols: 80, graceMs: 10, + })).rejects.toBe(launchFailure) + expect(cleanup).toHaveBeenCalledOnce() + } finally { + await fiber?.dispose() + vi.doUnmock('node-pty') + vi.doUnmock('../src/linux-scope.ts') + unmockWin32ForIsolatedRuntime() vi.resetModules() } }) @@ -504,6 +577,7 @@ describe('LocalSubprocessRuntime', () => { kill: () => {}, } vi.resetModules() + mockWin32ForIsolatedRuntime() vi.doMock('node-pty', () => ({ spawn: () => terminal })) try { const { default: IsolatedLocalSubprocessRuntime } = await import('../src/index.ts') @@ -532,6 +606,7 @@ describe('LocalSubprocessRuntime', () => { expect(disposalErrors).toHaveLength(1) } finally { vi.doUnmock('node-pty') + unmockWin32ForIsolatedRuntime() vi.resetModules() } }) @@ -540,6 +615,7 @@ describe('LocalSubprocessRuntime', () => { const ctx = new Context() const fiber = await ctx.plugin(LocalSubprocessRuntime) const handle = ctx.subprocess.spawn(spec('echo managed')) + expect(handle).not.toHaveProperty('pid') const result = await handle.done expect(result.exitCode).toBe(0) expect(handle.collected.stdout!.readFrom(0).text).toBe('managed\n') @@ -593,21 +669,17 @@ describe('LocalSubprocessRuntime', () => { } }) - it('rechecks the Linux manager while caching successful stable native probes', async () => { + it('rechecks native prerequisites for every eligible spawn and prepares storage before launch', async () => { const linuxLaunch = { kind: 'linux' } const windowsLaunch = { kind: 'windows' } const launchLinuxScope = vi.fn(() => linuxLaunch) const launchWindowsJob = vi.fn(() => windowsLaunch) - const probeLinuxUserManager = vi.fn(() => true) - const probeLinuxScope = vi.fn(() => true) - const probeLinuxRunner = vi.fn(() => true) + const probeLinuxNative = vi.fn(() => true) const probeWindowsJob = vi.fn(() => true) const prepareManagedProcessBinding = vi.fn(() => ({ spillDir: '/tmp/dsh-test-spill' })) - let nextPid = 100 const handles = [true, false, false].map((failFirstWait) => { let waits = 0 return { - pid: nextPid++, collected: {}, done: Promise.resolve({ exitCode: 0, signal: null }), terminate: vi.fn(), @@ -627,12 +699,11 @@ describe('LocalSubprocessRuntime', () => { const spawnSubprocess = vi.fn() vi.resetModules() + mockWin32ForIsolatedRuntime() vi.doMock('../src/linux-scope.ts', () => ({ launchLinuxScope, prepareLinuxTerminalScope: vi.fn(), - probeLinuxRunner, - probeLinuxScope, - probeLinuxUserManager, + probeLinuxNative, })) vi.doMock('../src/windows-job.ts', () => ({ launchWindowsJob, probeWindowsJob })) vi.doMock('../src/spawn.ts', async importOriginal => ({ @@ -657,9 +728,7 @@ describe('LocalSubprocessRuntime', () => { await new Promise(resolve => setImmediate(resolve)) await linuxRuntime.spawn(spec('true')).done await new Promise(resolve => setImmediate(resolve)) - expect(probeLinuxUserManager).toHaveBeenCalledTimes(3) - expect(probeLinuxScope).toHaveBeenCalledOnce() - expect(probeLinuxRunner).toHaveBeenCalledOnce() + expect(probeLinuxNative).toHaveBeenCalledTimes(3) expect(launchLinuxScope).toHaveBeenCalledTimes(2) const windowsContext = new Context() @@ -683,35 +752,30 @@ describe('LocalSubprocessRuntime', () => { vi.doUnmock('../src/linux-scope.ts') vi.doUnmock('../src/windows-job.ts') vi.doUnmock('../src/spawn.ts') + unmockWin32ForIsolatedRuntime() vi.resetModules() } }) - it('retries failed stable probes and does not cache Linux manager availability', async () => { - const probeLinuxUserManager = vi.fn() + it('does not cache failed or successful native capability probes', async () => { + const probeLinuxNative = vi.fn() + .mockReturnValueOnce(false) + .mockReturnValueOnce(false) .mockReturnValueOnce(false) .mockReturnValueOnce(true) - .mockReturnValueOnce(true) - .mockReturnValueOnce(true) - .mockReturnValueOnce(false) - .mockReturnValueOnce(true) - const probeLinuxScope = vi.fn() - .mockReturnValueOnce(false) - .mockReturnValueOnce(true) - const probeLinuxRunner = vi.fn() .mockReturnValueOnce(false) .mockReturnValueOnce(true) const probeWindowsJob = vi.fn() .mockReturnValueOnce(false) .mockReturnValueOnce(true) + .mockReturnValueOnce(true) vi.resetModules() + mockWin32ForIsolatedRuntime() vi.doMock('../src/linux-scope.ts', () => ({ launchLinuxScope: vi.fn(), prepareLinuxTerminalScope: vi.fn(), - probeLinuxRunner, - probeLinuxScope, - probeLinuxUserManager, + probeLinuxNative, })) vi.doMock('../src/windows-job.ts', () => ({ launchWindowsJob: vi.fn(), probeWindowsJob })) const fibers: Array<{ dispose(): Promise }> = [] @@ -733,9 +797,7 @@ describe('LocalSubprocessRuntime', () => { expect(linuxSelect('ordinary')).toBe('linux-scope') expect(linuxSelect('ordinary')).toBe('fallback') expect(linuxSelect('ordinary')).toBe('linux-scope') - expect(probeLinuxUserManager).toHaveBeenCalledTimes(6) - expect(probeLinuxScope).toHaveBeenCalledTimes(2) - expect(probeLinuxRunner).toHaveBeenCalledTimes(2) + expect(probeLinuxNative).toHaveBeenCalledTimes(6) const windowsContext = new Context() vi.spyOn(windowsContext.logger, 'warn').mockImplementation(() => {}) @@ -750,11 +812,12 @@ describe('LocalSubprocessRuntime', () => { expect(windowsSelect('ordinary')).toBe('fallback') expect(windowsSelect('ordinary')).toBe('windows-job') expect(windowsSelect('ordinary')).toBe('windows-job') - expect(probeWindowsJob).toHaveBeenCalledTimes(2) + expect(probeWindowsJob).toHaveBeenCalledTimes(3) } finally { for (const fiber of fibers.reverse()) await fiber.dispose() vi.doUnmock('../src/linux-scope.ts') vi.doUnmock('../src/windows-job.ts') + unmockWin32ForIsolatedRuntime() vi.resetModules() } }) diff --git a/packages/subprocess/subprocess-local/tests/managed-spawn.spec.ts b/packages/subprocess/subprocess-local/tests/managed-spawn.spec.ts deleted file mode 100644 index ed5e299f44..0000000000 --- a/packages/subprocess/subprocess-local/tests/managed-spawn.spec.ts +++ /dev/null @@ -1,279 +0,0 @@ -import { spawn } from 'node:child_process' -import { PassThrough } from 'node:stream' -import { describe, expect, it, vi } from 'vitest' -import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' -import type { BoundProcessOwner } from '../src/managed-owner.ts' -import { waitWithAbort } from '../src/managed-owner.ts' -import { bindManagedProcess } from '../src/spawn.ts' - -function spec(graceMs = 30): SubprocessSpawnSpec { - return { - argv: [process.execPath], - cwd: process.cwd(), - stdio: { stdin: 'ignore', stdout: { maxBytes: 1024 }, stderr: { maxBytes: 1024 } }, - graceMs, - } -} - -describe('managed process binding', () => { - it('forwards target pid publication after the handle is returned', async () => { - const target = { pid: undefined as number | undefined } - const handle = bindManagedProcess({ - ...spec(), - stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, - }, { - stdin: null, - stdout: null, - stderr: null, - get pid() { return target.pid }, - direct: Promise.resolve({ exitCode: 0, signal: null }), - owner: { signal: vi.fn(), waitForExit: async () => {} }, - }) - - expect(handle.pid).toBeUndefined() - target.pid = 4242 - expect(handle.pid).toBe(4242) - await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) - }) - - it('does not miss an abort between the initial check and listener registration', async () => { - let aborted = false - const addEventListener = vi.fn(() => { aborted = true }) - const removeEventListener = vi.fn() - const signal = { - get aborted() { return aborted }, - addEventListener, - removeEventListener, - } as unknown as AbortSignal - - await expect(waitWithAbort(new Promise(() => {}), signal)).resolves.toBe(false) - expect(addEventListener).toHaveBeenCalledOnce() - expect(removeEventListener).toHaveBeenCalledOnce() - }) - - it('contains owner failure after an already-aborted wait returns false', async () => { - const controller = new AbortController() - const ownerFailure = Promise.withResolvers() - controller.abort() - - await expect(waitWithAbort(ownerFailure.promise, controller.signal)).resolves.toBe(false) - ownerFailure.reject(new Error('owner unavailable')) - await new Promise(resolve => setImmediate(resolve)) - }) - - it('keeps direct outcome separate from managed-range quiescence', async () => { - const wrapper = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { - stdio: ['ignore', 'pipe', 'pipe'], - }) - const direct = Promise.withResolvers<{ exitCode: number | null; signal: NodeJS.Signals | null }>() - const stopped = Promise.withResolvers() - let ownerStopped = false - const signals: NodeJS.Signals[] = [] - const owner: BoundProcessOwner = { - signal(signal) { - if (ownerStopped) return - signals.push(signal) - if (signal === 'SIGKILL') { - ownerStopped = true - wrapper.kill('SIGKILL') - stopped.resolve(undefined) - } - }, - async waitForExit() { - if (ownerStopped) return - await stopped.promise - }, - } - const handle = bindManagedProcess(spec(), { - stdin: wrapper.stdin, - stdout: wrapper.stdout, - stderr: wrapper.stderr, - pid: 4242, - direct: direct.promise, - owner, - }) - direct.resolve({ exitCode: 42, signal: null }) - await expect(handle.done).resolves.toEqual({ exitCode: 42, signal: null }) - - const bound = AbortSignal.timeout(10) - await expect(handle.waitForExit(bound)).resolves.toBe(false) - handle.terminate() - expect(signals).toEqual(['SIGTERM']) - await new Promise(resolve => setTimeout(resolve, 50)) - expect(signals).toEqual(['SIGTERM', 'SIGKILL']) - await expect(handle.waitForExit()).resolves.toBe(true) - handle.terminateForHostExit() - expect(signals).toEqual(['SIGTERM', 'SIGKILL']) - }) - - it('routes synchronous host-exit finalization directly to the owner', () => { - const wrapper = spawn(process.execPath, ['-e', 'process.exit(0)'], { stdio: ['ignore', 'pipe', 'pipe'] }) - const signal = vi.fn() - const handle = bindManagedProcess(spec(), { - stdin: wrapper.stdin, - stdout: wrapper.stdout, - stderr: wrapper.stderr, - pid: 4242, - direct: Promise.resolve({ exitCode: 0, signal: null }), - owner: { signal, waitForExit: async () => {} }, - }) - handle.terminateForHostExit() - expect(signal).toHaveBeenCalledExactlyOnceWith('SIGKILL') - }) - - it.each([ - ['raw', 'pipe'], - ['collected', { maxBytes: 1024 }], - ] as const)('waits for %s output EOF after the direct outcome', async (_label, stdoutMode) => { - const stdout = new PassThrough() - const direct = Promise.withResolvers<{ exitCode: number | null; signal: NodeJS.Signals | null }>() - const request = { - ...spec(1_000), - stdio: { stdin: 'ignore', stdout: stdoutMode, stderr: 'inherit' } as const, - } - const handle = bindManagedProcess(request, { - stdin: null, - stdout, - stderr: null, - pid: 4242, - direct: direct.promise, - owner: { signal: vi.fn(), waitForExit: async () => {} }, - }) - if (stdoutMode === 'pipe') stdout.resume() - let doneSettled = false - void handle.done.then(() => { doneSettled = true }) - direct.resolve({ exitCode: 23, signal: null }) - await new Promise(resolve => setImmediate(resolve)) - expect(doneSettled).toBe(false) - stdout.end() - await expect(Promise.race([ - handle.done, - new Promise<'timeout'>(resolve => setTimeout(() => { resolve('timeout') }, 100)), - ])).resolves.toEqual({ exitCode: 23, signal: null }) - }) - - it('publishes direct outcome immediately when no collected stream needs draining', async () => { - const wrapper = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { - stdio: ['ignore', 'ignore', 'ignore'], - }) - const direct = Promise.withResolvers<{ exitCode: number | null; signal: NodeJS.Signals | null }>() - const handle = bindManagedProcess({ - ...spec(1_000), - stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, - }, { - stdin: wrapper.stdin, - stdout: wrapper.stdout, - stderr: wrapper.stderr, - pid: wrapper.pid, - direct: direct.promise, - owner: { signal: vi.fn(), waitForExit: async () => {} }, - }) - try { - direct.resolve({ exitCode: 23, signal: null }) - const outcome = await Promise.race([ - handle.done, - new Promise<'timeout'>(resolve => setTimeout(() => { resolve('timeout') }, 50)), - ]) - expect(outcome).toEqual({ exitCode: 23, signal: null }) - } finally { - wrapper.kill('SIGKILL') - } - }) - - it('retries termination after an expired escalation and range-observation rejection', async () => { - vi.useFakeTimers() - const failure = new Error('range observation failed') - const firstObservation = Promise.withResolvers() - const secondObservation = Promise.withResolvers() - const waitForExit = vi.fn() - .mockImplementationOnce(() => firstObservation.promise) - .mockImplementationOnce(() => secondObservation.promise) - const signal = vi.fn() - const handle = bindManagedProcess({ - ...spec(), - stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, - }, { - stdin: null, - stdout: null, - stderr: null, - pid: 4242, - direct: new Promise(() => {}), - owner: { signal, waitForExit }, - }) - try { - handle.terminate() - const firstWait = handle.waitForExit() - expect(signal.mock.calls).toEqual([['SIGTERM']]) - await vi.advanceTimersByTimeAsync(30) - expect(signal.mock.calls).toEqual([['SIGTERM'], ['SIGKILL']]) - firstObservation.reject(failure) - await expect(firstWait).rejects.toBe(failure) - - handle.terminate() - const secondWait = handle.waitForExit() - expect(signal.mock.calls).toEqual([['SIGTERM'], ['SIGKILL'], ['SIGTERM']]) - await vi.advanceTimersByTimeAsync(30) - expect(signal.mock.calls).toEqual([['SIGTERM'], ['SIGKILL'], ['SIGTERM'], ['SIGKILL']]) - secondObservation.resolve(undefined) - await expect(secondWait).resolves.toBe(true) - expect(waitForExit).toHaveBeenCalledTimes(2) - } finally { - vi.useRealTimers() - } - }) - - it('normalizes a non-Error direct rejection', async () => { - const wrapper = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { - stdio: ['ignore', 'pipe', 'pipe'], - }) - const rejection: unknown = 'runner failed' - const direct = Promise.resolve().then(() => { throw rejection }) - const signal = vi.fn() - const handle = bindManagedProcess(spec(), { - stdin: wrapper.stdin, - stdout: wrapper.stdout, - stderr: wrapper.stderr, - pid: wrapper.pid, - direct, - owner: { signal, waitForExit: async () => {} }, - }) - try { - await expect(handle.done).rejects.toThrow('runner failed') - expect(signal).toHaveBeenCalledExactlyOnceWith('SIGTERM') - expect(wrapper.stdout?.destroyed).toBe(true) - expect(wrapper.stderr?.destroyed).toBe(true) - } finally { - wrapper.kill('SIGKILL') - } - }) - - it('keeps abort ownership after direct exit until the managed range is empty', async () => { - const wrapper = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { - stdio: ['ignore', 'pipe', 'pipe'], - }) - const direct = Promise.withResolvers<{ exitCode: number | null; signal: NodeJS.Signals | null }>() - const stopped = Promise.withResolvers() - const signal = vi.fn((requested: NodeJS.Signals) => { - if (requested !== 'SIGTERM') return - wrapper.kill('SIGTERM') - stopped.resolve(undefined) - }) - const controller = new AbortController() - const handle = bindManagedProcess({ ...spec(), signal: controller.signal }, { - stdin: wrapper.stdin, - stdout: wrapper.stdout, - stderr: wrapper.stderr, - pid: wrapper.pid, - direct: direct.promise, - owner: { - signal, - waitForExit: async () => { await stopped.promise }, - }, - }) - direct.resolve({ exitCode: 0, signal: null }) - await handle.done - controller.abort() - await expect(handle.waitForExit()).resolves.toBe(true) - expect(signal).toHaveBeenCalledExactlyOnceWith('SIGTERM') - }) -}) diff --git a/packages/subprocess/subprocess-local/tests/native-containment.spec.ts b/packages/subprocess/subprocess-local/tests/native-containment.spec.ts index 403a682178..b10c538e53 100644 --- a/packages/subprocess/subprocess-local/tests/native-containment.spec.ts +++ b/packages/subprocess/subprocess-local/tests/native-containment.spec.ts @@ -6,6 +6,7 @@ import { Context } from '@deepseek-ai/cordis' import type { SubprocessSpawnSpec, SubprocessTerminalHandle } from '@deepseek-ai/dsh-subprocess' import LocalSubprocessRuntime from '../src/index.ts' import { launchLinuxScope, probeLinuxScope } from '../src/linux-scope.ts' +import { targetEnvironment } from '../src/runner-launch.ts' import { bindManagedProcess } from '../src/spawn.ts' const scratch = mkdtempSync(join(tmpdir(), 'dsh-native-containment-')) @@ -135,7 +136,8 @@ describe.skipIf(!linuxNative)('Linux user-systemd native containment', () => { it('terminates a setsid descendant and waits for the scope to become empty', async () => { const pidFile = join(scratch, `setsid-${Date.now()}.pid`) const command = `setsid sh -c 'echo $$ > "$1"; trap "" TERM; while :; do sleep 60; done' sh ${JSON.stringify(pidFile)} & wait` - const handle = bindManagedProcess(spec(['bash', '-c', command], 80), launchLinuxScope(spec(['bash', '-c', command], 80))) + const request = spec(['bash', '-c', command], 80) + const handle = bindManagedProcess(request, launchLinuxScope(request, targetEnvironment(request))) const descendant = await waitForPid(pidFile) handle.terminate() await handle.done @@ -145,14 +147,14 @@ describe.skipIf(!linuxNative)('Linux user-systemd native containment', () => { it('preserves Node-shaped ENOENT and EACCES spawn failures without replay', async () => { const missing = spec([`missing-native-target-${Date.now()}`]) - const missingHandle = bindManagedProcess(missing, launchLinuxScope(missing)) + const missingHandle = bindManagedProcess(missing, launchLinuxScope(missing, targetEnvironment(missing))) await expect(missingHandle.done).rejects.toMatchObject({ code: 'ENOENT' }) const deniedPath = join(scratch, `not-executable-${Date.now()}`) writeFileSync(deniedPath, '#!/bin/sh\nexit 0\n', { mode: 0o600 }) chmodSync(deniedPath, 0o600) const denied = spec([deniedPath]) - const deniedHandle = bindManagedProcess(denied, launchLinuxScope(denied)) + const deniedHandle = bindManagedProcess(denied, launchLinuxScope(denied, targetEnvironment(denied))) await expect(deniedHandle.done).rejects.toMatchObject({ code: 'EACCES' }) }) diff --git a/packages/subprocess/subprocess-local/tests/native-windows.spec.ts b/packages/subprocess/subprocess-local/tests/native-windows.spec.ts index 517ecbeaa0..9d83a3adf4 100644 --- a/packages/subprocess/subprocess-local/tests/native-windows.spec.ts +++ b/packages/subprocess/subprocess-local/tests/native-windows.spec.ts @@ -2,9 +2,9 @@ import { spawn, spawnSync } from 'node:child_process' import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs' import { tmpdir } from 'node:os' import { join } from 'node:path' -import { pathToFileURL } from 'node:url' import { afterAll, describe, expect, it } from 'vitest' import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' +import { targetEnvironment } from '../src/runner-launch.ts' import { bindManagedProcess } from '../src/spawn.ts' import { launchWindowsJob, probeWindowsJob } from '../src/windows-job.ts' @@ -73,7 +73,7 @@ function directSpawnFailure(argv: string[], cwd = scratch): Promise { - it('keeps raw stdin writable before target pid publication', async () => { + it('keeps raw stdin writable while the runner starts the target', async () => { const output = join(scratch, `stdin-${Date.now()}.txt`) const script = ` const { writeFileSync } = require('node:fs') @@ -86,15 +86,15 @@ describe.skipIf(!windowsNative)('Windows Job native containment', () => { ...spec([process.execPath, '-e', script]), stdio: { stdin: 'pipe', stdout: 'inherit', stderr: 'inherit' } as const, } - const handle = bindManagedProcess(request, launchWindowsJob(request)) + const handle = bindManagedProcess(request, launchWindowsJob(request, targetEnvironment(request))) if (handle.stdin === undefined) throw new Error('expected piped stdin') await new Promise((resolve, reject) => { handle.stdin?.once('error', reject) - handle.stdin?.end('before-publication', resolve) + handle.stdin?.end('immediate-stdin', resolve) }) await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) await expect(handle.waitForExit()).resolves.toBe(true) - expect(readFileSync(output, 'utf8')).toBe('before-publication') + expect(readFileSync(output, 'utf8')).toBe('immediate-stdin') }) it('reports direct exit before terminating its default-inheritance descendant', async () => { @@ -119,7 +119,7 @@ describe.skipIf(!windowsNative)('Windows Job native containment', () => { cwd: targetCwd, stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' } as const, } - const handle = bindManagedProcess(request, launchWindowsJob(request)) + const handle = bindManagedProcess(request, launchWindowsJob(request, targetEnvironment(request))) if (handle.stdout === undefined) throw new Error('expected piped stdout') if (handle.stderr === undefined) throw new Error('expected piped stderr') handle.stdout.resume() @@ -154,62 +154,21 @@ describe.skipIf(!windowsNative)('Windows Job native containment', () => { } }) - it('publishes target identity before reporting cwd restoration failure', async () => { - const preload = join(scratch, `fail-runner-cwd-restore-${Date.now()}.mjs`) - writeFileSync(preload, ` - const originalChdir = process.chdir.bind(process) - let calls = 0 - process.chdir = (path) => { - calls += 1 - if (calls === 2) { - const error = new Error('injected runner cwd restoration failure') - error.code = 'ENOENT' - error.syscall = 'chdir' - throw error - } - originalChdir(path) - } - `) - const previousNodeOptions = process.env.NODE_OPTIONS - process.env.NODE_OPTIONS = [previousNodeOptions, `--import=${pathToFileURL(preload).href}`] - .filter((value): value is string => value !== undefined && value.length > 0) - .join(' ') - try { - const command = process.env.ComSpec ?? process.env.COMSPEC - if (command === undefined) throw new Error('expected ComSpec for the Windows runner test') - const request = spec([command, '/d', '/s', '/c', 'exit 0']) - const launch = launchWindowsJob(request) - expect(launch.pid).toBeUndefined() - const failure = await launch.direct.catch((error: unknown) => error) - expect(launch.pid).toBeGreaterThan(0) - expect(failure).toMatchObject({ - message: 'injected runner cwd restoration failure', - code: 'ENOENT', - syscall: 'chdir', - }) - expect(failure).not.toHaveProperty('path') - await expect(launch.owner.waitForExit()).rejects.toThrow('before proving its managed range empty') - } finally { - if (previousNodeOptions === undefined) Reflect.deleteProperty(process.env, 'NODE_OPTIONS') - else process.env.NODE_OPTIONS = previousNodeOptions - } - }) - it('preserves missing-target and invalid-executable rejection errors', async () => { const relativeExecutable = `relative-node-${String(Date.now())}.exe` copyFileSync(process.execPath, join(scratch, relativeExecutable)) const relative = spec([relativeExecutable, '-e', 'process.exit(17)']) - const relativeHandle = bindManagedProcess(relative, launchWindowsJob(relative)) + const relativeHandle = bindManagedProcess(relative, launchWindowsJob(relative, targetEnvironment(relative))) await expect(relativeHandle.done).resolves.toEqual({ exitCode: 17, signal: null }) await expect(relativeHandle.waitForExit()).resolves.toBe(true) const missing = spec([`missing-native-target-${Date.now()}.exe`]) - const missingHandle = bindManagedProcess(missing, launchWindowsJob(missing)) + const missingHandle = bindManagedProcess(missing, launchWindowsJob(missing, targetEnvironment(missing))) await expect(missingHandle.done).rejects.toMatchObject({ code: 'ENOENT' }) await expect(missingHandle.waitForExit()).resolves.toBe(true) const accessDenied = spec([scratch]) - const accessDeniedHandle = bindManagedProcess(accessDenied, launchWindowsJob(accessDenied)) + const accessDeniedHandle = bindManagedProcess(accessDenied, launchWindowsJob(accessDenied, targetEnvironment(accessDenied))) await expect(accessDeniedHandle.done).rejects.toMatchObject({ code: 'EACCES' }) await expect(accessDeniedHandle.waitForExit()).resolves.toBe(true) @@ -217,7 +176,7 @@ describe.skipIf(!windowsNative)('Windows Job native containment', () => { const cwdArgv = [process.execPath, '-e', 'process.exit(0)'] const expectedCwd = await directSpawnFailure(cwdArgv, missingCwd) const invalidCwd = { ...spec(cwdArgv), cwd: missingCwd } - const invalidCwdHandle = bindManagedProcess(invalidCwd, launchWindowsJob(invalidCwd)) + const invalidCwdHandle = bindManagedProcess(invalidCwd, launchWindowsJob(invalidCwd, targetEnvironment(invalidCwd))) await expect(invalidCwdHandle.done).rejects.toMatchObject({ code: expectedCwd.code, syscall: expectedCwd.syscall, @@ -230,7 +189,7 @@ describe.skipIf(!windowsNative)('Windows Job native containment', () => { writeFileSync(invalidExecutable, 'not a Windows executable\r\n') const directError = await directSpawnFailure([invalidExecutable]) const invalid = spec([invalidExecutable]) - const invalidHandle = bindManagedProcess(invalid, launchWindowsJob(invalid)) + const invalidHandle = bindManagedProcess(invalid, launchWindowsJob(invalid, targetEnvironment(invalid))) await expect(invalidHandle.done).rejects.toMatchObject({ code: directError.code }) await expect(invalidHandle.waitForExit()).resolves.toBe(true) }) diff --git a/packages/subprocess/subprocess-local/tests/spawn-runner-built.e2e.ts b/packages/subprocess/subprocess-local/tests/spawn-runner-built.e2e.ts index b19af88b6b..d4c6dadcc2 100644 --- a/packages/subprocess/subprocess-local/tests/spawn-runner-built.e2e.ts +++ b/packages/subprocess/subprocess-local/tests/spawn-runner-built.e2e.ts @@ -1,42 +1,69 @@ -import { spawnSync } from 'node:child_process' +import { spawn } from 'node:child_process' +import type { Buffer } from 'node:buffer' import { existsSync } from 'node:fs' -import { fileURLToPath } from 'node:url' +import { resolve } from 'node:path' import { describe, expect, it } from 'vitest' -import { cleanupRunnerFiles, createRunnerFiles, readRunnerEventsAsync } from '../src/runner-protocol.ts' +import { + cleanupLinuxLaunchFiles, + createLinuxLaunchFiles, +} from '../src/runner-protocol.ts' +import { runnerEnvironment, SUBPROCESS_RUNNER_ENV } from '../src/runner-launch.ts' -const builtEntry = fileURLToPath(new URL( - './lib/spawn-runner.js', - import.meta.resolve('@deepseek-ai/dsh-subprocess-local/package.json'), -)) -const required = process.env.DSH_REQUIRE_BUILT_SUBPROCESS_RUNNER === '1' +const repoRoot = resolve(import.meta.dirname, '../../../..') +const sourceRunner = resolve(repoRoot, 'packages/subprocess/subprocess-local/src/bin.ts') +const builtRunner = resolve(repoRoot, 'packages/subprocess/subprocess-local/lib/runner.js') -describe.skipIf(!existsSync(builtEntry) && !required)('built subprocess runner entry', () => { - it('reports the direct target outcome through the built private entry', async () => { - if (!existsSync(builtEntry)) throw new Error(`required built subprocess runner is missing: ${builtEntry}`) - const files = createRunnerFiles({ - argv: [process.execPath, '-e', 'process.exit(11)'], - cwd: process.cwd(), - env: {}, +function targetEnv(): Record { + return { + ...Object.fromEntries(Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined)), + [SUBPROCESS_RUNNER_ENV]: 'target-collision-restored', + } +} + +async function execute(invocation: string[]): Promise<{ status: number | null; stdout: string; stderr: string }> { + const files = createLinuxLaunchFiles({ cwd: repoRoot, env: targetEnv() }) + try { + const child = spawn(invocation[0] as string, [ + ...invocation.slice(1), + '--', + process.execPath, + '--input-type=module', + '--eval', + `process.stdout.write(process.argv[0]+'|'+process.cwd()+'|'+process.env.${SUBPROCESS_RUNNER_ENV})`, + ], { + env: runnerEnvironment(files.requestPath), + stdio: ['ignore', 'pipe', 'pipe'], + }) + let stdout = '' + let stderr = '' + child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString() }) + child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString() }) + const status = await new Promise((resolveExit, rejectExit) => { + child.once('error', rejectExit) + child.once('exit', resolveExit) + }) + return { status, stdout, stderr } + } finally { + cleanupLinuxLaunchFiles(files) + } +} + +describe('subprocess-local runner artifacts', () => { + it('executes the source entry through the provider-owned core', async () => { + const result = await execute([process.execPath, '--import', 'tsx/esm', sourceRunner]) + expect(result).toEqual({ + status: 0, + stdout: `${process.execPath}|${repoRoot}|target-collision-restored`, + stderr: '', + }) + }) + + it.skipIf(!existsSync(builtRunner))('executes the built ./runner subpath through the same core', async () => { + const result = await execute([process.execPath, builtRunner]) + expect(result).toEqual({ + status: 0, + stdout: `${process.execPath}|${repoRoot}|target-collision-restored`, + stderr: '', }) - try { - const result = spawnSync(process.execPath, [ - builtEntry, - '--mode', - 'node', - '--request', - files.requestPath, - '--events', - files.eventsPath, - ], { encoding: 'utf8', timeout: 10_000 }) - expect(result.error).toBeUndefined() - const events = await readRunnerEventsAsync(files.eventsPath) - expect(events).toHaveLength(2) - expect(events[0]?.type).toBe('started') - if (events[0]?.type !== 'started') throw new Error('expected started event') - expect(events[0].pid).toBeGreaterThan(0) - expect(events[1]).toEqual({ type: 'exit', exitCode: 11, signal: null }) - } finally { - cleanupRunnerFiles(files) - } }) }) diff --git a/packages/subprocess/subprocess-local/tests/spawn-runner.spec.ts b/packages/subprocess/subprocess-local/tests/spawn-runner.spec.ts index a65bcbed81..37c59ba112 100644 --- a/packages/subprocess/subprocess-local/tests/spawn-runner.spec.ts +++ b/packages/subprocess/subprocess-local/tests/spawn-runner.spec.ts @@ -1,1252 +1,666 @@ -import { spawn, spawnSync } from 'node:child_process' -import type { ChildProcess } from 'node:child_process' import { EventEmitter } from 'node:events' -import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs' +import { + existsSync, + mkdtempSync, + mkdirSync, + readdirSync, + rmSync, + statSync, + symlinkSync, + unlinkSync, + writeFileSync, +} from 'node:fs' import { tmpdir } from 'node:os' import { join } from 'node:path' -import { fileURLToPath } from 'node:url' -import { describe, expect, it, vi } from 'vitest' -import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' +import { afterEach, describe, expect, it, vi } from 'vitest' import { Win32Error } from '@deepseek-ai/dsh-win32-process' import type { NativePtr, Win32ProcessBindings } from '@deepseek-ai/dsh-win32-process' import { - cleanupAfterRunner, - runnerDirectResult, - runnerFiles, + cleanupLinuxLaunchFiles, + consumeLinuxLaunchRequest, + createLinuxLaunchFiles, + deserializeRunnerError, + isWindowsTerminateRequest, + linuxLaunchFilesFromLocator, + parseWindowsRunnerResult, + parseWindowsStartRequest, + readLinuxStartupError, + serializeRunnerError, + writeLinuxStartupError, +} from '../src/runner-protocol.ts' +import { + consumeRunnerSelection, + parseRunnerTargetArgv, + runnerEnvironment, + runnerInvocationAvailable, runnerStdio, spawnRunnerInvocation, + SUBPROCESS_RUNNER_ENV, + targetEnvironment, + validateTerminalTarget, + WINDOWS_RUNNER_SELECTION, } from '../src/runner-launch.ts' -import { observeChildLifecycle } from '../src/managed-owner.ts' import { - appendRunnerEvent, - cleanupRunnerFiles, - consumeRunnerRequest, - createRunnerFiles, - deserializeSpawnError, - readRunnerEventsAsync, - serializeSpawnError, -} from '../src/runner-protocol.ts' -import { reportSpawnRunnerFailure, runSpawnRunner } from '../src/spawn-runner.ts' + reportSpawnRunnerFailure, + runSpawnRunner, +} from '../src/spawn-runner.ts' +import type { SpawnRunnerInternals } from '../src/spawn-runner.ts' -const sourceInvocation = [ - process.execPath, - '--import', - 'tsx/esm', - fileURLToPath(import.meta.resolve('@deepseek-ai/dsh-subprocess-local/src/bin.ts')), -] +const scratch: string[] = [] -function spec(overrides: Partial = {}): SubprocessSpawnSpec { +afterEach(() => { + for (const path of scratch.splice(0)) rmSync(path, { recursive: true, force: true }) + vi.restoreAllMocks() +}) + +function track(files: T): T { + scratch.push(files.directory) + return files +} + +class FakeRunnerHost extends EventEmitter { + env: NodeJS.ProcessEnv = { [SUBPROCESS_RUNNER_ENV]: 'stale', SAFE: 'bootstrap' } + exitCode: number | undefined + connected = true + directory = process.cwd() + sent: unknown[] = [] + sendFailure: Error | undefined + sendThrown: unknown + + cwd(): string { return this.directory } + chdir(path: string): void { this.directory = path } + disconnect(): void { + if (!this.connected) return + this.connected = false + this.emit('disconnect') + } + send(message: unknown, callback?: (error: Error | null) => void): boolean { + if (this.sendThrown !== undefined) throw this.sendThrown + this.sent.push(message) + queueMicrotask(() => { callback?.(this.sendFailure ?? null) }) + return true + } +} + +function hostArgument(host: FakeRunnerHost): Parameters[2] { + return host as unknown as Parameters[2] +} + +function internals(overrides: Partial = {}): SpawnRunnerInternals { return { - argv: [process.execPath, '-e', ''], - cwd: process.cwd(), - stdio: { stdin: 'ignore', stdout: { maxBytes: 1024 }, stderr: { maxBytes: 1024 } }, - graceMs: 100, + execve: vi.fn(() => { throw Object.assign(new Error('missing'), { code: 'ENOENT' }) }), + loadWin32ProcessBindings: vi.fn(() => ({} as Win32ProcessBindings)), + spawnCurrentTokenJobProcess: vi.fn(() => ({ + pid: 123, + process: 10n as NativePtr, + job: 20n as NativePtr, + })), + closeCurrentProcessStandardHandles: vi.fn(), + pollProcessExit: vi.fn(() => 0), + isJobEmpty: vi.fn(() => true), + terminateJob: vi.fn(), + closeHandleChecked: vi.fn(), ...overrides, } } -function fakeChild(pid: number | undefined): ChildProcess { - const child = new EventEmitter() as ChildProcess - Object.assign(child, { pid, exitCode: null, signalCode: null }) - return child +async function runWindows( + host: FakeRunnerHost, + native: SpawnRunnerInternals, + start: unknown = { type: 'start', cwd: 'C:\\target', env: { TARGET: 'yes', dsh_subprocess_runner: 'restored' } }, +): Promise { + const running = runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe', 'literal arg'], + hostArgument(host), + native, + ) + host.emit('message', start) + await running } -class FakeRunnerHost extends EventEmitter { - env: NodeJS.ProcessEnv = {} - exitCode: number | undefined - connected = false - directory = process.cwd() - readonly disconnect = vi.fn(() => { this.connected = false }) +describe('closed runner protocol', () => { + it('creates, consumes, reports through, and cleans one private Linux exchange', () => { + const files = track(createLinuxLaunchFiles({ cwd: '/target', env: { A: '1' } })) + expect(statSync(files.directory).mode & 0o777).toBe(0o700) + expect(statSync(files.requestPath).mode & 0o777).toBe(0o600) + expect(linuxLaunchFilesFromLocator(files.requestPath)).toEqual(files) + expect(consumeLinuxLaunchRequest(files.requestPath)).toEqual({ cwd: '/target', env: { A: '1' } }) + expect(existsSync(files.requestPath)).toBe(false) - cwd(): string { return this.directory } - chdir(directory: string): void { this.directory = directory } -} - -function asRunnerHost(host: FakeRunnerHost): Parameters[1] { - return host as unknown as Parameters[1] -} - -type RunnerInternals = NonNullable[2]> - -const fakeWin32Api = {} as Win32ProcessBindings -const fakeProcessHandle = 60n as NativePtr -const fakeJobHandle = 50n as NativePtr - -function fakeRunnerInternals(overrides: Partial = {}): RunnerInternals { - let nextPipeHandle = 70n - return { - spawn, - loadWin32ProcessBindings: vi.fn(() => fakeWin32Api), - openNamedPipeForStdio: vi.fn(() => nextPipeHandle++), - spawnCurrentTokenJobProcess: vi.fn(() => ({ - pid: 1234, - process: fakeProcessHandle, - job: fakeJobHandle, - })), - pollProcessExit: vi.fn(() => 0), - isJobEmpty: vi.fn(() => true), - terminateJob: vi.fn(), - waitForProcessExit: vi.fn(() => 0), - closeHandleChecked: vi.fn(), - ...overrides, - } as RunnerInternals -} - -function win32RunnerArgs( - requestPath: string, - eventsPath: string, - pipes: string[] = [], -): string[] { - return [ - '--mode', 'win32', - '--request', requestPath, - '--events', eventsPath, - ...pipes, - ] -} - -function runRunner(invocation: string[], requestPath: string, eventsPath: string) { - const [command, ...prefix] = invocation - return spawnSync(command as string, [ - ...prefix, - '--mode', - 'node', - '--request', - requestPath, - '--events', - eventsPath, - ], { encoding: 'utf8', timeout: 10_000 }) -} - -describe('spawn runner transport', () => { - it('selects the source runner without publishing a runner package face', () => { - expect(spawnRunnerInvocation()).toEqual(sourceInvocation) - const manifest = JSON.parse(readFileSync( - fileURLToPath(new URL('../package.json', import.meta.url)), - 'utf8', - )) as { exports: Record } - expect(manifest.exports).not.toHaveProperty('./spawn-runner') - expect(manifest.exports['./package.json']).toBe('./package.json') - }) - - it('observes runner events without SharedArrayBuffer', async () => { - const descriptor = Object.getOwnPropertyDescriptor(globalThis, 'SharedArrayBuffer') - Object.defineProperty(globalThis, 'SharedArrayBuffer', { configurable: true, value: undefined }) - vi.resetModules() - const files = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - const isolated = await import('../src/runner-launch.ts') - const result = isolated.runnerDirectResult(fakeChild(123), files, new Promise(() => {})) - appendRunnerEvent(files.eventsPath, { type: 'started', pid: 456 }) - appendRunnerEvent(files.eventsPath, { type: 'exit', exitCode: 0, signal: null }) - await expect(result.direct).resolves.toEqual({ exitCode: 0, signal: null }) - expect(result.pid).toBe(456) - } finally { - cleanupRunnerFiles(files) - if (descriptor === undefined) Reflect.deleteProperty(globalThis, 'SharedArrayBuffer') - else Object.defineProperty(globalThis, 'SharedArrayBuffer', descriptor) - vi.resetModules() - } - }) - - it('re-enters a packaged executable through its private runner dispatch', () => { - const packagedProcess = process as NodeJS.Process & { pkg?: unknown } - const original = Object.getOwnPropertyDescriptor(packagedProcess, 'pkg') - Object.defineProperty(packagedProcess, 'pkg', { configurable: true, value: {} }) - try { - expect(spawnRunnerInvocation()).toEqual([process.execPath, '--dsh-internal-subprocess-runner']) - } finally { - if (original === undefined) Reflect.deleteProperty(packagedProcess, 'pkg') - else Object.defineProperty(packagedProcess, 'pkg', original) - } - }) - - it('supports the node runner capability probe', () => { - const result = spawnSync(sourceInvocation[0] as string, [ - ...sourceInvocation.slice(1), - '--mode', - 'probe-node', - ], { encoding: 'utf8', timeout: 10_000 }) - expect(result.error).toBeUndefined() - expect(result.status).toBe(0) - }) - - it('runs the Node target lifecycle in-process through the coverable runner logic', async () => { - const files = createRunnerFiles({ - argv: [process.execPath, '-e', 'process.exit(12)'], - cwd: process.cwd(), - env: {}, + const failure = Object.assign(new Error('spawn missing'), { + name: 'SpawnError', code: 'ENOENT', errno: -2, syscall: 'spawn tool', path: 'tool', spawnargs: ['x'], }) - const host = new FakeRunnerHost() - try { - await runSpawnRunner([ - '--mode', 'node', - '--request', files.requestPath, - '--events', files.eventsPath, - ], asRunnerHost(host)) - expect(host.exitCode).toBe(12) - expect(await readRunnerEventsAsync(files.eventsPath)).toEqual([ - expect.objectContaining({ type: 'started' }), - { type: 'exit', exitCode: 12, signal: null }, - ]) - } finally { - cleanupRunnerFiles(files) - } - }) - - it('reports an in-process Node target spawn failure', async () => { - const files = createRunnerFiles({ - argv: [`missing-dsh-runner-target-${String(process.pid)}-${String(Date.now())}`], - cwd: process.cwd(), - env: {}, + writeLinuxStartupError(files, { type: 'spawn-error', error: serializeRunnerError(failure) }) + expect(statSync(files.startupErrorPath).mode & 0o777).toBe(0o600) + const result = readLinuxStartupError(files.startupErrorPath) + expect(result).toMatchObject({ type: 'spawn-error', error: { code: 'ENOENT', path: 'tool', spawnargs: ['x'] } }) + expect(deserializeRunnerError(result!.error)).toMatchObject({ + name: 'SpawnError', message: 'spawn missing', code: 'ENOENT', errno: -2, }) - const host = new FakeRunnerHost() - try { - await runSpawnRunner([ - '--mode', 'node', - '--request', files.requestPath, - '--events', files.eventsPath, - ], asRunnerHost(host)) - expect(host.exitCode).toBe(127) - const [event] = await readRunnerEventsAsync(files.eventsPath) - expect(event?.type).toBe('spawn-error') - if (event?.type !== 'spawn-error') throw new Error('expected spawn error') - expect(event.error.code).toBe('ENOENT') - } finally { - cleanupRunnerFiles(files) - } - }) - - it('contains a post-start Node runner error and ignores scope signals', async () => { - const files = createRunnerFiles({ argv: ['node'], cwd: process.cwd(), env: {} }) - const host = new FakeRunnerHost() - const child = Object.assign(new EventEmitter(), { pid: 4321 }) as ChildProcess - const injectedSpawn = vi.fn(() => { - queueMicrotask(() => { - host.emit('SIGTERM') - child.emit('spawn') - child.emit('error', new Error('post-start node failure')) - child.emit('exit', 0, null) - }) - return child - }) as unknown as typeof spawn - try { - await runSpawnRunner([ - '--mode', 'node', - '--request', files.requestPath, - '--events', files.eventsPath, - ], asRunnerHost(host), fakeRunnerInternals({ spawn: injectedSpawn })) - expect(injectedSpawn).toHaveBeenCalledTimes(1) - expect(injectedSpawn).toHaveBeenCalledWith('node', [], { - cwd: process.cwd(), - env: {}, - stdio: 'inherit', - detached: true, - }) - expect(host.exitCode).toBe(127) - expect(await readRunnerEventsAsync(files.eventsPath)).toEqual([ - { type: 'started', pid: 4321 }, - { type: 'runner-error', error: { name: 'Error', message: 'post-start node failure' } }, - ]) - expect(host.listenerCount('SIGTERM')).toBe(0) - } finally { - cleanupRunnerFiles(files) - } - }) - - it('maps a signal-only Node exit to the runner failure exit code', async () => { - const files = createRunnerFiles({ argv: ['node'], cwd: process.cwd(), env: {} }) - const host = new FakeRunnerHost() - const child = Object.assign(new EventEmitter(), { pid: 4321 }) as ChildProcess - const injectedSpawn = vi.fn(() => { - queueMicrotask(() => { - child.emit('spawn') - child.emit('exit', null, 'SIGTERM') - }) - return child - }) as unknown as typeof spawn - try { - await runSpawnRunner([ - '--mode', 'node', - '--request', files.requestPath, - '--events', files.eventsPath, - ], asRunnerHost(host), fakeRunnerInternals({ spawn: injectedSpawn })) - expect(host.exitCode).toBe(1) - expect(await readRunnerEventsAsync(files.eventsPath)).toEqual([ - { type: 'started', pid: 4321 }, - { type: 'exit', exitCode: null, signal: 'SIGTERM' }, - ]) - } finally { - cleanupRunnerFiles(files) - } - }) - - it('runs the in-process capability probes and always closes the probe Job', async () => { - const nodeHost = new FakeRunnerHost() - await expect(runSpawnRunner( - ['--mode', 'probe-node'], - asRunnerHost(nodeHost), - fakeRunnerInternals(), - )).resolves.toBeUndefined() - - const host = new FakeRunnerHost() - host.env.ComSpec = 'C:\\Windows\\System32\\cmd.exe' - host.directory = 'C:\\runner' - const internals = fakeRunnerInternals() - await expect(runSpawnRunner( - ['--mode', 'probe-win32'], - asRunnerHost(host), - internals, - )).resolves.toBeUndefined() - expect(internals.spawnCurrentTokenJobProcess).toHaveBeenCalledWith(fakeWin32Api, { - command: 'C:\\Windows\\System32\\cmd.exe', - args: ['/d', '/s', '/c', 'exit 0'], - cwd: 'C:\\runner', - }) - expect(internals.waitForProcessExit).toHaveBeenCalledWith(fakeWin32Api, fakeProcessHandle) - expect(internals.closeHandleChecked).toHaveBeenCalledWith( - fakeWin32Api, - fakeJobHandle, - 'subprocess Windows Job probe', - ) - - const legacyHost = new FakeRunnerHost() - legacyHost.env.COMSPEC = 'legacy-cmd.exe' - const failing = fakeRunnerInternals({ waitForProcessExit: vi.fn(() => 9) }) - await expect(runSpawnRunner( - ['--mode', 'probe-win32'], - asRunnerHost(legacyHost), - failing, - )).rejects.toThrow('probe exited with code 9') - expect(failing.closeHandleChecked).toHaveBeenCalledWith( - fakeWin32Api, - fakeJobHandle, - 'subprocess Windows Job probe', - ) - - await expect(runSpawnRunner( - ['--mode', 'probe-win32'], - asRunnerHost(new FakeRunnerHost()), - fakeRunnerInternals(), - )).rejects.toThrow('without ComSpec') - }) - - it('runs the Win32 target, forwards every pipe, and waits for an empty Job', async () => { - vi.useFakeTimers() - const files = createRunnerFiles({ - argv: ['tool.exe', 'literal $HOME'], - cwd: 'C:\\target', - env: { ONLY: 'kept' }, - }) - const host = new FakeRunnerHost() - host.env.STALE = 'removed' - host.directory = 'C:\\runner' - host.connected = true - const pollProcessExit = vi.fn() - .mockReturnValueOnce(undefined) - .mockReturnValueOnce(42) - const isJobEmpty = vi.fn() - .mockReturnValueOnce(false) - .mockReturnValueOnce(true) - const internals = fakeRunnerInternals({ pollProcessExit, isJobEmpty }) - try { - const running = runSpawnRunner(win32RunnerArgs(files.requestPath, files.eventsPath, [ - '--stdin-pipe', '\\\\.\\pipe\\stdin', - '--stdout-pipe', '\\\\.\\pipe\\stdout', - '--stderr-pipe', '\\\\.\\pipe\\stderr', - ]), asRunnerHost(host), internals) - await vi.advanceTimersByTimeAsync(30) - await running - - expect(host.env).toEqual({ ONLY: 'kept' }) - expect(host.directory).toBe('C:\\runner') - expect(host.disconnect).toHaveBeenCalledOnce() - expect(internals.openNamedPipeForStdio).toHaveBeenNthCalledWith( - 1, - fakeWin32Api, - '\\\\.\\pipe\\stdin', - 'read', - ) - expect(internals.openNamedPipeForStdio).toHaveBeenNthCalledWith( - 2, - fakeWin32Api, - '\\\\.\\pipe\\stdout', - 'write', - ) - expect(internals.openNamedPipeForStdio).toHaveBeenNthCalledWith( - 3, - fakeWin32Api, - '\\\\.\\pipe\\stderr', - 'write', - ) - expect(internals.spawnCurrentTokenJobProcess).toHaveBeenCalledWith( - fakeWin32Api, - { command: 'tool.exe', args: ['literal $HOME'], cwd: 'C:\\target' }, - { - stdin: 70n, - stdout: 71n, - stderr: 72n, - }, - ) - expect(pollProcessExit).toHaveBeenCalledTimes(2) - expect(isJobEmpty).toHaveBeenCalledTimes(2) - expect(await readRunnerEventsAsync(files.eventsPath)).toEqual([ - { type: 'started', pid: 1234 }, - { type: 'exit', exitCode: 42, signal: null }, - ]) - expect(internals.closeHandleChecked).toHaveBeenCalledWith( - fakeWin32Api, - fakeProcessHandle, - 'ordinary direct process', - ) - expect(internals.closeHandleChecked).toHaveBeenCalledWith( - fakeWin32Api, - fakeJobHandle, - 'ordinary process Job', - ) - } finally { - vi.useRealTimers() - cleanupRunnerFiles(files) - } - }) - - it('accepts only the Win32 terminate IPC message and coalesces disconnect', async () => { - vi.useFakeTimers() - const files = createRunnerFiles({ argv: ['tool.exe'], cwd: 'C:\\target', env: {} }) - const host = new FakeRunnerHost() - const internals = fakeRunnerInternals() - try { - const running = runSpawnRunner( - win32RunnerArgs(files.requestPath, files.eventsPath), - asRunnerHost(host), - internals, - ) - host.emit('message', null) - host.emit('message', 'terminate') - host.emit('message', { type: 'other' }) - host.emit('message', { type: 'terminate' }) - host.emit('message', { type: 'terminate' }) - host.emit('disconnect') - await vi.advanceTimersByTimeAsync(10) - await running - - expect(internals.terminateJob).toHaveBeenCalledOnce() - expect(internals.terminateJob).toHaveBeenCalledWith(fakeWin32Api, fakeJobHandle, 1) - expect(host.disconnect).not.toHaveBeenCalled() - expect(await readRunnerEventsAsync(files.eventsPath)).toEqual([ - { type: 'started', pid: 1234 }, - { type: 'exit', exitCode: 0, signal: null }, - ]) - } finally { - vi.useRealTimers() - cleanupRunnerFiles(files) - } - }) - - it('reports a non-Error Win32 termination failure and closes both live handles', async () => { - const files = createRunnerFiles({ argv: ['tool.exe'], cwd: 'C:\\target', env: {} }) - const host = new FakeRunnerHost() - host.connected = true - const terminateJob = vi.fn(() => { throw 'raw termination failure' }) - const internals = fakeRunnerInternals({ terminateJob }) - try { - const running = runSpawnRunner( - win32RunnerArgs(files.requestPath, files.eventsPath), - asRunnerHost(host), - internals, - ) - host.emit('disconnect') - await running - - expect(host.exitCode).toBe(127) - expect(host.disconnect).toHaveBeenCalledOnce() - expect(await readRunnerEventsAsync(files.eventsPath)).toEqual([ - { type: 'started', pid: 1234 }, - { type: 'runner-error', error: { name: 'Error', message: 'raw termination failure' } }, - ]) - expect(internals.closeHandleChecked).toHaveBeenCalledWith( - fakeWin32Api, - fakeProcessHandle, - 'ordinary direct process cleanup', - ) - expect(internals.closeHandleChecked).toHaveBeenCalledWith( - fakeWin32Api, - fakeJobHandle, - 'ordinary process Job cleanup', - ) - } finally { - cleanupRunnerFiles(files) - } - }) - - it.each([ - [2, 'ENOENT'], - [3, 'ENOENT'], - [267, 'ENOENT'], - [5, 'EACCES'], - [193, 'EFTYPE'], - [999, 'UNKNOWN'], - ] as const)('maps Win32 CreateProcess error %i to %s', async (win32Code, code) => { - const files = createRunnerFiles({ - argv: ['missing.exe', 'literal argument'], - cwd: 'C:\\target', - env: {}, - }) - const host = new FakeRunnerHost() - const internals = fakeRunnerInternals({ - spawnCurrentTokenJobProcess: vi.fn(() => { - throw new Win32Error('CreateProcessW', win32Code) - }), - }) - try { - await runSpawnRunner( - win32RunnerArgs(files.requestPath, files.eventsPath), - asRunnerHost(host), - internals, - ) - expect(host.exitCode).toBeUndefined() - const [event] = await readRunnerEventsAsync(files.eventsPath) - expect(event?.type).toBe('spawn-error') - if (event?.type !== 'spawn-error') throw new Error('expected spawn error') - expect(event.error).toMatchObject({ - code, - syscall: 'spawn missing.exe', - path: 'missing.exe', - spawnargs: ['literal argument'], - }) - } finally { - cleanupRunnerFiles(files) - } - }) - - it('preserves a Win32 target spawn failure when restoring the runner cwd also fails', async () => { - const files = createRunnerFiles({ - argv: ['missing.exe', 'literal argument'], - cwd: 'C:\\target', - env: {}, - }) - const host = new FakeRunnerHost() - host.directory = 'C:\\runner' - const chdir = vi.fn((directory: string) => { - if (directory === 'C:\\runner') throw new Error('cwd restore failed') - host.directory = directory - }) - host.chdir = chdir - const internals = fakeRunnerInternals({ - spawnCurrentTokenJobProcess: vi.fn(() => { - throw new Win32Error('CreateProcessW', 2) - }), - }) - try { - await runSpawnRunner( - win32RunnerArgs(files.requestPath, files.eventsPath), - asRunnerHost(host), - internals, - ) - expect(chdir).toHaveBeenCalledTimes(2) - expect(host.exitCode).toBeUndefined() - const [event] = await readRunnerEventsAsync(files.eventsPath) - expect(event?.type).toBe('spawn-error') - if (event?.type !== 'spawn-error') throw new Error('expected spawn error') - expect(event.error).toMatchObject({ - code: 'ENOENT', - syscall: 'spawn missing.exe', - path: 'missing.exe', - spawnargs: ['literal argument'], - }) - expect(event.error.message).not.toContain('cwd restore failed') - } finally { - cleanupRunnerFiles(files) - } - }) - - it.each([ - [undefined, false], - ['ENOENT', true], - ] as const)('maps a target chdir failure with code %s', async (code, hasSpawnShape) => { - const files = createRunnerFiles({ argv: ['tool.exe', 'arg'], cwd: 'C:\\missing', env: {} }) - const host = new FakeRunnerHost() - const error = Object.assign(new Error('target cwd failed'), { - syscall: 'chdir', - ...code === undefined ? {} : { code }, - }) - host.chdir = vi.fn(() => { throw error }) - try { - await runSpawnRunner( - win32RunnerArgs(files.requestPath, files.eventsPath), - asRunnerHost(host), - fakeRunnerInternals(), - ) - expect(host.exitCode).toBeUndefined() - const [event] = await readRunnerEventsAsync(files.eventsPath) - expect(event?.type).toBe('spawn-error') - if (event?.type !== 'spawn-error') throw new Error('expected spawn error') - expect(typeof event.error.message).toBe('string') - expect('path' in event.error).toBe(hasSpawnShape) - if (hasSpawnShape) { - expect(event.error).toMatchObject({ - code: 'ENOENT', - syscall: 'spawn tool.exe', - path: 'tool.exe', - spawnargs: ['arg'], - }) - } else { - expect(event.error).toMatchObject({ message: 'target cwd failed', syscall: 'chdir' }) - } - } finally { - cleanupRunnerFiles(files) - } - }) - - it.each([ - ['a non-CreateProcess Win32 error', new Win32Error('CreateFileW', 5), 'Win32Error'], - ['a non-Error setup failure', 'raw pipe setup failure', 'Error'], - ])('reports %s as runner infrastructure failure', async (_label, failure, name) => { - const files = createRunnerFiles({ argv: ['tool.exe'], cwd: 'C:\\target', env: {} }) - const host = new FakeRunnerHost() - const internals = fakeRunnerInternals({ - openNamedPipeForStdio: vi.fn(() => { throw failure }), - }) - try { - await runSpawnRunner(win32RunnerArgs(files.requestPath, files.eventsPath, [ - '--stdin-pipe', '\\\\.\\pipe\\stdin', - ]), asRunnerHost(host), internals) - expect(host.exitCode).toBe(127) - const [event] = await readRunnerEventsAsync(files.eventsPath) - expect(event?.type).toBe('runner-error') - if (event?.type !== 'runner-error') throw new Error('expected runner error') - expect(event.error.name).toBe(name) - } finally { - cleanupRunnerFiles(files) - } - }) - - it.each([ - ['an Error', new Error('stdio close failed')], - ['a non-Error value', 'raw stdio close failure'], - ])('reports %s from the initial stdio close and retries cleanup', async (_label, failure) => { - const files = createRunnerFiles({ argv: ['tool.exe'], cwd: 'C:\\target', env: {} }) - let failedOnce = false - const closeHandleChecked = vi.fn((_api, _handle, label: string) => { - if (!failedOnce && label.includes('pipe')) { - failedOnce = true - throw failure - } - }) - const internals = fakeRunnerInternals({ closeHandleChecked }) - try { - await runSpawnRunner(win32RunnerArgs(files.requestPath, files.eventsPath, [ - '--stdin-pipe', '\\\\.\\pipe\\stdin', - ]), asRunnerHost(new FakeRunnerHost()), internals) - expect(await readRunnerEventsAsync(files.eventsPath)).toEqual([ - { type: 'started', pid: 1234 }, - { - type: 'runner-error', - error: { name: 'Error', message: failure instanceof Error ? failure.message : failure }, - }, - ]) - expect(closeHandleChecked).toHaveBeenCalledWith( - fakeWin32Api, - 70n, - 'ordinary target stdin pipe', - ) - expect(closeHandleChecked).toHaveBeenCalledWith( - fakeWin32Api, - 70n, - 'ordinary target stdin pipe', - ) - } finally { - cleanupRunnerFiles(files) - } - }) - - it('preserves the first stdio close failure while retaining every failed handle', async () => { - const files = createRunnerFiles({ argv: ['tool.exe'], cwd: 'C:\\target', env: {} }) - let remainingFailures = 2 - const closeHandleChecked = vi.fn((_api, _handle, label: string) => { - if (remainingFailures > 0 && label.includes('pipe')) { - remainingFailures -= 1 - throw remainingFailures === 1 ? new Error('first close failure') : 'second close failure' - } - }) - const internals = fakeRunnerInternals({ closeHandleChecked }) - try { - await runSpawnRunner(win32RunnerArgs(files.requestPath, files.eventsPath, [ - '--stdin-pipe', '\\\\.\\pipe\\stdin', - '--stdout-pipe', '\\\\.\\pipe\\stdout', - ]), asRunnerHost(new FakeRunnerHost()), internals) - expect(await readRunnerEventsAsync(files.eventsPath)).toContainEqual({ - type: 'runner-error', - error: { name: 'Error', message: 'first close failure' }, - }) - expect(closeHandleChecked).toHaveBeenCalledTimes(6) - } finally { - cleanupRunnerFiles(files) - } - }) - - it.each([ - ['poll', 'poll failed'], - ['direct close', 'direct close failed'], - ['Job query', 'Job query failed'], - ['Job close', 'Job close failed'], - ] as const)('reports a Win32 %s failure and cleans remaining handles', async (stage, message) => { - vi.useFakeTimers() - const files = createRunnerFiles({ argv: ['tool.exe'], cwd: 'C:\\target', env: {} }) - const pollProcessExit = vi.fn(() => { - if (stage === 'poll') throw new Error(message) - return 0 - }) - const isJobEmpty = vi.fn(() => { - if (stage === 'Job query') throw new Error(message) - return true - }) - const closeHandleChecked = vi.fn((_api, _handle, label: string) => { - if (stage === 'direct close' && label === 'ordinary direct process') { - throw new Error(message) - } - if (stage === 'Job close' && label === 'ordinary process Job') { - throw new Error(message) - } - if (label.endsWith('cleanup')) throw new Error('ignored cleanup failure') - }) - const internals = fakeRunnerInternals({ pollProcessExit, isJobEmpty, closeHandleChecked }) - try { - const running = runSpawnRunner( - win32RunnerArgs(files.requestPath, files.eventsPath), - asRunnerHost(new FakeRunnerHost()), - internals, - ) - await vi.advanceTimersByTimeAsync(10) - await running - - expect(await readRunnerEventsAsync(files.eventsPath)).toEqual([ - { type: 'started', pid: 1234 }, - ...stage === 'poll' ? [] : [{ type: 'exit' as const, exitCode: 0, signal: null }], - { type: 'runner-error', error: { name: 'Error', message } }, - ]) - expect(closeHandleChecked).toHaveBeenCalledWith( - fakeWin32Api, - fakeJobHandle, - expect.stringContaining('Job'), - ) - } finally { - vi.useRealTimers() - cleanupRunnerFiles(files) - } - }) - - it('preserves the first failure when termination settles reentrantly during polling', async () => { - vi.useFakeTimers() - const files = createRunnerFiles({ argv: ['tool.exe'], cwd: 'C:\\target', env: {} }) - const host = new FakeRunnerHost() - const terminateJob = vi.fn(() => { throw new Error('reentrant termination failed') }) - const pollProcessExit = vi.fn(() => { - host.emit('disconnect') - return 0 - }) - const internals = fakeRunnerInternals({ terminateJob, pollProcessExit }) - try { - const running = runSpawnRunner( - win32RunnerArgs(files.requestPath, files.eventsPath), - asRunnerHost(host), - internals, - ) - await vi.advanceTimersByTimeAsync(10) - await running - - expect(await readRunnerEventsAsync(files.eventsPath)).toEqual([ - { type: 'started', pid: 1234 }, - { type: 'exit', exitCode: 0, signal: null }, - { - type: 'runner-error', - error: { name: 'Error', message: 'reentrant termination failed' }, - }, - ]) - } finally { - vi.useRealTimers() - cleanupRunnerFiles(files) - } - }) - - it('reports failure while restoring cwd after a successful Win32 spawn', async () => { - const files = createRunnerFiles({ argv: ['tool.exe'], cwd: 'C:\\target', env: {} }) - const host = new FakeRunnerHost() - host.directory = 'C:\\runner' - const chdir = vi.fn((directory: string) => { - if (directory === 'C:\\runner') throw new Error('cwd restore failed') - host.directory = directory - }) - host.chdir = chdir - try { - await runSpawnRunner( - win32RunnerArgs(files.requestPath, files.eventsPath), - asRunnerHost(host), - fakeRunnerInternals(), - ) - expect(chdir).toHaveBeenCalledTimes(2) - expect(host.exitCode).toBe(127) - expect(await readRunnerEventsAsync(files.eventsPath)).toEqual([ - { type: 'started', pid: 1234 }, - { type: 'runner-error', error: { name: 'Error', message: 'cwd restore failed' } }, - ]) - } finally { - cleanupRunnerFiles(files) - } - }) - - it('disconnects after an uncaught Win32 binding setup failure', async () => { - const files = createRunnerFiles({ argv: ['tool.exe'], cwd: 'C:\\target', env: {} }) - const host = new FakeRunnerHost() - host.connected = true - const internals = fakeRunnerInternals({ - loadWin32ProcessBindings: vi.fn(() => { throw new Error('binding setup failed') }), - }) - try { - await expect(runSpawnRunner( - win32RunnerArgs(files.requestPath, files.eventsPath), - asRunnerHost(host), - internals, - )).rejects.toThrow('binding setup failed') - expect(host.disconnect).toHaveBeenCalledOnce() - expect(await readRunnerEventsAsync(files.eventsPath)).toEqual([]) - } finally { - cleanupRunnerFiles(files) - } - }) - - it.each([ - [['--mode'], 'missing value'], - [['--unknown', 'value'], 'unknown argument'], - [['--mode', 'unknown'], 'unknown mode'], - [['--mode', 'node'], 'requires request and event paths'], - ] as const)('rejects invalid runner arguments: %s', async (argv, message) => { - await expect(runSpawnRunner([...argv], asRunnerHost(new FakeRunnerHost()))).rejects.toThrow(message) - }) - - it('reports only failures whose arguments identify an event transport', async () => { - const files = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - reportSpawnRunnerFailure([ - '--mode', 'node', - '--request', files.requestPath, - '--events', files.eventsPath, - ], new Error('runner main failed')) - reportSpawnRunnerFailure(['--mode', 'probe-node'], new Error('ignored probe failure')) - reportSpawnRunnerFailure(['--mode'], new Error('unparseable failure')) - expect(await readRunnerEventsAsync(files.eventsPath)).toEqual([ - { type: 'runner-error', error: { name: 'Error', message: 'runner main failed' } }, - ]) - } finally { - cleanupRunnerFiles(files) - } - }) - - it('maps every target stdio disposition', () => { - expect(runnerStdio(spec())).toEqual(['ignore', 'pipe', 'pipe']) - expect(runnerStdio(spec({ - stdio: { stdin: { data: 'input' }, stdout: 'inherit', stderr: 'inherit' }, - }))).toEqual(['pipe', 'inherit', 'inherit']) - }) - - it('materializes and consumes the exact runner request once', () => { - const removed = `DSH_RUNNER_REMOVED_${process.pid}` - const files = runnerFiles(spec({ - argv: [process.execPath, 'literal $HOME'], - env: { RUNNER_VALUE: 'explicit', [removed]: undefined }, - })) - try { - const request = consumeRunnerRequest(files.requestPath) - expect(request.argv).toEqual([process.execPath, 'literal $HOME']) - expect(request.cwd).toBe(process.cwd()) - expect(request.env.RUNNER_VALUE).toBe('explicit') - expect(request.env).not.toHaveProperty(removed) - expect(existsSync(files.requestPath)).toBe(false) - } finally { - cleanupRunnerFiles(files) - } - }) - - it.each([ - ['non-object request', null, 'no executable'], - ['non-array argv', { argv: 'node', cwd: '.', env: {} }, 'no executable'], - ['empty argv', { argv: [], cwd: '.', env: {} }, 'no executable'], - ['non-string argv', { argv: [1], cwd: '.', env: {} }, 'no executable'], - ['non-string cwd', { argv: ['node'], cwd: 1, env: {} }, 'invalid cwd or environment'], - ['non-record env', { argv: ['node'], cwd: '.', env: [] }, 'invalid cwd or environment'], - ['non-string env value', { argv: ['node'], cwd: '.', env: { VALUE: 1 } }, 'invalid cwd or environment'], - ])('rejects an invalid %s', (_label, request, message) => { - const files = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - writeFileSync(files.requestPath, JSON.stringify(request)) - expect(() => consumeRunnerRequest(files.requestPath)).toThrow(message) - } finally { - cleanupRunnerFiles(files) - } - }) - - it('unlinks a substituted runner-directory link without traversing it', () => { - const files = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - const outside = mkdtempSync(join(tmpdir(), 'dsh-runner-outside-')) - const sentinel = join(outside, 'events.ndjson') - writeFileSync(sentinel, 'keep') - rmSync(files.directory, { recursive: true, force: true }) - symlinkSync(outside, files.directory, process.platform === 'win32' ? 'junction' : 'dir') - try { - cleanupRunnerFiles(files) - expect(existsSync(files.directory)).toBe(false) - expect(existsSync(sentinel)).toBe(true) - } finally { - rmSync(files.directory, { recursive: true, force: true }) - rmSync(outside, { recursive: true, force: true }) - } - }) - - it('contains an unexpected owned-path cleanup failure', () => { - const files = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - rmSync(files.requestPath, { force: true }) - mkdirSync(files.requestPath) - try { - expect(() => { cleanupRunnerFiles(files) }).not.toThrow() - expect(existsSync(files.directory)).toBe(true) - } finally { - rmSync(files.directory, { recursive: true, force: true }) - } - }) - - it('reads only complete known event records and propagates file errors', async () => { - const files = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - await expect(readRunnerEventsAsync(files.eventsPath)).resolves.toEqual([]) - await expect(readRunnerEventsAsync(join(files.directory, 'missing.ndjson'))).resolves.toEqual([]) - appendRunnerEvent(files.eventsPath, { type: 'started', pid: 123 }) - appendRunnerEvent(files.eventsPath, { - type: 'runner-error', - error: { name: 'Error', message: 'runner failed' }, - }) - appendRunnerEvent(files.eventsPath, { type: 'exit', exitCode: null, signal: 'SIGTERM' }) - appendRunnerEvent(files.eventsPath, { - type: 'spawn-error', - error: { - name: 'Error', - message: 'spawn failed', - code: 'ENOENT', - errno: -2, - syscall: 'spawn missing', - path: 'missing', - spawnargs: ['argument'], - }, - }) - await expect(readRunnerEventsAsync(files.eventsPath)).resolves.toEqual([ - { type: 'started', pid: 123 }, - { type: 'runner-error', error: { name: 'Error', message: 'runner failed' } }, - { type: 'exit', exitCode: null, signal: 'SIGTERM' }, - { - type: 'spawn-error', - error: { - name: 'Error', - message: 'spawn failed', - code: 'ENOENT', - errno: -2, - syscall: 'spawn missing', - path: 'missing', - spawnargs: ['argument'], - }, - }, - ]) - writeFileSync(files.eventsPath, '{"type":"started","pid":123}\n{"type":"exit"') - await expect(readRunnerEventsAsync(files.eventsPath)).resolves.toEqual([{ type: 'started', pid: 123 }]) - for (const event of [null, []]) { - writeFileSync(files.eventsPath, `${JSON.stringify(event)}\n`) - await expect(readRunnerEventsAsync(files.eventsPath)).rejects.toThrow('emitted invalid event') - } - writeFileSync(files.eventsPath, '{"type":"unknown"}\n') - await expect(readRunnerEventsAsync(files.eventsPath)).rejects.toThrow('emitted unknown event') - await expect(readRunnerEventsAsync(files.directory)).rejects.toThrow() - } finally { - cleanupRunnerFiles(files) - } - }) - - it.each([ - ['started without a pid', { type: 'started' }], - ['started with a non-number pid', { type: 'started', pid: '1' }], - ['started with a fractional pid', { type: 'started', pid: 1.5 }], - ['started with a non-positive pid', { type: 'started', pid: 0 }], - ['exit with a missing code', { type: 'exit', signal: null }], - ['exit with a non-number code', { type: 'exit', exitCode: '0', signal: null }], - ['exit with a fractional code', { type: 'exit', exitCode: 1.5, signal: null }], - ['exit with a negative code', { type: 'exit', exitCode: -1, signal: null }], - ['exit with a non-string signal', { type: 'exit', exitCode: 0, signal: 9 }], - ['exit with an unknown signal', { type: 'exit', exitCode: 0, signal: 'NOT_A_SIGNAL' }], - ['spawn error without an object', { type: 'spawn-error', error: null }], - ['spawn error without a name', { type: 'spawn-error', error: { message: 'failed' } }], - ['spawn error without a message', { type: 'spawn-error', error: { name: 'Error' } }], - ['spawn error with a numeric code', { type: 'spawn-error', error: { name: 'Error', message: 'failed', code: 1 } }], - ['spawn error with a string errno', { type: 'spawn-error', error: { name: 'Error', message: 'failed', errno: '1' } }], - ['spawn error with a numeric syscall', { type: 'spawn-error', error: { name: 'Error', message: 'failed', syscall: 1 } }], - ['spawn error with a numeric path', { type: 'spawn-error', error: { name: 'Error', message: 'failed', path: 1 } }], - ['spawn error with non-array args', { type: 'spawn-error', error: { name: 'Error', message: 'failed', spawnargs: 'arg' } }], - ['spawn error with non-string args', { type: 'spawn-error', error: { name: 'Error', message: 'failed', spawnargs: [1] } }], - ])('rejects an invalid event payload: %s', async (_label, event) => { - const files = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - writeFileSync(files.eventsPath, `${JSON.stringify(event)}\n`) - await expect(readRunnerEventsAsync(files.eventsPath)).rejects.toThrow('emitted invalid event') - } finally { - cleanupRunnerFiles(files) - } - }) - - it('creates private request files and preserves Node-shaped error fields', () => { - const files = createRunnerFiles({ argv: [process.execPath], cwd: process.cwd(), env: {} }) - try { - if (process.platform !== 'win32') expect(statSync(files.requestPath).mode & 0o777).toBe(0o600) - const source = Object.assign(new Error('spawn missing ENOENT'), { - code: 'ENOENT', - errno: -2, - syscall: 'spawn missing', - path: 'missing', - spawnargs: ['literal $VALUE'], - }) - const restored = deserializeSpawnError(serializeSpawnError(source)) as NodeJS.ErrnoException & { - path?: string - spawnargs?: string[] - } - expect(restored).toMatchObject({ - message: 'spawn missing ENOENT', - code: 'ENOENT', - errno: -2, - syscall: 'spawn missing', - path: 'missing', - spawnargs: ['literal $VALUE'], - }) - const minimal = serializeSpawnError('plain failure') - expect(minimal).toEqual({ name: 'Error', message: 'plain failure' }) - expect(deserializeSpawnError(minimal)).toMatchObject({ name: 'Error', message: 'plain failure' }) - } finally { - cleanupRunnerFiles(files) - } - }) - - it('maps runner failures and missing direct results', async () => { - const runnerFailure = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - appendRunnerEvent(runnerFailure.eventsPath, { - type: 'runner-error', - error: { name: 'Error', message: 'runner setup failed', code: 'EIO' }, - }) - const result = runnerDirectResult(fakeChild(123), runnerFailure, new Promise(() => {})) - expect(result.pid).toBeUndefined() - await expect(result.direct).rejects.toMatchObject({ message: 'runner setup failed', code: 'EIO' }) - } finally { - cleanupRunnerFiles(runnerFailure) - } - - const afterStartFailure = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - appendRunnerEvent(afterStartFailure.eventsPath, { type: 'started', pid: 456 }) - const result = runnerDirectResult(fakeChild(123), afterStartFailure, new Promise(() => {})) - const directFailure = result.direct.catch((error: unknown) => error) - appendRunnerEvent(afterStartFailure.eventsPath, { - type: 'runner-error', - error: { name: 'Error', message: 'post-start runner failed', code: 'EIO' }, - }) - await vi.waitFor(() => { expect(result.pid).toBe(456) }) - await expect(directFailure).resolves.toMatchObject({ message: 'post-start runner failed', code: 'EIO' }) - } finally { - cleanupRunnerFiles(afterStartFailure) - } - - const missing = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - appendRunnerEvent(missing.eventsPath, { type: 'started', pid: 456 }) - const result = runnerDirectResult(fakeChild(123), missing, Promise.resolve()) - await vi.waitFor(() => { expect(result.pid).toBe(456) }) - await expect(result.direct).rejects.toThrow('exited without a direct-command result') - } finally { - cleanupRunnerFiles(missing) - } - - }) - - it('publishes terminal events already present when asynchronous observation starts', async () => { - const failed = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - appendRunnerEvent(failed.eventsPath, { - type: 'spawn-error', - error: { name: 'Error', message: 'target missing', code: 'ENOENT' }, - }) - const result = runnerDirectResult(fakeChild(123), failed, new Promise(() => {})) - await expect(result.direct).rejects.toMatchObject({ message: 'target missing', code: 'ENOENT' }) - } finally { - cleanupRunnerFiles(failed) - } - - const exited = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - appendRunnerEvent(exited.eventsPath, { type: 'started', pid: 456 }) - appendRunnerEvent(exited.eventsPath, { type: 'exit', exitCode: 23, signal: null }) - const result = runnerDirectResult(fakeChild(123), exited, new Promise(() => {})) - await expect(result.direct).resolves.toEqual({ exitCode: 23, signal: null }) - expect(result.pid).toBe(456) - } finally { - cleanupRunnerFiles(exited) - } - }) - - it('requires an event snapshot started after wrapper exit before reporting a missing result', async () => { - const staleRead = Promise.withResolvers>>() - let readCount = 0 - vi.resetModules() - vi.doMock('../src/runner-protocol.ts', async (importOriginal) => { - const actual = await importOriginal() - return { - ...actual, - readRunnerEventsAsync: vi.fn(async (eventsPath: string) => { - readCount += 1 - if (readCount === 1) return staleRead.promise - return actual.readRunnerEventsAsync(eventsPath) - }), - } - }) - const files = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - appendRunnerEvent(files.eventsPath, { type: 'started', pid: 456 }) - const exited = Promise.withResolvers() - const isolated = await import('../src/runner-launch.ts') - const result = isolated.runnerDirectResult(fakeChild(123), files, exited.promise) - expect(readCount).toBe(1) - exited.resolve(undefined) - await Promise.resolve() - appendRunnerEvent(files.eventsPath, { type: 'exit', exitCode: 0, signal: null }) - staleRead.resolve([{ type: 'started', pid: 456 }]) - await expect(result.direct).resolves.toEqual({ exitCode: 0, signal: null }) - expect(readCount).toBe(2) - } finally { - cleanupRunnerFiles(files) - vi.doUnmock('../src/runner-protocol.ts') - vi.resetModules() - } - }) - - it('reports a missing direct result at runner exit without waiting for pipe close', async () => { - const files = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - appendRunnerEvent(files.eventsPath, { type: 'started', pid: 456 }) - const child = new EventEmitter() as ChildProcess - Object.assign(child, { pid: 123, exitCode: null, signalCode: null }) - const lifecycle = observeChildLifecycle(child) - const result = runnerDirectResult(child, files, lifecycle.exited) - child.emit('exit', 1, null) - await expect(result.direct).rejects.toThrow('exited without a direct-command result') - child.emit('close', 1, null) - await lifecycle.closed - } finally { - cleanupRunnerFiles(files) - } - }) - - it('contains wrapper spawn errors while publishing the runner startup rejection', async () => { - const files = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - const child = spawn(`missing-dsh-native-runner-${String(process.pid)}-${String(Date.now())}`, [], { - stdio: 'ignore', - }) - const lifecycle = observeChildLifecycle(child) - const result = runnerDirectResult(child, files, lifecycle.exited) - expect(result.pid).toBeUndefined() - await expect(result.direct).rejects.toThrow('runner failed to start') - await expect(lifecycle.closed).resolves.toBeUndefined() - } finally { - cleanupRunnerFiles(files) - } - }) - - it('returns before target publication and updates the pid getter from runner events', async () => { - const files = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - try { - const result = runnerDirectResult(fakeChild(process.pid), files, new Promise(() => {})) - expect(result.pid).toBeUndefined() - appendRunnerEvent(files.eventsPath, { type: 'started', pid: 456 }) - await vi.waitFor(() => { expect(result.pid).toBe(456) }) - appendRunnerEvent(files.eventsPath, { type: 'exit', exitCode: 0, signal: null }) - await expect(result.direct).resolves.toEqual({ exitCode: 0, signal: null }) - } finally { - cleanupRunnerFiles(files) - } - }) - - it('cleans runner files only after the direct result and runner close settle', async () => { - const files = createRunnerFiles({ argv: ['node'], cwd: '.', env: {} }) - const closed = Promise.withResolvers() - cleanupAfterRunner(files, Promise.resolve({ exitCode: 0, signal: null }), closed.promise) - await new Promise(resolve => setImmediate(resolve)) - expect(existsSync(files.directory)).toBe(true) - closed.resolve(undefined) - await new Promise(resolve => setImmediate(resolve)) + writeFileSync(join(files.directory, '.startup-error.tmp'), 'incomplete') + cleanupLinuxLaunchFiles(files) expect(existsSync(files.directory)).toBe(false) }) - it('reports the direct target pid and exit outcome from the source entry', async () => { - const files = createRunnerFiles({ - argv: [process.execPath, '-e', 'process.exit(7)'], - cwd: process.cwd(), - env: {}, - }) + it('removes the private directory when request creation fails partway through', () => { + const isolatedTmp = mkdtempSync(join(tmpdir(), 'dsh-launch-failure-spec-')) + vi.stubEnv('TMPDIR', isolatedTmp) + vi.stubEnv('TMP', isolatedTmp) + vi.stubEnv('TEMP', isolatedTmp) try { - const result = runRunner(sourceInvocation, files.requestPath, files.eventsPath) - expect(result.error).toBeUndefined() - const events = await readRunnerEventsAsync(files.eventsPath) - expect(events).toHaveLength(2) - expect(events[0]?.type).toBe('started') - if (events[0]?.type !== 'started') throw new Error('expected started event') - expect(events[0].pid).toBeGreaterThan(0) - expect(events[1]).toEqual({ type: 'exit', exitCode: 7, signal: null }) + const stringify = vi.spyOn(JSON, 'stringify').mockImplementationOnce(() => { + throw new Error('request serialization failed') + }) + expect(() => createLinuxLaunchFiles({ cwd: '/target', env: {} })).toThrow('request serialization failed') + stringify.mockRestore() + expect(readdirSync(isolatedTmp)).toEqual([]) } finally { - cleanupRunnerFiles(files) + vi.unstubAllEnvs() + rmSync(isolatedTmp, { recursive: true, force: true }) } }) - it('preserves literal argv, cwd, and the exact target environment', () => { - const files = createRunnerFiles({ - argv: [ - process.execPath, - '-e', - 'console.log(JSON.stringify({ cwd: process.cwd(), value: process.env.RUNNER_VALUE, arg: process.argv[1] }))', - 'literal $HOME ${UNCHANGED}', - ], - cwd: process.cwd(), - env: { RUNNER_VALUE: 'explicit' }, + it('strictly rejects malformed Linux and Windows messages', () => { + const files = track(createLinuxLaunchFiles({ cwd: '/ok', env: {} })) + writeFileSync(files.requestPath, JSON.stringify({ cwd: '/ok', env: {}, extra: true })) + expect(() => consumeLinuxLaunchRequest(files.requestPath)).toThrow('invalid Linux launch request') + expect(() => linuxLaunchFilesFromLocator('relative.json')).toThrow('invalid Linux launch-request locator') + expect(readLinuxStartupError(files.startupErrorPath)).toBeUndefined() + writeFileSync(files.startupErrorPath, 'null') + expect(() => readLinuxStartupError(files.startupErrorPath)).toThrow('invalid startup error') + writeFileSync(files.startupErrorPath, JSON.stringify({ + type: 'unknown', error: { name: 'Error', message: 'bad' }, + })) + expect(() => readLinuxStartupError(files.startupErrorPath)).toThrow('unknown error result') + + expect(parseWindowsStartRequest({ type: 'start', cwd: 'C:\\x', env: { A: '1' } })).toEqual({ + type: 'start', cwd: 'C:\\x', env: { A: '1' }, }) - try { - const result = runRunner(sourceInvocation, files.requestPath, files.eventsPath) - expect(result.status).toBe(0) - expect(result.stdout.trim()).toBe(JSON.stringify({ - cwd: process.cwd(), - value: 'explicit', - arg: 'literal $HOME ${UNCHANGED}', - })) - } finally { - cleanupRunnerFiles(files) - } + expect(() => parseWindowsStartRequest({ type: 'start', cwd: 'C:\\x', env: {}, extra: 1 })).toThrow() + expect(isWindowsTerminateRequest({ type: 'terminate' })).toBe(true) + expect(isWindowsTerminateRequest({ type: 'terminate', reason: 'no' })).toBe(false) + expect(parseWindowsRunnerResult({ type: 'start-cancelled' })).toEqual({ type: 'start-cancelled' }) + expect(parseWindowsRunnerResult({ type: 'target-exit', exitCode: null, signal: 'SIGTERM' })).toEqual({ + type: 'target-exit', exitCode: null, signal: 'SIGTERM', + }) + expect(parseWindowsRunnerResult({ type: 'spawn-error', error: { name: 'Error', message: 'bad' } })).toEqual({ + type: 'spawn-error', error: { name: 'Error', message: 'bad' }, + }) + for (const invalid of [ + null, + { type: 'unknown' }, + { type: 'start-cancelled', payload: 1 }, + { type: 'target-exit', exitCode: -1, signal: null }, + { type: 'target-exit', exitCode: 0, signal: 'NOPE' }, + { type: 'runner-error', error: { name: 'Error', message: 'bad', cause: {} } }, + ]) expect(() => parseWindowsRunnerResult(invalid)).toThrow() }) - it('reports target spawn failure without executing a fallback command', async () => { - const files = createRunnerFiles({ - argv: [`missing-dsh-runner-${Date.now()}`], - cwd: process.cwd(), - env: {}, - }) - try { - const result = runRunner(sourceInvocation, files.requestPath, files.eventsPath) - expect(result.error).toBeUndefined() - const events = await readRunnerEventsAsync(files.eventsPath) - expect(events).toHaveLength(1) - expect(events[0]).toMatchObject({ type: 'spawn-error', error: { code: 'ENOENT' } }) - } finally { - cleanupRunnerFiles(files) - } - }) + it('contains cleanup failures and removes a substituted symlink only', () => { + const files = track(createLinuxLaunchFiles({ cwd: '/ok', env: {} })) + cleanupLinuxLaunchFiles(files) + cleanupLinuxLaunchFiles(files) + const target = join(tmpdir(), `dsh-runner-cleanup-target-${String(process.pid)}`) + const link = join(tmpdir(), `dsh-runner-cleanup-link-${String(process.pid)}`) + scratch.push(target, link) + mkdirSync(target, { recursive: true }) + symlinkSync(target, link) + cleanupLinuxLaunchFiles({ + directory: link, + requestPath: join(link, 'launch-request.json'), + startupErrorPath: join(link, 'startup-error.json'), + }) + expect(existsSync(link)).toBe(false) + expect(existsSync(target)).toBe(true) + + const blocked = track(createLinuxLaunchFiles({ cwd: '/ok', env: {} })) + unlinkSync(blocked.requestPath) + mkdirSync(blocked.requestPath) + cleanupLinuxLaunchFiles(blocked) + expect(existsSync(blocked.directory)).toBe(true) + }) +}) + +describe('runner launch inputs', () => { + const spec = { + argv: ['node', 'a'], + cwd: process.cwd(), + stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'inherit' }, + graceMs: 100, + env: { EXPLICIT: 'yes' }, + } as const + + it('keeps target state out of the bootstrap environment and consumes its selector', () => { + const env = runnerEnvironment('/tmp/request') + expect(env[SUBPROCESS_RUNNER_ENV]).toBe('/tmp/request') + expect(env.SYSTEMD_LOG_TARGET).toBe('null') + expect(env.EXPLICIT).toBeUndefined() + expect(consumeRunnerSelection(env)).toBe('/tmp/request') + expect(env[SUBPROCESS_RUNNER_ENV]).toBeUndefined() + expect(consumeRunnerSelection({})).toBeUndefined() + expect(parseRunnerTargetArgv(['--', 'node', 'a'])).toEqual(['node', 'a']) + expect(() => parseRunnerTargetArgv(['node'])).toThrow('private -- delimiter') + expect(runnerStdio(spec, false)).toEqual(['pipe', 'pipe', 'inherit']) + expect(runnerStdio(spec, true)).toEqual(['pipe', 'pipe', 'inherit', 'ipc']) + expect(runnerStdio({ + ...spec, + stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'pipe' }, + }, false)).toEqual(['ignore', 'inherit', 'pipe']) + }) + + it('validates every Node-baseline NUL location before launch', () => { + expect(targetEnvironment(spec)).toMatchObject({ EXPLICIT: 'yes' }) + expect(validateTerminalTarget({ ...spec, rows: 24, cols: 80 })).toMatchObject({ EXPLICIT: 'yes' }) + for (const invalid of [ + { ...spec, argv: ['node\0'] }, + { ...spec, argv: ['node', 'a\0'] }, + { ...spec, cwd: 'bad\0cwd' }, + { ...spec, env: { 'BAD\0KEY': 'x' } }, + { ...spec, env: { BAD: 'x\0' } }, + ]) { + try { + targetEnvironment(invalid) + throw new Error('expected targetEnvironment to reject') + } catch (error) { + expect(error).toMatchObject({ name: 'TypeError', code: 'ERR_INVALID_ARG_VALUE' }) + } + } + }) + + it('resolves the source runner entry and checks concrete paths without executing it', () => { + const invocation = spawnRunnerInvocation() + expect(invocation[0]).toBe(process.execPath) + expect(invocation).toContain('tsx/esm') + expect(runnerInvocationAvailable(invocation)).toBe(true) + expect(runnerInvocationAvailable(['/definitely/missing-dsh-runner'])).toBe(false) + expect(runnerInvocationAvailable(['node'])).toBe(true) + expect(runnerInvocationAvailable(['node', 'runner.js'])).toBe(true) + + Object.defineProperty(process, 'pkg', { configurable: true, value: {} }) + try { + expect(spawnRunnerInvocation()).toEqual([process.execPath]) + } finally { + Reflect.deleteProperty(process, 'pkg') + } + }) + + it('bounds non-Error and stackless runner failures', () => { + expect(serializeRunnerError('plain failure')).toMatchObject({ + name: 'Error', message: 'plain failure', + }) + const stackless = new Error('stackless') + Reflect.deleteProperty(stackless, 'stack') + expect(serializeRunnerError(stackless)).toEqual({ name: 'Error', message: 'stackless' }) + const minimal = deserializeRunnerError({ name: 'Error', message: 'minimal' }) + expect(minimal).toMatchObject({ name: 'Error', message: 'minimal' }) + expect(minimal).not.toHaveProperty('code') + expect(minimal).not.toHaveProperty('errno') + expect(minimal).not.toHaveProperty('syscall') + expect(minimal).not.toHaveProperty('path') + expect(minimal).not.toHaveProperty('spawnargs') + }) +}) + +describe('Linux one-shot exec bootstrap', () => { + it('uses final cwd/env PATH while preserving the original argv', async () => { + const files = track(createLinuxLaunchFiles({ + cwd: '/final/work', + env: { PATH: 'relative::/absolute', [SUBPROCESS_RUNNER_ENV]: 'target-value' }, + })) + const host = new FakeRunnerHost() + const execve = vi.fn((_file: string, _argv: string[], _env: Record) => { + throw Object.assign(new Error('not found'), { code: 'ENOENT' }) + }) + await runSpawnRunner(files.requestPath, ['--', 'tool', 'literal arg'], hostArgument(host), internals({ execve })) + expect(host.directory).toBe('/final/work') + expect(host.env[SUBPROCESS_RUNNER_ENV]).toBeUndefined() + expect(execve.mock.calls.map(call => call[0])).toEqual([ + '/final/work/relative/tool', + '/final/work/tool', + '/absolute/tool', + ]) + expect(execve.mock.calls[0]?.[1]).toEqual(['tool', 'literal arg']) + expect(execve.mock.calls[0]?.[2]).toMatchObject({ [SUBPROCESS_RUNNER_ENV]: 'target-value' }) + expect(readLinuxStartupError(files.startupErrorPath)).toMatchObject({ + type: 'spawn-error', error: { code: 'ENOENT', path: 'tool' }, + }) + }) + + it('uses the default PATH and stops on a non-search error', async () => { + const files = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) + const execve = vi.fn((_file: string) => { throw Object.assign(new Error('denied'), { code: 'EACCES' }) }) + await runSpawnRunner(files.requestPath, ['--', 'tool'], hostArgument(new FakeRunnerHost()), internals({ execve })) + expect(execve.mock.calls.map(call => call[0])).toEqual(['/usr/bin/tool', '/bin/tool']) + expect(readLinuxStartupError(files.startupErrorPath)).toMatchObject({ type: 'spawn-error', error: { code: 'EACCES' } }) + + const explicit = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) + const fatal = vi.fn(() => { throw Object.assign(new Error('bad executable'), { code: 'EIO' }) }) + await runSpawnRunner(explicit.requestPath, ['--', './tool'], hostArgument(new FakeRunnerHost()), internals({ execve: fatal })) + expect(fatal).toHaveBeenCalledOnce() + + const stackless = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) + await runSpawnRunner(stackless.requestPath, ['--', './tool'], hostArgument(new FakeRunnerHost()), internals({ + execve: vi.fn(() => { throw new Error('unclassified failure') }), + })) + expect(readLinuxStartupError(stackless.startupErrorPath)).toMatchObject({ + type: 'spawn-error', error: { message: 'unclassified failure' }, + }) + + const searched = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) + const searchedExecve = vi.fn() + .mockImplementationOnce(() => { throw Object.assign(new Error('not a directory'), { code: 'ENOTDIR' }) }) + .mockImplementationOnce(() => { throw Object.assign(new Error('I/O failure'), { code: 'EIO' }) }) + await runSpawnRunner(searched.requestPath, ['--', 'tool'], hostArgument(new FakeRunnerHost()), internals({ + execve: searchedExecve as never, + })) + expect(readLinuxStartupError(searched.startupErrorPath)).toMatchObject({ + type: 'spawn-error', error: { code: 'EIO' }, + }) + }) + + it('publishes request/protocol failures as runner errors', async () => { + const files = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) + writeFileSync(files.requestPath, '{') + await runSpawnRunner(files.requestPath, ['--', 'tool'], hostArgument(new FakeRunnerHost()), internals()) + expect(readLinuxStartupError(files.startupErrorPath)).toMatchObject({ type: 'runner-error' }) + + const early = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) + await reportSpawnRunnerFailure(early.requestPath, new Error('delimiter failed'), hostArgument(new FakeRunnerHost())) + expect(readLinuxStartupError(early.startupErrorPath)).toMatchObject({ + type: 'runner-error', error: { message: 'delimiter failed' }, + }) + }) +}) + +describe('Windows Job runner protocol owner', () => { + it('maps the bounded Win32 process-creation error classes', async () => { + for (const [win32Code, code] of [ + [3, 'ENOENT'], + [267, 'ENOENT'], + [5, 'EACCES'], + [193, 'EFTYPE'], + [999, 'UNKNOWN'], + ] as const) { + const host = new FakeRunnerHost() + await runWindows(host, internals({ + spawnCurrentTokenJobProcess: vi.fn(() => { throw new Win32Error('CreateProcessW', win32Code) }), + })) + expect(host.sent).toMatchObject([{ type: 'spawn-error', error: { code } }]) + } + }) + + it('rejects a Windows runner without an initial IPC channel', async () => { + const disconnected = new FakeRunnerHost() + disconnected.connected = false + await runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe'], + hostArgument(disconnected), + internals(), + ) + expect(disconnected.exitCode).toBe(127) + + const missingSend = new FakeRunnerHost() + Object.defineProperty(missingSend, 'send', { value: undefined }) + await runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe'], + hostArgument(missingSend), + internals(), + ) + expect(missingSend.exitCode).toBe(127) + }) + + it('sends target-exit only after suspended Job launch and closes runner stdio', async () => { + const host = new FakeRunnerHost() + const native = internals() + await runWindows(host, native) + expect(native.spawnCurrentTokenJobProcess).toHaveBeenCalledWith(expect.anything(), { + command: 'tool.exe', args: ['literal arg'], cwd: 'C:\\target', + }) + expect(native.closeCurrentProcessStandardHandles).toHaveBeenCalledOnce() + expect(native.closeHandleChecked).toHaveBeenCalledWith(expect.anything(), 10n, 'ordinary direct process') + expect(native.closeHandleChecked).toHaveBeenCalledWith(expect.anything(), 20n, 'ordinary process Job') + expect(host.sent).toEqual([{ type: 'target-exit', exitCode: 0, signal: null }]) + expect(host.exitCode).toBe(0) + expect(host.env).toEqual({ TARGET: 'yes', dsh_subprocess_runner: 'restored' }) + }) + + it('exhausts spawn-error, runner-error, and payload-free start-cancelled', async () => { + const spawnHost = new FakeRunnerHost() + await runWindows(spawnHost, internals({ + spawnCurrentTokenJobProcess: vi.fn(() => { throw new Win32Error('CreateProcessW', 2) }), + })) + expect(spawnHost.sent).toMatchObject([{ type: 'spawn-error', error: { code: 'ENOENT', path: 'tool.exe' } }]) + expect(spawnHost.exitCode).toBe(0) + + const runnerHost = new FakeRunnerHost() + await runWindows(runnerHost, internals({ + loadWin32ProcessBindings: vi.fn(() => { throw new Error('binding failed') }), + })) + expect(runnerHost.sent).toMatchObject([{ type: 'runner-error', error: { message: 'binding failed' } }]) + expect(runnerHost.exitCode).toBe(127) + + const cancelledHost = new FakeRunnerHost() + const native = internals() + const running = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(cancelledHost), native) + cancelledHost.emit('message', { type: 'terminate' }) + cancelledHost.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await running + expect(cancelledHost.sent).toEqual([{ type: 'start-cancelled' }]) + expect(native.spawnCurrentTokenJobProcess).not.toHaveBeenCalled() + }) + + it('cancels after accepting start but before target commit', async () => { + const host = new FakeRunnerHost() + const native = internals() + const running = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(host), native) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + host.emit('message', { type: 'terminate' }) + await running + expect(host.sent).toEqual([{ type: 'start-cancelled' }]) + expect(native.spawnCurrentTokenJobProcess).not.toHaveBeenCalled() + }) + + it('does not create a target after pre-commit IPC disconnect', async () => { + const host = new FakeRunnerHost() + const native = internals() + const running = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(host), native) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + host.disconnect() + await running + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + expect(native.spawnCurrentTokenJobProcess).not.toHaveBeenCalled() + expect(native.terminateJob).not.toHaveBeenCalled() + expect(host.exitCode).toBe(127) + }) + + it('terminates and closes the unique Job immediately when IPC disconnects', async () => { + const host = new FakeRunnerHost() + const native = internals({ pollProcessExit: vi.fn(() => undefined), isJobEmpty: vi.fn(() => false) }) + const running = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(host), native) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + host.disconnect() + await running + expect(native.terminateJob).toHaveBeenCalledWith(expect.anything(), 20n, 1) + expect(native.closeHandleChecked).toHaveBeenCalledWith(expect.anything(), 20n, 'ordinary process Job cleanup') + expect(host.exitCode).toBe(127) + }) + + it('honors terminate after commit and treats result-send failure as infrastructure failure', async () => { + const host = new FakeRunnerHost() + const native = internals({ pollProcessExit: vi.fn(() => undefined), isJobEmpty: vi.fn(() => false) }) + const running = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(host), native) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + host.emit('message', { type: 'terminate' }) + host.emit('message', { type: 'terminate' }) + expect(native.terminateJob).toHaveBeenCalledWith(expect.anything(), 20n, 1) + host.disconnect() + await running + + const sendFailureHost = new FakeRunnerHost() + sendFailureHost.sendFailure = new Error('send failed') + const sendFailureNative = internals({ isJobEmpty: vi.fn(() => false) }) + await runWindows(sendFailureHost, sendFailureNative) + expect(sendFailureNative.terminateJob).toHaveBeenCalledWith(expect.anything(), 20n, 1) + expect(sendFailureNative.closeHandleChecked).toHaveBeenCalledWith( + expect.anything(), + 20n, + 'ordinary process Job cleanup', + ) + expect(sendFailureHost.exitCode).toBe(127) + }) + + it('handles commit-time termination reentrancy and termination failure', async () => { + const reentrantHost = new FakeRunnerHost() + const reentrant = internals({ + closeCurrentProcessStandardHandles: vi.fn(() => { + reentrantHost.emit('message', { type: 'terminate' }) + }), + pollProcessExit: vi.fn(() => undefined), + isJobEmpty: vi.fn(() => false), + }) + const reentrantRun = runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe'], + hostArgument(reentrantHost), + reentrant, + ) + reentrantHost.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + expect(reentrant.terminateJob).toHaveBeenCalledTimes(2) + reentrantHost.disconnect() + await reentrantRun + + const failedHost = new FakeRunnerHost() + const failed = internals({ + pollProcessExit: vi.fn(() => undefined), + isJobEmpty: vi.fn(() => false), + terminateJob: vi.fn(() => { throw new Error('terminate Job failed') }), + }) + const failedRun = runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe'], + hostArgument(failedHost), + failed, + ) + failedHost.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + failedHost.emit('message', { type: 'terminate' }) + await failedRun + expect(failedHost.sent).toMatchObject([{ type: 'runner-error', error: { message: 'terminate Job failed' } }]) + }) + + it('finishes when a later poll observes Job emptiness after result delivery', async () => { + const host = new FakeRunnerHost() + const native = internals({ + pollProcessExit: vi.fn().mockReturnValueOnce(0).mockReturnValue(undefined), + isJobEmpty: vi.fn().mockReturnValueOnce(false).mockReturnValue(true), + }) + const running = runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe'], + hostArgument(host), + native, + ) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await running + expect(host.sent).toEqual([{ type: 'target-exit', exitCode: 0, signal: null }]) + expect(native.isJobEmpty).toHaveBeenCalledTimes(2) + }) + + it('contains poll failures and queued ticks after disconnect', async () => { + const failedHost = new FakeRunnerHost() + await runWindows(failedHost, internals({ + pollProcessExit: vi.fn(() => { throw new Error('poll failed') }), + })) + expect(failedHost.sent).toMatchObject([{ type: 'runner-error', error: { message: 'poll failed' } }]) + + let tick: (() => void) | undefined + const interval = vi.spyOn(globalThis, 'setInterval').mockImplementation((callback: () => void) => { + tick = callback + return 1 as unknown as ReturnType + }) + try { + const host = new FakeRunnerHost() + const native = internals({ pollProcessExit: vi.fn(() => undefined), isJobEmpty: vi.fn(() => false) }) + const running = runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe'], + hostArgument(host), + native, + ) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + tick?.() + host.disconnect() + await running + tick?.() + } finally { + interval.mockRestore() + } + }) + + it('cleans a direct handle after the Job identity was already cleared', async () => { + const host = new FakeRunnerHost() + const native = internals({ pollProcessExit: vi.fn(() => undefined), isJobEmpty: vi.fn(() => true) }) + const running = runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe'], + hostArgument(host), + native, + ) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + host.emit('message', { type: 'terminate' }) + host.disconnect() + await running + expect(native.closeHandleChecked).toHaveBeenCalledWith( + expect.anything(), 10n, 'ordinary direct process cleanup', + ) + }) + + it('fails closed for malformed or duplicate start messages and disconnected reporting', async () => { + const malformed = new FakeRunnerHost() + await runWindows(malformed, internals(), { type: 'start', cwd: 'C:\\x', env: {}, extra: true }) + expect(malformed.sent).toMatchObject([{ type: 'runner-error' }]) + + const duplicate = new FakeRunnerHost() + const native = internals({ pollProcessExit: vi.fn(() => undefined), isJobEmpty: vi.fn(() => false) }) + const running = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(duplicate), native) + duplicate.emit('message', { type: 'start', cwd: 'C:\\x', env: {} }) + duplicate.emit('message', { type: 'start', cwd: 'C:\\x', env: {} }) + await running + expect(duplicate.sent).toMatchObject([{ type: 'runner-error' }]) + + const raced = new FakeRunnerHost() + const racedRun = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(raced), internals()) + const lateMessage = raced.listeners('message')[0] as ((value: unknown) => void) | undefined + const lateDisconnect = raced.listeners('disconnect')[0] as (() => void) | undefined + raced.emit('message', { type: 'bad' }) + raced.emit('message', { type: 'bad' }) + await racedRun + await Promise.resolve() + lateMessage?.({ type: 'bad' }) + lateDisconnect?.() + + const disconnected = new FakeRunnerHost() + disconnected.connected = false + await reportSpawnRunnerFailure(WINDOWS_RUNNER_SELECTION, new Error('early'), hostArgument(disconnected)) + expect(disconnected.exitCode).toBe(127) + + const connected = new FakeRunnerHost() + connected.sendThrown = new Error('synchronous send failure') + await reportSpawnRunnerFailure(WINDOWS_RUNNER_SELECTION, new Error('early'), hostArgument(connected)) + expect(connected.exitCode).toBe(127) + expect(connected.connected).toBe(false) + + const noSelection = new FakeRunnerHost() + await reportSpawnRunnerFailure(undefined, new Error('no selector'), hostArgument(noSelection)) + expect(noSelection.exitCode).toBe(127) + }) }) diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts index 8b54a6b3de..e839201d65 100644 --- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts +++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts @@ -3,6 +3,7 @@ import { tmpdir } from 'node:os' import { dirname, join } from 'node:path' import { describe, expect, it, vi } from 'vitest' import { + bindManagedProcess, childEnv, killGroup, OutputCollector, @@ -12,6 +13,7 @@ import { } from '../src/spawn.ts' import type { SubprocessHandle, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess' import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout' +import { waitWithAbort } from '../src/managed-owner.ts' /** * Translate the suite's POSIX command strings into node one-liners on Windows, @@ -252,13 +254,14 @@ describe('spawnSubprocess', () => { ...spec('unused', { graceMs }), argv: [process.execPath, '-e', childScript], }) - const rootPid = running.pid - if (rootPid === undefined) throw new Error('test child did not publish a pid') const helper = await waitForPidFile(pidFile) const realKill: typeof process.kill = process.kill.bind(process) + let rootPid: number | undefined let termAt = 0 let forceSignals = 0 const killSpy = vi.spyOn(process, 'kill').mockImplementation((target, signal) => { + if (typeof target !== 'number' || target >= 0) return realKill(target, signal) + rootPid ??= -target if (target !== -rootPid) return realKill(target, signal) if (signal === 'SIGTERM') { termAt = Date.now() @@ -589,9 +592,7 @@ describe('killGroup', () => { }) it('swallows ESRCH for vanished groups', async () => { - const running = spawnSubprocess(spec('true')) - await running.done - expect(() => { killGroup(running.pid, 'SIGTERM') }).not.toThrow() + expect(() => { killGroup(2 ** 30, 'SIGTERM') }).not.toThrow() }) }) @@ -649,7 +650,8 @@ describe('windows tree semantics (injected platform)', () => { }) running.terminateForHostExit() await running.done - expect(killed).toEqual([running.pid]) + expect(killed).toHaveLength(1) + expect(killed[0]).toBeGreaterThan(0) }) it('terminate routes through taskkill by root pid', async () => { @@ -669,7 +671,8 @@ describe('windows tree semantics (injected platform)', () => { }) running.terminate() const outcome = await running.done - expect(killed).toContain(running.pid) + expect(killed).toHaveLength(1) + expect(killed[0]).toBeGreaterThan(0) expect(outcome.signal).toBe(process.platform === 'win32' ? null : 'SIGKILL') }) @@ -775,6 +778,126 @@ describe.skipIf(process.platform === 'win32')('tree-survivor escalation (termina }) describe('coverage seams', () => { + it('cleans a managed owner after direct settlement and contains a later infrastructure failure', async () => { + const direct = Promise.withResolvers<{ exitCode: number; signal: null }>() + const stopped = Promise.withResolvers() + const infrastructureFailure = Promise.withResolvers() + const cleanup = vi.fn(() => { throw new Error('protocol cleanup failed') }) + const owner = { + signal: vi.fn(), + waitForExit: vi.fn(() => stopped.promise), + terminateForHostExit: vi.fn(), + cleanup, + } + const handle = bindManagedProcess(spec('true', { + stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, + }), { + stdin: null, + stdout: null, + stderr: null, + direct: direct.promise, + infrastructureFailure: infrastructureFailure.promise, + owner, + }) + + const waiting = handle.waitForExit() + stopped.resolve(undefined) + await expect(waiting).resolves.toBe(true) + expect(cleanup).not.toHaveBeenCalled() + + direct.resolve({ exitCode: 0, signal: null }) + await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) + await vi.waitFor(() => { expect(cleanup).toHaveBeenCalledOnce() }) + + infrastructureFailure.reject(new Error('late runner failure')) + await Promise.resolve() + await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) + }) + + it('does not deliver a stale escalation after range exit wins the timer race', async () => { + vi.useFakeTimers() + const clearTimer = vi.spyOn(globalThis, 'clearTimeout').mockImplementation(() => {}) + try { + const direct = Promise.withResolvers<{ exitCode: number; signal: null }>() + const stopped = Promise.withResolvers() + const signal = vi.fn() + const handle = bindManagedProcess(spec('true', { + graceMs: 10, + stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, + }), { + stdin: null, + stdout: null, + stderr: null, + direct: direct.promise, + owner: { + signal, + waitForExit: () => stopped.promise, + terminateForHostExit: vi.fn(), + }, + }) + + handle.terminate() + expect(signal).toHaveBeenCalledExactlyOnceWith('SIGTERM', expect.any(Error)) + stopped.resolve(undefined) + await expect(handle.waitForExit()).resolves.toBe(true) + await vi.advanceTimersByTimeAsync(10) + expect(signal).toHaveBeenCalledTimes(1) + + direct.resolve({ exitCode: 0, signal: null }) + await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) + } finally { + clearTimer.mockRestore() + vi.useRealTimers() + } + }) + + it('delivers an already-aborted managed spawn reason before target settlement', async () => { + const reason = new Error('caller cancelled') + const controller = new AbortController() + controller.abort(reason) + const signal = vi.fn() + const handle = bindManagedProcess(spec('true', { + signal: controller.signal, + stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, + }), { + stdin: null, + stdout: null, + stderr: null, + direct: Promise.resolve({ exitCode: 0, signal: null }), + owner: { + signal, + waitForExit: async () => {}, + terminateForHostExit: vi.fn(), + }, + }) + + expect(signal).toHaveBeenCalledExactlyOnceWith('SIGTERM', reason) + await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) + await expect(handle.waitForExit()).resolves.toBe(true) + }) + + it('contains a late wait rejection after an already-aborted observation', async () => { + const pending = Promise.withResolvers() + await expect(waitWithAbort(pending.promise, AbortSignal.abort())).resolves.toBe(false) + pending.reject(new Error('late observation failure')) + await Promise.resolve() + }) + + it('closes the abort-listener registration race', async () => { + let aborted = false + const removeEventListener = vi.fn() + const signal = { + get aborted() { return aborted }, + addEventListener(_type: string, listener: () => void) { + aborted = true + listener() + }, + removeEventListener, + } as unknown as AbortSignal + await expect(waitWithAbort(new Promise(() => {}), signal)).resolves.toBe(false) + expect(removeEventListener).toHaveBeenCalledOnce() + }) + it('taskkillProcessTree ignores an unpublished pid and contains a missing binary', () => { expect(() => { taskkillProcessTree(undefined) }).not.toThrow() // On POSIX there is no taskkill; spawnSync reports the failure in its @@ -792,13 +915,13 @@ describe('coverage seams', () => { platform: 'linux', linuxProcessGroupHasLiveMembers: () => false, }) - const rootPid = running.pid - if (rootPid === undefined) throw new Error('test child did not publish a pid') const realKill = process.kill.bind(process) + let rootPid: number | undefined const killSpy = vi.spyOn(process, 'kill').mockImplementation((target, signal) => { if (typeof target === 'number' && target < 0) { + rootPid ??= -target if (signal === 0) return true - if (signal === 'SIGKILL') realKill(rootPid, 'SIGKILL') + if (signal === 'SIGKILL') realKill(-target, 'SIGKILL') return true } return realKill(target, signal) @@ -814,11 +937,11 @@ describe('coverage seams', () => { it('treats a vanished group probe as quiescent without signalling', async () => { const running = spawnSubprocess(spec('sleep 60'), { platform: 'linux' }) - const rootPid = running.pid - if (rootPid === undefined) throw new Error('test child did not publish a pid') const realKill = process.kill.bind(process) + let rootPid: number | undefined const killSpy = vi.spyOn(process, 'kill').mockImplementation((target, signal) => { if (typeof target === 'number' && target < 0) { + rootPid ??= -target throw Object.assign(new Error('simulated absent group'), { code: 'ESRCH' }) } return realKill(target, signal) @@ -826,6 +949,7 @@ describe('coverage seams', () => { try { running.terminate() await new Promise(resolve => setTimeout(resolve, 20)) + if (rootPid === undefined) throw new Error('fallback owner did not probe its private process group') realKill(rootPid, 'SIGKILL') await running.done await expect(running.waitForExit()).resolves.toBe(true) @@ -836,11 +960,11 @@ describe('coverage seams', () => { it('treats an EPERM group probe as still alive', async () => { const running = spawnSubprocess(spec('sleep 60'), { platform: 'linux' }) - const rootPid = running.pid - if (rootPid === undefined) throw new Error('test child did not publish a pid') const realKill = process.kill.bind(process) + let rootPid: number | undefined const killSpy = vi.spyOn(process, 'kill').mockImplementation((target, signal) => { if (typeof target === 'number' && target < 0 && signal === 0) { + rootPid ??= -target throw Object.assign(new Error('simulated permission denial'), { code: 'EPERM' }) } return realKill(target, signal) @@ -849,6 +973,7 @@ describe('coverage seams', () => { await expect(running.waitForExit(AbortSignal.timeout(20))).resolves.toBe(false) } finally { killSpy.mockRestore() + if (rootPid === undefined) throw new Error('fallback owner did not probe its private process group') realKill(-rootPid, 'SIGKILL') await running.done } @@ -942,13 +1067,13 @@ describe('coverage seams', () => { await running.waitForExit() }) - it('waitForExit is immediate after host-exit finalization observes an absent tree', async () => { + it('host-exit finalization synchronously terminates until range absence is observed', async () => { const taskkill = vi.fn() const running = spawnSubprocess(spec('true'), { platform: 'win32', taskkill }) await running.done running.terminateForHostExit() await expect(running.waitForExit()).resolves.toBe(true) - expect(taskkill).not.toHaveBeenCalled() + expect(taskkill).toHaveBeenCalledOnce() }) it('repeated terminate after exit never probes or signals a reused process group', async () => { @@ -999,16 +1124,19 @@ describe('coverage seams 2', () => { await expect(running.waitForExit(aborted.signal)).resolves.toBe(false) // alive branch running.terminate() await running.done - expect(killedPid).toBe(running.pid) + expect(killedPid).toBeGreaterThan(0) await expect(running.waitForExit()).resolves.toBe(true) }) it('an inert win32 taskkill leaves the tree alive for a bounded wait to report', async () => { // An inert taskkill simulates a tree that never reports exit: terminate() // delivers nothing, so a bounded consumer wait must come back false. - const running = spawnSubprocess(spec('sleep 60'), { spillDir, platform: 'win32', taskkill: () => {} }) - const rootPid = running.pid - if (rootPid === undefined) throw new Error('test child did not publish a pid') + let rootPid: number | undefined + const running = spawnSubprocess(spec('sleep 60'), { + spillDir, + platform: 'win32', + taskkill: (pid) => { rootPid = pid }, + }) running.terminate() const bound = new AbortController() const timer = setTimeout(() => { bound.abort() }, 60) @@ -1016,6 +1144,7 @@ describe('coverage seams 2', () => { clearTimeout(timer) // Real cleanup: the injected platform spawned without detachment, so the // child is a plain (group-less) POSIX process — kill it directly. + if (rootPid === undefined) throw new Error('fallback owner did not call its private taskkill adapter') process.kill(rootPid, 'SIGKILL') await running.done }) diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts index 40b1a7f211..ffa34187d1 100644 --- a/packages/subprocess/subprocess-local/tests/terminal.spec.ts +++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts @@ -110,6 +110,7 @@ describe('LocalTerminalHandle', () => { } }, waitForExit: () => stopped.promise, + terminateForHostExit: vi.fn(), } const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10, 'linux', owner) @@ -134,6 +135,7 @@ describe('LocalTerminalHandle', () => { } }, waitForExit: () => stopped.promise, + terminateForHostExit: vi.fn(), } const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10, 'linux', owner) @@ -154,6 +156,7 @@ describe('LocalTerminalHandle', () => { const owner: BoundProcessOwner = { signal: (signal) => { signals.push(signal) }, waitForExit, + terminateForHostExit: vi.fn(), } const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 10, 'linux', owner) @@ -172,6 +175,7 @@ describe('LocalTerminalHandle', () => { waitForExit: vi.fn() .mockRejectedValueOnce(firstFailure) .mockRejectedValueOnce(finalFailure), + terminateForHostExit: vi.fn(), } const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 10, 'linux', owner) @@ -186,19 +190,50 @@ describe('LocalTerminalHandle', () => { const pty = new FakePty() const inspector = new FakeInspector() const signal = vi.fn() - const owner: BoundProcessOwner = { signal, waitForExit: async () => {} } + const terminateForHostExit = vi.fn() + const owner: BoundProcessOwner = { signal, waitForExit: async () => {}, terminateForHostExit } const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10, 'linux', owner) handle.terminateForHostExit() - expect(signal).toHaveBeenCalledExactlyOnceWith('SIGKILL') + expect(signal).not.toHaveBeenCalled() + expect(terminateForHostExit).toHaveBeenCalledOnce() expect(inspector.processes).toEqual([]) expect(pty.kills).toEqual([]) }) + it('rejects managed outcome conversion and cleans its protocol after exit', async () => { + const pty = new FakePty() + const failure = new Error('invalid bootstrap outcome') + const cleanupManagedProtocol = vi.fn() + const owner: BoundProcessOwner = { + signal: vi.fn(), + waitForExit: async () => {}, + terminateForHostExit: vi.fn(), + } + const handle = new LocalTerminalHandle( + pty.asPty(), + new FakeInspector(), + 10, + 'linux', + owner, + () => { throw failure }, + cleanupManagedProtocol, + ) + + pty.emitExit() + await expect(handle.done).rejects.toBe(failure) + await expect(handle.terminate()).resolves.toBeUndefined() + await vi.waitFor(() => { expect(cleanupManagedProtocol).toHaveBeenCalledOnce() }) + }) + it('waits for the node-pty exit event after the managed range becomes empty', async () => { const pty = new FakePty() - const owner: BoundProcessOwner = { signal: vi.fn(), waitForExit: async () => {} } + const owner: BoundProcessOwner = { + signal: vi.fn(), + waitForExit: async () => {}, + terminateForHostExit: vi.fn(), + } const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 100, 'linux', owner) let settled = false @@ -217,6 +252,7 @@ describe('LocalTerminalHandle', () => { const owner: BoundProcessOwner = { signal: (signal) => { signals.push(signal) }, waitForExit: async () => {}, + terminateForHostExit: vi.fn(), } const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 10, 'linux', owner) diff --git a/packages/subprocess/subprocess-local/tests/windows-job.spec.ts b/packages/subprocess/subprocess-local/tests/windows-job.spec.ts index 68850d04c4..49f4bc35d8 100644 --- a/packages/subprocess/subprocess-local/tests/windows-job.spec.ts +++ b/packages/subprocess/subprocess-local/tests/windows-job.spec.ts @@ -1,322 +1,277 @@ -import { spawn, spawnSync } from 'node:child_process' -import type { ChildProcess } from 'node:child_process' import { EventEmitter } from 'node:events' import { PassThrough } from 'node:stream' -import { fileURLToPath } from 'node:url' import { describe, expect, it, vi } from 'vitest' -import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' -import { appendRunnerEvent } from '../src/runner-protocol.ts' -import { launchWindowsJob, probeWindowsJob } from '../src/windows-job.ts' -import type { WindowsStdioBridge } from '../src/windows-stdio.ts' +import { + launchWindowsJob, + probeWindowsJob, +} from '../src/windows-job.ts' +import { bindManagedProcess } from '../src/spawn.ts' -const fixture = fileURLToPath(new URL('fixtures/fake-job-runner.ts', import.meta.url)) -const invocation: [string, ...string[]] = [process.execPath, '--import', 'tsx/esm', fixture] +class FakeChild extends EventEmitter { + pid: number | undefined = 432 + connected = true + stdin = new PassThrough() + stdout = new PassThrough() + stderr = new PassThrough() + sent: unknown[] = [] + killed: NodeJS.Signals[] = [] + sendError: Error | undefined + throwOnSendCall: number | undefined + sendThrown: unknown = new Error('send threw') + private sendCalls = 0 -function spec(argv: string[]): SubprocessSpawnSpec { - return { - argv, - cwd: process.cwd(), - stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, - graceMs: 100, + send(message: unknown, callback?: (error: Error | null) => void): boolean { + this.sendCalls += 1 + if (this.sendCalls === this.throwOnSendCall) throw this.sendThrown + this.sent.push(message) + queueMicrotask(() => { callback?.(this.sendError ?? null) }) + return true + } + kill(signal: NodeJS.Signals): boolean { + this.killed.push(signal) + return true } } -describe('Windows Job runner adapter', () => { - it('probes the runner before a user command is selected', () => { - const runSync = vi.fn(() => ({ status: 0, error: undefined })) as unknown as typeof spawnSync - expect(probeWindowsJob({ spawnSync: runSync, runnerInvocation: invocation })).toBe(true) - expect(runSync).toHaveBeenCalledWith( - process.execPath, - [...invocation.slice(1), '--mode', 'probe-win32'], - expect.objectContaining({ stdio: 'ignore' }), - ) - expect(probeWindowsJob({ - spawnSync: vi.fn(() => ({ status: 1, error: undefined })) as unknown as typeof spawnSync, - runnerInvocation: invocation, - })).toBe(false) - expect(probeWindowsJob({ - spawnSync: vi.fn(() => ({ status: 0, error: new Error('probe failed') })) as unknown as typeof spawnSync, - runnerInvocation: invocation, - })).toBe(false) +const spec = { + argv: ['tool.exe', 'literal arg'], + cwd: 'C:\\target', + env: { TARGET: 'yes' }, + stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'inherit' }, + graceMs: 100, +} as const + +function launch(child = new FakeChild()) { + const spawn = vi.fn(() => child) + const result = launchWindowsJob(spec, { TARGET: 'yes' }, { + spawn: spawn as never, + runnerInvocation: ['C:\\node.exe', 'C:\\runner.js'], }) + return { child, result, spawn } +} - it('reports direct outcome separately from runner settlement', async () => { - const launch = launchWindowsJob(spec(['fake-target', '7']), { - spawn, - runnerInvocation: invocation, - }) - expect(launch.pid).toBeUndefined() - await vi.waitFor(() => { expect(launch.pid).toBeGreaterThan(0) }) - await expect(launch.direct).resolves.toEqual({ exitCode: 7, signal: null }) - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - }) - - it('signals the Job runner and waits for its managed range to stop', async () => { - const launch = launchWindowsJob(spec(['fake-target']), { - spawn, - runnerInvocation: invocation, - }) - launch.owner.signal('SIGTERM') - await expect(launch.direct).resolves.toEqual({ exitCode: 1, signal: null }) - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - launch.owner.signal('SIGKILL') - }) - - it.each([ - { exitCode: 127, signal: null, status: 'exit code 127' }, - { exitCode: null, signal: 'SIGTERM' as NodeJS.Signals, status: 'signal SIGTERM' }, - { exitCode: null, signal: null, status: 'without an exit status' }, - ])('rejects range settlement when the runner exits with $status', async ({ exitCode, signal, status }) => { - const child = new EventEmitter() as ChildProcess - const kill = vi.fn(() => true) - Object.assign(child, { pid: 432, connected: false, kill }) - let eventsPath = '' - const run = vi.fn((_command: string, args: readonly string[]) => { - eventsPath = args[args.indexOf('--events') + 1] as string - appendRunnerEvent(eventsPath, { type: 'started', pid: 432 }) - return child - }) as unknown as typeof spawn - const launch = launchWindowsJob(spec(['fake-target']), { spawn: run, runnerInvocation: ['fake-runner'] }) - const directFailure = launch.direct.catch((error: unknown) => error) - - child.emit('close', exitCode, signal) - - await expect(launch.owner.waitForExit()).rejects.toThrow( - `Windows Job runner exited with ${status} before proving its managed range empty`, - ) - await expect(directFailure).resolves.toBeInstanceOf(Error) - launch.owner.signal('SIGKILL') - expect(kill).not.toHaveBeenCalled() - }) - - it('uses runner exit status as the managed-range settlement fact after startup failure', async () => { - const child = new EventEmitter() as ChildProcess - const kill = vi.fn(() => true) - const send = vi.fn() - Object.assign(child, { pid: 432, connected: true, kill, send }) - const run = vi.fn((_command: string, args: readonly string[]) => { - const eventsPath = args[args.indexOf('--events') + 1] as string - appendRunnerEvent(eventsPath, { - type: 'spawn-error', - error: { name: 'Error', message: 'spawn missing ENOENT', code: 'ENOENT' }, - }) - return child - }) as unknown as typeof spawn - const launch = launchWindowsJob(spec(['missing-target']), { spawn: run, runnerInvocation: ['fake-runner'] }) - - launch.owner.signal('SIGTERM') - await expect(launch.direct).rejects.toMatchObject({ code: 'ENOENT' }) - expect(send).toHaveBeenCalledExactlyOnceWith({ type: 'terminate' }, expect.any(Function)) - expect(kill).not.toHaveBeenCalled() - child.emit('close', 0, null) - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - }) - - it('treats a wrapper that never started as an empty managed range', async () => { - const child = new EventEmitter() as ChildProcess - const kill = vi.fn(() => true) - Object.assign(child, { pid: undefined, connected: false, kill }) - const run = vi.fn(() => child) as unknown as typeof spawn - const launch = launchWindowsJob(spec(['fake-target']), { spawn: run, runnerInvocation: ['missing-runner'] }) - - child.emit('error', new Error('spawn missing-runner ENOENT')) - child.emit('close', -2, null) - await expect(launch.direct).rejects.toThrow('runner failed to start') - launch.owner.signal('SIGTERM') - expect(kill).not.toHaveBeenCalled() - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - }) - - it('waits for a runner that disconnects before its clean close', async () => { - const child = new EventEmitter() as ChildProcess - const kill = vi.fn(() => true) - const send = vi.fn() - Object.assign(child, { pid: 321, connected: false, kill, send }) - let eventsPath = '' - const run = vi.fn((_command: string, args: readonly string[]) => { - eventsPath = args[args.indexOf('--events') + 1] as string - appendRunnerEvent(eventsPath, { type: 'started', pid: 321 }) - return child - }) as unknown as typeof spawn - const launch = launchWindowsJob(spec(['fake-target']), { spawn: run, runnerInvocation: ['fake-runner'] }) - - launch.owner.signal('SIGTERM') - expect(send).not.toHaveBeenCalled() - expect(kill).not.toHaveBeenCalled() - - appendRunnerEvent(eventsPath, { type: 'exit', exitCode: 0, signal: null }) - child.emit('close', 0, null) - await expect(launch.direct).resolves.toEqual({ exitCode: 0, signal: null }) - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - }) - - it('kills the runner only when IPC delivery fails while still connected', async () => { - for (const mode of ['callback-error', 'callback-disconnect', 'throw', 'throw-disconnect'] as const) { - const child = new EventEmitter() as ChildProcess - const kill = vi.fn(() => true) - const send = vi.fn((_message: unknown, callback: (error: Error | null) => void) => { - if (mode === 'callback-disconnect' || mode === 'throw-disconnect') { - Object.assign(child, { connected: false }) - } - if (mode === 'throw' || mode === 'throw-disconnect') throw new Error('send threw') - callback(new Error('send failed')) - return true - }) - Object.assign(child, { - pid: 321, - connected: true, - kill, - send, - }) - let eventsPath = '' - const run = vi.fn((_command: string, args: readonly string[]) => { - eventsPath = args[args.indexOf('--events') + 1] as string - appendRunnerEvent(eventsPath, { type: 'started', pid: 321 }) - return child - }) as unknown as typeof spawn - const launch = launchWindowsJob(spec(['fake-target']), { spawn: run, runnerInvocation: ['fake-runner'] }) - - launch.owner.signal('SIGTERM') - const shouldKill = mode === 'callback-error' || mode === 'throw' - expect(kill).toHaveBeenCalledTimes(shouldKill ? 1 : 0) - - appendRunnerEvent(eventsPath, { type: 'exit', exitCode: 0, signal: null }) - child.emit('close', shouldKill ? null : 0, shouldKill ? 'SIGTERM' : null) - await expect(launch.direct).resolves.toEqual({ exitCode: 0, signal: null }) - if (shouldKill) { - await expect(launch.owner.waitForExit()).rejects.toThrow('before proving its managed range empty') - } else { - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - } - const sends = send.mock.calls.length - const kills = kill.mock.calls.length - launch.owner.signal('SIGKILL') - expect(send).toHaveBeenCalledTimes(sends) - expect(kill).toHaveBeenCalledTimes(kills) - } - - const child = new EventEmitter() as ChildProcess - const kill = vi.fn(() => true) - const send = vi.fn((_message: unknown, callback: (error: Error | null) => void) => { - callback(null) - return true - }) - Object.assign(child, { pid: 654, connected: true, kill, send }) - let eventsPath = '' - const run = vi.fn((_command: string, args: readonly string[]) => { - eventsPath = args[args.indexOf('--events') + 1] as string - appendRunnerEvent(eventsPath, { type: 'started', pid: 654 }) - return child - }) as unknown as typeof spawn - const launch = launchWindowsJob(spec(['fake-target']), { spawn: run, runnerInvocation: ['fake-runner'] }) - launch.owner.signal('SIGTERM') - expect(send).toHaveBeenCalledOnce() - expect(kill).not.toHaveBeenCalled() - appendRunnerEvent(eventsPath, { type: 'exit', exitCode: 0, signal: null }) - child.emit('close', 0, null) - await launch.direct - await launch.owner.waitForExit() - }) - - it('uses production runner defaults', async () => { - const child = new EventEmitter() as ChildProcess - Object.assign(child, { - pid: 987, - connected: true, - kill: vi.fn(() => true), - send: vi.fn(), - }) - let eventsPath = '' - const run = vi.fn((_command: string, args: readonly string[]) => { - eventsPath = args[args.indexOf('--events') + 1] as string - appendRunnerEvent(eventsPath, { type: 'started', pid: 987 }) - return child - }) - const runSync = vi.fn(() => ({ status: 0, error: undefined })) +describe('Windows Job capability', () => { + it('uses the production dependency paths by default', async () => { vi.resetModules() + const child = new FakeChild() + const spawn = vi.fn(() => child) + const load = vi.fn(() => ({ bindings: true }) as never) + const probe = vi.fn() vi.doMock('node:child_process', async importOriginal => ({ ...await importOriginal(), - spawn: run, - spawnSync: runSync, + spawn, })) - try { - const defaults = await import('../src/windows-job.ts') - expect(defaults.probeWindowsJob()).toBe(true) - const launch = defaults.launchWindowsJob(spec(['fake-target'])) - appendRunnerEvent(eventsPath, { type: 'exit', exitCode: 0, signal: null }) - child.emit('close', 0, null) - await expect(launch.direct).resolves.toEqual({ exitCode: 0, signal: null }) - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - expect(run).toHaveBeenCalledOnce() - expect(runSync).toHaveBeenCalledOnce() - } finally { - vi.doUnmock('node:child_process') - vi.resetModules() - } - }) - - it('cleans synchronous setup failures and leaves collected-stream settlement to common binding', async () => { - const bridgeFailure = new Error('bridge failed') - const spawnFailure = new Error('spawn threw') - const bridges: Array; closeInput: ReturnType }> = [] - vi.resetModules() - vi.doMock('../src/windows-stdio.ts', async importOriginal => ({ - ...await importOriginal(), - createWindowsStdioBridge: vi.fn((request: SubprocessSpawnSpec): WindowsStdioBridge => { - if (request.argv[0] === 'bridge-failure') throw bridgeFailure - const stdout = typeof request.stdio.stdout === 'object' ? new PassThrough() : null - const stderr = typeof request.stdio.stderr === 'object' ? new PassThrough() : null - const bridge = { - stdin: null, - stdout, - stderr, - runnerArgs: [], - runnerStdio: ['ignore', 'ignore', 'ignore', 'ipc'], - closeInput: vi.fn(), - dispose: vi.fn(() => { - stdout?.destroy() - stderr?.destroy() - }), - } satisfies WindowsStdioBridge - bridges.push(bridge) - return bridge - }), + vi.doMock('@deepseek-ai/dsh-win32-process', () => ({ + loadWin32ProcessBindings: load, + probeCurrentTokenJobSupport: probe, })) try { const isolated = await import('../src/windows-job.ts') - expect(() => isolated.launchWindowsJob(spec(['bridge-failure']), { runnerInvocation: ['fake-runner'] })) - .toThrow(bridgeFailure) + expect(isolated.probeWindowsJob()).toBe(true) + expect(load).toHaveBeenCalledOnce() + expect(probe).toHaveBeenCalledOnce() - expect(() => isolated.launchWindowsJob(spec(['spawn-failure']), { - spawn: vi.fn(() => { throw spawnFailure }) as unknown as typeof spawn, - runnerInvocation: ['fake-runner'], - })).toThrow(spawnFailure) - expect(bridges.at(-1)?.dispose).toHaveBeenCalledOnce() - - const child = new EventEmitter() as ChildProcess - Object.assign(child, { pid: 432, connected: true, kill: vi.fn(), send: vi.fn() }) - const run = vi.fn((_command: string, args: readonly string[]) => { - const eventsPath = args[args.indexOf('--events') + 1] as string - appendRunnerEvent(eventsPath, { type: 'started', pid: 432 }) - appendRunnerEvent(eventsPath, { type: 'exit', exitCode: 0, signal: null }) - setImmediate(() => { child.emit('close', 0, null) }) - return child - }) as unknown as typeof spawn - const request = { - ...spec(['collect']), - stdio: { - stdin: 'ignore', - stdout: { maxBytes: 1024 }, - stderr: { maxBytes: 1024 }, - }, - } satisfies SubprocessSpawnSpec - const launch = isolated.launchWindowsJob(request, { spawn: run, runnerInvocation: ['fake-runner'] }) - await expect(launch.direct).resolves.toEqual({ exitCode: 0, signal: null }) - await expect(launch.owner.waitForExit()).resolves.toBeUndefined() - expect(bridges.at(-1)?.closeInput).toHaveBeenCalledOnce() + const result = isolated.launchWindowsJob(spec, { TARGET: 'yes' }) + expect(spawn).toHaveBeenCalledOnce() + child.emit('message', { type: 'target-exit', exitCode: 0, signal: null }) + child.connected = false + child.emit('close', 0, null) + await expect(result.direct).resolves.toEqual({ exitCode: 0, signal: null }) + await expect(result.owner.waitForExit()).resolves.toBeUndefined() } finally { - vi.doUnmock('../src/windows-stdio.ts') + vi.doUnmock('node:child_process') + vi.doUnmock('@deepseek-ai/dsh-win32-process') vi.resetModules() } }) + + it('rechecks runner and empty Job support on every eligible spawn', () => { + const runnerAvailable = vi.fn(() => true) + const load = vi.fn(() => ({ bindings: true }) as never) + const probe = vi.fn() + const inputs = { + runnerInvocation: ['C:\\node.exe', 'C:\\runner.js'] as [string, ...string[]], + runnerAvailable, + loadWin32ProcessBindings: load, + probeCurrentTokenJobSupport: probe, + } + expect(probeWindowsJob(inputs)).toBe(true) + expect(probeWindowsJob(inputs)).toBe(true) + expect(runnerAvailable).toHaveBeenCalledTimes(2) + expect(load).toHaveBeenCalledTimes(2) + expect(probe).toHaveBeenCalledTimes(2) + }) + + it('falls back when either runner or current Job capability is unavailable', () => { + expect(probeWindowsJob({ + resolveRunnerInvocation: () => { throw new Error('runner resolution failed') }, + })).toBe(false) + expect(probeWindowsJob({ runnerInvocation: ['/missing'], runnerAvailable: () => false })).toBe(false) + expect(probeWindowsJob({ + runnerInvocation: ['C:\\node.exe'], + runnerAvailable: () => true, + loadWin32ProcessBindings: () => { throw new Error('bindings missing') }, + })).toBe(false) + }) +}) + +describe('Windows parent runner contract', () => { + it('launches with real stdio plus IPC and sends cwd/env through the strict start message', () => { + const { child, result, spawn } = launch() + expect(spawn).toHaveBeenCalledWith('C:\\node.exe', [ + 'C:\\runner.js', '--', 'tool.exe', 'literal arg', + ], expect.objectContaining({ + cwd: process.cwd(), + stdio: ['pipe', 'pipe', 'inherit', 'ipc'], + })) + expect(child.sent).toEqual([{ type: 'start', cwd: 'C:\\target', env: { TARGET: 'yes' } }]) + expect(result.stdin).toBe(child.stdin) + expect(result.stdout).toBe(child.stdout) + expect(result.stderr).toBe(child.stderr) + }) + + it('maps target-exit to direct outcome and clean close to range quiescence', async () => { + const { child, result } = launch() + child.emit('message', { type: 'target-exit', exitCode: 7, signal: null }) + await expect(result.direct).resolves.toEqual({ exitCode: 7, signal: null }) + child.connected = false + child.emit('close', 0, null) + await expect(result.owner.waitForExit()).resolves.toBeUndefined() + }) + + it('rejects done when runner failure precedes stdio settlement', async () => { + const { child, result } = launch() + const handle = bindManagedProcess(spec, result) + child.emit('message', { type: 'target-exit', exitCode: 7, signal: null }) + await Promise.resolve() + child.connected = false + child.emit('close', 127, null) + await expect(handle.done).rejects.toThrow('exit code 127') + }) + + it('maps spawn-error and start-cancelled without requiring public target identity', async () => { + const spawned = launch() + spawned.child.emit('message', { + type: 'spawn-error', error: { name: 'Error', message: 'missing', code: 'ENOENT' }, + }) + await expect(spawned.result.direct).rejects.toMatchObject({ code: 'ENOENT' }) + spawned.child.connected = false + spawned.child.emit('close', 0, null) + await expect(spawned.result.owner.waitForExit()).resolves.toBeUndefined() + + const cancelled = launch() + const reason = new Error('caller aborted') + cancelled.result.owner.signal('SIGTERM', reason) + expect(cancelled.child.sent.at(-1)).toEqual({ type: 'terminate' }) + cancelled.child.emit('message', { type: 'start-cancelled' }) + await expect(cancelled.result.direct).rejects.toBe(reason) + cancelled.child.connected = false + cancelled.child.emit('close', 0, null) + await expect(cancelled.result.owner.waitForExit()).resolves.toBeUndefined() + + const implicit = launch() + implicit.child.emit('message', { type: 'start-cancelled' }) + await expect(implicit.result.direct).rejects.toThrow('target start was cancelled') + implicit.child.connected = false + implicit.child.emit('close', 0, null) + await expect(implicit.result.owner.waitForExit()).resolves.toBeUndefined() + }) + + it('rejects direct and wait for runner-error or abnormal runner exit', async () => { + const failed = launch() + failed.child.emit('message', { + type: 'runner-error', error: { name: 'Error', message: 'Job assignment failed' }, + }) + await expect(failed.result.direct).rejects.toThrow('Job assignment failed') + failed.child.connected = false + failed.child.emit('close', 127, null) + await expect(failed.result.owner.waitForExit()).rejects.toThrow('exit code 127') + await expect(failed.result.infrastructureFailure).rejects.toThrow('exit code 127') + + const missing = launch() + missing.child.connected = false + missing.child.emit('close', null, 'SIGKILL') + await expect(missing.result.direct).rejects.toThrow('signal SIGKILL') + + const statusless = launch() + statusless.child.connected = false + statusless.child.emit('close', null, null) + await expect(statusless.result.direct).rejects.toThrow('without an exit status') + }) + + it('fails closed on malformed/duplicate result, runner spawn error, and start-send error', async () => { + const malformed = launch() + malformed.child.emit('message', { type: 'target-exit', exitCode: -1, signal: null }) + expect(malformed.child.killed).toEqual(['SIGKILL']) + await expect(malformed.result.infrastructureFailure).rejects.toThrow('invalid target-exit') + + const duplicate = launch() + duplicate.child.emit('message', { type: 'target-exit', exitCode: 0, signal: null }) + duplicate.child.emit('message', { type: 'target-exit', exitCode: 0, signal: null }) + await expect(duplicate.result.infrastructureFailure).rejects.toThrow('more than one direct result') + duplicate.child.connected = false + duplicate.child.emit('close', 127, null) + await expect(duplicate.result.owner.waitForExit()).rejects.toThrow('exit code 127') + + const errored = launch() + const spawnError = new Error('runner executable missing') + errored.child.emit('error', spawnError) + await expect(errored.result.direct).rejects.toBe(spawnError) + await expect(errored.result.owner.waitForExit()).rejects.toBe(spawnError) + + const sendFailedChild = new FakeChild() + sendFailedChild.sendError = new Error('IPC send failed') + const sendFailed = launch(sendFailedChild) + await expect(sendFailed.result.direct).rejects.toThrow('IPC send failed') + await expect(sendFailed.result.infrastructureFailure).rejects.toThrow('IPC send failed') + expect(sendFailedChild.killed).toEqual(['SIGKILL']) + + const noIpc = new FakeChild() + Object.defineProperty(noIpc, 'send', { value: undefined }) + const noIpcResult = launch(noIpc).result + await expect(noIpcResult.direct).rejects.toThrow('has no IPC channel') + await expect(noIpcResult.infrastructureFailure).rejects.toThrow('has no IPC channel') + + const nonError = new FakeChild() + nonError.throwOnSendCall = 1 + nonError.sendThrown = 'start send failed' + const nonErrorResult = launch(nonError).result + await expect(nonErrorResult.direct).rejects.toThrow('start send failed') + await expect(nonErrorResult.infrastructureFailure).rejects.toThrow('start send failed') + }) + + it('fails infrastructure and kills the runner when termination delivery fails', async () => { + const callback = launch() + await Promise.resolve() + callback.child.sendError = new Error('terminate callback failed') + callback.result.owner.signal('SIGTERM') + await expect(callback.result.infrastructureFailure).rejects.toThrow('terminate callback failed') + expect(callback.child.killed).toEqual(['SIGKILL']) + callback.child.connected = false + callback.child.emit('close', 127, null) + await expect(callback.result.direct).rejects.toThrow('exit code 127') + + const throwingChild = new FakeChild() + throwingChild.throwOnSendCall = 2 + throwingChild.sendThrown = 'terminate send threw' + const throwing = launch(throwingChild) + throwing.result.owner.signal('SIGTERM') + await expect(throwing.result.infrastructureFailure).rejects.toThrow('terminate send threw') + expect(throwing.child.killed).toEqual(['SIGKILL']) + + const errorChild = new FakeChild() + errorChild.throwOnSendCall = 2 + const error = launch(errorChild) + error.result.owner.signal('SIGTERM') + await expect(error.result.infrastructureFailure).rejects.toThrow('send threw') + }) + + it('uses synchronous runner termination for host exit and isolates repeated control', () => { + const { child, result } = launch() + result.owner.signal('SIGTERM', new Error('first')) + result.owner.signal('SIGKILL', new Error('second')) + expect(child.sent.filter(message => (message as { type?: string }).type === 'terminate')).toHaveLength(1) + result.owner.terminateForHostExit() + expect(child.killed).toEqual(['SIGKILL']) + }) }) diff --git a/packages/subprocess/subprocess-local/tests/windows-stdio.spec.ts b/packages/subprocess/subprocess-local/tests/windows-stdio.spec.ts deleted file mode 100644 index c8b3cf4e07..0000000000 --- a/packages/subprocess/subprocess-local/tests/windows-stdio.spec.ts +++ /dev/null @@ -1,112 +0,0 @@ -import { spawnSync } from 'node:child_process' -import { randomUUID } from 'node:crypto' -import { once } from 'node:events' -import { connect } from 'node:net' -import { join } from 'node:path' -import { describe, expect, it } from 'vitest' -import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' -import { createWindowsStdioBridge } from '../src/windows-stdio.ts' - -function pipeBase(): string { - return process.platform === 'win32' - ? `\\\\.\\pipe\\dsh-windows-stdio-test-${randomUUID()}` - : join('/tmp', `dsh-windows-stdio-${randomUUID()}`) -} - -function spec(): SubprocessSpawnSpec { - return { - argv: ['target'], - cwd: process.cwd(), - stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 1024 } }, - graceMs: 100, - } -} - -function pathAfter(args: readonly string[], key: string): string { - const path = args[args.indexOf(key) + 1] - if (path === undefined) throw new Error(`missing ${key}`) - return path -} - -describe('Windows parent-owned stdio bridge', () => { - it('binds before returning so a synchronously launched peer can connect', async () => { - const bridge = createWindowsStdioBridge({ - ...spec(), - stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'inherit' }, - }, pipeBase()) - const stdoutPath = pathAfter(bridge.runnerArgs, '--stdout-pipe') - const result = spawnSync(process.execPath, ['-e', ` - const { connect } = require('node:net') - const socket = connect(${JSON.stringify(stdoutPath)}) - socket.once('connect', () => { - socket.write('blocked-parent', () => { - socket.destroy() - process.exit(0) - }) - }) - socket.once('error', () => { process.exit(1) }) - setTimeout(() => { process.exit(2) }, 2000) - `], { timeout: 5_000 }) - expect(result.status).toBe(0) - - const chunks: Buffer[] = [] - bridge.stdout?.on('data', (chunk: Buffer) => { chunks.push(chunk) }) - await once(bridge.stdout as NodeJS.ReadableStream, 'end') - expect(Buffer.concat(chunks).toString()).toBe('blocked-parent') - bridge.dispose() - }) - - it('moves bytes in both directions and ends output with its target-side peer', async () => { - const bridge = createWindowsStdioBridge(spec(), pipeBase()) - const stdoutPath = pathAfter(bridge.runnerArgs, '--stdout-pipe') - const stderrPath = pathAfter(bridge.runnerArgs, '--stderr-pipe') - const stdinPath = pathAfter(bridge.runnerArgs, '--stdin-pipe') - expect(bridge.runnerStdio).toEqual(['ignore', 'ignore', 'ignore', 'ipc']) - await new Promise(resolve => setImmediate(resolve)) - - bridge.stdin?.end('in') - const stdoutPeer = connect(stdoutPath) - const stderrPeer = connect(stderrPath) - const stdinPeer = connect(stdinPath) - await Promise.all([once(stdoutPeer, 'connect'), once(stderrPeer, 'connect'), once(stdinPeer, 'connect')]) - - const stdoutChunks: Buffer[] = [] - const stderrChunks: Buffer[] = [] - const stdinChunks: Buffer[] = [] - bridge.stdout?.on('data', (chunk: Buffer) => { stdoutChunks.push(chunk) }) - bridge.stderr?.on('data', (chunk: Buffer) => { stderrChunks.push(chunk) }) - stdinPeer.on('data', (chunk: Buffer) => { stdinChunks.push(chunk) }) - const stdoutEnded = once(bridge.stdout as NodeJS.ReadableStream, 'end') - const stderrEnded = once(bridge.stderr as NodeJS.ReadableStream, 'end') - const stdinEnded = once(stdinPeer, 'end') - - stdoutPeer.end('out') - stderrPeer.end('err') - await Promise.all([stdoutEnded, stderrEnded, stdinEnded]) - - expect(Buffer.concat(stdoutChunks).toString()).toBe('out') - expect(Buffer.concat(stderrChunks).toString()).toBe('err') - expect(Buffer.concat(stdinChunks).toString()).toBe('in') - bridge.dispose() - }) - - it('uses inherited output directly and disposes unconnected endpoints', () => { - const inherited = createWindowsStdioBridge({ - ...spec(), - stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, - }, pipeBase()) - expect(inherited.stdin).toBeNull() - expect(inherited.stdout).toBeNull() - expect(inherited.stderr).toBeNull() - expect(inherited.runnerArgs).toEqual([]) - expect(inherited.runnerStdio).toEqual(['ignore', 'inherit', 'inherit', 'ipc']) - inherited.dispose() - - const pending = createWindowsStdioBridge(spec(), pipeBase()) - pending.closeInput() - expect(pending.stdin?.destroyed).toBe(true) - pending.dispose() - expect(pending.stdout?.destroyed).toBe(true) - expect(pending.stderr?.destroyed).toBe(true) - }) -}) diff --git a/packages/subprocess/subprocess-local/tsdown.config.ts b/packages/subprocess/subprocess-local/tsdown.config.ts index 845b418bde..b0f7e7e85e 100644 --- a/packages/subprocess/subprocess-local/tsdown.config.ts +++ b/packages/subprocess/subprocess-local/tsdown.config.ts @@ -4,7 +4,7 @@ export default defineConfig({ entry: { index: 'lib/types/index.js', invariant: 'lib/types/invariant.js', - 'spawn-runner': 'lib/types/bin.js', + runner: 'lib/types/bin.js', }, outDir: 'lib', format: ['esm'], diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml index 86bba761f3..84d2845b96 100644 --- a/packages/subprocess/subprocess/README.i18n.yaml +++ b/packages/subprocess/subprocess/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/README.md -README.md: 4bfcf20a2116bffe8f830ca940aa32af71d73dc6 -README.zh.md: 75355ba952209be8126b999968343b1b0ca46840 +README.md: 35744148bf9f247c478c7fb86db31f6663712953 +README.zh.md: e8632cb0c73514d472763b5d875dc7d54abbc1eb diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md index 4bfcf20a21..35744148bf 100644 --- a/packages/subprocess/subprocess/README.md +++ b/packages/subprocess/subprocess/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -Any composition that runs child processes can start a fully specified child process or a real terminal session through `ctx.subprocess`, receive a live handle with streams, a target PID when available, and direct exit facts, then terminate and wait for the provider-managed range. The service provides executable lookup, the shared environment scrub, and bounded output capture, while every default — argv, deadlines, shell semantics — stays explicit on the request, so the consuming capability seams decide what a process means. A composition mounts one provider implementation (such as `dsh-subprocess-local`) that registers the service; the seam package itself is an abstract contract, not a loadable plugin. Nothing here reaches a model directly: process output and lifecycle are rendered by the consuming tools. +Any composition that runs child processes can start a fully specified child process or a real terminal session through `ctx.subprocess`, receive a live handle with streams and direct exit facts, then terminate and wait for the provider-managed range. The service provides executable lookup, the shared environment scrub, and bounded output capture, while every default — argv, deadlines, shell semantics — stays explicit on the request, so the consuming capability seams decide what a process means. A composition mounts one provider implementation (such as `dsh-subprocess-local`) that registers the service; the seam package itself is an abstract contract, not a loadable plugin. Nothing here reaches a model directly: process output and lifecycle are rendered by the consuming tools. ## Table of Contents @@ -38,7 +38,7 @@ One provider registers `ctx.subprocess` per composition; load it beside the cons ### Starting a managed process -The request is fully explicit: the program and arguments, the working directory, one stdio disposition per stream, a termination grace, an optional abort signal, and optional environment overrides. The provider publishes `pid` only when a real target PID is available; `undefined` means unavailable or not yet published and never encodes failure. `done` resolves with the direct command's exit facts (`exitCode` and `signal`) and rejects for spawn or provider failures; collected output stays readable after exit. +The request is fully explicit: the program and arguments, the working directory, one stdio disposition per stream, a termination grace, an optional abort signal, and optional environment overrides. Target and managed-range identities remain provider-private. `done` resolves with the direct command's exit facts (`exitCode` and `signal`) and rejects for spawn or provider failures; collected output stays readable after exit. ```text const executable = await ctx.subprocess.resolveExecutable('bash') @@ -100,7 +100,7 @@ The seam is built on one separation: the service owns process coordinates and li ### Data model and flow -A spawn returns a live handle immediately. Its `pid` can remain `undefined` until the provider has a real target identity, while `done` independently reports the direct command outcome or failure and `waitForExit()` reports managed-range quiescence. The request's abort signal drives the same termination procedure as `terminate()`. Collected readers are cursor-free: offsets are whole-stream byte coordinates the caller owns, so independent readers cannot consume one another's output, and a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. `spawnTerminal` is one deep primitive because ordinary pipes cannot allocate a controlling terminal or clean terminal-session members. +A spawn returns a live handle immediately without exposing target identity. `done` independently reports the direct command outcome or failure, while `waitForExit()` reports managed-range quiescence. The request's abort signal drives the same termination procedure as `terminate()`. Collected readers are cursor-free: offsets are whole-stream byte coordinates the caller owns, so independent readers cannot consume one another's output, and a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. `spawnTerminal` is one deep primitive because ordinary pipes cannot allocate a controlling terminal or clean terminal-session members. ### Lifecycle and invariants diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md index 75355ba952..e8632cb0c7 100644 --- a/packages/subprocess/subprocess/README.zh.md +++ b/packages/subprocess/subprocess/README.zh.md @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -任何需要运行子进程的组合都可以通过 `ctx.subprocess` 启动完全明确指定的子进程或真实终端会话，收到带流、可用时的目标 PID 与直接退出事实的活动句柄，然后终止并等待由提供方管理的范围。本服务提供可执行文件查找、共享的环境清理与有界输出捕获，而每一项默认值——argv、时限、shell 语义——都显式留在请求上，由消费方能力 seam 决定进程的含义。组合只需挂载一个提供方实现（如 `dsh-subprocess-local`）来注册该服务；seam 包本身是抽象约定，不是可直接加载的插件。本包不直接接触模型：进程输出与生命周期的渲染由消费方工具负责。 +任何需要运行子进程的组合都可以通过 `ctx.subprocess` 启动完全明确指定的子进程或真实终端会话，收到带流与直接退出事实的活动句柄，然后终止并等待由提供方管理的范围。本服务提供可执行文件查找、共享的环境清理与有界输出捕获，而每一项默认值——argv、时限、shell 语义——都显式留在请求上，由消费方能力 seam 决定进程的含义。组合只需挂载一个提供方实现（如 `dsh-subprocess-local`）来注册该服务；seam 包本身是抽象约定，不是可直接加载的插件。本包不直接接触模型：进程输出与生命周期的渲染由消费方工具负责。 ## 目录 @@ -38,7 +38,7 @@ kind: "package-reference" ### 启动受管进程 -请求完全明确：程序与参数、工作目录、每条流一种 stdio 处置方式、终止宽限期、可选的中止信号与可选的环境覆盖。只有真实目标 PID 可用时，提供方才会发布 `pid`；`undefined` 表示不可用或尚未发布，绝不表示失败。`done` 以直接命令的退出事实（`exitCode` 与 `signal`）resolve，并在 spawn 或提供方失败时 reject；收集输出在退出后仍可读取。 +请求完全明确：程序与参数、工作目录、每条流一种 stdio 处置方式、终止宽限期、可选的中止信号与可选的环境覆盖。目标与受管范围标识保留在提供方内部。`done` 以直接命令的退出事实（`exitCode` 与 `signal`）resolve，并在 spawn 或提供方失败时 reject；收集输出在退出后仍可读取。 ```text const executable = await ctx.subprocess.resolveExecutable('bash') @@ -100,7 +100,7 @@ const output = handle.collected.stdout?.readFrom(0) ### 数据模型与流程 -spawn 会立即返回活动句柄。提供方拥有真实目标身份之前，`pid` 可以保持 `undefined`；`done` 独立报告直接命令的结果或失败，`waitForExit()` 则报告受管范围是否完全停稳。请求的中止信号驱动与 `terminate()` 相同的终止流程。收集模式的读取器无游标：偏移量是调用方拥有的全流字节坐标，因此独立读取器不会消费彼此的输出，偏移量滑出内存尾部的读取标记为 `lossy`，并在 spill 文件存在时指向它。`spawnTerminal` 是一项底层原语，因为普通管道无法分配控制终端或清理终端会话成员。 +spawn 会立即返回活动句柄，而不公开目标身份。`done` 独立报告直接命令的结果或失败，`waitForExit()` 则报告受管范围是否完全停稳。请求的中止信号驱动与 `terminate()` 相同的终止流程。收集模式的读取器无游标：偏移量是调用方拥有的全流字节坐标，因此独立读取器不会消费彼此的输出，偏移量滑出内存尾部的读取标记为 `lossy`，并在 spill 文件存在时指向它。`spawnTerminal` 是一项底层原语，因为普通管道无法分配控制终端或清理终端会话成员。 ### 生命周期与不变式 diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts index 8fc9773df7..4a6977c6c5 100644 --- a/packages/subprocess/subprocess/src/index.ts +++ b/packages/subprocess/subprocess/src/index.ts @@ -80,10 +80,9 @@ declare module '@deepseek-ai/cordis' { * Implementations must honor these semantics: * - Executable paths belong to one execution world shared with the mounted * filesystem provider. - * - {@link spawn} returns a live handle synchronously. Its pid is provider-owned - * and may remain unavailable during asynchronous startup. `done` resolves with - * the spawned command's exit facts and may reject for spawn or provider - * failures. + * - {@link spawn} returns a live handle synchronously. Target identity remains + * provider-private; `done` resolves with the spawned command's exit facts and + * may reject for spawn or provider failures. * - Collect-mode readers are offset-based and non-consuming, so independent * readers never consume one another's output; lossy reads report truncation * and the spill file holding the complete stream when one exists. Piped @@ -92,7 +91,7 @@ declare module '@deepseek-ai/cordis' { * provider's documented procedure against its managed range. * {@link SubprocessHandle.waitForExit} observes that same range so a * consumer-owned teardown ladder can hold each tier on real quiescence; each - * provider documents its identity, signalling, and observability limits. + * provider documents its signalling and observability limits. * - Disposal of the service terminates all still-running managed processes * and awaits their exit. * - {@link spawnTerminal} owns terminal allocation, text transport, diff --git a/packages/subprocess/subprocess/src/types.ts b/packages/subprocess/subprocess/src/types.ts index bfb2ce1ad1..5a68231c0f 100644 --- a/packages/subprocess/subprocess/src/types.ts +++ b/packages/subprocess/subprocess/src/types.ts @@ -161,12 +161,10 @@ export interface SubprocessCollectedOutputs { * remains readable after exit; piped streams belong to the caller. * * Termination and {@link SubprocessHandle.waitForExit} use the same managed - * range. Each provider documents the process identity and range it can - * observe. + * range. Each provider documents the range it can observe and its signalling + * and observation limits. */ export interface SubprocessHandle { - /** Provider-published target process identifier, or undefined until it is available. */ - readonly pid: number | undefined /** The child's stdin, present iff spawned with `stdin: 'pipe'`. */ readonly stdin: Writable | undefined /** The child's raw stdout, present iff spawned with `stdout: 'pipe'`. */ diff --git a/packages/subprocess/subprocess/tests/service.spec.ts b/packages/subprocess/subprocess/tests/service.spec.ts index d2b75b4536..1e71605781 100644 --- a/packages/subprocess/subprocess/tests/service.spec.ts +++ b/packages/subprocess/subprocess/tests/service.spec.ts @@ -26,7 +26,6 @@ class StubSubprocessRuntime extends SubprocessRuntime { ? { stdout: { readFrom: () => read } } : {} return { - pid: spec.argv[0] === 'pending' ? undefined : spec.argv.length, stdin: undefined, stdout: undefined, stderr: undefined, @@ -60,7 +59,7 @@ describe('SubprocessRuntime seam', () => { stdio: { stdin: 'ignore', stdout: { maxBytes: 1 }, stderr: 'inherit' }, graceMs: 1, }) - expect(handle.pid).toBe(1) + expect(Object.hasOwn(handle, 'pid')).toBe(false) expect(handle.collected.stdout!.readFrom(0)).toEqual({ text: '', nextOffset: 0, lossy: false }) handle.terminate() await expect(handle.waitForExit()).resolves.toBe(true) @@ -68,21 +67,6 @@ describe('SubprocessRuntime seam', () => { expect(outcome.exitCode).toBe(0) }) - it('preserves an unavailable provider pid without treating it as failure', async () => { - const ctx = new Context() - await ctx.plugin(StubSubprocessRuntime) - const handle = ctx.subprocess.spawn({ - argv: ['pending'], - cwd: '/stub', - stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, - graceMs: 1, - }) - - expect(handle.pid).toBeUndefined() - await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) - await expect(handle.waitForExit()).resolves.toBe(true) - }) - it('loading a second implementation throws (one subprocess service per context — cordis standard)', async () => { const ctx = new Context() await ctx.plugin(StubSubprocessRuntime) diff --git a/packages/subprocess/win32-process/README.i18n.yaml b/packages/subprocess/win32-process/README.i18n.yaml index 16fc16bea1..a3e3e7b55a 100644 --- a/packages/subprocess/win32-process/README.i18n.yaml +++ b/packages/subprocess/win32-process/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/win32-process/README.md -README.md: 5898fe0afb5e2a4c553b8406437783a3cf44b011 -README.zh.md: ce3adcf55db4555ad3b6ced37998a27a6d83caef +README.md: ebffba7780bbc3888c36e5afdca1f3cf387b03ab +README.zh.md: 3ed6aedfc4e845361e8fc26f7599851d430a5d97 diff --git a/packages/subprocess/win32-process/README.md b/packages/subprocess/win32-process/README.md index 5898fe0afb..ebffba7780 100644 --- a/packages/subprocess/win32-process/README.md +++ b/packages/subprocess/win32-process/README.md @@ -28,8 +28,8 @@ This low-level Win32 process library is consumed by the Windows ACL sandbox and - **Restricted-token creation** — `RestrictedProcessSpawnOptions` requires the sandbox's primary token and uses `CreateProcessAsUserW`. Piped and inherited-stdio paths share command-line quoting, cwd, the inherited environment block, checked return values, and handle cleanup. - **Piped process primitive** — `spawnPipedProcess()` creates anonymous stdin/stdout/stderr pipes, closes stdin immediately, returns the two read ends, and leaves process waiting and pipe draining to the caller. Every partial failure closes the handles already owned by the operation, and every Koffi out-parameter or struct allocation is freed after its Win32 lifetime. - **Inherited-stdio Job primitive** — `spawnInheritedJobProcess()` creates one kill-on-close Job, temporarily marks the current stdio handles inheritable, creates the restricted child suspended, assigns it to the Job, and then resumes its initial thread. Target code cannot run before Job assignment; controlled assignment or resume failures terminate the suspended child or close the assigned Job before releasing every owned handle. -- **Named-pipe stdio primitive** — `openNamedPipeForStdio()` opens a parent-owned endpoint with only the target-side read or write access required by that stream. `spawnCurrentTokenJobProcess()` accepts those explicit handles, temporarily enables inheritance for target creation, and otherwise uses the runner's inherited standard handle. -- **Ordinary Job runner primitive** — `spawnCurrentTokenJobProcess()` applies the suspended-create, Job-assignment, and resume lifecycle through `CreateProcessW` and returns the original process handle plus the unnamed Job to the same runner. A zero-time process wait publishes direct exit separately, while `QueryInformationJobObject(JobObjectBasicAccountingInformation)` keeps that runner alive until `ActiveProcesses` reaches zero. +- **Ordinary Job runner primitive** — `spawnCurrentTokenJobProcess()` temporarily marks the runner's standard handles inheritable, passes those exact handles through `STARTF_USESTDHANDLES`, creates the target suspended through `CreateProcessW`, assigns it to an unnamed kill-on-close Job, and resumes it only after assignment. It returns the direct-process handle and Job to the same runner; `closeCurrentProcessStandardHandles()` then closes the runner's copies so target exit can produce EOF at the parent. +- **Ordinary settlement operations** — `pollProcessExit()` publishes direct exit separately, while `isJobEmpty()` reads `QueryInformationJobObject(JobObjectBasicAccountingInformation)` until `ActiveProcesses` reaches zero. Checked Job termination and handle closure keep the runner as the only native owner. - **Explicit settlement ownership** — `waitForProcessExit()` waits and closes a sandbox process handle; ordinary runner process polling, Job accounting, and checked Job termination/closure remain separate operations. `drainPipe()` reuses one native count slot while draining, frees it, and closes the pipe read handle. Each caller owns its result composition and returned handles. The Windows ACL sandbox adds SID, DACL, grant, workspace, and public child policy above these primitives. @@ -37,7 +37,7 @@ The Windows ACL sandbox adds SID, DACL, grant, workspace, and public child polic ## Header verification -The process, named-pipe, stdio, and Job constants plus selected structure sizes and offsets are checked against the MinGW Windows headers by [`verify/abi-probe.cpp`](verify/abi-probe.cpp): +The process, stdio, and Job constants plus selected structure sizes and offsets are checked against the MinGW Windows headers by [`verify/abi-probe.cpp`](verify/abi-probe.cpp): ```sh g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp && ./abi-probe.exe diff --git a/packages/subprocess/win32-process/README.zh.md b/packages/subprocess/win32-process/README.zh.md index ce3adcf55d..3ed6aedfc4 100644 --- a/packages/subprocess/win32-process/README.zh.md +++ b/packages/subprocess/win32-process/README.zh.md @@ -28,8 +28,8 @@ kind: "package-library" - **restricted-token 创建** — `RestrictedProcessSpawnOptions` 要求 sandbox 的 primary token，并使用 `CreateProcessAsUserW`。pipe 与 inherited-stdio 路径共用命令行引用、cwd、继承环境块、返回值检查与句柄清理。 - **管道进程原语** — `spawnPipedProcess()` 创建匿名 stdin/stdout/stderr 管道，立即关闭 stdin，并返回两个读取端；调用方负责等待进程与排空管道。任一局部失败都会关闭该操作已经拥有的句柄，并在各自 Win32 生命周期结束后释放每个 Koffi 输出槽与结构体分配。 - **继承 stdio 的 Job 原语** — `spawnInheritedJobProcess()` 创建一个 kill-on-close Job，临时把当前 stdio 句柄设为可继承，以 suspended 状态创建 restricted child，把它分配给 Job，再恢复初始线程。目标代码不会在 Job 分配前运行；受控的分配或恢复失败会终止 suspended child，或在释放全部已拥有句柄前关闭已分配的 Job。 -- **named-pipe stdio 原语** — `openNamedPipeForStdio()` 打开 parent-owned endpoint，并只申请该流 target 侧需要的 read 或 write access。`spawnCurrentTokenJobProcess()` 接受这些显式 handle，在创建目标期间临时启用继承；未显式提供的流继续使用 runner 继承的标准句柄。 -- **ordinary Job runner 原语** — `spawnCurrentTokenJobProcess()` 通过 `CreateProcessW` 应用 suspended-create、Job-assignment 与 resume 生命周期，并把原始 process handle 与 unnamed Job 返回给同一个 runner。process 的 zero-time wait 单独发布 direct exit，`QueryInformationJobObject(JobObjectBasicAccountingInformation)` 则让该 runner 一直存活到 `ActiveProcesses` 归零。 +- **ordinary Job runner 原语** — `spawnCurrentTokenJobProcess()` 临时把 runner 的标准句柄设为可继承，通过 `STARTF_USESTDHANDLES` 传入这些准确句柄，再以 suspended 状态通过 `CreateProcessW` 创建 target、把它分配给 unnamed kill-on-close Job，并只在分配后恢复。它把 direct-process handle 与 Job 返回给同一个 runner；`closeCurrentProcessStandardHandles()` 随后关闭 runner 的副本，使 target 退出可以在 parent 产生 EOF。 +- **ordinary 停稳操作** — `pollProcessExit()` 单独发布 direct exit，`isJobEmpty()` 则读取 `QueryInformationJobObject(JobObjectBasicAccountingInformation)`，直到 `ActiveProcesses` 归零。带检查的 Job 终止与 handle 关闭使 runner 保持唯一 native owner。 - **显式结算归属** — `waitForProcessExit()` 等待并关闭 sandbox process handle；ordinary runner 的 process polling、Job accounting 与 checked Job termination/closure 是独立操作。`drainPipe()` 在排空期间复用一个 native count slot，释放该分配并关闭管道读取句柄。每个调用方拥有自己的 result 组合与返回 handle。 Windows ACL 沙箱在这些原语上增加 SID、DACL、grant、workspace 与公共 child policy。 @@ -37,7 +37,7 @@ Windows ACL 沙箱在这些原语上增加 SID、DACL、grant、workspace 与公 ## 头部验证 -process、named-pipe、stdio 与 Job 的常量以及选定结构体的大小和偏移由 [`verify/abi-probe.cpp`](verify/abi-probe.cpp) 对照 MinGW Windows 头文件检查： +process、stdio 与 Job 的常量以及选定结构体的大小和偏移由 [`verify/abi-probe.cpp`](verify/abi-probe.cpp) 对照 MinGW Windows 头文件检查： ```sh g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp && ./abi-probe.exe diff --git a/packages/subprocess/win32-process/src/abi.ts b/packages/subprocess/win32-process/src/abi.ts index 3a7448b497..d3b2eafcb4 100644 --- a/packages/subprocess/win32-process/src/abi.ts +++ b/packages/subprocess/win32-process/src/abi.ts @@ -10,12 +10,6 @@ export const INFINITE = 0xFFFFFFFF export const WAIT_TIMEOUT = 258 /** CreateProcess flag that prevents user code from running before resume. */ export const CREATE_SUSPENDED = 0x4 -/** Read access requested for a private named-pipe client handle. */ -export const GENERIC_READ = 0x80000000 -/** Write access requested for a private named-pipe client handle. */ -export const GENERIC_WRITE = 0x40000000 -/** Open an existing named-pipe endpoint. */ -export const OPEN_EXISTING = 3 /** GetStdHandle selector for standard input. */ export const STD_INPUT_HANDLE = -10 /** GetStdHandle selector for standard output. */ diff --git a/packages/subprocess/win32-process/src/ffi.ts b/packages/subprocess/win32-process/src/ffi.ts index 62375975ac..b1adeff700 100644 --- a/packages/subprocess/win32-process/src/ffi.ts +++ b/packages/subprocess/win32-process/src/ffi.ts @@ -67,15 +67,6 @@ export interface Win32ProcessBindings { args: null, ): number createPipe(readHandle: NativePtr, writeHandle: NativePtr, attributes: null, size: number): number - createFileW( - path: string, - desiredAccess: number, - shareMode: number, - securityAttributes: null, - creationDisposition: number, - flagsAndAttributes: number, - templateFile: null, - ): NativePtr setHandleInformation(handle: NativePtr, mask: number, flags: number): number createProcessAsUserW( token: NativePtr, @@ -265,9 +256,6 @@ function bindings(): Win32ProcessBindings { 'uint32', PVOID, 'uint32', 'uint32', PVOID, 'uint32', PVOID, ]), createPipe: bind(kernel32, 'CreatePipe', 'int', [PPVOID, PPVOID, PVOID, 'uint32']), - createFileW: bind(kernel32, 'CreateFileW', PVOID, [ - 'str16', 'uint32', 'uint32', PVOID, 'uint32', 'uint32', PVOID, - ]), setHandleInformation: bind(kernel32, 'SetHandleInformation', 'int', [PVOID, 'uint32', 'uint32']), createProcessAsUserW: bind(advapi32, 'CreateProcessAsUserW', 'int', [ PVOID, 'str16', 'str16', PVOID, PVOID, 'int', 'uint32', PVOID, 'str16', diff --git a/packages/subprocess/win32-process/src/index.ts b/packages/subprocess/win32-process/src/index.ts index fe61f4a409..17960f94c4 100644 --- a/packages/subprocess/win32-process/src/index.ts +++ b/packages/subprocess/win32-process/src/index.ts @@ -19,10 +19,11 @@ export type { } from './ffi.ts' export { closeHandleChecked, + closeCurrentProcessStandardHandles, drainPipe, isJobEmpty, - openNamedPipeForStdio, pollProcessExit, + probeCurrentTokenJobSupport, spawnInheritedJobProcess, spawnCurrentTokenJobProcess, spawnPipedProcess, @@ -30,7 +31,6 @@ export { waitForProcessExit, } from './process.ts' export type { - ChildStdioHandles, CurrentTokenProcessSpawnOptions, SpawnedJobProcess, SpawnedPipedProcess, diff --git a/packages/subprocess/win32-process/src/process.ts b/packages/subprocess/win32-process/src/process.ts index 608e31c100..a609b2d08c 100644 --- a/packages/subprocess/win32-process/src/process.ts +++ b/packages/subprocess/win32-process/src/process.ts @@ -63,13 +63,6 @@ export interface CurrentTokenProcessSpawnOptions { cwd: string } -/** Optional explicit target standard handles; omitted entries use the caller's standard handle. */ -export interface ChildStdioHandles { - stdin?: NativePtr - stdout?: NativePtr - stderr?: NativePtr -} - /** Restricted-token process creation inputs owned by the Windows ACL sandbox. */ export interface RestrictedProcessSpawnOptions extends CurrentTokenProcessSpawnOptions { /** Restricted primary token supplied by sandbox policy. */ @@ -327,38 +320,10 @@ function createKillOnCloseJob(api: Win32ProcessBindings): NativePtr { return job } -/** - * Open one private named-pipe client for target stdio. - * @param api - active binding table. - * @param path - unique parent-owned named-pipe path. - * @param access - target-side read access for stdin or write access for output. - * @returns caller-owned connected pipe handle. - */ -export function openNamedPipeForStdio( - api: Win32ProcessBindings, - path: string, - access: 'read' | 'write', -): NativePtr { - const handle = api.createFileW( - path, - access === 'read' ? abi.GENERIC_READ : abi.GENERIC_WRITE, - 0, - null, - abi.OPEN_EXISTING, - 0, - null, - ) - if (isNullPtr(handle) || (handle as bigint) === -1n || (handle as bigint) === 0xFFFFFFFFFFFFFFFFn) { - throwLastError(api, 'CreateFileW', path) - } - return handle -} - /** Shared suspended-create, Job-assignment, and resume lifecycle. */ function spawnJobProcess( api: Win32ProcessBindings, options: CurrentTokenProcessSpawnOptions, - stdio: ChildStdioHandles, createName: 'CreateProcessAsUserW' | 'CreateProcessW', create: (startupInfo: NativePtr, processInfo: NativePtr) => number, ): SpawnedJobProcess { @@ -370,9 +335,9 @@ function spawnJobProcess( api.closeHandle(job) throwWin32(api, 'GetStdHandle', win32Code, `null ${label} handle`) } - const stdIn = stdio.stdin ?? getStdHandle(abi.STD_INPUT_HANDLE, 'stdin') - const stdOut = stdio.stdout ?? getStdHandle(abi.STD_OUTPUT_HANDLE, 'stdout') - const stdErr = stdio.stderr ?? getStdHandle(abi.STD_ERROR_HANDLE, 'stderr') + const stdIn = getStdHandle(abi.STD_INPUT_HANDLE, 'stdin') + const stdOut = getStdHandle(abi.STD_OUTPUT_HANDLE, 'stdout') + const stdErr = getStdHandle(abi.STD_ERROR_HANDLE, 'stderr') const enabled: NativePtr[] = [] let startupInfo: NativePtr | undefined let processInfo: NativePtr | undefined @@ -468,7 +433,7 @@ export function spawnInheritedJobProcess( options: RestrictedProcessSpawnOptions, ): SpawnedJobProcess { const commandLine = buildCommandLine(options.command, options.args) - return spawnJobProcess(api, options, {}, 'CreateProcessAsUserW', (startupInfo, processInfo) => + return spawnJobProcess(api, options, 'CreateProcessAsUserW', (startupInfo, processInfo) => createRestrictedProcess( api, options, @@ -483,16 +448,14 @@ export function spawnInheritedJobProcess( * Spawn an ordinary process suspended, assign its Job, then resume it. * @param api - active binding table. * @param options - command, cwd, and argv. - * @param stdio - optional explicit handles opened for this target. * @returns caller-owned process and Job handles after successful resume. */ export function spawnCurrentTokenJobProcess( api: Win32ProcessBindings, options: CurrentTokenProcessSpawnOptions, - stdio: ChildStdioHandles = {}, ): SpawnedJobProcess { const commandLine = buildCommandLine(options.command, options.args) - return spawnJobProcess(api, options, stdio, 'CreateProcessW', (startupInfo, processInfo) => + return spawnJobProcess(api, options, 'CreateProcessW', (startupInfo, processInfo) => api.createProcessW( null, commandLine, @@ -507,6 +470,42 @@ export function spawnCurrentTokenJobProcess( )) } +/** + * Verify that an unnamed kill-on-close Job can be created and released now. + * @param api - active binding table. + */ +export function probeCurrentTokenJobSupport(api: Win32ProcessBindings): void { + const job = createKillOnCloseJob(api) + closeHandleChecked(api, job, 'current-token Job capability probe') +} + +/** + * Close the runner's inherited standard-handle copies after target creation. + * The target retains its inherited copies; closing these permits parent pipe + * EOF to follow the target rather than the longer-lived runner. + * @param api - active binding table. + */ +export function closeCurrentProcessStandardHandles(api: Win32ProcessBindings): void { + const handles: NativePtr[] = [] + for (const selector of [abi.STD_INPUT_HANDLE, abi.STD_OUTPUT_HANDLE, abi.STD_ERROR_HANDLE]) { + const handle = api.getStdHandle(selector) + if (isNullPtr(handle) || handles.includes(handle)) continue + handles.push(handle) + } + const failures: Error[] = [] + for (const handle of handles) { + try { + closeHandleChecked(api, handle, 'runner standard handle') + } catch (error) { + failures.push(error instanceof Error ? error : new Error(String(error))) + } + } + if (failures.length === 1) { + for (const failure of failures) throw failure + } + if (failures.length > 1) throw new AggregateError(failures, 'closing runner standard handles failed') +} + /** * Poll one process handle without blocking the runner event loop. * @param api - active binding table. diff --git a/packages/subprocess/win32-process/tests/ordinary-process.spec.ts b/packages/subprocess/win32-process/tests/ordinary-process.spec.ts index 6035b7c3a6..99d90d8267 100644 --- a/packages/subprocess/win32-process/tests/ordinary-process.spec.ts +++ b/packages/subprocess/win32-process/tests/ordinary-process.spec.ts @@ -2,30 +2,34 @@ import koffi from 'koffi' import { describe, expect, it, vi } from 'vitest' import { closeHandleChecked, + closeCurrentProcessStandardHandles, isJobEmpty, - openNamedPipeForStdio, pollProcessExit, + probeCurrentTokenJobSupport, spawnCurrentTokenJobProcess, terminateJob, Win32Error, } from '../src/index.ts' import { CREATE_SUSPENDED, - GENERIC_READ, - GENERIC_WRITE, JOBOBJECT_BASIC_ACCOUNTING_ACTIVE_PROCESSES_OFFSET, JOBOBJECT_BASIC_ACCOUNTING_SIZE, JobObjectBasicAccountingInformation, - OPEN_EXISTING, + STD_ERROR_HANDLE, + STD_INPUT_HANDLE, + STD_OUTPUT_HANDLE, WAIT_TIMEOUT, } from '../src/abi.ts' import { PROCESS_INFORMATION, STARTUPINFOW } from '../src/ffi.ts' import type { NativePtr, Win32ProcessBindings } from '../src/index.ts' +function nativePtr(value: bigint): NativePtr { + return value as NativePtr +} + function api(overrides: Partial = {}): Win32ProcessBindings { return { createJobObjectW: vi.fn(() => 50n), - createFileW: vi.fn(() => 70n), setInformationJobObject: vi.fn(() => 1), queryInformationJobObject: vi.fn((_job: NativePtr, _cls: number, information: Buffer) => { information.writeUInt32LE(0, JOBOBJECT_BASIC_ACCOUNTING_ACTIVE_PROCESSES_OFFSET) @@ -116,11 +120,18 @@ describe('ordinary Job process operations', () => { expect(caught).toMatchObject({ api: 'CreateProcessW', win32Code: 5 }) }) - it('passes explicit target stdio handles without reading caller stdio', () => { + it('inherits the runner standard handles and restores their flags', () => { let startup: Record | undefined - const getStdHandle = vi.fn(() => 99n as NativePtr) + const handles = new Map([ + [STD_INPUT_HANDLE, 71n as NativePtr], + [STD_OUTPUT_HANDLE, 72n as NativePtr], + [STD_ERROR_HANDLE, 73n as NativePtr], + ]) + const getStdHandle = vi.fn((selector: number) => handles.get(selector) as NativePtr) + const setHandleInformation = vi.fn(() => 1) const bindings = api({ getStdHandle, + setHandleInformation, createProcessW: vi.fn((_app, _line, _pa, _ta, _inherit, _flags, _env, _cwd, infoPtr, processInfo) => { startup = koffi.decode(infoPtr, STARTUPINFOW) as Record koffi.encode(processInfo, PROCESS_INFORMATION, { @@ -136,43 +147,17 @@ describe('ordinary Job process operations', () => { command: 'probe.exe', args: [], cwd: 'C:\\work', - }, { - stdin: 71n as NativePtr, - stdout: 72n as NativePtr, - stderr: 73n as NativePtr, })).toEqual({ pid: 1234, process: 60n, job: 50n }) - expect(getStdHandle).not.toHaveBeenCalled() + expect(getStdHandle.mock.calls.map(([selector]) => selector)).toEqual([ + STD_INPUT_HANDLE, + STD_OUTPUT_HANDLE, + STD_ERROR_HANDLE, + ]) expect(startup).toMatchObject({ hStdInput: 71n, hStdOutput: 72n, hStdError: 73n }) - }) - - it('opens private named-pipe clients with stream-specific access', () => { - const createFileW = vi.fn(() => 70n as NativePtr) - const bindings = api({ createFileW }) - expect(openNamedPipeForStdio(bindings, '\\\\.\\pipe\\dsh-stdin', 'read')).toBe(70n) - expect(openNamedPipeForStdio(bindings, '\\\\.\\pipe\\dsh-stdout', 'write')).toBe(70n) - expect(createFileW).toHaveBeenNthCalledWith( - 1, - '\\\\.\\pipe\\dsh-stdin', - GENERIC_READ, - 0, - null, - OPEN_EXISTING, - 0, - null, - ) - expect(createFileW).toHaveBeenNthCalledWith( - 2, - '\\\\.\\pipe\\dsh-stdout', - GENERIC_WRITE, - 0, - null, - OPEN_EXISTING, - 0, - null, - ) - - const invalid = api({ createFileW: vi.fn(() => -1n as NativePtr) }) - expect(() => openNamedPipeForStdio(invalid, '\\\\.\\pipe\\missing', 'read')).toThrow(Win32Error) + expect(setHandleInformation.mock.calls).toEqual([ + [71n, 1, 1], [72n, 1, 1], [73n, 1, 1], + [71n, 1, 0], [72n, 1, 0], [73n, 1, 0], + ]) }) it('polls direct exit and Job emptiness without blocking', () => { @@ -223,4 +208,65 @@ describe('ordinary Job process operations', () => { const closeFailure = api({ closeHandle: vi.fn(() => 0) }) expect(() => { closeHandleChecked(closeFailure, 50n as NativePtr, 'test Job') }).toThrow(Win32Error) }) + + it('probes an unnamed Job and closes its handle', () => { + const closeHandle = vi.fn(() => 1) + const bindings = api({ closeHandle }) + expect(() => { probeCurrentTokenJobSupport(bindings) }).not.toThrow() + expect(closeHandle).toHaveBeenCalledExactlyOnceWith(50n) + }) + + it('closes unique non-null inherited standard handles', () => { + const getStdHandle = vi.fn((_selector: number): NativePtr => nativePtr(0n)) + .mockReturnValueOnce(nativePtr(0n)) + .mockReturnValueOnce(nativePtr(72n)) + .mockReturnValueOnce(nativePtr(72n)) + const closeHandle = vi.fn(() => 1) + const bindings = api({ getStdHandle, closeHandle }) + + expect(() => { closeCurrentProcessStandardHandles(bindings) }).not.toThrow() + expect(getStdHandle.mock.calls.map(([selector]) => selector)).toEqual([ + STD_INPUT_HANDLE, + STD_OUTPUT_HANDLE, + STD_ERROR_HANDLE, + ]) + expect(closeHandle).toHaveBeenCalledExactlyOnceWith(72n) + }) + + it('reports one or several inherited standard-handle close failures', () => { + const singleFailure = api({ + getStdHandle: vi.fn() + .mockReturnValueOnce(nativePtr(71n)) + .mockReturnValueOnce(nativePtr(72n)) + .mockReturnValueOnce(nativePtr(73n)), + closeHandle: vi.fn((handle: NativePtr) => handle === 72n ? 0 : 1), + }) + expect(() => { closeCurrentProcessStandardHandles(singleFailure) }).toThrow(Win32Error) + + const severalFailures = api({ + getStdHandle: vi.fn() + .mockReturnValueOnce(nativePtr(71n)) + .mockReturnValueOnce(nativePtr(72n)) + .mockReturnValueOnce(nativePtr(73n)), + closeHandle: vi.fn((handle: NativePtr) => { + if (handle === 71n) throw 'raw close failure' + return handle === 72n ? 0 : 1 + }), + }) + let failure: unknown + try { + closeCurrentProcessStandardHandles(severalFailures) + } catch (error) { + failure = error + } + expect(failure).toMatchObject({ + name: 'AggregateError', + message: 'closing runner standard handles failed', + }) + const errors = (failure as { errors: unknown }).errors + expect(errors).toEqual(expect.arrayContaining([ + expect.objectContaining({ message: 'raw close failure' }), + expect.any(Win32Error), + ])) + }) }) diff --git a/packages/subprocess/win32-process/verify/abi-probe.cpp b/packages/subprocess/win32-process/verify/abi-probe.cpp index 60ad3c662d..3cbb883ccf 100644 --- a/packages/subprocess/win32-process/verify/abi-probe.cpp +++ b/packages/subprocess/win32-process/verify/abi-probe.cpp @@ -21,9 +21,6 @@ int wmain() P(STARTF_USESTDHANDLES); P(HANDLE_FLAG_INHERIT); P(INFINITE); - P(GENERIC_READ); - P(GENERIC_WRITE); - P(OPEN_EXISTING); P(WAIT_TIMEOUT); P(STD_INPUT_HANDLE); P(STD_OUTPUT_HANDLE); @@ -46,9 +43,6 @@ int wmain() static_assert(CREATE_SUSPENDED == 0x4, "suspended process flag"); static_assert(STARTF_USESTDHANDLES == 0x100, "std handles flag"); static_assert(HANDLE_FLAG_INHERIT == 0x1, "inherit flag"); - static_assert(GENERIC_READ == 0x80000000, "generic read access"); - static_assert(GENERIC_WRITE == 0x40000000, "generic write access"); - static_assert(OPEN_EXISTING == 3, "open existing disposition"); static_assert(WAIT_TIMEOUT == 258, "zero-time wait timeout"); static_assert(sizeof(JOBOBJECT_BASIC_ACCOUNTING_INFORMATION) == 48, "job accounting size"); static_assert(offsetof(JOBOBJECT_BASIC_ACCOUNTING_INFORMATION, ActiveProcesses) == 40, "active process offset"); diff --git a/scripts/build-exe-for-python-sdk.ts b/scripts/build-exe-for-python-sdk.ts index c7c8cfed66..9bb8019a54 100644 --- a/scripts/build-exe-for-python-sdk.ts +++ b/scripts/build-exe-for-python-sdk.ts @@ -18,7 +18,7 @@ const root = resolve(import.meta.dirname, '..') /** The closure manifest whose dependencies define the executable. */ const DEPLOY_ROOT_PACKAGE = 'dsh-python-runtime-closure' /** The sole application launcher inside the deployed closure. */ -const ENTRY_BIN = 'node_modules/@deepseek-ai/dsh/lib/bin.js' +const ENTRY_BIN = 'node_modules/@deepseek-ai/dsh/lib/runtime-bootstrap.js' /** Python-visible executable basename. */ const OUTPUT_BASENAME = 'deepseek-harness-sdk-runtime' /** Default Node major; SEA mode requires at least Node 22. */ diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts index 8708b010d9..7afa1acea8 100644 --- a/scripts/check-workspace-constraints.ts +++ b/scripts/check-workspace-constraints.ts @@ -168,10 +168,10 @@ const packageFileExtras: Readonly> = { ], '@deepseek-ai/dsh-skill-badge': ['assets'], // Ordinary native containment ships a path-loaded runner and its shared - // result-protocol chunk beside the existing node-pty permission repair. + // runner chunk beside the existing node-pty permission repair. '@deepseek-ai/dsh-subprocess-local': [ - 'lib/spawn-runner.js', - 'lib/runner-protocol-*.js', + 'lib/runner.js', + 'lib/runner-*.js', 'scripts/ensure-spawn-helper.mjs', ], // tsdown shares the repository/pack code between the lib entry and the bin diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts index b89c72c047..93e931e425 100644 --- a/scripts/run-gates.spec.ts +++ b/scripts/run-gates.spec.ts @@ -463,10 +463,6 @@ describe('Node 24 lane ownership', () => { 'packages/experimental/agent-team/tests/built-lib.e2e.ts', ]), ) - expect(subject.find(item => item.id === 'built-bin-smoke')?.env).toEqual({ - DSH_EXAMPLE_MODE: 'lib', - DSH_REQUIRE_BUILT_SUBPROCESS_RUNNER: '1', - }) expect(subject.find(item => item.id === 'web-snapshot')).toMatchObject({ displayCommand: 'DSH_SNAPSHOT=replay pnpm run test:web:built', env: { DSH_SNAPSHOT: 'replay' }, diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index 91ccc15a70..4132e16146 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -772,10 +772,7 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate { ], { label: 'built-bin smoke', needs, - env: { - DSH_EXAMPLE_MODE: 'lib', - DSH_REQUIRE_BUILT_SUBPROCESS_RUNNER: '1', - }, + env: { DSH_EXAMPLE_MODE: 'lib' }, }) } diff --git a/scripts/smoke-python-runtime.py b/scripts/smoke-python-runtime.py index 672ff33178..e4ea8485c6 100644 --- a/scripts/smoke-python-runtime.py +++ b/scripts/smoke-python-runtime.py @@ -10,6 +10,7 @@ import importlib.metadata import json import os import queue +import shutil import subprocess import sys import sysconfig @@ -1330,52 +1331,97 @@ def smoke_packaged_runner(executable: Path) -> None: """Exercise the private subprocess runner through the single-file entry.""" with tempfile.TemporaryDirectory(prefix="dsh-packaged-runner-") as temporary: root = Path(temporary).resolve() - request_path = root / "request.json" - events_path = root / "events.ndjson" - probe = subprocess.run( - [str(executable), "--dsh-internal-subprocess-runner", "--mode", "probe-node"], - cwd=root, - capture_output=True, - text=True, - timeout=30, - check=False, + target_script = ( + "import os,sys; " + "ok = (os.getcwd() == os.environ['PACKAGED_RUNNER_EXPECTED_CWD'] " + "and os.environ.get('DSH_SUBPROCESS_RUNNER') == 'target-collision-restored'); " + "sys.exit(7 if ok else 9)" ) - if probe.returncode != 0: - raise AssertionError(f"packaged runner probe failed: {probe.stderr}") - - request_path.write_text(json.dumps({ - "argv": [sys.executable, "-c", "import sys; sys.exit(7)"], - "cwd": str(root), - "env": {}, - })) - result = subprocess.run( - [ - str(executable), - "--dsh-internal-subprocess-runner", - "--mode", - "node", - "--request", - str(request_path), - "--events", - str(events_path), - ], - cwd=root, - capture_output=True, - text=True, - timeout=30, - check=False, - ) - if result.returncode != 7: - raise AssertionError( - f"packaged runner returned {result.returncode}, expected 7; stderr: {result.stderr}" + if not IS_WINDOWS: + request_path = root / "launch-request.json" + target_env = dict(os.environ) + target_env["DSH_SUBPROCESS_RUNNER"] = "target-collision-restored" + target_env["PACKAGED_RUNNER_EXPECTED_CWD"] = str(root) + request_path.write_text( + json.dumps({"cwd": str(root), "env": target_env}), + encoding="utf-8", ) - events = [json.loads(line) for line in events_path.read_text().splitlines()] - if len(events) != 2 or events[0].get("type") != "started" or events[1] != { - "type": "exit", - "exitCode": 7, + request_path.chmod(0o600) + environment = dict(os.environ) + environment["DSH_SUBPROCESS_RUNNER"] = str(request_path) + result = subprocess.run( + [str(executable), "--", sys.executable, "-c", target_script], + cwd=root, + env=environment, + capture_output=True, + text=True, + timeout=30, + check=False, + ) + if result.returncode != 7 or request_path.exists() or (root / "startup-error.json").exists(): + raise AssertionError( + "packaged POSIX runner failed: " + f"exit={result.returncode}; stdout={result.stdout!r}; stderr={result.stderr!r}" + ) + return + + node = shutil.which("node") + if node is None: + raise AssertionError("packaged Windows runner smoke requires node on PATH") + helper = root / "windows-runner-smoke.mjs" + helper.write_text( + """import { spawn } from 'node:child_process' +const [runtime, target, cwd, targetScript] = process.argv.slice(2) +const child = spawn(runtime, ['--', target, '-c', targetScript], { + cwd, + env: { ...process.env, DSH_SUBPROCESS_RUNNER: 'windows' }, + stdio: ['ignore', 'pipe', 'pipe', 'ipc'], +}) +const messages = [] +let stdout = '' +let stderr = '' +child.stdout.on('data', chunk => { stdout += chunk.toString() }) +child.stderr.on('data', chunk => { stderr += chunk.toString() }) +child.on('message', message => { messages.push(message) }) +const result = await new Promise((resolve, reject) => { + child.once('error', reject) + child.once('spawn', () => { + child.send({ + type: 'start', + cwd, + env: { + ...process.env, + DSH_SUBPROCESS_RUNNER: 'target-collision-restored', + PACKAGED_RUNNER_EXPECTED_CWD: cwd, + }, + }, error => { if (error) reject(error) }) + }) + child.once('close', (exitCode, signal) => { resolve({ exitCode, signal }) }) +}) +process.stdout.write(JSON.stringify({ ...result, messages, stdout, stderr })) +""", + encoding="utf-8", + ) + helper_result = subprocess.run( + [node, str(helper), str(executable), sys.executable, str(root), target_script], + cwd=root, + capture_output=True, + text=True, + timeout=30, + check=False, + ) + if helper_result.returncode != 0: + raise AssertionError(f"packaged Windows runner helper failed: {helper_result.stderr}") + observed = json.loads(helper_result.stdout) + expected = { + "exitCode": 0, "signal": None, - }: - raise AssertionError(f"packaged runner emitted unexpected events: {events}") + "messages": [{"type": "target-exit", "exitCode": 7, "signal": None}], + "stdout": "", + "stderr": "", + } + if observed != expected: + raise AssertionError(f"packaged Windows runner returned unexpected facts: {observed}") def is_idle_notification(message: dict[str, object]) -> bool: diff --git a/scripts/verify-application-entrypoints.ts b/scripts/verify-application-entrypoints.ts index bbe67e5b80..96a216a937 100644 --- a/scripts/verify-application-entrypoints.ts +++ b/scripts/verify-application-entrypoints.ts @@ -32,6 +32,7 @@ const MANIFEST_BIN_ALLOWLIST = new Map([ /** Every executable in a Node application workspace has one explicit role. */ const EXECUTABLE_SOURCE_ALLOWLIST = new Map([ ['apps/cli/src/bin.ts', 'supported dsh application launcher'], + ['apps/cli/src/runtime-bootstrap.ts', 'private packaging-only runtime dispatcher'], ['packages/context/time-context/tests/fixtures/driver.ts', 'test-only subprocess driver'], ['packages/experimental/webworker-packer/bin.js', 'private build-only wrapper'], ['packages/experimental/webworker-packer/src/bin.ts', 'private build-only implementation'], diff --git a/snapshots/session/cordis-inspect-jsdoc/session.jsonl b/snapshots/session/cordis-inspect-jsdoc/session.jsonl index 77a61a5099..6a2ce8a42e 100644 --- a/snapshots/session/cordis-inspect-jsdoc/session.jsonl +++ b/snapshots/session/cordis-inspect-jsdoc/session.jsonl @@ -28,7 +28,7 @@ {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} {"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-subprocess-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:5}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[22,23,24,25,26],"surfaceOp":"append"} {"type":"tool/call","data":{"turn":1,"step":2,"callId":"inspect-subprocess-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"}} -{"type":"tool/result","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"inspect-subprocess-api"},"content":[{"type":"tool-result","toolCallId":"inspect-subprocess-api","content":[{"type":"text","text":"{\n \"platform\": \"host\",\n \"provider\": \"Service\",\n \"method\": \"listService\",\n \"data\": {\n \"mode\": \"service\",\n \"service\": {\n \"key\": \"subprocess\",\n \"description\": \"Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).\\n\\nImplementations must honor these semantics:\\n\\n- Executable paths belong to one execution world shared with the mounted filesystem provider.\\n- spawn returns a live handle synchronously. Its pid is provider-owned and may remain unavailable during asynchronous startup. `done` resolves with the spawned command's exit facts and may reject for spawn or provider failures.\\n- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.\\n- SubprocessHandle.terminate (and the spec's abort signal) starts the provider's documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its identity, signalling, and observability limits.\\n- Disposal of the service terminates all still-running managed processes and awaits their exit.\\n- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.\",\n \"access\": {\n \"optional\": {\n \"expression\": \"ctx.get(\\\"subprocess\\\")\",\n \"requiresUndefinedCheck\": true\n },\n \"hardDependency\": {\n \"inject\": [\n \"subprocess\"\n ],\n \"expression\": \"ctx.subprocess\"\n }\n },\n \"methods\": [\n {\n \"signature\": \"abstract resolveExecutable( command: string, env?: Readonly>, signal?: AbortSignal, ): Promise\",\n \"description\": \"Resolve one configured executable in this provider's execution world. Absolute paths are verified; bare names use the provider's scrubbed PATH plus explicit environment overrides. Relative paths containing separators are rejected: the resolution base is undefined, so providers fail loud instead of guessing.\",\n \"parameters\": [\n {\n \"name\": \"command\",\n \"description\": \"absolute executable path or bare PATH name.\"\n },\n {\n \"name\": \"env\",\n \"description\": \"explicit environment entries used for lookup.\"\n },\n {\n \"name\": \"signal\",\n \"description\": \"aborts remote or local lookup.\"\n }\n ],\n \"returns\": \"a canonical executable path.\"\n },\n {\n \"signature\": \"abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle\",\n \"description\": \"Start one managed child process from a fully-specified spec; this seam applies no defaults.\",\n \"parameters\": [\n {\n \"name\": \"spec\",\n \"description\": \"argv, directory, stdio dispositions, grace, cancellation, and environment.\"\n }\n ],\n \"returns\": \"the live process handle (streams/readers, signalling, outcome promise).\"\n },\n {\n \"signature\": \"abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise\",\n \"description\": \"Allocate a real terminal and start one owned process session. This is the only non-pipe process primitive: implementations own terminal byte I/O, foreground groups, signals, and complete session-tree cleanup.\",\n \"parameters\": [\n {\n \"name\": \"spec\",\n \"description\": \"fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.\"\n }\n ],\n \"returns\": \"the live terminal handle after allocation succeeds.\"\n }\n ]\n },\n \"referencedTypes\": [\n {\n \"name\": \"SubprocessCollect\",\n \"declaration\": \"export interface SubprocessCollect {\\n maxBytes: number;\\n spill?: {\\n maxBytes: number;\\n };\\n}\"\n },\n {\n \"name\": \"SubprocessCollectedOutputs\",\n \"declaration\": \"export interface SubprocessCollectedOutputs {\\n readonly stdout?: SubprocessOutputReader;\\n readonly stderr?: SubprocessOutputReader;\\n}\"\n },\n {\n \"name\": \"SubprocessHandle\",\n \"declaration\": \"export interface SubprocessHandle {\\n readonly pid: number | undefined;\\n readonly stdin: Writable | undefined;\\n readonly stdout: Readable | undefined;\\n readonly stderr: Readable | undefined;\\n readonly collected: SubprocessCollectedOutputs;\\n readonly done: Promise;\\n terminate(): void;\\n waitForExit(signal?: AbortSignal): Promise;\\n}\"\n },\n {\n \"name\": \"SubprocessOutcome\",\n \"declaration\": \"export interface SubprocessOutcome {\\n exitCode: number | null;\\n signal: NodeJS.Signals | null;\\n}\"\n },\n {\n \"name\": \"SubprocessOutputMode\",\n \"declaration\": \"export type SubprocessOutputMode = 'pipe' | 'inherit' | SubprocessCollect;\"\n },\n {\n \"name\": \"SubprocessOutputRead\",\n \"declaration\": \"export interface SubprocessOutputRead {\\n text: string;\\n nextOffset: number;\\n lossy: boolean;\\n spillPath?: string;\\n}\"\n },\n {\n \"name\": \"SubprocessOutputReader\",\n \"declaration\": \"export interface SubprocessOutputReader {\\n readFrom(fromByte: number): SubprocessOutputRead;\\n}\"\n },\n {\n \"name\": \"SubprocessSpawnSpec\",\n \"declaration\": \"export interface SubprocessSpawnSpec {\\n argv: readonly string[];\\n cwd: string;\\n stdio: SubprocessStdio;\\n graceMs: number;\\n signal?: AbortSignal | undefined;\\n env?: NodeJS.ProcessEnv | undefined;\\n}\"\n },\n {\n \"name\": \"SubprocessStdinMode\",\n \"declaration\": \"export type SubprocessStdinMode = 'ignore' | 'pipe' | {\\n readonly data: string;\\n};\"\n },\n {\n \"name\": \"SubprocessStdio\",\n \"declaration\": \"export interface SubprocessStdio {\\n stdin: SubprocessStdinMode;\\n stdout: SubprocessOutputMode;\\n stderr: SubprocessOutputMode;\\n}\"\n },\n {\n \"name\": \"SubprocessTerminalForeground\",\n \"declaration\": \"export interface SubprocessTerminalForeground {\\n processGroupId: number;\\n inputWaiting: boolean;\\n}\"\n },\n {\n \"name\": \"SubprocessTerminalHandle\",\n \"declaration\": \"export interface SubprocessTerminalHandle {\\n readonly pid: number;\\n readonly output: Readable;\\n readonly done: Promise;\\n write(data: string): Promise;\\n inspectForeground(): Promise;\\n signalForeground(signal: SubprocessTerminalSignal): Promise;\\n terminate(): Promise;\\n}\"\n },\n {\n \"name\": \"SubprocessTerminalSignal\",\n \"declaration\": \"export type SubprocessTerminalSignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP';\"\n },\n {\n \"name\": \"SubprocessTerminalSpawnSpec\",\n \"declaration\": \"export interface SubprocessTerminalSpawnSpec {\\n argv: readonly string[];\\n cwd: string;\\n env?: Record | undefined;\\n rows: number;\\n cols: number;\\n graceMs: number;\\n signal?: AbortSignal | undefined;\\n}\"\n }\n ]\n }\n}"}],"isError":false}],"role":"user","id":"{{message:6}}"}},"sourceEventSeqs":[28],"surfaceOp":"append"} +{"type":"tool/result","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"inspect-subprocess-api"},"content":[{"type":"tool-result","toolCallId":"inspect-subprocess-api","content":[{"type":"text","text":"{\n \"platform\": \"host\",\n \"provider\": \"Service\",\n \"method\": \"listService\",\n \"data\": {\n \"mode\": \"service\",\n \"service\": {\n \"key\": \"subprocess\",\n \"description\": \"Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).\\n\\nImplementations must honor these semantics:\\n\\n- Executable paths belong to one execution world shared with the mounted filesystem provider.\\n- spawn returns a live handle synchronously. Target identity remains provider-private; `done` resolves with the spawned command's exit facts and may reject for spawn or provider failures.\\n- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.\\n- SubprocessHandle.terminate (and the spec's abort signal) starts the provider's documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its signalling and observability limits.\\n- Disposal of the service terminates all still-running managed processes and awaits their exit.\\n- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.\",\n \"access\": {\n \"optional\": {\n \"expression\": \"ctx.get(\\\"subprocess\\\")\",\n \"requiresUndefinedCheck\": true\n },\n \"hardDependency\": {\n \"inject\": [\n \"subprocess\"\n ],\n \"expression\": \"ctx.subprocess\"\n }\n },\n \"methods\": [\n {\n \"signature\": \"abstract resolveExecutable( command: string, env?: Readonly>, signal?: AbortSignal, ): Promise\",\n \"description\": \"Resolve one configured executable in this provider's execution world. Absolute paths are verified; bare names use the provider's scrubbed PATH plus explicit environment overrides. Relative paths containing separators are rejected: the resolution base is undefined, so providers fail loud instead of guessing.\",\n \"parameters\": [\n {\n \"name\": \"command\",\n \"description\": \"absolute executable path or bare PATH name.\"\n },\n {\n \"name\": \"env\",\n \"description\": \"explicit environment entries used for lookup.\"\n },\n {\n \"name\": \"signal\",\n \"description\": \"aborts remote or local lookup.\"\n }\n ],\n \"returns\": \"a canonical executable path.\"\n },\n {\n \"signature\": \"abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle\",\n \"description\": \"Start one managed child process from a fully-specified spec; this seam applies no defaults.\",\n \"parameters\": [\n {\n \"name\": \"spec\",\n \"description\": \"argv, directory, stdio dispositions, grace, cancellation, and environment.\"\n }\n ],\n \"returns\": \"the live process handle (streams/readers, signalling, outcome promise).\"\n },\n {\n \"signature\": \"abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise\",\n \"description\": \"Allocate a real terminal and start one owned process session. This is the only non-pipe process primitive: implementations own terminal byte I/O, foreground groups, signals, and complete session-tree cleanup.\",\n \"parameters\": [\n {\n \"name\": \"spec\",\n \"description\": \"fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.\"\n }\n ],\n \"returns\": \"the live terminal handle after allocation succeeds.\"\n }\n ]\n },\n \"referencedTypes\": [\n {\n \"name\": \"SubprocessCollect\",\n \"declaration\": \"export interface SubprocessCollect {\\n maxBytes: number;\\n spill?: {\\n maxBytes: number;\\n };\\n}\"\n },\n {\n \"name\": \"SubprocessCollectedOutputs\",\n \"declaration\": \"export interface SubprocessCollectedOutputs {\\n readonly stdout?: SubprocessOutputReader;\\n readonly stderr?: SubprocessOutputReader;\\n}\"\n },\n {\n \"name\": \"SubprocessHandle\",\n \"declaration\": \"export interface SubprocessHandle {\\n readonly stdin: Writable | undefined;\\n readonly stdout: Readable | undefined;\\n readonly stderr: Readable | undefined;\\n readonly collected: SubprocessCollectedOutputs;\\n readonly done: Promise;\\n terminate(): void;\\n waitForExit(signal?: AbortSignal): Promise;\\n}\"\n },\n {\n \"name\": \"SubprocessOutcome\",\n \"declaration\": \"export interface SubprocessOutcome {\\n exitCode: number | null;\\n signal: NodeJS.Signals | null;\\n}\"\n },\n {\n \"name\": \"SubprocessOutputMode\",\n \"declaration\": \"export type SubprocessOutputMode = 'pipe' | 'inherit' | SubprocessCollect;\"\n },\n {\n \"name\": \"SubprocessOutputRead\",\n \"declaration\": \"export interface SubprocessOutputRead {\\n text: string;\\n nextOffset: number;\\n lossy: boolean;\\n spillPath?: string;\\n}\"\n },\n {\n \"name\": \"SubprocessOutputReader\",\n \"declaration\": \"export interface SubprocessOutputReader {\\n readFrom(fromByte: number): SubprocessOutputRead;\\n}\"\n },\n {\n \"name\": \"SubprocessSpawnSpec\",\n \"declaration\": \"export interface SubprocessSpawnSpec {\\n argv: readonly string[];\\n cwd: string;\\n stdio: SubprocessStdio;\\n graceMs: number;\\n signal?: AbortSignal | undefined;\\n env?: NodeJS.ProcessEnv | undefined;\\n}\"\n },\n {\n \"name\": \"SubprocessStdinMode\",\n \"declaration\": \"export type SubprocessStdinMode = 'ignore' | 'pipe' | {\\n readonly data: string;\\n};\"\n },\n {\n \"name\": \"SubprocessStdio\",\n \"declaration\": \"export interface SubprocessStdio {\\n stdin: SubprocessStdinMode;\\n stdout: SubprocessOutputMode;\\n stderr: SubprocessOutputMode;\\n}\"\n },\n {\n \"name\": \"SubprocessTerminalForeground\",\n \"declaration\": \"export interface SubprocessTerminalForeground {\\n processGroupId: number;\\n inputWaiting: boolean;\\n}\"\n },\n {\n \"name\": \"SubprocessTerminalHandle\",\n \"declaration\": \"export interface SubprocessTerminalHandle {\\n readonly pid: number;\\n readonly output: Readable;\\n readonly done: Promise;\\n write(data: string): Promise;\\n inspectForeground(): Promise;\\n signalForeground(signal: SubprocessTerminalSignal): Promise;\\n terminate(): Promise;\\n}\"\n },\n {\n \"name\": \"SubprocessTerminalSignal\",\n \"declaration\": \"export type SubprocessTerminalSignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP';\"\n },\n {\n \"name\": \"SubprocessTerminalSpawnSpec\",\n \"declaration\": \"export interface SubprocessTerminalSpawnSpec {\\n argv: readonly string[];\\n cwd: string;\\n env?: Record | undefined;\\n rows: number;\\n cols: number;\\n graceMs: number;\\n signal?: AbortSignal | undefined;\\n}\"\n }\n ]\n }\n}"}],"isError":false}],"role":"user","id":"{{message:6}}"}},"sourceEventSeqs":[28],"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":2}} {"type":"step/start","data":{"turn":1,"step":3}} {"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}