@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/execution/finalize-record.ts

@@ -5,11 +5,11 @@
 // D-017 时序：collectPatch → completeRecord → archive → cleanup(finalized+worktree+
 // aliveMarker+pending注销) → manifest(最后 best-effort)。
 //
-// [Critical #1 / PR #85] cleanup 全部在 manifest 写之前执行——manifest 是诊断辅助
-//（orphan recovery），写失败仅记录不阻断。旧实现 Step 2.5 throw 会跳过 Step 3 cleanup，
-// 导致磁盘满/权限错时 worktree 泄漏 + finalized marker 不写 + alive marker 残留 +
-// pending 记账错乱。现 manifest 写移到 Step 4（最后），best-effort（console.error +
-// appendEntry，不 throw）。
+// [Critical #1 / PR #85] cleanup 全部在 manifest 写之前执行——manifest 是 sa- id 反查
+// 索引（最新已知快照），非正确性依赖，写失败仅记录不阻断。旧实现 Step 2.5 throw 会跳过
+// Step 3 cleanup，导致磁盘满/权限错时 worktree 泄漏 + finalized marker 不写 + alive
+// marker 残留 + pending 记账错乱。现 manifest 写移到 Step 4（最后），best-effort
+//（console.error + appendEntry，不 throw）。
 //
 // B9 兜底：completeRecord/archive 抛错→后续 cleanup/manifest 仍执行。
 
@@ -86,115 +86,106 @@ function findSessionFileByRecordIdentity(
 }
 
 /**
- * 时序收尾（D-017）。步骤 0→4 全部 best-effort 互不阻断（除 manifest 外都幂等）。
+ * [T1/PS-9] Step 序言：sessionFile 缺失时按 record 身份在 sessionDir 反查回填。
  *
- * [Critical #1] Step 3 cleanup 全部在 Step 4 manifest 之前——manifest 写失败仅 console.error +
- * appendEntry，不 throw 不跳过 cleanup。task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord
- * 补字段），manifestToSubagent 投影真实值而非硬编码空串。
+ * 放在一切步骤前，让 archive 投影 / Step 3 marker / Step 4 manifest 统一受益。
+ * RC-1（握手失败）+ LC-4（收尾反查未命中）的残余形态下，磁盘上 session 文件仍可能
+ * 真实存在（identity 携带 record.id）——反查命中则 tombstone/finalized sidecar 与
+ * removeAliveMarker 有了依据，终态原因不再丢失、alive marker 不再残留；未命中则
+ * 保持旧行为（best-effort 跳过）。
  */
