@zhushanwen/subagent-core 0.8.0 → 0.9.0

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

@@ -1,372 +1,95 @@
 // src/execution/subprocess-agent-runner.ts
 //
-// Wave 4: SubprocessAgentRunner 委托重写
+// [H2 W4] SAR 壳归位（设计 subagent-workflow-record-unification.md §5 W4）：
+// run() 掏空为纯转调 SubagentService.executeWorkflowAgent——编排权（路由/预检/
+// journal/守护/spawned-children/池）彻底归 service 单点（W2 executeWorkflowAgent
+// 八步迁移承接），本类不再自持任何编排。历史形态（Wave 4 委托重写 → P4 路由 →
+// M3 no-progress 守护落点）随本次掏空退役，行为守护由 workflow-agent-dispatch
+// 测试族（service 落点）承接。
 //
-// 从"自己 spawn pi"改为"委托 SubagentService.executeAndAwait"。
-// MF-3: 从 orchestration/infra 迁入 execution，同层委托 SubagentService。
+// 保留壳的原因（设计 v3 定形）：唯一装配点 session-lifecycle.ts（D-008 per-session
+// SAR 构造）与 index.ts 的 model_select → updateCtxModel 刷新链零改动——掏空只删
+// run() 内部编排，构造签名与公共面不变。
 //
