@zhushanwen/pi-subagent-workflow 8.5.0 → 8.6.0

package/src/execution/__tests__/helpers/spawn-mock.ts

@@ -89,6 +89,10 @@ export class FakeChild extends EventEmitter {
   stdin = new PassThrough();
   killed = false;
   killSignal: string | undefined;
+  // [race-F4] SIGKILL 升级判定读真 ChildProcess 的 exitCode/signalCode（未退出时均为
+  // null）——FakeChild 同形提供，测试可赋值模拟已死进程（如 deliverMessage 写后死检测）。
+  exitCode: number | null = null;
+  signalCode: string | null = null;
   kill(sig?: string): boolean {
     this.killed = true;
     this.killSignal = sig;

package/src/execution/__tests__/index-session-start.test.ts

@@ -18,7 +18,7 @@
 // 但**没有断言 setUiRequestHandler 被调用**——本测试补这个断言，且覆盖 existing 路径
 // （既有测试 fixed getSubagentService() => null，只能走 new 分支）。
 
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 // ── mock modules（在 import 前声明；路径相对 src/execution/__tests/） ──
 //
@@ -191,8 +191,9 @@ import { WorkflowRun } from "../../orchestration/models/workflow-run.ts";
 // ── helpers ──
 
 /** 创建可观察的 mock ExtensionAPI，捕获 session_start / session_shutdown handler。
- *  Proxy 兜底：未显式处理的 pi.xxx 返回 noop，避免抛错。 */
-function createMockPi(): {
+ *  Proxy 兜底：未显式处理的 pi.xxx 返回 noop，避免抛错。
+ *  spies（可选）：U2 通知账本用例注入 appendEntry / sendMessage 观察桩。 */
+function createMockPi(spies?: { appendEntry?: (customType: string, data: unknown) => void; sendMessage?: (message: unknown, options?: unknown) => void }): {
   pi: ExtensionAPI;
   getSessionStartHandler: () => ((event: unknown, ctx: unknown) => Promise<void>) | undefined;
   getSessionShutdownHandler: () => ((event: unknown, ctx: unknown) => Promise<void>) | undefined;
@@ -216,7 +217,8 @@ function createMockPi(): {
         };
       }
       if (prop === "events") return events;
-      if (prop === "appendEntry") return noop;
+      if (prop === "appendEntry") return spies?.appendEntry ?? noop;
+      if (prop === "sendMessage") return spies?.sendMessage ?? noop;
       if (prop === "registerMessageRenderer") return noop;
       return noop;
     },
@@ -228,14 +230,16 @@ function createMockPi(): {
   };
 }
 
-/** 最小 ExtensionContext mock。mode 由参数控制（决定 handler 注入行为）。 */
-function createMockCtx(mode: "tui" | "rpc" | "json" | "print"): Record<string, unknown> {
+/** 最小 ExtensionContext mock。mode 由参数控制（决定 handler 注入行为）。
+ *  entries（可选）：U2 通知账本用例注入 sessionManager.getEntries 返回值
+ *  （模拟重启前落盘的 ledger/ack entry）。 */
+function createMockCtx(mode: "tui" | "rpc" | "json" | "print", entries?: unknown[]): Record<string, unknown> {
   const sessionManager = {
     getSessionId: () => "session-inject-1",
     getSessionFile: () => "/home/user/.pi/agent/sessions/session-inject-1.jsonl",
     getSessionDir: () => "/home/user/.pi/agent/sessions",
     getCwd: () => "/home/user/project",
-    getEntries: () => [],
+    getEntries: () => entries ?? [],
     getBranch: () => [],
     getLeafId: () => null,
     getLeafEntry: () => undefined,
@@ -256,6 +260,7 @@ function createMockCtx(mode: "tui" | "rpc" | "json" | "print"): Record<string, u
     model: undefined,
     sessionManager,
     ui,
+    isIdle: () => true,
   };
 }
 
@@ -591,3 +596,77 @@ describe("W-3: done run 淘汰接线（loadAll 裁剪 + onRunDone 裁剪）", ()
     }
   });
 });
