@zhushanwen/subagent-core 0.5.1 → 0.7.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__/workflow-state-root.test.ts

@@ -0,0 +1,232 @@
+// src/execution/__tests__/workflow-state-root.test.ts
+//
+// [F-1 修复] pi 宿主 WorkflowRun state 读侧装配同源布局测试。
+//
+// 背景（装配错位事故面）：round-supervisor sweep 与 idle-gc 曾用 FileRunStore 缺省根
+// `<dataRoot>/workflow-state`（zcode 宿主布局）读 workflow run state，而 pi 宿主真实
+// 落盘 = JsonlRunStore 的 `<sessionDir>/workflow-state/<runId>.jsonl`——两目录生产不
+// 相交 → findStateByIdSync 恒 missing → sweep 按终态补注销**活跃 run**；WorkflowRun
+// GC 恒空转。修复后装配点传 resolvePiWorkflowStateDir()（execution/workflow-state-root.ts，
+// 与 extensions/universal/subagent-workflow/src/session-lifecycle.ts resolveSessionDir
+// 同规则重写）。
+//
+// 本套件用 mkdtemp 真实目录布局（非 mock fs）证明四件事：
+//   ① resolvePiWorkflowStateDir 探测语义两分支（sessionScopedDir 存在/不存在）；
+//   ② FileRunStore({stateDir}) findStateByIdSync 在真实布局命中 running/终态/missing；
+//   ③ sweep 装配链（runPendingReconcileSweepForService，env 指向 tmp agentDir）端到端：
+//      running run 不补注销（修复前被误注销的事故方向）、终态 run 补注销；
+//   ④ idle-gc 同布局：30 天 running run 文件被终态化写回（findStateByIdSync 变 done）。
+//
+// 写删目标全部 mkdtempSync 自建自删（禁触真实数据目录纪律）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { FileRunStore } from "../../orchestration/file-run-store.ts";
+import { Budget } from "../../orchestration/models/budget.ts";
+import { Trace } from "../../orchestration/models/trace.ts";
+import { WorkflowRun } from "../../orchestration/models/workflow-run.ts";
+import { startIdleGc } from "../idle-gc.ts";
+import { RecordStore } from "../record-store.ts";
+import { runPendingReconcileSweepForService } from "../round-supervisor/service-binding.ts";
+import type { RoundSupervisorBinding } from "../round-supervisor/service-binding.ts";
+import { resolvePiWorkflowStateDir } from "../workflow-state-root.ts";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const GC_INTERVAL_MS = 60 * 60 * 1000;
+
+let tmpDir: string;
+let stopGc: (() => void) | undefined;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-state-root-"));
+});
+
+afterEach(() => {
+  stopGc?.();
+  stopGc = undefined;
+  vi.unstubAllEnvs();
+  vi.useRealTimers();
+  fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+});
+
+/** 与 session-lifecycle.resolveSessionDir 同规则的 cwd-slug（测试构造期望布局用）。 */
+function slugOf(cwd: string): string {
+  return `--${cwd.replace(/^\//, "").replace(/\//g, "-")}--`;
+}
+
+/** 构造可持久化的 WorkflowRun（对齐 file-run-store.test.ts makeRun 模式）。 */
+function makeRun(
+  runId: string,
+  opts: { status?: "running" | "done"; startedAt?: string } = {},
+): WorkflowRun {
+  const status = opts.status ?? "running";
+  return WorkflowRun.reconstruct(
+    runId,
+    {
+      scriptSource: "export function execute() { return 'ok'; }",
+      args: { topic: "demo" },
+      scriptName: "test-script",
+      scriptPath: "/fake/test.js",
+      parameters: { type: "object" },
+      budgetTokens: 1000,
+    },
+    {
+      status,
+      ...(status === "done" ? { reason: "completed" as const } : {}),
+      budget: new Budget({ maxTokens: 1000, usedTokens: 1, usedCost: 0, totalCallCount: 1 }),
+      calls: new Map(),
+      trace: new Trace(),
+      errorLogs: [],
+      scriptResult: undefined,
+    },
+    { startedAt: opts.startedAt ?? "2026-08-30T00:00:00.000Z" },
+  );
+}
+
+describe("resolvePiWorkflowStateDir 探测语义（session-lifecycle resolveSessionDir 同规则）", () => {
+  it("sessionScopedDir 存在 → 用 <agentDir>/sessions/<slug>/workflow-state（实例隔离布局）", () => {
+    const cwd = path.join(tmpDir, "proj"); // 形式 cwd（不要求真实存在）
+    const agentDir = path.join(tmpDir, "agent");
+    const sessionScopedDir = path.join(agentDir, "sessions", slugOf(cwd));
+    fs.mkdirSync(sessionScopedDir, { recursive: true });
+    expect(resolvePiWorkflowStateDir({ agentDir, cwd })).toBe(path.join(sessionScopedDir, "workflow-state"));
+  });
+
+  it("sessionScopedDir 不存在 → 回退 <agentDir>/workflow-state（JsonlRunStore 首写 mkdir 的根布局）", () => {
+    const agentDir = path.join(tmpDir, "agent");
+    fs.mkdirSync(agentDir, { recursive: true });
+    expect(resolvePiWorkflowStateDir({ agentDir, cwd: path.join(tmpDir, "fresh-proj") })).toBe(
+      path.join(agentDir, "workflow-state"),
+    );
+  });
+});
+
+describe("FileRunStore({stateDir}) × 真实 JsonlRunStore 布局（findStateByIdSync 读侧判据）", () => {
+  it("真实布局命中：running → {kind:running}；done → {kind:terminal, reason}；无文件 → {kind:missing}", async () => {
+    const stateDir = path.join(tmpDir, "sessions", slugOf("/x/y"), "workflow-state");
+    const store = new FileRunStore({ stateDir });
+    await store.save(makeRun("wf-live")); // running（首写不节流）
+    await store.save(makeRun("wf-done", { status: "done" }));
+
+    expect(store.findStateByIdSync("wf-live")).toEqual({ kind: "running" });
+    expect(store.findStateByIdSync("wf-done")).toEqual({ kind: "terminal", reason: "completed" });
+    expect(store.findStateByIdSync("wf-never")).toEqual({ kind: "missing" });
+    // 落盘路径形状与 pi 壳 JsonlRunStore 同构：<sessionDir>/workflow-state/<runId>.jsonl
+    expect(fs.existsSync(path.join(stateDir, "wf-live.jsonl"))).toBe(true);
+  });
+});
+
+describe("sweep 装配链端到端（runPendingReconcileSweepForService × 真实布局）", () => {
+  /**
+   * 装配 harness：env 指向 tmp agentDir（生产装配 resolvePiWorkflowStateDir() 无参走
+   * env + process.cwd()），run state 由 FileRunStore({stateDir}) 写入解析出的目录——
+   * 证明「生产装配点读的目录 = run state 真实落盘目录」（同源布局闭环）。
+   */
+  function setupSweep(): { agentDir: string; store: FileRunStore } {
+    const agentDir = path.join(tmpDir, "agent");
+    vi.stubEnv("PI_CODING_AGENT_DIR", agentDir);
+    const store = new FileRunStore({ stateDir: resolvePiWorkflowStateDir() }); // 与生产装配同参
+    return { agentDir, store };
+  }
+
+  function makeBinding(sessionFile: string, appended: Array<{ customType: string; data: unknown }>): RoundSupervisorBinding {
+    return {
+      getStore: () => new RecordStore(path.join(tmpDir, "records")),
+      getPi: () =>
+        ({
+          appendEntry: (type: string, data: unknown) => appended.push({ customType: type, data }),
+          events: { emit: vi.fn() },
+          sendMessage: vi.fn(),
+        }) as unknown as NonNullable<ReturnType<RoundSupervisorBinding["getPi"]>>,
+      getSessionRootId: () => "root",
+      getMainSessionFile: () => sessionFile,
+      finalizeClosed: vi.fn(),
+    };
+  }
+
+  function writeRegister(sessionFile: string, id: string): void {
+    fs.writeFileSync(
+      sessionFile,
+      JSON.stringify({ customType: "pending:register", data: { id, type: "workflow", name: id } }) + "\n",
+      "utf-8",
+    );
+  }
+
+  it("活跃 workflow run（running state 文件在盘）→ sweep 不补注销（修复前被误注销）", async () => {
+    const { agentDir, store } = setupSweep();
+    await store.save(makeRun("wf-live"));
+
+    const sessionFile = path.join(agentDir, "main-session.jsonl");
+    writeRegister(sessionFile, "wf-live");
+    const appended: Array<{ customType: string; data: unknown }> = [];
+    runPendingReconcileSweepForService(makeBinding(sessionFile, appended), false);
+    expect(appended).toHaveLength(0); // 活跃 run 不注销——事故方向的回归钉
+  });
+
+  it("终态 workflow run（done state 文件在盘）→ sweep 补注销（reason 取 run reason）", async () => {
+    const { agentDir, store } = setupSweep();
+    await store.save(makeRun("wf-done", { status: "done" }));
+
+    const sessionFile = path.join(agentDir, "main-session.jsonl");
+    writeRegister(sessionFile, "wf-done");
+    const appended: Array<{ customType: string; data: unknown }> = [];
+    runPendingReconcileSweepForService(makeBinding(sessionFile, appended), false);
+    expect(appended).toEqual([
+      { customType: "pending:unregister", data: { id: "wf-done", reason: "completed", status: "completed" } },
+    ]);
+  });
+});
+
+describe("idle-gc 同布局（WorkflowRun GC 读对根）", () => {
+  /**
+   * GC interval 用 fake timers 推进；但 gcWorkflowRuns 的 loadAll/save 是**真实 fs IO**
+   * （libuv 线程池回调不属被 fake 的 timer API）——推进后经 setImmediate（toFake 排除，
+   * 保持真实调度）反复让出事件循环排空在途 IO。
+   */
+  async function flushRealIo(): Promise<void> {
+    for (let i = 0; i < 50; i++) {
+      await new Promise<void>((resolve) => setImmediate(() => resolve()));
+    }
+  }
+
+  it("真实布局 30 天 running run → GC 终态化写回（findStateByIdSync 变 terminal/time_limited）", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "setInterval", "clearInterval"] });
+    const agentDir = path.join(tmpDir, "agent");
+    const cwd = path.join(tmpDir, "proj");
+    const sessionScopedDir = path.join(agentDir, "sessions", slugOf(cwd));
+    fs.mkdirSync(sessionScopedDir, { recursive: true });
+    const stateDir = resolvePiWorkflowStateDir({ agentDir, cwd });
+    const runStore = new FileRunStore({ stateDir });
+    await runStore.save(
+      makeRun("wf-stale", { startedAt: new Date(Date.now() - 31 * DAY_MS).toISOString() }),
+    );
+    expect(runStore.findStateByIdSync("wf-stale")).toEqual({ kind: "running" });
+
+    stopGc = startIdleGc(new RecordStore(path.join(tmpDir, "records")), runStore);
+    await vi.advanceTimersByTimeAsync(GC_INTERVAL_MS + 1);
+    await flushRealIo();
+
+    // 终态已落盘（同目录 append 终态快照行）——GC 读侧与落盘侧同根闭环
+    expect(runStore.findStateByIdSync("wf-stale")).toEqual({ kind: "terminal", reason: "time_limited" });
+  });
+
+  it("窗内 running run 不动（GC 判据在正确根上按 startedAt 生效）", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "setInterval", "clearInterval"] });
+    const agentDir = path.join(tmpDir, "agent");
+    const stateDir = resolvePiWorkflowStateDir({ agentDir, cwd: tmpDir });
+    const runStore = new FileRunStore({ stateDir });
+    await runStore.save(
+      makeRun("wf-fresh", { startedAt: new Date(Date.now() - 1 * DAY_MS).toISOString() }),
+    );
+
+    stopGc = startIdleGc(new RecordStore(path.join(tmpDir, "records")), runStore);
+    await vi.advanceTimersByTimeAsync(GC_INTERVAL_MS + 1);
+    await flushRealIo();
+
+    expect(runStore.findStateByIdSync("wf-fresh")).toEqual({ kind: "running" });
+  });
+});

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/agent-registry.ts

