@zhushanwen/pi-subagent-workflow 8.3.0 → 8.5.0

package/src/execution/__tests__/relay-env.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  RELAY_ENV_NODE,
+  RELAY_ENV_RECORD_ID,
+  RELAY_ENV_SCRIPT,
+  RELAY_ENV_SESSION_ID,
+  RELAY_ENV_SOCKET,
+  RELAY_EXIT_CODES,
+  RELAY_PROTOCOL_VERSION,
+  isRelayActive,
+} from '../relay-env.js';
+
+describe('relay env SSOT', () => {
+  it('激活判定：三 env 同时非空', () => {
+    expect(isRelayActive({ [RELAY_ENV_SOCKET]: '/x.sock', [RELAY_ENV_NODE]: '/node', [RELAY_ENV_SCRIPT]: '/relay.mjs' })).toBe(true);
+  });
+
+  it('任一缺失即不激活（全有或全无）', () => {
+    const full = {
+      [RELAY_ENV_SOCKET]: '/x.sock',
+      [RELAY_ENV_NODE]: '/node',
+      [RELAY_ENV_SCRIPT]: '/relay.mjs',
+    };
+    expect(isRelayActive({ ...full, [RELAY_ENV_SOCKET]: '' })).toBe(false);
+    expect(isRelayActive({ ...full, [RELAY_ENV_NODE]: undefined })).toBe(false);
+    expect(isRelayActive({})).toBe(false);
+    expect(isRelayActive(process.env)).toBe(false);
+  });
+
+  it('env 名与退出码稳定（relay.mjs 镜像一致性由 conformance relay 断言锁定）', () => {
+    expect(RELAY_ENV_SESSION_ID).toBe('XYZ_SUBAGENT_RELAY_SESSION_ID');
+    expect(RELAY_ENV_RECORD_ID).toBe('XYZ_SUBAGENT_RELAY_RECORD_ID');
+    expect(RELAY_PROTOCOL_VERSION).toBe(1);
+    expect(RELAY_EXIT_CODES).toEqual({
+      VERSION_MISMATCH: 10,
+      SOCKET_UNREACHABLE: 11,
+      SOCKET_CLOSED: 12,
+      MISSING_IDENTITY: 13,
+    });
+  });
+});

package/src/execution/__tests__/startup-config-declaration.test.ts

@@ -0,0 +1,35 @@
+// src/execution/__tests__/startup-config-declaration.test.ts
+//
+// startupConfig 声明守护测试：断言 package.json `xyz-agent.startupConfig` 声明的
+// content 与代码 DEFAULT_CONFIG 常量深相等，防止两侧任一改动未同步（漂移）。
+// 机制：runtime 启动序列统一 ensure（extension-startup-config.ts），声明即首建内容。
+//
+// 运行：cd extensions/universal/subagent-workflow && npx vitest run src/execution/__tests__/startup-config-declaration.test.ts
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_CONFIG } from "../config.ts";
+
+/** package.json `xyz-agent.startupConfig` 声明条目的最小形状（守护断言用）。 */
+interface StartupConfigEntry {
+	path: string;
+	content: unknown;
+}
+
+const pkg = JSON.parse(
+	readFileSync(join(fileURLToPath(import.meta.url), "../../../../package.json"), "utf-8"),
+) as { "xyz-agent"?: { startupConfig?: StartupConfigEntry[] } };
+
+describe("startupConfig 声明守护", () => {
+	it("声明 content 与代码 DEFAULT_CONFIG 深相等", () => {
+		const entry = pkg["xyz-agent"]?.startupConfig?.find(
+			(e: StartupConfigEntry) => e.path === "subagents/config.json",
+		);
+		expect(entry).toBeDefined();
+		expect(entry?.content).toEqual(DEFAULT_CONFIG);
+	});
+});

package/src/execution/__tests__/stream-sink-retirement.test.ts