-// [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）
-//   [模块内直调] 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-A8（onEvent 桥接）/ D-A9（timeoutMs 合并 signal）/
-//   D-008（model 填底，不调 resolveModel）/ BC-9（timeoutMs 行为）/ BC-10（live-record 进度）
+// ctxModel dep 保留在构造签名（装配点兼容），但 run() 不再消费——model 解析归
+// service resolveIdentity（W2 迁移清单⑧：ctxModel 孪生守卫放弃迁移，不双轨）。
 
 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 { 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";
-// [W6 R1 MF-5] pi EnginePort 解析改经 host 公共面（engine/host/pi-host-binding.ts）：
-// registry cli 形态经 descriptor 路由（W3 双模 getEngine），inproc/未注册回落 per-session
-// DI 直构（行为与改线前 createPiEngine 逐点一致）。
-import { resolveHostPiEnginePort } from "./engine/host/pi-host-binding.ts";
-import type { EnginePort, RunContext } from "./engine/port.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";
-// [W6 R1 MF-5] 子进程注册改经 spawnedChildren 状态镜像公共面（engine/host/
-// spawned-children.ts——镜像 + inproc 过渡委托，不再深路径 import inproc pi 引擎目录）。
-import { registerSpawnedChildForRecord } from "./engine/host/spawned-children.ts";
 import type { SubagentStream } from "./stream-sink.ts";
 import type { SubagentService } from "./subagent-service.ts";
-import { toErrorMessage } from "../core/error-message.ts";
-
-// ── 构造依赖（per-session 注入）──
 
 /**
- * SAR 构造参数。
+ * SAR 直调（无 workflow run 上下文）时的 parentRunId 占位——record 仍带
+ * origin:"workflow" 进 store，但不隶属任何 run（views 按真实 runId 查询
+ * collectRecordsByParentRunId 天然不中；治理通道 `subagents action:'list'
+ * includeWorkflow:true` 仍可查）。
  *
- * per-session（makeDeps 时创建，随 session 销毁）：
- *   - subagentService: 进程单例（getSubagentService()），委托目标
- *   - ctxModel: 当前 session 主 agent 模型（D-008 model 填底，opts.model 空时用此）
- *
- * resolveAgentOpts 在 orchestration 层完成（M2 修正后单参数，只处理 schema SO 指令 + skill），
- * 结果填进 AgentCallOpts.skillPath/schemaEnv/appendSystemPrompt，SAR 收已解析的 opts。
- * 不含 agent/session 目录/临时文件集合依赖（agent ref 交 resolveIdentity，无临时文件）。
+ * 生产链路 pump 恒经 workflowAgentDispatch 注入（闭包携带真实 run.runId），
+ * 本占位仅在 SAR.run 被直接调用的场景出现（生产不可达；测试直调）。
  */
+export const SAR_UNATTACHED_PARENT_RUN_ID = "sar-unattached";
+
+/** SAR 构造参数（签名冻结——session-lifecycle.ts 装配点零改动）。 */
 export interface SubprocessAgentRunnerDeps {
   subagentService: SubagentService;
+  /** 兼容保留：run() 不消费（model 解析归 service resolveIdentity）。 */
   ctxModel?: ModelInfo;
 }
 
 /**
- * AgentRunner port 实现——委托 SubagentService.executeAndAwait。
+ * AgentRunner port 实现——纯转调 SubagentService.executeWorkflowAgent。
  *
- * 层归属：execution（MF-3 从 orchestration 迁入）。implements orchestration 层 port。
+ * 层归属：execution。implements orchestration 层 port。
  *
- * 行为契约（BC-1/BC-2/BC-9/BC-10）：
+ * 契约：
  *   - opts 形状不变（AgentCallOpts，含 resolveAgentOpts 填的 skillPath/schemaEnv）
- *   - result 形状不变（workflow AgentResult: content/parsedOutput/usage/error/toolCalls）
- *   - 不 reject——失败信息入 result.error（与 executeAgentCall 契约一致）
- *   - timeoutMs 合并 signal（D-A9）；onEvent 桥接 AgentEvent→workflow liveRecord（D-A8）
- *
- * [P1 引擎接线] 执行经 EnginePort。pi 引擎绑定本 SAR 的服务引用（per-session DI——
- * 单测注入 mock 时全局单例不可见；生产环境两者是同一进程单例对象），行为零变化；
- * 非 pi 引擎（P4 路由可达：frontmatter/调用参数/全局默认指定）经 registry.getEngine
- * 动态获取——「引擎身份」的归属边界在注册表，SAR 不感知具体引擎实现。
- *
- * [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 契约一致。
+ *   - result 形状不变（AgentResult——executeWorkflowAgent 返回类型即 orchestration
+ *     AgentResult，零映射）
+ *   - 路由失败/预检命中/嵌套超限经 service 同步抛错（§3.4 同步抛错回脚本 + D3
+ *     路由先于 record 创建的构造性推论：不产生孤儿 record）——传播形态与
+ *     workflowAgentDispatch 注入路径一致（dispatch 闭包同样不吞错），pump 侧
+ *     dispatchCall catch 兜底回发。
  */
 export class SubprocessAgentRunner implements AgentRunner {
   private readonly subagentService: SubagentService;
   private ctxModel: ModelInfo | undefined;
-  /** pi 引擎（per-session DI 绑定，缺省执行路径——见类注释）。 */
-  private readonly piEngine: EnginePort;
 
   constructor(deps: SubprocessAgentRunnerDeps) {
     this.subagentService = deps.subagentService;
     this.ctxModel = deps.ctxModel;
-    // [D4 聚合连带] 经 asEngineService 显式视图适配（原结构化直绑依赖查询面 public）。
-    // [W6] 解析经 host 公共面（descriptor 路由 / inproc DI，见 pi-host-binding 注释）。
-    this.piEngine = resolveHostPiEnginePort(() => this.subagentService.asEngineService);
   }
 
   /**
-   * 刷新主 agent model 缓存。model_select 事件时由 index.ts 调用。
-   * H1 修复：旧实现 ctxModel 是 readonly，session_start 后固化，
-   * model_select 只刷新 ModelConfigService._ctxModel 不更新 SAR →
-   * workflow 路径用过期模型。
+   * 刷新主 agent model 缓存（model_select 事件时由 extension index.ts 调用）。
+   *
+   * [H2 W4] run() 不再消费 ctxModel（model 解析归 service resolveIdentity），
+   * 本方法保留仅为装配链兼容（index.ts 调用不炸）；字段更新不再影响执行路径。
    */
   updateCtxModel(model: ModelInfo | undefined): void {
     this.ctxModel = model;
   }
 
-  /**
-   * 执行单次 agent 调用：路由（P4）→ 预检（D3-④）→ EnginePort.run → PiEngine 委托
-   * SubagentService.executeAndAwait。
-   *
-   * 接线链路：
-   *   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（不逃逸）
-   */
+  /** 纯转调 service 统一编排入口（形参原样透传；parentRunId 用直调占位）。 */
   async run(
     opts: AgentCallOpts,
     signal: AbortSignal,
     onEvent?: (event: AgentEvent) => void,
     stream?: SubagentStream,
   ): Promise<AgentResult> {
-    const startedAt = Date.now();
-
-    // ── P4 路由（D3-② 单点：routeEngineForHost）+ D3-④ 预检 ──
-    // 路由在最前——引擎身份决定 journal 路径与后续一切执行面。pi 快路径同步短路
-    //（routed 非 Promise，零微任务）——首个 await 前完成**路由决策**（engine id 已定，
-    // A2 观测点）；其后的执行经进程边界（cli 形态 spawn + 握手 + 帧往返必经 await），
-    // 旧「run 内首个 await 前已触达 executeAndAwait」时序契约由引擎协议化设计
-    // §3.5.3 作废放宽。路由失败（未注册 id / probe 失败 + strict/守卫）与预检命中
-    //（capabilities 驱动，含 worktree——workflow 域漏拦缺口修复）一并按「不 reject」
-    // 契约转 result.error。
-    let route: EngineRouteResult;
-    try {
-      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/守卫）与预检拒绝（engine_capability_unsupported）一并在此
-      // 收口——「不 reject」契约
-      return errorResult(err, startedAt);
-    }
-
-    // ── P2 event journal 接线（设计 D6 第②级；对齐点③：路径权威 = 引擎池 key）──
-    // [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 依赖 TTL 兜底回收，见 D8 分域裁决），
-    // read ②级经 handle.journalPath 自描述定位不受影响）。
-    const taskId = `sa-${crypto.randomUUID()}`;
-    const journal = wireEventJournal({ engineId: route.engineId, taskId, forwardEvents: onEvent });
-
-    try {
-      // ── [U1 D2] RunContext.modelRef 接入：ctxModel 继承路径的孪生守卫 ──
-      // ctxModel 是运行时已验证的 ModelInfo（豁免 registry 存在性复查），但继承产出的
-      // canonical 串与显式入参走同一个 pi pattern 引擎，孪生守卫同等适用（modelRefFromVerified）。
-      // 守卫在 engine.run 之前同步拒绝：含孪生 registry 下不产生任何 record/spawn，
-      // 失败走下方 catch → errorResult（错误文案含恢复指引）。
-      // RunContext 类型本身定义在 engine/port.ts（跨模块 port，不在本单元领地），
-      // 故接入点为构造 runCtx 前的守卫调用；pi 链路下游 resolveModel 的 ctxModel 分支
-      // 有同一守卫（model-resolver.ts），两处共用同一入口函数。
-      if (this.ctxModel) {
-        const modelService = getModelConfigService();
-        if (modelService) modelRefFromVerified(this.ctxModel, modelService.getModelRegistry());
-      }
-
-      // ── D-A9: timeoutMs 合并 signal（超时 abort 带 HOST_TIMEOUT_ABORT_REASON 标记）──
-      const mergedSignal = mergeTimeoutSignal(signal, opts.timeoutMs);
-
-      // ── P1/P4 引擎接线：EnginePort.run ──
-      const runCtx: RunContext = {
-        taskId,
-        poolKey: JOURNAL_INITIAL_POOL_KEY,
-        signal: mergedSignal,
-        onEvent: journal.onEvent,
-        ctxModel: this.ctxModel,
-        ...(route.engineFallback !== undefined ? { engineFallback: route.engineFallback } : {}),
-        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 } : {}),
-        // [D6 合流] 解耦形态（有 schemaEnv 无 schema）不再经 RunContext.schemaEnv
-        // 兜底通道——schemaEnv 已在合流形状 AgentCallOpts.schemaEnv 内，pi 直出
-        // （agentCallToExecuteOptions）以「schema 派生优先、schemaEnv 兜底」取值，
-        // 与原 ctx 兜底链路逐字节等值。
-      };
-      const { handle, outcome } = await route.engine.run(
-        // [D6 合流] opts 直传——AgentCallOpts 即 EnginePort 任务形状（缺省路径零映射；
-        // pi 边界一次直出由 PiEngine.agentCallToExecuteOptions 承担，逐字段等值由
-        // inproc pi 引擎目录/__tests__/spawn-opts-direct.test.ts 对照表锁定）
-        opts,
-        runCtx,
-      );
-      // handle.journalPath 回填（§3.3.6：read ②级的自描述定位符——运行期落盘路径
-      // 权威在 writer，handle 记录最终路径供跨重启 read 消费）
-      journal.backfillHandle(handle);
-      return outcomeToRunnerResult(outcome);
-    } catch (err) {
-      // executeAndAwait throw（嵌套超限 ForkDepthExceededError，BC-12）或未预期异常 → 不 reject，入 error。
-      const message = toErrorMessage(err);
-      return {
-        content: "",
-        durationMs: Date.now() - startedAt,
-        error: message,
-        toolCalls: [],
-      };
-    } finally {
-      // run 终态后 flush + fsync 一次（§3.3.6 写入纪律）；写失败已由 writer 内部
-      // warn + failed 收口，close 不抛（journal 是②级尽力而为数据源）
-      await journal.close();
-    }
-  }
-
-  // ── 内部 ──
-
-  /**
-   * 引擎获取（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;
-    return getEngine(engineId);
+    return this.subagentService.executeWorkflowAgent(
+      opts,
+      SAR_UNATTACHED_PARENT_RUN_ID,
+      signal,
+      onEvent,
+      stream,
+    );
   }
-
-  /**
-   * 三层路由输入装配（D9）：调用参数（opts.engine，workflow step 级透传）> agent
-   * frontmatter（ModelConfigService.getAgentConfig——loadByPath mtime 缓存，幂等）>
-   * 全局默认（config.json defaultEngine）。单例未就绪（session_start 前/测试 mock）
-   * 时各层缺省——落内置 'pi'。
-   */
-  private buildRoutingInput(opts: AgentCallOpts): EngineRoutingInput {
-    const service = getModelConfigService();
-    const agentEngine =
-      opts.agent !== undefined && opts.agent !== "" ? service?.getAgentConfig(opts.agent)?.engine : undefined;
-    const globalDefault = service?.getGlobalConfig().defaultEngine;
-    return {
-      ...(opts.engine !== undefined && opts.engine !== "" ? { callEngine: opts.engine } : {}),
-      ...(agentEngine !== undefined && agentEngine !== "" ? { agentEngine } : {}),
-      ...(globalDefault !== undefined && globalDefault !== "" ? { globalDefaultEngine: globalDefault } : {}),
-    };
-  }
-}
-
-/** 路由期/预检错误 → AgentResult.error（错误码前缀格式保留——engine_not_found 等）。 */
-function errorResult(err: unknown, startedAt: number): AgentResult {
-  return {
-    content: "",
-    durationMs: Date.now() - startedAt,
-    error: toErrorMessage(err),
-    toolCalls: [],
-  };
 }
 
