@zhushanwen/pi-subagent-workflow 8.5.0 → 8.6.0

package/src/execution/__tests__/spawn-args.test.ts

@@ -11,8 +11,9 @@ import { MAX_FORK_DEPTH } from "../session-context-resolver.ts";
 import { buildEnvBlock, buildSpawnArgs } from "../session-runner.ts";
 
 describe("buildSpawnArgs", () => {
+  // [U1 D2] modelRef 为必填（spawn 前置守卫：未经裁决的裸字符串类型层面不可达）。
   const baseParams = {
-    model: undefined as string | undefined,
+    modelRef: { provider: "openai", id: "gpt-4o" },
     thinkingLevel: undefined as string | undefined,
     agentTools: undefined as string[] | undefined,
     appendSystemPromptPath: undefined as string | undefined,
@@ -21,9 +22,11 @@ describe("buildSpawnArgs", () => {
     skillPaths: undefined as string[] | undefined,
   };
 
-  it("基础参数：--mode rpc --session-dir，不含 -p 也不含 task（task 经 stdin 传）", () => {
+  it("基础参数：--mode rpc --session-dir + --model provider/id，不含 -p 也不含 task（task 经 stdin 传）", () => {
     const args = buildSpawnArgs(baseParams);
-    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir"]);
+    expect(args).toEqual([
+      "--mode", "rpc", "--session-dir", "/sessions/dir", "--model", "openai/gpt-4o",
+    ]);
   });
 
   it("不含 -p / --print（rpc mode 下 -p 被 resolveAppMode 无视，是死代码）", () => {
@@ -32,28 +35,22 @@ describe("buildSpawnArgs", () => {
     expect(args).not.toContain("--print");
   });
 
-  it("有 model → 追加 --model provider/id", () => {
-    const args = buildSpawnArgs(
-      { ...baseParams, model: "openai/gpt-4o" },
-    );
-    expect(args).toContain("--model");
+  it("modelRef → --model 值恒为 `${provider}/${id}`（全等拼接，不重写输入）", () => {
+    // 含大小写差异的 provider/id 原样拼接（大小写敏感规则：放行即全等回显）
+    const args = buildSpawnArgs({
+      ...baseParams,
+      modelRef: { provider: "zai-coding-cn", id: "GLM-5.3-Flash" },
+    });
     const idx = args.indexOf("--model");
-    expect(args[idx + 1]).toBe("openai/gpt-4o");
+    expect(args[idx + 1]).toBe("zai-coding-cn/GLM-5.3-Flash");
   });
 
-  it("model + thinkingLevel → model 后缀 :level", () => {
+  it("modelRef + thinkingLevel → model 后缀 :level", () => {
     const args = buildSpawnArgs(
-      { ...baseParams, model: "anthropic/claude", thinkingLevel: "high" },
+      { ...baseParams, thinkingLevel: "high" },
     );
     const idx = args.indexOf("--model");
-    expect(args[idx + 1]).toBe("anthropic/claude:high");
-  });
-
-  it("thinkingLevel 无 model → 不追加（thinking 依赖 model 后缀）", () => {
-    const args = buildSpawnArgs(
-      { ...baseParams, model: undefined, thinkingLevel: "high" },
-    );
-    expect(args).not.toContain("--model");
+    expect(args[idx + 1]).toBe("openai/gpt-4o:high");
   });
 
   it("agentTools → --tools 逗号分隔", () => {
@@ -109,7 +106,7 @@ describe("buildSpawnArgs", () => {
   it("全参数组合：所有 flag 存在，不含 -p 也不含 positional task", () => {
     const args = buildSpawnArgs(
       {
-        model: "openai/gpt-4o",
+        ...baseParams,
         thinkingLevel: "low",
         agentTools: ["read"],
         appendSystemPromptPath: "/tmp/p.md",
@@ -179,12 +176,12 @@ describe("buildSpawnArgs", () => {
     expect(args).not.toContain("--extension");
     expect(args).not.toContain("--no-context-files");
     // 仅基础参数
-    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir"]);
+    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir", "--model", "openai/gpt-4o"]);
   });
 
   it("mirrorFlags undefined → 行为等同旧版（TC7）", () => {
     const args = buildSpawnArgs(baseParams);
-    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir"]);
+    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir", "--model", "openai/gpt-4o"]);
     expect(args).not.toContain("--extension");
     expect(args).not.toContain("--no-extensions");
     expect(args).not.toContain("--approve");
@@ -234,14 +231,13 @@ describe("buildSpawnArgs", () => {
   it("sessionFile undefined → 不含 --session（向后兼容）", () => {
     const args = buildSpawnArgs(baseParams);
     expect(args).not.toContain("--session");
-    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir"]);
+    expect(args).toEqual(["--mode", "rpc", "--session-dir", "/sessions/dir", "--model", "openai/gpt-4o"]);
   });
 
-  it("sessionFile + model + thinkingLevel → 三者都进 args（resume 全参数）", () => {
+  it("sessionFile + modelRef + thinkingLevel → 三者都进 args（resume 全参数）", () => {
     const args = buildSpawnArgs({
       ...baseParams,
       sessionFile: "/sessions/sub/resume.jsonl",
-      model: "anthropic/claude",
       thinkingLevel: "high",
     });
     // --session <file>
@@ -251,7 +247,7 @@ describe("buildSpawnArgs", () => {
     // --model provider/id:level（thinkingLevel 作 model 后缀）
     const modelIdx = args.indexOf("--model");
     expect(modelIdx).toBeGreaterThan(-1);
-    expect(args[modelIdx + 1]).toBe("anthropic/claude:high");
+    expect(args[modelIdx + 1]).toBe("openai/gpt-4o:high");
   });
 });
 
@@ -332,6 +328,21 @@ describe("mirrorMainProcessFlags", () => {
     const r = mirrorMainProcessFlags(["bun", "/pi", "-e", "/a", "-e=/b", "-e", "/c"]);
     expect(r.extensionPaths).toEqual(["/a", "/b", "/c"]);
   });
+
+  // [MF-7a] flag 判定收窄为 startsWith("--")：单 - 开头的合法路径不被误判为 flag。
+  it("[MF-7a] - 开头的路径被当值镜像（不误判 flag）", () => {
+    const r = mirrorMainProcessFlags(["bun", "/pi", "--extension", "-weird-dir/ext.js"]);
+    expect(r.extensionPaths).toEqual(["-weird-dir/ext.js"]);
+  });
+
+  // [MF-7a] -- 开头的真 flag 仍正确跳过：--extension 后跟 --flag 时不吃值、不越界。
+  it("[MF-7a] --extension 后跟 -- 开头真 flag → 不吃值", () => {
+    const r = mirrorMainProcessFlags([
+      "bun", "/pi", "--extension", "--approve", "--extension", "/real.js",
+    ]);
+    expect(r.extensionPaths).toEqual(["/real.js"]);
+    expect(r.approve).toBe(true);
+  });
 });
 
 // ============================================================

package/src/execution/__tests__/start-sync-model-guard.test.ts

@@ -0,0 +1,150 @@
+// src/execution/__tests__/start-sync-model-guard.test.ts
+//
+// [U1 验收 3] start 同步期裁决：非全等 model 入参在 start 工具调用同步期 isError——
+// 无 spawn、无子 session、record 不落盘。
+//
+// 用真实 SubagentService（tmpdir + mock pi）走 execute 全链路，断言：
+//   1. execute 在 IDENTITY 解析（resolveModel 裁决）阶段 reject（问句式报错）；
+//   2. buildSpawnArgs 从未被调用（vi.mock spy 包装真实实现）——spawn 前置守卫的结构性证据；
+//   3. node:child_process.spawn 从未被调用——无子进程；
+//   4. pi.appendEntry 从未被调用——record 未创建（emitPendingRegister 未发生）。
+//
+// 放行路径（全等 → 裁决通过）由 model-ref.test.ts / model-resolver.test.ts 锁定，
+// 全链路放行的 spawn 行为由 run-spawn-* 契约测试覆盖。
+
+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";
+
+vi.mock("node:child_process", async () => {
+  const actual = await import("node:child_process");
+  return {
+    ...actual,
+    spawn: vi.fn(() => {
+      throw new Error("spawn must not be called on sync-model rejection");
+    }),
+  };
+});
+
+// buildSpawnArgs 包装为 spy（保留真实实现）——「非全等拒单不触达 spawn 参数组装」的承重断言。
+vi.mock("../session-runner.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../session-runner.ts")>();
+  return { ...actual, buildSpawnArgs: vi.fn(actual.buildSpawnArgs) };
+});
+
+import { ModelConfigService } from "../model-config-service.ts";
+import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
+import { buildSpawnArgs } from "../session-runner.ts";
+import type { PiLike } from "../subagent-service.ts";
+import { SubagentService } from "../subagent-service.ts";
+
+const mockSpawn = vi.mocked(spawn);
+const mockBuildSpawnArgs = vi.mocked(buildSpawnArgs);
+
+// ── 工具 ──
+
+function makeModel(over: Partial<ModelInfo> = {}): ModelInfo {
+  return {
+    id: over.id ?? "GLM-5.3-Flash",
+    name: over.name ?? "GLM 5.3 Flash",
+    provider: over.provider ?? "zai-coding-cn",
+    reasoning: over.reasoning ?? false,
+    ...over,
+  };
+}
+
+/** registry 快照：真实形态（大小写混合 id），无孪生（P-A2 放行快照形态）。 */
+function makeRegistry(models: ModelInfo[]): ModelRegistryLike {
+  return {
+    getAvailable: () => models,
+    find: (provider, modelId) => models.find((m) => m.provider === provider && m.id === modelId),
+    hasConfiguredAuth: () => true,
+  };
+}
+
+function makePi(): PiLike {
+  return {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+  } as unknown as PiLike;
+}
+
+describe("start 同步期裁决（U1 验收 3：非全等 → isError 且无 spawn 无子 session）", () => {
+  let tmpDir: string;
+  let service: SubagentService;
+  let pi: PiLike;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sw-start-guard-"));
+    const modelService = new ModelConfigService({ agentDir: tmpDir, cwd: tmpDir });
+    modelService.initModel({
+      modelRegistry: makeRegistry([makeModel()]),
+      sessionId: "guard-session",
+    });
+    service = new SubagentService({ cwd: tmpDir, modelService });
+    pi = makePi();
+    service.initSession({ pi, sessionId: "guard-session" });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("小写变体入参 → execute 同步 reject（问句式报错），buildSpawnArgs/spawn/appendEntry 均未被调", async () => {
+    await expect(
+      service.execute({
+        task: "probe task",
+        slug: "guard",
+        model: "zai-coding-cn/glm-5.3-flash",
+      }),
+    ).rejects.toThrow(/is not a registry entry.*Did you mean one of these\?/s);
+
+    // spawn 链路零触达：参数组装（buildSpawnArgs）与进程创建（spawn）都未发生
+    expect(mockBuildSpawnArgs).not.toHaveBeenCalled();
+    expect(mockSpawn).not.toHaveBeenCalled();
+    // record 未创建（emitPendingRegister 未发生）→ 无子 session 前置状态
+    expect(pi.appendEntry).not.toHaveBeenCalled();
+  });
+
+  it("错误含 case variant 首位建议 + 继承指引（可直接重发的合法串）", async () => {
+    let msg = "";
+    try {
+      await service.execute({
+        task: "probe task",
+        slug: "guard",
+        model: "zai-coding-cn/glm-5.3-flash",
+      });
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toContain('zai-coding-cn/GLM-5.3-Flash   ← case variant of "glm-5.3-flash"');
+    expect(msg).toMatch(/Or omit the `model` param to inherit the main agent model\./);
+  });
+
+  it("全等入参通过裁决（reject 不发生，放行链路触达 spawn 参数组装）——守卫零误伤对照", async () => {
+    // 放行路径会进入 kickOffBackground（detached）；execute resolve 即视为裁决放行。
+    // spawn 本身由 FakeChild 缺失抛错收口——本断言只关心「越过了同步裁决」：
+    // execute 不 reject，且 buildSpawnArgs 已被调（或即将被调的 record 已创建）。
+    const promise = service.execute({
+      task: "probe task",
+      slug: "guard-exact",
+      model: "zai-coding-cn/GLM-5.3-Flash",
+    });
+    // 放行路径：裁决不抛（execute 最终可能因 mock 环境子进程收尾而 reject，
+    // 但错误不能是模型裁决错误）
+    try {
+      await promise;
+    } catch (e) {
+      expect((e as Error).message).not.toMatch(/is not a registry entry/);
+      expect((e as Error).message).not.toMatch(/ambiguous case variants/);
+    }
+    // 全等放行 → record 已创建（emitPendingRegister 发生）——与拒单路径形成对照
+    expect(pi.appendEntry).toHaveBeenCalled();
+  });
+});

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

@@ -17,9 +17,11 @@ import { mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { describe, expect, it, vi } from "vitest";
+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";
@@ -187,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）
   // ────────────────────────────────────────────────

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();