@@ -0,0 +1,261 @@
+// src/execution/__tests__/stream-sink-retirement.test.ts
+//
+// widget 私货通道退役步骤 2（E 方案 §6.3）测试，两层：
+//   判定层：createBackgroundStream 真实函数（vi.importActual 绕过文件级 mock）——
+//   gui+relay 激活不创建；tui / relay 未激活 / headless 原样创建；sink=null 恒降级。
+//   接线层：SubagentService.execute（background → kickOffBackground 同步段）透传
+//   mode/streamSink 给工厂——mode 传错 = 判定失效，故接线面必须锁定。
+//
+// spawn 层 mock（FakeChild），与 nested-visibility-env-propagation.test.ts 同模式。
+
+import type { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ── mock modules ──
+
+vi.mock("node:child_process", async () => {
+  const { EventEmitter } = await import("node:events");
+  const { PassThrough } = await import("node:stream");
+
+  class FakeChild extends EventEmitter {
+    pid = 12345;
+    stdout = new PassThrough();
+    stdin = new PassThrough();
+    stderr = new PassThrough();
+    killed = false;
+    killSignal: string | undefined;
+    kill(sig?: string): boolean {
+      this.killed = true;
+      this.killSignal = sig;
+      return true;
+    }
+  }
+
+  return {
+    spawn: vi.fn(() => new FakeChild()),
+    execFile: vi.fn(
+      (
+        _cmd: string,
+        _args: readonly string[],
+        _opts: unknown,
+        cb: (err: Error | null, stdout?: string, stderr?: string) => void,
+      ) => cb(new Error("execFile not configured in this test")),
+    ),
+  };
+});
+
+vi.mock("node:fs", async () => {
+  const actual = await import("node:fs");
+  return {
+    default: {
+      ...actual,
+      mkdirSync: vi.fn(),
+      existsSync: vi.fn(() => false),
+      appendFileSync: vi.fn(),
+      writeFileSync: vi.fn(),
+      readdirSync: vi.fn(() => []),
+    },
+    mkdirSync: vi.fn(),
+    existsSync: vi.fn(() => false),
+    appendFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+    readdirSync: vi.fn(() => []),
+    promises: actual.promises,
+  };
+});
+
+// 接线层观测点：工厂调用记录（参数透传断言用）。返回 stub 形状满足消费面
+// （session-runner onDelta / subagent-service dispose）。判定层走 vi.importActual。
+vi.mock("../stream-sink.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../stream-sink.ts")>();
+  return {
+    ...actual,
+    createBackgroundStream: vi.fn((recordId: string) => ({
+      onDelta: () => {},
+      dispose: () => {},
+      recordId,
+    })),
+  };
+});
+
+vi.mock("../alive-store.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../alive-store.ts")>();
+  return {
+    ...actual,
+    writeAliveMarker: vi.fn(),
+    removeAliveMarker: vi.fn(),
+  };
+});
+
+vi.mock("../finalized-marker.ts", () => ({
+  writeFinalized: vi.fn(),
+  readFinalized: vi.fn(() => false),
+}));
+
+vi.mock("../manifest-store.ts", () => {
+  class FakeManifestStore {
+    writeManifest = vi.fn(async () => {});
+    readManifest = vi.fn(async () => null);
+    listAllSync = vi.fn(() => []);
+    recoverTmpFiles = vi.fn(async () => []);
+  }
+  return { ManifestStore: vi.fn(function (_recordsDir: string) { return new FakeManifestStore(); }) };
+});
+
+vi.mock("../temp-prompt.ts", () => ({
+  writePromptToTempFile: vi.fn(async (agent: string) => {
+    const safeName = agent.replace(/[^\w.-]+/g, "_");
+    return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
+  }),
+  cleanupTempPrompt: vi.fn(async () => {}),
+}));
+
+import { spawn } from "node:child_process";
+
+import { ModelConfigService } from "../model-config-service.ts";
+import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
+import { RELAY_ENV_NODE, RELAY_ENV_SCRIPT, RELAY_ENV_SOCKET } from "../relay-env.ts";
+import { SubagentService } from "../subagent-service.ts";
+import { createBackgroundStream } from "../stream-sink.ts";
+import type { ExtensionMode } from "../host-mode.ts";
+
+const mockSpawn = vi.mocked(spawn);
+const mockCreateStream = vi.mocked(createBackgroundStream);
+
+interface FakeChild {
+  pid: number;
+  stdout: PassThrough;
+  emit(event: string, ...args: unknown[]): boolean;
+}
+
+const RELAY_ENV_KEYS = [RELAY_ENV_SOCKET, RELAY_ENV_NODE, RELAY_ENV_SCRIPT] as const;
+
+/** relay 激活三 env 齐备输入（判定矩阵共用）。 */
+const RELAY_ON: Record<string, string> = {
+  [RELAY_ENV_SOCKET]: "/tmp/retire.sock",
+  [RELAY_ENV_NODE]: "/usr/bin/node",
+  [RELAY_ENV_SCRIPT]: "/opt/relay.mjs",
+};
+
+function lastSpawnedChild(): FakeChild {
+  const result = mockSpawn.mock.results.at(-1);
+  if (!result) throw new Error("spawn was not called yet");
+  return result.value as FakeChild;
+}
+
+function makeEmptyRegistry(): ModelRegistryLike {
+  return { getAvailable: () => [], find: () => undefined, hasConfiguredAuth: () => true };
+}
+
+function makePi() {
+  return { sendMessage: vi.fn(), appendEntry: vi.fn(), events: { emit: vi.fn() } };
+}
+
+const ctxModel: ModelInfo = { id: "m", name: "M", provider: "p", reasoning: false };
+
+function setupService(mode: ExtensionMode | undefined, sessionId = "retire-it"): SubagentService {
+  const agentDir = "/tmp/stream-retire-it";
+  const modelService = new ModelConfigService({ agentDir });
+  modelService.initModel({
+    modelRegistry: makeEmptyRegistry(),
+    sessionId,
+    ctxModel,
+  });
+  const service = new SubagentService({
+    cwd: agentDir,
+    modelService,
+    getMainSessionFile: () => "/mock/main-session.jsonl",
+  });
+  service.initSession({
+    pi: makePi(),
+    sessionId,
+    mode,
+    streamSink: { setWidget: vi.fn() },
+  });
+  return service;
+}
+
+/** 等 kickOffBackground 的 detached runAndFinalize 走到 spawn（stream 创建先于此）。 */
+async function waitForSpawnCall(): Promise<void> {
+  const baseline = mockSpawn.mock.calls.length;
+  const deadline = Date.now() + 2000;
+  while (mockSpawn.mock.calls.length <= baseline) {
+    if (Date.now() > deadline) throw new Error("spawn was not called within 2000ms");
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+async function executeBackground(service: SubagentService): Promise<void> {
+  await service.execute({ task: "retire test", ctxModel });
+  await waitForSpawnCall();
+  // 推进 detached runSpawn 收尾（FakeChild close），防句柄悬挂干扰后续用例
+  lastSpawnedChild().emit("close", 0);
+}
+
+// ── 判定层：createBackgroundStream 真实函数（vi.importActual 绕过文件级 mock）──
+
+describe("退役步骤 2 判定层：createBackgroundStream", () => {
+  const sink = { setWidget: vi.fn() };
+
+  it("gui（mode=rpc）+ relay 激活 → 不创建（tee 供数，widget 私货停发）", async () => {
+    const actual = await vi.importActual<typeof import("../stream-sink.ts")>("../stream-sink.ts");
+    expect(actual.createBackgroundStream("rec-1", sink, "rpc", RELAY_ON)).toBeUndefined();
+  });
+
+  it("tui（mode=tui）+ relay 激活 → 原样创建（TUI widget 行是终端用户的实时预览）", async () => {
+    const actual = await vi.importActual<typeof import("../stream-sink.ts")>("../stream-sink.ts");
+    const stream = actual.createBackgroundStream("rec-1", sink, "tui", RELAY_ON);
+    expect(stream).toBeInstanceOf(actual.SubagentStream);
+    stream?.dispose();
+    expect(sink.setWidget).toHaveBeenCalledWith(`subagent-stream-rec-1`, undefined);
+  });
+
+  it("gui + relay 未激活 → 原样创建（现状路径，独立 pi / 无 runtime 环境零回归）", async () => {
+    const actual = await vi.importActual<typeof import("../stream-sink.ts")>("../stream-sink.ts");
+    const stream = actual.createBackgroundStream("rec-1", sink, "rpc", {});
+    expect(stream).toBeInstanceOf(actual.SubagentStream);
+    stream?.dispose();
+  });
+
+  it("headless（mode 未穿透）+ relay 激活 → 原样创建（抑制条件精确等于 gui，不扩大面）", async () => {
+    const actual = await vi.importActual<typeof import("../stream-sink.ts")>("../stream-sink.ts");
+    const stream = actual.createBackgroundStream("rec-1", sink, undefined, RELAY_ON);
+    expect(stream).toBeInstanceOf(actual.SubagentStream);
+    stream?.dispose();
+  });
+
+  it("sink=null 恒不创建（session_start 未注入降级，与退役判定正交）", async () => {
+    const actual = await vi.importActual<typeof import("../stream-sink.ts")>("../stream-sink.ts");
+    expect(actual.createBackgroundStream("rec-1", null, "tui", {})).toBeUndefined();
+    expect(actual.createBackgroundStream("rec-1", null, "rpc", RELAY_ON)).toBeUndefined();
+  });
+});
+
+// ── 接线层：service → 工厂的参数透传（mode 传错 = 判定失效）──
+
+describe("退役步骤 2 接线层：kickOffBackground 透传 mode/sink 给工厂", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    for (const key of RELAY_ENV_KEYS) delete process.env[key];
+  });
+
+  afterEach(() => {
+    for (const key of RELAY_ENV_KEYS) delete process.env[key];
+    vi.restoreAllMocks();
+  });
+
+  it.each<[string, ExtensionMode | undefined]>([
+    ["rpc", "rpc"],
+    ["tui", "tui"],
+    ["undefined（headless）", undefined],
+  ])("mode=%s：工厂收到 initSession 注入的 mode 与 streamSink", async (_label, mode) => {
+    const service = setupService(mode);
+    await executeBackground(service);
+    expect(mockCreateStream).toHaveBeenCalledTimes(1);
+    const [recordId, sinkArg, modeArg] = mockCreateStream.mock.calls[0]!;
+    expect(typeof recordId).toBe("string");
+    expect(sinkArg).toHaveProperty("setWidget");
+    expect(modeArg).toBe(mode);
+  });
+});

