@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/execution/cold-resurrect.ts

@@ -0,0 +1,199 @@
+// [D4-③ 冷路径复活职责轴] message action 冷查/复活链（原 SubagentService 私有的
+// findColdLookupCandidate / assertReconnectAllowed / resurrectColdRecord /
+// coldLookupForAction + isReconnectableClosed 判定）整体搬移至 record-store 邻接处
+// （行为逐字节等价：搬移 + 依赖注入，不重写逻辑）。变化轴：改跨重启重建 /
+// 透明重生回边 / 可重连守卫语义，只改本文件；Service 的 getRecordForAction 保留
+// 归属校验编排（内存未命中分支委托 coldLookupForAction）。
+
+import * as fs from "node:fs";
+
+import { findForeignLiveInstance, writeAliveMarker } from "./alive-store.ts";
+import { createRecord, resurrectClosed } from "./execution-record.ts";
+import type { StatusFilter } from "./record-store.ts";
+import type { ExecutionRecord, SubagentRecord } from "./types.ts";
+import { isReconnectableFinalReason, ResurrectDeniedError } from "./types.ts";
+
+/** SP-2 冷路径按 id 查 record 的 collectRecords 扫描上限（全扫兜底的容量 cap）。
+ *  原定义于 subagent-service.ts，随冷查链搬移；Service.lookupRecordAnyState
+ *  （全态查询）同样消费本常量。 */
+export const COLD_LOOKUP_SCAN_LIMIT = 1000;
+
+/** 冷查/复活的依赖注入（Service 侧供给，store 查询 + 归属上下文）。 */
+export interface ColdResurrectDeps {
+  /** store 的 idToFile 索引直查（light 快照）。 */
+  findLightById: (id: string) => SubagentRecord | undefined;
+  /** store 的磁盘全扫（内存未命中 / 索引未热时兜底）。rootFilter 恒 undefined
+   *  （冷查不做 root 过滤——归属校验在候选定位之后，见 coldLookupForAction）。 */
+  collectRecords: (limit: number, statusFilter: StatusFilter, rootFilter: undefined) => SubagentRecord[];
+  /** 重建 record 注册进内存 store。 */
+  register: (record: ExecutionRecord) => void;
+  /** 重建后的 transition entry 上报（live ≡ reload 等价性）。 */
+  reportRecordTransition: (record: ExecutionRecord) => void;
+  /** 当前所属根 session id（归属校验用，运行时可变——initSession 建立）。 */
+  getSessionRootId: () => string | null;
+  /** 本进程嵌套基线 recordId（直接父校验用；根进程 undefined）。 */
+  getBaselineRecordId: () => string | undefined;
+}
+
+/** 冷查候选定位（coldLookupForAction 步骤 1）：idToFile 索引直查 running 命中，
+ *  未命中再全目录 collectRecords 兜底（running，或 allowReconnect 且可重连 closed）。
+ *
+ *  [T5③ / PS-7b] running 候选异进程活实例守卫：冷查 running 候选（跨重启 / 内存重建）
+ *  此前不经任何探针直接 resurrect + resume spawn——若其 .alive marker 仍指向活着的
+ *  异进程实例（父进程重启后旧子进程尚存的窗口），resume 会 spawn 第二个 pi 子进程
+ *  写同一 session JSONL（本代码最忌惮的双写者形态，v4 A-5/P7 事故模式）。closed 候选
+ *  的同款守卫已在 assertReconnectAllowed（v8.5 D）；本守卫闭合 running 候选的防御
+ *  不对称。marker 的 pid 是子进程 pi 的 pid（非父进程），本进程持有的 running record
+ *  恒在内存（archive 才移出），可达本冷查分支的 running 候选必然来自磁盘重建——
+ *  探针命中即拒绝（ResurrectDeniedError，与 closed 候选守卫同异常类型，错误含 pid
+ *  与恢复指引）。 */
+function findColdLookupCandidate(
+  deps: ColdResurrectDeps,
+  id: string,
+  allowReconnect: boolean,
+): SubagentRecord | undefined {
+  const direct = deps.findLightById(id);
+  const found =
+    (direct?.status === "running" ? direct : undefined) ??
+    deps
+      .collectRecords(COLD_LOOKUP_SCAN_LIMIT, "all", undefined)
+      .find((r) => r.id === id && (r.status === "running" || (allowReconnect && isReconnectableClosed(r))));
+  if (found?.status === "running" && found.sessionFile) {
+    const foreign = findForeignLiveInstance(found.sessionFile);
+    if (foreign) {
+      throw new ResurrectDeniedError(
+        `subagent ${id} is currently running in another process instance (pid ${foreign.pid}, ` +
+          `startedAt=${new Date(foreign.startedAt).toISOString()}); resuming here would double-write ${found.sessionFile}. ` +
+          `Recovery: retry once that process exits; if it never exits, action:'close' this subagent, then action:'start' a fresh one.`,
+      );
+    }
+  }
+  return found;
+}
+
+/** [v8.5 D] 冷查候选过滤：closed 且死因落在可重连集。判定源 = closedReason（buildRecord
+ *  归一化后的对外字段：A 档真实死因直通、旧空 sidecar 兑底 disconnected——SubagentRecord
+ *  不暴露 raw finalizedReason）；cancelled/user-close/gc 等主动关闭与自然完成死因天然不在集合内。
+ *  防线在集合本身而非调用点。 */
+function isReconnectableClosed(r: SubagentRecord): boolean {
+  return isReconnectableFinalReason(r.closedReason);
+}
+
+/** 可重连守卫（coldLookupForAction 步骤 2，[v8.5 D]）：先于任何状态突变与注册。
+ *  worktree 绑定丢失 / 异进程活实例以 ResurrectDeniedError 抛出（endedMessageGuard
+ *  必须原样透传，不得改写为 fork-from 指引误导 agent 走已被判死的通道）；拒绝时
+ *  内存不得残留该记录（findRecord 契约）。 */
+function assertReconnectAllowed(found: SubagentRecord, id: string): void {
+  if (found.status !== "closed") return;
+  if (found.worktree === true) {
+    throw new ResurrectDeniedError(
+      `subagent ${id} cannot be transparently resumed: it was created with worktree isolation, ` +
+        `and its worktree checkout no longer exists after restart (resuming in place would make spawn cwd fall back to the main repo). ` +
+        `Recovery: action:'start' a fresh subagent (with a new worktree if isolation is still needed); ` +
+        `its conversation history remains intact at ${found.sessionFile}.`,
+    );
+  }
+  const foreign = found.sessionFile ? findForeignLiveInstance(found.sessionFile) : undefined;
+  if (foreign) {
+    throw new ResurrectDeniedError(
+      `subagent ${id} is not transparently resumable: its previous instance still finishing in another process ` +
+        `(pid ${foreign.pid}, startedAt=${new Date(foreign.startedAt).toISOString()}). ` +
+        `Resuming in place would double-write ${found.sessionFile}. ` +
+        `Recovery: retry once that process exits; if it never exits, action:'start' a fresh subagent and treat the history at ${found.sessionFile} as read-only reference.`,
+    );
+  }
+}
+
+/** 磁盘候选重建为可变 record 并 register + 上报（coldLookupForAction 步骤 4）。 */
+function resurrectColdRecord(
+  deps: ColdResurrectDeps,
+  found: SubagentRecord,
+  id: string,
+): ExecutionRecord {
+  const record = createRecord(id, {
+    agent: found.agent,
+    model: found.model,
+    thinkingLevel: found.thinkingLevel,
+    mode: found.mode,
+    task: found.task,
+    slug: found.slug,
+    startedAt: found.startedAt,
+    rootSessionId: found.rootSessionId,
+    parentRecordId: found.parentRecordId,
+    depth: found.depth,
+    // [v4 A-3] 跨重启恢复入口——message 路径磁盘重建无条件置 chatMode=true（现状机制，
+    // V3 方案 A 方向兑现）。改动此处必须带 S3 回归场景（跨重启 message 续聊验证）。
+    // V3 SP-5 探针定案：机制已存在，本注释即定案，不再悬置。
+    chatMode: true,
+    controller: new AbortController(),
+  });
+  record.sessionFile = found.sessionFile;
+  record.round = found.round;
+  // [review round2] 跨重启 worktree 绑定丢失防护：原 record 创建时启用了 worktree 隔离
+  //（session entry 的 worktree 标志），但 WorktreeHandle 不可序列化、重建后恒缺失。
+  // 标记 hadWorktree，冷路径续轮守卫据此拒绝续聊（防 spawn cwd 静默回落主 repo 破坏
+  // 隔离——正是 worktree 要防的并发写冲突场景）。close 不受影响（closeChatIdle 走
+  // doFinalizeRecord，泄漏的 worktree 由 reaper 兜底回收）。
+  record.hadWorktree = found.worktree === true;
+  // [v8.5 D] 透明重生回边：独立函数不走 tryTransition 单向语义（closed 单向性对正常
+  // 执行流完整保留）；准入唯一依据 = A 档 sidecar 真实死因 ∈ 可重连集。死亡语义位由
+  // resurrectClosed 清除；register 后立刻上报 transition entry，live/reload 视图同步
+  // 翻回 running（等价性由 applyEntry reducer 保证，对齐 SP-2 重建即报告先例）。
+  const wasClosed = found.status !== "running";
+  if (wasClosed) {
+    // [review MF-8] 磁盘终态位同步翻转：record-store buildRecord 分支 2（.finalized
+    // 存在 → closed）优先级高于 .alive 活态分支 3，重生若不删 sidecar，任何磁盘扫描
+    // （异进程 / reload / session-reader）都会把本进程内存里 running 的 record 报成
+    // closed/disconnected——破坏 live ≡ reload，且为跨进程二次 resurrect 开门。
+    // best-effort 对齐 BC-4 语义；.alive 刷新为当前进程（后续 resume spawn 会覆盖写）。
+    if (record.sessionFile) {
+      try {
+        fs.rmSync(`${record.sessionFile}.finalized`, { force: true });
+        writeAliveMarker(record.sessionFile, { pid: process.pid, id, startedAt: Date.now() });
+      } catch (_e) {
+        void _e; // best-effort：sidecar 翻转失败不阻断重生主流程
+      }
+    }
+    resurrectClosed(record);
+  }
+  deps.register(record);
+  if (wasClosed) {
+    deps.reportRecordTransition(record);
+  }
+  return record;
+}
+
+/** [D4-③] 冷查编排（原 Service.coldLookupForAction）：getRecordForAction 内存未命中
+ *  分支——候选定位 → 可重连守卫 → 归属/直接父校验 → 重建注册。
+ *  @returns 重建的 record；磁盘也无则 undefined
+ *  @throws ResurrectDeniedError 可重连候选被 worktree/异进程活实例守卫拦截
+ *  @throws Error parentRecordId 跨层不匹配（direct parent 错误，与外层校验同文案） */
+export function coldLookupForAction(
+  deps: ColdResurrectDeps,
+  id: string,
+  allowReconnect: boolean,
+): ExecutionRecord | undefined {
+  const found = findColdLookupCandidate(deps, id, allowReconnect);
+  if (!found) return undefined;
+  // [v8.5 D] 可重连候选的守卫先于任何状态突变与注册（细节见 assertReconnectAllowed）
+  assertReconnectAllowed(found, id);
+  // [review MF-9] 归属校验先于任何持久化副作用：coldLookup 是 getRecordForAction 的
+  // 内存未命中分支，若先 resurrect/register/report 再由调用方抛归属错误，会在磁盘/
+  // 内存留下幽灵 running record + running transition entry（跨进程双 resurrect 窗口）。
+  // rootSessionId 不匹配 → 返回 undefined，由 getRecordForAction 抛统一「not found or
+  // not owned」（不区分失败形态，防跨 session 探测）；parentRecordId 跨层不匹配 →
+  // 原样抛 direct parent 错误（与外层校验同文案，保留跨层导航指引）。
+  if (found.rootSessionId !== deps.getSessionRootId()) {
+    return undefined;
+  }
+  const baselineRecordId = deps.getBaselineRecordId();
+  if (found.parentRecordId !== baselineRecordId) {
+    throw new Error(
+      `subagent ${id} is owned by its direct parent; message it through that parent ` +
+        `(see /subagents list, parent=${found.parentRecordId ?? "(root layer)"}). [v4 A-5] cross-layer ` +
+        `ownership guard: this process's baseline=${baselineRecordId ?? "(root)"} is not the direct parent of ${id}; ` +
+        `operating here would race the owning child process's handle and double-write the session file.`,
+    );
+  }
+  return resurrectColdRecord(deps, found, id);
+}

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/capability-gate.test.ts