@@ -20,7 +20,10 @@ import { parseResourceMeta } from "../shared/meta-parser.ts";
 import { lintAgentMeta } from "../orchestration/script-lint.ts";
 import type { AgentMeta, RoutingExample } from "../shared/resource-meta.ts";
 import type { AgentConfig } from "./model-resolver.ts";
-import { hasEngine, listEngines, EngineNotFoundError } from "./engine/registry.ts";
+import { EngineNotFoundError, listEngines } from "./engine/registry.ts";
+// [W8] 存在性校验经补扫通道（快照未命中触发一次三级补扫，W4 ensureEngineDiscovered
+// 语义——宿主未接线补扫参数时与裸 hasEngine 等价）。
+import { hasEngineWithRescan } from "./engine/routing.ts";
 
 const logger = getLogger("subagents");
 
@@ -134,7 +137,8 @@ function resolveAgentEngine(
   filePath: string,
 ): string | undefined {
   const engine = agentMeta?.engine ?? extractYamlField(yamlBlock, "engine");
-  if (engine !== undefined && !hasEngine(engine)) {
+  // [W8] 补扫通道：快照未命中先一次三级补扫再判（装了引擎包 → 下次解析即可用）。
+  if (engine !== undefined && !hasEngineWithRescan(engine)) {
     throw new EngineNotFoundError(engine, listEngines(), filePath);
   }
   return engine;

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;
 }
 
 /**