@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/execution/__tests__/settled-watchdog.test.ts

@@ -1,16 +1,21 @@
 // src/execution/__tests__/settled-watchdog.test.ts
 //
-// [T2-③ / LC-1] chatMode settled 等待固定硬上限。
+// [T2-③ / D9 两段式] chatMode settled 等待守护：中段无进展检测 + 收尾段固定上界。
 //
-// 设计：docs/design/subagent-core-unbounded-wait-audit.md §7.2 T2-③；10min 默认值
-// 由 P-T2c 探针定案（probe/p-t2c-report.md，正常形态 ≈0ms、余量 4 个数量级）。
+// 设计：docs/design/timeout-zcode-turn-and-settled-watchdog.md §6-D9 / §7（两段式
+// 重锚定，P0-4 核心）；收尾段 600s 定值由 P-T2c 已执行探针定案（probe/p-t2c-report.md，
+// 收尾段 <2ms、compact 30 万 tokens 40.1s、P99×10=401s<600s）；中段 30min 对齐
+// KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS 先例。
 //
-// 覆盖三面：
-//   1. 原语单测（settled-watchdog.ts）：唯一常量值 + arm 到期触发 + disarm 清除 +
-//      重复 arm 以新窗口覆盖旧计时（旧窗不清则提前触发，断言可证伪）。
-//   2. 首轮挂载集成（runSpawn chatMode）：prompt 发出后挂载；advance 到
-//      SETTLED_WATCHDOG_TIMEOUT_MS 触发 kill → close → runSpawn 以错误返回且错误含
-//      恢复指引（S-B 验收判据）。
+// 覆盖五面（对应单元验收 ①-⑤）：
+//   1. 原语单测（settled-watchdog.ts）：两常量值；①中段静默超时按第一段语义触发；
+//      ②agent_end 交棒后切换收尾段；③收尾段 settle 到达 disarm 不误杀；④两段各自
+//      独立计时（中段已过时间不继承——收尾段从 agent_end 起满 600s 才 fire）；
+//      ⑤env XYZ_SUBAGENT_SETTLED_WATCHDOG_MS 覆盖 / ≤0 双段关闭 / 非法回落。
+//   2. 首轮挂载集成（runSpawn chatMode）：prompt 发出后挂中段；静默 30min 触发 kill
+//      → close → runSpawn 以错误返回且错误含段标注 + 恢复指引（S-B 验收判据）；
+//      agent_end 交棒后收尾段 600s 独立计时；正常轮转（agent_end+agent_settled）
+//      不误杀。
 //   3. 清除点：settled 到达（含 resolveRun 同点）/ close 任一发生即清——挂载点消费
 //      同一导出常量（advance 常量值可触发 = 同源断言）。
 //
@@ -69,7 +74,7 @@ vi.mock("../session-pending.ts", () => ({
   listActivePendingFromSessionFile: vi.fn(() => ({ items: [] })),
 }));
 