+
+// ============================================================
+// [U2] session_start 通知账本装配 + 重启恢复钩子（设计 D4）
+// ============================================================
+//
+// mock session 文件（ctx.sessionManager.getEntries）含 ledger/ack entry →
+// session_start handler 装配账本并重放差集：未销账号经 pi.sendMessage({triggerTurn:true})
+// 单通道重投；已销账零重发。bind 顺序在 service.initSession 之前（notifier.notify
+// 经模块级绑定消费账本）。
+
+import {
+  _resetNotifyLedgerForTest,
+  NOTIFY_ACK_CUSTOM_TYPE,
+  NOTIFY_CUSTOM_TYPE,
+  NOTIFY_LEDGER_CUSTOM_TYPE,
+} from "../notify-ledger.ts";
+
+describe("session_start 通知账本恢复钩子（U2 B-ledger）", () => {
+  afterEach(() => {
+    _resetNotifyLedgerForTest();
+  });
+
+  it("mock session 含 ledger/ack entry → 未销账号重放（单通道 triggerTurn），已销账零重发", async () => {
+    const appendEntryCalls: Array<{ customType: string; data: unknown }> = [];
+    const sendMessageCalls: Array<{ message: unknown; options: unknown }> = [];
+    const { pi, getSessionStartHandler } = createMockPi({
+      appendEntry: (customType, data) => {
+        appendEntryCalls.push({ customType, data });
+      },
+      sendMessage: (message, options) => {
+        sendMessageCalls.push({ message, options });
+      },
+    });
+    subagentsExtension(pi);
+
+    // 模拟重启前落盘：2 条 ledger entry（s-a 已销账 + s-b 未销账）+ 1 条 ack
+    const entries: unknown[] = [
+      { type: "custom", customType: NOTIFY_LEDGER_CUSTOM_TYPE, data: { v: 1, notifyId: "s-a", content: "ca", record: { notifyId: "s-a" } } },
+      { type: "custom", customType: NOTIFY_LEDGER_CUSTOM_TYPE, data: { v: 1, notifyId: "s-b", content: "cb", record: { notifyId: "s-b" } } },
+      { type: "custom", customType: NOTIFY_ACK_CUSTOM_TYPE, data: { v: 1, notifyId: "s-a" } },
+    ];
+    const handler = getSessionStartHandler();
+    expect(handler).toBeDefined();
+    await handler!({ type: "session_start" }, createMockCtx("rpc", entries));
+
+    // 未销账 s-b 单条重放：sendMessage 恰 1 次，options 恰 {triggerTurn:true}
+    expect(sendMessageCalls).toHaveLength(1);
+    expect(sendMessageCalls[0]!.options).toEqual({ triggerTurn: true });
+    const sent = sendMessageCalls[0]!.message as { customType: string; content: string; details?: { notifyId?: string } };
+    expect(sent.customType).toBe(NOTIFY_CUSTOM_TYPE);
+    expect(sent.content).toBe("cb");
+    expect(sent.details?.notifyId).toBe("s-b");
+    // 已销账 s-a 零重发（不追加新 ledger entry，不重投）
+    expect(appendEntryCalls.filter((c) => c.customType === NOTIFY_LEDGER_CUSTOM_TYPE)).toHaveLength(0);
+  });
+
+  it("全部已销账（差集为空）→ 零重放零发送", async () => {
+    const sendMessageCalls: unknown[] = [];
+    const { pi, getSessionStartHandler } = createMockPi({
+      sendMessage: () => {
+        sendMessageCalls.push({});
+      },
+    });
+    subagentsExtension(pi);
+
+    const entries: unknown[] = [
+      { type: "custom", customType: NOTIFY_LEDGER_CUSTOM_TYPE, data: { v: 1, notifyId: "s-x", content: "cx", record: { notifyId: "s-x" } } },
+      { type: "custom", customType: NOTIFY_ACK_CUSTOM_TYPE, data: { v: 1, notifyId: "s-x" } },
+    ];
+    await getSessionStartHandler()!({ type: "session_start" }, createMockCtx("rpc", entries));
+
+    expect(sendMessageCalls).toHaveLength(0);
+  });
+});

