@zhushanwen/subagent-engine-sdk 0.2.0

package/src/logger.ts

@@ -0,0 +1,105 @@
+// src/logger.ts
+//
+// 日志 facade（引擎侧原语，自 core src/core/logger.ts 迁入 @zhushanwen/subagent-engine-sdk）。
+// 迁移处置（impl-plan §2.1：「日志 facade」直接搬；kill-chain 行「logger 走 SDK facade」）：
+// core 版经 getHostServices()（configureCore 时序契约）动态解析宿主实现；SDK 进程
+// （引擎 CLI）无 configureCore 通道，同款「调用时动态解析」语义改为经可注入
+// LoggerSink——引擎 CLI 启动早期 configureLoggerSink(sink) 注入宿主形态 sink，
+// 未注入时落缺省 console 出口（对齐 core NULL_HOST.log 语义：warn/error 走 console、
+// debug no-op）。facade 代理而非绑死实现的时序契约（模块顶层 getLogger 先于配置、
+// 配置后透明切换）与 core 版逐字一致。
+//
+// CJS 多 entry 内联副本的实例分裂影响 = facadeCache 分裂（同 component 引用不同）；
+// facade 无状态、sink 解析每次调用发生，无语义后果——与 core 版同结论。
+
+/**
+ * SDK 侧 logger sink（引擎 CLI 注入宿主形态日志出口；core 版对应 HostServices.log）。
+ */
+export interface LoggerSink {
+  log(level: LogLevel, component: string, message: string, data?: unknown): void;
+}
+
+/** 日志级别。对齐 core logger 的 LogLevel（三值，无 info）。 */
+export type LogLevel = "debug" | "warn" | "error";
+
+/** logger 接口。与 core CoreLogger 结构兼容——迁移调用面（方法名/参数序）逐文件等价。 */
+export interface CoreLogger {
+  debug(msg: string, data?: unknown): void;
+  warn(msg: string, data?: unknown): void;
+  error(msg: string, data?: unknown): void;
+}
+
+// sink 配置态：globalThis[Symbol.for] slot（core host-services 同款范式）——模块级
+// `let` 在 dist 双形态 / CJS 多 entry 内联副本下会被分裂，slot 形态跨副本一致。
+const SINK_SLOT_KEY = Symbol.for("@zhushanwen/subagent-engine-sdk.logger-sink");
+
+type SinkSlot = { current: LoggerSink | undefined };
+
+function getSinkSlot(): SinkSlot {
+  let slot = Reflect.get(globalThis, SINK_SLOT_KEY) as SinkSlot | undefined;
+  if (!slot) {
+    slot = { current: undefined };
+    Reflect.set(globalThis, SINK_SLOT_KEY, slot);
+  }
+  return slot;
+}
+
+/** 缺省 console 出口（未注入 sink 时的日志不丢）。格式对齐 core NULL_HOST.log。 */
+const CONSOLE_SINK: LoggerSink = {
+  log(level, component, message, data) {
+    const line = `[${component}] ${message}`;
+    // data 作第二参数；缺省时必须省略——node console 会把显式 undefined 格式化成
+    // " undefined" 尾巴污染每行输出。
+    if (level === "error") {
+      if (data === undefined) console.error(line);
+      else console.error(line, data);
+      return;
+    }
+    if (level === "warn") {
+      if (data === undefined) console.warn(line);
+      else console.warn(line, data);
+      return;
+    }
+    // debug 缺省 no-op：对齐 core NULL_HOST 语义（未配置期多为模块加载窗口，刷屏无
+    // 诊断价值）；warn/error 不可静默。
+  },
+};
+
+function currentSink(): LoggerSink {
+  return getSinkSlot().current ?? CONSOLE_SINK;
+}
+
+/**
+ * 注入日志 sink（引擎 CLI 启动早期调用；重复调用后者覆盖——测试切 sink 依赖此语义）。
+ * 解析发生在每次 logger 方法调用时，模块顶层已缓存的 logger 透明切换，无加载顺序依赖。
+ */
+export function configureLoggerSink(sink: LoggerSink): void {
+  getSinkSlot().current = sink;
+}
+
+/** 测试隔离专用：清空 sink 配置态（生产禁用）。 */
+export function resetLoggerSinkForTests(): void {
+  getSinkSlot().current = undefined;
+}
+
+// 与 core getLogger singleton 惯例对齐（同 component 同引用）。
+// facade 自身无状态（解析发生在方法内），缓存只为引用稳定，不影响透明切换。
+const facadeCache = new Map<string, CoreLogger>();
+
+export function getLogger(component: string): CoreLogger {
+  const existing = facadeCache.get(component);
+  if (existing) return existing;
+  const facade: CoreLogger = {
+    debug(msg, data) {
+      currentSink().log("debug", component, msg, data);
+    },
+    warn(msg, data) {
+      currentSink().log("warn", component, msg, data);
+    },
+    error(msg, data) {
+      currentSink().log("error", component, msg, data);
+    },
+  };
+  facadeCache.set(component, facade);
+  return facade;
+}