-vi.mock("../temp-prompt.ts", () => ({
+vi.mock("../engine/engines/pi/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` };
@@ -77,13 +82,22 @@ vi.mock("../temp-prompt.ts", () => ({
   cleanupTempPrompt: vi.fn(async () => {}),
 }));
 
-import { runSpawn } from "../session-runner.ts";
+import { runSpawn } from "../engine/engines/pi/session-runner.ts";
 import {
   _resetSettledWatchdogsForTest,
+  armMidRoundNoProgress,
   armSettledWatchdog,
   disarmSettledWatchdog,
+  getSettledWatchdogPhase,
+  getSettledWatchdogTimeoutMs,
+  handoverMidRoundToSettled,
   hasSettledWatchdog,
+  isSettledWatchdogDisabled,
+  refreshMidRoundNoProgress,
+  SETTLED_MID_ROUND_NO_PROGRESS_MS,
+  SETTLED_WATCHDOG_ENV,
   SETTLED_WATCHDOG_TIMEOUT_MS,
+  type SettledWatchdogFireInfo,
 } from "../settled-watchdog.ts";
 import { _resetLifecycleState } from "../lifecycle-manager.ts";
 import { createRecord } from "../execution-record.ts";
@@ -104,12 +118,12 @@ function sessionHeaderLine(): Record<string, unknown> {
   return { type: "session", id: "sess-sw", timestamp: "2026-09-01T00:00:00.000Z", cwd: "/tmp/test" };
 }
 
-/** 构造 chatMode record（idleTimeoutMs 拉长到 1h，防 idle timer 干扰 10min 窗口断言）。 */
+/** 构造 chatMode record（idleTimeoutMs 拉长到 1h，防 idle timer 干扰两段窗口断言）。 */
 function makeChatModeRecord(id = "sa-chat-sw"): ExecutionRecord {
   const record = createRecord(id, {
     agent: "general-purpose",
     model: "test-model",
-    mode: "sync",
+    mode: "background",
     task: "chat task",
     slug: "chat",
     startedAt: 1_000_000,
@@ -118,7 +132,7 @@ function makeChatModeRecord(id = "sa-chat-sw"): ExecutionRecord {
     depth: 0,
     chatMode: true,
   });
-  record.idleTimeoutMs = 3_600_000;
+  (record as { idleTimeoutMs: number }).idleTimeoutMs = 3_600_000;
   return record;
 }
 
@@ -135,57 +149,234 @@ async function waitForSpawnUnderFakeTimers(baseline: number, maxIters = 50): Pro
   }
 }
 
-describe("[T2-③] settled-watchdog 原语", () => {
+// ============================================================
+// 原语单测（两段式，验收 ①-⑤）
+// ============================================================
+
+describe("[T2-③ / D9] settled-watchdog 两段式原语", () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    vi.unstubAllEnvs();
     _resetSettledWatchdogsForTest();
   });
 
   afterEach(() => {
     _resetSettledWatchdogsForTest();
+    vi.unstubAllEnvs();
     vi.useRealTimers();
   });
 
-  it("唯一常量值 = 10min（P-T2c 定案，双挂载点共享此导出）", () => {
-    expect(SETTLED_WATCHDOG_TIMEOUT_MS).toBe(10 * 60 * 1000);
+  it("两常量值：中段 30min（对齐 keep-alive 先例）+ 收尾段 600s（P-T2c 定案，值不变）", () => {
+    expect(SETTLED_MID_ROUND_NO_PROGRESS_MS).toBe(30 * 60 * 1000);
+    expect(SETTLED_WATCHDOG_TIMEOUT_MS).toBe(600_000);
+    expect(getSettledWatchdogTimeoutMs()).toBe(600_000);
+    expect(isSettledWatchdogDisabled()).toBe(false);
   });
 
-  it("arm 后 advance 到 10min 触发 onTimeout（到期自删记账）；disarm 后不再触发", async () => {
+  it("验收①：agent_end 前静默超时按第一段语义触发（mid-round 回调 + 段信息；收尾回调不触发）", async () => {
     vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
-    const onTimeout = vi.fn();
-    armSettledWatchdog("sa-1", onTimeout);
+    const onMidTimeout = vi.fn();
+    const onSettleTimeout = vi.fn();
+    armMidRoundNoProgress("sa-1", { onMidTimeout, onSettleTimeout });
     expect(hasSettledWatchdog("sa-1")).toBe(true);
+    expect(getSettledWatchdogPhase("sa-1")).toBe("mid-round");
 
-    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS - 1);
-    expect(onTimeout).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS - 1);
+    expect(onMidTimeout).not.toHaveBeenCalled();
     await vi.advanceTimersByTimeAsync(1);
-    expect(onTimeout).toHaveBeenCalledTimes(1);
+    expect(onMidTimeout).toHaveBeenCalledTimes(1);
+    expect(onMidTimeout).toHaveBeenCalledWith({ phase: "mid-round", waitedMs: SETTLED_MID_ROUND_NO_PROGRESS_MS });
+    // 第一段语义：只触发中段回调，收尾回调不参与
+    expect(onSettleTimeout).not.toHaveBeenCalled();
     // 到期回调先自删条目（对齐 armIdleTimer 语义）
     expect(hasSettledWatchdog("sa-1")).toBe(false);
 
     // disarm 已触发/不存在的 record：幂等 no-op
     disarmSettledWatchdog("sa-1");
     disarmSettledWatchdog("never-armed");
-    expect(onTimeout).toHaveBeenCalledTimes(1);
+    expect(onMidTimeout).toHaveBeenCalledTimes(1);
   });
 
-  it("重复 arm 以新窗口覆盖旧计时——旧窗口不清会提前触发（断言可证伪）", async () => {
+  it("验收②：agent_end 交棒后切换到收尾段（phase=settled；收尾段从交棒点独立计时）", async () => {
     vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
-    const onTimeout = vi.fn();
-    armSettledWatchdog("sa-2", onTimeout);
-    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS / 2);
-    // 重挂（新一轮 prompt）：旧窗口必须作废
-    armSettledWatchdog("sa-2", onTimeout);
+    const onMidTimeout = vi.fn();
+    const onSettleTimeout = vi.fn();
+    armMidRoundNoProgress("sa-2", { onMidTimeout, onSettleTimeout });
 
-    // 若旧窗未清：旧 timer 会在重挂后 5min 触发（此处 advance 内）→ 断言失败
+    handoverMidRoundToSettled("sa-2");
+    expect(getSettledWatchdogPhase("sa-2")).toBe("settled");
+    expect(hasSettledWatchdog("sa-2")).toBe(true);
+
+    // 交棒后满收尾段窗长才触发，触发的是收尾回调（段信息 settled + 600s）
     await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS - 1);
-    expect(onTimeout).not.toHaveBeenCalled();
+    expect(onSettleTimeout).not.toHaveBeenCalled();
     await vi.advanceTimersByTimeAsync(1);
-    expect(onTimeout).toHaveBeenCalledTimes(1);
+    expect(onSettleTimeout).toHaveBeenCalledTimes(1);
+    expect(onSettleTimeout).toHaveBeenCalledWith({ phase: "settled", waitedMs: SETTLED_WATCHDOG_TIMEOUT_MS });
+    expect(onMidTimeout).not.toHaveBeenCalled();
+  });
+
+  it("验收③：收尾段内 settle 到达（disarm）则正常解除不误杀", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const onMidTimeout = vi.fn();
+    const onSettleTimeout = vi.fn();
+    armMidRoundNoProgress("sa-3", { onMidTimeout, onSettleTimeout });
+    handoverMidRoundToSettled("sa-3");
+
+    // settled 到达（生产接线：handleSdkEvent / close / 收尾统一 disarm，两段一并清）
+    disarmSettledWatchdog("sa-3");
+    expect(hasSettledWatchdog("sa-3")).toBe(false);
+
+    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS + 60_000);
+    expect(onSettleTimeout).not.toHaveBeenCalled();
+    expect(onMidTimeout).not.toHaveBeenCalled();
+  });
+
+  it("验收④：两段各自独立计时——中段已过时间不继承进收尾段（D9 交棒语义，构造性断言）", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const onMidTimeout = vi.fn();
+    const onSettleTimeout = vi.fn();
+    armMidRoundNoProgress("sa-4", { onMidTimeout, onSettleTimeout });
+
+    // 中段跑了 29min（差 1min 触发）时 agent_end 到达交棒
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS - 60_000);
+    handoverMidRoundToSettled("sa-4");
+
+    // 若收尾段继承中段已过时间，agent_end 后约 10min 即触发；独立计时应满 600s
+    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS - 60_000);
+    expect(onSettleTimeout).not.toHaveBeenCalled();
+    expect(onMidTimeout).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(onSettleTimeout).toHaveBeenCalledTimes(1);
+    expect(onSettleTimeout).toHaveBeenCalledWith({ phase: "settled", waitedMs: SETTLED_WATCHDOG_TIMEOUT_MS });
+  });
+
+  it("中段刷新语义：有效事件行重挂同窗（连续静默才触发）；交棒后刷新 no-op（收尾段不刷新）", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const onMidTimeout = vi.fn();
+    const onSettleTimeout = vi.fn();
+    armMidRoundNoProgress("sa-5", { onMidTimeout, onSettleTimeout });
+
+    // 静默 29min → 事件刷新 → 再 29min 不触发（若未刷新早已触发）
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS - 60_000);
+    refreshMidRoundNoProgress("sa-5");
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS - 60_000);
+    expect(onMidTimeout).not.toHaveBeenCalled();
+    // 刷新后再满 1min 静默触发
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(onMidTimeout).toHaveBeenCalledTimes(1);
+
+    // 收尾段不刷新（D9 被否 (b) 方案的否决理由：刷新让收尾段失去唯一可收敛形态）
+    const onSettleOnly = vi.fn();
+    armSettledWatchdog("sa-5b", onSettleOnly);
+    refreshMidRoundNoProgress("sa-5b");
+    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS);
+    expect(onSettleOnly).toHaveBeenCalledTimes(1);
+  });
+
+  it("handover 幂等：未挂载 / 重复交棒 / 收尾段后再交棒均 no-op（pump 每轮 agent_end 都调）", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    // 未挂载：no-op
+    handoverMidRoundToSettled("sa-6-none");
+    expect(hasSettledWatchdog("sa-6-none")).toBe(false);
+
+    const onMidTimeout = vi.fn();
+    const onSettleTimeout = vi.fn();
+    armMidRoundNoProgress("sa-6", { onMidTimeout, onSettleTimeout });
+    // 重复交棒：第二次 no-op（不会叠加/重置收尾段计时）
+    handoverMidRoundToSettled("sa-6");
+    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS / 2);
+    handoverMidRoundToSettled("sa-6");
+    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS / 2);
+    expect(onSettleTimeout).toHaveBeenCalledTimes(1);
+    expect(onMidTimeout).not.toHaveBeenCalled();
+  });
+
+  it("重复 arm 以新窗口覆盖旧计时（新一轮 prompt：旧中段/残留收尾段一并作废）", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const onMidTimeout = vi.fn();
+    const onSettleTimeout = vi.fn();
+    armMidRoundNoProgress("sa-7", { onMidTimeout, onSettleTimeout });
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS / 2);
+    // 新一轮 prompt 重新 arm：旧窗口必须作废（含异常形态下残留的收尾段）
+    armMidRoundNoProgress("sa-7", { onMidTimeout, onSettleTimeout });
+    expect(getSettledWatchdogPhase("sa-7")).toBe("mid-round");
+
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS - 1);
+    expect(onMidTimeout).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(1);
+    expect(onMidTimeout).toHaveBeenCalledTimes(1);
+  });
+
+  // ── 验收⑤：env XYZ_SUBAGENT_SETTLED_WATCHDOG_MS ──
+
+  it("验收⑤a：env >0 覆盖收尾段定值（生效窗长随 fire 信息回传）", async () => {
+    vi.stubEnv(SETTLED_WATCHDOG_ENV, "12345");
+    _resetSettledWatchdogsForTest(); // 清 env 解析缓存使新 env 生效
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    expect(getSettledWatchdogTimeoutMs()).toBe(12_345);
+    expect(isSettledWatchdogDisabled()).toBe(false);
+
+    const onSettleTimeout = vi.fn();
+    armSettledWatchdog("sa-8", onSettleTimeout);
+    await vi.advanceTimersByTimeAsync(12_345 - 1);
+    expect(onSettleTimeout).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(1);
+    expect(onSettleTimeout).toHaveBeenCalledWith({ phase: "settled", waitedMs: 12_345 });
+
+    // 交棒路径同样消费覆盖值
+    const onSettle2 = vi.fn();
+    armMidRoundNoProgress("sa-8b", { onMidTimeout: vi.fn(), onSettleTimeout: onSettle2 });
+    handoverMidRoundToSettled("sa-8b");
+    await vi.advanceTimersByTimeAsync(12_345);
+    expect(onSettle2).toHaveBeenCalledWith({ phase: "settled", waitedMs: 12_345 });
+  });
+
+  it("验收⑤b：env ≤0 关闭两段（arm no-op + warn 明示三无窗口后果）", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    vi.stubEnv(SETTLED_WATCHDOG_ENV, "0");
+    _resetSettledWatchdogsForTest();
+    expect(isSettledWatchdogDisabled()).toBe(true);
+
+    const onMidTimeout = vi.fn();
+    const onSettleTimeout = vi.fn();
+    armMidRoundNoProgress("sa-9", { onMidTimeout, onSettleTimeout });
+    // 两段都不挂载（关闭语义：回到「三无窗口」，warn 已明示）
+    expect(hasSettledWatchdog("sa-9")).toBe(false);
+    handoverMidRoundToSettled("sa-9");
+    refreshMidRoundNoProgress("sa-9");
+    armSettledWatchdog("sa-9", onSettleTimeout);
+    expect(hasSettledWatchdog("sa-9")).toBe(false);
+
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS + SETTLED_WATCHDOG_TIMEOUT_MS);
+    expect(onMidTimeout).not.toHaveBeenCalled();
+    expect(onSettleTimeout).not.toHaveBeenCalled();
+  });
+
+  it("验收⑤c：env 非法（非数字）回落默认 + warn 留痕（LC-7 教训：非法回落必须可见）", () => {
+    vi.stubEnv(SETTLED_WATCHDOG_ENV, "not-a-number");
+    _resetSettledWatchdogsForTest();
+    expect(getSettledWatchdogTimeoutMs()).toBe(SETTLED_WATCHDOG_TIMEOUT_MS);
+    expect(isSettledWatchdogDisabled()).toBe(false);
+  });
+
+  it("验收⑤d：env 未设/空串 = 默认 600s（规则 19：用户显式指定才生效）", () => {
+    delete process.env[SETTLED_WATCHDOG_ENV];
+    _resetSettledWatchdogsForTest();
+    expect(getSettledWatchdogTimeoutMs()).toBe(600_000);
+
+    vi.stubEnv(SETTLED_WATCHDOG_ENV, "  ");
+    _resetSettledWatchdogsForTest();
+    expect(getSettledWatchdogTimeoutMs()).toBe(600_000);
+    expect(isSettledWatchdogDisabled()).toBe(false);
   });
 });
 
