@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/notify-host.ts

@@ -0,0 +1,212 @@
+// [D4-① 通知簇职责轴] background 完成通知的 host 面——原 SubagentService 私有通知簇
+// （notifyComplete / notifyClosed / piAdapter / toNotifyRecord / emitPendingRegister /
+// emitPendingUnregister + notifier 实例持有）整体搬移至此（行为逐字节等价：搬移 +
+// 依赖注入，不重写逻辑）。变化轴：改通知文案 / dedup 身份 / 放行守卫 / pending 注册
+// 注销协议，只改本文件；Service 只保留编排与依赖注入（getPi / listRunning / isIdle）。
+
+import { displayAgentName } from "../shared/agent-ref.ts";
+import { snapshot } from "./execution-record.ts";
+import { hasIdleTimer } from "./lifecycle-manager.ts";
+import { hasLiveProcessHandle, isIdle, isResumable } from "./lifecycle-predicates.ts";
+import type { BgNotifier, NotifierHost } from "./notifier.ts";
+import { createNotifier } from "./notifier.ts";
+import type { BgNotifyRecord } from "./notifier.ts";
+import type { ExecutionRecord, RecordSnapshot } from "./types.ts";
+
+/** Pi ExtensionAPI 的最小接口（duck-typed）——原定义于 subagent-service.ts，随通知簇
+ *  （piAdapter / emitPending* 的依赖）搬移至此并导出（Service 的 session 注入参数仍引用）。
+ *  subagent-service 直接调 pi.sendMessage 发 background 完成通知（BgNotifier 滑动窗口合并），
+ *  不委托 pending-notifications EventBus 中继——后者只管 registry 不参与通知发送。 */
+export interface PiLike {
+  appendEntry(customType: string, data?: unknown): void;
+  events: { emit(channel: string, data: unknown): void };
+  sendMessage(
+    message: { customType: string; content: string; display: boolean; details?: unknown },
+    options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" }, // g4-allow: 类型注解——PiLike 接口形状（pi.sendMessage 签面子集），非投递调用
+  ): void;
+  /** 订阅 pi 事件（D8：notifier 的 settled 边沿订阅用 'agent_settled'）。
+   *  pi 0.84.1 的 on 返回 void 且无 off——退订语义由调用侧 disposed 标志包装兑现。
+   *  可选：旧测试 mock pi 可能未实现 on，缺省时 notifier 退化为内核退避路径。 */
+  on?(event: "agent_settled", handler: () => void): void;
+}
+
+/** NotifyHost 的依赖注入（Service 侧供给，全部惰性求值——pi/session 级状态运行时可变）。 */
+export interface NotifyHostDeps {
+  /** 当前 pi session handle（session_start 注入 / shutdown 置 null）。 */
+  getPi: () => PiLike | null;
+  /** store 的 running record 快照（piAdapter.hasRunningBackground 用）。 */
+  listRunning: () => RecordSnapshot[];
+  /** 主 agent isIdle 查询（ctx.isIdle，initSession 注入；未注入时 undefined）。 */
+  getIsIdle: () => (() => boolean) | undefined;
+}
+
+/** 通知簇 host 面（Service 经此消费；notifier 实例封装在内部不外露）。 */
+export interface NotifyHost {
+  /** background 完成回注（原 Service.notifyComplete）。 */
+  notifyComplete(record: ExecutionRecord): void;
+  /** [C-1] chatMode close 终态通知（原 Service.notifyClosed）。 */
+  notifyClosed(record: ExecutionRecord, emptyBody?: boolean): void;
+  /** pending-notifications 注册（原模块函数 emitPendingRegister，pi 经 deps 取）。 */
+  emitPendingRegister(id: string, name?: string): void;
+  /** pending-notifications 注销（原模块函数 emitPendingUnregister）。 */
+  emitPendingUnregister(id: string, reason: string): void;
+  /** dispose 的逆操作（initSession 复活，原 notifier.revive 委托）。 */
+  revive(): void;
+  /** dispose 前冲刷待发通知（原 notifier.flushPendingNotifications 委托）。 */
+  flushPendingNotifications(): void;
+  /** 丢弃 pending 通知（原 notifier.dispose 委托）。 */
+  dispose(): void;
+}
+
+/** pending-notifications 注册/注销 helper（避免重复代码）。
+ *  name 是 GUI pending 通知的显示名——取 basename 短名（displayAgentName），
+ *  完整路径仍走 record.agent（env 注入 / 持久化）。 */
+function emitPendingRegister(pi: PiLike | null, id: string, name?: string): void {
+  pi?.events.emit("pending:register", {
+    id,
+    type: "subagent",
+    name: name ? displayAgentName(name) : id,
+  });
+}
+
+function emitPendingUnregister(
+  pi: PiLike | null,
+  id: string,
+  reason: string,
+): void {
+  pi?.events.emit("pending:unregister", {
+    id,
+    reason,
+  });
+}
+
+/** 通知簇工厂：notifier 实例随本函数创建并封装（原 Service 构造器
+ *  `createNotifier(this.piAdapter())` 的等价形态）。 */
+export function createNotifyHost(deps: NotifyHostDeps): NotifyHost {
+  /** notifier 的 NotifierHost 适配器（绑定到 pi.sendMessage + store 查询）。 */
+  const piAdapter = (): NotifierHost => {
+    return {
+      sendMessage: (message, options) => {
+        deps.getPi()?.sendMessage(message, options);
+      },
+      hasRunningBackground: () => {
+        // [M3] 「在跑的 background 工作」= 有活进程且非等待续聊（idle timer armed）。
+        // v4 B-1 把旧 idle 折入 running 且 record 留 store：轮次完成的 chatMode record
+        // （timer armed、无在跑轮）与 one-shot 完成后等待 message 升级的 record 都不再计入。
+        // 旧判定 `mode === "background"` 对这两类恒 true → 轮次完成通知恒挂 60s 合并窗口
+        // （notifier MERGE_WINDOW_MS），主 agent 的续聊回复固定延迟 60s 送达，持续对话（G1）失效。
+        return deps.listRunning().some(
+          (r) => r.mode === "background" && hasLiveProcessHandle(r.id) && !hasIdleTimer(r.id),
+        );
+      },
+      isIdle: () => deps.getIsIdle()?.() ?? true,
+      // [must-fix #4 / D8] settled 边沿订阅，与 isIdle 同源（session_start 注入的 pi）。
+      // 只注入原生订阅能力；disposed 标志包装（退订语义）在 notifier 的 port 装配完成。
+      onAgentSettled: (handler) => { deps.getPi()?.on?.("agent_settled", handler); },
+    };
+  };
+
+  const notifier: BgNotifier = createNotifier(piAdapter());
+
+  /** record → BgNotifyRecord（notifier.notify 入参映射，内部不外露）。
+   *  v4 B-1：守卫放行 closed（终态，含 cancelled）、isIdle（对话模式轮次完成，notify 主 agent G1）
+   *  或 isResumable（running + 无活进程——SP-5 one-shot 成功完成 / MF-6 失败轮回退）。
+   *  正在执行（running + 活进程 + 非 timer-armed）返回 undefined（调用方 notifyComplete 跳过）。
+   *  SP-1: closed 统一终态，closedReason 由 BgNotifyRecord 携带。 */
+  const toNotifyRecord = (record: ExecutionRecord): BgNotifyRecord | undefined => {
+    const snap = snapshot(record);
+    const s = snap.status;
+    // [N1] isResumable 放行：SP-5 one-shot 成功完成后 finalizeRoundToIdle 把 record 回退
+    // running-resumable——进程已死且永不 arm idle timer（armIdleTimer 只在 agent_settled 的
+    // chatMode 分支调用），旧守卫（closed / isIdle only）对其恒拒绝 → 完成通知静默丢失，
+    // 而 one-shot 失败走 finalizeRecord 保持 closed 反而通知——与 tool 契约「runs once,
+    // notifies on completion」完全倒置。isResumable = running + 无活进程，恰为该完成态；
+    // 在跑轮的 record 有活进程，不会被误放行。
+    if (s !== "closed" && !isIdle(record) && !isResumable(record)) return undefined;
+    // closed → BgNotifyRecord.closed（cancelled 区分靠 closedReason）；chatMode 的 isIdle/
+    // isResumable（轮次完成或 MF-6 失败轮回退，对话可续）→ running（轮次完成）。
+    // isResumable 且非 chatMode（SP-5 one-shot 成功完成）→ closed：对主 agent 的语义是
+    // completed（非对话轮次），且只有 closed 分支文案携带 worktree patchFile 的 git apply
+    // 提示——one-shot worktree 模式的改动回收依赖该提示（running 分支文案不含 patchFile）。
+    const notifyStatus: BgNotifyRecord["status"] =
+      s === "closed" || !record.chatMode ? "closed" : "running";
+    return {
+      id: snap.id,
+      status: notifyStatus,
+      agent: snap.agent,
+      model: snap.model,
+      result: snap.result,
+      error: snap.error,
+      startedAt: snap.startedAt,
+      endedAt: snap.endedAt,
+      patchFile: record.patchFile,
+      // round 透传给 notifier 的 dedup key（对话模式按轮次去重，G1 决策 9）。
+      round: record.round,
+      // SP-1: closedReason 透传给 notifier（L2 原因，供通知文案按需展示）。
+      closedReason: record.closedReason,
+      // [wave2] chatMode 条件透传 sessionFile：通知末尾追加 Full transcript 指针行
+      //（增量语义的全文恢复通道，见 notifier.buildLlmContent）。one-shot（chatMode
+      // falsy）不透传——通知输出逐字节不变（G4），该条件由 message-close 测试的
+      // 必选用例锁死（漏加条件时 notifier 单测不红——notifier 层只见最终字段）。
+      sessionFile: record.chatMode ? record.sessionFile : undefined,
+    };
+  };
+
+  return {
+    /** background 完成回注（record → BgNotifyRecord 映射 + notifier.notify）。
+     *  正在执行（running + 活进程 + 非 timer-armed）静默跳过——notify 只对 closed（终态）、
+     *  isIdle（chatMode 轮次完成）或 isResumable（SP-5 one-shot 成功完成 / MF-6 失败轮回退）有意义。
+     *  SP-1: closed 统一终态（done/failed/crashed 合并），closedReason 携带 L2 原因。 */
+    notifyComplete(record: ExecutionRecord): void {
+      const notify = toNotifyRecord(record);
+      if (notify) notifier.notify(notify);
+    },
+
+    /** [C-1] chatMode close 终态通知（设计 D2：正文空/本轮增量 + sessionFile 指针行）。
+     *
+     *  与 notifyComplete 的差异只在 dedup 身份与轮次统计：终态通知必须与最后一轮的轮次通知
+     *  区分（轮次通知 key=`id:round`），否则同 key 被 60s dedup 吞——close 后父 agent 永远
+     *  收不到带指针行的终态通知（审查 C-1）。故 round 置 undefined（key 回退为裸 id），
+     *  轮数改经 totalRounds 进文案 "completed after N rounds."（C-2）。
+     *
+     *  仅 chatMode close 语义调用（closeChatIdle / closeAfterRoundSettled 终态化成功后）。
+     *  one-shot 显式拒绝（G4：one-shot close 路径现状无终态通知，字节不变）；cancel 走
+     *  cancelBackground 自己的 notifyComplete，不经本方法。幂等性：两条 close 路径均由
+     *  closeSubagent 的 status 分流守卫（closed 后幂等 no-op）/ CAS 抢锁保证只执行一次，
+     *  本方法自身不重复发送；迟到的轮次收尾 .then 通知与轮次通知同 key=`id:round`，
+     *  60s 窗内仍被吞，不构成第三条。 */
+    /** @param emptyBody true = 终态通知正文置空串（D2 路径②）。W16 P-1 修复后
+     *  closeChatIdle 的 doneResult.text 改用 record.result 保真（close 终态
+     *  subagent-record entry 的 result 不抹空轮终真实值），「正文空」不再由合成空
+     *  text 的副作用承载，改为显式参数——持久化 result 与通知正文两个关注点解耦。 */
+    notifyClosed(record: ExecutionRecord, emptyBody = false): void {
+      if (!record.chatMode) return;
+      const notify = toNotifyRecord(record);
+      if (!notify) return;
+      notify.round = undefined;
+      if (emptyBody) notify.result = "";
+      if (record.round != null) notify.totalRounds = record.round;
+      notifier.notify(notify);
+    },
+
+    emitPendingRegister(id: string, name?: string): void {
+      emitPendingRegister(deps.getPi(), id, name);
+    },
+
+    emitPendingUnregister(id: string, reason: string): void {
+      emitPendingUnregister(deps.getPi(), id, reason);
+    },
+
+    revive(): void {
+      notifier.revive();
+    },
+
+    flushPendingNotifications(): void {
+      notifier.flushPendingNotifications();
+    },
+
+    dispose(): void {
+      notifier.dispose();
+    },
+  };
+}