package/src/execution/__tests__/subprocess-agent-runner-routing.test.ts

@@ -0,0 +1,310 @@
+// subprocess-agent-runner-routing.test.ts —— P4 SAR 路由集成测试（验收 1/2/3 的
+// runner 级证据面）：三层优先级落到 run、fallback 留痕进 ExecuteOptions（record 投影
+// 的入参面）、守卫/strict 报错入 result.error、journal 池 key 对齐（对齐点③：落盘
+// 路径 = 引擎 onPoolResolved 声明的池 key 派生路径）。
+//
+// fake 注入：pi 侧 mock SubagentService（executeAndAwait 记录入参）；zcode 侧向
+// registry 注册 fake EnginePort（probe 结果可注入）；frontmatter/全局配置经真实
+// ModelConfigService 单例（agentDir 指向临时目录，真实落盘 .md 与 config.json）。
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { AgentCallOpts, AgentResult } from "../../orchestration/models/types.ts";
+import type { RunContext } from "../engine/port.ts";
+import { clearEngines, registerEngine } from "../engine/registry.ts";
+import type { EnginePort, ProbeReport } from "../engine/types.ts";
+import { ModelConfigService, setModelConfigService } from "../model-config-service.ts";
+import { getChildByRecord } from "../session-runner.ts";
+import { SubprocessAgentRunner } from "../subprocess-agent-runner.ts";
+import type { SubagentService } from "../subagent-service.ts";
+import type { ExecuteOptions } from "../types.ts";
+
+// ── fake 引擎（registry 登记，probe/run 可记录；run 模拟 onPoolResolved + 事件 emit）──
+
+interface FakeEngineCalls {
+  probed: number;
+  runs: Array<{ taskSpec: unknown; ctx: RunContext }>;
+}
+
+function makeFakeZcodeEngine(probeOk: boolean): { engine: EnginePort; calls: FakeEngineCalls } {
+  const calls: FakeEngineCalls = { probed: 0, runs: [] };
+  const engine: EnginePort = {
+    id: "zcode",
+    capabilities: () => ({
+      schemaEnforcement: "emulated",
+      steer: "unsupported",
+      conversation: "unsupported",
+      personaInjection: "prompt",
+      eventGranularity: "coarse",
+      sandbox: "none",
+      sessionRead: "outcome-only",
+      resume: "cold",
+      interrupt: "kill-only",
+      permissionMode: "native",
+    }),
+    probe: () => {
+      calls.probed++;
+      const report: ProbeReport = probeOk
+        ? { ok: true, engineVersion: "0.16.5", checks: [{ name: "stub", ok: true }] }
+        : {
+            ok: false,
+            engineVersion: "",
+            checks: [{ name: "binary", ok: false, detail: "missing" }],
+            error: { code: "engine_probe_failed", recovery: "reinstall zcode and retry the probe" },
+          };
+      return Promise.resolve(report);
+    },
+    run: (taskSpec, ctx) => {
+      calls.runs.push({ taskSpec, ctx });
+      // 对齐点③模拟：prepare 期声明池 key → 事件 emit（zcode coarse 形态：终态后合成）
+      ctx.onPoolResolved?.("home-test-provider-m1");
+      ctx.onEvent?.({ type: "message_end", usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0 } });
+      ctx.onEvent?.({ type: "turn_end" });
+      return Promise.resolve({
+        handle: { data: { v: 1, engineId: "zcode", sessionRef: {}, poolKey: "home-test-provider-m1", adapterVersion: "t" } },
+        outcome: { engineId: "zcode", content: "from-zcode" },
+      });
+    },
+    interact: () => Promise.resolve({ ok: false, code: "engine_capability_unsupported", message: "stub" }),
+    read: () => Promise.resolve({ engineId: "zcode", turns: [], source: "outcome-only" }),
+  };
+  return { engine, calls };
+}
+
+// ── mock pi 编排服务（executeAndAwait 入参记录——record 投影的入参面）──
+
+function makeMockPiService() {
+  const executeOpts: ExecuteOptions[] = [];
+  const executeAndAwait = vi.fn(async (opts: ExecuteOptions): Promise<AgentResult> => {
+    executeOpts.push(opts);
+    return { content: "from-pi", durationMs: 1, toolCalls: [] };
+  });
+  const service = { executeAndAwait } as unknown as SubagentService;
+  return { service, executeOpts, executeAndAwait };
+}
+
+// ── 环境 ──
+
+let tmpRoot: string;
+let agentDir: string;
+let prevDataDirEnv: string | undefined;
+
+function writeGlobalConfig(cfg: Record<string, unknown>): void {
+  fs.mkdirSync(path.join(agentDir, "subagents"), { recursive: true });
+  fs.writeFileSync(path.join(agentDir, "subagents", "config.json"), JSON.stringify(cfg));
+}
+
+function writeAgentMd(name: string, frontmatter: string): string {
+  fs.mkdirSync(path.join(agentDir, "agents"), { recursive: true });
+  const p = path.join(agentDir, "agents", `${name}.md`);
+  fs.writeFileSync(p, `---\n${frontmatter}\n---\nbody`);
+  return p;
+}
+
+function makeOpts(overrides?: Partial<AgentCallOpts>): AgentCallOpts {
+  return {
+    prompt: "task",
+    description: "routing-test",
+    ...overrides,
+  };
+}
+
+/** 装配真实 ModelConfigService 单例（agentDir 指临时目录——frontmatter/config.json 真实落盘）。 */
+function installModelService(cfg?: Record<string, unknown>): void {
+  if (cfg !== undefined) writeGlobalConfig(cfg);
+  setModelConfigService(new ModelConfigService({ agentDir, cwd: tmpRoot }));
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "sar-routing-"));
+  agentDir = path.join(tmpRoot, "pi-agent");
+  fs.mkdirSync(agentDir, { recursive: true });
+  // journal 落盘隔离（getEngineDataDir 的权威通道）：tmpRoot 下，不污染真实目录
+  prevDataDirEnv = process.env["XYZ_AGENT_DATA_DIR"];
+  process.env["XYZ_AGENT_DATA_DIR"] = path.join(tmpRoot, "engine-data");
+  clearEngines();
+});
+
+afterEach(() => {
+  if (prevDataDirEnv === undefined) delete process.env["XYZ_AGENT_DATA_DIR"];
+  else process.env["XYZ_AGENT_DATA_DIR"] = prevDataDirEnv;
+  clearEngines();
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("SAR 路由集成（P4 验收 1/2/3）", () => {
+  it("缺省路径：无任何指定 → pi（本地 DI 绑定），ExecuteOptions.engine='pi' 留痕", async () => {
+    installModelService();
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    const result = await sar.run(makeOpts(), new AbortController().signal);
+
+    expect(result.content).toBe("from-pi");
+    expect(pi.executeOpts[0]?.engine).toBe("pi"); // record 投影的入参面（验收 3）
+    expect(pi.executeOpts[0]?.engineFallback).toBeUndefined();
+  });
+
+  it("frontmatter 指定 zcode（probe ok）→ registry 引擎执行；journal 落盘路径 = 引擎池 key（对齐点③）", async () => {
+    const agentRef = writeAgentMd("reviewer", "name: reviewer\ndescription: d\nengine: zcode");
+    installModelService();
+    const { engine, calls } = makeFakeZcodeEngine(true);
+    registerEngine("zcode", () => engine);
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    const result = await sar.run(makeOpts({ agent: agentRef }), new AbortController().signal);
+
+    expect(result.content).toBe("from-zcode");
+    expect(calls.runs).toHaveLength(1);
+    expect(pi.executeAndAwait).not.toHaveBeenCalled();
+    // 对齐点③断言：journal 落在引擎声明的池 key 目录（非 pi 'shared' 占位路径）
+    const poolDir = path.join(tmpRoot, "engine-data", "engines", "zcode", "home-test-provider-m1");
+    const journals = fs.existsSync(poolDir) ? fs.readdirSync(poolDir) : [];
+    expect(journals).toHaveLength(1);
+    expect(journals[0]).toMatch(/^journal-sa-.+\.jsonl$/);
+    const sharedDir = path.join(tmpRoot, "engine-data", "engines", "zcode", "shared");
+    expect(fs.existsSync(sharedDir)).toBe(false); // 占位 poolKey 未产生错位落盘
+  });
+
+  it("调用参数 engine 覆盖 frontmatter（三层优先级落到 run，A7）", async () => {
+    const agentRef = writeAgentMd("reviewer", "name: reviewer\ndescription: d\nengine: zcode");
+    installModelService();
+    const zcode = makeFakeZcodeEngine(true);
+    registerEngine("zcode", () => zcode.engine);
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    await sar.run(makeOpts({ agent: agentRef, engine: "pi" }), new AbortController().signal);
+
+    expect(zcode.calls.runs).toHaveLength(0);
+    expect(pi.executeOpts).toHaveLength(1); // 调用参数显式 pi 胜出
+  });
+
+  it("全局默认引擎（config defaultEngine=zcode）生效", async () => {
+    installModelService({ version: 1, maxConcurrent: 6, defaultEngine: "zcode" });
+    const { engine, calls } = makeFakeZcodeEngine(true);
+    registerEngine("zcode", () => engine);
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    await sar.run(makeOpts(), new AbortController().signal);
+    expect(calls.runs).toHaveLength(1);
+    expect(pi.executeAndAwait).not.toHaveBeenCalled();
+  });
+
+  it("frontmatter zcode probe 失败 → 路由回 pi + engineFallback 进 ExecuteOptions（record 留痕面，A9①）", async () => {
+    const agentRef = writeAgentMd("reviewer", "name: reviewer\ndescription: d\nengine: zcode");
+    installModelService();
+    const zcode = makeFakeZcodeEngine(false);
+    registerEngine("zcode", () => zcode.engine);
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    const result = await sar.run(makeOpts({ agent: agentRef }), new AbortController().signal);
+
+    expect(result.content).toBe("from-pi");
+    expect(pi.executeOpts[0]?.engine).toBe("pi");
+    expect(pi.executeOpts[0]?.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+    expect(zcode.calls.probed).toBe(1);
+  });
+
+  it("调用参数显式 zcode + probe 失败 → 不兜底，result.error 含 engine_probe_failed（守卫 a，A9②）", async () => {
+    installModelService();
+    const zcode = makeFakeZcodeEngine(false);
+    registerEngine("zcode", () => zcode.engine);
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    const result = await sar.run(makeOpts({ engine: "zcode" }), new AbortController().signal);
+
+    expect(result.content).toBe("");
+    expect(result.error).toContain("engine_probe_failed");
+    expect(pi.executeAndAwait).not.toHaveBeenCalled();
+  });
+
+  it("frontmatter zcode + 显式 model + probe 失败 → model_not_available（守卫 c）", async () => {
+    const agentRef = writeAgentMd("reviewer", "name: reviewer\ndescription: d\nengine: zcode");
+    installModelService();
+    const zcode = makeFakeZcodeEngine(false);
+    registerEngine("zcode", () => zcode.engine);
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    const result = await sar.run(
+      makeOpts({ agent: agentRef, model: "builtin:bigmodel-coding-plan/GLM-5.3" }),
+      new AbortController().signal,
+    );
+
+    expect(result.error).toContain("model_not_available");
+    expect(pi.executeAndAwait).not.toHaveBeenCalled();
+  });
+
+  it("strict=true（config engineRouting.strict）→ frontmatter 层 probe 失败直接报错（A5）", async () => {
+    const agentRef = writeAgentMd("reviewer", "name: reviewer\ndescription: d\nengine: zcode");
+    installModelService({ version: 1, maxConcurrent: 6, engineRouting: { strict: true } });
+    const zcode = makeFakeZcodeEngine(false);
+    registerEngine("zcode", () => zcode.engine);
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    const result = await sar.run(makeOpts({ agent: agentRef }), new AbortController().signal);
+
+    expect(result.error).toContain("engine_probe_failed");
+    expect(result.error).toContain("strict");
+    expect(pi.executeAndAwait).not.toHaveBeenCalled();
+  });
+
+  it("调用参数未注册 id → engine_not_found 入 result.error（文案含注册清单）", async () => {
+    installModelService();
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    const result = await sar.run(makeOpts({ engine: "no-such-engine" }), new AbortController().signal);
+
+    expect(result.error).toContain("engine_not_found");
+    expect(result.error).toContain("Registered engines:");
+  });
+
+  it("frontmatter 未注册 id（解析期拦截）→ SAR 转错误结果（不 crash）", async () => {
+    // frontmatter 校验在 agent 解析期（agent-registry 抛 EngineNotFoundError）——经
+    // ModelConfigService.getAgentConfig 到达 SAR 路由装配，SAR catch 转 result.error
+    const agentRef = writeAgentMd("broken", "name: broken\ndescription: d\nengine: ghost-engine");
+    installModelService();
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    const result = await sar.run(makeOpts({ agent: agentRef }), new AbortController().signal);
+
+    expect(result.error).toContain("engine_not_found");
+    expect(pi.executeAndAwait).not.toHaveBeenCalled();
+  });
+
+  it("[D10] RunContext.onChildSpawned 注入：子进程注册进 spawnedChildren，退出后按句移除", async () => {
+    // C-ext-17 路径①回归：SAR 构造的 RunContext 必须提供 onChildSpawned（引擎 spawn
+    // 后回调 → session-runner spawnedChildren 记账 → dispose killAll 收割兜底可见）
+    const agentRef = writeAgentMd("reviewer", "name: reviewer\ndescription: d\nengine: zcode");
+    installModelService();
+    const { engine, calls } = makeFakeZcodeEngine(true);
+    registerEngine("zcode", () => engine);
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    await sar.run(makeOpts({ agent: agentRef }), new AbortController().signal);
+
+    const ctx = calls.runs[0]?.ctx;
+    expect(ctx?.onChildSpawned).toBeTypeOf("function");
+    // 引擎回调（真实引擎在 spawn 成功后同步调）→ 按 taskId（'sa-' 记账 key）注册可见
+    const child = spawn(process.execPath, ["-e", ""]);
+    ctx?.onChildSpawned?.(child);
+    expect(getChildByRecord(ctx.taskId)).toBe(child);
+    // 子进程退出（真实 close 事件）后记账按句移除——不残留死句柄
+    await new Promise<void>((resolve) => child.once("close", () => resolve()));
+    expect(getChildByRecord(ctx.taskId)).toBeUndefined();
+  });
+});