package/src/execution/__tests__/lifecycle-manager.test.ts

@@ -30,11 +30,15 @@ describe("lifecycle-manager — V2 §5.2 模块 1", () => {
   beforeEach(() => {
     vi.useFakeTimers();
     _resetLifecycleState();
+    // [F-4 同源修复] env 隔离：「默认超时」用例依赖 XYZ_SUBAGENT_IDLE_TIMEOUT_MS
+    // 未设基线（getEnvIdleTimeoutMs 会覆盖 DEFAULT），宿主 export 即假红。空串 = 未设。
+    vi.stubEnv("XYZ_SUBAGENT_IDLE_TIMEOUT_MS", "");
   });
 
   afterEach(() => {
     _resetLifecycleState();
     vi.useRealTimers();
+    vi.unstubAllEnvs();
   });
 
   // ============================================================
@@ -92,6 +96,48 @@ describe("lifecycle-manager — V2 §5.2 模块 1", () => {
       vi.advanceTimersByTime(1);
       expect(onTimeout).toHaveBeenCalledTimes(1);
     });
+
+    it("显式禁用值（0/负数）→ 不挂 timer（预算语义对齐：idle GC 可显式关闭；旧实现 0 落成 setTimeout(0) 立即 kill）", () => {
+      const onTimeout = vi.fn();
+      armIdleTimer("sa-disable-0", onTimeout, 0);
+      expect(hasIdleTimer("sa-disable-0")).toBe(false);
+      armIdleTimer("sa-disable-neg", onTimeout, -1);
+      expect(hasIdleTimer("sa-disable-neg")).toBe(false);
+
+      vi.advanceTimersByTime(DEFAULT_IDLE_TIMEOUT_MS * 2);
+      expect(onTimeout).not.toHaveBeenCalled();
+    });
+
+    it("显式禁用值顺带 disarm 已有 armed timer（禁用不形同虚设）", () => {
+      const onTimeout = vi.fn();
+      armIdleTimer("sa-disable-late", onTimeout, 1000);
+      expect(hasIdleTimer("sa-disable-late")).toBe(true);
+      armIdleTimer("sa-disable-late", onTimeout, 0);
+      expect(hasIdleTimer("sa-disable-late")).toBe(false);
+      vi.advanceTimersByTime(2000);
+      expect(onTimeout).not.toHaveBeenCalled();
+    });
+
+    // [U1] setTimeout 2^31-1 溢出 fail-fast：溢出 delay 被 Node 置 1ms 立即触发
+    //（「长空闲保活」变「立即 kill」），arm 入口拦截且错误含上限值与恢复指引。
+    // 显式禁用通道（<=0）不受影响（上方用例已锁）。
+    it("idleTimeoutMs 溢出（>2^31-1）→ fail-fast throw，不挂 timer", () => {
+      const onTimeout = vi.fn();
+      expect(() => armIdleTimer("sa-overflow", onTimeout, 3_000_000_000)).toThrowError(/2147483647/);
+      expect(() => armIdleTimer("sa-overflow", onTimeout, Number.MAX_SAFE_INTEGER)).toThrowError(
+        /Recovery/,
+      );
+      expect(hasIdleTimer("sa-overflow")).toBe(false);
+      vi.advanceTimersByTime(3_000_000_000);
+      expect(onTimeout).not.toHaveBeenCalled();
+    });
+
+    it("env XYZ_SUBAGENT_IDLE_TIMEOUT_MS 溢出 → fail-fast throw（arm 入口统一拦截）", () => {
+      vi.stubEnv("XYZ_SUBAGENT_IDLE_TIMEOUT_MS", "3000000000");
+      const onTimeout = vi.fn();
+      expect(() => armIdleTimer("sa-env-overflow", onTimeout)).toThrowError(/2147483647/);
+      expect(hasIdleTimer("sa-env-overflow")).toBe(false);
+    });
   });
 
   // ============================================================

