@zhushanwen/pi-subagent-workflow 8.3.0 → 8.5.0

package/src/execution/subagent-service.ts

@@ -29,6 +29,15 @@ import {
   tryTransition,
 } from "./execution-record.ts";
 import { doFinalizeRecord, doFinalizeRoundToIdle } from "./finalize-record.ts";
+import { getEngineDataDir } from "./engine/common/data-dir.ts";
+import { EngineError } from "./engine/common/errors.ts";
+import { JournalWriter } from "./engine/common/event-journal.ts";
+import { resolveJournalPath } from "./engine/paths.ts";
+import { executeOptionsToEngineTaskSpec } from "./engine/host-task-spec.ts";
+import type { EnginePort, RunContext } from "./engine/port.ts";
+import { DEFAULT_ENGINE_ID, getEngine } from "./engine/registry.ts";
+import { type EngineRouteResult, resolveEngineRouting, routeEngine } from "./engine/routing.ts";
+import type { AgentOutcome } from "./engine/types.ts";
 import { ManifestStore } from "./manifest-store.ts";
 import type { ModelConfigService } from "./model-config-service.ts";
 import type { AgentConfig, ModelInfo, ResolvedModel } from "./model-resolver.ts";
@@ -38,7 +47,7 @@ import { getSubagentRecordsDir, getSubagentSessionDir } from "./path-encoding.ts
 import type { StatusFilter } from "./record-store.ts";
 import { RecordStore } from "./record-store.ts";
 import { MAX_FORK_DEPTH } from "./session-context-resolver.ts";