-/**
- * AgentOutcome → workflow AgentResult：剥离引擎层新增字段（engineId/engineFallback/
- * exitCode——engineFallback 经 record（pi 路径）/outcome（zcode 路径）留痕，GUI 投影
- * 通道在后续 wave 接线，workflow 引擎不消费）。其余字段由 PiEngine 从 executeAndAwait
- * 的返回值逐字段映射而来，字段全集完整性由 pi-engine 单测锁定（缺字段会在该处转红，
- * 不会静默丢失）。
- */
-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,
-    error: outcome.error,
-    sessionId: outcome.sessionId,
-    sessionFile: outcome.sessionFile,
-    worktreePath: outcome.worktreePath,
-    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;
-}
+// [H2 W2 迁移步⑥] mergeRunSignals/MergedRunSignalHandle 公共 helper 权威落点在
+// engine/common/run-signals.ts；此处 re-export 保持既有 import 路径（no-progress
+// killall 测试等消费面零改动）。
+export { mergeRunSignals, type MergedRunSignalHandle } from "./engine/common/run-signals.ts";

package/src/execution/types.ts

@@ -47,8 +47,9 @@ export const DEFAULT_AGENT_NAME = "general-purpose";
  * 旧 cancelled 折入 closed（closedReason='cancelled' 区分）。
  *
  * running = 活跃态。含两种子态（由派生谓词区分，见 lifecycle-predicates.ts）：
