@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

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

@@ -13,9 +13,16 @@
 //   T3.18 (NFR): dispose 兜底覆盖（delegate 后子进程进 spawnedChildren）
 //   T3.19 (NFR): AgentCallOpts→ExecuteOptions 映射保真
 
-import { describe, expect, it, vi } from "vitest";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 import type { AgentCallOpts, AgentResult } from "../../orchestration/models/types.ts";
+import { ModelConfigService, setModelConfigService } from "../model-config-service.ts";
+import type { ModelRegistryLike } from "../model-resolver.ts";
+import { replayJournal } from "../engine/common/event-journal.ts";
 import type { SubprocessAgentRunnerDeps } from "../subprocess-agent-runner.ts";
 import { SubprocessAgentRunner } from "../subprocess-agent-runner.ts";
 
@@ -182,6 +189,97 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
     });
   });
 
+  // ────────────────────────────────────────────────
+  // [U1 D2] RunContext.modelRef 接入：ctxModel 继承路径孪生守卫
+  // ────────────────────────────────────────────────
+  describe("U1 ctxModel twin guard (RunContext.modelRef 接入)", () => {
+    const prevDataDir = process.env["XYZ_AGENT_DATA_DIR"];
+    let tmpRoot = "";
+
+    /** 装配含指定快照的 ModelConfigService 单例（initModel 注入 registry）。 */
+    function installModelService(registry: ModelRegistryLike): void {
+      tmpRoot = mkdtempSync(join(tmpdir(), "sar-model-ref-"));
+      process.env["XYZ_AGENT_DATA_DIR"] = join(tmpRoot, "engine-data");
+      const svc = new ModelConfigService({ agentDir: join(tmpRoot, "agent"), cwd: tmpRoot });
+      svc.initModel({ modelRegistry: registry, sessionId: "sar-guard" });
+      setModelConfigService(svc);
+    }
+
+    afterEach(() => {
+      // 单例 slot 无 reset API，重装一个空注册服务隔离后续用例（同文件后续
+      // describe 不消费 ctxModel 守卫，getGlobalConfig 对空目录返回默认值）
+      if (tmpRoot) {
+        const svc = new ModelConfigService({ agentDir: join(tmpRoot, "agent"), cwd: tmpRoot });
+        svc.initModel({ modelRegistry: { getAvailable: () => [], find: () => undefined, hasConfiguredAuth: () => false }, sessionId: "cleanup" });
+        setModelConfigService(svc);
+        rmSync(tmpRoot, { recursive: true, force: true });
+        tmpRoot = "";
+      }
+      if (prevDataDir === undefined) delete process.env["XYZ_AGENT_DATA_DIR"];
+      else process.env["XYZ_AGENT_DATA_DIR"] = prevDataDir;
+    });
+
+    it("P-A2 拒单路径：ctxModel 命中但 registry 含孪生 → run 返回 error（ambiguous），executeAndAwait 未被调", async () => {
+      const models = [
+        { id: "GLM-5.3-Flash", name: "flash", provider: "zai-coding-cn", reasoning: false },
+        { id: "glm-5.3-flash", name: "flash lower", provider: "zai-coding-cn", reasoning: false },
+      ];
+      installModelService({
+        getAvailable: () => models,
+        find: (p, id) => models.find((m) => m.provider === p && m.id === id),
+        hasConfiguredAuth: () => true,
+      });
+      const mockService = createMockService();
+      const sar = new SubprocessAgentRunner({
+        subagentService: mockService as unknown as SubprocessAgentRunnerDeps["subagentService"],
+        ctxModel: { id: "GLM-5.3-Flash", name: "flash", provider: "zai-coding-cn", reasoning: false },
+      });
+
+      const result = await sar.run(makeBaseOpts(), new AbortController().signal);
+
+      expect(result.error).toMatch(/ambiguous case variants/);
+      expect(result.content).toBe("");
+      // 守卫在 engine.run 之前：不产生任何 record/spawn（委托零发生）
+      expect(mockService.executeAndAwait).not.toHaveBeenCalled();
+    });
+
+    it("P-A2 放行路径：无孪生 registry 下同 ctxModel 正常委托（守卫零误伤）", async () => {
+      const models = [
+        { id: "GLM-5.3-Flash", name: "flash", provider: "zai-coding-cn", reasoning: false },
+      ];
+      installModelService({
+        getAvailable: () => models,
+        find: (p, id) => models.find((m) => m.provider === p && m.id === id),
+        hasConfiguredAuth: () => true,
+      });
+      const mockService = createMockService(
+        vi.fn().mockResolvedValue(makeMockResult({ content: "ok" })),
+      );
+      const sar = new SubprocessAgentRunner({
+        subagentService: mockService as unknown as SubprocessAgentRunnerDeps["subagentService"],
+        ctxModel: { id: "GLM-5.3-Flash", name: "flash", provider: "zai-coding-cn", reasoning: false },
+      });
+
+      const result = await sar.run(makeBaseOpts(), new AbortController().signal);
+
+      expect(result.error).toBeUndefined();
+      expect(result.content).toBe("ok");
+      expect(mockService.executeAndAwait).toHaveBeenCalledTimes(1);
+    });
+
+    it("ctxModel 未指定时守卫跳过（无单例也不阻断）", async () => {
+      const mockService = createMockService(
+        vi.fn().mockResolvedValue(makeMockResult({ content: "ok" })),
+      );
+      const sar = new SubprocessAgentRunner({
+        subagentService: mockService as unknown as SubprocessAgentRunnerDeps["subagentService"],
+      });
+      const result = await sar.run(makeBaseOpts(), new AbortController().signal);
+      expect(result.content).toBe("ok");
+      expect(mockService.executeAndAwait).toHaveBeenCalledTimes(1);
+    });
+  });
+
   // ────────────────────────────────────────────────
   // H1: SAR ctxModel 刷新（model_select 后不再 stale）
   // ────────────────────────────────────────────────
