@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/execution/subprocess-agent-runner.ts

@@ -5,37 +5,44 @@
 // 从"自己 spawn pi"改为"委托 SubagentService.executeAndAwait"。
 // MF-3: 从 orchestration/infra 迁入 execution，同层委托 SubagentService。
 //
+// [D6 任务形状合流] AgentCallOpts 已是 EnginePort.run 的单一任务形状——本类直传 opts
+// 给 engine.run（无 ExecuteOptions/AgentTaskSpec 中间态映射）；pi 边界的一次直出在
+// PiEngine.agentCallToExecuteOptions。mergeTimeoutSignal（原 execute-options-mapper
+// 的运行期件，D-A9）随 mapper 删除迁入本文件（唯一消费点）。
+//
 // 接线层级：
 //   [跨模块 port] implements AgentRunner（orchestration/models/ports.ts）
-//   [模块内直调] mapToExecuteOptions + mergeTimeoutSignal（execute-options-mapper）
-//   [P4 路由层]  engine/routing.ts routeEngine（三层优先级 + probe + fallback 三守卫，D9）
+//   [模块内直调] mergeTimeoutSignal（本文件，D-A9）
+//   [P4 路由层]  engine/routing.ts routeEngineForHost（D3-② 路由单点：三层优先级 +
+//                pi 同步短路 + probe + fallback 三守卫，D9）
+//   [公共预检]   engine/common/capability-gate（D3-④：capabilities 驱动的调用前拒绝）
 //   [引擎层]     EnginePort.run（pi = 本地 DI 绑定实例；非 pi = registry.getEngine 动态获取）
+//   [公共 journal] engine/common/journal-wiring（D3-③：writer + retarget + 回填单实现）
 //   [模块内直调] this.subagentService.executeAndAwait（PiEngine 内部委托目标）
 //
 // 设计基线：
-//   D-A2（映射归 adapter）/ D-A8（onEvent 桥接）/ D-A9（timeoutMs 合并 signal）/
+//   D-A8（onEvent 桥接）/ D-A9（timeoutMs 合并 signal）/
 //   D-008（model 填底，不调 resolveModel）/ BC-9（timeoutMs 行为）/ BC-10（live-record 进度）
 
 import type { AgentRunner } from "../orchestration/models/ports.ts";
 import type { AgentCallOpts, AgentResult } from "../orchestration/models/types.ts";
 import type { AgentEvent } from "../shared/agent-event.ts";
-import { getEngineDataDir } from "./engine/common/data-dir.ts";
-import { JournalWriter } from "./engine/common/event-journal.ts";
-import { createPiEngine, PI_POOL_KEY } from "./engine/engines/pi/registration.ts";
-import { executeOptionsToTaskSpec } from "./engine/engines/pi/task-spec-mapper.ts";
-import { resolveJournalPath } from "./engine/paths.ts";
+import { assertTaskShapeSupported } from "./engine/common/capability-gate.ts";
+import { HOST_TIMEOUT_ABORT_REASON } from "./engine/common/kill-chain.ts";
+import { JOURNAL_INITIAL_POOL_KEY, wireEventJournal } from "./engine/common/journal-wiring.ts";
+import { createPiEngine } from "./engine/engines/pi/registration.ts";
 import type { EnginePort, RunContext } from "./engine/port.ts";
-import { routeEngine, resolveEngineRouting, type EngineRouteResult, type EngineRoutingInput } from "./engine/routing.ts";
-import { getEngine, hasEngine, listEngines } from "./engine/registry.ts";
-import type { AgentOutcome, EngineHandle } from "./engine/types.ts";
-import { mapToExecuteOptions, mergeTimeoutSignal } from "./execute-options-mapper.ts";
+import { validateModelForEngine } from "./engine/model-validation.ts";
+import { routeEngineForHost, type EngineRouteResult, type EngineRoutingInput } from "./engine/routing.ts";
+import { getEngine } from "./engine/registry.ts";
+import type { AgentOutcome } from "./engine/types.ts";
 import { getModelConfigService } from "./model-config-service.ts";
 import type { ModelInfo } from "./model-resolver.ts";
 import { modelRefFromVerified } from "../shared/model-ref";
-import { registerSpawnedChildForRecord } from "./session-runner.ts";
+import { registerSpawnedChildForRecord } from "./engine/engines/pi/session-runner.ts";
 import type { SubagentStream } from "./stream-sink.ts";
 import type { SubagentService } from "./subagent-service.ts";
-import type { ExecuteOptions } from "./types.ts";
+import { toErrorMessage } from "../core/error-message.ts";
 
 // ── 构造依赖（per-session 注入）──
 
