@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

package/src/execution/__tests__/notify-ledger.test.ts

@@ -0,0 +1,826 @@
+// src/execution/__tests__/notify-ledger.test.ts
+//
+// U2 B-ledger 单测族：通知账本与 courier 的四步生命周期
+// （设计 docs/design/subagent-dispatch-reliability.md §3.3 D4/D5）。
+//
+// 覆盖验收面：
+//   - 写账先于投递（顺序断言：appendEntry ledger entry 先于 sendMessage）
+//   - settled 边沿投递 + isIdle 二次复查命中 busy 时挂回 pending
+//   - 回执销账（ack entry 追加）后两列 entry 差集为空
+//   - 重启恢复（新实例扫账本）重放未销账号、已销账零重发
+//   - notifyId 幂等（重复 record / 重复投递条目可识别）
+//   - 120s 看门狗触发（fake timers；主 session 长期无 settled 兜底 + 超时重投）
+//   - 合并投递（同一边沿多条 pending 单条送达，content join + batch details）
+//   - compaction 降级（ledger/ack entry 被清除后按内存态补写）
+//   - session_start 恢复钩子（bindNotifyLedgerHost + recoverFromSession：
+//     mock session entries 含 ledger/ack entry → 重放差集）
+//   - notifier 四步接线（createNotifier + bindNotifyLedgerHost：notify → 写账 →
+//     边沿投递 → 回执销账全链路）
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { clearRateLimiterState, setPiHandle } from "@zhushanwen/pi-extension-logger";
+import {
+  bindNotifyLedgerHost,
+  createNotifyLedger,
+  getBoundNotifyLedger,
+  NOTIFY_ACK_CUSTOM_TYPE,
+  NOTIFY_CUSTOM_TYPE,
+  NOTIFY_LEDGER_CUSTOM_TYPE,
+  NOTIFY_WATCHDOG_MS,
+  _resetNotifyLedgerForTest,
+  type NotifyLedgerHost,
+} from "../notify-ledger.ts";
+import { createNotifier, type BgNotifyRecord, type NotifierHost } from "../notifier.ts";
+
+// ─── mock host ─────────────────────────────────────────────
+
+interface LedgerHostMock {
+  host: NotifyLedgerHost;
+  /** 追加的 plain custom entry（ledger/ack 两列，含 customType）。与 sessionEntries
+   *  共享同一数组——送达 custom_message entry 也会落入（无 data 字段）。 */
+  entries: { type: string; customType: string; data?: Record<string, unknown> }[];
+  /** session entries 视图（回执扫描 + 恢复扫描的输入；与 entries 共享同一数组）。 */
+  sessionEntries: unknown[];
+  /** 送达消息（sendDelivery 调用）。 */
+  sentMessages: { customType: string; content: string; display: boolean; details?: unknown }[];
+  /** settled 边沿回调（测试手动触发模拟 pi agent_settled 事件）。 */
+  settledHandlers: Array<() => void>;
+  setIdle(idle: boolean): void;
+  /** 送达是否同步落盘为 custom_message entry（模拟 pi：triggerTurn run 结束后落盘）。
+   *  false = 模拟回执延迟/丢失（消息滞留内存）。 */
+  deliverPersists: { value: boolean };
+  /** U4：sendDelivery 是否抛异常（模拟受理被拒——下方 sendDelivery 首行 throw）。 */
+  deliveryThrows: { value: boolean };
+}
+
+function makeLedgerHost(): LedgerHostMock {
+  const entries: LedgerHostMock["entries"] = [];
+  const sessionEntries: unknown[] = entries;
+  const sentMessages: LedgerHostMock["sentMessages"] = [];
+  const settledHandlers: Array<() => void> = [];
+  const idle = { value: true };
+  const deliverPersists = { value: true };
+  const deliveryThrows = { value: false };
+  const host: NotifyLedgerHost = {
+    appendLedgerEntry: (customType, data) => {
+      entries.push({ type: "custom", customType, data: data as Record<string, unknown> | undefined });
+    },
+    readSessionEntries: () => sessionEntries,
+    isIdle: () => idle.value,
+    onAgentSettled: (handler) => {
+      settledHandlers.push(handler);
+    },
+    sendDelivery: (message) => {
+      if (deliveryThrows.value) {
+        throw new Error("delivery rejected (mock)");
+      }
+      sentMessages.push(message);
+      if (deliverPersists.value) {
+        sessionEntries.push({
+          type: "custom_message",
+          customType: message.customType,
+          content: message.content,
+          display: message.display,
+          details: message.details,
+        });
+      }
+    },
+  };
+  return {
+    host,
+    entries,
+    sessionEntries,
+    sentMessages,
+    settledHandlers,
+    setIdle: (v: boolean) => {
+      idle.value = v;
+    },
+    deliverPersists,
+    deliveryThrows,
+  };
+}
+
+/** 触发一次 settled 边沿（模拟 pi agent_settled 事件）。 */
+function fireSettled(mock: LedgerHostMock): void {
+  for (const handler of mock.settledHandlers) handler();
+}
+
+/** 两列 entry 差集（未销账号）：ledger entry 的 notifyId − ack entry 的 notifyId。 */
+function ledgerDiff(mock: LedgerHostMock): Set<string> {
+  const ledgerIds = new Set<string>();
+  const acked = new Set<string>();
+  for (const e of mock.entries) {
+    if (e.customType !== NOTIFY_LEDGER_CUSTOM_TYPE && e.customType !== NOTIFY_ACK_CUSTOM_TYPE) continue;
+    const notifyId = e.data?.["notifyId"];
+    if (typeof notifyId !== "string") continue;
+    if (e.customType === NOTIFY_LEDGER_CUSTOM_TYPE) ledgerIds.add(notifyId);
+    if (e.customType === NOTIFY_ACK_CUSTOM_TYPE) acked.add(notifyId);
+  }
+  for (const id of acked) ledgerIds.delete(id);
+  return ledgerIds;
+}
+
+// ─── 账本四步生命周期 ─────────────────────────────────────
+
+describe("NotifyLedger — 四步生命周期（D4/D5）", () => {
+  beforeEach(() => {
+    _resetNotifyLedgerForTest();
+  });
+  afterEach(() => {
+    _resetNotifyLedgerForTest();
+  });
+
+  it("①→② 写账先于投递：appendEntry(ledger) 先于 sendDelivery（顺序断言）", () => {
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+
+    const recorded = ledger.record("sa-1", "content-1", { notifyId: "sa-1", id: "sa-1" });
+    expect(recorded).toBe(true);
+    // idle → notify 后立即投递（record 内不自投，attemptDeliver 由调用方驱动；
+    // 此处显式调用验证顺序）
+    ledger.attemptDeliver();
+
+    expect(mock.sentMessages).toHaveLength(1);
+    // 顺序断言：账本 entry（entries[0]）先于送达消息（sentMessages[0]）
+    expect(mock.entries[0]?.customType).toBe(NOTIFY_LEDGER_CUSTOM_TYPE);
+    expect(mock.sentMessages[0]?.customType).toBe(NOTIFY_CUSTOM_TYPE);
+    // 单条投递形态：details = record 本体（notifyId 携带在 details，不在文案）
+    expect(mock.sentMessages[0]?.details).toMatchObject({ notifyId: "sa-1" });
+
+    ledger.dispose();
+  });
+
+  it("② settled 边沿投递：busy 挂回 pending，isIdle 复查通过后边沿送达", () => {
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+
+    // busy：notify 后 attemptDeliver 放弃本次，消息挂回 pending
+    mock.setIdle(false);
+    expect(ledger.record("sa-busy", "content", { notifyId: "sa-busy" })).toBe(true);
+    ledger.attemptDeliver();
+    expect(mock.sentMessages).toHaveLength(0);
+    expect(ledger.pendingCount()).toBe(1);
+
+    // settled 边沿（边沿回调内 isIdle 复查）：仍 busy → 继续挂 pending
+    fireSettled(mock);
+    expect(mock.sentMessages).toHaveLength(0);
+    expect(ledger.pendingCount()).toBe(1);
+
+    // 主 agent 空闲后的下一 settled 边沿 → 送达
+    mock.setIdle(true);
+    fireSettled(mock);
+    expect(mock.sentMessages).toHaveLength(1);
+    expect(ledger.pendingCount()).toBe(0);
+    expect(ledger.waitingReceiptCount()).toBe(1);
+
+    ledger.dispose();
+  });
+
+  it("②→③ 回执销账：送达 entry 出现后下一 settled 边沿追加 ack entry，差集为空", () => {
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+
+    ledger.record("sa-ack", "content", { notifyId: "sa-ack" });
+    ledger.attemptDeliver();
+    expect(mock.sentMessages).toHaveLength(1);
+    expect(ledgerDiff(mock)).toEqual(new Set(["sa-ack"])); // 已送达未销账
+
+    // 下一 settled 边沿：checkReceipts 扫到 custom_message entry（sendDelivery 已
+    // 模拟落盘）→ 追加 ack entry → 两列差集为空
+    fireSettled(mock);
+    expect(ledgerDiff(mock)).toEqual(new Set());
+    expect(ledger.waitingReceiptCount()).toBe(0);
+    expect(mock.entries.some((e) => e.customType === NOTIFY_ACK_CUSTOM_TYPE)).toBe(true);
+
+    ledger.dispose();
+  });
+
+  it("③ 内存不承担销账职责：回执缺失（消息滞留内存）时不销账，差集保留", () => {
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+
+    // 模拟消息滞留内存（如竞态窗口掉进 steer 队列）：sendDelivery 不落盘
+    mock.deliverPersists.value = false;
+    ledger.record("sa-lost", "content", { notifyId: "sa-lost" });
+    ledger.attemptDeliver();
+    expect(mock.sentMessages).toHaveLength(1);
+
+    fireSettled(mock);
+    // 无 custom_message entry 回执 → 不销账（内存不销账，等看门狗重投）
+    expect(ledgerDiff(mock)).toEqual(new Set(["sa-lost"]));
+    expect(ledger.waitingReceiptCount()).toBe(1);
+
+    ledger.dispose();
+  });
+
+  it("④ 重启恢复：新实例扫两列差集，未销账号重放、已销账零重发", () => {
+    // 旧实例（模拟崩溃前的进程）：sa-r1/sa-r2 送达销账，sa-r3 入账未投
+    const oldMock = makeLedgerHost();
+    const oldLedger = createNotifyLedger(oldMock.host);
+    for (const id of ["sa-r1", "sa-r2"]) {
+      oldLedger.record(id, `content-${id}`, { notifyId: id });
+    }
+    oldLedger.attemptDeliver();
+    fireSettled(oldMock);
+    oldLedger.record("sa-r3", "content-sa-r3", { notifyId: "sa-r3" }); // 崩溃前未投
+    expect(ledgerDiff(oldMock)).toEqual(new Set(["sa-r3"]));
+    oldLedger.dispose();
+
+    // 重启：新实例扫同一 session 文件（sessionEntries 视图保留旧 entry 列）
+    const newMock = makeLedgerHost();
+    newMock.sessionEntries.push(...oldMock.sessionEntries);
+    const newLedger = createNotifyLedger(newMock.host);
+    const replayed = newLedger.recoverFromSession();
+
+    expect(replayed).toBe(1); // 仅未销账的 sa-r3 重放
+    expect(newMock.sentMessages).toHaveLength(1);
+    expect(newMock.sentMessages[0]?.details).toMatchObject({ notifyId: "sa-r3" });
+    // 已销账号零重发
+    const sentIds = newMock.sentMessages.map((m) => (m.details as { notifyId?: string }).notifyId);
+    expect(sentIds).not.toContain("sa-r1");
+    expect(sentIds).not.toContain("sa-r2");
+
+    newLedger.dispose();
+  });
+
+  it("④ notifyId 幂等：重复 record 同 notifyId 返回 false，不重复投递", () => {
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+
+    expect(ledger.record("sa-dup", "content", { notifyId: "sa-dup" })).toBe(true);
+    expect(ledger.record("sa-dup", "content", { notifyId: "sa-dup" })).toBe(false);
+
+    ledger.attemptDeliver();
+    ledger.attemptDeliver();
+    expect(mock.sentMessages).toHaveLength(1); // 至多一次
+
+    // 销账后同 notifyId 再来（重复调用方）→ 仍幂等拒绝（已销账号绝不重发）
+    fireSettled(mock);
+    expect(ledger.record("sa-dup", "content", { notifyId: "sa-dup" })).toBe(false);
+
+    ledger.dispose();
+  });
+
+  it("④ 重复投递条目可识别：批量送达 details.items 每项携带 notifyId（回执匹配）", () => {
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+
+    ledger.record("sa-m1", "c1", { notifyId: "sa-m1" });
+    ledger.record("sa-m2", "c2", { notifyId: "sa-m2" });
+    ledger.attemptDeliver();
+
+    expect(mock.sentMessages).toHaveLength(1); // 合并为一条
+    const msg = mock.sentMessages[0]!;
+    expect(msg.content).toBe("c1\n\n---\n\nc2");
+    const details = msg.details as { batch: boolean; items: Array<{ notifyId?: string }> };
+    expect(details.batch).toBe(true);
+    expect(details.items.map((i) => i.notifyId)).toEqual(["sa-m1", "sa-m2"]);
+
+    // 批量回执匹配：items[].notifyId 命中 → 两条全部销账
+    fireSettled(mock);
+    expect(ledgerDiff(mock)).toEqual(new Set());
+
+    ledger.dispose();
+  });
+});
+
+// ─── 120s 看门狗（fake timers） ───────────────────────────
+
+describe("NotifyLedger — 120s 看门狗（D5 ②兜底触发面）", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    _resetNotifyLedgerForTest();
+  });
+  afterEach(() => {
+    _resetNotifyLedgerForTest();
+    vi.useRealTimers();
+  });
+
+  it("主 session 长期无 settled：busy 挂起的 pending 由看门狗在空闲后补投", () => {
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+
+    mock.setIdle(false);
+    ledger.record("sa-wd1", "content", { notifyId: "sa-wd1" });
+    ledger.attemptDeliver();
+    expect(mock.sentMessages).toHaveLength(0);
+
+    // 第一个周期仍 busy → 不投
+    vi.advanceTimersByTime(NOTIFY_WATCHDOG_MS);
+    expect(mock.sentMessages).toHaveLength(0);
+
+    // 主 agent 空闲（长期无 settled 事件）→ 下一周期看门狗补投
+    mock.setIdle(true);
+    vi.advanceTimersByTime(NOTIFY_WATCHDOG_MS);
+    expect(mock.sentMessages).toHaveLength(1);
+
+    ledger.dispose();
+  });
+
+  it("超时重投：sent 后一个周期无回执（消息滞留内存丢失）→ 看门狗重投", () => {
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+
+    // 投递但不落盘（模拟 steer 滞留后丢失——回执永不到）
+    mock.deliverPersists.value = false;
+    ledger.record("sa-wd2", "content", { notifyId: "sa-wd2" });
+    ledger.attemptDeliver();
+    expect(mock.sentMessages).toHaveLength(1);
+
+    // 一个周期后：无回执 → sentAt 超时转回 pending → 本 tick 重投（at-least-once）
+    vi.advanceTimersByTime(NOTIFY_WATCHDOG_MS);
+    expect(mock.sentMessages).toHaveLength(2);
+    expect(mock.sentMessages[1]?.details).toMatchObject({ notifyId: "sa-wd2" }); // 同 notifyId 可识别
+
+    ledger.dispose();
+  });
+
+  it("回执正常时序不重投：送达落盘 + settled 销账后，看门狗空转零动作", () => {
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+
+    ledger.record("sa-wd3", "content", { notifyId: "sa-wd3" });
+    ledger.attemptDeliver();
+    fireSettled(mock); // 销账
+    expect(ledgerDiff(mock)).toEqual(new Set());
+
+    vi.advanceTimersByTime(NOTIFY_WATCHDOG_MS * 3);
+    expect(mock.sentMessages).toHaveLength(1); // 无重投
+    expect(ledgerDiff(mock)).toEqual(new Set()); // 差集保持为空
+
+    ledger.dispose();
+  });
+});
+
+// ─── U4 投递计数分桶（设计 §5 U4 × §2.2 三条丢失路径） ─────
+
+describe("NotifyLedger — U4 投递计数分桶", () => {
+  beforeEach(() => {
+    _resetNotifyLedgerForTest();
+    clearRateLimiterState();
+  });
+  afterEach(() => {
+    _resetNotifyLedgerForTest();
+    setPiHandle(undefined);
+    clearRateLimiterState();
+  });
+
+  it("初始快照：三桶全 0（无投递异常时零计数）", () => {
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+    expect(ledger.deliveryMetrics()).toEqual({ settleRejected: 0, watchdogReplays: 0, recoveryReplays: 0 });
+    ledger.dispose();
+  });
+
+  it("②settleRejected 桶：sendDelivery 受理被拒 → +1 且消息挂回 pending；恢复后不再累计", () => {
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+
+    mock.deliveryThrows.value = true;
+    ledger.record("sa-rj", "content", { notifyId: "sa-rj" });
+    ledger.attemptDeliver();
+
+    expect(ledger.deliveryMetrics().settleRejected).toBe(1);
+    expect(mock.sentMessages).toHaveLength(0);
+    expect(ledger.pendingCount()).toBe(1); // 挂回 pending，账未丢
+
+    // 下一边沿受理恢复：投递成功，rejection 桶不再增长
+    mock.deliveryThrows.value = false;
+    ledger.attemptDeliver();
+    expect(mock.sentMessages).toHaveLength(1);
+    expect(ledger.deliveryMetrics().settleRejected).toBe(1);
+
+    ledger.dispose();
+  });
+
+  it("①watchdogReplays 桶：销账超时重投按条数累计（同消息反复超时继续累计）", () => {
+    vi.useFakeTimers();
+    try {
+      const mock = makeLedgerHost();
+      const ledger = createNotifyLedger(mock.host);
+
+      // 投递但回执永不到（消息滞留内存丢失）
+      mock.deliverPersists.value = false;
+      ledger.record("sa-wd", "content", { notifyId: "sa-wd" });
+      ledger.attemptDeliver();
+      expect(ledger.deliveryMetrics().watchdogReplays).toBe(0);
+
+      // 第一个周期：销账超时 → 转回 pending 重投，桶 +1
+      vi.advanceTimersByTime(NOTIFY_WATCHDOG_MS);
+      expect(mock.sentMessages).toHaveLength(2);
+      expect(ledger.deliveryMetrics().watchdogReplays).toBe(1);
+
+      // 第二个周期仍无回执：同消息再重投，桶累计到 2（滞留深度可见）
+      vi.advanceTimersByTime(NOTIFY_WATCHDOG_MS);
+      expect(mock.sentMessages).toHaveLength(3);
+      expect(ledger.deliveryMetrics().watchdogReplays).toBe(2);
+
+      ledger.dispose();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("③recoveryReplays 桶：session_start 恢复重放条数与返回值一致，已销账零计数", () => {
+    const mock = makeLedgerHost();
+    mock.sessionEntries.push(
+      { 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 ledger = createNotifyLedger(mock.host);
+    const replayed = ledger.recoverFromSession();
+
+    expect(replayed).toBe(1); // s-b 未销账重放；s-a 已销账零重发
+    expect(ledger.deliveryMetrics().recoveryReplays).toBe(1);
+
+    // 再次恢复（幂等）：差集已入账，零重发零计数
+    expect(ledger.recoverFromSession()).toBe(0);
+    expect(ledger.deliveryMetrics().recoveryReplays).toBe(1);
+
+    ledger.dispose();
+  });
+
+  it("分桶增量经 extensionLogger 通道落日志（appendEntry，msg 固定 key + 动态值在 data）", () => {
+    const appendEntry = vi.fn();
+    setPiHandle({ appendEntry });
+
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+
+    mock.deliveryThrows.value = true;
+    ledger.record("sa-log", "content", { notifyId: "sa-log" });
+    ledger.attemptDeliver();
+
+    expect(appendEntry).toHaveBeenCalledTimes(1);
+    const [customType, data] = appendEntry.mock.calls[0] as unknown as [string, { level: string; message: string; data: Record<string, unknown> }];
+    expect(customType).toBe("subagents:log");
+    expect(data.level).toBe("warn");
+    expect(data.message).toContain("notify delivery bucket [settleRejected]");
+    expect(data.data).toEqual({ total: 1, pending: 1 });
+
+    ledger.dispose();
+  });
+});
+
+// ─── compaction 降级（P-B4） ───────────────────────────────
+
+describe("NotifyLedger — compaction 降级（P-B4 未验证，条件补写）", () => {
+  beforeEach(() => {
+    _resetNotifyLedgerForTest();
+  });
+  afterEach(() => {
+    _resetNotifyLedgerForTest();
+  });
+
+  it("compaction 清除 ledger/ack entry 后按内存态补写（重建两列差集）", () => {
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+
+    // sa-c1 送达销账、sa-c2 入账未投
+    ledger.record("sa-c1", "c1", { notifyId: "sa-c1" });
+    ledger.attemptDeliver();
+    fireSettled(mock);
+    ledger.record("sa-c2", "c2", { notifyId: "sa-c2" });
+    expect(ledgerDiff(mock)).toEqual(new Set(["sa-c2"]));
+
+    // 模拟 compaction 清掉全部 plain custom entry（ledger/ack 两列全丢，送达
+    // custom_message entry 假设保留——保守验证降级闭环）
+    mock.sessionEntries.length = 0;
+
+    const rewritten = ledger.compactionCheck();
+    expect(rewritten).toBe(2); // 补写 sa-c2 的 ledger + sa-c1 的 ack
+    // 补写后差集恢复：仍只有 sa-c2 未销账（sa-c1 销账事实随 ack 补写恢复）
+    expect(ledgerDiff(mock)).toEqual(new Set(["sa-c2"]));
+
+    ledger.dispose();
+  });
+
+  it("entry 存活时 compactionCheck no-op（零补写）", () => {
+    const mock = makeLedgerHost();
+    const ledger = createNotifyLedger(mock.host);
+    ledger.record("sa-nc", "c", { notifyId: "sa-nc" });
+    ledger.attemptDeliver();
+    fireSettled(mock);
+
+    expect(ledger.compactionCheck()).toBe(0);
+    ledger.dispose();
+  });
+});
+
+// ─── session_start 恢复钩子（bindNotifyLedgerHost） ────────
+
+describe("bindNotifyLedgerHost — session_start 恢复钩子", () => {
+  beforeEach(() => {
+    _resetNotifyLedgerForTest();
+  });
+  afterEach(() => {
+    _resetNotifyLedgerForTest();
+  });
+
+  it("bind + recoverFromSession：mock session 含 ledger/ack entry → 重放差集", () => {
+    const mock = makeLedgerHost();
+    // 预置 session 文件内容（模拟重启前的落盘）：2 条 ledger + 1 条 ack + 1 条已送达
+    mock.sessionEntries.push(
+      { 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" } },
+      { type: "custom_message", customType: NOTIFY_CUSTOM_TYPE, content: "ca", display: true, details: { notifyId: "s-a" } },
+    );
+
+    const ledger = bindNotifyLedgerHost(mock.host);
+    const replayed = ledger.recoverFromSession();
+
+    expect(replayed).toBe(1); // s-b 未销账重放；s-a 已销账零重发
+    expect(mock.sentMessages).toHaveLength(1);
+    expect(mock.sentMessages[0]?.content).toBe("cb");
+    expect(mock.sentMessages[0]?.details).toMatchObject({ notifyId: "s-b" });
+  });
+
+  it("重复 bind 替换旧实例（/resume /fork /new 的 session_start）", () => {
+    const mock1 = makeLedgerHost();
+    bindNotifyLedgerHost(mock1.host);
+    expect(bindNotifyLedgerHost(makeLedgerHost().host)).toBeDefined();
+    // 旧实例已 dispose（settled 回调静默）
+    fireSettled(mock1);
+    expect(mock1.sentMessages).toHaveLength(0);
+  });
+
+  it("损坏 / 形态不符 entry 跳过不 throw（无 notifyId / data 非 object）", () => {
+    const mock = makeLedgerHost();
+    mock.sessionEntries.push(
+      { type: "custom", customType: NOTIFY_LEDGER_CUSTOM_TYPE, data: { v: 1 } }, // 无 notifyId
+      { type: "custom", customType: NOTIFY_LEDGER_CUSTOM_TYPE }, // 无 data
+      { type: "custom", customType: "unrelated-type", data: { notifyId: "x" } },
+      null,
+    );
+    const ledger = bindNotifyLedgerHost(mock.host);
+    expect(ledger.recoverFromSession()).toBe(0);
+  });
+});
+
+// ─── notifier 四步接线（createNotifier × ledger） ─────────
+
+describe("createNotifier — ledger 四步接线（U2）", () => {
+  beforeEach(() => {
+    _resetNotifyLedgerForTest();
+  });
+  afterEach(() => {
+    _resetNotifyLedgerForTest();
+  });
+
+  /** notifier 侧 mock host：sendMessage 是 ledger sendDelivery 的下游（index.ts
+   *  装配 sendDelivery = pi.sendMessage({triggerTurn:true})，此处直接捕获）。 */
+  function makeNotifierHost(): NotifierHost & {
+    sentOptions: unknown[];
+    sentMessages: { customType: string; content: string; display: boolean; details?: unknown }[];
+  } {
+    const sentOptions: unknown[] = [];
+    const sentMessages: { customType: string; content: string; display: boolean; details?: unknown }[] = [];
+    return {
+      sentOptions,
+      sentMessages,
+      sendMessage(message, options) {
+        sentOptions.push(options);
+        sentMessages.push(message);
+      },
+      hasRunningBackground: () => false,
+      isIdle: () => true,
+    };
+  }
+
+  function oneShotRecord(id: string, result = "done"): BgNotifyRecord {
+    return { id, status: "closed", agent: "worker", result, startedAt: 1, endedAt:2 };
+  }
+
+  it("notify → 写账 → 投递 → 回执销账全链路（notifyId = id，G4 文案不变）", () => {
+    const ledgerMock = makeLedgerHost();
+    // sendDelivery 桥接到 notifier host.sendMessage（模拟 index.ts 装配）
+    const notifierHost = makeNotifierHost();
+    ledgerMock.host.sendDelivery = (message) => {
+      ledgerMock.sentMessages.push(message);
+      if (ledgerMock.deliverPersists.value) {
+        ledgerMock.sessionEntries.push({
+          type: "custom_message",
+          customType: message.customType,
+          content: message.content,
+          display: message.display,
+          details: message.details,
+        });
+      }
+      notifierHost.sendMessage(message, { triggerTurn: true });
+    };
+    bindNotifyLedgerHost(ledgerMock.host);
+
+    const notifier = createNotifier(notifierHost);
+    notifier.notify(oneShotRecord("sa-n1"));
+
+    // ① 写账先于 ② 投递：ledger entry 落盘且消息已送达
+    expect(ledgerMock.entries[0]?.customType).toBe(NOTIFY_LEDGER_CUSTOM_TYPE);
+    expect(notifierHost.sentMessages).toHaveLength(1);
+    // 单通道断言：options 只有 triggerTurn，无 deliverAs
+    expect(notifierHost.sentOptions[0]).toEqual({ triggerTurn: true });
+    // G4 文案锚：one-shot 完成通知逐字节不变（notifyId 不进文案）
+    expect(notifierHost.sentMessages[0]?.content).toBe('Subagent "worker" (sa-n1) completed. Result:\ndone');
+    // details 携带 notifyId + outcome 物化（U3）
+    expect(notifierHost.sentMessages[0]?.details).toMatchObject({ notifyId: "sa-n1", outcome: "completed" });
+
+    // ③ 回执销账：settled 边沿 → ack entry + 差集为空
+    fireSettled(ledgerMock);
+    expect(ledgerDiff(ledgerMock)).toEqual(new Set());
+
+    notifier.dispose();
+  });
+
+  it("chatMode round dedupe key 平移：notifyId = `${id}:${round}`，规则不变", () => {
+    const ledgerMock = makeLedgerHost();
+    const notifierHost = makeNotifierHost();
+    // 桥接：ledger sendDelivery → notifier host.sendMessage（模拟 index.ts 装配）
+    ledgerMock.host.sendDelivery = (message) => {
+      notifierHost.sendMessage(message, { triggerTurn: true });
+      if (ledgerMock.deliverPersists.value) {
+        ledgerMock.sessionEntries.push({
+          type: "custom_message",
+          customType: message.customType,
+          content: message.content,
+          display: message.display,
+          details: message.details,
+        });
+      }
+    };
+    bindNotifyLedgerHost(ledgerMock.host);
+
+    const notifier = createNotifier(notifierHost);
+    notifier.notify({ id: "sa-chat", status: "running", agent: "w", round: 1, result: "r1", startedAt: 1, endedAt: 2 });
+    notifier.notify({ id: "sa-chat", status: "running", agent: "w", round: 2, result: "r2", startedAt: 3, endedAt: 4 });
+    // 同 id 同 round 第二次被 notifyId 幂等吞
+    notifier.notify({ id: "sa-chat", status: "running", agent: "w", round: 1, result: "r1-again", startedAt: 5, endedAt: 6 });
+
+    expect(notifierHost.sentMessages).toHaveLength(2);
+    expect(notifierHost.sentMessages[0]?.details).toMatchObject({ notifyId: "sa-chat:1" });
+    expect(notifierHost.sentMessages[1]?.details).toMatchObject({ notifyId: "sa-chat:2" });
+    // chatMode 轮次通知文案（running 分支）不变
+    expect(notifierHost.sentMessages[0]?.content).toBe('Subagent "w" (sa-chat) finished a round. Reply:\nr1');
+
+    notifier.dispose();
+  });
+
+  it("ledger 未 bind 时退回内核路径（向后兼容，options 仍单通道 triggerTurn）", () => {
+    const notifierHost = makeNotifierHost();
+    const notifier = createNotifier(notifierHost);
+    notifier.notify(oneShotRecord("sa-nb"));
+
+    expect(notifierHost.sentMessages).toHaveLength(1);
+    expect(notifierHost.sentOptions[0]).toEqual({ triggerTurn: true });
+    expect(notifierHost.sentMessages[0]?.content).toBe('Subagent "worker" (sa-nb) completed. Result:\ndone');
+
+    notifier.dispose();
+  });
+
+  it("U4 warn 注入：内核路径 port.send 失败 → 警告落 extensionLogger appendEntry，console.warn 零调用", () => {
+    const appendEntry = vi.fn();
+    setPiHandle({ appendEntry });
+    const consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const notifierHost = makeNotifierHost();
+      // sendMessage 抛异常 = port.send 同步失败 → 内核 onSendFail → warn（经注入出口）
+      notifierHost.sendMessage = () => {
+        throw new Error("channel closed (mock)");
+      };
+      const notifier = createNotifier(notifierHost);
+      notifier.notify(oneShotRecord("sa-warn"));
+
+      const logCalls = appendEntry.mock.calls.filter((c) => c[0] === "subagents:log");
+      expect(logCalls.length).toBeGreaterThanOrEqual(1);
+      // 按内容定位目标日志（logCalls[0] 可能是 ledger 未 bind 的 fallback warn——
+      // 该降级留痕同样落 extensionLogger 通道，先于 port.send 失败发生）
+      const sendFailLogged = logCalls.some((c) => JSON.stringify(c[1]).includes("port.send failed"));
+      expect(sendFailLogged).toBe(true);
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+
+      notifier.dispose();
+    } finally {
+      consoleWarnSpy.mockRestore();
+      setPiHandle(undefined);
+      clearRateLimiterState();
+    }
+  });
+
+  it("dispose 摘除模块级绑定：后续 notify 走内核路径，settled 边沿静默", () => {
+    const ledgerMock = makeLedgerHost();
+    bindNotifyLedgerHost(ledgerMock.host);
+    const notifierHost = makeNotifierHost();
+    const notifier = createNotifier(notifierHost);
+    notifier.dispose();
+
+    fireSettled(ledgerMock);
+    // revive（/resume /fork /new 后）：notifier 复活，但 ledger 已随 dispose 摘除
+    // ——notify 退回内核路径
+    notifier.revive();
+    notifier.notify(oneShotRecord("sa-post-dispose"));
+    expect(notifierHost.sentMessages).toHaveLength(1); // 内核路径立即投（无 ledger）
+  });
+});
+
+// ─── MF-5: settled 监听单例化 ──────────────────────────────
+//
+// 回归背景：index.ts:428-430 每次 session_start 注册新 pi.on("agent_settled")
+// handler，旧实例 dispose 只置标志不移除物理监听（pi 0.84.1 on() 无 off）——
+// 长会话 N 次切换累积 N 个死 handler。修复：bind 路径首次注册模块级单例
+// handler（settledEdgeDispatch），后续 bind 只换 boundLedger 引用。
+
+describe("MF-5: settled 监听单例化（多次 bind 物理监听数不增）", () => {
+  beforeEach(() => {
+    _resetNotifyLedgerForTest();
+  });
+  afterEach(() => {
+    _resetNotifyLedgerForTest();
+  });
+
+  it("连续 3 次 bind（/resume /fork /new 的 session_start）→ onAgentSettled 注册仅首次发生", () => {
+    const mocks = [makeLedgerHost(), makeLedgerHost(), makeLedgerHost()];
+    const registerSpies = mocks.map((mock) => {
+      const spy = vi.fn();
+      mock.host.onAgentSettled = spy;
+      return spy;
+    });
+
+    bindNotifyLedgerHost(mocks[0]!.host);
+    bindNotifyLedgerHost(mocks[1]!.host);
+    bindNotifyLedgerHost(mocks[2]!.host);
+
+    // 首次 bind 注册一次（单例 handler）；后续 bind 只换 boundLedger 引用
+    expect(registerSpies[0]).toHaveBeenCalledTimes(1);
+    expect(registerSpies[1]).not.toHaveBeenCalled();
+    expect(registerSpies[2]).not.toHaveBeenCalled();
+  });
+
+  it("边沿分发到当前活跃实例：旧 mock 上的边沿事件驱动新 ledger 投递，旧实例零动作", () => {
+    const mock1 = makeLedgerHost();
+    bindNotifyLedgerHost(mock1.host);
+    const mock2 = makeLedgerHost();
+    bindNotifyLedgerHost(mock2.host);
+
+    // 活跃实例（mock2 的 ledger）入账 pending
+    const ledger = getBoundNotifyLedger();
+    expect(ledger).toBeDefined();
+    ledger!.record("sa-active", "content", { notifyId: "sa-active" });
+
+    // 旧 mock（mock1）上触发边沿——单例 handler 分发到 boundLedger（mock2）
+    fireSettled(mock1);
+    expect(mock2.sentMessages).toHaveLength(1);
+    expect(mock2.sentMessages[0]?.details).toMatchObject({ notifyId: "sa-active" });
+    // 旧实例无动作（disposed 短路语义：不会成为分发目标）
+    expect(mock1.sentMessages).toHaveLength(0);
+  });
+
+  it("活跃实例 dispose 后边沿静默（boundLedger 摘除 → 单例 handler 无分发目标）", () => {
+    const mock1 = makeLedgerHost();
+    bindNotifyLedgerHost(mock1.host);
+    getBoundNotifyLedger()!.dispose();
+
+    fireSettled(mock1);
+    expect(mock1.sentMessages).toHaveLength(0);
+  });
+
+  it("直调 createNotifyLedger 注册行为不变（默认注册 / 显式 registerSettledListener:false 跳过）", () => {
+    const mockDefault = makeLedgerHost();
+    const ledgerDefault = createNotifyLedger(mockDefault.host);
+    expect(mockDefault.settledHandlers).toHaveLength(1);
+    ledgerDefault.dispose();
+
+    const mockSkip = makeLedgerHost();
+    const ledgerSkip = createNotifyLedger(mockSkip.host, { registerSettledListener: false });
+    expect(mockSkip.settledHandlers).toHaveLength(0);
+    ledgerSkip.dispose();
+  });
+});
+
+// ─── 常量等值钉住（notify-ledger 与 notifier/渲染器共用字符串） ──
+
+describe("notify-ledger 常量锚", () => {
+  it("NOTIFY_CUSTOM_TYPE 与 notifier 送达 customType / ledger 回执扫描同源", async () => {
+    const notifierModule = await import("../notifier.ts");
+    // notifier 模块不再自带本地常量（单一常量源 = notify-ledger）；用运行时行为钉住：
+    // ledger 回执扫描匹配的 customType === notifier 送达消息的 customType。
+    const mock = makeLedgerHost();
+    const notifierHost: NotifierHost = {
+      sendMessage: (message) => {
+        mock.host.sendDelivery(message);
+      },
+      hasRunningBackground: () => false,
+      isIdle: () => true,
+    };
+    const ledger = bindNotifyLedgerHost(mock.host);
+    const notifier = createNotifier(notifierHost);
+    notifier.notify({ id: "sa-cst", status: "closed", agent: "w", result: "r", startedAt: 1, endedAt: 2 });
+    fireSettled(mock);
+    // 全链路销账成功 === 三处 customType 同一字符串（否则回执扫描不命中）
+    expect(ledgerDiff(mock)).toEqual(new Set());
+    expect(typeof notifierModule.createNotifier).toBe("function");
+    ledger.dispose();
+    _resetNotifyLedgerForTest();
+  });
+});