- *   - 对话模式等待续聊（旧 idle）：进程可能保活（isIdle=hasIdleTimer）或已回收
- *     待冷路径 resume（isResumable=running && 无活进程句柄）。
+ *   - 对话模式等待续聊（旧 idle）：进程已回收，待冷路径 resume
+ *     （isResumable=running && 无活进程句柄）。旧「进程保活待热路径」形态随
+ *     H1 U6 长驻退役消亡，isIdle（hasIdleTimer）生产恒 false。
  *   - 正在执行（有活进程句柄）。
  *
  * closed = 统一终态（done/failed/crashed/cancelled 合并）。具体关闭原因由
@@ -57,6 +58,16 @@ export const DEFAULT_AGENT_NAME = "general-purpose";
  */
 export type ExecutionStatus = "running" | "closed";
 
+/**
+ * record 来源身份（H2 W1，设计 subagent-workflow-record-unification §3.3 D1 建议新增）：
+ *   "tool"     — 主 agent 经 subagent 工具手动派发（现状全部 record）；
+ *   "workflow" — workflow 脚本内 agent() 调用派发（生产写入方 W2 executeWorkflowAgent 接线）。
+ * 缺省语义 = "tool"：存量 record / 未传字段的 entry 反序列化产物一律视为手动派发，
+ * 四个投影消费面（subagents tool list / renderer 侧栏计数 / renderer 后台工作指示 /
+ * TUI /subagents）对缺省 record 的可见性与历史行为完全一致（零迁移）。
+ */
+export type RecordOrigin = "tool" | "workflow";
+
 /**
  * closed 终态的 L2 关闭原因子枚举。
  *
@@ -79,7 +90,7 @@ export type ClosedReason = 'parent-shutdown' | 'parent-fork' | 'parent-new' | 'u
  * sessionFile（resurrectClosed 回边），不再要求 fork-from 换新 id。
  *
  * 取值以 `.finalized` sidecar 实际写入的 ClosedReason 字面量为准：
- *   disconnected    — 断联（sidecar 空/损坏兜底 + pi-invocation 中断写入）
+ *   disconnected    — 断联（sidecar 空/损坏兜底；in-proc 时代写点已随 engine-CLI 化消失）
  *   parent-shutdown — 父进程 session_shutdown 回收
  * 其余 reason 刻意排除：user-close/cancelled 是用户主动告别（close 语义不可旁路）；
  * gc 是自然完成（追问走 fork-from 或新 start）；parent-fork/parent-new 同理是编排性
@@ -133,19 +144,16 @@ export type ExecutionOutcome = "completed" | "failed" | "cancelled";
 export type ProjectedOutcome = ExecutionOutcome | "closed-legacy";
 
 /**
- * 对外四态（设计决策 10 细则 3）：内部 ExecutionStatus（v4 B-1 两态）收敛为 agent
+ * 对外两态（设计决策 10 细则 3）：内部 ExecutionStatus（v4 B-1 两态）收敛为 agent
  * 可理解的状态语义。真实映射只有两条：
  *   running → active / closed → ended（closed 统一终态，含 cancelled）。
  * mapExternalState 不消费 ClosedReason——closed 恒映射 ended。
  *
- * waiting / error 是历史多态映射（idle→waiting / failed+crashed→error）的遗留声明：
- * 对外四态联合契约不变，但当前状态机不产生这两个值。
- *
  * 原始 ExecutionStatus 进 list item 的 status 字段供调试；state 是对外主字段。
- * 映射实现见 subagent-actions.ts mapExternalState——未来内部加态必须扩展该处，
+ * 映射实现见 subagent-actions-core.ts mapExternalState——未来内部加态必须扩展该处，
  * 漏加会在 default 分支编译报错，不影响对外契约。
  */