package/src/execution/notify-ledger.ts

@@ -21,10 +21,16 @@
 //      D5）；同一边沿的多条 pending 合并为一条注入
 //   ③ ack：回执判定成功（主 session 出现 notifyId 匹配的 subagent-bg-notify
 //      custom_message entry）后 appendEntry("subagent-bg-notify-ack")
-//   ④ replay：重启恢复扫描 ledger/ack 两列 entry 差集重放；重放按 notifyId 幂等去重
+//   ④ replay：重启恢复扫描 ledger/ack/abandoned entry 差集重放；重放按 notifyId 幂等去重
 //    （details 携带 notifyId，重复条目可识别）
 //
-// 通道分工（D4）：ledger/ack 用 plain appendEntry（type=custom 不进 LLM 上下文——
+// 止损上半场（T4③/PS-6）：④只保证「送达保证」下半场，回执确认不可达时（如送达
+// entry 被 compaction 清除）attempts 无上限 = 同一条通知每 120s 重复注入并
+// triggerTurn 无限唤醒 LLM。收敛：重投达 NOTIFY_REDELIVERY_MAX_ATTEMPTS 仍无回执 →
+// 写 abandoned 终态 entry 放弃（warn 含 subagent 标识与 subagents action:"list"
+// 手动核对指引），放弃号跨重启不复活（恢复扫描视同已销账）。
+//
+// 通道分工（D4）：ledger/ack/abandoned 用 plain appendEntry（type=custom 不进 LLM 上下文——
 // session-manager sessionEntryToContextMessages 对 custom 返回 []）；送达消息用
 // pi.sendMessage({triggerTurn:true})（custom_message 进上下文）。两通道不得混用。
 //
