@zhushanwen/subagent-core 0.5.1 → 0.7.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 仍执行。
 
@@ -43,6 +43,16 @@ export interface FinalizeDeps {
   pi: { appendEntry?: (type: string, data: unknown) => void } | null;
   /** pending-notifications 终态注销（绑定 pi.events.emit，由调用方闭包提供）。 */
   emitUnregister(id: string, status: string): void;
+  /**
+   * [F-5 修复] record 终态化的宿主侧收口钩子（recordId；best-effort，抛错由调用方
+   * 在闭包内自行兜底）。单一汇聚点：doFinalizeRecord 是全部 closed 终态的必经路径
+   * （finalizeRecord / closeChatIdle / closeAfterRoundSettled / finalizeFailed /
+   * finalizeAborted / consumeCloseAfterRound），chat 轮路由注销（chatRoundRoutes）
+   * 由 SubagentService 经此钩子统一执行——此前仅 cancelBackground 注销，chat record
+   * 经 finalize 链终态化后路由闭包（持 record/stream/守护引用）泄漏。finalizeRoundToIdle
+   * 不经本钩子（回 idle 非终态，续聊仍需路由）。
+   */
+  onFinalized?: (recordId: string) => void;
   /**
    * [T1/PS-9] subagent sessionDir（getSubagentSessionDir(agentDir, rootCwd)，调用方注入）。
    *
@@ -177,11 +187,13 @@ function removeAliveMarkerIfPresent(record: ExecutionRecord): void {
 /**
  * Step 4 (last): manifest 持久化（best-effort，不阻断、不 throw）。
  *
- * [Critical #1] manifest 是诊断辅助（orphan recovery），不是正确性依赖。写失败时
- * 仅记录（console.error + appendEntry），绝不让 manifest 写失败跳过 Step 3 cleanup
- * 或抛出打断 finalize 链。旧实现 Step 2.5 throw 会跳过 Step 3 cleanup。
- * task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord 补字段），
- * manifestToSubagent 投影时用真实值而非硬编码空串。
+ * [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 {
@@ -252,8 +264,23 @@ export async function doFinalizeRecord(
   removeAliveMarkerIfPresent(record);
 
   // pending-notifications：终态注销（只记 registry 状态，通知由 BgNotifier 发）
+  // [W4 发射点枚举归属①] 注销合法发射点枚举（设计 D2）第 ① 处：subagent record
+  // 终态化（finalizeRecord 路径，含监督器放弃）。其余合法发射点：② chatMode 轮末
+  // idle（doFinalizeRoundToIdle，本文件下方）；③ workflow run 终态迁移
+  // （transition("done") 路径）；④ 监督器显式放弃（走本路径，终态化+注销同批）；
+  // ⑤ 注册对账 sweep 补发（round-supervisor/reconcile-sweep.ts）。进程退出本身
+  // 永远不是注销理由（subagent-service disposeAllRecords 的 emit 属①——其同批
+  // completeRecord+archive 终态化）。
   deps.emitUnregister(record.id, status);
 
+  // [F-5 修复] 宿主侧终态收口钩子（chat 轮路由注销的单一汇聚点，见 FinalizeDeps
+  // .onFinalized 注释）。fire-and-forget：钩子失败不阻断 manifest 收尾（闭包内自查）。
+  try {
+    deps.onFinalized?.(record.id);
+  } catch (err) {
+    bestEffort(err, "onFinalized hook (finalizeRecord)");
+  }
+
   // ── Step 4 (last): manifest 持久化（best-effort，不阻断、不 throw）──
   await writeManifestBestEffort(deps, record);
 }
@@ -265,7 +292,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

@@ -2,6 +2,22 @@
  * SP-4 idle record GC：30 天 TTL 定时归档，防 idle record 永久驻留内存。
  * 从 subagent-service.ts 抽出（文件超 max-lines；逻辑自包含：interval + TTL 扫描）。
  * 启动幂等由调用方（service.startGcTimer）守卫；返回 stop 函数供 dispose 清理。
+ *
+ * [W4 idle-gc 扩展 · 设计 chat-domain-v1x-liveness-governance D4 连带面 2③]
+ * 注册翻 process 档后的兜底通道扩展（与翻档同批生效，先行期 = 无兜底挂账窗口）：
+ *  1. 锚扩展：无 idleSince 的 resumable record 以 startedAt（创建时确定，
+ *     types.ts ExecutionRecord.startedAt）为锚——兜底定位 30 天量级终态归档，
+ *     创建时锚的精度损失在该量级可接受（同设计对 record startedAt 的 rationale）。
+ *  2. **只归档不补注销**：被归档 record 的注册注销统一交 core 注册对账 sweep
+ *     （判据含「已归档 = 视同终态」）——归档跨 session record 时 appendEntry 只达
+ *     当前 session entries（写达域无效），且 archive 不走 finalizeRecord、无注销
+ *     发射枚举身份（发射点枚举 D2 的 5 处不含 GC）。
+ *  3. WorkflowRun store 同批纳入：running 且 meta.startedAt 超 IDLE_TTL_MS 的 run
+ *     终态化归档（transition("done","time_limited") + save 持久化终态）。时间锚选择
+ *     = WorkflowRunMeta.startedAt（run 创建时刻，ISO string）——run 状态无 idleSince
+ *     等价物，meta.completedAt 仅终态存在，startedAt 是唯一创建时确定的锚（与
+ *     record startedAt 同 rationale）。**只终态化不补注销**同上：run 的注销发射
+ *     身份在 transition("done") 路径（发射点③）与其宿主收口链，GC 不越权补发。
  */
 import { getLogger } from "../core/logger.ts";
 import { getEngineDataDir } from "./engine/common/data-dir.ts";
@@ -16,17 +32,32 @@ const logger = getLogger("subagents");
 /** GC 扫描间隔：1 小时。 */
 // eslint-disable-next-line no-magic-numbers -- 60*60*1000 = 1h 的毫秒换算常数
 const GC_INTERVAL_MS = 60 * 60 * 1000;
-/** idle record TTL：30 天（超龄归档）。 */
+/** idle record TTL：30 天（超龄归档）。record 锚窗与 workflow run 锚窗共用。 */
 // eslint-disable-next-line no-magic-numbers -- 30*24*60*60*1000 = 30d 的毫秒换算常数
 const IDLE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 /** 毫秒/天（GC 日志的 d 换算）。 */
 // eslint-disable-next-line no-magic-numbers -- 24*60*60*1000 = 1d 的毫秒换算常数
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
+/**
+ * WorkflowRun GC 窄口（idle-gc 对 WorkflowRun store 的最小依赖面，结构类型——
+ * 调用方传 FileRunStore 实例即可，不 import orchestration 具体类，保持本模块
+ * 可独立编译 + 单测）。loadAll 失败（宿主未 configureCore / IO 错）由实现侧
+ * 或本模块 catch 吞掉，单轮跳过下轮重试。
+ */
+export interface WorkflowRunGcStore {
+  loadAll(): Promise<Array<{ runId: string; state: { status: string }; meta: { startedAt: string }; transition(target: "done", reason?: string): void }>>;
+  save(run: unknown): Promise<void>;
+}
+
 /**
  * 启动 idle record GC 定时器，返回 stop 函数（清理 interval；幂等）。
- * 每个扫描周期：对 store 内全部 active record 中 resumable 且带 idleSince 的，
- * 超过 IDLE_TTL_MS 的归档（archive 单条失败不阻断其余，bestEffort 留痕）。
+ * 每个扫描周期：
+ *  - record 面：对 store 内全部 active record 中 resumable 的，锚点（idleSince
+ *    优先，缺失回退 startedAt——[W4 锚扩展]）超过 IDLE_TTL_MS 的归档。archive
+ *    单条失败不阻断其余（bestEffort 留痕）。**只归档不补注销**（见文件头注）。
+ *  - workflow 面（注入 workflowRuns 时）：running 且 meta.startedAt 超
+ *    IDLE_TTL_MS 的 run 终态化归档（transition + save），单 run 失败不阻断。
  *
  * [D8 池引用计数接线] 归档时同步释放该 record 的引擎池引用（releasePoolRef：
  * journal 跟随 record 删除 + refs 移除 + 归零删池内原生状态）。锚点选在 30 天 TTL
@@ -37,28 +68,72 @@ const MS_PER_DAY = 24 * 60 * 60 * 1000;
  * 不能删——那是 record 主数据死亡（主 session 文件被 pi 侧删除，core 无触发点）才有
  * 的处置，由 cleanupExpiredPoolRefs 的 TTL 兜底覆盖。
  */
-export function startIdleGc(store: RecordStore): () => void {
+export function startIdleGc(store: RecordStore, workflowRuns?: WorkflowRunGcStore): () => void {
   const timer = setInterval(() => {
     const now = Date.now();
     for (const record of store.listAllActive()) {
-      if (isResumable(record) && record.idleSince) {
-        const age = now - record.idleSince;
-        if (age > IDLE_TTL_MS) {
-          logger.warn(`[subagents] GC: archiving idle record ${record.id} (idle for ${Math.round(age / MS_PER_DAY)}d)`);
-          try {
-            store.archive(record);
-          } catch (err) {
-            bestEffort(err, `GC archive record ${record.id}`);
-          }
-          releaseEnginePoolRef(record);
+      if (!isResumable(record)) continue;
+      // [W4 锚扩展] idleSince（轮终写点）优先；缺失（resumable 但无轮终信号的
+      // 存量/异常形态）回退 startedAt（创建时确定）——两锚同为「最晚活性证据」，
+      // 30 天量级下 created 锚的精度损失可接受。
+      const anchorMs = record.idleSince ?? record.startedAt;
+      const age = now - anchorMs;
+      if (age > IDLE_TTL_MS) {
+        logger.warn(
+          `[subagents] GC: archiving idle record ${record.id} (idle for ${Math.round(age / MS_PER_DAY)}d)`,
+        );
+        try {
+          store.archive(record);
+        } catch (err) {
+          bestEffort(err, `GC archive record ${record.id}`);
         }
+        releaseEnginePoolRef(record);
       }
     }
+    if (workflowRuns !== undefined) {
+      void gcWorkflowRuns(workflowRuns, now);
+    }
   }, GC_INTERVAL_MS);
   timer.unref?.();
   return () => clearInterval(timer);
 }
 
+/**
+ * [W4 WorkflowRun store 纳入] running 且 startedAt 超锚窗的 run 终态化归档。
+ * reason = "time_limited"（超龄归档语义的 DoneReason，对主 agent 的语义是
+ * 「run 因超时被收口」而非 completed）。失败吞错留痕（清理是旁路维护，不能
+ * 拖垮 GC interval；下轮重试）。
+ */
+async function gcWorkflowRuns(workflowRuns: WorkflowRunGcStore, now: number): Promise<void> {
+  let runs: Awaited<ReturnType<WorkflowRunGcStore["loadAll"]>>;
+  try {
+    runs = await workflowRuns.loadAll();
+  } catch (err) {
+    // 宿主未 configureCore（core_host_not_configured）/ IO 失败：本轮跳过，
+    // 下轮重试。debug 留痕——这是「workflow 域未启用」的正常形态，warn 会噪声。
+    logger.debug(`[subagents] GC: workflow run store loadAll failed (skipped this cycle): ${
+      err instanceof Error ? err.message : String(err)
+    }`);
+    return;
+  }
+  for (const run of runs) {
+    if (run.state.status !== "running") continue;
+    const startedMs = Date.parse(run.meta.startedAt);
+    if (!Number.isFinite(startedMs)) continue; // 畸形锚不过判（宁挂账不失明）
+    const age = now - startedMs;
+    if (age <= IDLE_TTL_MS) continue;
+    logger.warn(
+      `[subagents] GC: terminating stale running workflow run ${run.runId} (started ${Math.round(age / MS_PER_DAY)}d ago)`,
+    );
+    try {
+      run.transition("done", "time_limited");
+      await workflowRuns.save(run);
+    } catch (err) {
+      bestEffort(err, `GC terminate workflow run ${run.runId}`);
+    }
+  }
+}
+
 /**
  * 释放 record 的引擎池引用（best-effort）。无 engineHandle（存量 record / 非引擎
  * 路径）时 no-op；engine 缺省投影 'pi'（与读侧存量 entry 零迁移口径一致）。

package/src/execution/lifecycle-manager.ts

@@ -13,7 +13,10 @@
 //      【已接线：session-runner.ts agent_settled arm / subagent-service 新 turn disarm】
 //   2. 全局 ceiling —— 活进程上限，超限时按 LRU 挤出最久空闲（决策 4）【未接线，deferred】
 //   3. shutdown 收割 —— 父进程 shutdown 时显式 SIGTERM 全部 activation（决策 7 防线 i）
-//      【未接线：index.ts reapSpawnedChildrenOnShutdown + killAllSpawnedChildren 已等价覆盖】
+//      【未接线：[F-7 纠偏] 旧注「reapSpawnedChildrenOnShutdown 已等价覆盖」失实——
+//      该 hook 调 killAllSpawnedChildren，后者协议化后仅镜像置死 no-op（见
+//      engine/host/spawned-children.ts 与 src/index.ts 导出注释）；引擎进程实际回收 =
+//      stdin-EOF 自灭链，本职责仍无显式收割接线】
 //   4. 孤儿扫描 —— 父进程启动时按持久化 PID 扫收上次崩溃遗留的孤儿（决策 7 防线 ii）【deferred】
 //   5. activate 互斥 —— 同 recordId 的并发 activate 串行化（决策 7 防线 iii，防双写者）
 //      【已接线：subagent-service.ts 冷路径 resume 前 acquireActivateLock】
@@ -295,12 +298,12 @@ export function getActiveProcessCount(): number {
 // ============================================================
 // 职责 3：shutdown 收割（防线 i）
 //
-// [状态：未接线，已有等价实现] reapAllAliveProcesses 无生产调用方——shutdown 收割
-// 已由 index.ts 的 reapSpawnedChildrenOnShutdown（process hook → killAllSpawnedChildren
-// 发 SIGTERM，覆盖 SIGTERM/SIGINT/beforeExit 挂点）等价覆盖；后者直接遍历
-// spawnedChildren 句柄表，不依赖本模块 activeProcesses 记账的 register 时机，覆盖面
-// 更可靠。本函数保留作跨模块等价实现；若未来接入须先保证 register/unregister 记账
-// 完整，否则收割列表不全。
+// [状态：未接线，无等价实现（[F-7 纠偏]）] reapAllAliveProcesses 无生产调用方。旧注
+// 「shutdown 收割已由 reapSpawnedChildrenOnShutdown 等价覆盖」失实：该 hook 调
+// killAllSpawnedChildren，而后者协议化后（engines/pi inproc 删除、子进程活在引擎
+// 进程内）仅做 core 侧镜像置死，不发任何 SIGTERM（_signal 参数被忽略）——引擎进程
+// 实际回收走 stdin-EOF 自灭链，本职责的显式收割仍无接线。本函数保留作未来接入面；
+// 若未来接入须先保证 register/unregister 记账完整，否则收割列表不全。
 // ============================================================
 
 /**

package/src/execution/lifecycle-predicates.ts

@@ -4,8 +4,8 @@
 //
 // 旧三态（running/idle/cancelled）折为两态（running/closed）后，「对话模式等待续聊」
 //（旧 idle）和「正在执行」都是 status="running"，需派生谓词区分。谓词复用已有
-// lifecycle-manager.hasIdleTimer（idle timer 是否 armed）与 session-runner.getChildByRecord
-//（活进程句柄是否存在），不新增状态记账。
+// lifecycle-manager.hasIdleTimer（idle timer 是否 armed）与 core 侧 spawnedChildren
+// 状态镜像读点（engine/host/spawned-children.ts，活进程句柄是否存在），不新增状态记账。
 //
 // 两种 running 子态（v4 B-1）：
 //   - 等待续聊（旧 idle）：isIdle=true（timer armed）。又分两路：
@@ -20,19 +20,21 @@
 // 故 isIdle 在这两个检查点恒为 true——notify 守卫与 early-return 判据可靠。
 
 import { hasIdleTimer } from "./lifecycle-manager.ts";
-import { getChildByRecord } from "./engine/engines/pi/session-runner.ts";
+// [W6 拆依赖] 活进程句柄读点改经 core 侧 spawnedChildren 状态镜像公共面
+// （engine/host/spawned-children.ts），不再深路径 import inproc pi 引擎目录 内部——
+// 行为不变（镜像 ∪ inproc 权威 map 并读，见该文件头注释的过渡桥语义）。
+import { hasLiveProcessHandleCore } from "./engine/host/spawned-children.ts";
 import type { ExecutionRecord } from "./types.ts";
 
 /**
  * 活进程句柄是否存在（isResumable 子判据）。
  *
- * 复用 session-runner.spawnedChildren 的 getChildByRecord 查询。child 存在且未 kill
- * = 有活进程句柄（正在执行 / Path A 保活）。进程 close 后 spawnedChildren 已 delete，
- * 返回 undefined = 无活进程（Path B / 跨重启）。
+ * [W6] 改读 core 侧状态镜像（engine/host/spawned-children.ts 的 hasLiveProcessHandleCore：
+ * 镜像项存在且未 killed = 有活进程句柄；迁移期内建 pi 的 inproc 权威 map 并读兜底）。
+ * 进程 close / 被杀后镜像项置死或移除 = 无活进程（Path B / 跨重启）。
  */
 export function hasLiveProcessHandle(recordId: string): boolean {
-  const child = getChildByRecord(recordId);
-  return child !== undefined && !child.killed;
+  return hasLiveProcessHandleCore(recordId);
 }
 
 /**

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 {