@@ -0,0 +1,91 @@
+// capability-gate.test.ts —— [D3-④ 预检 capabilities 化] 拦截矩阵单测。
+// 设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-④（r3 裁定：
+// EngineCapabilities +maxTurns 位 pi=true/zcode=false，不保留硬编码 shape 检查）+
+// §3.4 错误规格第 1 行 + §4 V4④⑤（正反向验收）。
+//
+// 覆盖（构建者白盒 + 使用者黑盒）：
+//   1. per-engine 拦截矩阵：pi 全放行（含 maxTurns/fork/conversation/worktree——V4⑤
+//      反向守护，pi 既有合法能力零拦截）；zcode 四参数全拦（fork/conversation/
+//      maxTurns/worktree）
+//   2. 错误族：engine_capability_unsupported + recovery 含可操作指引（换参数/换引擎）
+//   3. fork 判据（借位裁定）：session 分叉通道族任一可用即放行——pi conversation=
+//      native 放行（steer 虽 unsupported 不参与否决）；通道族全缺才拦
+
+import { describe, expect, it } from "vitest";
+
+import { assertTaskShapeSupported, type TaskShapeForGate } from "../../common/capability-gate.ts";
+import { EngineError } from "../../common/errors.ts";
+import type { EngineCapabilities } from "../../types.ts";
+import { PiEngine } from "../../engines/pi/pi-engine.ts";
+import { ZcodeEngine } from "../../engines/zcode/zcode-engine.ts";
+
+/** 真实引擎的 capabilities 面单测直取（D3 声明是判据本体——pi=true/zcode=false 扩位）。 */
+const PI_CAPS = new PiEngine({ getService: () => null }).capabilities();
+const ZCODE_CAPS = new ZcodeEngine({ engineDataDir: () => "/tmp/zcode-gate" }).capabilities();
+
+/** 会话分叉通道族可用的 zcode 形态变体（fork 判据用）。 */
+const ZCODE_CAPS_WITH_CONVERSATION: EngineCapabilities = { ...ZCODE_CAPS, conversation: "native" };
+
+function gate(
+  caps: EngineCapabilities,
+  task: TaskShapeForGate,
+  engineId = "zcode",
+): void {
+  assertTaskShapeSupported(engineId, caps, task);
+}
+
+function gateError(caps: EngineCapabilities, task: TaskShapeForGate, engineId = "zcode"): EngineError {
+  try {
+    gate(caps, task, engineId);
+  } catch (err) {
+    expect(err).toBeInstanceOf(EngineError);
+    return err as EngineError;
+  }
+  throw new Error("expected assertTaskShapeSupported to throw");
+}
+
+describe("capability-gate（D3-④ 拦截矩阵）", () => {
+  it("能力位声明：pi maxTurns=true、zcode maxTurns=false（r3 扩位裁定）", () => {
+    expect(PI_CAPS.maxTurns).toBe(true);
+    expect(ZCODE_CAPS.maxTurns).toBe(false);
+  });
+
+  it("[V4⑤ 反向] pi 引擎全参数放行：maxTurns/fork/forkFromSessionFile/conversation/worktree 零拦截", () => {
+    expect(() =>
+      gate(PI_CAPS, { maxTurns: 3, fork: true, conversation: true, worktree: true }, "pi"),
+    ).not.toThrow();
+    expect(() => gate(PI_CAPS, { forkFromSessionFile: "/tmp/sess.jsonl", worktree: { path: "/tmp/wt" } }, "pi")).not.toThrow();
+  });
+
+  it("[V4④ 正向] zcode 引擎四参数全拦：fork/conversation/maxTurns/worktree → engine_capability_unsupported", () => {
+    const cases: Array<[TaskShapeForGate, RegExp]> = [
+      [{ fork: true }, /不支持 fork/],
+      [{ forkFromSessionFile: "/tmp/sess.jsonl" }, /fork-from 同为父 session 上下文继承/],
+      [{ conversation: true }, /不支持 conversation/],
+      [{ maxTurns: 10 }, /不支持 maxTurns/],
+      [{ worktree: true }, /不支持 worktree 隔离/],
+      [{ worktree: { path: "/tmp/wt" } }, /不支持 worktree 隔离/],
+    ];
+    for (const [task, pattern] of cases) {
+      const err = gateError(ZCODE_CAPS, task);
+      expect(err.code).toBe("engine_capability_unsupported");
+      expect(err.message).toMatch(pattern);
+      expect(err.message).toContain("capabilities");
+      // 错误信息可操作（§3.4）：恢复指引指向换参数/换引擎
+      expect(err.recovery).toMatch(/engine: pi|不传|去掉/);
+    }
+  });
+
+  it("zcode 放行面：无能力参数的任务全放行；maxTurns undefined（未传）不拦", () => {
+    expect(() => gate(ZCODE_CAPS, {})).not.toThrow();
+    expect(() => gate(ZCODE_CAPS, { maxTurns: undefined, fork: false, conversation: false, worktree: false })).not.toThrow();
+  });
+
+  it("fork 判据（借位裁定）：session 分叉通道族任一可用即放行——conversation=native 的引擎 fork 放行", () => {
+    // pi 的 steer 声明 unsupported（spawn 链路未接通），fork 仍放行——通道族判定不因
+    // 单一通道缺失而误拦（上面 pi 用例已覆盖）。此处补 zcode 形态 + conversation 通道
+    // 可用的对照：fork 从拦截翻为放行。
+    expect(() => gate(ZCODE_CAPS_WITH_CONVERSATION, { fork: true })).not.toThrow();
+    expect(() => gate({ ...ZCODE_CAPS, steer: "native" }, { fork: true })).not.toThrow();
+  });
+});

package/src/execution/engine/__tests__/common/data-dir.test.ts

@@ -49,7 +49,7 @@ describe("getEngineDataDir", () => {
 
   it("缺 env → 回退宿主数据根（HostServices.dataRoot()，假宿主值）并 warn 一次", () => {
     const warnings: string[] = [];
-    const warn = (m: string): void => warnings.push(m);
+    const warn = (m: string): void => { warnings.push(m); };
     const dir1 = getEngineDataDir({}, warn);
     expect(dir1).toBe(FAKE_DATA_ROOT);
     expect(warnings.length).toBe(1);

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;
   }
 });