@zhushanwen/pi-subagent-workflow 5.0.0 → 5.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -49,7 +49,8 @@
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*",
-    "@zhushanwen/pi-structured-output": "5.0.0"
+    "@zhushanwen/pi-structured-output": "5.0.0",
+    "@zhushanwen/pi-pending-notifications": "0.3.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

package/src/execution/__tests__/run-spawn-edges.test.ts

@@ -48,6 +48,11 @@ vi.mock("../alive-store.ts", () => ({
   writeAliveMarker: vi.fn(),
 }));
 
+// [recursive-orchestration] agent_end 后代判定独立 mock（判定函数本身在 session-pending.test.ts 单独测）。
+vi.mock("../session-pending.ts", () => ({
+  readActivePendingFromSessionFile: vi.fn(() => ({ count: 0 })),
+}));
+
 vi.mock("../temp-prompt.ts", () => ({
   writePromptToTempFile: vi.fn(async (agent: string) => {
     const safeName = agent.replace(/[^\w.-]+/g, "_");
@@ -56,7 +61,8 @@ vi.mock("../temp-prompt.ts", () => ({
   cleanupTempPrompt: vi.fn(async () => {}),
 }));
 
-import { killAllSpawnedChildren, runSpawn, spawnedChildren } from "../session-runner.ts";
+import { killAllSpawnedChildren, runSpawn, spawnedChildren, WAKEUP_GRACE_MS, computeWatchdogMs } from "../session-runner.ts";
+import { readActivePendingFromSessionFile } from "../session-pending.ts";
 import {
   emitStdoutLine,
   type FakeChild,
@@ -366,7 +372,177 @@ describe("runSpawn", () => {
   // 主动 child.kill("SIGTERM") 让子进程退出，触发 close → runSpawn resolve。
   // willRetry=true 时 agent 会重试，不能 kill。
   describe("agent_end 自然完成", () => {
-    it("agent_end（willRetry=false）→ child.kill(SIGTERM) 被调用，close 后 success=true", async () => {
+    // [recursive-orchestration] 条件 kill：agent_end 时读子进程 session 文件算活跃后代
+    // （pending:register − unregister 差集）。有活跃后代 → 保持进程 idle 等 steer 唤醒。
+    const mockPending = vi.mocked(readActivePendingFromSessionFile);
+
+    // [MF-3] recentUnregister 竞态分支的秒级宽限：count=0 + recentUnregister=true → keep alive
+    // 挂 WAKEUP_GRACE_MS（15s）定时器，到期无新 agent_end（未被唤醒）即 kill。
+    // 背景：旧实现挂固定 2h（WAIT_DESCENDANT_TIMEOUT_MS）——层主 closeout 的最终 agent_end
+    // 距最后一次 unregister <60s 必命中此分支，空等 2h 才 kill + 冒牌完成通知级联。
+    it("MF-3: agent_end（count=0 + recentUnregister）→ 15s 宽限到期后 kill", async () => {
+      mockPending.mockReturnValue({ count: 0, recentUnregister: true });
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: wake-grace", makeOpts(), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      // 必须在 emit agent_end 之前启用 fake timers——keep-alive 定时器在 agent_end 处理器里
+      // 新建，新建时若已是 fake 定时器才可被 advance。不 fake setImmediate：stream .write() 的
+      // data flush 靠真实事件循环（微任务/nextTick）交付，用真实 setImmediate 让出事件循环。
+      vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "Date"] });
+      try {
+        emitStdoutLine(child, sessionHeader());
+        emitStdoutLine(child, { type: "agent_end", messages: [], willRetry: false });
+        // 让事件 pump 处理 agent_end（stream flush 是异步的）
+        await new Promise((r) => setImmediate(r));
+        // keep alive：宽限挂起，不 kill
+        expect(child.killed).toBe(false);
+
+        // 宽限未到（14999ms）：仍不 kill
+        await vi.advanceTimersByTimeAsync(WAKEUP_GRACE_MS - 1);
+        expect(child.killed).toBe(false);
+
+        // 第 15000ms 到期：无新 agent_end（未被唤醒）→ kill
+        await vi.advanceTimersByTimeAsync(1);
+        expect(child.killed).toBe(true);
+        expect(child.killSignal).toBe("SIGTERM");
+
+        // 收尾：close 让 runSpawn resolve
+        child.stdout.end();
+        child.stderr.end();
+        child.emit("close", 143);
+
+        const result = await promise;
+        expect(result.success).toBe(true);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    // [MF-3] 唤醒重评估：宽限挂起期间父被 steer 唤醒（续跑产出新一轮）→ 下一次 agent_end
+    // 重新判定；此时后代已完成（count=0，recentUnregister=false）→ 正常 kill，不等宽限到期。
+    it("MF-3: 宽限期内被唤醒 → 下一次 agent_end 重新评估（后代已完成 → kill）", async () => {
+      mockPending
+        .mockReturnValueOnce({ count: 0, recentUnregister: true })
+        .mockReturnValueOnce({ count: 0, recentUnregister: false });
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: wake-then-done", makeOpts(), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "Date"] });
+      try {
+        emitStdoutLine(child, sessionHeader());
+        // 第一次 agent_end：recentUnregister 竞态 → keep alive（宽限挂起）
+        emitStdoutLine(child, { type: "agent_end", messages: [], willRetry: false });
+        await new Promise((r) => setImmediate(r));
+        expect(child.killed).toBe(false);
+
+        // 被唤醒后父续跑产出新一轮 agent_end：后代已 unregister → 立即 kill（不等宽限）
+        emitStdoutLine(child, { type: "agent_end", messages: [], willRetry: false });
+        await new Promise((r) => setImmediate(r));
+        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(true);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    // [MF-4] count>0 分支的动态超时：等待超时 = computeWatchdogMs(maxTurns)，非固定 2h。
+    // maxTurns=20 → 20×5min = 100min 到期 kill。若回归到固定 2h 常量，100min 处不会 kill，
+    // 本用例 advance(computeWatchdogMs − 1) 后仍不 kill、再 +1 才 kill 的断言会失败。
+    it("MF-4: agent_end（count>0）→ 等待超时 = computeWatchdogMs(maxTurns)（动态，非固定 2h）", async () => {
+      const maxTurns = 20;
+      const expected = computeWatchdogMs(maxTurns);
+      mockPending.mockReturnValue({ count: 2 });
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: slow-desc", makeOpts({ maxTurns }), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "Date"] });
+      try {
+        emitStdoutLine(child, sessionHeader());
+        emitStdoutLine(child, { type: "agent_end", messages: [], willRetry: false });
+        await new Promise((r) => setImmediate(r));
+        // keep alive：动态超时挂起，不 kill
+        expect(child.killed).toBe(false);
+
+        // 未到动态超时（100min−1ms）：不 kill
+        await vi.advanceTimersByTimeAsync(expected - 1);
+        expect(child.killed).toBe(false);
+
+        // 动态超时到期：kill。若误用固定 2h，此处不会 kill → 用例失败
+        await vi.advanceTimersByTimeAsync(1);
+        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(true);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    // [S-9] pending.error 分支（sessionFile 不可读 → 保守 keep-alive + re-arm dynamic watchdog）
+    // 集成行为 guard：session-pending 单测覆盖 error 返回值，但 session-runner 的 no-kill +
+    // re-arm 到 computeWatchdogMs(maxTurns) 行为无集成 guard。若 re-arm 误删/误用固定超时，
+    // 保守 keep-alive 会退化成永久挂起或被固定超时误杀。
+    it("S-9: agent_end（count=0 + error）→ 保守不 kill + watchdog re-arm 到动态超时", async () => {
+      const maxTurns = 20;
+      const expected = computeWatchdogMs(maxTurns);
+      mockPending.mockReturnValue({ count: 0, error: "session file unreadable: EACCES" });
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: unreadable", makeOpts({ maxTurns }), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "Date"] });
+      try {
+        emitStdoutLine(child, sessionHeader());
+        emitStdoutLine(child, { type: "agent_end", messages: [], willRetry: false });
+        await new Promise((r) => setImmediate(r));
+        // 保守策略：sessionFile 不可读时不 kill（宁可空等也不误杀有后代的进程）
+        expect(child.killed).toBe(false);
+
+        // watchdog re-arm 到动态超时（computeWatchdogMs(maxTurns)），未到期不 kill
+        await vi.advanceTimersByTimeAsync(expected - 1);
+        expect(child.killed).toBe(false);
+
+        // 动态超时到期：kill。若 error 分支漏了 re-arm（或误用固定超时），此断言失败
+        await vi.advanceTimersByTimeAsync(1);
+        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(true);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("agent_end（willRetry=false，无活跃后代）→ child.kill(SIGTERM) 被调用，close 后 success=true", async () => {
+      mockPending.mockReturnValue({ count: 0 });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: done", makeOpts(), makeCtx());
 
@@ -389,7 +565,38 @@ describe("runSpawn", () => {
       expect(result.success).toBe(true);
     });
 
+    it("agent_end（willRetry=false，有活跃后代）→ 不 kill，进程保持 idle 等 steer 唤醒；后代完成后 kill", async () => {
+      // 第一次 agent_end：有活跃后代（count=1）→ 不 kill
+      mockPending.mockReturnValueOnce({ count: 1 });
+      // 第二次 agent_end：后代已 unregister（count=0）→ kill
+      mockPending.mockReturnValueOnce({ count: 0 });
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: orchestrate", makeOpts(), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      emitStdoutLine(child, sessionHeader());
+      emitStdoutLine(child, { type: "agent_end", messages: [], willRetry: false });
+      // 给事件 pump 一点时间处理 agent_end（判定读 session 文件）
+      await new Promise((r) => setTimeout(r, 20));
+      expect(child.killed).toBe(false);
+
+      // 后代完成（unregister 已写入）后再次 agent_end → 无活跃后代 → kill
+      emitStdoutLine(child, { type: "agent_end", messages: [], willRetry: false });
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 143);
+
+      const result = await promise;
+
+      expect(child.killed).toBe(true);
+      expect(child.killSignal).toBe("SIGTERM");
+      expect(result.success).toBe(true);
+    });
+
     it("agent_end（willRetry=true）→ child.kill 不被调用（agent 会重试，等下一个 agent_end）", async () => {
+      mockPending.mockReturnValue({ count: 0 });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: retry", makeOpts(), makeCtx());
 
@@ -418,6 +625,7 @@ describe("runSpawn", () => {
     });
 
     it("agent_end 后的后续 event 仍被 handleSdkEvent 处理（kill 不阻塞 event pump）", async () => {
+      mockPending.mockReturnValue({ count: 0 });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: flush", makeOpts(), makeCtx());
 

package/src/execution/__tests__/session-pending.test.ts

@@ -0,0 +1,138 @@
+// src/execution/__tests__/session-pending.test.ts
+//
+// readActivePendingFromSessionFile：读 session 文件算活跃后代（pending 差集）。
+// 覆盖：差集、快速路径过滤、文件不存在/坏行/未回填 sessionFile。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { readActivePendingFromSessionFile } from "../session-pending.ts";
+
+function makeTmpSessionFile(lines: string[]): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "session-pending-test-"));
+  const file = path.join(dir, "session.jsonl");
+  fs.writeFileSync(file, lines.join("\n") + "\n");
+  return file;
+}
+
+const mkRegister = (id: string, type: "subagent" | "workflow" = "subagent") =>
+  JSON.stringify({ type: "custom", customType: "pending:register", data: { id, type, name: id } });
+
+const mkUnregister = (id: string, reason = "completed", ts = "2026-08-06T08:00:00.000Z") =>
+  JSON.stringify({ type: "custom", customType: "pending:unregister", data: { id, reason }, timestamp: ts });
+
+const mkMessage = (role: string, text: string) =>
+  JSON.stringify({ type: "message", id: `m-${Date.now()}-${Math.random()}`, message: { role, content: [{ type: "text", text }] } });
+
+describe("readActivePendingFromSessionFile", () => {
+  const tmpFiles: string[] = [];
+
+  afterEach(() => {
+    for (const f of tmpFiles.splice(0)) {
+      try {
+        fs.rmSync(path.dirname(f), { recursive: true, force: true });
+      } catch {
+        // 清理失败不影响断言
+      }
+    }
+  });
+
+  it("无 pending entries → count 0", () => {
+    const file = makeTmpSessionFile([mkMessage("user", "hi"), mkMessage("assistant", "hello")]);
+    tmpFiles.push(file);
+    expect(readActivePendingFromSessionFile(file)).toEqual({ count: 0, recentUnregister: false });
+  });
+
+  it("纯 register → count = 活跃后代数", () => {
+    const file = makeTmpSessionFile([mkRegister("bg-1"), mkRegister("bg-2", "workflow")]);
+    tmpFiles.push(file);
+    expect(readActivePendingFromSessionFile(file)).toEqual({ count: 2, recentUnregister: false });
+  });
+
+  it("register + unregister 同 id → 差集抵消", () => {
+    const file = makeTmpSessionFile([mkRegister("bg-1"), mkUnregister("bg-1")]);
+    tmpFiles.push(file);
+    expect(readActivePendingFromSessionFile(file)).toEqual({ count: 0, recentUnregister: false });
+  });
+
+  it("混合：部分注销 → 只统计仍活跃的（真实 e2e 场景：P 的 agent_end 时 explorer 未注销）", () => {
+    const file = makeTmpSessionFile([
+      mkRegister("bg-1"),
+      mkUnregister("bg-1", "completed"),
+      mkRegister("explorer-1"),
+      mkMessage("assistant", "waiting for explorer..."),
+    ]);
+    tmpFiles.push(file);
+    expect(readActivePendingFromSessionFile(file)).toEqual({ count: 1, recentUnregister: false });
+  });
+
+  it("fork 继承的主 session register 已被 expired unregister 抵消 → 不干扰", () => {
+    // 模拟 P fork 主 session：继承 register（sessionId 不匹配），session_start 重建补 unregister(expired)
+    const file = makeTmpSessionFile([
+      mkRegister("parent-bg"),
+      mkUnregister("parent-bg", "expired"),
+      mkRegister("my-bg"),
+    ]);
+    tmpFiles.push(file);
+    expect(readActivePendingFromSessionFile(file)).toEqual({ count: 1, recentUnregister: false });
+  });
+
+  it("坏行（截断 JSON）跳过，不影响其余判定", () => {
+    const file = makeTmpSessionFile([
+      '{"type":"custom","customType":"pending:register","data":{"id":"bg-1"',
+      mkRegister("bg-2"),
+    ]);
+    tmpFiles.push(file);
+    expect(readActivePendingFromSessionFile(file)).toEqual({ count: 1, recentUnregister: false });
+  });
+
+  it("sessionFile 未回填（undefined）→ error（调用方保守不 kill）", () => {
+    const res = readActivePendingFromSessionFile(undefined);
+    expect(res.count).toBe(0);
+    expect(res.error).toBeDefined();
+  });
+
+  it("文件不存在 → error（调用方保守不 kill）", () => {
+    const res = readActivePendingFromSessionFile("/nonexistent/path/session.jsonl");
+    expect(res.count).toBe(0);
+    expect(res.error).toBeDefined();
+  });
+
+  it("最近 60s 内有 unregister → recentUnregister=true（后代刚完成，唤醒在路上——竞态窗口不 kill）", () => {
+    const file = makeTmpSessionFile([
+      mkRegister("bg-live"),
+      mkUnregister("bg-live", "completed", new Date().toISOString()),
+    ]);
+    tmpFiles.push(file);
+    expect(readActivePendingFromSessionFile(file)).toEqual({ count: 0, recentUnregister: true });
+  });
+
+  it("unregister 在 60s 窗口外 → recentUnregister=false（正常 kill 路径）", () => {
+    const file = makeTmpSessionFile([
+      mkRegister("bg-live"),
+      mkUnregister("bg-live", "completed", "2020-01-01T00:00:00.000Z"),
+    ]);
+    tmpFiles.push(file);
+    expect(readActivePendingFromSessionFile(file)).toEqual({ count: 0, recentUnregister: false });
+  });
+
+  // [S-4] fast-path 按值匹配而非序列化格式。旧行 `line.includes('"customType":"pending:')`
+  // 耦合 pi 的 JSON 序列化空格习惯（冒号后无空格）。若 pi 改序列化（单行内冒号后加空格），
+  // 旧实现全过滤 → count=0 → keep-alive 静默失效 → recursive tree 被杀、steer 丢失。
+  // 本用例构造冒号后带空格的单行 JSON，验证值匹配仍命中 + 解析正确。
+  it("S-4: 序列化冒号后带空格 → 仍正确解析（防 fast-path 格式耦合导致 keep-alive 静默失效）", () => {
+    const file = makeTmpSessionFile([
+      `{ "type": "message", "message": { "role": "user", "content": [] } }`,
+      `{ "type": "custom", "customType": "pending:register", "data": { "id": "bg-1", "type": "subagent", "name": "bg-1" } }`,
+      `{ "type": "custom", "customType": "pending:unregister", "data": { "id": "bg-1", "reason": "completed" }, "timestamp": "2020-01-01T00:00:00.000Z" }`,
+      `{ "type": "custom", "customType": "pending:register", "data": { "id": "bg-2", "type": "subagent", "name": "bg-2" } }`,
+    ]);
+    tmpFiles.push(file);
+    // bg-1 register+unregister 抵消，bg-2 仍活跃 → count=1。
+    // 旧 fast-path（`"customType":"pending:` 冒号无空格）会跳过所有行 → count=0（静默失效）。
+    expect(readActivePendingFromSessionFile(file)).toEqual({ count: 1, recentUnregister: false });
+  });
+});

package/src/execution/session-pending.ts

@@ -0,0 +1,89 @@
+// src/execution/session-pending.ts
+//
+// agent_end 后代判定：读子进程的 session 文件，用 pending-notifications 的
+// countActiveFromEntries（register − unregister 差集）判断该 subagent 是否还有
+// 活跃后代（background subagent / workflow）。
+//
+// 背景（v4 递归编排）：层主 planning-agent 派子 subagent 后结束 turn 等待被唤醒。
+// 若 runSpawn 在 agent_end 无条件 kill，进程被回收、steer 唤醒送不到，递归树断。
+// 判定依据：子进程的 session 文件里 pending:register entry（其进程内 appendEntry
+// 同步写盘，见 pi SessionManager._persist）减去 pending:unregister 的差集。
+// fork 继承的主 session register 残留由 pending-notifications 的 session_start
+// 重建流程补 unregister(expired) 抵消，纯差集不受污染。
+//
+// 纯函数 + fs，独立于 runSpawn，可单测。
+
+import * as fs from "node:fs";
+
+import { countActiveFromEntries } from "@zhushanwen/pi-pending-notifications";
+
+/** 后代刚完成（unregister）后，notify 唤醒父 agent 可能仍在路上（triggerTurn steer
+ *  经进程内 EventBus 发送，与主进程处理 agent_end 行存在毫秒级竞态——explorer 3 秒完成
+ *  时实测 unregister 先于 agent_end 判定写入，导致差集 0 误判完成）。此窗口内的
+ *  agent_end 不 kill，等父被唤醒后的下一次 agent_end 再判。 */
+const RECENT_UNREGISTER_WINDOW_MS = 60_000;
+
+/** 判定结果：count > 0 = 有活跃后代（应保持进程等唤醒）。 */
+export interface ActivePendingResult {
+	count: number;
+	/** 最近窗口内（60s）有 pending:unregister——后代刚完成，唤醒通知可能在路上。 */
+	recentUnregister: boolean;
+	/** 读取/解析失败的原因（undefined = 成功）。调用方对 error 采取保守策略（不 kill）。 */
+	error?: string;
+}
+
+/**
+ * 读 session 文件计算活跃 pending 数。
+ *
+ * 快速路径：行内含 pending 值（`"pending:register"` / `"pending:unregister"`）才解析，
+ * 大文件（fork 继承主 session）只付 includes 扫描跳过大量 message 行的 JSON.parse。
+ * [S-4] 按值匹配而非 `"customType":"pending:` 序列化格式——后者耦合 pi 的 JSON 序列化
+ * 空格习惯（冒号后无空格），pi 改 pretty-print 会导致全过滤 → count=0 → keep-alive
+ * 静默失效 → recursive tree 被杀、steer 丢失。值字符串本身不受序列化空格影响。
+ *
+ * 文件不存在（sessionFile 未回填/首次 assistant 前）→ error（调用方保守不 kill）。
+ * 坏行跳过（append 中途崩溃的截断行）。
+ */
+export function readActivePendingFromSessionFile(
+	sessionFile: string | undefined,
+): ActivePendingResult {
+	if (!sessionFile) {
+		return { count: 0, recentUnregister: false, error: "no sessionFile (handshake not settled)" };
+	}
+	let raw: string;
+	try {
+		raw = fs.readFileSync(sessionFile, "utf-8");
+	} catch (err) {
+		return {
+			count: 0,
+			recentUnregister: false,
+			error: `session file unreadable: ${err instanceof Error ? err.message : String(err)}`,
+		};
+	}
+
+	const entries: unknown[] = [];
+	let latestUnregisterMs = 0;
+	for (const line of raw.split("\n")) {
+		// [S-4] 按值匹配：countActiveFromEntries 只消费 register/unregister 两种 customType，
+		// 故只需检测这两个值字符串；冒号前后空格变化不影响（值始终是连续子串）。
+		if (!line.includes('"pending:register"') && !line.includes('"pending:unregister"')) continue;
+		try {
+			const entry = JSON.parse(line) as { customType?: string; timestamp?: string };
+			entries.push(entry);
+			if (entry.customType === "pending:unregister" && entry.timestamp) {
+				const ts = Date.parse(entry.timestamp);
+				if (Number.isFinite(ts) && ts > latestUnregisterMs) latestUnregisterMs = ts;
+			}
+		} catch {
+			// 截断行/坏行跳过——不影响其余 entry 的差集判定（罕见：append 中途崩溃）
+			console.debug("[session-pending] skipped malformed pending line in", sessionFile);
+		}
+	}
+
+	const active = countActiveFromEntries(entries);
+	return {
+		count: active.count,
+		recentUnregister:
+			latestUnregisterMs > 0 && Date.now() - latestUnregisterMs < RECENT_UNREGISTER_WINDOW_MS,
+	};
+}

package/src/execution/session-runner.ts

@@ -10,6 +10,7 @@ import { type ChildProcess,execFileSync, spawn } from "node:child_process";
 import * as fs from "node:fs";
 
 import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { readActivePendingFromSessionFile } from "./session-pending.ts";
 
 import type { ExtensionMode } from "./host-mode.ts";
 
@@ -92,6 +93,22 @@ const SPAWN_WATCHDOG_FLOOR_MS = 30 * 60 * 1000;
  *  留 1-2 分钟余量。下限与按 turn 计算取 max，避免 maxTurns 过小时 watchdog 紧到误杀。 */
 const WATCHDOG_MS_PER_TURN = 5 * 60 * 1000;
 
+// [recursive-orchestration] agent_end keep-alive 的两类等待超时（不 kill 分支的兑底）。
+// 层主 subagent 空闲等待后代完成（steer 唤醒）期间不产生 turn，原 watchdog 已清；
+// 此后代卡死（永不完成）时此 timer 保证进程最终回收。超时 kill → finalize 视为正常
+// 完成 → 通知父（父查 cw status 发现未 closed 会走 L2/L3 重派，见 planning-agent 模板）。
+// 两类超时分挂不同分支（见 agent_end handler）：
+//   - 有活跃后代（count>0 / error）→ computeWatchdogMs(maxTurns) 动态超时（MF-4，不误杀慢后代）
+//   - 仅 recentUnregister 竞态 → WAKEUP_GRACE_MS 秒级宽限（MF-3，不空等 2h）
+
+/** [MF-3] agent_end keep-alive 的 recentUnregister 竞态宽限（ms）。
+ *  notify steer 唤醒的竞态宽限——15s 内无新 agent_end（未被唤醒）即 kill；
+ *  被唤醒后下一次 agent_end 重新评估。不用长超时：层主 closeout 的最终 agent_end
+ *  必然命中此分支（距最后一次 unregister <60s），挂长超时 = 空等 2h 才回收
+ *  + 冒牌完成通知级联。
+ *  [export] 测试可观测（run-spawn-edges MF-3 用例用 fake timers 断言 15s 后 kill）。 */
+export const WAKEUP_GRACE_MS = 15_000;
+
 /**
  * [M-1] 基于 maxTurns 动态计算 watchdog 超时。
  *
@@ -103,9 +120,13 @@ const WATCHDOG_MS_PER_TURN = 5 * 60 * 1000;
  * - maxTurns=20 → 100 分钟
  * - maxTurns=100 → 500 分钟（8 小时+，覆盖全量重构）
  *
+ * [MF-4] 同时是 agent_end keep-alive 的「有活跃后代」等待超时（不 kill 分支），
+ * 替代旧固定 2h（WAIT_DESCENDANT_TIMEOUT_MS，已删除）——wave 开发 >2h 不被误杀。
+ * [export] 测试可观测（run-spawn-edges MF-4 用例断言 keep-alive 等待超时 = 动态值）。
+ *
  * @param maxTurns 调用方指定的 turn 上限；undefined/null/0 视为默认 10 turns
  */
-function computeWatchdogMs(maxTurns: number | undefined | null): number {
+export function computeWatchdogMs(maxTurns: number | undefined | null): number {
   const effectiveTurns = maxTurns && maxTurns > 0 ? maxTurns : 10;
   return Math.max(SPAWN_WATCHDOG_FLOOR_MS, effectiveTurns * WATCHDOG_MS_PER_TURN);
 }
@@ -710,9 +731,14 @@ export async function runSpawn(
     // 主进程退出时（session_shutdown reason=quit）dispose 会 abort running controller
     // → 本监听器 kill 子进程。无此 unref，watchdog timer 会拖住 event loop 阻止退出。
     const watchdogMs = computeWatchdogMs(opts.maxTurns);
-    const watchdog = setTimeout(() => child.kill("SIGTERM"), watchdogMs);
+    let watchdog = setTimeout(() => child.kill("SIGTERM"), watchdogMs);
     watchdog.unref();
 
+    // [recursive-orchestration] agent_end 有活跃后代时的等待超时（不 kill 分支的兑底）。
+    // 层主 subagent 空闲等待后代完成（steer 唤醒）期间不产生 turn，原 watchdog 已清；
+    // 此后代卡死（永不完成）时此 timer 保证进程最终回收。超时 kill → finalize 视为正常
+    // 完成 → 通知父（父查 cw status 发现未 closed 会走 L2/L3 重派，见 planning-agent 模板）。
+
     // stdout pump：逐行解析 → handleSdkEvent / enqueueUiRequest
     const enqueueUiRequest = createUiRequestQueue(child, ctx);
     // FR-4: get_state RPC response 监听器（id → resolver）。
@@ -796,7 +822,47 @@ export async function runSpawn(
           //（runRpcMode 末尾 return new Promise(() => {}) 长驻等命令），需主动 kill
           // 触发 close → runSpawn resolve。willRetry=true 时 agent 会重试，不能 kill。
           if (isAgentEndEvt(evt)) {
-            if (!evt.willRetry) child.kill("SIGTERM");
+            if (evt.willRetry) {
+              // agent 会重试，不能 kill。
+            } else {
+              // [recursive-orchestration] 条件 kill：读子进程 session 文件算活跃后代
+              // （pending:register − unregister 差集）。有活跃后代（background subagent /
+              // workflow）→ 保持进程 idle，等后代完成时 notifier triggerTurn steer 唤醒；
+              // 无 → 正常完成，kill 触发 close → runSpawn resolve。
+              const pending = readActivePendingFromSessionFile(record.sessionFile);
+              if (pending.count > 0 || pending.error) {
+                if (pending.error) {
+                  logger.warn(
+                    `[session-runner] agent_end: keep alive (sessionFile unreadable, conservative): ${pending.error}`,
+                  );
+                } else {
+                  logger.debug(
+                    `[session-runner] agent_end: keep alive, ${pending.count} active descendant(s) pending`,
+                  );
+                }
+                // 空闲等待期间不消耗 turn：清原 watchdog，换等待后代超时（每次 agent_end 重新计时）。
+                // [MF-4] 动态超时 = computeWatchdogMs(maxTurns)：真实后代在跑，慢任务（wave 开发
+                // 数小时）不能被固定 2h 误杀——2h 到点 kill 会连坐 SubagentService.dispose 的
+                // killAllSpawnedChildren 杀全部子进程，L2 重派丢在途工作。maxTurns 大则超时长。
+                clearTimeout(watchdog);
+                watchdog = setTimeout(() => child.kill("SIGTERM"), computeWatchdogMs(opts.maxTurns));
+                watchdog.unref();
+              } else if (pending.recentUnregister) {
+                // 差集 0 但最近有 unregister：后代刚完成，notify 唤醒可能在路上（竞态窗口），
+                // 保持进程——父被唤醒后的下一次 agent_end 会正常判定。
+                // [MF-3] 秒级宽限：此分支在每层「最终 turn」必命中（closeout 的 agent_end 距
+                // 最后一次 unregister <60s），挂长超时 = 空等 2h 才 kill + 冒牌完成通知级联。
+                // 15s 内无新 agent_end（未被唤醒）即 kill；被唤醒后下一次 agent_end 重新评估。
+                logger.debug(
+                  "[session-runner] agent_end: keep alive, recent descendant completion (wake-up in flight)",
+                );
+                clearTimeout(watchdog);
+                watchdog = setTimeout(() => child.kill("SIGTERM"), WAKEUP_GRACE_MS);
+                watchdog.unref();
+              } else {
+                child.kill("SIGTERM");
+              }
+            }
           }
           if (isSdkEvent(parsed.event)) handleSdkEvent(parsed.event);
         } else if (parsed.kind === "response") {

package/workflows/review-fix-loop.js

@@ -313,7 +313,7 @@ function buildReviewCall(def, round, max, batchIndex, roundDir, scoped) {
     model: MODEL || def.model,
     schema: reviewerSchema,
     description: def.name,
-    timeoutMs: 1_800_000,
+    timeoutMs: 3_600_000, // 1h（只读审查 + retry 退避余量）
     // returnMeta: true — 与 recursive-split 脚本的 executeActionAgent 对齐：失败时 resolve
     // {value, error}，raw.error 可检测（review- 前缀兜底/结构化终止可达）；成功时
     // value = parsedOutput ?? content，parseResult 作用于 raw.value（MF-1）。
@@ -558,7 +558,7 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
       model: MODEL,
       schema: aggregatorSchema,
       description: "aggregate",
-      timeoutMs: 1_800_000,
+      timeoutMs: 3_600_000, // 1h
       returnMeta: true,
     });
 
@@ -788,9 +788,8 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
       // frontmatter model 字段同样生效（之前丢弃了 FIX_DEF.model，只在 review 阶段消费）
       model: MODEL || (FIX_DEF && FIX_DEF.model),
       description: (FIX_DEF && FIX_DEF.name) || "fix",
-      // info #15: 显式 timeoutMs 与 review/aggregator 档位一致（fix 是写操作中最长阶段，
-      // 不依赖引擎默认值——引擎默认值变化不会悄然缩短 fix 预算）
-      timeoutMs: 1_800_000,
+      // fix 不设 timeoutMs = 不限时（execute-options-mapper: undefined/<=0 → 不设超时）。
+      // 带写操作（改项目代码）可能很久（大重构/多文件），不应被墙钟超时打断。
       returnMeta: true,
       ...(FIX_DEF && !FIX_DEF.isCustom ? { agent: FIX_DEF.name } : {}),
     });