@@ -49,6 +55,11 @@ const logger = getLogger("subagents");
 export const NOTIFY_LEDGER_CUSTOM_TYPE = "subagent-bg-notify-ledger";
 /** 销账 entry customType（plain custom entry，不进 LLM 上下文）。 */
 export const NOTIFY_ACK_CUSTOM_TYPE = "subagent-bg-notify-ack";
+/**
+ * [T4③/PS-6] 放弃终态 entry customType（plain custom entry，不进 LLM 上下文）。
+ * 与 ack 同形同域：恢复/compaction 扫描把它视同已销账——放弃条目跨重启不复活。
+ */
+export const NOTIFY_ABANDONED_CUSTOM_TYPE = "subagent-bg-notify-abandoned";
 
 /**
  * 送达消息的 customType。notifier.ts / bg-notify-render / index.ts（messageRenderer
@@ -65,6 +76,14 @@ export const NOTIFY_CUSTOM_TYPE = "subagent-bg-notify";
  */
 export const NOTIFY_WATCHDOG_MS = 120_000;
 
+/**
+ * [T4③/PS-6] 单条通知投递尝试上限（attempts 字段含首次投递）：看门狗把 sent 超期
+ * 条目转回 pending 前，attempts 已达本上限 → 不再重投，转放弃终态（abandoned entry
+ * + warn 恢复指引）。被否语义：「重投无限但幂等」——幂等只防重复入账，不防重复
+ * 投递唤醒 LLM（设计 docs/design/subagent-core-unbounded-wait-audit.md §7.2 T4③）。
+ */
+export const NOTIFY_REDELIVERY_MAX_ATTEMPTS = 5;
+
 /**
  * U4 投递计数分桶（设计 §5 U4：分桶口径与 §2.2 三条丢失路径一一对应，回归时定位到
  * 具体环节）：
@@ -103,16 +122,22 @@ export interface NotifyAckEntryData {
   notifyId: string;
 }
 
+/** [T4③/PS-6] abandoned entry 的 data schema（v1，与 ack 同形——终态标记只需身份键）。 */
+export interface NotifyAbandonedEntryData {
+  v: 1;
+  notifyId: string;
+}
+
 /** ledger 依赖的宿主最小接口（index.ts session_start 装配；解耦便于测试）。 */
 export interface NotifyLedgerHost {
-  /** 写 plain custom entry（ledger/ack 通道；pi.appendEntry）。 */
+  /** 写 plain custom entry（ledger/ack/abandoned 通道；pi.appendEntry）。 */
   appendLedgerEntry(customType: string, data: unknown): void;
   /** 读当前 session 全部 entry（回执扫描 + 恢复扫描；ctx.sessionManager.getEntries()）。 */
   readSessionEntries(): readonly unknown[];
   /** 主 agent 是否空闲（发送前二次复查用；ctx.isIdle()）。 */
   isIdle(): boolean;
   /** 订阅 settled 边沿（pi.on("agent_settled")——无退订语义：createExtensionAPI.on
-   *  只 push 进 extension.handlers、无 off（pi 0.84.1 loader.js:209-214），由 ledger
+   *  只 push 进 extension.handlers、无 off（pi 0.84.4 loader.js:209-214），由 ledger
    *  disposed 标志包装）。注意与 ctx.events.on(channel) 消歧：后者走 eventBus、有
    *  trackEventBusSubscription 退订通路（loader.js:174、:338），语义不同。 */
   onAgentSettled(handler: () => void): void;
@@ -128,7 +153,7 @@ interface NotifyLedgerItem {
   recordedAt: number;
   /** 最近一次投递受理时刻；undefined = 尚未投递（pending，等下一边沿）。 */
   sentAt: number | undefined;
-  /** 投递尝试次数（看门狗重投计数，诊断用）。 */
+  /** 投递尝试次数（含首次；达 NOTIFY_REDELIVERY_MAX_ATTEMPTS 后超期即放弃，诊断用）。 */
   attempts: number;
 }
 
@@ -141,16 +166,24 @@ export interface NotifyLedger {
    *  同批 pending 合并单条送达（triggerTurn 直达）。 */
   attemptDeliver(): void;
   /** ③ 回执销账：扫 session entries，出现 notifyId 匹配的送达 custom_message entry
-   *  → appendEntry(ack) + 摘账（内存态不承担销账职责，权威 = 两列 entry 差集）。 */
+   *  → appendEntry(ack) + 摘账（内存态不承担销账职责，权威 = 多列 entry 差集）。 */
   checkReceipts(): void;
-  /** ④ 重启恢复：扫 ledger/ack 两列 entry 差集，未销账号重新入账并投递（已销账零重发）。
+  /** ④ 重启恢复：扫 ledger/ack/abandoned entry 差集，未销账且未放弃号重新入账并投递
+   *  （已销账零重发；已放弃号不复活——[T4③/PS-6] 止损终态跨重启生效）。
    *  @returns 重放条数。 */
   recoverFromSession(): number;
-  /** compaction 降级（P-B4 未验证）：检测 ledger/ack entry 被清除 → 按内存态补写。
+  /** compaction 降级（P-B4 未验证）：检测 ledger/ack/abandoned entry 被清除 → 按内存态补写。
    *  @returns 补写条数。 */
   compactionCheck(): number;
   /** 诊断/测试：pending（已记账未投递）条数。 */
   pendingCount(): number;
+  /**
+   * [T4④/PS-5] pending 只读快照（notifyId/content/record，副本非活引用）：
+   * 供 SubagentService.dispose 在「shutdown flush 被 isIdle 门拦」时把未投递
+   * pending 复写落盘（同一 ledger entry 通道，notifyId 幂等）供重启 replay。
+   * 消费侧配合面仅此只读方法——不改变 attemptDeliver/abandon 既有语义。
+   */
+  pendingEntries(): ReadonlyArray<{ notifyId: string; content: string; record: object }>;
   /** 诊断/测试：已投递待回执条数。 */
   waitingReceiptCount(): number;
   /** U4 诊断：三桶计数快照（副本；增量同时经 extensionLogger 通道落日志）。 */
@@ -166,13 +199,15 @@ function isPlainObject(v: unknown): v is Record<string, unknown> {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 
-/** 扫 ledger/ack 两列 plain custom entry（恢复 / compaction 检查共用）。 */
+/** 扫 ledger/ack/abandoned 三列 plain custom entry（恢复 / compaction 检查共用）。 */
 function scanSessionLedgerEntries(entries: readonly unknown[]): {
   ledger: Map<string, NotifyLedgerEntryData>;
   acked: Set<string>;
+  abandoned: Set<string>;
 } {
   const ledger = new Map<string, NotifyLedgerEntryData>();
   const acked = new Set<string>();
+  const abandoned = new Set<string>();
   for (const entry of entries) {
     if (!isPlainObject(entry) || entry["type"] !== "custom") continue;
     const customType = entry["customType"];
@@ -189,9 +224,11 @@ function scanSessionLedgerEntries(entries: readonly unknown[]): {
       }
     } else if (customType === NOTIFY_ACK_CUSTOM_TYPE) {
       acked.add(notifyId);
+    } else if (customType === NOTIFY_ABANDONED_CUSTOM_TYPE) {
+      abandoned.add(notifyId);
     }
   }
-  return { ledger, acked };
+  return { ledger, acked, abandoned };
 }
 
 /** 收集 wanted 集合中已送达（custom_message entry 出现）的 notifyId。
@@ -232,6 +269,11 @@ export function createNotifyLedger(
   const items = new Map<string, NotifyLedgerItem>();
   /** 已销账内存索引（notifyId 幂等判重 + compaction 补写源；权威 = ack entry 列）。 */
   const ackedIds = new Set<string>();
+  /**
+   * [T4③/PS-6] 已放弃终态内存索引（幂等判重 + compaction 补写源；权威 = abandoned
+   * entry 列）。与 ackedIds 同型：放弃是终态，同 notifyId 绝不再入账/重投/复活。
+   */
+  const abandonedIds = new Set<string>();
   /** U4 投递计数三桶（诊断快照源；增量经 emitBucketLog 落 extensionLogger）。 */
   const buckets: NotifyDeliveryBucketMetrics = {
     settleRejected: 0,
@@ -244,7 +286,8 @@ export function createNotifyLedger(
   const api: NotifyLedger = {
     record(notifyId, content, record): boolean {
       if (disposed) return false;
-      if (items.has(notifyId) || ackedIds.has(notifyId)) return false;
+      // 幂等去重：在账（pending/sent）/ 已销账 / 已放弃（[T4③] 终态绝不重发）→ false
+      if (items.has(notifyId) || ackedIds.has(notifyId) || abandonedIds.has(notifyId)) return false;
       host.appendLedgerEntry(NOTIFY_LEDGER_CUSTOM_TYPE, {
         v: 1,
         notifyId,
@@ -297,9 +340,13 @@ export function createNotifyLedger(
       if (disposed) return 0;
       const state = scanSessionLedgerEntries(host.readSessionEntries());
       for (const notifyId of state.acked) ackedIds.add(notifyId);
+      // [T4③/PS-6] 放弃终态跨重启生效：abandoned entry 视同已销账，下方差集重放跳过
+      // ——放弃号重启后不复活不重投（止损语义不以进程边界失效）。
+      for (const notifyId of state.abandoned) abandonedIds.add(notifyId);
       let replayed = 0;
       for (const entry of state.ledger.values()) {
         if (state.acked.has(entry.notifyId)) continue; // 已销账零重发
+        if (abandonedIds.has(entry.notifyId)) continue; // 已放弃不复活（止损终态）
         if (items.has(entry.notifyId) || ackedIds.has(entry.notifyId)) continue; // 幂等
         items.set(entry.notifyId, {
           ...entry,
@@ -345,6 +392,14 @@ export function createNotifyLedger(
           rewritten += 1;
         }
       }
+      // [T4③/PS-6] 放弃终态同享补写：内存是权威，compaction 清掉 abandoned entry 后
+      // 不补写会让放弃号在下次重启按差集复活（重投重启）。
+      for (const notifyId of abandonedIds) {
+        if (!state.abandoned.has(notifyId)) {
+          host.appendLedgerEntry(NOTIFY_ABANDONED_CUSTOM_TYPE, { v: 1, notifyId } satisfies NotifyAbandonedEntryData);
+          rewritten += 1;
+        }
+      }
       return rewritten;
     },
 
@@ -356,6 +411,16 @@ export function createNotifyLedger(
       return n;
     },
 
+    pendingEntries(): ReadonlyArray<{ notifyId: string; content: string; record: object }> {
+      const out: Array<{ notifyId: string; content: string; record: object }> = [];
+      for (const item of items.values()) {
+        if (item.sentAt !== undefined) continue;
+        // 逐条浅拷贝：消费方（dispose 落盘复写）不得持有内部可变态。
+        out.push({ notifyId: item.notifyId, content: item.content, record: { ...item.record } });
+      }
+      return out;
+    },
+
     waitingReceiptCount(): number {
       let n = 0;
       for (const item of items.values()) {
@@ -408,6 +473,35 @@ export function createNotifyLedger(
     };
   }
 
+  /** [T4③/PS-6] 放弃终态：appendEntry(abandoned) 落盘终态标记（重启恢复不复活）+
+   *  warn 恢复指引。放弃后账面摘除（pending/waiting 计数归零、看门狗可停），同
+   *  notifyId 被 record 幂等拒绝——「确认不可达」的止损上半场；通知内容本身仍可
+   *  经 subagents action:"list" 手动核对（账本 entry 与 result 落盘不受影响）。
+   *  放弃不计入 watchdogReplays 桶（该桶口径 = 实际发生重投的条数）。 */
+  function abandonItem(item: NotifyLedgerItem): void {
+    host.appendLedgerEntry(NOTIFY_ABANDONED_CUSTOM_TYPE, { v: 1, notifyId: item.notifyId } satisfies NotifyAbandonedEntryData);
+    items.delete(item.notifyId);
+    abandonedIds.add(item.notifyId);
+    // 消息含 subagent 标识与恢复指引（S-E 验收面）；notifyId/attempts 等动态值按
+    // D4 约定放 data 参数（msg 近固定 key，限流命中面）。
+    logger.warn(
+      `Subagent "${itemLabel(item)}" notification abandoned - no receipt after ` +
+        `${NOTIFY_REDELIVERY_MAX_ATTEMPTS} delivery attempts; verify manually via subagents action:"list"`,
+      { notifyId: item.notifyId, attempts: item.attempts },
+    );
+    maybeStopWatchdog();
+  }
+
+  /** 放弃 warn 的 subagent 标识：优先 record.agent（人可读）；record 形态异常时
+   *  （ledger 对 record 不透明，见 NotifyLedgerEntryData）退回 notifyId（仍可检索）。 */
+  function itemLabel(item: NotifyLedgerItem): string {
+    if (isPlainObject(item.record)) {
+      const agent = item.record["agent"];
+      if (typeof agent === "string" && agent.length > 0) return agent;
+    }
+    return item.notifyId;
+  }
+
   function ensureWatchdog(): void {
     if (watchdogTimer !== undefined || disposed) return;
     // 看门狗（D5 ②兜底触发面）：回执检查 + 超时重投 + pending 补投。
@@ -418,12 +512,19 @@ export function createNotifyLedger(
       // attemptDeliver 即重投——正常时序 settled 边沿早已销账，只有消息真丢失才到这
       const cutoff = Date.now() - NOTIFY_WATCHDOG_MS;
       let timedOut = 0;
+      // [T4③/PS-6] 止损：attempts 已达上限仍超期 = 确认不可达 → 放弃转终态，
+      // 不再重投（同一条完成通知不无限重复注入唤醒 LLM）。
+      const givenUp: NotifyLedgerItem[] = [];
       for (const item of items.values()) {
-        if (item.sentAt !== undefined && item.sentAt <= cutoff) {
-          item.sentAt = undefined;
-          timedOut += 1;
+        if (item.sentAt === undefined || item.sentAt > cutoff) continue;
+        if (item.attempts >= NOTIFY_REDELIVERY_MAX_ATTEMPTS) {
+          givenUp.push(item);
+          continue;
         }
+        item.sentAt = undefined;
+        timedOut += 1;
       }
+      for (const item of givenUp) abandonItem(item);
       if (timedOut > 0) {
         // U4 ①watchdogReplays 桶：busy 窗口滞留兜底的重投条数（同一消息反复超时累计）
         buckets.watchdogReplays += timedOut;
@@ -467,7 +568,7 @@ export function createNotifyLedger(
   // （P-B0 相邻机制已源码级锚定，agent-session.js:327-331，PS-07）。
   // [MF-5] registerSettledListener=false（bind 路径）时跳过注册：pi.on("agent_settled")
   // 无退订语义——createExtensionAPI.on 只 push 进 extension.handlers、无 off
-  //（pi 0.84.1 dist/core/extensions/loader.js:209-214）。注意消歧两类订阅面：此处的
+  //（pi 0.84.4 dist/core/extensions/loader.js:209-214）。注意消歧两类订阅面：此处的
   // pi.on 是生命周期事件订阅（无退订）；ctx.events.on(channel) 走 eventBus、有
   // trackEventBusSubscription 退订通路（loader.js:174、:338）——勿按后者的可退订
   // 语义「修复」此处。per-bind 注册会随 session 切换累积死 handler
@@ -543,7 +644,7 @@ function settledEdgeDispatch(): void {
 /**
  * session_start 装配（index.ts）：构造新 ledger 并绑定为模块级单例（notifier.notify
  * 经 getBoundNotifyLedger 消费）。重复 bind（/resume /fork /new 的 session_start）
- * 替换旧实例——内存态清零符合「内存不承担销账职责」，权威 = entry 两列差集
+ * 替换旧实例——内存态清零符合「内存不承担销账职责」，权威 = entry 多列差集
  * （调用方随后 recoverFromSession 重建）。
  *
  * [MF-5] 监听单例化：首次 bind 经当次 host 注册模块级单例 handler

package/src/execution/record-entry.ts

@@ -21,7 +21,9 @@ import type {
 } from "./types.ts";
 
 /** 自描述 record entry 的 customType。写点字面量与本常量的等值由
- *  __tests__/record-store.test.ts 断言钉住（消费方引用本常量，勿用裸字符串）。 */
+ *  __tests__/record-store.test.ts 断言钉住（消费方引用本常量，勿用裸字符串）。
+ *
+ * @experimental execution 运行时面（U10① D6）：一个 minor 周期内允许签名微调。 */
 export const SUBAGENT_RECORD_CUSTOM_TYPE = "subagent-record";
 
 /**
@@ -34,6 +36,8 @@ export const SUBAGENT_RECORD_CUSTOM_TYPE = "subagent-record";
  *   - worktreeHandle：不可 JSON 序列化的运行时句柄（布尔投影 worktree 保留）。
  *
  * undefined 字段经 JSON.stringify 自然缺省（与 SubagentRecord 重建侧语义一致）。
+ *
+ * @experimental execution 运行时面（U10① D6）：一个 minor 周期内允许签名微调。
  */
 export interface SubagentRecordEntryData {
   /** schema 版本（W16 起 v1）。消费方按 v 判别解析，不认识的版本跳过而非猜测。 */
@@ -95,7 +99,9 @@ export interface SubagentRecordEntryData {
   engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
 }
 
-/** SubagentRecord → 自描述 entry data（快照投影，不 mutate 源）。 */
+/** SubagentRecord → 自描述 entry data（快照投影，不 mutate 源）。
+ *
+ * @experimental execution 运行时面（U10① D6）：一个 minor 周期内允许签名微调。 */
 export function toSubagentRecordEntry(record: SubagentRecord): SubagentRecordEntryData {
   return {
     v: 1,