@@ -284,12 +382,12 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
       });
     });
 
-    it("无 workflow onEvent → 不传 bridgedOnEvent", async () => {
-      let bridgedOnEvent: ((e: Record<string, unknown>) => void) | undefined;
+    it("无 workflow onEvent → 引擎仍收到包装 onEvent（P2 journal 通道恒开）", async () => {
+      let engineOnEvent: ((e: Record<string, unknown>) => void) | undefined;
       const mockService = createMockService(
         vi.fn().mockImplementation(
           (_opts: Record<string, unknown>, _signal?: AbortSignal, onEvent?: (e: Record<string, unknown>) => void) => {
-            bridgedOnEvent = onEvent;
+            engineOnEvent = onEvent;
             return Promise.resolve(makeMockResult());
           },
         ),
@@ -299,8 +397,51 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
 
       await sar.run(makeBaseOpts(), new AbortController().signal);
 
-      // 不传 workflow onEvent → bridgedOnEvent 应为 undefined
-      expect(bridgedOnEvent).toBeUndefined();
+      // P2 接线（设计 D6 第②级）：SAR 包装 onEvent 写 journal 后转发——原 onEvent
+      // 未传时也恒传包装版（全引擎免费获得 journal；P1「undefined 透传」细节已被
+      // 有意变更，本用例锁定新语义：引擎侧 onEvent 通道恒开）
+      expect(typeof engineOnEvent).toBe("function");
+      // 包装版不向外抛（journal append 是同步入队）
+      expect(() => engineOnEvent?.({ type: "turn_end" })).not.toThrow();
+    });
+
+    it("P2 journal 接线：run 期间事件落盘 journal-<taskId>.jsonl（中立格式，可重放）", async () => {
+      vi.useFakeTimers({ toFake: [] }); // 真实 timers：journal 写盘走真实 fs
+      const dataDir = mkdtempSync(join(tmpdir(), "sar-journal-test-"));
+      const prevEnv = process.env.XYZ_AGENT_DATA_DIR;
+      process.env.XYZ_AGENT_DATA_DIR = dataDir;
+      try {
+        const mockService = createMockService(
+          vi.fn().mockImplementation(
+            (_opts: Record<string, unknown>, _signal?: AbortSignal, onEvent?: (e: Record<string, unknown>) => void) => {
+              onEvent?.({ type: "tool_start", toolName: "bash", args: { cmd: "ls" } });
+              onEvent?.({ type: "turn_end" });
+              return Promise.resolve(makeMockResult());
+            },
+          ),
+        );
+        const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+        const sar = new SubprocessAgentRunner(deps);
+
+        const workflowOnEvent = vi.fn();
+        await sar.run(makeBaseOpts(), new AbortController().signal, workflowOnEvent);
+
+        // journal 落在 <dataDir>/engines/pi/shared/journal-<taskId>.jsonl
+        const journalFile = join(dataDir, "engines", "pi", "shared");
+        const files = readdirSync(journalFile).filter((f) => f.startsWith("journal-") && f.endsWith(".jsonl"));
+        expect(files.length).toBe(1);
+        const replayed = replayJournal(join(journalFile, files[0] ?? ""));
+        expect(replayed).toEqual([
+          { type: "tool_start", toolName: "bash", args: { cmd: "ls" } },
+          { type: "turn_end" },
+        ]);
+        // workflow onEvent 照常透传（journal 包装不吞事件）
+        expect(workflowOnEvent).toHaveBeenCalledTimes(2);
+      } finally {
+        if (prevEnv === undefined) delete process.env.XYZ_AGENT_DATA_DIR;
+        else process.env.XYZ_AGENT_DATA_DIR = prevEnv;
+        rmSync(dataDir, { recursive: true, force: true });
+      }
     });
   });
 

package/src/execution/__tests__/timeout-integration.test.ts

@@ -40,6 +40,10 @@ vi.mock("node:child_process", async () => {
     stderr = new PassThrough();
     killed = false;
     killSignal: string | undefined;
+    // [race-F4] SIGKILL 升级判定读 exitCode/signalCode（真 ChildProcess 未退出时均 null），
+    // FakeChild 同形提供才能驱动升级路径测试（undefined === null 为 false 会误判已退出）。
+    exitCode: number | null = null;
+    signalCode: string | null = null;
     kill(sig?: string): boolean {
       this.killed = true;
       this.killSignal = sig;
@@ -97,7 +101,14 @@ import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 
 import { createRecord } from "../execution-record.ts";
-import { type RunOptions, runSpawn, type SessionRunnerContext } from "../session-runner.ts";
+import {
+  computeWatchdogMs,
+  type RunOptions,
+  resolveSpawnWatchdogMs,
+  runSpawn,
+  SPAWN_WATCHDOG_ENV,
+  type SessionRunnerContext,
+} from "../session-runner.ts";
 
 const mockSpawn = vi.mocked(spawn);
 const mockExistsSync = vi.mocked(fs.existsSync);
@@ -244,10 +255,17 @@ describe("timeoutMs / signal abort → child.kill 端到端路径", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     mockExistsSync.mockReturnValue(false);
+    // [F-4 假红源修复] env 隔离：多数用例默认 maxTurns=undefined →
+    // resolveSpawnWatchdogMs 走 env 兑底分支，宿主 export SPAWN_WATCHDOG 即假红
+    //（极端值 3e9 还会在 assertSafeTimerDelay fail-fast 直接炸掉 runSpawn）。
+    // 用例内显式 stubEnv 的值照常叠加生效（inner describe 的 afterEach
+    // unstubAllEnvs 与本处兼容）。
+    vi.stubEnv(SPAWN_WATCHDOG_ENV, "");
   });
 
   afterEach(() => {
     vi.restoreAllMocks();
+    vi.unstubAllEnvs();
   });
 
   // ── 1. watchdog 到期 → child.kill ──
@@ -291,9 +309,209 @@ describe("timeoutMs / signal abort → child.kill 端到端路径", () => {
       // 信号终止（>=128）视为正常完成
       expect(result.success).toBe(true);
     });
+
+    // [race-F4] SIGKILL 升级：watchdog SIGTERM 后子进程无视信号（exitCode/signalCode
+    // 保持 null = 未退出）→ 30s 后升级 SIGKILL。挂住子进程永不回收的兑底防线。
+    it("[race-F4] watchdog SIGTERM 后 30s 未 exit → 升级 SIGKILL", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: hang ignores SIGTERM", makeOpts({ maxTurns: 6 }), makeCtx());
+
+      const child = await waitForSpawnFake();
+
+      // watchdog 到期 → SIGTERM（升级路径入口）
+      await vi.advanceTimersByTimeAsync(30 * 60 * 1000 + 100);
+      expect(child.killSignal).toBe("SIGTERM");
+
+      // 子进程无视 SIGTERM：不 emit exit/close，exitCode/signalCode 保持 null。
+      // 推进升级窗口：非贴边断言（waitForSpawnFake 每步 10ms 推进，升级 timer 挂载
+      // 时刻有 ≤100ms 抖动）——先推 29s（余量 > 抖动）断言未升级，再推 2s 越过窗口。
+      await vi.advanceTimersByTimeAsync(29 * 1000);
+      expect(child.killSignal).toBe("SIGTERM"); // 尚未升级
+      await vi.advanceTimersByTimeAsync(2 * 1000);
+      expect(child.killSignal).toBe("SIGKILL"); // 已升级
+
+      // 收尾：SIGKILL 后子进程退出 → runSpawn resolve（信号终止视为完成）
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.emit("close", 137); // SIGKILL = 128+9
+      const result = await promise;
+      expect(result.success).toBe(true);
+    });
+
+    // [race-F4] 升级 timer 的 exit 自动 clear：SIGTERM 后子进程正常退出（exit 事件到
+    // 达），升级 timer 被清，不误发 SIGKILL（killSignal 停留在 SIGTERM）。
+    it("[race-F4] SIGTERM 后子进程 exit → 升级 timer 被 clear，不误发 SIGKILL", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: dies on SIGTERM", makeOpts({ maxTurns: 6 }), makeCtx());
+
+      const child = await waitForSpawnFake();
+
+      // watchdog 到期 → SIGTERM
+      await vi.advanceTimersByTimeAsync(30 * 60 * 1000 + 100);
+      expect(child.killSignal).toBe("SIGTERM");
+
+      // 子进程响应 SIGTERM 退出：exitCode 143（SIGTERM 终止形态）+ exit + close。
+      // exit 事件触发升级 timer clear（killChildWithEscalation 内 once("exit") 挂钩）。
+      child.exitCode = 143;
+      child.emit("exit", 143);
+      child.stdout.end();
+      child.emit("close", 143);
+      const result = await promise;
+
+      // 越过升级窗口：无 SIGKILL（timer 已被 exit clear），killSignal 停留在 SIGTERM
+      await vi.advanceTimersByTimeAsync(60 * 1000);
+      expect(child.killSignal).toBe("SIGTERM");
+      expect(result.success).toBe(true);
+    });
+  });
+
+  // ── 2. watchdog 默认不挂载 + env 兑底（预算语义对齐 2026-08）──
+  //
+  // 语义：maxTurns 未传 → env 兑底；显式 0/负 → 压过 env 不挂（U5，SP-6 参数 > env，
+  // 旧实现 maxTurns:0 落到 env 兑底，参数显式关不掉 watchdog，已废）；
+  // env XYZ_SUBAGENT_SPAWN_WATCHDOG_MS 设置时按绝对时限兑底挂载（hang 泄漏防线
+  // opt-in）。resolveSpawnWatchdogMs 是挂载判定唯一入口。
+  describe("watchdog 默认不挂载 + env 兑底（预算语义对齐）", () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+      vi.unstubAllEnvs();
+    });
+
+    it("resolveSpawnWatchdogMs：maxTurns 未传/0/负数且 env 未设 → undefined（不挂）", () => {
+      vi.stubEnv(SPAWN_WATCHDOG_ENV, ""); // 空串 = 未设（raw falsy）
+      expect(resolveSpawnWatchdogMs(undefined)).toBeUndefined();
+      expect(resolveSpawnWatchdogMs(null)).toBeUndefined();
+      expect(resolveSpawnWatchdogMs(0)).toBeUndefined();
+      expect(resolveSpawnWatchdogMs(-5)).toBeUndefined();
+    });
+
+    it("resolveSpawnWatchdogMs：env 设置 → 绝对时限；非法值 → undefined；maxTurns 有效优先", () => {
+      vi.stubEnv(SPAWN_WATCHDOG_ENV, "60000");
+      expect(resolveSpawnWatchdogMs(undefined)).toBe(60_000);
+      // [U5] SP-6 参数 > env：显式 0 压过 env 兑底 → 不挂（旧实现落成 60000）
+      expect(resolveSpawnWatchdogMs(0)).toBeUndefined();
+      expect(resolveSpawnWatchdogMs(-5)).toBeUndefined();
+      // maxTurns 有效（>0）→ turns 估算优先于 env 兑底
+      expect(resolveSpawnWatchdogMs(6)).toBe(computeWatchdogMs(6));
+      vi.stubEnv(SPAWN_WATCHDOG_ENV, "abc");
+      expect(resolveSpawnWatchdogMs(undefined)).toBeUndefined();
+      vi.stubEnv(SPAWN_WATCHDOG_ENV, "-1");
+      expect(resolveSpawnWatchdogMs(undefined)).toBeUndefined();
+    });
+
+    // [U1] setTimeout 2^31-1 溢出 fail-fast：溢出 delay 被 Node 置 1ms 立即触发
+    //（watchdog 变「启动即杀」），两路径（env 兑底 / turns 估算）都必须在入口拦截。
+    it("resolveSpawnWatchdogMs：env 值溢出（>2^31-1）→ fail-fast throw（不静默 clamp/不挂）", () => {
+      vi.stubEnv(SPAWN_WATCHDOG_ENV, "3000000000");
+      expect(() => resolveSpawnWatchdogMs(undefined)).toThrowError(/2147483647/);
+      expect(() => resolveSpawnWatchdogMs(undefined)).toThrowError(/Recovery/);
+    });
+
+    it("resolveSpawnWatchdogMs：maxTurns 估算值溢出 → fail-fast throw", () => {
+      vi.stubEnv(SPAWN_WATCHDOG_ENV, "");
+      // maxTurns=1e6 → 估算 5e9 ms > 2^31-1，入口拦截
+      expect(() => resolveSpawnWatchdogMs(1_000_000)).toThrowError(/2147483647/);
+    });
+
+    // [F-R3] maxTurns 垃圾值网格：NaN/""/null/0/负数（含 ±Infinity）。
+    // 旧实现 NaN/"" 绕过 Number.isFinite 且压过 env 兑底成「显式不限」。
+    it("resolveSpawnWatchdogMs：maxTurns NaN → fail-fast throw（压过 env）；\"\"→Number(\"\")=0 显式不限；null/0/负数网格（F-R3）", () => {
+      vi.stubEnv(SPAWN_WATCHDOG_ENV, "60000");
+      // NaN：非有限数 fail-fast（与 timer-delay U1 同语义），不再压过 env 兑底成「显式不限」
+      expect(() => resolveSpawnWatchdogMs(NaN)).toThrowError(/not a finite number/);
+      expect(() => resolveSpawnWatchdogMs(NaN)).toThrowError(/Recovery/);
+      // ±Infinity：同非有限数 fail-fast
+      expect(() => resolveSpawnWatchdogMs(Infinity)).toThrowError(/not a finite number/);
+      // ""：Number("") === 0 → 与显式 0 同路径（显式不限，压过 env，U5 语义不回归）
+      expect(resolveSpawnWatchdogMs("" as unknown as number)).toBeUndefined();
+      // null → 未传语义，env 兑底生效
+      expect(resolveSpawnWatchdogMs(null)).toBe(60_000);
+      // 0 / 负数 → 显式不限，压过 env（既有 U5 网格不回归）
+      expect(resolveSpawnWatchdogMs(0)).toBeUndefined();
+      expect(resolveSpawnWatchdogMs(-5)).toBeUndefined();
+    });
+
+    it("maxTurns 未传 → 推进 56min 不 kill（旧实现 50min 估算会误杀）", async () => {
+      vi.stubEnv(SPAWN_WATCHDOG_ENV, "");
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: no-turns", makeOpts({ maxTurns: undefined }), makeCtx());
+
+      const child = await waitForSpawnFake();
+      expect(child.killed).toBe(false);
+
+      // 旧实现的估算默认（10 turns → 50min）已过，仍不 kill = watchdog 未挂载
+      await vi.advanceTimersByTimeAsync(56 * 60 * 1000);
+      expect(child.killed).toBe(false);
+
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.emit("close", 0);
+      const result = await promise;
+      expect(result.success).toBe(true);
+    });
+
+    it("maxTurns: 0（显式关不掉的旧默认已废）→ 同样不挂 watchdog", async () => {
+      vi.stubEnv(SPAWN_WATCHDOG_ENV, "");
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: zero-turns", makeOpts({ maxTurns: 0 }), makeCtx());
+
+      const child = await waitForSpawnFake();
+      await vi.advanceTimersByTimeAsync(56 * 60 * 1000);
+      expect(child.killed).toBe(false);
+
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.emit("close", 0);
+      const result = await promise;
+      expect(result.success).toBe(true);
+    });
+
+    // [U5] SP-6 参数 > env：显式 maxTurns:0 压过 SPAWN_WATCHDOG_ENV 兑底——
+    // 旧实现落成 env 时限 kill，参数显式关不掉 watchdog。
+    it("maxTurns: 0 + env=60000 → 显式 0 压过 env，61s 不 kill（U5）", async () => {
+      vi.stubEnv(SPAWN_WATCHDOG_ENV, "60000");
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: zero-turns-override", makeOpts({ maxTurns: 0 }), makeCtx());
+
+      const child = await waitForSpawnFake();
+      // 推进越过 env 兑底时限（60s）：若 maxTurns:0 未压过 env，此处已被 kill
+      await vi.advanceTimersByTimeAsync(61 * 1000);
+      expect(child.killed).toBe(false);
+
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.emit("close", 0);
+      const result = await promise;
+      expect(result.success).toBe(true);
+    });
+
+    it("env SPAWN_WATCHDOG_MS=60000 + maxTurns 未传 → 1min 兑底 kill", async () => {
+      vi.stubEnv(SPAWN_WATCHDOG_ENV, "60000");
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: env-watchdog", makeOpts(), makeCtx());
+
+      const child = await waitForSpawnFake();
+      // 非贴边断言：waitForSpawnFake 每步 10ms 推进，watchdog 挂载时刻有 ≤10ms 抖动，
+      // 用 55s / 61s 两个窗口避开 60s 贴边比较
+      await vi.advanceTimersByTimeAsync(55_000);
+      expect(child.killed).toBe(false);
+      await vi.advanceTimersByTimeAsync(6_000);
+      expect(child.killed).toBe(true);
+      expect(child.killSignal).toBe("SIGTERM");
+
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.emit("close", 143);
+      const result = await promise;
+      expect(result.success).toBe(true);
+    });
   });
 