-export type ExternalState = "active" | "waiting" | "ended" | "error";
+export type ExternalState = "active" | "ended";
 
 /** 执行模式。background = 调用方立即拿 handle 返回，子 agent 在 detached promise 里跑。 */
 export type ExecutionMode = "background";
@@ -172,6 +180,8 @@ export type ExecutionMode = "background";
 //     tool_start / tool_end      ↔ ACP tool_call / tool_call_update
 //     turn_end / message_end     ↔ ACP prompt turn 终态（stop_reason + usage）
 //     compaction                 ↔ ACP session/compaction
+//     activity                   ↔ 无 ACP 对应（协议内生活性信号：reducer no-op、
+//                                 不落 journal，仅供无进展守护刷新判活）
 //   本协议以 pi 为语义锚点（D3）——命名不迁移，对照表仅保证未来 AcpEngine 适配器
 //   与跨引擎 trace 映射的翻译成本最低。
 export type {
@@ -279,7 +289,8 @@ export interface AgentResult {
 // Object.freeze 守卫不可变」的语义注释见消费方 worktree-manager / worktree-git-ops）。
 export type { WorktreeHandle } from "@zhushanwen/subagent-engine-sdk";
 
-/** alive marker：子进程存活标记，用于心跳检测和 crash 推断。 */
+/** alive marker：跨进程写权声明载体（写者 = 宿主进程；acquire/release 见
+ *  alive-store 模块头；startedAt 仅载体字段，判活不消费——pid 单判据）。 */
 export interface AliveMarker {
   readonly pid: number;
   readonly id: string;
@@ -366,6 +377,19 @@ export interface ExecutionRecord {
   readonly parentRecordId: string | undefined;
   /** subagent 递归深度。顶层（主 session 直接创建）=0，每层嵌套 +1。 */
   readonly depth: number;
+  /**
+   * 来源身份（H2 W1，D1）。缺省（undefined）语义 = "tool"（存量 record 零迁移）；
+   * "workflow" = workflow 脚本 agent() 派发（生产写入方 W2 接线）。过滤在投影/查询
+   * 消费面（list 默认滤 workflow origin），store 治理面（孤儿恢复/revive）全量可见。
+   * 持久化经 subagent-record entry。
+   */
+  readonly origin?: RecordOrigin;
+  /**
+   * origin="workflow" 时所属 workflow run 的 id（W2 写入）；tool 来源恒 undefined。
+   * W2 run 视图进度 / W3 下钻按本 id 查询本 run 的 record 集（内存 ∪ 磁盘重建口径，
+   * collectRecordsByParentRunId）。持久化经 subagent-record entry。
+   */
+  readonly parentRunId?: string;
   /**
    * 对话模式标志（可持续对话 subagent）。true = 轮次完成进 idle 态（保留 record +
    * worktree）等待续聊，而非一次性终态化。
@@ -443,32 +467,9 @@ export interface ExecutionRecord {
    * 进 idle）+1。undefined 时视为 0。非 chatMode 不自增。
    */
   round?: number;
-  /**
-   * [增量通知] 当前轮次增量的 turns[] 起始下标（仅 chatMode 有意义；内存态记账，D4 不持久化）。
-   *
-   * - 生命周期：undefined 视为 0（首轮增量 = 全量，与改造前首轮通知逐字节一致，向后兼容旧
-   *   record）；唯一写点 onRoundSettled 第 5 步（notify 之后推进），唯一读点同回调第 2 步
-   *   （`getFullTextFrom(record, record.roundBaseTurnIndex ?? 0)`）。非 chatMode 恒
-   *   undefined（onRoundSettled 是 session-runner chatMode 分支专属回调）。
-   * - D1 滞后空 turn 防丢文本（防御性）：pi 当前事件序下该形态不可达——带 usage 的
-   *   message_end 恒先于 turn_end（@earendil-works/pi-agent-core dist/agent-loop.js
-   *   :240/:253/:547 三处 message_end emit 均在 :131 正常路径 turn_end 之前），settle 时
-   *   turn 全闭合。防 pi 未来事件序变化：若 settle 时刻末 turn 是滞后 message_end 开出的
-   *   空 turn（execution-record.ts message_end 分支经 currentTurn，需同时过两层 usage 守卫：
-   *   session-runner.ts 转发层 `if (msg?.usage)`（bare message_end 不转发）+ execution-record.ts
-   *   累积层 `if (event.usage)`（bare message_end 不开 turn）），推进公式
-   *   nextRoundBaseTurnIndex 把它留在下一轮增量内（新轮首个 text_delta 经 currentTurn 复用该
-   *   空 turn，复用累积被 slice 覆盖）；直用 turns.length 推进会把下轮首段文本挤出 slice
-   *   范围静默丢失。
-   * - D4 不持久化：磁盘重建走 createRecord（turns 仅为初始 [emptyTurn()]），base=0 对空 turn
-   *   的增量派生等价为空、天然产出仅新轮增量，持久化是死数据。故不写 manifest、不参与重建。
-   * - pi 内部序锚定依据（R1 mitigation）：@earendil-works/pi-agent-core 0.84.2
-   *   dist/agent-loop.js :108-111（error/aborted stopReason 也先 emit turn_end 再 agent_end）
-   *   与 :131（正常路径 turn_end 收尾）；agent_settled 在 agent_end 之后 emit，故未闭合
-   *   turn 只可能来自滞后事件。pi 升级若改变 turn_end/agent_end 时序，onRoundSettled 推进前
-   *   的观测哨（末 turn 未闭合且 text 非空 → logger.warn）会留痕。
-   */
-  roundBaseTurnIndex?: number;
+  // [H1 U6 / D7 ③] roundBaseTurnIndex（增量通知 base 记账）已退役删除——消费函数
+  // getFullTextFrom/nextRoundBaseTurnIndex 与唯一写点 settleChatRoundFromResponse 随
+  // chat 域载体退役，生产零调用（base 推进 = 死记账）。
   /**
    * record 进入 idle 态的时间戳（ms）。finalizeRoundToIdle 设值；GC 定时器据此计算
    * 剩余 TTL。undefined = 非 idle 态（running/closed/cancelled）或旧 record 缺失字段。
@@ -493,12 +494,11 @@ export interface ExecutionRecord {
   sessionFile?: string;
 
   /**
-   * [V2 决策 3] 子进程 pid（spawn 后由 session-runner 回填到内存 record）。
+   * [V2 决策 3] 子进程 pid（spawn 后回填到内存 record，并随 record 持久化落盘）。
    *
-   * 用于 lifecycle-manager 孤儿扫描（V2 §5.2 职责 4：父进程重启时按持久化 pid 扫收
-   * 上次崩溃遗留的孤儿）。本字段仅在内存记账，持久化留 Step 5（record
-   * 文件写入 pid + 启动时 scanOrphanProcesses 消费）。undefined = 尚未 spawn / 已退出。
-   * 向后兼容：旧 record 无此字段，按无 pid 处理（孤儿扫描跳过）。
+   * 诊断字段：排障时对照 record 文件与进程表核实 spawn 事实。原职责 4 孤儿扫描
+   * （按持久化 pid 扫收上次崩溃遗留孤儿）自落地起未接线，已随 L2 死代码清扫删除。
+   * undefined = 尚未 spawn / 已退出。向后兼容：旧 record 无此字段，按无 pid 处理。
    */
   pid?: number;
 
@@ -693,6 +693,14 @@ export interface SubagentListItem {
    * 无需翻 error 字段原文（S5）。
    */
   outcome?: ProjectedOutcome;
+  /**
+   * 来源身份（H2 W1）：undefined（存量 list 形态 / record 无 origin）= "tool" 语义。
+   * includeWorkflow 打开后 list 条目与手动派发 record 靠本字段区分（排查 workflow
+   * run's subagents 场景的辨识数据）。
+   */
+  origin?: RecordOrigin;
+  /** origin="workflow" 时所属 workflow run id；tool 来源恒缺省（同 record 侧）。 */
+  parentRunId?: string;
 }
 
 /** background 启动的内层响应（挂在 SubagentToolResult.bgResponse）。 */
@@ -805,6 +813,17 @@ export interface SubagentRecord {
   parentRecordId: string | undefined;
   /** subagent 递归深度。顶层 =0，每层嵌套 +1。 */
   depth: number;
+  /**
+   * 来源身份（H2 W1，D1，与 ExecutionRecord.origin 同源投影/entry 重建）。
+   * 缺省（undefined / 存量磁盘重建源）语义 = "tool"；消费面按 `=== "workflow"`
+   * 负向判定，list 查询缺省过滤（includeWorkflow 缺省 false）。
+   */
+  origin?: RecordOrigin;
+  /**
+   * origin="workflow" 时所属 workflow run id（与 ExecutionRecord.parentRunId 同源）。
+   * W2/W3 run 视图下钻按 collectRecordsByParentRunId 查询；tool 来源恒 undefined。
+   */
+  parentRunId?: string;
   endedAt: number | undefined;
   turns: number;
   totalTokens: number;
@@ -842,8 +861,6 @@ export interface SubagentRecord {
    * （轮终 idle / 重建孤儿兜底），GUI 侧据此排除「真在跑」判定。
    */
   resumable?: boolean;
-  /** 外部 Pi 实例（进程隔离模式下由外部启动的子进程）。 */
-  externalInstance?: AliveMarker;
   /** fork 模式下的 worktree handle。 */
   worktreeHandle?: WorktreeHandle;
   /**

package/src/execution/ui-request-handler-factory.ts

@@ -26,6 +26,7 @@ import { getLogger } from "../core/logger.ts";
 import {
   DialogGlobalQueue,
   isValidDialogTimeout,
+  registerActiveDialogQueue,
   type UiRequest,
   type UiRequestHandler,
   type UiResponse,
@@ -94,6 +95,10 @@ export function createUiRequestHandlerForMode(
   const hostMode = resolveHostMode(ctx.mode);
   if (hostMode === "headless") return undefined;
 
+  // [SR-4 接线登记] 队列是跨子进程全局单例（宿主壳创建），而子进程退出信号来自 core
+  // 引擎镜像层——本工厂是两者交汇点，在返回 handler 的同一路径上登记，壳侧无需改动。
+  registerActiveDialogQueue(dialogQueue);
+
   const realHandler = createRealHandler(ctx, hostMode, registry);
 
   return async (req: UiRequest): Promise<UiResponse> => {

package/src/execution/worktree-manager.ts

@@ -1,4 +1,4 @@
-// src/runtime/worktree-manager.ts
+// src/execution/worktree-manager.ts
 //
 // git worktree 生命周期管理：创建、清理、patch 回传、孤儿 reaper。
 //

package/src/execution/worktree-registry.ts

@@ -1,4 +1,4 @@
-// src/runtime/worktree-registry.ts
+// src/execution/worktree-registry.ts
 //
 // 全局 worktree 注册表：跨 repo 记录所有活 pi-sub-* worktree。
 //