-import { getChildByRecord, killAllSpawnedChildren, runSpawn, spawnedChildren, type SessionRunnerContext, type SpawnResumeOpts } from "./session-runner.ts";
+import { getChildByRecord, killAllSpawnedChildren, registerSpawnedChildForRecord, runSpawn, spawnedChildren, type SessionRunnerContext, type SpawnResumeOpts } from "./session-runner.ts";
 import { isIdle, isResumable, hasLiveProcessHandle } from "./lifecycle-predicates.ts";
 import { startIdleGc } from "./idle-gc.ts";
 import {
@@ -48,8 +57,8 @@ import {
   resetAllEpipeFailures,
   sendPromptCommand,
 } from "./stdin-writer.ts";
-import type { StreamSink } from "./stream-sink.ts";
-import { SubagentStream } from "./stream-sink.ts";
+import type { StreamSink, SubagentStream } from "./stream-sink.ts";
+import { createBackgroundStream } from "./stream-sink.ts";
 import { writeCancelledTombstone } from "./tombstone-store.ts";
 import type { WorktreeHandle } from "./types.ts";
 import type {
@@ -684,8 +693,47 @@ export class SubagentService {
     // ── 1. IDENTITY 解析（确认 → agentConfig → resolveModel）──
     const identity = await this.resolveIdentity(opts);
 
+    // ── 1.5 引擎路由（D4 chat 入口分叉；U2 升级为 routeEngine 编排）──
+    // 三层解析（调用参数 > agent frontmatter > config.json defaultEngine）仍是同步纯
+    // 函数；解析为非 pi 时升级走 routeEngine（probe 编排 + fallback 三守卫）。时机
+    // 选择：路由（含 probe）在 record 创建前完成——兜底时 record 直接按 pi 语义创建 +
+    // engineFallback 留痕（D5 字节级守护只约束「无 fallback 的纯缺省路径」，兜底路径
+    // 的 entry 允许含 engine/engineFallback 字段）；守卫命中/strict 时 routeEngine 在此
+    // throw，不产生孤儿 record。
+    const routingInput = {
+      callEngine: opts.engine,
+      agentEngine: identity.agentConfig?.engine,
+      globalDefaultEngine: this.modelService.getGlobalConfig().defaultEngine,
+    };
+    const routing = resolveEngineRouting(routingInput);
+    let route: EngineRouteResult | undefined;
+    if (routing.engineId !== DEFAULT_ENGINE_ID) {
+      route = await routeEngine({
+        routing: routingInput,
+        // 守卫 c 判据只看调用方显式指定的 model（resolved model 含 ctxModel 兼底，
+        // 恒非空会把一切兜底误判为 model 绑定命中）
+        taskModel: opts.model,
+        strict: this.modelService.getGlobalConfig().engineRouting?.strict === true,
+        probe: (engineId) => getEngine(engineId).probe(),
+      });
+      if (route.engineId !== DEFAULT_ENGINE_ID) {
+        return this.executeViaEngine(opts, identity, route);
+      }
+      // 兜底成功（典型：默认路由 + probe 失败 + 无守卫命中）→ 落回下方 pi 主路径，
+      // record 创建时按 pi 语义 + engine/engineFallback 留痕（engine = 实际执行引擎）
+    }
+    // D5 字节级守护：无 fallback 的 pi 路由剥掉 opts.engine——createRecordForMode
+    // 不盖章（pi record entry 序列化产物不得新增 engine 键，undefined 经 JSON 省略）。
+    // 兜底路径显式盖 engine='pi' + engineFallback（见上方时机注释）。
+    const piOpts =
+      route?.engineFallback !== undefined
+        ? { ...opts, engine: DEFAULT_ENGINE_ID, engineFallback: route.engineFallback }
+        : opts.engine === undefined
+          ? opts
+          : { ...opts, engine: undefined };
+
     // ── 2. RECORD 创建 + 注册 ──
-    const record = this.createRecordForMode(identity, opts, mode);
+    const record = this.createRecordForMode(identity, piOpts, mode);
     emitPendingRegister(this.pi, record.id, record.agent);
 
     // ── 2.5 worktree 创建（仅 worktree===true 或已传入 handle 时）──
@@ -724,7 +772,7 @@ export class SubagentService {
     // ── 4-7. background 包 detached 立即返回 id ──
     // background detached 运行对 tool 层不可见，完成由 notify 驱动新 turn。
     const bgDetails = project(record);
-    this.kickOffBackground(record, { ...opts, worktree: worktreeHandle }, ctx, identity, signal, priority);
+    this.kickOffBackground(record, { ...piOpts, worktree: worktreeHandle }, ctx, identity, signal, priority);
     return { mode: "background", subagentId: record.id, sessionFile: record.sessionFile, details: bgDetails };
   }
 
@@ -1389,6 +1437,10 @@ export class SubagentService {
       depth,
       chatMode: opts.conversation === true,
       idleTimeoutMs: opts.idleTimeoutMs,
+      // P4 引擎留痕（D9①）：opts.engine/engineFallback 由引擎适配层写入（PiEngine.run
+      // 从 RunContext 回填；缺省 = pi 投影，存量调用方零感知）
+      engine: opts.engine,
+      engineFallback: opts.engineFallback,
       controller,
     });
 
@@ -1403,6 +1455,194 @@ export class SubagentService {
     return { mode: "background", subagentId: record.id, sessionFile: record.sessionFile, details };
   }
 
+  // ── 引擎分支（D4/D10：非 pi 引擎的 chat 域执行骨架，U0）──────────
+
+  /**
+   * 路由到非 pi 引擎的执行入口：routeEngine（注册表校验 + probe/守卫）已由 execute
+   * 完成——这里只剩 unsupported 预检 → record 创建+盖章 → detached 引擎 run。
+   * 全部同步拒绝发生在 record 创建前（不产生孤儿 record）。
+   */
+  private executeViaEngine(
+    opts: ExecuteOptions,
+    identity: ResolvedIdentity,
+    route: EngineRouteResult,
+  ): ExecutionHandle {
+    const engine = route.engine;
+    this.assertEngineParamSupport(engine, opts);
+    // record 盖章路由结果（D5 仅 pi 缺省不盖章；非 pi 显式留痕，createRecordForMode
+    // 经 opts.engine/engineFallback 读入 record identity——engine 为实际执行引擎，
+    // fallback 路径 from=请求引擎留痕，probe 通过的常态路径恒缺省）
+    const record = this.createRecordForMode(
+      identity,
+      {
+        ...opts,
+        engine: route.engineId,
+        ...(route.engineFallback !== undefined ? { engineFallback: route.engineFallback } : {}),
+      },
+      "background",
+    );
+    emitPendingRegister(this.pi, record.id, record.agent);
+    this.kickOffEngineRun(record, opts, engine);
+    return { mode: "background", subagentId: record.id, sessionFile: record.sessionFile, details: project(record) };
+  }
+
+  /**
+   * 非 pi 引擎的 unsupported 参数预检（D11 处置「调用前拒绝」的判据 = capabilities）。
+   * conversation / fork / worktree 三参数对首期接入的引擎（zcode）均不可用：
+   * conversation 依赖同进程 idle 复用、fork 依赖父 pi session 上下文继承、worktree 依赖
+   * 文件隔离（capabilities.sandbox='none'）。同步 throw，文案含 capabilities 依据与恢复指引。
+   */
+  private assertEngineParamSupport(engine: EnginePort, opts: ExecuteOptions): void {
+    const caps = engine.capabilities();
+    if (opts.conversation === true && caps.conversation === "unsupported") {
+      throw new EngineError(
+        "engine_capability_unsupported",
+        `engine '${engine.id}' 不支持 conversation（capabilities.conversation = 'unsupported'，` +
+          `spawn 单轮模式无同进程 idle 复用，message/close 交互控制面不可用）`,
+        `改用 engine: pi（支持 conversation 续聊），或不传该参数（一次性任务默认形态）`,
+      );
+    }
+    if (opts.fork === true) {
+      throw new EngineError(
+        "engine_capability_unsupported",
+        `engine '${engine.id}' 不支持 fork（fork 依赖父 pi session 上下文继承，` +
+          `capabilities.steer = '${caps.steer}'——非 pi 引擎无父 session 分叉通道）`,
+        `把所需父上下文写进 task 正文后不传 fork，或改用 engine: pi`,
+      );
+    }
+    if ((opts.worktree === true || typeof opts.worktree === "object") && caps.sandbox === "none") {
+      throw new EngineError(
+        "engine_capability_unsupported",
+        `engine '${engine.id}' 不支持 worktree 隔离（capabilities.sandbox = 'none'，` +
+          `引擎未接文件系统隔离层）`,
+        `改用 engine: pi（worktree 隔离可用），或不传该参数（在 parent cwd 执行）`,
+      );
+    }
+  }
+
+  /**
+   * 非 pi 引擎的 detached 执行编排（与 kickOffBackground 同构的 background 语义）：
+   * pool 并发槽（maxConcurrent 对非 pi 引擎同样生效）→ journal 接线（D6 第②级：
+   * taskId=record.id，初始池 key 占位 'shared'，onPoolResolved retarget 到引擎实际
+   * 池 key——路径与 paths.ts 同源推导）→ engine.run（signal 接 record controller，
+   * kill-chain 两级生效）→ engineHandle 回填（终态迁移落 entry 前）→ 终态迁移 →
+   * bg notify（chat 域宿主职责，与 pi 完成通知同语义）。
+   */
+  private kickOffEngineRun(record: ExecutionRecord, opts: ExecuteOptions, engine: EnginePort): void {
+    const signal = record.controller?.signal;
+    void (async () => {
+      try {
+        await this.pool.acquire(PRIORITY_BACKGROUND, this.effectiveMaxConcurrentFor(record), signal);
+      } catch {
+        // S1: 排队中被 abort（signal.aborted）走 cancelled，与已运行被 abort 一致（runAndFinalize 同款）
+        if (signal?.aborted) {
+          await this.finalizeAborted(record);
+        } else {
+          await this.finalizeFailed(record, new Error("aborted"));
+        }
+        return;
+      }
+      // [review MF1] acquire 成功后必须 finally release：不 release 则
+      // DefaultConcurrencyPool._active 永不递减——每次引擎任务泄漏一个并发槽，累计
+      // maxConcurrent 次后全部 background subagent（pi 与引擎共用同一池）在 acquire 队列永久挂起
+      try {
+        await this.runEngineTask(record, opts, engine, signal);
+        // cancel 抢先（closedReason='cancelled'）时 cancelBackground 自己 notify，跳过
+        if (record.closedReason !== "cancelled") {
+          this.notifyComplete(record);
+        }
+      } finally {
+        this.pool.release();
+      }
+    })();
+  }
+
+  /**
+   * kickOffEngineRun 的 acquire 后主体：journal 接线（D6 第②级：taskId=record.id，
+   * 初始池 key 占位 'shared'，onPoolResolved retarget 到引擎实际池 key）→ engine.run
+   * （signal 接 record controller，kill-chain 两级生效）→ engineHandle 回填（终态迁移
+   * 落 entry 前）→ 终态迁移。bg notify 归编排侧（与 kickOffBackground 收尾通知归编排对称）。
+   */
+  private async runEngineTask(
+    record: ExecutionRecord,
+    opts: ExecuteOptions,
+    engine: EnginePort,
+    signal: AbortSignal | undefined,
+  ): Promise<void> {
+    const journal = new JournalWriter({
+      path: resolveJournalPath(getEngineDataDir(), engine.id, "shared", record.id),
+      taskId: record.id,
+      engineId: engine.id,
+    });
+    const retargetJournal = (poolKey: string): void => {
+      journal.retarget(resolveJournalPath(getEngineDataDir(), engine.id, poolKey, record.id));
+    };
+    // 对齐点③：journal 路径权威 = 引擎声明的池 key（writer 初始用占位，retarget 后
+    // 与 handle.poolKey 同源）。模式对齐 SAR 的 journalingOnEvent：先落盘再转发。
+    const runCtx: RunContext = {
+      taskId: record.id,
+      poolKey: "shared",
+      signal,
+      ctxModel: opts.ctxModel,
+      onEvent: (event) => journal.append(event),
+      onPoolResolved: retargetJournal,
+      // D9①：路由层 fallback 留痕投影进 outcome（zcode 无独立 record 通路）
+      ...(record.engineFallback !== undefined ? { engineFallback: record.engineFallback } : {}),
+      // D10 终止链：engine spawn 的子进程注册进 spawnedChildren 记账
+      //（cancelBackground SIGTERM / dispose killAll 收割对非 pi record 生效）
+      onChildSpawned: (child) => registerSpawnedChildForRecord(record.id, child),
+    };
+    try {
+      const { handle, outcome } = await engine.run(executeOptionsToEngineTaskSpec(opts), runCtx);
+      // engineHandle 完整回填（U2：终态迁移落 entry 前）。sessionRef 整体透传——
+      // 失败终态 sessionId 缺失时也回填已有部分（dbPath/poolKey），读侧①级降②级
+      // 的防御形态；journalPath 取 retarget 后的实际落盘路径（writer 是路径权威）。
+      record.engineHandle = {
+        sessionRef: handle.data.sessionRef,
+        poolKey: handle.data.poolKey,
+        journalPath: journal.path,
+      };
+      await journal.close();
+      await this.finalizeEngineOutcome(record, outcome);
+    } catch (err) {
+      // engine.run prepare 期 reject（进程创建前）→ failed 终态（与 runAndFinalize catch 同语义）；
+      // journal 尽力而为收口（②级数据源写失败已由 writer 内部 warn 收敛）
+      await journal.close();
+      await this.finalizeFailed(record, err);
+    }
+  }
+
+  /**
+   * 分层并发配额：depth 越深可用配额越少（下限 1）。fork 深度护栏在池维度的投影，
+   * 公式约定以 concurrency-pool.ts 注释为登记处、此处为唯一代码锚点。
+   */
+  private effectiveMaxConcurrentFor(record: ExecutionRecord): number {
+    return Math.max(1, this.pool.maxConcurrent - record.depth);
+  }
+
+  /**
+   * engine.run resolve 的终态迁移：outcome.error → failed（success=false + error 文案）；
+   * 否则 done（result=content）。CAS 抢锁（tryTransition）防与 cancelBackground 双收尾。
+   */
+  private async finalizeEngineOutcome(record: ExecutionRecord, outcome: AgentOutcome): Promise<void> {
+    if (outcome.sessionFile !== undefined) {
+      record.sessionFile = outcome.sessionFile;
+    }
+    const result: AgentResult = {
+      text: outcome.content,
+      turns: outcome.usage?.turns ?? 0,
+      durationMs: outcome.durationMs ?? Date.now() - record.startedAt,
+      success: outcome.error === undefined,
+      ...(outcome.error !== undefined ? { error: outcome.error } : {}),
+      sessionId: outcome.sessionId ?? record.id,
+      toolCalls: [],
+      ...(outcome.parsedOutput !== undefined ? { parsedOutput: outcome.parsedOutput } : {}),
+    };
+    if (tryTransition(record, "closed", "gc")) {
+      await this.finalizeRecord(record, result, "closed", "gc");
+    }
+  }
+
   // ── 执行内部：run + finalize（sync/bg 共用）──────────────
 
   /** 共享的"干活 + 收尾"——sync 直接 await，background 在 detached 里调。 */
@@ -1421,9 +1661,8 @@ export class SubagentService {
     const pooled = record.mode === "background";
     let acquired = false;
     if (pooled) {
-      const effectiveMaxConcurrent = Math.max(1, this.pool.maxConcurrent - record.depth);
       try {
-        await this.pool.acquire(priority, effectiveMaxConcurrent, signal);
+        await this.pool.acquire(priority, this.effectiveMaxConcurrentFor(record), signal);
         acquired = true;
       } catch {
         // S1: 排队中被 abort（signal.aborted）走 cancelled，与已运行被 abort 一致。
@@ -1575,10 +1814,9 @@ export class SubagentService {
     /** resume 选项（M2-B1）：透传 runAndFinalize→runSpawn。undefined = 新 session。 */
     resume?: SpawnResumeOpts,
   ): void {
-    // 创建 streaming 生命周期对象——streamSink 为 null（session_start 未注入）时降级为 undefined。
-    const stream = this.streamSink
-      ? new SubagentStream(record.id, this.streamSink)
-      : undefined;
+    // 创建 streaming 生命周期对象。策略（含 widget 退役步骤 2：GUI + relay 激活时停发
+    // 私货、TUI/未激活原样创建、sink 未注入降级 undefined）集中在 createBackgroundStream。
+    const stream = createBackgroundStream(record.id, this.streamSink, ctx.mode, process.env);
 
     void this.runAndFinalize(
       record, opts, ctx, identity, signal, priority,

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

@@ -8,7 +8,9 @@
 // 接线层级：
 //   [跨模块 port] implements AgentRunner（orchestration/models/ports.ts）
 //   [模块内直调] mapToExecuteOptions + mergeTimeoutSignal（execute-options-mapper）
-//   [模块内直调] this.subagentService.executeAndAwait
+//   [P4 路由层]  engine/routing.ts routeEngine（三层优先级 + probe + fallback 三守卫，D9）
+//   [引擎层]     EnginePort.run（pi = 本地 DI 绑定实例；非 pi = registry.getEngine 动态获取）
+//   [模块内直调] this.subagentService.executeAndAwait（PiEngine 内部委托目标）
 //
 // 设计基线：
 //   D-A2（映射归 adapter）/ D-A8（onEvent 桥接）/ D-A9（timeoutMs 合并 signal）/
@@ -17,8 +19,19 @@
 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 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 { getModelConfigService } from "./model-config-service.ts";
 import type { ModelInfo } from "./model-resolver.ts";
+import { registerSpawnedChildForRecord } from "./session-runner.ts";
 import type { SubagentStream } from "./stream-sink.ts";
 import type { SubagentService } from "./subagent-service.ts";
 import type { ExecuteOptions } from "./types.ts";
@@ -51,14 +64,27 @@ export interface SubprocessAgentRunnerDeps {
  *   - 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 解析三层优先级（调用参数 opts.engine >
+ * agent frontmatter engine > 全局默认 'pi'）+ probe + fallback 三守卫（D9）。路由失败
+ * （engine_not_found / engine_probe_failed / model_not_available）不 reject，入
+ * result.error——与 executeAgentCall 契约一致。
  */
 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;
+    this.piEngine = createPiEngine(() => this.subagentService);
   }
 
   /**
@@ -72,13 +98,16 @@ export class SubprocessAgentRunner implements AgentRunner {
   }
 
   /**
-   * 执行单次 agent 调用：委托 SubagentService.executeAndAwait。
+   * 执行单次 agent 调用：路由（P4）→ EnginePort.run → PiEngine 委托
+   * SubagentService.executeAndAwait。
    *
    * 接线链路：
-   *   mergeTimeoutSignal → mapToExecuteOptions →
-   *   this.subagentService.executeAndAwait → 返回 AgentResult
+   *   routeEngine（三层 + probe + 守卫）→ mergeTimeoutSignal → mapToExecuteOptions →
+   *   AgentTaskSpec → engine.run（PiEngine：spec → ExecuteOptions 还原 + engine 留痕）→
+   *   executeAndAwait → AgentOutcome → AgentResult
    *
    * 错误处理：不 reject。
+   *   - 路由失败（未注册 id / probe 失败 + 守卫或 strict）→ AgentResult.error（错误码前缀）
    *   - executeAndAwait 内部失败 → 返回 AgentResult(success:false) → 已映射 error 字段
    *   - executeAndAwait throw（嵌套超限 BC-12）→ catch → AgentResult.error
    *   - spawn 级失败已由 runSpawn 内部收口为 failed AgentResult（不逃逸）
@@ -91,22 +120,105 @@ 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;
+    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()]),
+        });
+      }
+    } catch (err) {
+      // buildRoutingInput 的 agent 解析期校验（未注册 frontmatter engine）与路由失败
+      // （probe + strict/守卫）一并在此收口——「不 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 返回后回填）。
+    //
+    // 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 自描述定位不受影响）。
+    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);
+    };
+
     try {
-      // ── D-A9: timeoutMs 合并 signal ──
+      // ── 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);
 
-      // ── D-A8: onEvent 桥接 ──
-      // executeAndAwait 发强类型 AgentEvent（session-runner handleSdkEvent 出口）。
-      // workflow 的 onEvent 闭包（error-recovery.ts dispatchAgentCall）类型已升级为
-      // (event: AgentEvent) => updateFromEvent(liveRecord, event)（D-005）。
-      // SAR 直接透传 onEvent——类型对齐后零桥接开销。
-      const bridgedOnEvent = onEvent;
-
-      // ── 核心委托 ──
-      return await this.subagentService.executeAndAwait(mappedOpts, mergedSignal, bridgedOnEvent, stream);
+      // ── P1/P4 引擎接线：EnginePort.run ──
+      const runCtx: RunContext = {
+        taskId,
+        poolKey: PI_POOL_KEY,
+        signal: mergedSignal,
+        onEvent: journalingOnEvent,
+        ctxModel: this.ctxModel,
+        ...(route.engineFallback !== undefined ? { engineFallback: route.engineFallback } : {}),
+        onPoolResolved: retargetJournal,
+        // [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 } : {}),
+      };
+      const { handle, outcome } = await route.engine.run(
+        // 泛化为中立声明（PiEngine 内部再还原回 ExecuteOptions——往返保真，
+        // 由 engines/pi/__tests__/task-spec-mapper.test.ts 逐字段锁定）
+        executeOptionsToTaskSpec(mappedOpts),
+        runCtx,
+      );
+      // handle.journalPath 回填（§3.3.6：read ②级的自描述定位符——运行期落盘路径
+      // 权威在 writer，handle 记录最终路径供跨重启 read 消费）
+      backfillJournalPath(handle, journal.path);
+      return outcomeToRunnerResult(outcome);
     } catch (err) {
       // executeAndAwait throw（嵌套超限 ForkDepthExceededError，BC-12）或未预期异常 → 不 reject，入 error。
       const message = err instanceof Error ? err.message : String(err);
@@ -116,6 +228,76 @@ export class SubprocessAgentRunner implements AgentRunner {
         error: message,
         toolCalls: [],
       };
+    } finally {
+      // run 终态后 flush + fsync 一次（§3.3.6 写入纪律）；写失败已由 writer 内部
+      // warn + failed 收口，close 不抛（journal 是②级尽力而为数据源）
+      await journal.close();
     }
   }
+
+  // ── 内部 ──
+
+  /**
+   * 引擎获取：pi 走 per-session DI 绑定（mock 语义 + 生产同单例，P1 行为零变化）；
+   * 非 pi 经 registry.getEngine 动态获取（P4：引擎身份归属注册表，未注册 id 抛
+   * EngineNotFoundError——路由期已前置校验，这里是防御性兜底）。
+   */
+  private engineFor(engineId: string): EnginePort {
+    if (engineId === "pi") return this.piEngine;
+    return getEngine(engineId);
+  }
+
+  /**
+   * 三层路由输入装配（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: err instanceof Error ? err.message : String(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 投影
+ * 通道在后续 wave 接线，workflow 引擎不消费）。其余字段由 PiEngine 从 executeAndAwait
+ * 的返回值逐字段映射而来，字段全集完整性由 pi-engine 单测锁定（缺字段会在该处转红，
+ * 不会静默丢失）。
+ */
+function outcomeToRunnerResult(outcome: AgentOutcome): AgentResult {
+  return {
+    content: outcome.content,
+    parsedOutput: outcome.parsedOutput,
+    usage: outcome.usage,
+    durationMs: outcome.durationMs,
+    error: outcome.error,
+    sessionId: outcome.sessionId,
+    sessionFile: outcome.sessionFile,
+    worktreePath: outcome.worktreePath,
+    toolCalls: outcome.toolCalls,
+  };
 }