-  // ── 2. watchdog 到期前正常完成 → clearTimeout 生效，不 kill ──
+  // ── 3. watchdog 到期前正常完成 → clearTimeout 生效，不 kill ──
   describe("watchdog 到期前正常完成 → 不 kill", () => {
     beforeEach(() => {
       vi.useFakeTimers();

package/src/execution/__tests__/tool-action.test.ts

@@ -103,7 +103,7 @@ describe("startHandler", () => {
     ).rejects.toThrow(/≤35 chars/);
   });
 
-  it("background 启动 → kind=bg + bgResponse.message 含 detached", async () => {
+  it("background 启动 → kind=bg + bgResponse.message 含 detached + notifyContract 恒值", async () => {
     const svc = makeService({
       execute: vi.fn(async (): Promise<ExecutionHandle> => ({
         mode: "background",
@@ -117,6 +117,50 @@ describe("startHandler", () => {
     if (r.kind !== "bg") return;
     expect(r.subagentId).toBe("bg-1-123");
     expect(r.response.message).toMatch(/detached/);
+    // [U1] 通知投递契约回显位（U2 账本兑现）
+    expect(r.response.notifyContract).toBe("ledger+at-least-once");
+  });
+
+  it("[U1] start 返回值 model 为 registry 全等回显（透传 handle.details.model）", async () => {
+    const svc = makeService({
+      execute: vi.fn(async (): Promise<ExecutionHandle> => ({
+        mode: "background",
+        subagentId: "bg-2-456",
+        sessionFile: undefined,
+        // record.model = resolved（裁决放行条目）拼接的 "provider/id"，保留 registry 大小写
+        details: makeDetails({ status: "running", mode: "background", model: "zai-coding-cn/GLM-5.3-Flash" }),
+      })),
+    });
+    const r = await startHandler(svc, { task: "t", slug: "s" }, undefined);
+    expect(r.model).toBe("zai-coding-cn/GLM-5.3-Flash");
+    // adapter 外层 result 同源回显
+    const toolResult = adapter({ action: "start", domain: r });
+    const result = toolResult.details;
+    if (result.action !== "start") throw new Error("expected start variant");
+    expect(result.model).toBe("zai-coding-cn/GLM-5.3-Flash");
+    // LLM content JSON 同源（与 details 一致）
+    const contentJson = JSON.parse(toolResult.content[0]!.type === "text" ? toolResult.content[0].text : "{}");
+    expect(contentJson.model).toBe("zai-coding-cn/GLM-5.3-Flash");
+    expect(contentJson.bgResponse.notifyContract).toBe("ledger+at-least-once");
+  });
+
+  it("[U1] model 非全等 → 裁决错误向上传播（无 bgResponse 产出，execute 不重试）", async () => {
+    // 裁决发生在 service.execute 内部步骤 1（IDENTITY 解析 → resolveModel），在 record
+    // 创建 / runSpawn 之前——错误直接向上传播为 tool isError。resolveModel 层的拒单
+    // 行为（含 P-A2 双路径）由 model-ref.test.ts + model-resolver.test.ts 锁定；本用例
+    // 锁定 handler 层传播语义：异常穿越 startHandler，不产出任何受理响应。
+    const svc = makeService({
+      execute: vi.fn(async () => {
+        throw new Error(
+          'Model "zai-coding-cn/glm-5.3-flash" (paramOverride) is not a registry entry. ' +
+            "Did you mean one of these?\n  zai-coding-cn/GLM-5.3-Flash",
+        );
+      }),
+    });
+    await expect(
+      startHandler(svc, { task: "t", slug: "s", model: "zai-coding-cn/glm-5.3-flash" }, undefined),
+    ).rejects.toThrow(/is not a registry entry.*Did you mean/s);
+    expect(svc.execute).toHaveBeenCalledTimes(1);
   });
 });
 
@@ -377,6 +421,53 @@ describe("adapter", () => {
     expect(r.details.listResponse).toEqual({ running: 0, items: [] });
   });
 
+  // [U3 C-outcome] 对外 JSON 契约：list items 携带 outcome 且旧字段保留（验收③）。
+  it("[U3] list JSON：items[].outcome 在位（failed 值）且 status/mode/state 旧字段保留", () => {
+    const r = adapter({
+      action: "list",
+      domain: {
+        response: {
+          running: 0,
+          items: [
+            {
+              subagentId: "bg-u3", agent: "w", slug: "s", state: "ended", status: "closed",
+              mode: "background", duration: 1, model: "m", totalTokens: 0,
+              outcome: "failed",
+            },
+          ],
+        },
+      },
+    });
+    const parsed = JSON.parse(r.content[0]!.text) as {
+      listResponse: { items: Array<Record<string, unknown>> };
+    };
+    const item = parsed.listResponse.items[0]!;
+    expect(item.outcome).toBe("failed");
+    // 旧字段保留（向后兼容）
+    expect(item.status).toBe("closed");
+    expect(item.state).toBe("ended");
+    expect(item.mode).toBe("background");
+    // closedReason 退出对外 JSON
+    expect("closedReason" in item).toBe(false);
+  });
+
+  // [U3 C-outcome] start bgResponse：旧字段保留；outcome 为契约完备位，start 时点
+  // record 未终态恒 undefined（JSON.stringify 落键省略），终态成败经 list items 披露。
+  it("[U3] start bgResponse JSON：status/mode/message 旧字段保留，outcome 起点为 undefined", () => {
+    const r = adapter({
+      action: "start",
+      domain: {
+        kind: "bg", subagentId: "bg-u3-2", sessionFile: undefined, slug: "s",
+        response: { status: "running", mode: "background", message: "detached" },
+      },
+    });
+    const parsed = JSON.parse(r.content[0]!.text) as { bgResponse: Record<string, unknown> };
+    expect(parsed.bgResponse.status).toBe("running");
+    expect(parsed.bgResponse.mode).toBe("background");
+    expect(parsed.bgResponse.message).toBe("detached");
+    expect(parsed.bgResponse.outcome).toBeUndefined();
+  });
+
   it("cancel → cancelResponse.cancelled:true 字面量", () => {
     const r = adapter({ action: "cancel", domain: { subagentId: "bg-1", response: { cancelled: true } } });
     expect(r.details.cancelResponse).toEqual({ cancelled: true });

package/src/execution/agent-registry.ts

@@ -20,6 +20,7 @@ import { parseResourceMeta } from "../shared/meta-parser.ts";
 import { lintAgentMeta } from "../orchestration/script-lint.ts";
 import type { AgentMeta } from "../shared/resource-meta.ts";
 import type { AgentConfig } from "./model-resolver.ts";
+import { hasEngine, listEngines, EngineNotFoundError } from "./engine/registry.ts";
 
 const logger = getLogger("subagents");
 
@@ -100,6 +101,14 @@ export function parseAgentWithMeta(
     );
   }
   const defaultBackgroundRaw = extractYamlField(yamlBlock, "defaultBackground");
+  // engine 字段（D9）：结构化优先（IF1），legacy fallback 与 model/tools 同判——
+  // agentMeta 未通过 IF1 时配置不丢
+  const engine = agentMeta?.engine ?? extractYamlField(yamlBlock, "engine");
+  // 解析期校验（D9：未注册 id 前置暴露，不留到运行时神秘失败）。为什么在解析期而非
+  // 路由期：配置错误的根源在 .md 文件，越早报错定位越准（错误含文件路径 + 注册清单）
+  if (engine !== undefined && !hasEngine(engine)) {
+    throw new EngineNotFoundError(engine, listEngines(), filePath);
+  }
 
   return {
     config: {
@@ -107,6 +116,7 @@ export function parseAgentWithMeta(
       systemPrompt: body,
       model: agentMeta?.model ?? modelFallback ?? undefined,
       thinkingLevel: extractYamlField(yamlBlock, "thinkingLevel") ?? undefined,
+      ...(engine !== undefined ? { engine } : {}),
       tools: agentMeta?.tools && agentMeta.tools.length > 0
         ? agentMeta.tools
         : (toolsFallback && toolsFallback.length > 0 ? toolsFallback : undefined),
@@ -142,7 +152,13 @@ export class AgentRegistry {
    * - ~/ 前缀展开；相对路径/非 .md 引用返回 undefined（引用唯一形态 = 绝对路径）
    * - 文件不可读/不存在 → 驱逐缓存 + 返回 undefined（调用方给错误指引）
    * - mtime 未变复用 config 缓存；cache-miss 时 W4 lint 一次
+   *
+   * require 语义：require:true 时上述两类失败改为 throw（错误文案含
+   * <available_subagents> 恢复指引），供「用户显式点名 agent」的调用点使用——
+   * 显式 ref 失败是配置错误，必须显式报错而非静默降级（三通道对称审查）。
    */
+  loadByPath(ref: string, require: true): AgentConfig;
+  loadByPath(ref: string, require?: boolean): AgentConfig | undefined;
   loadByPath(ref: string, require?: boolean): AgentConfig | undefined {
     const filePath = normalizeRef(ref, AGENT_REF_EXT);
     if (filePath === null) {

package/src/execution/argv-mirror.ts

@@ -86,9 +86,13 @@ export function mirrorMainProcessFlags(argv: readonly string[]): MirrorFlags {
       continue;
     }
     // 空格形式 --extension <path> / -e <path>：值在下一个 token
+    // [MF-7a] flag 判定收窄为 startsWith("--")：守卫原为 !startsWith("-")，把以单个
+    // - 开头的合法路径（如相对路径 -weird-dir/x.md）误判为 flag 跳过——extension 路径
+    // 静默丢失。pi CLI 的多字符长 flag 一律 -- 前缀，单 - 只接单字符短 flag（-e 本身），
+    // 故「-- 开头才算 flag」不误吃真 flag 且放行 - 开头路径。
     if (tok === "--extension" || tok === "-e") {
       const next = flagArgs[i + 1];
-      if (next !== undefined && !next.startsWith("-") && next.length > 0) {
+      if (next !== undefined && !next.startsWith("--") && next.length > 0) {
         extensionPaths.push(next);
         i++; // 跳过值
       }

package/src/execution/concurrency-pool.ts

@@ -63,7 +63,7 @@ export class DefaultConcurrencyPool implements ConcurrencyPool {
       // H2: abort 时 reject 排队条目并从 queue 移除，防止永久挂起
       if (signal) {
         if (signal.aborted) {
-          // S1: abort reject 需带 name="AbortError"，对齐 concurrency-gate.ts 的 AbortError 语义
+          // S1: abort reject 需带 name="AbortError"，对齐包内 AbortError 错误语义约定（消费方按 err.name 判别）
           const err = new Error("acquire aborted");
           err.name = "AbortError";
           reject(err);