-export async function doFinalizeRecord(
-  deps: FinalizeDeps,
-  record: ExecutionRecord,
-  result: AgentResult,
-  status: "closed",
-  closedReason?: ClosedReason,
-): Promise<void> {
-  // [T1/PS-9] sessionFile 缺失时 sessionDir 反查（放在一切步骤前，让 archive 投影 /
-  // Step 3 marker / Step 4 manifest 统一受益）。RC-1（握手失败）+ LC-4（收尾反查未命中）
-  // 的残余形态下，磁盘上 session 文件仍可能真实存在（identity 携带 record.id）——
-  // 反查命中则 tombstone/finalized sidecar 与 removeAliveMarker 有了依据，终态原因
-  // 不再丢失、alive marker 不再残留；未命中则保持旧行为（best-effort 跳过）。
-  if (!record.sessionFile && deps.sessionDir) {
-    const resolved = findSessionFileByRecordIdentity(deps.sessionDir, record.id);
-    if (resolved) {
-      record.sessionFile = resolved;
-      logger.warn(
-        `[subagent] finalizeRecord: sessionFile was missing, resolved via sessionDir identity lookup: ${resolved}`,
-      );
-    }
+function resolveMissingSessionFile(deps: FinalizeDeps, record: ExecutionRecord): void {
+  if (record.sessionFile || !deps.sessionDir) return;
+  const resolved = findSessionFileByRecordIdentity(deps.sessionDir, record.id);
+  if (resolved) {
+    record.sessionFile = resolved;
+    logger.warn(
+      `[subagent] finalizeRecord: sessionFile was missing, resolved via sessionDir identity lookup: ${resolved}`,
+    );
   }
+}
 
-  // ── Step 0: collectPatch（best-effort）──
-  // [MF#3] patchFile 写到 worktree 之外（sessionsDir/<branch>.patch），避免被 cleanup 删除；
-  //        路径回填 record.patchFile，供调用方（tool result / /subagents list）应用。
-  if (record.worktreeHandle) {
-    try {
-      const sessionsDir = getSubagentSessionDir(
-        deps.modelService.getAgentDir(),
-        record.worktreeHandle.mainCwd,
-      );
-      fs.mkdirSync(sessionsDir, { recursive: true });
-      const patchFile = path.join(sessionsDir, `${record.worktreeHandle.branch}.patch`);
-      const patch = await deps.worktreeManager.collectPatch(record.worktreeHandle, patchFile);
-      if (patch.written) record.patchFile = patchFile;
-    } catch (pe: unknown) {
-      bestEffort(pe, "collectPatch (finalizeRecord Step0)");
-    }
+/**
+ * Step 0: collectPatch（best-effort，仅 worktree 绑定时执行）。
+ * [MF#3] patchFile 写到 worktree 之外（sessionsDir/<branch>.patch），避免被 cleanup 删除；
+ * 路径回填 record.patchFile，供调用方（tool result / /subagents list）应用。
+ */
+async function collectPatchIfWorktree(deps: FinalizeDeps, record: ExecutionRecord): Promise<void> {
+  if (!record.worktreeHandle) return;
+  try {
+    const sessionsDir = getSubagentSessionDir(
+      deps.modelService.getAgentDir(),
+      record.worktreeHandle.mainCwd,
+    );
+    fs.mkdirSync(sessionsDir, { recursive: true });
+    const patchFile = path.join(sessionsDir, `${record.worktreeHandle.branch}.patch`);
+    const patch = await deps.worktreeManager.collectPatch(record.worktreeHandle, patchFile);
+    if (patch.written) record.patchFile = patchFile;
+  } catch (pe: unknown) {
+    bestEffort(pe, "collectPatch (finalizeRecord Step0)");
   }
+}
 
-  // ── Step 1: completeRecord（B9: 抛错→后续仍执行）──
+/**
+ * Step 3a: finalized/tombstone sidecar（best-effort 幂等，仅 sessionFile 存在时执行）。
+ * MF-1 fix / v4 B-1: cancelled（closedReason='cancelled'）写 tombstone 而非 finalized，
+ * 防重建丢失 cancelled；其余 reason 写 finalized sidecar（真实 reason 进 sidecar 内容，
+ * 磁盘重建用它还原 closedReason，不再一律硬编码 gc）。
+ */
+function writeFinalizedOrTombstone(record: ExecutionRecord, closedReason: ClosedReason | undefined): void {
+  if (!record.sessionFile) return;
   try {
-    completeRecord(record, result, status, closedReason);
+    if (closedReason === "cancelled") {
+      writeCancelledTombstone(record.sessionFile, {
+        id: record.id,
+        status: "cancelled",
+        agent: record.agent,
+        startedAt: record.startedAt,
+        endedAt: record.endedAt ?? Date.now(),
+      });
+    } else {
+      writeFinalized(record.sessionFile, closedReason);
+    }
   } catch (err) {
-    bestEffort(err, "completeRecord (finalizeRecord B9)", "error");
+    bestEffort(err, "writeFinalized/tombstone (finalizeRecord Step3)");
   }
+}
 
-  // ── Step 2: archive（B9: 抛错→后续仍执行）──
+/**
+ * Step 3b: worktree cleanup（best-effort 幂等，仅 worktree 绑定时执行）。
+ * [Critical] 绝不能因 manifest 写失败而跳过（否则 worktree 泄漏）。
+ */
+async function cleanupWorktreeIfBound(deps: FinalizeDeps, record: ExecutionRecord): Promise<void> {
+  if (!record.worktreeHandle) return;
   try {
-    deps.store.archive(record);
+    await deps.worktreeManager.cleanup(record.worktreeHandle);
   } catch (err) {
-    bestEffort(err, "store.archive (finalizeRecord B9)", "error");
+    bestEffort(err, "worktree cleanup (finalizeRecord Step3)");
   }
+}
 
-  // ── Step 3: finalized + cleanup + aliveMarker + pending注销（全部先执行，幂等）──
-  // [Critical] 清理必须在 manifest 写入之前：worktree cleanup / finalized marker / aliveMarker
-  //   都是幂等且不可跳过的副作用。绝不能因 manifest 写失败而跳过 worktree cleanup
-  //   （否则 worktree 泄漏）。各件独立 try/catch，互不阻断。
-  if (record.sessionFile) {
-    try {
-      // MF-1 fix / v4 B-1: cancelled（closedReason='cancelled'）写 tombstone 而非 finalized，防重建丢失 cancelled
-      if (closedReason === "cancelled") {
-        writeCancelledTombstone(record.sessionFile, {
-          id: record.id,
-          status: "cancelled",
-          agent: record.agent,
-          startedAt: record.startedAt,
-          endedAt: record.endedAt ?? Date.now(),
-        });
-      } else {
-        // [v8.5 A2] 真实 reason 写入 sidecar 内容（旧格式是空文件）：磁盘重建时用它
-        // 还原 closedReason，不再一律硬编码 gc。cancelled 之外的全部原因（gc /
-        // user-close / parent-*）都经此路径持久化。
-        writeFinalized(record.sessionFile, closedReason);
-      }
-    } catch (err) {
-      bestEffort(err, "writeFinalized/tombstone (finalizeRecord Step3)");
-    }
-  }
-  if (record.worktreeHandle) {
-    try {
-      await deps.worktreeManager.cleanup(record.worktreeHandle);
-    } catch (err) {
-      bestEffort(err, "worktree cleanup (finalizeRecord Step3)");
-    }
-  }
-  if (record.sessionFile) {
-    try {
-      removeAliveMarker(record.sessionFile);
-    } catch (err) {
-      bestEffort(err, "removeAliveMarker (finalizeRecord Step3)");
-    }
+/** Step 3c: 删 .alive marker（best-effort 幂等，仅 sessionFile 存在时执行）。 */
+function removeAliveMarkerIfPresent(record: ExecutionRecord): void {
+  if (!record.sessionFile) return;
+  try {
+    removeAliveMarker(record.sessionFile);
+  } catch (err) {
+    bestEffort(err, "removeAliveMarker (finalizeRecord Step3)");
   }
+}
 
-  // pending-notifications：终态注销（只记 registry 状态，通知由 BgNotifier 发）
-  deps.emitUnregister(record.id, status);
-
-  // ── Step 4 (last): manifest 持久化（best-effort，不阻断、不 throw）──
-  // [Critical #1] manifest 是诊断辅助（orphan recovery），不是正确性依赖。写失败时
-  //   仅记录（console.error + appendEntry），绝不让 manifest 写失败跳过上面的 worktree
-  //   cleanup 或抛出打断 finalize 链。旧实现 Step 2.5 throw 会跳过 Step 3 cleanup。
-  //   task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord 补字段），
-  //   manifestToSubagent 投影时用真实值而非硬编码空串。
+/**
+ * Step 4 (last): manifest 持久化（best-effort，不阻断、不 throw）。
+ *
+ * [Critical #1] manifest 是 sa- id 反查索引（最新已知快照），不是正确性依赖。本步骤
+ * 写终态快照；sync 批成功成员不经此处——落标出口（subagent-service
+ * appendBatchFinalizedEntry）已先行补写，message upgrade 到终态时被本步骤原子
+ * 覆盖。写失败时仅记录（console.error + appendEntry），绝不让 manifest 写失败
+ * 跳过 Step 3 cleanup 或抛出打断 finalize 链。旧实现 Step 2.5 throw 会
+ * 跳过 Step 3 cleanup。task/slug/model 从 ExecutionRecord 抓取（配合
+ * ManifestRecord 补字段），manifestToSubagent 投影时用真实值而非硬编码空串。
+ */
+async function writeManifestBestEffort(deps: FinalizeDeps, record: ExecutionRecord): Promise<void> {
   try {
     await deps.manifestStore.writeManifest({
       id: record.id,
@@ -220,6 +211,55 @@ export async function doFinalizeRecord(
   }
 }
 
+/**
+ * 时序收尾（D-017）。步骤 0→4 全部 best-effort 互不阻断（除 manifest 外都幂等）。
+ *
+ * [Critical #1] Step 3 cleanup 全部在 Step 4 manifest 之前——manifest 写失败仅 console.error +
+ * appendEntry，不 throw 不跳过 cleanup。task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord
+ * 补字段），manifestToSubagent 投影真实值而非硬编码空串。
+ */
+export async function doFinalizeRecord(
+  deps: FinalizeDeps,
+  record: ExecutionRecord,
+  result: AgentResult,
+  status: "closed",
+  closedReason?: ClosedReason,
+): Promise<void> {
+  // [T1/PS-9] sessionFile 缺失时 sessionDir 反查（序言，先于一切步骤）。
+  resolveMissingSessionFile(deps, record);
+
+  // ── Step 0: collectPatch（best-effort）──
+  await collectPatchIfWorktree(deps, record);
+
+  // ── Step 1: completeRecord（B9: 抛错→后续仍执行）──
+  try {
+    completeRecord(record, result, status, closedReason);
+  } catch (err) {
+    bestEffort(err, "completeRecord (finalizeRecord B9)", "error");
+  }
+
+  // ── Step 2: archive（B9: 抛错→后续仍执行）──
+  try {
+    deps.store.archive(record);
+  } catch (err) {
+    bestEffort(err, "store.archive (finalizeRecord B9)", "error");
+  }
+
+  // ── Step 3: finalized + cleanup + aliveMarker（全部先执行，幂等）──
+  // [Critical] 清理必须在 manifest 写入之前：worktree cleanup / finalized marker / aliveMarker
+  //   都是幂等且不可跳过的副作用。绝不能因 manifest 写失败而跳过 worktree cleanup
+  //   （否则 worktree 泄漏）。各件独立 try/catch，互不阻断。
+  writeFinalizedOrTombstone(record, closedReason);
+  await cleanupWorktreeIfBound(deps, record);
+  removeAliveMarkerIfPresent(record);
+
+  // pending-notifications：终态注销（只记 registry 状态，通知由 BgNotifier 发）
+  deps.emitUnregister(record.id, status);
+
+  // ── Step 4 (last): manifest 持久化（best-effort，不阻断、不 throw）──
+  await writeManifestBestEffort(deps, record);
+}
+
 /**
  * 对话模式轮次完成收尾：record 进 idle 态（非终态化，等待续聊）。
  *
@@ -227,7 +267,9 @@ export async function doFinalizeRecord(
  *   - 不调 completeRecord（record 不冻结，保留 turns[] 等运行时状态供续聊累积）
  *   - 不调 store.archive（record 留内存，getMutable 可查、list 可见）
  *   - 不 cleanup worktree（保留对话模式工作目录）
- *   - 不写 manifest（idle 非终态，manifest 是终态诊断辅助）
+ *   - 不写 manifest：轮终回 running-resumable 非终态化，本方法无终态快照可写——
+ *     manifest 是 sa- id 反查索引（最新已知快照），sync 批成员的先行快照由落标出口
+ *     补写（subagent-service appendBatchFinalizedEntry），此处不重复
  *   - 删 .alive marker（进程已 SIGTERM 回收，不再是活进程）
  *   - emitUnregister（进程已死，从 pending 活跃后代差集移除；record 留内存不 archive）
  *

package/src/execution/idle-gc.ts

@@ -4,9 +4,12 @@
  * 启动幂等由调用方（service.startGcTimer）守卫；返回 stop 函数供 dispose 清理。
  */
 import { getLogger } from "../core/logger.ts";
+import { getEngineDataDir } from "./engine/common/data-dir.ts";
+import { releasePoolRef } from "./engine/common/pool-manager.ts";
 import { bestEffort } from "./best-effort.ts";
 import { isResumable } from "./lifecycle-predicates.ts";
 import type { RecordStore } from "./record-store.ts";
+import type { ExecutionRecord } from "./types.ts";
 
 const logger = getLogger("subagents");
 
@@ -24,6 +27,15 @@ const MS_PER_DAY = 24 * 60 * 60 * 1000;
  * 启动 idle record GC 定时器，返回 stop 函数（清理 interval；幂等）。
  * 每个扫描周期：对 store 内全部 active record 中 resumable 且带 idleSince 的，
  * 超过 IDLE_TTL_MS 的归档（archive 单条失败不阻断其余，bestEffort 留痕）。
+ *
+ * [D8 池引用计数接线] 归档时同步释放该 record 的引擎池引用（releasePoolRef：
+ * journal 跟随 record 删除 + refs 移除 + 归零删池内原生状态）。锚点选在 30 天 TTL
+ * 而非 dispose/archive 类时机，依据：idle record 30 天后引擎侧不会再有活动（archive
+ * 后 message 续聊走 fork-from/新 start，不触原引擎），且与 pi 域 session 文件 30 天
+ * TTL（session-file-gc 同期删①级读源）形成两引擎对称衰减；disposeAllRecords/close
+ * 类时机 record 数据仍保留（可 resurrect / GUI 历史重建可见），journal（②级数据源）
+ * 不能删——那是 record 主数据死亡（主 session 文件被 pi 侧删除，core 无触发点）才有
+ * 的处置，由 cleanupExpiredPoolRefs 的 TTL 兜底覆盖。
  */
 export function startIdleGc(store: RecordStore): () => void {
   const timer = setInterval(() => {
@@ -38,6 +50,7 @@ export function startIdleGc(store: RecordStore): () => void {
           } catch (err) {
             bestEffort(err, `GC archive record ${record.id}`);
           }
+          releaseEnginePoolRef(record);
         }
       }
     }
@@ -45,3 +58,18 @@ export function startIdleGc(store: RecordStore): () => void {
   timer.unref?.();
   return () => clearInterval(timer);
 }
+
+/**
+ * 释放 record 的引擎池引用（best-effort）。无 engineHandle（存量 record / 非引擎
+ * 路径）时 no-op；engine 缺省投影 'pi'（与读侧存量 entry 零迁移口径一致）。
+ */
+function releaseEnginePoolRef(record: ExecutionRecord): void {
+  const poolKey = record.engineHandle?.poolKey;
+  if (poolKey === undefined) return;
+  const engineId = record.engine ?? "pi";
+  try {
+    releasePoolRef(getEngineDataDir(), engineId, poolKey, record.id);
+  } catch (err) {
+    bestEffort(err, `GC release pool ref for record ${record.id}`);
+  }
+}

package/src/execution/lifecycle-predicates.ts

@@ -20,7 +20,7 @@
 // 故 isIdle 在这两个检查点恒为 true——notify 守卫与 early-return 判据可靠。
 
 import { hasIdleTimer } from "./lifecycle-manager.ts";
-import { getChildByRecord } from "./session-runner.ts";
+import { getChildByRecord } from "./engine/engines/pi/session-runner.ts";
 import type { ExecutionRecord } from "./types.ts";
 
 /**

package/src/execution/notifier.ts

@@ -1,6 +1,7 @@
 // src/execution/notifier.ts
 //
-// Background 完成回注主对话。sync 不用（调用方还在 await，结果直接返回）。
+// Background 完成回注主对话。collect:"sync" 的批通知不经单条 notify() 生命周期，
+// 由 collect-coordinator 合批后调本文件 notifyBatch 投递（成员结果不直接返回调用方）。
 //
 // 职责（U2 后）：
 //   - buildLlmContent：格式化通知文案（本文件唯一逻辑职责）
@@ -9,6 +10,7 @@
 //     notify-ledger.ts）；未装配时退回投递内核路径（createDelivery 经通知域窄端口
 //     NotifyDomainPorts 注入——core 依赖闭包不含 session-delivery，见 core/notify-ports.ts；
 //     合并窗口 / 去重 / 退避 / flush 委托内核，旧装配 / 无 ledger 测试兼容）
+//   - notifyBatch / buildBatchLlmContent / computeBatchBudget：sync 批通知三件套（U3/U4）
 //
 // 投递通道（D5 单通道化）：ledger 路径经 courier 在 settled 边沿直达
 // pi.sendMessage({triggerTurn:true})；内核路径的 port.send 同样只传
@@ -17,6 +19,8 @@
 // 设计 D5 实测证伪）；busy 场景由 ledger（settled 边沿 + isIdle 二次复查）或内核
 // settled 订阅驱动在空闲边沿投递。
 
+import { createHash } from "node:crypto";
+
 import { getLogger } from "../core/logger.ts";
 import { getNotifyDomainPorts, type DeliveryHandle, type DeliveryPort } from "../core/notify-ports.ts";
 
@@ -104,6 +108,169 @@ export interface NotifierHost {
   onAgentSettled?(handler: () => void): void;
 }
 
+/** sync 批通知幂等键前缀（subagent-sync-collect 设计 §3.1.3 批身份）。 */
+const BATCH_NOTIFY_ID_PREFIX = "sync-batch:";
+
+/**
+ * sync 批通知 notifyId：`sync-batch:<sha1(sorted member ids)>`。
+ *
+ * 成员集身份（D2 隐式批）：字典序排序后 sha1——同成员集不同登记顺序同 hash（重启
+ * 重建批 / E1 补发凭此与账本原条目对齐，幂等去重）；不同成员集必异 hash（跨批不互吞）。
+ * 成员 id 为 sa-xxx 格式无分隔歧义，join(",") 仅作边界防御。
+ */
+export function buildBatchNotifyId(memberIds: readonly string[]): string {
+  const digest = createHash("sha1")
+    .update([...memberIds].sort().join(","))
+    .digest("hex");
+  return `${BATCH_NOTIFY_ID_PREFIX}${digest}`;
+}
+
+// ─── U4 预算截断 + 指针（设计 §3.1.2 两段式预算，确定性统一收紧）───
+
+/** sync 批预算参数（config collectSync 节语义）。U4 以设计默认值锁规格；
+ * config 热读（flush 时读值）需 service 传参接线，不在本函数内自行读 config。 */
+export interface BatchBudgetParams {
+  /** 单条目正文上限（第一段截断）。 */
+  perItemChars: number;
+  /** 全批正文中量预算（第二段收紧触发阈值）。 */
+  totalChars: number;
+}
+
+/** 设计默认预算（§3.1.3 config 示例值）。 */
+const DEFAULT_BATCH_BUDGET: BatchBudgetParams = { perItemChars: 4000, totalChars: 24000 };
+
+/** 预算计划（computeBatchBudget 输出，纯数据）。 */
+export interface BatchBudgetPlan {
+  /** ② 总量再压缩是否触发（Σ per-item 截断后正文 > totalChars）。 */
+  tightened: boolean;
+  /** 每条目正文有效上限：未收紧 = perItemChars（兼作第一段截断上限）；纯清单退化 = 0。 */
+  effectivePerItem: number;
+  /** 纯清单退化（floor(totalChars/n) < 200 → 条目只剩头行 + 指针行，正文 0 字符）。 */
+  listOnly: boolean;
+}
+
+/** 绝对下限（设计 §3.1.2）：预算折算低于它时放弃正文，条目退化为「头行 + 指针行」。 */
+const LIST_ONLY_FLOOR = 200;
+
+/**
+ * 两段式批预算计划（纯函数，规格测试 collect-budget.test.ts 锁定）。
+ *
+ * ① per-item：每条目正文 ≤ perItemChars；② 总量：Σ(截断后) > totalChars 时
+ * effectivePerItem = clamp(floor(totalChars / n), 200, perItemChars) 统一收紧
+ * （n = 成员数）。刻意放弃按剩余预算的瀑布分配（非确定、依赖条目顺序），
+ * 统一收紧换确定性；收紧后 Σ ≤ n × floor(totalChars/n) ≤ totalChars 恒回到预算内。
+ * 未触发收紧时 effectivePerItem = perItemChars（同时承担第一段截断上限）。
+ */
+export function computeBatchBudget(
+  bodyLengths: readonly number[],
+  perItemChars: number,
+  totalChars: number,
+): BatchBudgetPlan {
+  const n = bodyLengths.length;
+  const sumAfterPerItem = bodyLengths.reduce((sum, len) => sum + Math.min(len, perItemChars), 0);
+  if (n === 0 || sumAfterPerItem <= totalChars) {
+    return { tightened: false, effectivePerItem: perItemChars, listOnly: false };
+  }
+  const tight = Math.floor(totalChars / n);
+  if (tight < LIST_ONLY_FLOOR) {
+    return { tightened: true, effectivePerItem: 0, listOnly: true };
+  }
+  return { tightened: true, effectivePerItem: Math.min(tight, perItemChars), listOnly: false };
+}
+
+/** 千位分隔（对齐设计样例 11,234；手写正则零 ICU 依赖）。 */
+function formatChars(n: number): string {
+  return n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+
+/**
+ * session_read result action 的默认单条字符上限（adversarial-review-fixes §3.4 C3）。
+ * 对齐 extensions/universal/session-reader/src/result-action.ts 的 RESULT_DEFAULT_LIMIT
+ * （8000）——extension 与 runtime 包无共享常量处、反向 import 会建立 subagent-core 对
+ * extension 的依赖，故本地常量 + 注释锚定；两侧改动须同步。
+ */
+const SESSION_READ_DEFAULT_LIMIT = 8000;
+
+/** 截断指针行（设计 §3.1.2 样例）：主 agent 据此按需 session_read 取回全文。
+ *  [S8 code-simplify 口径注] 本函数的 X（total - kept）= **丢弃**字符数；而
+ *  session-reader result-action.ts formatResultTruncation 同模板的 X = **保留**
+ *  字符数（limit）——同模板异语义，统一字符串 = 行为变更，勿顺手改口径。
+ *  [C3 limit 随附] perItemLimit = 该成员实际截断预算（effectivePerItem）：预算超过
+ *  session_read 默认 limit(8000) 时附 "limit":N——模型照抄指针行 JSON 调用才能取到
+ *  ≥ 默认值的有效正文（否则默认 8000 反而少于通知里已见的 kept，触发第二层截断）；
+ *  ≤8000 不附（默认已覆盖，避免噪音）。 */
+function buildTruncationPointer(id: string, kept: number, total: number, perItemLimit: number): string {
+  const limitPart = perItemLimit > SESSION_READ_DEFAULT_LIMIT ? `,"limit":${perItemLimit}` : "";
+  return `[truncated ${formatChars(total - kept)} of ${formatChars(total)} chars — full result: session_read {"action":"result","session":"${id}"${limitPart}}]`;
+}
+
+/** closed 成员 outcome 兑底物化（与下方 notify() 投影边界同款）；running 原样透传。 */
+function withMaterializedOutcome(record: BgNotifyRecord): BgNotifyRecord {
+  return record.status === "closed"
+    ? { ...record, outcome: record.outcome ?? deriveOutcome(record.closedReason, record.error) }
+    : record;
+}
+
+/**
+ * sync 批通知文案（U3 批形态 + U4 两段式预算截断）。
+ *
+ * 形态（设计 §3.1.1 交互样例）：批头行 `Subagent batch completed: N finished,
+ * M failed, K cancelled.` + 各成员条目（buildLlmContent 同语义）以 "\n\n---\n\"
+ * \n" join（分隔符对齐 ledger mergeItems / 内核合批——TUI/LLM 两消费方同构）。
+ * 批头计数口径 = 成员 outcome 三态（completed→finished）；closed 成员 outcome 缺省
+ * 时按单一权威 deriveOutcome 兑底（与 notify() 投影边界同款，幂等无害）。
+ *
+ * [U4 预算截断] 仅对展示结果正文的条目（closed+completed / running）生效；
+ * failed/cancelled 条目无 result 可取回（指针无意义）不计正文预算、原样输出。
+ * totalChars 口径（§3.1.2）：仅计条目正文（截断后）之和，批头/头行/指针行/
+ * 分隔符等包装开销为有界常量不入预算。未触预算时输出与 U3 基线逐字节一致。
+ * budget 缺省 = 设计默认值；config 热读接线由 flush 调用方传入。
+ */
+export function buildBatchLlmContent(
+  records: readonly BgNotifyRecord[],
+  budget: BatchBudgetParams = DEFAULT_BATCH_BUDGET,
+): string {
+  // 入口一次物化（S1，code-simplify）：closed 成员 outcome 兑底仅此一处，bodies/计数/
+  // 条目全部读物化结果——「单一权威 deriveOutcome」从注释承诺变构造事实。幂等纯函数，
+  // 与原四处各自推导逐字节等价；running 原样透传零拷贝。
+  const mat = records.map(withMaterializedOutcome);
+  let finished = 0;
+  let failed = 0;
+  let cancelled = 0;
+  // 各条目参与预算的正文（§3.1.2 口径）；null = 该条目不展示 result 正文。
+  const bodies = mat.map((record): string | null => {
+    if (record.status === "closed" && record.outcome !== "completed") return null;
+    return record.result ?? "(empty)";
+  });
+  const plan = computeBatchBudget(
+    bodies.map((body) => body?.length ?? 0),
+    budget.perItemChars,
+    budget.totalChars,
+  );
+  const items = mat.map((record, i) => {
+    if (record.status === "closed") {
+      const outcome = record.outcome;
+      if (outcome === "completed") finished += 1;
+      else if (outcome === "failed") failed += 1;
+      else if (outcome === "cancelled") cancelled += 1;
+    }
+    const body = bodies[i];
+    if (body === null || body.length <= plan.effectivePerItem) {
+      // 未触预算（含 failed/cancelled 条目）：U3 基线字节不变。
+      return buildLlmContent(record);
+    }
+    // 截断：正文保留前 limit 字符 + 省略号，尾接指针行（kept=0 纯清单时省略号一并省略）。
+    const kept = body.slice(0, plan.effectivePerItem);
+    const truncated = buildLlmContent({ ...record, result: plan.listOnly ? "" : `${kept}…` });
+    // 纯清单时 result 置空会在 buildLlmContent 内残留头行尾换行（"Result:\n" + ""），
+    // 收掉该空行让条目严格为「头行 + 指针行」两行形态（设计 §3.1.2 纯清单退化）。
+    const stripped = plan.listOnly ? truncated.replace(/\n$/, "") : truncated;
+    return `${stripped}\n${buildTruncationPointer(record.id, kept.length, body.length, plan.effectivePerItem)}`;
+  });
+  const header = `Subagent batch completed: ${finished} finished, ${failed} failed, ${cancelled} cancelled.`;
+  return [header, ...items].join("\n\n---\n\n");
+}
+
 /**
  * 将 BgNotifyRecord 格式化为 LLM 可读的 notification content。
  *
@@ -164,6 +331,13 @@ function buildLlmContent(record: BgNotifyRecord): string {
 export interface BgNotifier {
   /** 入队一条完成通知（去重 + 合批窗口合并）。dispose 后短路。 */
   notify(record: BgNotifyRecord): void;
+  /**
+   * sync 批通知（subagent-sync-collect U3）：成员集 → 单条批投递。幂等键
+   * `sync-batch:<sha1(sorted ids)>`，走与 notify 同一写账→settled 边沿投递链（单
+   * entry）。返回 false = 幂等拒绝（同成员集批已在账/已销账）或空批 / dispose 后——
+   * 调用方（service flushBatch 接线）据此决定 batchFinalized 落标。
+   */
+  notifyBatch(records: readonly BgNotifyRecord[], budget?: BatchBudgetParams): boolean;
   /** 立即 flush（session_shutdown 调用，防丢失）。 */
   flushPendingNotifications(): void;
   /** session 结束：清队列，dispose 内核 handle。 */
@@ -292,6 +466,37 @@ export function createNotifier(host: NotifierHost): BgNotifier {
   };
   let handle: DeliveryHandle = createHandle();
 
+  /** 四步投递链尾部共用段（S2，code-simplify）：notify 单条与 notifyBatch 逐行同构
+   *  的收尾——原两份手写拷贝使注释宣称的「同一四步链」无结构强制，现单点实现。
+   *  ledger 在 → ①写账（拒绝 = false，幂等去重：同 notifyId 已在账/已销账）→
+   *  ②attemptDeliver（settled 边沿 + isIdle 二次复查，③④销账/重放在 ledger 内）；
+   *  ledger 缺（旧装配 / 部分测试，含 jiti 单例分裂的失效形态）→ 内核路径降级 +
+   *  降级留痕 warn（C-ext-06 配套，不改变向后兼容行为）。返回 false 仅 notifyBatch
+   *  消费（调用方跳过落标）；notify 忽略（fire-and-forget）。闭包读 let handle：
+   *  revive 重建后自然指向新 handle。 */
+  function deliverViaLedgerOrKernel(notifyId: string, content: string, details: object): boolean {
+    const ledger = getBoundNotifyLedger();
+    if (ledger) {
+      if (!ledger.record(notifyId, content, details)) return false;
+      ledger.attemptDeliver();
+      return true;
+    }
+    notifyLogger.warn("notify ledger not bound, falling back to delivery kernel path (at-most-once)", {
+      notifyId,
+    });
+    handle.send({
+      payload: {
+        kind: "custom",
+        customType: NOTIFY_CUSTOM_TYPE,
+        content,
+        display: true,
+        details,
+      },
+      dedupeKey: notifyId,
+    });
+    return true;
+  }
+
   return {
     notify(record: BgNotifyRecord): void {
       if (disposed) return;
@@ -314,31 +519,35 @@ export function createNotifier(host: NotifierHost): BgNotifier {
       // 投递尝试）→ ②courier 边沿投递（settled 边沿 + 120s 看门狗 + isIdle 二次
       // 复查）→ ③回执销账 / ④重放幂等均在 ledger 内。record 返回 false = 同
       // notifyId 已在账或已销账（幂等去重，含重启恢复后的已送达账号零重发）。
-      const ledger = getBoundNotifyLedger();
-      if (ledger) {
-        if (!ledger.record(notifyId, content, payload)) return;
-        ledger.attemptDeliver();
-        return;
-      }
+      // 无 ledger 装配时内核路径降级 + 降级留痕（C-ext-06 配套，见 helper 注释）。
+      // 单条通知为 fire-and-forget，返回值忽略。
+      deliverViaLedgerOrKernel(notifyId, content, payload);
+    },
 
-      // 无 ledger 装配（旧装配 / 部分测试）：内核路径——合批窗口 / settled 边沿 /
-      // dedupe（按 notifyId，key 规则与旧 dedupeKey 一致：id 或 id:round）不变。
-      // [C-ext-06 配套] 降级留痕：bind 缺失（含 jiti 单例分裂致跨模块读不到绑定的
-      // 失效形态）本是无声分岔，U2 at-least-once 在此退化为内核路径——warn 一条
-      // 供诊断检索，不改变向后兼容行为。
-      notifyLogger.warn("notify ledger not bound, falling back to delivery kernel path (at-most-once)", {
-        notifyId,
-      });
-      handle.send({
-        payload: {
-          kind: "custom",
-          customType: NOTIFY_CUSTOM_TYPE,
-          content,
-          display: true,
-          details: payload,
-        },
-        dedupeKey: notifyId,
-      });
+    notifyBatch(records: readonly BgNotifyRecord[], budget?: BatchBudgetParams): boolean {
+      if (disposed || records.length === 0) return false;
+
+      // 投影边界物化（与 notify 同款）：closed 成员补 outcome——批头计数与成员条目
+      // 单一来源。消源自入参浅拷贝，不改写协调器缓冲持有的快照对象。
+      const payloads = records.map((record) =>
+        record.status === "closed"
+          ? { ...record, outcome: record.outcome ?? deriveOutcome(record.closedReason, record.error) }
+          : { ...record },
+      );
+      const batchNotifyId = buildBatchNotifyId(payloads.map((p) => p.id));
+      // budget（可选）= service flushBatch/E1 补发接线传入的 config 热读值（U4 deviation #8
+      // 由 U5 接线）；undefined → buildBatchLlmContent 参数缺省 = 设计默认值（4000/24000）。
+      // 账本重放走写入时已定格的 content，预算在写账时刻生效（“flush 时热读”语义）。
+      const content = buildBatchLlmContent(payloads, budget);
+      // details 形态 = ledger mergeItems 批量分支（{batch:true, items}——bg-notify-render
+      // extractBatch 已支持，⛔1 核对）+ 顶层 notifyId：collectDeliveredNotifyIds 的回执
+      // 匹配键认 details.notifyId / details.items[].notifyId，批身份键必须顶层可达，
+      // 否则批 entry 永不销账、重投至放弃。顶层 notifyId 键对 extractBatch 透明（多键无感）。
+      const details = { batch: true as const, notifyId: batchNotifyId, items: payloads };
+
+      // 与 notify 同一四步链（deliverViaLedgerOrKernel，S2 提取）：返回 false = 同成
+      // 员集批已在账（E1 重建重发 / 重复 flush）→ 调用方跳过落标。
+      return deliverViaLedgerOrKernel(batchNotifyId, content, details);
     },
 
     flushPendingNotifications(): void {