package/src/logs/stderr-rotation.ts

@@ -0,0 +1,166 @@
+// src/logs/stderr-rotation.ts
+//
+// 引擎侧 stderr tee 的实例维度文件名 + 轮转 + 过期清理（单源实现，前缀参数化——
+// 两引擎包（pi-subagent-cli / zcode-subagent-cli）各自的 logs/stderr-rotation.ts
+// 是本模块的薄包装，只绑定各自前缀常量）。
+//
+// 清理三判据（三者同时成立才删，缺一不删）：
+//   1. 同前缀（调用方绑定）；2. pid 已死（process.kill(pid,0) 跨实例探测，存活实例
+//   的文件一律不删）；3. mtime 过期（XYZ_LOG_KEEP_DAYS，缺省 7 天）。
+// 轮转参数读宿主同款 env：XYZ_LOG_MAX_BYTES（缺省 50MB）/ XYZ_LOG_KEEP_DAYS。
+
+import * as fs from "node:fs";
+import { dirname, join } from "node:path";
+
+/** 缺省轮转阈值（与宿主 logger 同源缺省：50MB）。 */
+const BYTES_PER_KB = 1024;
+const DEFAULT_MAX_FILE_MB = 50;
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+const MINUTES_PER_HOUR = 60;
+const HOURS_PER_DAY = 24;
+
+export const DEFAULT_STDERR_MAX_BYTES = DEFAULT_MAX_FILE_MB * BYTES_PER_KB * BYTES_PER_KB;
+
+const DAY_MS = HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
+
+/** 缺省保留天数（与宿主 logger 同源缺省：7 天）。 */
+export const DEFAULT_STDERR_KEEP_DAYS = 7;
+
+/** 轮转参数（env 覆盖面 = 宿主 logger 同款 XYZ_LOG_* 两键）。 */
+export interface StderrRotationParams {
+  maxBytes: number;
+  keepDays: number;
+}
+
+function positiveIntEnv(env: NodeJS.ProcessEnv, key: string): number | undefined {
+  const raw = env[key];
+  if (raw === undefined || raw.trim() === "") return undefined;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+/** 读 env 解析轮转参数（非法值回缺省——取证面配置不拖垮主通道）。 */
+export function stderrRotationParams(env: NodeJS.ProcessEnv): StderrRotationParams {
+  return {
+    maxBytes:
+      positiveIntEnv(env, "XYZ_LOG_MAX_BYTES") ?? DEFAULT_STDERR_MAX_BYTES,
+    keepDays:
+      positiveIntEnv(env, "XYZ_LOG_KEEP_DAYS") ?? DEFAULT_STDERR_KEEP_DAYS,
+  };
+}
+
+/** 实例维度 stderr tee 路径：<engineDataDir>/logs/<prefix><pid>.log。 */
+export function stderrLogPathFor(engineDataDir: string, pid: number, prefix: string): string {
+  return join(engineDataDir, "logs", `${prefix}${pid}.log`);
+}
+
+/** 从文件名解析实例 pid（非本前缀形态返回 undefined——调用方跳过）。 */
+export function stderrLogPidOf(fileName: string, prefix: string): number | undefined {
+  if (!fileName.startsWith(prefix)) return undefined;
+  const rest = fileName.slice(prefix.length);
+  // 兼容轮转副本形态 <pid>.log.<timestamp>
+  const pidToken = rest.split(".", 1)[0] ?? "";
+  if (!/^\d+$/.test(pidToken)) return undefined;
+  return Number(pidToken);
+}
+
+/** pid 存活探测（跨实例：ESRCH = 死；EPERM = 存活但非属主，按存活保守处理）。 */
+export function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * 尺寸轮转：当前文件超过 maxBytes 时 rename 为 `<path>.<时间戳>` 副本并返回
+ * true（调用方懒重开新文件继续 append）。rename 失败返回 false（继续 append 原
+ * 文件——轮转是取证面优化，不是主通道）。
+ */
+export function rotateStderrLogIfNeeded(
+  path: string,
+  params: StderrRotationParams,
+): boolean {
+  let size: number;
+  try {
+    size = fs.statSync(path).size;
+  } catch {
+    return false;
+  }
+  if (size <= params.maxBytes) return false;
+  const rotated = `${path}.${Date.now()}`;
+  try {
+    fs.renameSync(path, rotated);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface CleanupResult {
+  /** 已删除文件数。 */
+  deleted: number;
+  /** 命中前缀但跳过（pid 存活 / mtime 未过期 / 探测不确定）的文件数。 */
+  skipped: number;
+}
+
+/**
+ * 过期清理：扫描 logsDir 下同前缀文件，三判据同时成立才删。目录缺失/读失败返回
+ * 零删除（取证面 best-effort）。
+ */
+export function cleanupStaleStderrLogs(
+  logsDir: string,
+  env: NodeJS.ProcessEnv,
+  prefix: string,
+  now: number = Date.now(),
+): CleanupResult {
+  const params = stderrRotationParams(env);
+  const expiryMs = params.keepDays * DAY_MS;
+  let deleted = 0;
+  let skipped = 0;
+  let names: string[];
+  try {
+    names = fs.readdirSync(logsDir);
+  } catch {
+    return { deleted, skipped };
+  }
+  for (const name of names) {
+    const pid = stderrLogPidOf(name, prefix);
+    if (pid === undefined) continue;
+    // 判据 2：pid 存活 → 该实例的文件（含轮转副本）一律不删
+    if (isPidAlive(pid)) {
+      skipped += 1;
+      continue;
+    }
+    // 判据 3：mtime 未过期 → 保留
+    const full = join(logsDir, name);
+    try {
+      if (fs.statSync(full).mtimeMs > now - expiryMs) {
+        skipped += 1;
+        continue;
+      }
+    } catch {
+      continue;
+    }
+    try {
+      fs.rmSync(full, { force: true });
+      deleted += 1;
+    } catch {
+      skipped += 1;
+    }
+  }
+  return { deleted, skipped };
+}
+
+/** 便捷入口：对 tee 路径所在 logs 目录做过期清理（流打开时机调用，每代一次）。 */
+export function cleanupSiblingStderrLogs(
+  logPath: string,
+  env: NodeJS.ProcessEnv,
+  prefix: string,
+  now?: number,
+): CleanupResult {
+  return cleanupStaleStderrLogs(dirname(logPath), env, prefix, now);
+}

package/src/nesting-guard.ts

@@ -0,0 +1,140 @@
+// src/nesting-guard.ts
+//
+// 嵌套防护（引擎侧原语，自 core execution/engine/common/nesting-guard.ts 迁入
+// @zhushanwen/subagent-engine-sdk，实现体逐字等价）。迁移处置：无 core 内部依赖 →
+// 直接搬（impl-plan §2.1 原语迁移处置表）；唯二差异：
+//   1. nestedSpawnRejectedError 自 core common/errors.ts 内联进本模块（errors.ts 不在
+//      迁移清单，本模块只消费它这一个构造器；文案与恢复指引逐字保留）；
+//   2. 头部注释的模块路径改为 SDK 落点。
+//
+// 设计权威源：docs/architecture/subagent-engine-abstraction.md D8（嵌套防护双层）：
+//   统一 XYZ_AGENT_SUBAGENT=1 标记（所有引擎 spawn 都注入，引擎 adapter 检测到即拒绝
+//   递归派发）+ 剥离各引擎原生标记（CC 的 CLAUDECODE / zsub 的 ZSW_NESTED / pi 的
+//   PI_SUBAGENT_*）防继承泄漏——子代理环境的旧标记会让孙代理误判自己已在嵌套层。
+//
+// 为什么 env 标记是唯一跨引擎可靠手段（被否方案见设计）：「隔离目录里不装扩展」
+// 依赖配置洁癖，且 opencode/CC 会吃项目级配置；env 由宿主显式控制，随 spawn 必达。
+//
+// [D3-⑤ 嵌套防护合一] 进程内执行嵌套上下文（原 SubagentService.execCtxAls，pi 路径
+// 私有）并入本文件——「嵌套防护」的两层机制（跨进程 env 标记 / 进程内 ALS 深度计数）
+// 单点于公共层。设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-⑤
+// + 双轨清单 #10。
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** 统一嵌套标记 env 名（D8）。值恒 '1'。 */
+export const NESTED_SPAWN_ENV = "XYZ_AGENT_SUBAGENT";
+
+/** 需剥离的引擎原生嵌套标记（精确名）。 */
+const NATIVE_NESTED_KEYS: readonly string[] = ["CLAUDECODE", "ZSW_NESTED"];
+
+/** 需剥离的引擎原生嵌套标记前缀（pi 家族）。 */
+const NATIVE_NESTED_PREFIXES: readonly string[] = ["PI_SUBAGENT_"];
+
+/** env 对象形状（NodeJS.ProcessEnv 的结构子集，测试可传普通对象）。 */
+export type SpawnEnv = Record<string, string | undefined>;
+
+/**
+ * nested_spawn_rejected 的结构化错误（自 core errors.ts 内联；code/recovery 与 core
+ * 词表逐字一致，EngineError 类形态对齐 SDK protocol/error-codes.ts 的 EngineSdkError）。
+ */
+export class NestedSpawnRejectedError extends Error {
+  readonly code = "nested_spawn_rejected";
+  /** 恢复指引：指向具体下一步，非安慰性文案。 */
+  readonly recovery: string;
+
+  constructor() {
+    super(
+      "nested_spawn_rejected: this process is already a subagent (XYZ_AGENT_SUBAGENT=1)",
+    );
+    this.name = "NestedSpawnRejectedError";
+    this.recovery =
+      "Subagents must not spawn further subagents (unbounded recursion guard). " +
+      "Do the work directly inside the current task instead of delegating.";
+  }
+}
+
+/**
+ * 构造子代理 spawn env：注入 XYZ_AGENT_SUBAGENT=1 + 剥离引擎原生嵌套标记。
+ * 返回新对象，不改入参（spawn env 组装链中的多层 spread 安全）。
+ */
+export function buildNestedSpawnEnv(baseEnv: SpawnEnv): SpawnEnv {
+  const env: SpawnEnv = {};
+  for (const [key, value] of Object.entries(baseEnv)) {
+    if (NATIVE_NESTED_KEYS.includes(key)) continue;
+    if (NATIVE_NESTED_PREFIXES.some((prefix) => key.startsWith(prefix))) continue;
+    env[key] = value;
+  }
+  env[NESTED_SPAWN_ENV] = "1";
+  return env;
+}
+
+/**
+ * 嵌套 spawn 防护断言：检测到统一标记（本进程已是 subagent）抛
+ * nested_spawn_rejected——文案说明防护规则、指向 task 内自行完成。
+ * 调用点：subagent 工具入口（进程创建前拒绝，D11 处置三级）。
+ */
+export function assertNotNestedSpawn(env: SpawnEnv): void {
+  if (env[NESTED_SPAWN_ENV] === "1") {
+    throw new NestedSpawnRejectedError();
+  }
+}
+
+// ============================================================
+// [D3-⑤] 进程内执行嵌套上下文（原 SubagentService.execCtxAls 下沉）
+// ============================================================
+
+/** 执行嵌套状态：当前正在跑的 record 身份 + 递归深度（D-033 通用嵌套深度护栏的计数载体）。 */
+export interface ExecutionNestingState {
+  recordId: string | undefined;
+  depth: number;
+}
+
+/**
+ * 进程内执行嵌套上下文（[D3-⑤] 从 SubagentService 的 execCtxAls 私有字段并入公共层）。
+ *
+ * 机制（原样迁移，行为零变化）：
+ *   - ALS 按异步调用链传递当前 record 身份：B run() 期间包 this 上下文，B 内创建 C 时
+ *     读到 B → C.parentRecordId=B.id、C.depth=B.depth+1；主 session 链上无 store → 顶层。
+ *   - 进程级基线兜底 [ALS 断裂修复]：pi RPC mode 的 stdin JSONL 是事件回调式
+ *     （attachJsonlLineReader stream.on("data")），每个命令是独立异步链，enterWith 的
+ *     store 不会贯穿到后续 tool 调用事件（实测：递归第二层 parentRecordId/depth 丢失
+ *     而 rootSessionId 正确）。基线 = 本进程自己的身份（initSession 从 env 读取）：
+ *     读 ALS store 失败时兜底，保证「本进程派发的 subagent 都是本进程记录的孩子」。
+ *
+ * 实例归属：per-Service（基线随宿主进程身份而异），Service 构造时创建并持有。
+ * 深度上限判据（MAX_FORK_DEPTH）留在调用方——上限常量属 execution 层
+ * （session-context-resolver），公共层只提供状态存取单点。
+ */
+export class ExecutionNestingContext {
+  private readonly als = new AsyncLocalStorage<ExecutionNestingState>();
+  private baselineState: ExecutionNestingState | null = null;
+
+  /** 建立进程级基线（initSession：有 env 自我标记 → env 身份；根进程 → null 顶层）。 */
+  setBaseline(state: ExecutionNestingState | null): void {
+    this.baselineState = state;
+  }
+
+  /** 读当前嵌套状态：ALS store 优先，断裂时基线兜底（顶层 = null）。 */
+  current(): ExecutionNestingState | null {
+    return this.als.getStore() ?? this.baselineState;
+  }
+
+  /**
+   * 读进程级基线（与 current() 的差异：不看 ALS store——直接父归属校验等场景要的是
+   * 「本进程自己的身份」而非「当前异步链正在跑的 record 身份」）。
+   */
+  baseline(): ExecutionNestingState | null {
+    return this.baselineState;
+  }
+
+  /** 包裹执行（B run() 期间挂 B 身份——内层创建 C 时 current() 读到 B）。 */
+  run<T>(state: ExecutionNestingState, fn: () => T): T {
+    return this.als.run(state, fn);
+  }
+
+  /** 顶层 enterWith（initSession 建立基线身份后挂入当前异步链）。 */
+  enterWith(state: ExecutionNestingState): void {
+    this.als.enterWith(state);
+  }
+}

package/src/node-executor.ts

@@ -0,0 +1,272 @@
+// src/node-executor.ts
+//
+// 引擎 CLI 启动解析（W9，impl-plan §2.9「启动解析（宿主 × 平台二维矩阵）」）。
+//
+// 为什么在 SDK：core/引擎包都不可 import runtime（runtime 包只存在于 xyz-agent 宿主
+// 链），而矩阵的三宿主（pi 扩展 / runtime sidecar / standalone）两侧都要消费同一套
+// 解析规则——探针逻辑在 SDK 侧复刻 runtime 先例
+// packages/runtime/src/infra/relay/relay-env.ts:47-90（行为保持一致：同超时、同
+// --eval process.exit(0) 探针体、同 PATH/HOME 最小 env、同 Electron RUN_AS_NODE 条件）。
+//
+// 矩阵（规格逐行对应）：
+//   ① pi 扩展宿主（打包）：process.execPath 是 Bun standalone binary，再拉就是又起
+//      一个 pi——必须用注入执行器 XYZ_AGENT_ENGINE_NODE（与 relay 的
+//      XYZ_SUBAGENT_RELAY_NODE 不复用，单一名字）；执行器为 Electron 二进制时同时带
+//      ELECTRON_RUN_AS_NODE=1；首次使用前跑探针，失败 → engine_not_found + 指引。
+//   ② runtime sidecar：process.execPath + ELECTRON_RUN_AS_NODE=1（sidecar 本身由主进程
+//      以该形态 spawn，其 execPath 即宿主 Electron / dev node）。
+//   ③ standalone pi / zsw：PATH node（缺 node → engine_not_found + 安装指引）。
+//   Windows：入口 .mjs 不需 shim；引擎声明 .cmd → 禁 shell:true，改显式
+//   cmd.exe /c + 参数数组。
+//
+// env 名常量与 packages/shared/src/constants.ts 的 W9 挂载块同源（SDK 不 import
+// shared——F9，见 env.ts 头注释同款理由）。
+
+import { spawn } from "node:child_process";
+
+import { EngineSdkError } from "./protocol/error-codes.ts";
+
+/** L0 注入的引擎执行器路径 env（与 relay 的 XYZ_SUBAGENT_RELAY_NODE 不复用）。 */
+export const ENGINE_NODE_ENV = "XYZ_AGENT_ENGINE_NODE";
+
+/** 探针超时（与 relay-env.ts 先例一致：spawn 执行器跑 --eval "process.exit(0)" 的上限）。 */
+const PROBE_TIMEOUT_MS = 5_000;
+
+/**
+ * 探针：验证执行器能以纯 node 语义执行 JS（先例 = runtime relay-env.ts:47-90）。
+ *
+ * 为什么需要：打包态 pi 宿主的候选执行器可能是 Electron 二进制——直接当 node 用会
+ * 拉起 GUI，必须同 env 注入 ELECTRON_RUN_AS_NODE=1 才是纯 node 模式；探针被证伪则
+ * 按矩阵① 报 engine_not_found（带可操作指引），不静默回落 PATH 探测。
+ */
+export function probeNodeExecutor(
+  execPath: string,
+  isElectron: boolean,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false;
+    let child: ReturnType<typeof spawn> | null = null;
+    const finish = (ok: boolean): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        child?.kill("SIGKILL");
+      } catch {
+        // 已退出，正常路径
+        void 0;
+      }
+      resolve(ok);
+    };
+    const env: Record<string, string> = {};
+    if (process.env.PATH !== undefined) env.PATH = process.env.PATH;
+    if (process.env.HOME !== undefined) env.HOME = process.env.HOME;
+    if (isElectron) env.ELECTRON_RUN_AS_NODE = "1";
+
+    try {
+      child = spawn(execPath, ["--eval", "process.exit(0)"], {
+        env,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+    } catch {
+      resolve(false);
+      return;
+    }
+    const timer = setTimeout(() => finish(false), PROBE_TIMEOUT_MS);
+    timer.unref();
+    child.on("error", () => finish(false));
+    child.on("exit", (code) => finish(code === 0));
+  });
+}
+
+/** 探针结果缓存（key = execPath:isElectron）。失败也缓存——重试窗口留给宿主重启。 */
+const probeCache = new Map<string, Promise<boolean>>();
+
+function probeCached(execPath: string, isElectron: boolean): Promise<boolean> {
+  const key = `${execPath}:${isElectron}`;
+  let p = probeCache.get(key);
+  if (!p) {
+    p = probeNodeExecutor(execPath, isElectron);
+    probeCache.set(key, p);
+  }
+  return p;
+}
+
+/** 测试钩子：清探针缓存（生产无调用方；与 relay-env resetRelayNodeProbeCache 同款）。 */
+export function resetEngineNodeProbeCache(): void {
+  probeCache.clear();
+}
+
+/** 宿主形态（矩阵行；EngineClient 的 hostKind 自由字符串经 hostKindOf 归一）。 */
+export type EngineNodeHostKind = "pi-extension" | "runtime-sidecar" | "standalone";
+
+/** resolveEngineNodeLaunch 的可注入项（测试隔离用；生产全部走缺省推导）。 */
+export interface EngineNodeLaunchOptions {
+  /** 引擎 CLI 入口绝对路径（descriptor command / staged bin 解析结果）。 */
+  entryPath: string;
+  /** 入口附加参数（descriptor args；缺省 []）。 */
+  args?: readonly string[];
+  /** 宿主形态。 */
+  hostKind: EngineNodeHostKind;
+  /** 读取 XYZ_AGENT_ENGINE_NODE 的 env 快照（矩阵① 的注入通道）。 */
+  env?: Record<string, string | undefined>;
+  /** 宿主 process.execPath（缺省 process.execPath）。 */
+  execPath?: string;
+  /** 宿主自身是否 Electron（缺省 process.versions.electron !== undefined）。 */
+  isElectronHost?: boolean;
+  /** 平台覆盖（缺省 process.platform）。 */
+  platform?: NodeJS.Platform;
+}
+
+/** 解析结果：spawn(command, args) 形态 + buildEngineChildEnv 的 electronRunAsNode 输入。 */
+export interface EngineNodeLaunch {
+  command: string;
+  args: string[];
+  /** 执行器为 Electron 二进制 → true（L0 注入 ELECTRON_RUN_AS_NODE=1）。 */
+  electronRunAsNode: boolean;
+}
+
+function engineNotFound(detail: string, recovery: string): EngineSdkError {
+  return new EngineSdkError("engine_not_found", detail, recovery);
+}
+
+/** 传入 opts.env 的快照（矩阵① env 缺省 = 宿主 process.env）。 */
+function launchEnvOf(opts: EngineNodeLaunchOptions): Record<string, string | undefined> {
+  return opts.env ?? process.env;
+}
+
+/**
+ * 矩阵①：pi 扩展宿主（打包）——必须用注入执行器 XYZ_AGENT_ENGINE_NODE
+ * （env 缺失 = engine_not_found；执行器探针失败 = engine_not_found + 指引）。
+ */
+async function resolvePiExtensionLaunch(
+  entryPath: string,
+  entryArgs: string[],
+  env: Record<string, string | undefined>,
+): Promise<EngineNodeLaunch> {
+  const engineNode = env[ENGINE_NODE_ENV]?.trim();
+  if (engineNode === undefined || engineNode === "") {
+    throw engineNotFound(
+      `pi extension host must spawn engines via injected executor ${ENGINE_NODE_ENV}, `
+        + `but it is not set (host process.execPath is the pi binary, not a node executor)`,
+      `The xyz-agent runtime injects ${ENGINE_NODE_ENV} when spawning the pi host. `
+        + `If you are running the extension inside a packaged app, report this as a packaging `
+        + `regression; standalone pi installs do not use the pi-extension host kind.`,
+    );
+  }
+  // 执行器为 Electron 二进制时宿主会同时注入 ELECTRON_RUN_AS_NODE=1（矩阵① 同点注入）
+  const isElectron = env.ELECTRON_RUN_AS_NODE === "1";
+  if (!(await probeCached(engineNode, isElectron))) {
+    throw engineNotFound(
+      `injected node executor failed the probe: ${engineNode} (isElectron=${isElectron})`,
+      `Verify the executor exists and can run plain node semantics `
+        + `(Electron binaries need ELECTRON_RUN_AS_NODE=1). The host re-probes after restart.`,
+    );
+  }
+  return { command: engineNode, args: [entryPath, ...entryArgs], electronRunAsNode: isElectron };
+}
+
+/**
+ * 矩阵②：runtime sidecar——process.execPath + ELECTRON_RUN_AS_NODE=1（Electron 宿主时，
+ * 探针先行）。
+ */
+async function resolveRuntimeSidecarLaunch(
+  entryPath: string,
+  entryArgs: string[],
+  opts: EngineNodeLaunchOptions,
+): Promise<EngineNodeLaunch> {
+  const execPath = opts.execPath ?? process.execPath;
+  const isElectron = opts.isElectronHost ?? process.versions.electron !== undefined;
+  if (!(await probeCached(execPath, isElectron))) {
+    throw engineNotFound(
+      `runtime sidecar executor failed the probe: ${execPath} (isElectron=${isElectron})`,
+      `The sidecar process.execPath must run plain node semantics (ELECTRON_RUN_AS_NODE=1 `
+        + `for Electron binaries). Check how the runtime sidecar was spawned.`,
+    );
+  }
+  return { command: execPath, args: [entryPath, ...entryArgs], electronRunAsNode: isElectron };
+}
+
+/** 矩阵③：standalone——PATH node（探针被证伪 = engine_not_found + 安装指引）。 */
+async function resolveStandaloneLaunch(
+  entryPath: string,
+  entryArgs: string[],
+): Promise<EngineNodeLaunch> {
+  if (!(await probeCached("node", false))) {
+    throw engineNotFound(
+      `no usable 'node' on PATH for standalone engine launch (entry: ${entryPath})`,
+      `Install Node.js >= 22 and ensure 'node' is on PATH `
+        + `(https://nodejs.org/), or configure the engine explicitly via subagents/config.json.`,
+    );
+  }
+  return { command: "node", args: [entryPath, ...entryArgs], electronRunAsNode: false };
+}
+
+/**
+ * 宿主 × 平台二维矩阵解析（W9 §2.9）。返回 spawn argv；不直接 spawn——调用方
+ * （EngineClient / runtime）持有各自的平台参数（detached / 进程组收割语义）。
+ *
+ * 判定序（与规格逐行对应）：
+ *   Windows + entry .cmd → cmd.exe /c 显式形态（禁 shell:true 的注入面）；
+ *   pi-extension → 注入执行器（env XYZ_AGENT_ENGINE_NODE），缺失/探针失败 =
+ *     engine_not_found + 指引；
+ *   runtime-sidecar → process.execPath（Electron 时 electronRunAsNode，探针先行）；
+ *   standalone → PATH node（探针失败 = engine_not_found + 安装指引）；
+ *   其余（dev 形态、非 Windows 非 .cmd、无矩阵命中的兜底）→ 直接 spawn 入口本体
+ *   （shebang `#!/usr/bin/env node` 走 PATH node——引擎 bin 均带 shebang，dev/独立
+ *   安装形态与现状一致）。
+ */
+export async function resolveEngineNodeLaunch(
+  opts: EngineNodeLaunchOptions,
+): Promise<EngineNodeLaunch> {
+  const platform = opts.platform ?? process.platform;
+  const entryArgs = [...(opts.args ?? [])];
+
+  // Windows 规则：入口 .cmd → 显式 cmd.exe /c + 参数数组（禁 shell:true）
+  if (platform === "win32" && opts.entryPath.toLowerCase().endsWith(".cmd")) {
+    return {
+      command: "cmd.exe",
+      args: ["/c", opts.entryPath, ...entryArgs],
+      electronRunAsNode: false,
+    };
+  }
+
+  // 非 JS 入口（原生二进制 / shell 脚本形态的引擎或测试 fixture）自管理执行体：
+  // 不经 node 执行器改写、不探针——直接 spawn 入口本体（shebang/原生入口语义）。
+  if (!/\.(?:js|mjs|cjs|ts)$/i.test(opts.entryPath)) {
+    return { command: opts.entryPath, args: entryArgs, electronRunAsNode: false };
+  }
+
+  if (opts.hostKind === "pi-extension") {
+    return resolvePiExtensionLaunch(opts.entryPath, entryArgs, launchEnvOf(opts));
+  }
+
+  if (opts.hostKind === "runtime-sidecar") {
+    return resolveRuntimeSidecarLaunch(opts.entryPath, entryArgs, opts);
+  }
+
+  if (opts.hostKind === "standalone") {
+    return resolveStandaloneLaunch(opts.entryPath, entryArgs);
+  }
+
+  // 非矩阵形态（理论不可达——hostKind 是封闭联合）；保守回落直接 spawn 入口本体。
+  return { command: opts.entryPath, args: entryArgs, electronRunAsNode: false };
+}
+
+/**
+ * EngineClient 的自由字符串 hostKind（'pi' / 'runtime' / …）→ 矩阵行归一：
+ *   'runtime*' → runtime-sidecar（②：sidecar execPath 权威）；
+ *   env 已注入 XYZ_AGENT_ENGINE_NODE（打包态 runtime 注入主 pi 进程的通道）→
+ *     pi-extension（①：必须用注入执行器——pi 宿主自身 execPath 是 pi binary）；
+ *   其余 → standalone（③：PATH node）。
+ */
+export function hostKindOf(
+  hostKind: string,
+  env: Record<string, string | undefined> = process.env,
+): EngineNodeHostKind {
+  if (hostKind.startsWith("runtime")) return "runtime-sidecar";
+  const engineNode = env[ENGINE_NODE_ENV]?.trim();
+  if (engineNode !== undefined && engineNode !== "") return "pi-extension";
+  return "standalone";
+}