@@ -71,10 +78,12 @@ export interface SubprocessAgentRunnerDeps {
  * 非 pi 引擎（P4 路由可达：frontmatter/调用参数/全局默认指定）经 registry.getEngine
  * 动态获取——「引擎身份」的归属边界在注册表，SAR 不感知具体引擎实现。
  *
- * [P4 配置路由] 每次运行经 engine/routing.ts 解析三层优先级（调用参数 opts.engine >
- * agent frontmatter engine > 全局默认 'pi'）+ probe + fallback 三守卫（D9）。路由失败
- * （engine_not_found / engine_probe_failed / model_not_available）不 reject，入
- * result.error——与 executeAgentCall 契约一致。
+ * [P4 配置路由] 每次运行经 engine/routing.ts 的 routeEngineForHost（D3-② 路由单点：
+ * 唯一实现承载三层优先级（调用参数 opts.engine > agent frontmatter engine > 全局默认
+ * 'pi'）+ pi 同步短路 + registry 注入 + probe/fallback 三守卫，D9；本类与
+ * SubagentService.execute 是其仅有的两调用点）。路由失败（engine_not_found /
+ * engine_probe_failed / model_not_available）与预检命中（engine_capability_unsupported，
+ * D3-④）不 reject，入 result.error——与 executeAgentCall 契约一致。
  */
 export class SubprocessAgentRunner implements AgentRunner {
   private readonly subagentService: SubagentService;
@@ -85,7 +94,8 @@ export class SubprocessAgentRunner implements AgentRunner {
   constructor(deps: SubprocessAgentRunnerDeps) {
     this.subagentService = deps.subagentService;
     this.ctxModel = deps.ctxModel;
-    this.piEngine = createPiEngine(() => this.subagentService);
+    // [D4 聚合连带] 经 asEngineService 显式视图适配（原结构化直绑依赖查询面 public）。
+    this.piEngine = createPiEngine(() => this.subagentService.asEngineService);
   }
 
   /**
@@ -99,16 +109,21 @@ export class SubprocessAgentRunner implements AgentRunner {
   }
 
   /**
-   * 执行单次 agent 调用：路由（P4）→ EnginePort.run → PiEngine 委托
+   * 执行单次 agent 调用：路由（P4）→ 预检（D3-④）→ EnginePort.run → PiEngine 委托
    * SubagentService.executeAndAwait。
    *
    * 接线链路：
-   *   routeEngine（三层 + probe + 守卫）→ mergeTimeoutSignal → mapToExecuteOptions →
-   *   AgentTaskSpec → engine.run（PiEngine：spec → ExecuteOptions 还原 + engine 留痕）→
-   *   executeAndAwait → AgentOutcome → AgentResult
+   *   routeEngineForHost（D3-② 路由单点：三层 + pi 同步短路 + probe + 守卫）→
+   *   assertTaskShapeSupported（D3-④ 预检 capabilities 化）→ mergeTimeoutSignal →
+   *   engine.run(opts 直传——D6 合流：AgentCallOpts 即 EnginePort 任务形状，零映射；
+   *   PiEngine 内一次直出 ExecuteOptions + engine 留痕) → executeAndAwait →
+   *   AgentOutcome → AgentResult
    *
    * 错误处理：不 reject。
    *   - 路由失败（未注册 id / probe 失败 + 守卫或 strict）→ AgentResult.error（错误码前缀）
+   *   - 预检命中（capabilities 不支持的任务形状参数）→ AgentResult.error
+   *     （engine_capability_unsupported——[D3-④] workflow 域 zcode+worktree 由漏拦变
+   *     拦截，本单元唯一有意行为变化；拒绝在 journal/run 之前，无进程无 journal 产物）
    *   - executeAndAwait 内部失败 → 返回 AgentResult(success:false) → 已映射 error 字段
    *   - executeAndAwait throw（嵌套超限 BC-12）→ catch → AgentResult.error
    *   - spawn 级失败已由 runSpawn 内部收口为 failed AgentResult（不逃逸）
@@ -121,69 +136,57 @@ export class SubprocessAgentRunner implements AgentRunner {
   ): Promise<AgentResult> {
     const startedAt = Date.now();
 
-    // ── P4 路由：三层优先级 + probe + fallback 三守卫（D9①/D7）──
-    // 路由在最前——引擎身份决定 journal 路径与后续一切执行面；失败（未注册 id /
-    // probe 失败 + strict/守卫）按「不 reject」契约转 result.error。
-    // pi 快路径同步短路（不经 routeEngine 的 await）：pi 恒免探、无 fallback 可言、
-    // engineFor('pi') 本地 DI 绑定恒可用——不引入微任务边界，缺省路径时序与 P1 接线
-    // 前完全一致（下游依赖「run 内首个 await 前已触达 executeAndAwait」的时序契约）。
-    let routingInput: EngineRoutingInput;
+    // ── P4 路由（D3-② 单点：routeEngineForHost）+ D3-④ 预检 ──
+    // 路由在最前——引擎身份决定 journal 路径与后续一切执行面。pi 快路径同步短路
+    //（routed 非 Promise，零微任务——缺省路径时序与 P1 接线前完全一致，下游依赖
+    // 「run 内首个 await 前已触达 executeAndAwait」的时序契约）。路由失败（未注册
+    // id / probe 失败 + strict/守卫）与预检命中（capabilities 驱动，含 worktree——
+    // workflow 域漏拦缺口修复）一并按「不 reject」契约转 result.error。
     let route: EngineRouteResult;
     try {
-      routingInput = this.buildRoutingInput(opts);
-      const routing = resolveEngineRouting(routingInput);
-      if (routing.engineId === "pi") {
-        route = {
-          engine: this.piEngine,
-          engineId: "pi",
-          requestedEngineId: "pi",
-          source: routing.source,
-        };
-      } else {
-        route = await routeEngine({
-          routing: routingInput,
-          taskModel: opts.model,
-          strict: getModelConfigService()?.getGlobalConfig().engineRouting?.strict === true,
-          probe: (engineId) => this.engineFor(engineId).probe(),
-          getEngineFn: (engineId) => this.engineFor(engineId),
-          // pi 经本地 DI 绑定恒可用（不依赖 registry 全局注册态——SAR 持有服务引用），
-          // has/list 注入同一口径，engine_not_found 文案不会把本地 pi 漏报成未注册
-          hasEngineFn: (engineId) => engineId === "pi" || hasEngine(engineId),
-          listEnginesFn: () => (hasEngine("pi") ? listEngines() : ["pi", ...listEngines()]),
-        });
+      const routed = routeEngineForHost({
+        routing: this.buildRoutingInput(opts),
+        taskModel: opts.model,
+        strict: getModelConfigService()?.getGlobalConfig().engineRouting?.strict === true,
+        probe: (engineId) => this.engineFor(engineId).probe(),
+        piEngine: this.piEngine,
+      });
+      route = routed instanceof Promise ? await routed : routed;
+      // [D3-④] SAR 路径预检调用点（run 前同模块调用；唯一实现 = common/capability-gate）。
+      // pi 全参数放行（V4⑤ 反向守护）；zcode 拦 fork/conversation/maxTurns/worktree。
+      // [D6 合流] opts（AgentCallOpts）直传预检——TaskShapeForGate 是结构子集，
+      // conversation/fork/worktree/maxTurns 均在合流形状字段表内。
+      assertTaskShapeSupported(route.engineId, route.engine.capabilities(), opts);
+      // [u-h2 D2-2 调用点②] workflow 域非 pi 引擎的派发同步期 model 校验——与 chat
+      // 路径（subagent-service.executeViaEngine）共享同一入口 validateModelForEngine
+      // 与同一错误文案（V2-4④：agent({engine:'zcode', model:<pi id>}) 同步期报
+      // 「引擎与模型不配套」，不再落 engine.run 的 prepare 期晚炸）。校验对象是显式
+      // opts.model（frontmatter model 的解析归 pi 链，workflow 域非 pi 路径现状不消费
+      // ——维持现状语义不扩散）。「不 reject」契约：throw 由本 try 的 catch 收口
+      // errorResult，不进入 journal 创建与 engine.run（零 record/spawn 副作用）。
+      if (route.engineId !== "pi") {
+        validateModelForEngine(route.engine, opts.model);
       }
     } catch (err) {
-      // buildRoutingInput 的 agent 解析期校验（未注册 frontmatter engine）与路由失败
-      // （probe + strict/守卫）一并在此收口——「不 reject」契约
+      // buildRoutingInput 的 agent 解析期校验（未注册 frontmatter engine）、路由失败
+      //（probe + strict/守卫）与预检拒绝（engine_capability_unsupported）一并在此
+      // 收口——「不 reject」契约
       return errorResult(err, startedAt);
     }
 
     // ── P2 event journal 接线（设计 D6 第②级；对齐点③：路径权威 = 引擎池 key）──
-    // host 在 onEvent 回调内统一落盘（全引擎免费获得②级数据源）。初始 poolKey 用 pi
-    // 缺省占位（pi 恒 'shared'）；非池化稳定引擎（zcode）在 prepare 期经
-    // RunContext.onPoolResolved 声明实际池 key → writer.retarget——保证 journal 落盘
-    // 路径与 handle.poolKey 同源（handle.journalPath 由本方法 run 返回后回填）。
+    // [D3-③] writer + retarget + 回填收敛 common/journal-wiring（与 chat 域同一实现）：
+    // 初始 poolKey 占位 'shared'（pi 恒终值）；非池化稳定引擎（zcode）在 prepare 期经
+    // RunContext.onPoolResolved 声明实际池 key → retarget——保证 journal 落盘路径与
+    // handle.poolKey 同源（handle.journalPath 由本方法 run 返回后回填）。
     //
     // taskId 为宿主侧任务标识（journal 文件名与池引用计数 key）——executeAndAwait
     // 不外露内部 record id（取真实 id 需 hook record store 且改 createRecordForMode
     // 签名，影响面大；P4 决策：保留占位，`sa-` 前缀与 record id 同构。影响面：record
-    // GC 时无法按 taskId 联动删 journal（journal 依赖 30 天 TTL 自然回收），read ②级
-    // 经 handle.journalPath 自描述定位不受影响）。
+    // GC 时无法按 taskId 联动删 journal（journal 依赖 TTL 兜底回收，见 D8 分域裁决），
+    // read ②级经 handle.journalPath 自描述定位不受影响）。
     const taskId = `sa-${crypto.randomUUID()}`;
-    const journal = new JournalWriter({
-      path: resolveJournalPath(getEngineDataDir(), route.engineId, PI_POOL_KEY, taskId),
-      taskId,
-      engineId: route.engineId,
-    });
-    const retargetJournal = (poolKey: string): void => {
-      journal.retarget(resolveJournalPath(getEngineDataDir(), route.engineId, poolKey, taskId));
-    };
-    // 包装：先写 journal 再转发原 onEvent（原 onEvent 未传时也恒传包装版——
-    // 下游 onEvent 通道是事件生成后的纯转发，无行为分支，仅多一次入队）
-    const journalingOnEvent = (event: AgentEvent): void => {
-      journal.append(event);
-      onEvent?.(event);
-    };
+    const journal = wireEventJournal({ engineId: route.engineId, taskId, forwardEvents: onEvent });
 
     try {
       // ── [U1 D2] RunContext.modelRef 接入：ctxModel 继承路径的孪生守卫 ──
@@ -202,40 +205,39 @@ export class SubprocessAgentRunner implements AgentRunner {
       // ── D-A9: timeoutMs 合并 signal（超时 abort 带 HOST_TIMEOUT_ABORT_REASON 标记）──
       const mergedSignal = mergeTimeoutSignal(signal, opts.timeoutMs);
 
-      // ── D-A2 + D-008: AgentCallOpts → ExecuteOptions 映射 ──
-      const mappedOpts: ExecuteOptions = mapToExecuteOptions(opts, this.ctxModel);
-
       // ── P1/P4 引擎接线：EnginePort.run ──
       const runCtx: RunContext = {
         taskId,
-        poolKey: PI_POOL_KEY,
+        poolKey: JOURNAL_INITIAL_POOL_KEY,
         signal: mergedSignal,
-        onEvent: journalingOnEvent,
+        onEvent: journal.onEvent,
         ctxModel: this.ctxModel,
         ...(route.engineFallback !== undefined ? { engineFallback: route.engineFallback } : {}),
-        onPoolResolved: retargetJournal,
+        onPoolResolved: journal.onPoolResolved,
         // [U0 D10] 终止链路径①：引擎 spawn 的子进程注册进 session-runner 的
         // spawnedChildren 记账（dispose killAll 收割兜底对 workflow 域引擎任务生效）；
         // taskId（'sa-' 前缀）即记账 key，与 chat 域 kickOffEngineRun 的 record.id 同构
         onChildSpawned: (child) => registerSpawnedChildForRecord(taskId, child),
         ...(stream !== undefined ? { stream } : {}),
-        // 解耦形态（有 schemaEnv 无 schema）的兜底通道——耦合形态下引擎从 task.schema
-        // 派生等值，此值被忽略（见 RunContext.schemaEnv 注释）
-        ...(mappedOpts.schemaEnv !== undefined ? { schemaEnv: mappedOpts.schemaEnv } : {}),
+        // [D6 合流] 解耦形态（有 schemaEnv 无 schema）不再经 RunContext.schemaEnv
+        // 兜底通道——schemaEnv 已在合流形状 AgentCallOpts.schemaEnv 内，pi 直出
+        // （agentCallToExecuteOptions）以「schema 派生优先、schemaEnv 兜底」取值，
+        // 与原 ctx 兜底链路逐字节等值。
       };
       const { handle, outcome } = await route.engine.run(
-        // 泛化为中立声明（PiEngine 内部再还原回 ExecuteOptions——往返保真，
-        // 由 engines/pi/__tests__/task-spec-mapper.test.ts 逐字段锁定）
-        executeOptionsToTaskSpec(mappedOpts),
+        // [D6 合流] opts 直传——AgentCallOpts 即 EnginePort 任务形状（缺省路径零映射；
+        // pi 边界一次直出由 PiEngine.agentCallToExecuteOptions 承担，逐字段等值由
+        // engines/pi/__tests__/spawn-opts-direct.test.ts 对照表锁定）
+        opts,
         runCtx,
       );
       // handle.journalPath 回填（§3.3.6：read ②级的自描述定位符——运行期落盘路径
       // 权威在 writer，handle 记录最终路径供跨重启 read 消费）
-      backfillJournalPath(handle, journal.path);
+      journal.backfillHandle(handle);
       return outcomeToRunnerResult(outcome);
     } catch (err) {
       // executeAndAwait throw（嵌套超限 ForkDepthExceededError，BC-12）或未预期异常 → 不 reject，入 error。
-      const message = err instanceof Error ? err.message : String(err);
+      const message = toErrorMessage(err);
       return {
         content: "",
         durationMs: Date.now() - startedAt,
@@ -252,9 +254,11 @@ export class SubprocessAgentRunner implements AgentRunner {
   // ── 内部 ──
 
   /**
-   * 引擎获取：pi 走 per-session DI 绑定（mock 语义 + 生产同单例，P1 行为零变化）；
-   * 非 pi 经 registry.getEngine 动态获取（P4：引擎身份归属注册表，未注册 id 抛
-   * EngineNotFoundError——路由期已前置校验，这里是防御性兜底）。
+   * 引擎获取（routeEngineForHost 的 probe 注入体）：pi 走 per-session DI 绑定（mock
+   * 语义 + 生产同单例，P1 行为零变化）；非 pi 经 registry.getEngine 动态获取（P4：
+   * 引擎身份归属注册表，未注册 id 抛 EngineNotFoundError——路由期已前置校验，这里
+   * 是防御性兜底）。[D3-②] get/has/list 的路由期注入已由 routeEngineForHost 内部
+   * 承载（本地 pi 恒可用口径），本方法只剩 probe 一个消费点（pi 请求同步短路恒免探）。
    */
   private engineFor(engineId: string): EnginePort {
     if (engineId === "pi") return this.piEngine;
@@ -280,21 +284,16 @@ export class SubprocessAgentRunner implements AgentRunner {
   }
 }
 
-/** 路由期错误 → AgentResult.error（错误码前缀格式保留——engine_not_found 等）。 */
+/** 路由期/预检错误 → AgentResult.error（错误码前缀格式保留——engine_not_found 等）。 */
 function errorResult(err: unknown, startedAt: number): AgentResult {
   return {
     content: "",
     durationMs: Date.now() - startedAt,
-    error: err instanceof Error ? err.message : String(err),
+    error: toErrorMessage(err),
     toolCalls: [],
   };
 }
 
-/** handle.journalPath 回填（一次写者：SAR 是 handle 的首个消费者）。 */
-function backfillJournalPath(handle: EngineHandle, journalPath: string): void {
-  handle.data.journalPath = journalPath;
-}
-
 /**
  * AgentOutcome → workflow AgentResult：剥离引擎层新增字段（engineId/engineFallback/
  * exitCode——engineFallback 经 record（pi 路径）/outcome（zcode 路径）留痕，GUI 投影
@@ -305,6 +304,9 @@ function backfillJournalPath(handle: EngineHandle, journalPath: string): void {
 function outcomeToRunnerResult(outcome: AgentOutcome): AgentResult {
   return {
     content: outcome.content,
+    // [D5-③] 失败分诊标签透传（pi 引擎产出；zcode 不产 failureKind，缺省 =
+    // unknown = 可重试）。成功路径 undefined 不落键。
+    ...(outcome.failureKind !== undefined ? { failureKind: outcome.failureKind } : {}),
     parsedOutput: outcome.parsedOutput,
     usage: outcome.usage,
     durationMs: outcome.durationMs,
@@ -315,3 +317,48 @@ function outcomeToRunnerResult(outcome: AgentOutcome): AgentResult {
     toolCalls: outcome.toolCalls,
   };
 }
+
+/**
+ * D-A9: per-call timeoutMs 合并进 AbortSignal（[D6 合流迁入]——原定义在已删除的
+ * execution/execute-options-mapper.ts，本类是唯一消费点，运行期件随消费方落位）。
+ *
+ * 墙钟 timeoutMs（per-call）+ 外部 signal（run 级 abort）都生效。
+ * 缺此合并则 agent({timeoutMs:5000}) 静默无效（BC-9）。
+ *
+ * @param signal    外部 signal（workflow run 级 controller.signal）
+ * @param timeoutMs per-call 墙钟超时；undefined/<=0 → 不设超时，原样返回 signal
+ * @returns 合并后的 signal（timeoutMs 或外部 signal 任一 abort 都触发）
+ */
+export function mergeTimeoutSignal(
+  signal: AbortSignal,
+  timeoutMs?: number,
+): AbortSignal {
+  if (!timeoutMs || timeoutMs <= 0) {
+    return signal;
+  }
+
+  const controller = new AbortController();
+  // 超时 abort 带 reason 标记（对齐点④）：引擎合成终态时判别「宿主超时」
+  // （engine_timeout 公共合成）vs「外部 cancel」（中止标记）——pi 链路不读 reason，
+  // 行为不变。外部 signal abort 不带标记（用户/编排层 cancel 语义）。
+  const timer = setTimeout(() => controller.abort(HOST_TIMEOUT_ABORT_REASON), timeoutMs);
+  timer.unref();
+
+  const onExternalAbort = (): void => controller.abort();
+  if (signal.aborted) {
+    controller.abort();
+  } else {
+    signal.addEventListener("abort", onExternalAbort, { once: true });
+  }
+
+  controller.signal.addEventListener(
+    "abort",
+    () => {
+      clearTimeout(timer);
+      if (!signal.aborted) signal.removeEventListener("abort", onExternalAbort);
+    },
+    { once: true },
+  );
+
+  return controller.signal;
+}

package/src/execution/sync-rebuild.ts

@@ -0,0 +1,87 @@
+// src/execution/sync-rebuild.ts
+//
+// [E1 恢复批语义修复] sync 批崩溃恢复（E1）与批闭合 flush（S11 兜底）的两条
+// BgNotifyRecord/SubagentRecord 映射，从 subagent-service 拆出（D4 按变化轴拆分：
+// 改恢复批的通知语义 / 落标数据源形态，只改本文件）。两函数均纯映射——零 service/
+// store 依赖，rootSessionId 由调用方注入。
+
+import { deriveOutcome } from "./execution-record.ts";
+import type { BgNotifyRecord } from "./notifier.ts";
+import type { SubagentRecord } from "./types.ts";
+
+/**
+ * E1 末条 entry 终态快照 → BgNotifyRecord（补发成员；sync 仅 one-shot，round/
+ * sessionFile 不透传——与 route() 缓冲快照的 one-shot 形态对齐）。
+ *
+ * [E1 恢复批语义修复] status/outcome/patchFile 三点对齐 notify-host toNotifyRecord
+ * 的映射（正常 flush 路径对同一成员的补发形态），不再直通 rec.status：
+ * - status：one-shot 成功成员崩溃时末条 entry 恒为 running+resumable（SP-5 轮终
+ *   形态，resumable 豁免正据此放行其入批）——直通会让补发记录仍是 running 形态：
+ *   buildBatchLlmContent 批头只统计 closed 成员（全员成功的恢复批显示
+ *   「0 finished, 0 failed, 0 cancelled」），条目文案落「finished a round」
+ *   （对话轮次语义）。同 toNotifyRecord：closed 或非 chatMode → "closed"（仅
+ *   chatMode 轮次形态保持 running——sync 成员恒 one-shot，此分支为防御完整性）。
+ * - outcome：closed 状态物化（单一权威 deriveOutcome）——resumable 成员末条未
+ *   终态化，closedReason 缺省与正常 flush 路径同形，无 error 即 completed、有
+ *   error 即 failed；notifier.notifyBatch 投影边界的 `??` 兜底对此幂等。
+ * - patchFile：透传（依赖 rebuildEntryRecord 的同名投影）——worktree one-shot
+ *   成员的 git-apply 回收指针只在 closed+completed 分支文案携带（running 分支
+ *   不含），正常 flush 路径经 toNotifyRecord 特意携带，恢复批不得缺失。
+ */
+export function syncRebuildToNotifyMember(rec: SubagentRecord): BgNotifyRecord {
+  const status: BgNotifyRecord["status"] =
+    rec.status === "closed" || !rec.chatMode ? "closed" : "running";
+  return {
+    id: rec.id,
+    status,
+    closedReason: rec.closedReason,
+    outcome: status === "closed" ? deriveOutcome(rec.closedReason, rec.error) : undefined,
+    agent: rec.agent,
+    model: rec.model,
+    result: rec.result,
+    error: rec.error,
+    startedAt: rec.startedAt,
+    endedAt: rec.endedAt,
+    patchFile: rec.patchFile,
+  };
+}
+
+/**
+ * [S11] getFullRecord miss 成员的缓冲快照兜底 → 最小 SubagentRecord（batchFinalized
+ * 落标数据源）。getFullRecord 不可达（子 session 文件缺失/已 GC）时，缓冲的
+ * BgNotifyRecord 是该成员唯一残存数据。最小形态只保标记链路必需字段：
+ * id/agent/task/startedAt 是 rebuildEntryRecord 的解析门槛（缺 task 的 entry 会被
+ * E1 扫描判损坏跳过——标记失效方向，task 占位空串保 entry 可解析）；终态字段
+ * （closedReason/result/error/endedAt/model/patchFile）自缓冲快照如实投影；
+ * rootSessionId 取当前 session 根（E1 候选过滤的归属口径）。
+ */
+export function bufferedMemberFallbackRecord(
+  m: BgNotifyRecord,
+  rootSessionId: string | undefined,
+): SubagentRecord {
+  return {
+    id: m.id,
+    agent: m.agent,
+    task: "",
+    slug: "",
+    status: "closed",
+    closedReason: m.closedReason,
+    mode: "background",
+    startedAt: m.startedAt,
+    rootSessionId,
+    parentRecordId: undefined,
+    depth: 0,
+    endedAt: m.endedAt,
+    turns: 0,
+    totalTokens: 0,
+    model: m.model ?? "",
+    thinkingLevel: undefined,
+    eventLog: [],
+    displayItems: [],
+    result: m.result,
+    error: m.error,
+    sessionFile: undefined,
+    chatMode: false,
+    patchFile: m.patchFile,
+  };
+}

package/src/execution/types.ts

@@ -9,6 +9,7 @@
 
 import type { GuiRenderResult } from "@xyz-agent/extension-protocol";
 
+import type { AgentFailureKind } from "../orchestration/models/types.ts";
 import type { ModelInfo, ModelRegistryLike } from "./model-resolver.ts";
 
 // ============================================================
@@ -318,6 +319,12 @@ export interface AgentResult {
   durationMs: number;
   success: boolean;
   error?: string;
+  /**
+   * [D5-③] 失败分诊结构化标签（类型 SSOT 在 orchestration/models/types.ts 的
+   * AgentFailureKind——消费语义「unknown=可重试」与其文档同源）。collectResult 对
+   * 最终 error 分类后写入；缺省 = unknown（可重试）。type-only 引用零运行时依赖。
+   */
+  failureKind?: AgentFailureKind;
   sessionId: string;
   toolCalls: ToolCall[];
   usage?: AgentUsageTotal;
@@ -472,6 +479,14 @@ export interface ExecutionRecord {
    * 回填（sessionFile 即定位符）。持久化经 subagent-record entry。
    */
   engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
+  /**
+   * 同步收集模式标记（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+   * 创建时确定不可变；undefined = async（缺省语义，旧记录零迁移）。持久化经
+   * subagent-record entry（record-entry.ts 序列化白名单，entry 唯一写点）。
+   * 消费方：U2 collectCoordinator 路由（sync→批缓冲）、U5 E1 重建投影。
+   * U2 接线点：service.createRecordForMode 从 ExecuteOptions.collect 读入 identity。
+   */
+  readonly collectMode?: "sync";
 
   // ── 状态（实时更新）──
   status: ExecutionStatus;
@@ -485,6 +500,13 @@ export interface ExecutionRecord {
    * record 无此字段，投影层按 projectOutcome 兜底（closed-legacy 语义）。
    */
   outcome?: ExecutionOutcome;
+  /**
+   * 离开批的终局标记（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+   * 两出口统一落标：① 批闭合 flush 写账成功后；② E9 dispose 逐条转 async 写账后
+   * （均 appendEntry 持久化，U3/U5 写点）。undefined = 未离开批 / 旧记录零迁移。
+   * 消费方：U5 E1 重建扫描只收「collectMode=sync 且无本标记」的成员（防双重通知）。
+   */
+  batchFinalized?: boolean;
   /** 完整执行内容，按 turn 组织。createRecord 初始化为 [空 turn]。 */
   turns: Turn[];
   /** turn 计数（= turns.filter(closed).length，冗余存储供投影直接读）。 */
@@ -669,6 +691,17 @@ export interface ExecuteOptions {
    * undefined/false = 一次性模式（默认，行为完全不变）。service.execute 透传到 createRecordForMode。
    */
   conversation?: boolean;
+  /**
+   * 同步收集模式（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+   * undefined = config collectSync.default（缺省 "async"，新 session 生效）。
+   * schema 层枚举限 "async"|"sync"；运行时宽收 string 与 engine 字段同风格
+   * （非法值 ≠ "sync" 按 async 处理）。
+   * "sync" + conversation:true 组合在 startHandler E4 校验即拒
+   * （immediate throw，不产生半启动 record）。
+   * U2 接线点：service.createRecordForMode 读入 createRecord identity.collectMode
+   * （U1 打通类型与 startHandler 透传，record 落点归 U2）。
+   */
+  collect?: string;
   /**
    * 空闲超时毫秒数（仅 conversation 模式有意义）。覆盖默认 5min idle timeout。
    * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms。
@@ -757,6 +790,13 @@ export interface BgResponse {
    * 值语义由 U2（execution/notify-ledger.ts）兑现。
    */
   notifyContract: "ledger+at-least-once";
+  /**
+   * 同步收集登记回显段（subagent-sync-collect 设计 §3.1.1 交互样例，U1 foundation）。
+   * 仅 resolved 模式为 sync 时附带（async 响应字节零变化，G3）：mode = 生效模式；
+   * pendingSyncCount = 当前未闭合批的 sync 成员总数（含本条；跨轮派发续累不重置，
+   * 与 D2 隐式批一致）。
+   */
+  collect?: { mode: "sync"; pendingSyncCount: number };
 }
 
 /** list 的内层响应（挂在 SubagentToolResult.listResponse）。 */
@@ -831,6 +871,8 @@ export interface SubagentRecord {
   status: ExecutionStatus;
   /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。SP-1 新增。 */
   closedReason?: ClosedReason;
+  /** 终态三态对外语义（U3 C-outcome）。磁盘重建源一等直读；无字段的存量兜底走 projectOutcome。 */
+  outcome?: ExecutionOutcome;
   mode: ExecutionMode;
   startedAt: number;
   /** 根 Pi session ID（session 隔离过滤用）。递归链上所有层 record 同值。 */
@@ -893,12 +935,37 @@ export interface SubagentRecord {
    * subagent-engine-history）；缺省 = pi（走 JSONL 直读链）。
    */
   engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
+  /**
+   * 同步收集模式标记（与 ExecutionRecord.collectMode 同源投影/重建，U1 foundation）。
+   * 缺省（存量 record）= async 投影，消费方零迁移。
+   */
+  collectMode?: "sync";
+  /**
+   * 离开批终局标记（与 ExecutionRecord.batchFinalized 同源投影/重建，U1 foundation）。
+   * 缺省 = 未离开批；U5 E1 重建扫描据此排除已离场成员。
+   */
+  batchFinalized?: boolean;
 }
 
 // ============================================================
 // 配置（global + session）
 // ============================================================
 
+/**
+ * 同步收集（sync collect）配置节类型（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+ * 权威默认值在 config.ts DEFAULT_COLLECT_SYNC；坏值 sanitize 回默认不炸启动（E5，
+ * 与 maxConcurrent 同判）。类型定义于 types.ts（避免 config → types 反向依赖成环），
+ * config.ts re-export。
+ */
+export interface CollectSyncConfig {
+  /** start 未显式传 collect 时的缺省模式。新 session 生效（与 engine 配置时机一致）。 */
+  default: "async" | "sync";
+  /** 批通知单条目结果正文预算（字符）：超出截断并接 session_read 指针行。flush 时热读。 */
+  perItemChars: number;
+  /** 批通知结果正文总量预算（字符）：Σ 超限时统一收紧 effectivePerItem（U4 算法）。flush 时热读。 */
+  totalChars: number;
+}
+
 /**
  * 全局配置（~/.pi/agent/subagents/config.json）。
  *
@@ -916,6 +983,11 @@ export interface SubagentsGlobalConfig {
   defaultEngine?: string;
   /** 引擎路由策略（D9①）：strict=true 时一切 probe 失败直接报错（不 fallback）。 */
   engineRouting?: { strict: boolean };
+  /**
+   * 同步收集配置节（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+   * 整节缺省 = DEFAULT_COLLECT_SYNC（config.ts）；逐字段 sanitize 回默认（E5）。
+   */
+  collectSync?: CollectSyncConfig;
 }
 
 // ============================================================