-describe("[T2-③] runSpawn 首轮挂载（chatMode）", () => {
+// ============================================================
+// runSpawn 首轮挂载集成（chatMode）
+// ============================================================
+
+describe("[T2-③ / D9] runSpawn 首轮挂载（chatMode）", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     vi.stubEnv("XYZ_SUBAGENT_SPAWN_WATCHDOG_MS", "");
@@ -202,19 +393,21 @@ describe("[T2-③] runSpawn 首轮挂载（chatMode）", () => {
     _resetSettledWatchdogsForTest();
   });
 
-  it("settled 永不到达：10min 硬上限到期 kill 层主 → runSpawn 以错误返回且含恢复指引", async () => {
+  it("验收①挂载面：agent_end 前静默超 30min（中段语义）→ kill 层主 → runSpawn 错误返回含段标注 + 恢复指引", async () => {
     const record = makeChatModeRecord();
     const baseline = mockSpawn.mock.results.length;
-    const promise = runSpawn(record, "Chat: wedge", makeOpts(), makeCtx());
+    const promise = runSpawn(record, "Chat: mid-round wedge", makeOpts(), makeCtx());
     await waitForSpawnUnderFakeTimers(baseline);
     const child = lastSpawnedChild();
 
-    // 挂载点消费同一导出常量：advance 常量值量级可触发即同源断言。
-    // [余量] fake timers 对 Date mock 有 ms 级舍入（实测 advance(SET-1) 会触发），
-    // 断言边界留 1s 余量——对 10min 上限语义无损，对计时器实现细节稳健。
+    // prompt 发出后挂中段：advance 到中段窗长触发（原 10min 全程窗已不存在——
+    // advance 10min 静默不再误杀，是对 P0-4 的直接回归断言）
     emitStdoutLine(child, sessionHeaderLine());
-    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS - 1_000);
+    await vi.advanceTimersByTimeAsync(10 * 60 * 1000);
+    expect(child.killed).toBe(false);
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS - 10 * 60 * 1000 - 1_000);
     expect(child.killed).toBe(false);
+    // [余量] fake timers 对 Date mock 有 ms 级舍入，断言边界留 1s 余量（对阈值语义无损）
     await vi.advanceTimersByTimeAsync(2_000);
     expect(child.killed).toBe(true);
     expect(child.killSignal).toBe("SIGTERM");
@@ -227,12 +420,44 @@ describe("[T2-③] runSpawn 首轮挂载（chatMode）", () => {
     expect(result.success).toBe(false);
     expect(result.error).toContain("settled watchdog");
     expect(result.error).toContain("agent_settled");
+    expect(result.error).toContain("mid-round no-progress");
     // S-B 验收判据：错误消息含恢复指引
     expect(result.error).toContain("Recovery:");
     expect(result.error).toContain("action:'list'");
   });
 
-  it("settled 到达：硬上限即清（含 resolveRun 同点）——advance 10min 不误杀已正常轮转的层主", async () => {
+  it("验收②挂载面：agent_end 交棒后收尾段 600s 独立计时——中段 30min 不再适用，600s 到期 kill + settled 段文案", async () => {
+    const record = makeChatModeRecord();
+    const baseline = mockSpawn.mock.results.length;
+    const promise = runSpawn(record, "Chat: settle never arrives", makeOpts(), makeCtx());
+    await waitForSpawnUnderFakeTimers(baseline);
+    const child = lastSpawnedChild();
+
+    emitStdoutLine(child, sessionHeaderLine());
+    // agent_end 到达：交棒收尾段（中段静默 30min 判定随之失效）
+    emitStdoutLine(child, { type: "agent_end", messages: [], willRetry: false });
+    await new Promise((r) => setImmediate(r));
+
+    // 收尾段从 agent_end 起独立计时：满 600s 前不触发（600s < 中段 30min——本推进
+    // 段内无论收尾段还是残留中段都不该 fire）
+    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS - 2_000);
+    expect(child.killed).toBe(false);
+    await vi.advanceTimersByTimeAsync(4_000);
+    expect(child.killed).toBe(true);
+    expect(child.killSignal).toBe("SIGTERM");
+
+    child.stdout.end();
+    child.stderr.end();
+    child.emit("close", 143);
+    const result = await promise;
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("settled watchdog");
+    expect(result.error).toContain("settled phase");
+    expect(result.error).toContain("after agent_end");
+    expect(result.error).toContain("Recovery:");
+  });
+
+  it("验收③挂载面：agent_end + agent_settled 正常轮转即清——advance 两段窗长合计不误杀已正常轮转的层主", async () => {
     const record = makeChatModeRecord();
     const baseline = mockSpawn.mock.results.length;
     const promise = runSpawn(record, "Chat: normal", makeOpts(), makeCtx());
@@ -244,10 +469,10 @@ describe("[T2-③] runSpawn 首轮挂载（chatMode）", () => {
     emitStdoutLine(child, { type: "agent_settled" });
     await new Promise((r) => setImmediate(r));
 
-    // 首轮窗口结束（resolveRun 同点清除硬上限）；idle timer 被拉长到 1h 不干扰本窗口
+    // 首轮窗口结束（resolveRun 同点清除两段守护）；idle timer 被拉长到 1h 不干扰
     expect(hasSettledWatchdog(record.id)).toBe(false);
-    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS + 60_000);
-    // settled watchdog 已清：子进程未被本上界 kill（若回归未清，此处 killed=true）
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS + SETTLED_WATCHDOG_TIMEOUT_MS + 60_000);
+    // settled watchdog 已清：子进程未被本守护 kill（若回归未清，此处 killed=true）
     expect(child.killed).toBe(false);
 
     // 收尾
@@ -259,7 +484,7 @@ describe("[T2-③] runSpawn 首轮挂载（chatMode）", () => {
     expect(result.error).toBeUndefined();
   });
 
-  it("挂载面限定 chatMode：非 chatMode 首轮不挂 settled 上界", async () => {
+  it("挂载面限定 chatMode：非 chatMode 首轮不挂 settled 守护（中段/收尾段均无）", async () => {
     const record = makeRecord(); // 非 chatMode
     const baseline = mockSpawn.mock.results.length;
     const promise = runSpawn(record, "Task: not chat", makeOpts(), makeCtx());
@@ -270,9 +495,9 @@ describe("[T2-③] runSpawn 首轮挂载（chatMode）", () => {
     await new Promise((r) => setImmediate(r));
     expect(hasSettledWatchdog(record.id)).toBe(false);
 
-    // 非 chatMode：即使静默超过 10min 也不被 settled 上界 kill（spawn watchdog 同为
+    // 非 chatMode：即使静默超过中段窗长也不被 settled 守护 kill（spawn watchdog 同为
     // 未挂载——裸缺省 + env 清），agent_end 之前的执行期不受 T2-③ 触及
-    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS + 60_000);
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS + 60_000);
     expect(child.killed).toBe(false);
 
     // agent_end（count=0）→ final kill（既有语义）
@@ -287,3 +512,13 @@ describe("[T2-③] runSpawn 首轮挂载（chatMode）", () => {
     expect(result.success).toBe(true);
   });
 });
+
+// fire info 类型形状守卫（挂载点回调签名消费；编译期校验的运行时锚定）
+describe("[T2-③ / D9] SettledWatchdogFireInfo 形状", () => {
+  it("fire 信息的段与窗长字段齐全（挂载点文案分叉的契约面）", () => {
+    const mid: SettledWatchdogFireInfo = { phase: "mid-round", waitedMs: SETTLED_MID_ROUND_NO_PROGRESS_MS };
+    const settled: SettledWatchdogFireInfo = { phase: "settled", waitedMs: SETTLED_WATCHDOG_TIMEOUT_MS };
+    expect(mid.phase).toBe("mid-round");
+    expect(settled.phase).toBe("settled");
+  });
+});

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

@@ -6,20 +6,21 @@ import * as path from "node:path";
 
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
-import { mirrorMainProcessFlags } from "../argv-mirror.ts";
+import { mirrorMainProcessFlags } from "../engine/engines/pi/argv-mirror.ts";
 import { MAX_FORK_DEPTH } from "../session-context-resolver.ts";
-import { buildEnvBlock, buildSpawnArgs } from "../session-runner.ts";
+import { buildEnvBlock, buildSpawnArgs } from "../engine/engines/pi/session-runner.ts";
 
 describe("buildSpawnArgs", () => {
   // [U1 D2] modelRef 为必填（spawn 前置守卫：未经裁决的裸字符串类型层面不可达）。
-  const baseParams = {
+  // 类型直接锚定 buildSpawnArgs 入参（thinkingLevel 是 ThinkingLevel 枚举，非裸 string）
+  const baseParams: Parameters<typeof buildSpawnArgs>[0] = {
     modelRef: { provider: "openai", id: "gpt-4o" },
-    thinkingLevel: undefined as string | undefined,
-    agentTools: undefined as string[] | undefined,
-    appendSystemPromptPath: undefined as string | undefined,
+    thinkingLevel: undefined,
+    agentTools: undefined,
+    appendSystemPromptPath: undefined,
     sessionDir: "/sessions/dir",
-    forkSource: undefined as string | undefined,
-    skillPaths: undefined as string[] | undefined,
+    forkSource: undefined,
+    skillPaths: undefined,
   };
 
   it("基础参数：--mode rpc --session-dir + --model provider/id，不含 -p 也不含 task（task 经 stdin 传）", () => {
@@ -372,7 +373,7 @@ describe("buildEnvBlock", () => {
   });
 
   afterEach(() => {
-    fs.rmSync(tmpGitRepo, { recursive: true, force: true });
+    fs.rmSync(tmpGitRepo, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("注入 cwd（Working directory 行）", async () => {
@@ -429,7 +430,7 @@ describe("buildEnvBlock", () => {
       // 但仍含 working directory（环境块始终输出）
       expect(block).toContain(`Working directory: ${nonGitDir}`);
     } finally {
-      fs.rmSync(nonGitDir, { recursive: true, force: true });
+      fs.rmSync(nonGitDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 

package/src/execution/__tests__/spawn-event-adapter-rpc.test.ts

@@ -2,7 +2,7 @@
 //
 // W1 红灯测试：spawn-event-adapter.ts 协议层重写 — Pi 原生格式 + method 平铺。
 //
-// 测试对象：extensions/universal/subagent-workflow/src/execution/spawn-event-adapter.ts（改造）
+// 测试对象：packages/subagent-core/src/execution/engine/engines/pi/spawn-event-adapter.ts（改造）
 // 契约来源：.fix-plans/00-master-summary.md §二（统一接口契约）+ §一冲突 2/判定顺序
 //
 // 核心改动：
@@ -18,7 +18,7 @@
 
 import { describe, expect, it } from "vitest";
 
-import { parseSpawnLine } from "../spawn-event-adapter.ts";
+import { parseSpawnLine } from "../engine/engines/pi/spawn-event-adapter.ts";
 
 // ── Pi 原生协议样本构造（来源：rpc-types.ts L230-265 真实类型） ──────────
 // 10 种 method，全部 {type:"extension_ui_request", id, method, ...平铺字段}。
@@ -28,6 +28,17 @@ function piLine(methodFields: Record<string, unknown>): string {
   return JSON.stringify({ type: "extension_ui_request", id: "req-001", ...methodFields });
 }
 
+
+/** 判别收窄辅助：string-fallback 变体（method: string）使 !== 收窄失效，
+ *  用 Extract 条件类型（可赋值方向）精确取变体。 */
+function asVariant<M extends string>(
+  req: import("../engine/engines/pi/spawn-event-adapter.ts").ExtensionUiRequest,
+  method: M,
+): Extract<import("../engine/engines/pi/spawn-event-adapter.ts").ExtensionUiRequest, { method: M }> {
+  if (req.method !== method) throw new Error(`request.method 应为 ${method}`);
+  return req as Extract<import("../engine/engines/pi/spawn-event-adapter.ts").ExtensionUiRequest, { method: M }>;
+}
+
 describe("parseSpawnLine — 10 种 method 真实样本分类（Pi 原生格式）", () => {
   describe("dialog 类（select/confirm/input/editor）", () => {
     it("select → kind=extension_ui_request + request.method=select + title/options 平铺", () => {
@@ -37,9 +48,7 @@ describe("parseSpawnLine — 10 种 method 真实样本分类（Pi 原生格式
       expect(result?.kind).toBe("extension_ui_request");
       if (result?.kind !== "extension_ui_request") return;
       expect(result.id).toBe("req-001");
-      expect(result.request.method).toBe("select");
-      expect(result.request.title).toBe("Pick one");
-      expect(result.request.options).toEqual(["a", "b"]);
+      const req = asVariant(result.request, "select");
     });
 
     it("confirm → request.method=confirm + title/message 平铺", () => {
@@ -48,9 +57,7 @@ describe("parseSpawnLine — 10 种 method 真实样本分类（Pi 原生格式
       }));
       expect(result?.kind).toBe("extension_ui_request");
       if (result?.kind !== "extension_ui_request") return;
-      expect(result.request.method).toBe("confirm");
-      expect(result.request.title).toBe("Sure?");
-      expect(result.request.message).toBe("Proceed?");
+      const req = asVariant(result.request, "confirm");
     });
 
     it("input → request.method=input + title + placeholder", () => {
@@ -59,8 +66,7 @@ describe("parseSpawnLine — 10 种 method 真实样本分类（Pi 原生格式
       }));
       expect(result?.kind).toBe("extension_ui_request");
       if (result?.kind !== "extension_ui_request") return;
-      expect(result.request.method).toBe("input");
-      expect(result.request.placeholder).toBe("type here");
+      const req = asVariant(result.request, "input");
     });
 
     it("editor → request.method=editor + title + prefill", () => {
@@ -69,8 +75,7 @@ describe("parseSpawnLine — 10 种 method 真实样本分类（Pi 原生格式
       }));
       expect(result?.kind).toBe("extension_ui_request");
       if (result?.kind !== "extension_ui_request") return;
-      expect(result.request.method).toBe("editor");
-      expect(result.request.prefill).toBe("initial text");
+      const req = asVariant(result.request, "editor");
     });
   });
 
@@ -81,8 +86,7 @@ describe("parseSpawnLine — 10 种 method 真实样本分类（Pi 原生格式
       }));
       expect(result?.kind).toBe("extension_ui_request");
       if (result?.kind !== "extension_ui_request") return;
-      expect(result.request.method).toBe("notify");
-      expect(result.request.message).toBe("hi");
+      const req = asVariant(result.request, "notify");
     });
 
     it("setStatus → request.method=setStatus + statusKey/statusText", () => {
@@ -91,8 +95,8 @@ describe("parseSpawnLine — 10 种 method 真实样本分类（Pi 原生格式
       }));
       expect(result?.kind).toBe("extension_ui_request");
       if (result?.kind !== "extension_ui_request") return;
-      expect(result.request.method).toBe("setStatus");
-      expect(result.request.statusKey).toBe("k");
+      const req = asVariant(result.request, "setStatus");
+      expect(req.statusKey).toBe("k");
     });
 
     it("setWidget → request.method=setWidget + widgetKey/widgetLines/widgetPlacement", () => {
@@ -102,25 +106,24 @@ describe("parseSpawnLine — 10 种 method 真实样本分类（Pi 原生格式
       }));
       expect(result?.kind).toBe("extension_ui_request");
       if (result?.kind !== "extension_ui_request") return;
-      expect(result.request.method).toBe("setWidget");
-      expect(result.request.widgetKey).toBe("w1");
-      expect(result.request.widgetPlacement).toBe("aboveEditor");
+      const req = asVariant(result.request, "setWidget");
+      expect(req.widgetKey).toBe("w1");
+      expect(req.widgetPlacement).toBe("aboveEditor");
     });
 
     it("setTitle → request.method=setTitle + title", () => {
       const result = parseSpawnLine(piLine({ method: "setTitle", title: "My Title" }));
       expect(result?.kind).toBe("extension_ui_request");
       if (result?.kind !== "extension_ui_request") return;
-      expect(result.request.method).toBe("setTitle");
-      expect(result.request.title).toBe("My Title");
+      const req = asVariant(result.request, "setTitle");
+      expect(req.title).toBe("My Title");
     });
 
     it("set_editor_text → request.method=set_editor_text + text", () => {
       const result = parseSpawnLine(piLine({ method: "set_editor_text", text: "body" }));
       expect(result?.kind).toBe("extension_ui_request");
       if (result?.kind !== "extension_ui_request") return;
-      expect(result.request.method).toBe("set_editor_text");
-      expect(result.request.text).toBe("body");
+      const req = asVariant(result.request, "set_editor_text");
     });
   });
 });