[Bug] LocalSubprocessRuntime.spawn() drops the internals argument when calling launchWindowsJob/launchLinuxScope

[boyingliu01]

摘要

LocalSubprocessRuntime.spawn() 调用 launchWindowsJob() / launchLinuxScope() 时漏传第三个参数 internals，导致这两个函数声明的 internals 形参永远是空对象，所有基于 internals 的注入点（runnerInvocation、spawn、taskkill、platform…）全部失效。

影响：文档注释写着「test hook」，但外部插件生态也没有别的接缝可用 —— 任何想在不改 DSH 源码的前提下替换 subprocess runner 的实现都做不到。我在做一个 NativeAOT runner 替代品时踩到了这个坑。

修复是 1 行。

版本

• @deepseek-ai/dsh-subprocess-local 0.2.0-rc.2
• Windows 11 / Node v24.22.1

缺陷位置

lib/index.js:1368：

handle = bindManagedProcess(spec,
  containmentMode === "linux-scope"
    ? launchLinuxScope(spec, env)      // ← 只传 2 个参数
    : launchWindowsJob(spec, env),     // ← 只传 2 个参数
  binding);

而两个 launch 函数的签名都接受第三个参数：

// lib/index.js:478
function launchLinuxScope(spec, targetEnv, internals = {}) {
  const invocation = internals.runnerInvocation ?? spawnRunnerInvocation();   // 479
  ...
}

// lib/index.js:587
function launchWindowsJob(spec, targetEnv, internals = {}) {
  const invocation = internals.runnerInvocation ?? spawnRunnerInvocation();   // 589
  ...
}

spawn() 里明明构造好了 internals（同文件 1361-1364 行），却没有往下传：

const internals = {
  ...this.internals,
  onSpillFailure: this.reportSpillFailure
};

结果 launchWindowsJob 内部 internals 恒为 {}，internals.runnerInvocation 恒为 undefined，必然回落到 spawnRunnerInvocation()。

对比：fallback 分支走 spawnSubprocess(spec, internals)，internals 传到位了（那里 internals.spawn / internals.taskkill / internals.platform 均生效）。所以这是两条路径之间的不一致，不是设计意图。

修复

-  handle = bindManagedProcess(spec, containmentMode === "linux-scope" ? launchLinuxScope(spec, env) : launchWindowsJob(spec, env), binding);
+  handle = bindManagedProcess(spec, containmentMode === "linux-scope" ? launchLinuxScope(spec, env, internals) : launchWindowsJob(spec, env, internals), binding);

internals 里其余字段（spawn / taskkill / platform / probeCurrentTokenJobSupport 等）也会一并恢复生效 —— 目前它们在主路径上同样被静默忽略。

复现

import { LocalSubprocessRuntime } from '@deepseek-ai/dsh-subprocess-local';

const rt = new LocalSubprocessRuntime(ctx);

// 拦截实际 launcher 的 spawn，看它收到什么
let seen = null;
rt.internals.spawn = (cmd, args, opts) => { seen = cmd; return spawn(cmd, args, opts); };
rt.internals.runnerInvocation = ['C:/path/to/my-runner.exe'];

const h = rt.spawn({ argv: ['cmd.exe', '/c', 'echo hi'], /* ... */ });
await h.done;

console.log(seen);
// 期望: 'C:/path/to/my-runner.exe'
// 实际: <node.exe>（且 internals.spawn 一次都没被调用）

internals.spawn 被调用次数为 0，internals.runnerInvocation 被完全忽略。

我实测的收益（说明为什么在意这个）

这不是一个纯理论问题。我在做一个 NativeAOT runner，目标是用原生 exe 替换 runner.js 这个纯转发进程（每次都要付一遍 Node.js 启动成本）。

手动补上这一行后，在真实的 launchWindowsJob 路径上交替采样（3 轮 × 100 次）：

实现	p50	p99
node runner（现状）	156~158ms	249~279ms
NativeAOT runner	63~64ms	142~206ms

• 每次省 92~94ms，比例稳定在 59.1%~59.6%（三轮收敛，0 失败、0 输出不一致）
• p99 改善 73~124ms
• 300 次连续调用零失败，RSS 无累积增长
• 一个附带收益：波动收窄。node runner 的 IQR/中位数离散度是 11.7%~20.5%，AOT 是 1.9%~4.1% —— 对交互式场景来说，减少抖动比降低均值更重要