package/src/execution/__tests__/list-fields.test.ts

@@ -1,11 +1,12 @@
 // src/execution/__tests__/list-fields.test.ts
 //
-// [v4 A-6] recordToListItem 字段派生单测。
+// [v4 A-6] recordToListItem 字段派生单测；[U3 C-outcome] closedReason 改锚 outcome。
 //
-// 验证 list 输出的新增字段派生正确：
+// 验证 list 输出的字段派生正确：
 //   - parent：从 record.parentRecordId 派生（顶层 record → undefined）
 //   - resumable：从 isResumable 派生（running && 无活进程句柄）
-//   - closedReason：透传 record.closedReason（SP-4 级联关闭告知替代）
+//   - outcome：一等终态语义（projectOutcome 唯一出口）；closedReason 退出对外 JSON，
+//     存量/重建 record（无 outcome 字段）由 deriveOutcome(closedReason, error) 兜底
 //
 // Mock 策略：vi.mock lifecycle-predicates 的 isResumable，控制其返回值模拟「有/无
 // 活进程句柄」两种 running 子态。isResumable 真实逻辑（running && !hasLiveProcessHandle）
@@ -21,7 +22,7 @@ vi.mock("../../execution/lifecycle-predicates.ts", () => ({
 
 import { recordToListItem } from "../../interface/subagent-actions.ts";
 import { isResumable } from "../../execution/lifecycle-predicates.ts";
-import type { ClosedReason, SubagentRecord } from "../types.ts";
+import type { SubagentRecord } from "../types.ts";
 
 // ── SubagentRecord stub 工厂（最小合法 record） ──
 
@@ -51,7 +52,7 @@ function makeRecord(over: Partial<SubagentRecord> = {}): SubagentRecord {
 	};
 }
 
-describe("recordToListItem — parent/resumable/closedReason (v4 A-6)", () => {
+describe("recordToListItem — parent/resumable (v4 A-6)", () => {
 	// ═══ parent：从 record.parentRecordId 派生 ═══
 
 	it("parent：嵌套 record（parentRecordId='sa-A'）→ parent='sa-A'", () => {
@@ -84,26 +85,56 @@ describe("recordToListItem — parent/resumable/closedReason (v4 A-6)", () => {
 		expect(recordToListItem(rec).resumable).toBe(false);
 	});
 
-	// ═══ closedReason：透传 record.closedReason ═══
+	// ═══ outcome：一等终态披露（U3 C-outcome，projectOutcome 唯一出口）═══
 
-	it("closedReason：closed + closedReason='parent-fork' → 透传", () => {
+	it("outcome：closed + closedReason='parent-fork' + 合成 error → 'failed'（D6 显式取舍：父进程关闭未完成即失败，勿改 cancelled）", () => {
 		const rec = makeRecord({
 			status: "closed",
-			closedReason: "parent-fork" as ClosedReason,
+			closedReason: "parent-fork",
+			error: "closed due to parent-fork",
 		});
-		expect(recordToListItem(rec).closedReason).toBe("parent-fork");
+		expect(recordToListItem(rec).outcome).toBe("failed");
 	});
 
-	it("closedReason：closed + closedReason='parent-new' → 透传（SP-4 级联关闭场景）", () => {
+	it("outcome：closed + closedReason='cancelled' → 'cancelled'（取消优先于 error）", () => {
 		const rec = makeRecord({
 			status: "closed",
-			closedReason: "parent-new" as ClosedReason,
+			closedReason: "cancelled",
+			error: "aborted",
 		});
-		expect(recordToListItem(rec).closedReason).toBe("parent-new");
+		expect(recordToListItem(rec).outcome).toBe("cancelled");
 	});
 
-	it("closedReason：running record（无 closedReason）→ undefined", () => {
+	it("outcome：closed + gc 正常完成（存量形态，无 outcome 字段、无 error）→ 兑底派生 'completed'", () => {
+		const rec = makeRecord({ status: "closed", closedReason: "gc" });
+		expect(recordToListItem(rec).outcome).toBe("completed");
+	});
+
+	it("outcome：closed + gc + error（存量失败形态）→ 兑底派生 'failed'", () => {
+		const rec = makeRecord({ status: "closed", closedReason: "gc", error: "spawn EPIPE" });
+		expect(recordToListItem(rec).outcome).toBe("failed");
+	});
+
+	it("outcome：一等字段存在时直读透传（不重推导）", () => {
+		const rec = makeRecord({ status: "closed", outcome: "failed", closedReason: "gc" });
+		expect(recordToListItem(rec).outcome).toBe("failed");
+	});
+
+	it("outcome：running record → undefined（终态语义不适用活跃态）", () => {
 		const rec = makeRecord({ status: "running" });
-		expect(recordToListItem(rec).closedReason).toBeUndefined();
+		expect(recordToListItem(rec).outcome).toBeUndefined();
+	});
+
+	it("closedReason 退出对外 JSON：list item 不再携带（内部诊断字段），outcome 字段在位", () => {
+		const rec = makeRecord({ status: "closed", closedReason: "gc", error: "boom" });
+		const item = recordToListItem(rec);
+		expect("closedReason" in item).toBe(false);
+		const parsed = JSON.parse(JSON.stringify(item)) as Record<string, unknown>;
+		expect("closedReason" in parsed).toBe(false);
+		expect(parsed.outcome).toBe("failed");
+		// 旧字段保留（向后兼容）
+		expect(parsed.status).toBe("closed");
+		expect(parsed.state).toBe("ended");
+		expect(parsed.mode).toBe("background");
 	});
 });

package/src/execution/__tests__/model-resolver.test.ts

@@ -97,7 +97,7 @@ describe("resolveModel — explicit override failures throw (no silent fallback)
     const reg = makeRegistry([]);
     expect(() =>
       resolveModel(undefined, reg, { model: "x/nonexistent" }, ctxModel),
-    ).toThrow(/not found in registry/);
+    ).toThrow(/is not a registry entry/);
   });
 
   it("paramOverride.model found but auth missing → throws auth-specific message", () => {
@@ -117,7 +117,7 @@ describe("resolveModel — explicit override failures throw (no silent fallback)
         undefined,
         ctxModel,
       ),
-    ).toThrow(/not found in registry/);
+    ).toThrow(/is not a registry entry/);
   });
 
   it("no override, no agentConfig.model, no ctxModel → throws listing available", () => {
@@ -132,7 +132,7 @@ describe("resolveModel — explicit override failures throw (no silent fallback)
     const reg = makeRegistry([]);
     expect(() =>
       resolveModel(undefined, reg, { model: "no-slash" }, ctxModel),
-    ).toThrow(/not found in registry/);
+    ).toThrow(/is not a registry entry/);
   });
 });
 
@@ -264,7 +264,7 @@ describe('resolveModel — strips ":thinkingLevel" suffix from model string (A)'
     // ":foo" 不是合法 thinking level，不剥离 → 查不到 → 抛 not found
     const m = makeModel({ id: "m1", provider: "p", reasoning: false });
     const reg = makeRegistry([m]);
-    expect(() => resolveModel(undefined, reg, { model: "p/m1:foo" })).toThrow(/not found in registry/);
+    expect(() => resolveModel(undefined, reg, { model: "p/m1:foo" })).toThrow(/is not a registry entry/);
   });
 
   it('suffix-stripped resolve still respects explicit thinkingLevel param', () => {
@@ -291,7 +291,7 @@ describe("resolveModel — not-found error suggests similar models (B)", () => {
     } catch (e) {
       msg = (e as Error).message;
     }
-    expect(msg).toMatch(/not found in registry/);
+    expect(msg).toMatch(/is not a registry entry/);
     expect(msg).toMatch(/deepseek-router\/ds-pro/); // 建议列表含正确拼写
   });
 
@@ -351,6 +351,58 @@ describe("availableThinkingLevels", () => {
   });
 });
 
+// ============================================================
+// [U1 ModelRef 全等裁决] 孪生守卫（D1 规则④，两路径共用）
+// ============================================================
+
+describe("resolveModel — U1 twin guard (D1 rule ④)", () => {
+  /** 含大小写孪生的 registry 快照（模拟 models-store 刷新后大小写两形态并存）。 */
+  function makeTwinRegistry(): ModelRegistryLike {
+    return makeRegistry([
+      makeModel({ id: "GLM-5.3-Flash", provider: "zai-coding-cn" }),
+      makeModel({ id: "glm-5.3-flash", provider: "zai-coding-cn" }),
+    ]);
+  }
+
+  it("显式入参全等命中但 registry 含孪生 → 拒单（ambiguous，不代改输入）", () => {
+    expect(() =>
+      resolveModel(undefined, makeTwinRegistry(), { model: "zai-coding-cn/GLM-5.3-Flash" }, ctxModel),
+    ).toThrow(/ambiguous case variants/);
+  });
+
+  it("ctxModel 继承路径孪生守卫同等生效（D2 豁免的只是存在性复查）", () => {
+    const main = makeModel({ id: "GLM-5.3-Flash", provider: "zai-coding-cn" });
+    expect(() => resolveModel(undefined, makeTwinRegistry(), undefined, main)).toThrow(
+      /ambiguous case variants/,
+    );
+  });
+
+  it("无孪生时 ctxModel 路径零误伤（引用透传不变，P-A2 放行路径）", () => {
+    const main = makeModel({ id: "main-model", provider: "main" });
+    const r = resolveModel(undefined, makeRegistry([]), undefined, main);
+    expect(r.model).toBe(main);
+  });
+
+  it("小写入参（存在 case variant）→ 首个建议为正确大写串并标注（S2 负面路径）", () => {
+    const reg = makeRegistry([makeModel({ id: "GLM-5.3-Flash", provider: "zai-coding-cn" })]);
+    let msg = "";
+    try {
+      resolveModel(undefined, reg, { model: "zai-coding-cn/glm-5.3-flash" }, ctxModel);
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toMatch(/is not a registry entry/);
+    expect(msg).toContain('zai-coding-cn/GLM-5.3-Flash   ← case variant of "glm-5.3-flash"');
+  });
+
+  it("放行后回显与入参全等（L1 路径 model 字段保持 registry 原始大小写）", () => {
+    const m = makeModel({ id: "GLM-5.3-Flash", provider: "zai-coding-cn" });
+    const r = resolveModel(undefined, makeRegistry([m]), { model: "zai-coding-cn/GLM-5.3-Flash" }, ctxModel);
+    expect(r.model.id).toBe("GLM-5.3-Flash");
+    expect(r.model.provider).toBe("zai-coding-cn");
+  });
+});
+
 // ============================================================
 // ModelConfigService: initModel(ctxModel) → resolveModel L3 plumb-through
 // changeset 主打路径的 runtime 契约保护（EA-4）。

package/src/execution/__tests__/notifier-flush.test.ts

@@ -1,13 +1,14 @@
 /**
- * BgNotifier flushPendingNotifications — deliverAs 契约（FR-3/AC-3）。
+ * BgNotifier flushPendingNotifications — 单通道 triggerTurn 契约（U2 / D5）。
  *
- * 修复：deliverAs 从 'followUp' 改为 'steer'，确保 subagent 完成通知在主 agent
- * 处于 processing 状态（如轮询 loop）时也能立即抢占下一个 turn。
+ * 迁移史：deliverAs 从 'followUp' 改为 'steer'（FR-3/AC-3，commit d214d0d83）后，
+ * U2 courier 单通道化再收敛——steer / followUp / nextTurn 通道全部删除（nextTurn
+ * 唯一 drain 点在 session.prompt() 内，主 agent 长 streaming 场景下无限期滞留，
+ * 设计 D5 实测证伪），唯一发送形态 = sendCustomMessage({triggerTurn:true})；busy
+ * 场景由 ledger（settled 边沿 + isIdle 二次复查）或内核 settled 订阅在空闲边沿驱动。
  *
- * 修复背景：commit d214d0d83 已验证 steer 能避免 'Agent is already processing'；
- * workflow helpers.ts:151 已在同语义下用 steer。
- *
- * 测试方法：mock NotifierHost，捕获 sendMessage 调用参数，断言 deliverAs === 'steer'。
+ * 测试方法：mock NotifierHost，捕获 sendMessage 调用参数，断言 options 恰为
+ * { triggerTurn: true }（G4 字节锁定测试新锚：行为契约不变，机械迁移）。
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -33,7 +34,7 @@ function makeMockHost(): NotifierHost & {
 	};
 }
 
-describe("BgNotifier.flushPendingNotifications — deliverAs 契约", () => {
+describe("BgNotifier.flushPendingNotifications — 单通道 triggerTurn 契约（U2/D5）", () => {
 	let host: ReturnType<typeof makeMockHost>;
 		let notifier: BgNotifier;
 
@@ -46,7 +47,7 @@ describe("BgNotifier.flushPendingNotifications — deliverAs 契约", () => {
 		notifier.dispose();
 	});
 
-	it("flush 时调 sendMessage 的 options.deliverAs === 'steer'（FR-3/AC-3）", () => {
+	it("flush 时 sendMessage 的 options 恰为 { triggerTurn: true }（无 deliverAs，D5 单通道）", () => {
 		notifier.notify({
 			id: "bg-test-1",
 			status: "closed",
@@ -59,10 +60,10 @@ describe("BgNotifier.flushPendingNotifications — deliverAs 契约", () => {
 		// hasRunningBackground=false → notify 立即 flush
 		expect(host.sendMessageCalls).toHaveLength(1);
 		const call = host.sendMessageCalls[0];
-		expect(call.options).toMatchObject({ deliverAs: "steer" });
+		expect(call.options).toEqual({ triggerTurn: true });
 	});
 
-	it("flush 时 triggerTurn 也必须为 true（让父 agent 立即唤醒）", () => {
+	it("flush 时 triggerTurn 必须为 true（让父 agent 立即唤醒）", () => {
 		notifier.notify({
 			id: "bg-test-2",
 			status: "closed",
@@ -73,10 +74,7 @@ describe("BgNotifier.flushPendingNotifications — deliverAs 契约", () => {
 		});
 
 		expect(host.sendMessageCalls).toHaveLength(1);
-		expect(host.sendMessageCalls[0].options).toMatchObject({
-			triggerTurn: true,
-			deliverAs: "steer",
-		});
+		expect(host.sendMessageCalls[0].options).toEqual({ triggerTurn: true });
 	});
 });
 
@@ -119,12 +117,9 @@ describe("BgNotifier — isIdle gate 竞态修复", () => {
 		host.isIdle.mockReturnValue(true);
 		vi.advanceTimersByTime(100);
 
-		// idle 后发送，deliverAs=steer + triggerTurn=true
+		// idle 后发送，单通道 {triggerTurn:true}（U2/D5：无 deliverAs）
 		expect(host.sendMessageCalls).toHaveLength(1);
-		expect(host.sendMessageCalls[0].options).toMatchObject({
-			triggerTurn: true,
-			deliverAs: "steer",
-		});
+		expect(host.sendMessageCalls[0].options).toEqual({ triggerTurn: true });
 	});
 
 	it("主 agent 持续 busy 达退避上限后强制发送（防通知饿死）", () => {
@@ -334,8 +329,8 @@ describe("BgNotifier buildLlmContent 指针行（wave2：chatMode sessionFile
 
 	it("[review 修复] gc-failed + patchFile 并存 → failed 文案优先（失败轮也会写 patchFile，patch 提示不可达）", () => {
 		// 回归锚定：doFinalizeRecord Step 0 对 worktreeHandle 无条件 collectPatch，gc 失败 +
-		// worktree 并存时 patchFile 有值。判定顺序必须与 deriveClosedDisplay / renderRecordLines
-		// 同构（cancelled → gc+error → patch/result），否则 LLM 被告知 completed 掩盖失败。
+		// worktree 并存时 patchFile 有值。[U3] 判定收口到单一 deriveOutcome（cancelled →
+		// failed → patch/result），否则 LLM 被告知 completed 掩盖失败。
 		notifier.notify({
 			id: "sa-ptr-8", status: "closed", closedReason: "gc", agent: "w",
 			error: "spawn EPIPE",
@@ -347,6 +342,52 @@ describe("BgNotifier buildLlmContent 指针行（wave2：chatMode sessionFile
 		expect(sentContent()).toBe('Subagent "w" (sa-ptr-8) failed: spawn EPIPE');
 	});
 
+	it("[U3][D6 显式取舍] parent-shutdown 合成关闭 + patchFile 并存 → failed 文案优先（patch 提示不可达）", () => {
+		// disposeAllRecords 合成 result 恒写 error:"closed due to ..." → outcome='failed'；
+		// worktree 失败并存时仍不得展示 patch 提示（「failed 优先于 patchFile 提示」保真）。
+		notifier.notify({
+			id: "sa-u3-ps", status: "closed", closedReason: "parent-shutdown", agent: "w",
+			error: "closed due to parent-shutdown",
+			patchFile: "/tmp/patches/sa-u3-ps.patch",
+			startedAt: 1, endedAt: 2,
+		});
+
+		expect(sentContent()).toBe('Subagent "w" (sa-u3-ps) failed: closed due to parent-shutdown');
+	});
+
+	it("[U3] details payload 物化 outcome：closed 入参缺省时按 deriveOutcome 兑底填充", () => {
+		notifier.notify({
+			id: "sa-u3-mat", status: "closed", closedReason: "gc", agent: "w",
+			error: "boom",
+			startedAt: 1, endedAt: 2,
+		});
+
+		expect(host.sendMessageCalls).toHaveLength(1);
+		const msg = host.sendMessageCalls[0]!.message as { details?: { outcome?: string } };
+		expect(msg.details?.outcome).toBe("failed");
+	});
+
+	it("[U3] 显式 outcome 优先于 closedReason 兑底（一等字段直读）", () => {
+		notifier.notify({
+			id: "sa-u3-explicit", status: "closed", closedReason: "gc", agent: "w",
+			outcome: "cancelled",
+			startedAt: 1, endedAt: 2,
+		});
+
+		expect(sentContent()).toBe('Subagent "w" (sa-u3-explicit) cancelled.');
+	});
+
+	it("[U3] running（轮次通知）不物化 outcome（终态语义不适用活跃态）", () => {
+		notifier.notify({
+			id: "sa-u3-round", status: "running", agent: "w", round: 1, result: "r1",
+			startedAt: 1, endedAt: 2,
+		});
+
+		expect(host.sendMessageCalls).toHaveLength(1);
+		const msg = host.sendMessageCalls[0]!.message as { details?: { outcome?: string } };
+		expect(msg.details?.outcome).toBeUndefined();
+	});
+
 	it("one-shot（sessionFile 未透传 → undefined）→ closed 通知与改造前逐字节一致（基线常量锚定）", () => {
 		notifier.notify({
 			id: "sa-ptr-7", status: "closed", agent: "worker", result: "done",
@@ -433,10 +474,7 @@ describe("BgNotifier — subscribeSettled 装配（must-fix #4 / D8 settled 边
 		settledEdges[0]!();
 
 		expect(host.sendMessageCalls).toHaveLength(1);
-		expect(host.sendMessageCalls[0]!.options).toMatchObject({
-			triggerTurn: true,
-			deliverAs: "steer",
-		});
+		expect(host.sendMessageCalls[0]!.options).toEqual({ triggerTurn: true });
 	});
 
 	it("dispose 后 settled 边沿不再触发发送（内核 disposed 拦截）", () => {