@zhushanwen/subagent-core 0.5.1 → 0.6.0

package/src/execution/__tests__/tombstone-store.test.ts

@@ -20,7 +20,7 @@ describe("tombstone-store", () => {
     sessionFile = path.join(tmpDir, "2026-01-01_uuid.jsonl");
   });
   afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   describe("write → read 往返", () => {

package/src/execution/__tests__/worktree-git-ops.test.ts

@@ -84,7 +84,7 @@ describe("worktree-git-ops", { timeout: 30_000 }, () => {
 
   afterEach(() => {
     resetCoreForTests();
-    fs.rmSync(outerDir, { recursive: true, force: true });
+    fs.rmSync(outerDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   /**

package/src/execution/__tests__/worktree-reconcile-aging.test.ts

@@ -76,7 +76,7 @@ describe("WorktreeManager 对账歧义跳过老化（PS-12 措施⑤）", { time
 
   afterEach(() => {
     process.env.TMPDIR = ORIG_TMPDIR;
-    fs.rmSync(outerDir, { recursive: true, force: true });
+    fs.rmSync(outerDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   /** 建一个物理 worktree（绕过 WorktreeManager.create 的脏树校验，路径布局同 create）。 */
@@ -174,7 +174,7 @@ describe("WorktreeManager 对账歧义跳过老化（PS-12 措施⑤）", { time
 
     // 出现对应：s-r2 pid 死 + c2 删除 → 1 活 pid ↔ 1 残留 → 自愈补写 c1
     await waitPidDead(sleeper.pid as number);
-    fs.rmSync(c2, { recursive: true, force: true });
+    fs.rmSync(c2, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     await mgr.scan();
     expect(registry.load().map((e) => e.branch)).toEqual(["pi-sub-r1"]);
     expect(escalationCalls()).toEqual([]);

package/src/execution/__tests__/worktree-reconcile.integration.test.ts

@@ -66,7 +66,7 @@ describe("WorktreeManager.scan 物理面对账（D5b）", { timeout: 30_000 }, (
 
 	afterEach(() => {
 		process.env.TMPDIR = ORIG_TMPDIR;
-		fs.rmSync(outerDir, { recursive: true, force: true });
+		fs.rmSync(outerDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 	});
 
 	/** 建一个物理 worktree（按 create() 的真实路径布局，绕过 WorktreeManager.create 的脏树校验）。 */

package/src/execution/__tests__/worktree-registry.test.ts

@@ -41,7 +41,7 @@ describe("WorktreeRegistry", () => {
   });
 
   afterEach(() => {
-    fs.rmSync(tmpAgentDir, { recursive: true, force: true });
+    fs.rmSync(tmpAgentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   describe("add + load", () => {

package/src/execution/collect-coordinator.ts

@@ -0,0 +1,200 @@
+// src/execution/collect-coordinator.ts
+//
+// collectCoordinator：notifyComplete 唯一路由入口——async 直通 / sync 批缓冲 / 闭合检测
+// （subagent-sync-collect 设计 §3.1.4 终态数据流 / D2 隐式批 / D5 service 层缓冲）。
+//
+// 职责（U2）：
+//   route(record)：
+//     - record.collectMode !== "sync" → deps.notifyAsync（现状 notifier.notify 路径，
+//       执行序列逐字节一致，G3/A5 零回归）；
+//     - record.collectMode === "sync" → deps.toNotifyRecord 终态快照登记入缓冲（内存，
+//       登记时定格——record 对象后续可变不影响快照）→ 闭合检测。
+//
+//   闭合判定（⛔3 已核实 U1，impl-plan §7）：缓冲非空 && 无非终态 sync 成员。
+//   「非终态」口径 = collectMode="sync" && 无 batchFinalized 标记 && status !== "closed"
+//   ——池排队成员在 store.register 时即 status="running"，自动计入非终态（闭合等待它）；
+//   batchFinalized=true 的已离场成员不阻止闭合。
+//
+//   跨轮续累（D2 隐式批）：缓冲跨多次 route 累积不清空（分两轮派 2+1 sync → 闭合时
+//   单批三成员）；flush 后缓冲清空，后续 sync 成员自然开新批（语义 = "等所有 sync 待收"）。
+//
+// [U8 拆批盲窗修复] 闭合满足 → 同宏任务去抖合批 flush（不再立即 flush）：
+//   盲窗机理：kickOffBackground 的 runAndFinalize（completeRecord+archive，record 从
+//   store.listAllActive 移除）先于 .then 链的 notifyComplete。同同步段背靠背终态时，
+//   成员 A route 触发闭合检测（只扫 listAllActive 非终态）看不到「已 archive 未路由」
+//   的成员 B → 立即 flush([A])；B route 再 flush([B]) → 拆两条单成员批（G1 弱化，
+//   单唤醒变两次）。
+//   修复：闭合首次满足改排程 flush（setTimeout(0)，Node 1ms clamp——同一宏任务级窗口，
+//   确定性、无可观察延迟）；窗口内后续 route 落缓冲后一并 flush（背靠背成员合单批）。
+//   触发时重验闭合条件：窗口内若有新 sync 成员注册 running（跨轮续累反转）→ 保留缓冲
+//   不 flush，等其终态 route 重新排程（终态必经 notifyComplete，不丢、不悬挂）。
+//   交互语义（授权修复轮决策）：
+//   - E9 dispose：service.convertPendingSyncBufferToAsync 先 cancelScheduledFlush
+//     （取消而非同步 flush——放任触发会与逐条转 async 写账双通道并发 → 同成员双投递，
+//     且触发点可能落在 notifier/store dispose 之后）；取消后缓冲原样保留，E9 单通路
+//     完整接管（选语义最简）。
+//   - E1 恢复补发：只在 session_start 编排处运行（此前 dispose 已取消挂起排程），
+//     补发直走 notifier.notifyBatch 不经协调器；异常时序相撞由账本 sync-batch:<hash>
+//     幂等拒绝兜底。
+//
+// flush 注入式（U3 已接线）：deps.flushBatch 由宿主注入——U3 接 service 闭包的
+//「manifest 屏障（await 落盘）→ notifier.notifyBatch 单条批投递（ledger sync-batch
+// hash 写账）→ batchFinalized 落标」（见 subagent-service.ts flushBatch 闭包）。
+// 测试注入 fake 断言闭合条件。flush 异步（Promise<void>）、协调器 void 调用不等待：
+// 缓冲在调用前已整体移交清空，flush 内部时序（屏障 → 写账 → 落标）与失败语义归
+// 实现方（与 notifier.notify 同风格）。
+//
+// 不变量：
+//   - 每个成员只登记一次：notifyComplete 调用点自带 CAS/gate 单次性（与既有 notify
+//     单次性同源——cancelBackground CAS 抢锁 / kickOffBackground.then gate / watchdog
+//     CAS），协调器不重复去重，不改变 at-least-once 语义。
+//   - toNotifyRecord 返回 undefined（gate 未过/非终态）→ 静默跳过不入缓冲，与 async
+//     路径的静默跳过对称——调用点 gate 语义不变，协调器不重复判定。
+//   - 闭合判定只敏感于「是否还有非终态 sync」：本条终态在 store 的可见性（archive 后
+//     磁盘重建时序）不影响判定正确性。
+//   - [U8] 排程幂等：窗口内多条 route 至多一个挂起定时器；flush 只在触发时重验后执行，
+//     缓冲在排程期内保持可枚举（pendingMembers 供 E9 dispose 转换读取）。
+
+import type { BgNotifyRecord } from "./notifier.ts";
+import type { ExecutionRecord } from "./types.ts";
+
+/** 闭合判定的 record 最小视图（ExecutionRecord / SubagentRecord 的同构子集）。
+ *
+ *  [U3 微调 / U5 已修] 原 deps 用 SubagentRecord——生产通路 collectRecords 经
+ *  recordToSubagent 投影曾不含 collectMode/batchFinalized（U2 披露，U5 已补投影），
+ *  保留结构化最小接口 + service 接线走 store.listAllActive()（原始 ExecutionRecord
+ *  内存态，不经投影）——非终态 sync 成员必在内存（archive 只删终态），内存视图语义
+ *  完整；纯注入测试的 SubagentRecord stub 结构兼容零改动。 */
+export interface CollectScanRecord {
+  status: string;
+  collectMode?: "sync";
+  batchFinalized?: boolean;
+  /** SP-5 执行态信号：true = 无活进程驱动的 running（one-shot 成功回退态）。
+   *  [U3 补丁] ⛔3 非终态口径的必要补充——one-shot 成功完成后 record 不 archive，
+   *  以 running+resumable 留内存等 message 升级（真链 trace 实证）：结果已定格、
+   *  进程已死 = 已完成待通知，不阻止闭合；否则 sync 批永不闭合。 */
+  resumable?: boolean;
+}
+
+/** 闭合判定的全 record 扫描上限（service 冷路径 COLD_LOOKUP_SCAN_LIMIT 同量级）。 */
+export const COLLECT_SCAN_LIMIT = 1000;
+
+/** 协调器宿主依赖（全部注入——协调器零 service/store 直依，可独立单测）。 */
+export interface CollectCoordinatorDeps {
+  /** async 直通（现状 notifier.notify 路径，字节不变）。 */
+  notifyAsync(record: ExecutionRecord): void;
+  /** record → 通知快照（登记时定格）。undefined = gate 未过/非终态（静默跳过）。 */
+  toNotifyRecord(record: ExecutionRecord): BgNotifyRecord | undefined;
+  /** 闭合判定数据源（CollectScanRecord 最小视图，见接口注释——数据源须携带
+   *  collectMode/batchFinalized 原始值，禁经 recordToSubagent 投影）。 */
+  listRecords(limit: number): CollectScanRecord[];
+  /** 批投递回调（合批窗口到期触发，缓冲整体移交后清空）。U3 接 service 闭包：
+   *  manifest 屏障 → notifier.notifyBatch 写账 → batchFinalized 落标——屏障先于写账
+   *  是「通知可达 ⇒ 索引就位」的构造性保证，故异步；协调器 void 调用不等待其完成。 */
+  flushBatch(members: BgNotifyRecord[]): Promise<void>;
+}
+
+/** route 去向（测试/诊断断言用）。 */
+export type CollectRouteResult =
+  /** 非 sync record：notifyAsync 直通（现状路径）。 */
+  | "async"
+  /** gate 未过（toNotifyRecord undefined）：静默跳过，不入缓冲。 */
+  | "sync-skipped"
+  /** 入缓冲未闭合（仍有非终态 sync 成员）。 */
+  | "sync-buffered"
+  /** 闭合触发（[U8] flush 已排程合批——同宏任务窗口内的后续 route 一并投递）。 */
+  | "sync-flushed";
+
+export class CollectCoordinator {
+  /** 批缓冲（内存）：已终态未 flush 的 sync 成员终态快照，跨 route 累积。
+   *  [U8] 排程合批窗口期内保持可枚举（E9 dispose 转换依赖 pendingMembers 全量）。 */
+  private readonly buffer: BgNotifyRecord[] = [];
+
+  /** [U8] 挂起的合批排程定时器（undefined = 无排程）。 */
+  private flushTimer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(private readonly deps: CollectCoordinatorDeps) {}
+
+  /** notifyComplete 唯一路由入口。返回去向供测试/诊断断言。 */
+  route(record: ExecutionRecord): CollectRouteResult {
+    if (record.collectMode !== "sync") {
+      this.deps.notifyAsync(record);
+      return "async";
+    }
+    const snapshotRecord = this.deps.toNotifyRecord(record);
+    if (!snapshotRecord) return "sync-skipped";
+    this.buffer.push(snapshotRecord);
+    return this.armFlushIfClosed() ? "sync-flushed" : "sync-buffered";
+  }
+
+  /** 诊断/测试：当前缓冲成员数（= 已终态未 flush 的 sync 成员数，含合批窗口内成员）。 */
+  get pendingCount(): number {
+    return this.buffer.length;
+  }
+
+  /** 诊断/测试 + E9 dispose 转换数据源：缓冲成员快照（副本，非活引用）。 */
+  pendingMembers(): BgNotifyRecord[] {
+    return [...this.buffer];
+  }
+
+  /** [U8·E9 交互] 取消挂起的合批排程（缓冲原样保留——dispose 转 async 通路仍读得到
+   *  全部成员）。无排程时 no-op；幂等。 */
+  cancelScheduledFlush(): void {
+    if (this.flushTimer !== undefined) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = undefined;
+    }
+  }
+
+  /** 闭合判定 + 合批排程武装：缓冲非空 && 无非终态 sync 成员 → 排程 flush。
+   *  已有排程挂起时幂等（同窗口合批，不重复定时器）。（S6 改名：原名 closeDetected
+   *  读作纯检测，实带副作用——武装排程改状态，名实相符优先。） */
+  private armFlushIfClosed(): boolean {
+    if (this.buffer.length === 0) return false;
+    if (this.hasRunningSync()) return false;
+    this.scheduleFlush();
+    return true;
+  }
+
+  /** [U8] 同宏任务去抖合批排程：setTimeout(0)（Node 1ms clamp）——窗口跨度覆盖一个
+   *  完整事件循环轮次（当前 poll 段 I/O 回调 + 微任务链排空），足以收纳 finalize 链
+   *  间隙内的背靠背 route，同时无可观察延迟（毫秒级 < 任意 LLM/投递时标）。 */
+  private scheduleFlush(): void {
+    if (this.flushTimer !== undefined) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = undefined;
+      this.flushIfClosed();
+    }, 0);
+  }
+
+  /** 合批窗口到期：重验闭合条件后整体移交 flushBatch 并清空。
+   *  窗口内新 sync 成员注册 running（跨轮续累反转）→ 保留缓冲不 flush，等其终态
+   *  route 重新排程（终态必经 notifyComplete，不丢、不悬挂）。
+   *  void 不等待 flush 的 async 屏障序列（manifest → 写账 → 落标）：缓冲已 splice
+   *  先行整体移交，屏障 await 期间窗口内新成员重新入空缓冲开新批，互不干扰。 */
+  private flushIfClosed(): void {
+    if (this.buffer.length === 0) return;
+    if (this.hasRunningSync()) return;
+    const members = this.buffer.splice(0, this.buffer.length);
+    void this.deps.flushBatch(members);
+  }
+
+  /** 是否存在非终态 sync 成员（collectMode=sync && 无 batchFinalized && 非终态）。
+   *  非终态口径（⛔3 U1 已核实 + U3 resumable 补丁）：status 非 closed 且非 resumable
+   *  ——池排队/在跑成员在 store.register 时即 status="running"，自动计入（闭合等待它）；
+   *  batchFinalized=true 的已离场成员不阻止闭合；running+resumable（SP-5 one-shot
+   *  成功回退态，进程已死结果已定格）视为已完成，不阻止闭合。 */
+  private hasRunningSync(): boolean {
+    for (const record of this.deps.listRecords(COLLECT_SCAN_LIMIT)) {
+      if (
+        record.collectMode === "sync" &&
+        record.batchFinalized !== true &&
+        record.resumable !== true &&
+        record.status !== "closed"
+      ) {
+        return true;
+      }
+    }
+    return false;
+  }
+}

package/src/execution/config.ts

@@ -9,7 +9,11 @@ import * as path from "node:path";
 
 import { getLogger } from "../core/logger.ts";
 
-import type { SubagentsGlobalConfig } from "./types.ts";
+import type { CollectSyncConfig, SubagentsGlobalConfig } from "./types.ts";
+
+// 同步收集配置节类型 re-export（类型权威定义在 types.ts，避免 config → types 反向依赖成环；
+// 消费方从本模块 import 与从 types.ts import 等价，U1 foundation 契约）。
+export type { CollectSyncConfig };
 
 // 包内 execution 模块统一具名 logger（getLogger 缓存单例，见 notify-ledger.ts 同款）。
 const logger = getLogger("subagents");
@@ -33,8 +37,25 @@ export const DEFAULT_CONFIG: SubagentsGlobalConfig = {
   maxConcurrent: 6,
 };
 
+// 注意：DEFAULT_CONFIG 刻意不含 collectSync 键（与 defaultEngine/engineRouting 同风格）——
+// SW 包 package.json 的 pi.startupConfig 声明守护（startup-config-declaration.test.ts）
+// 断言与 DEFAULT_CONFIG 深相等，声明面只含既有键。collectSync 缺省语义由
+// DEFAULT_COLLECT_SYNC 承载，消费方以 `config.collectSync ?? DEFAULT_COLLECT_SYNC` 兜底
+// （loadGlobalConfig 文件缺失/坏 JSON 路径返回 {...DEFAULT_CONFIG} 同样无键）。
+
 /** 默认 maxConcurrent（DEFAULT_CONFIG 的镜像，sanitize 用）。 */
 const DEFAULT_MAX_CONCURRENT = 6;
+
+/**
+ * 同步收集配置节权威默认值（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+ * 消费方：startHandler 缺省模式解析 / U3+U4 批通知预算（flush 时热读）。
+ * 供守护测试断言（E5 各坏值回默认）。展开拷贝防调用方 mutate。
+ */
+export const DEFAULT_COLLECT_SYNC: CollectSyncConfig = {
+  default: "async",
+  perItemChars: 4000,
+  totalChars: 24000,
+};
 // ============================================================
 // 路径
 // ============================================================
@@ -133,19 +154,70 @@ function errnoCodeOf(err: unknown): string | undefined {
 function sanitizeParsedConfig(parsed: Partial<SubagentsGlobalConfig>): SubagentsGlobalConfig {
   const defaultEngine = sanitizeDefaultEngine(parsed.defaultEngine);
   const engineRouting = sanitizeEngineRouting(parsed.engineRouting);
+  const collectSync = sanitizeCollectSync(parsed.collectSync);
   return {
     version: parsed.version ?? DEFAULT_CONFIG.version,
     maxConcurrent: sanitizeMaxConcurrent(parsed.maxConcurrent),
     ...(defaultEngine !== undefined ? { defaultEngine } : {}),
     ...(engineRouting !== undefined ? { engineRouting } : {}),
+    ...(collectSync !== undefined ? { collectSync } : {}),
   };
 }
 
-/** maxConcurrent 校验：正整数，否则默认。 */
+/** maxConcurrent 校验：正整数，否则默认（S5：委托 sanitizePositiveInt，正整数规则单点化）。 */
 function sanitizeMaxConcurrent(value: unknown): number {
-  return typeof value === "number" && Number.isInteger(value) && value > 0
-    ? value
-    : DEFAULT_MAX_CONCURRENT;
+  return sanitizePositiveInt(value, DEFAULT_MAX_CONCURRENT);
+}
+
+/**
+ * collectSync 节校验（E5：负数/非枚举/坏类型回默认，不炸启动；与 maxConcurrent 同判。
+ * subagent-sync-collect 设计 §3.1.5 E5 + §3.1.3）。逐字段 sanitize：坏字段回该字段
+ * 默认，好字段透传（部分覆盖合法）。整节缺失返回 undefined（不落键，与 engineRouting
+ * 同风格——缺省语义由消费方读 DEFAULT_COLLECT_SYNC）。
+ *
+ * [D6 #8] 字段级坏值回默认时 warn 一条（缺省字段不 warn——部分覆盖合法）：config.json
+ * 是用户手编文件，静默回落使「改了配置不生效」无从排查（sanitize 行为不变，只补可观测）。
+ *
+ * 消费时机：startHandler 缺省 collect 解析（config.default，新 session 生效）与
+ * U3/U4 批通知预算（perItemChars/totalChars，flush 时热读）。
+ */
+export function sanitizeCollectSync(value: unknown): CollectSyncConfig | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const v = value as Record<string, unknown>;
+  const fallback = DEFAULT_COLLECT_SYNC;
+  // [D6 #8] 坏值字段清单（仅「显式给了坏值」计——缺省是合法部分覆盖，不 warn）。
+  // 值格式化不用 JSON.stringify：Symbol/BigInt 等 stringify 返回 undefined，String() 全类型安全。
+  const fmt = (val: unknown): string => (typeof val === "string" ? JSON.stringify(val) : String(val));
+  const bad: string[] = [];
+  if (v.default !== undefined && v.default !== "sync" && v.default !== "async") {
+    bad.push(`default=${fmt(v.default)}`);
+  }
+  if (v.perItemChars !== undefined && !isPositiveInt(v.perItemChars)) {
+    bad.push(`perItemChars=${fmt(v.perItemChars)}`);
+  }
+  if (v.totalChars !== undefined && !isPositiveInt(v.totalChars)) {
+    bad.push(`totalChars=${fmt(v.totalChars)}`);
+  }
+  if (bad.length > 0) {
+    logger.warn(
+      `[subagents] config collectSync invalid field(s) reverted to defaults: ${bad.join(", ")}`,
+    );
+  }
+  return {
+    default: v.default === "sync" ? "sync" : v.default === "async" ? "async" : fallback.default,
+    perItemChars: sanitizePositiveInt(v.perItemChars, fallback.perItemChars),
+    totalChars: sanitizePositiveInt(v.totalChars, fallback.totalChars),
+  };
+}
+
+/** 正整数校验（collectSync 预算字段用；与 sanitizeMaxConcurrent 同判）。 */
+function sanitizePositiveInt(value: unknown, fallback: number): number {
+  return isPositiveInt(value) ? (value as number) : fallback;
+}
+
+/** 正整数判定（sanitizePositiveInt 的探测面，坏值 warn 清单复用）。 */
+function isPositiveInt(value: unknown): boolean {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
 }
 
 /**

package/src/execution/engine/__tests__/common/event-journal.test.ts

@@ -25,7 +25,7 @@ function tmpPath(name: string): string {
 
 afterEach(() => {
   if (tmpRoot !== undefined) {
-    rmSync(tmpRoot, { recursive: true, force: true });
+    rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     tmpRoot = undefined;
   }
 });

package/src/execution/engine/__tests__/common/pool-manager.test.ts

@@ -29,7 +29,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
-  rmSync(tmpRoot, { recursive: true, force: true });
+  rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 /** 读池 refs.json 的解析形态。 */
@@ -142,7 +142,7 @@ describe("releasePoolRef 引用计数与整池删除", () => {
   it("池目录不存在时 release → 无原生状态可清，视为成功不抛", () => {
     acquirePool(tmpRoot, "zcode", "ghost", "bg-1");
     // 归零但目录已被外部删除
-    rmSync(resolvePoolDir(tmpRoot, "zcode", "ghost"), { recursive: true, force: true });
+    rmSync(resolvePoolDir(tmpRoot, "zcode", "ghost"), { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     expect(() => releasePoolRef(tmpRoot, "zcode", "ghost", "bg-1")).not.toThrow();
   });
 

package/src/execution/engine/__tests__/conformance/contract.read-degradation.test.ts

@@ -44,7 +44,7 @@ describe("conformance C5：read 降级链（三级都不 throw）", () => {
     dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "c5-read-"));
   });
   afterEach(() => {
-    fs.rmSync(dataDir, { recursive: true, force: true });
+    fs.rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("重放等价性：journal 重放 turns 与 live 累积一致（共用 updateFromEvent reducer）", () => {

package/src/execution/engine/__tests__/conformance/golden-replay.pi.test.ts

@@ -45,7 +45,7 @@ describe("pi golden 回放（conformance C3/C5-journal，免 LLM）", () => {
       // 深比较（含 undefined 键缺省语义——JSON 序列化后 undefined 字段自然消失，两侧同构）
       expect(replayed).toEqual(golden.events);
     } finally {
-      rmSync(dir, { recursive: true, force: true });
+      rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 

package/src/execution/engine/engines/zcode/__tests__/appserver-launcher.test.ts

@@ -123,7 +123,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
-  fs.rmSync(tmpRoot, { recursive: true, force: true });
+  fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 describe("wrapper 合并语义（v2 注入优先）", () => {

package/src/execution/engine/engines/zcode/__tests__/zcode-engine-degrade.test.ts

@@ -45,7 +45,7 @@ beforeEach(() => {
 
 afterEach(async () => {
   for (const engine of engines.splice(0)) await engine.dispose().catch(() => undefined);
-  fs.rmSync(tmpRoot, { recursive: true, force: true });
+  fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 interface ErrorScenario {

package/src/execution/execution-record.ts

@@ -175,6 +175,12 @@ export function createRecord(
     engine?: string;
     /** 引擎 fallback 留痕（probe 失败路由回默认引擎）。GUI 警告条数据源。 */
     engineFallback?: { from: string; reason: string };
+    /**
+     * 同步收集模式标记（subagent-sync-collect U1 foundation）。undefined = async
+     * （缺省语义，旧记录零迁移）。U2 接线点：service.createRecordForMode 从
+     * ExecuteOptions.collect 读入（opts.collect === "sync" ? "sync" : undefined）。
+     */
+    collectMode?: "sync";
     controller?: AbortController;
   },
 ): ExecutionRecord {
@@ -194,6 +200,7 @@ export function createRecord(
     idleTimeoutMs: identity.idleTimeoutMs,
     engine: identity.engine,
     engineFallback: identity.engineFallback,
+    collectMode: identity.collectMode,
 
     // 状态（实时更新）
     status: "running",

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 仍执行。
 
@@ -177,11 +177,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 {
@@ -265,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）
  *