（题外话：我自己也栽过一次 —— 最初写的 e2e 测试只断言了 internals.runnerInvocation 字段被赋值，就认为"注入成功"，结果插件装到真实 DSH 里毫无作用。是新加了进程级观测才发现。这类"字段设了但没人读"的接缝，如果能有个断言 internals 真的被消费的测试，会安全很多。）

为什么对生态有影响

「Everything is a Plugin」是 DSH 的定位，而 subprocess 是所有工具调用的必经之路。目前第三方如果想优化这条链路：

• 改 DSH 源码 → 升级即失效（用户明确不接受的方案）
• 走 fallback 分支 → 会丢掉 Job Object 进程隔离，且它本来就不接受 runnerInvocation，不可接受
• 没有任何干净接缝 → 只能放弃

internals 目前注释为 test hook，如果无意长期作为扩展点，那这个 issue 至少也该修掉「声明了参数却不传」的不一致；如果有意开放，那这 1 行就是前提。

附

• 修复前后我都跑过完整验证：真实 DSH 实例启动、进程级观测、熔断降级、300 次稳定性
• 我的项目仓库：boyingliu01/dsh-aot-runner（当前打的是本地临时补丁，等上游修复）
• 如果这个方向你们已经在做了，或者 internals 计划改成别的形态，也欢迎说一声，我这边好对齐

谢谢！

[boyingliu01]

关联 #12532

[aturzone]

This is the same class as #12532 (after the earlier refactor): LocalSubprocessRuntime.spawn() builds internals and passes it only to the fallback spawnSubprocess, while launchWindowsJob / launchLinuxScope are called without it, so the declared runner seams are unreachable on production managed paths.

Fix on the fork (same change covers this thread): fix/subprocess-managed-internals @ ab42e3b983 — the runtime internals type now carries runnerInvocation / resolveRunnerInvocation / runnerAvailable, and spawn() lifts the present ones into both launches. The isolated-runtime test asserts the selected launch receives them and fails without the change. Details and gates are in the #12532 comment.

[boyingliu01]

补充：master 仍未修，且没有 issue/PR 通道可以推进

现状复核（2026-11-10，直接读 master 源码）

packages/subprocess/subprocess-local/src/index.ts:209-210：

? launchWindowsJob(spec, env)
: launchLinuxScope(spec, env, linuxScope.literalArgv)

@aturzone 在上面给出的修复分支 fix/subprocess-managed-internals @ ab42e3b983
把 internals 提升进了两个 launch，但该修复未进入 master。
发布版 0.2.2-rc.1 也仍带此缺陷（拆包验证：lib/index.js:1560）。

结果（为什么这个 seam 至今无人可用）

internals.runnerInvocation 在 managed 路径上永远读不到。
任何想通过这个 seam 替换子进程 runner 的实现（本项目就是一个）
在正式版上都无法生效，只能靠本地 1 行补丁。

这不是"某个插件不兼容"，而是声明出来的扩展点在生产路径上不可达。

为什么只能在这里说

本仓库已关闭 issues/PR 功能（has_issues=false），
开 PR 会 404。所以这条缺陷目前没有可用的正式跟踪入口 ——
discussion 是唯一渠道，但 discussion 不会进入维护者的 issue 队列。

如果维护者愿意，我可以把这个修复整理成 PR（或者由你们从 fork 合入）。
ab42e3b983 那个改动本身是我见过最干净的版本，直接合入即可。

需求方背景（供评估优先级）

本项目是 DSH 的 Windows x64 专用 AOT runner 插件，通过
internals.runnerInvocation 把子进程启动器换成 NativeAOT 二进制。
在真实 IPC 协议下实测：

• p50 延迟从 ~276ms 降到 ~114ms
• 高负载（CPU 100%）下尾抖（p90−p50）node 267ms vs AOT 40ms

也就是说这一个 1 行参数的缺失，挡住了约 60% 的子进程启动开销。
（测量口径：hostname.exe 作地板扣除后的 runner 跳，node vs AOT 交替采样；
高负载数据来自 bash 完整生命周期，未扣地板，两组的共享成本已在原始记录中标注。）

MIT 许可，可以无痛并入上游（连 vendor 补丁机制一起删掉）。