@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/engine/__tests__/registry.test.ts

@@ -2,20 +2,23 @@
 //
 // registry 专属测试（P1 验收 4）：注册/获取/listEngines/hasEngine/
 // 未注册 id 报 engine_not_found（错误文案含已注册清单——错误规格表第 1 行契约）。
+// [R1 D6] 追加：重注册先 dispose 旧单例（D6②）+ disposeEngines 收割遍历（D6③）。
 
-import { beforeEach, describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { EnginePort, RunContext } from "../port.ts";
 import {
   clearEngines,
   DEFAULT_ENGINE_ID,
+  disposeEngines,
   EngineNotFoundError,
   getEngine,
   hasEngine,
   listEngines,
   registerEngine,
 } from "../registry.ts";
-import type { AgentTaskSpec, SessionView } from "../types.ts";
+import type { SessionView } from "../types.ts";
+import type { AgentCallOpts } from "../../../orchestration/models/types.ts";
 
 /** 最小可运行假引擎（完整实现 EnginePort 五面——不 cast，防接口漂移失检）。 */
 function makeFakeEngine(id: string): EnginePort {
@@ -32,10 +35,11 @@ function makeFakeEngine(id: string): EnginePort {
       resume: "unsupported",
       interrupt: "kill-only",
       permissionMode: "fixed",
+      maxTurns: false,
     }),
     probe: () =>
       Promise.resolve({ ok: true, engineVersion: "0.0.0-test", checks: [{ name: "stub", ok: true }] }),
-    run: (_task: AgentTaskSpec, _ctx: RunContext) =>
+    run: (_task: AgentCallOpts, _ctx: RunContext) =>
       Promise.reject(new Error("fake engine: run not implemented")),
     interact: () => Promise.resolve({ ok: false, code: "engine_capability_unsupported", message: "stub" }),
     read: (_handle: Parameters<EnginePort["read"]>[0]): Promise<SessionView> =>
@@ -117,4 +121,91 @@ describe("engine registry", () => {
   it("DEFAULT_ENGINE_ID 缺省为 'pi'（D9：回填期零风险默认）", () => {
     expect(DEFAULT_ENGINE_ID).toBe("pi");
   });
+
+  // ── [R1 D6②] 重注册同名：先 dispose 已实例化的旧单例（防常驻资源泄漏）──
+
+  it("重注册同名：已实例化的旧单例 dispose 被调用一次，新工厂实例生效", () => {
+    const dispose = vi.fn(() => Promise.resolve());
+    registerEngine("fake", () => ({ ...makeFakeEngine("fake"), dispose }));
+    getEngine("fake"); // 实例化旧引擎（未实例化 = 无常驻资源可回收）
+    registerEngine("fake", () => makeFakeEngine("fake-v2"));
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(getEngine("fake").id).toBe("fake-v2");
+  });
+
+  it("重注册同名：旧实例 dispose 同步 throw 不阻断替换（best-effort）", () => {
+    const dispose = vi.fn(() => {
+      throw new Error("dispose boom");
+    });
+    registerEngine("fake", () => ({ ...makeFakeEngine("fake"), dispose }));
+    getEngine("fake");
+    expect(() => registerEngine("fake", () => makeFakeEngine("fake-v2"))).not.toThrow();
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(getEngine("fake").id).toBe("fake-v2");
+  });
+
+  it("重注册同名：旧实例 dispose 异步 reject 不阻断替换、不产生 unhandledRejection", async () => {
+    const dispose = vi.fn(() => Promise.reject(new Error("dispose async boom")));
+    registerEngine("fake", () => ({ ...makeFakeEngine("fake"), dispose }));
+    getEngine("fake");
+    expect(() => registerEngine("fake", () => makeFakeEngine("fake-v2"))).not.toThrow();
+    expect(getEngine("fake").id).toBe("fake-v2");
+    // flush macrotask：reject 必须已被 registry 侧 catch 吞掉——否则 vitest 以
+    // unhandledRejection 判本文件失败，用例即失效
+    await new Promise<void>((resolve) => setImmediate(resolve));
+  });
+
+  it("重注册同名：旧引擎仅注册工厂未实例化时不触发 dispose（惰性单例无资源）", () => {
+    const dispose = vi.fn(() => Promise.resolve());
+    registerEngine("fake", () => ({ ...makeFakeEngine("fake"), dispose }));
+    // 不 getEngine——singletons 无记录
+    registerEngine("fake", () => makeFakeEngine("fake-v2"));
+    expect(dispose).not.toHaveBeenCalled();
+  });
+
+  it("重注册同名：旧实例未实现 dispose（可选成员）时直接替换不抛", () => {
+    registerEngine("fake", () => makeFakeEngine("fake"));
+    getEngine("fake");
+    expect(() => registerEngine("fake", () => makeFakeEngine("fake-v2"))).not.toThrow();
+  });
+
+  // ── [R1 D6③] disposeEngines：宿主收割（killAllSpawnedChildren）前的触发遍历 ──
+
+  describe("disposeEngines（D6③）", () => {
+    it("只对已实例化的引擎触发 dispose（绝不实例化未用引擎）", () => {
+      const instantiated = vi.fn(() => Promise.resolve());
+      const neverInstantiated = vi.fn(() => Promise.resolve());
+      registerEngine("used", () => ({ ...makeFakeEngine("used"), dispose: instantiated }));
+      registerEngine("unused", () => ({ ...makeFakeEngine("unused"), dispose: neverInstantiated }));
+      getEngine("used");
+      disposeEngines();
+      expect(instantiated).toHaveBeenCalledTimes(1);
+      expect(neverInstantiated).not.toHaveBeenCalled();
+    });
+
+    it("未实现 dispose 的引擎（可选面）跳过不抛", () => {
+      registerEngine("plain", () => makeFakeEngine("plain"));
+      getEngine("plain");
+      expect(() => disposeEngines()).not.toThrow();
+    });
+
+    it("dispose 幂等（实现承诺）：disposeEngines 重复调用不抛、逐次触发", async () => {
+      const dispose = vi.fn(() => Promise.resolve());
+      registerEngine("fake", () => ({ ...makeFakeEngine("fake"), dispose }));
+      getEngine("fake");
+      expect(() => disposeEngines()).not.toThrow();
+      expect(() => disposeEngines()).not.toThrow();
+      // 幂等语义由引擎实现承诺（不变量 4），本断言只验证 registry 重复触发不抛
+      expect(dispose).toHaveBeenCalledTimes(2);
+      await new Promise<void>((resolve) => setImmediate(resolve));
+    });
+
+    it("dispose 后单例保留（run 自动重建归引擎承诺，registry 不删——不变量 4 边界）", () => {
+      const dispose = vi.fn(() => Promise.resolve());
+      registerEngine("fake", () => ({ ...makeFakeEngine("fake"), dispose }));
+      const engine = getEngine("fake");
+      disposeEngines();
+      expect(getEngine("fake")).toBe(engine);
+    });
+  });
 });

package/src/execution/engine/__tests__/routing.test.ts

@@ -6,8 +6,10 @@ import { describe, expect, it } from "vitest";
 import type { EnginePort, RunContext } from "../port.ts";
 import { DEFAULT_ENGINE_ID, EngineNotFoundError } from "../registry.ts";
 import { EngineError } from "../common/errors.ts";
-import type { AgentTaskSpec, ProbeReport, SessionView } from "../types.ts";
-import { resolveEngineRouting, routeEngine, type EngineRouteOptions } from "../routing.ts";
+import type { ProbeReport, SessionView } from "../types.ts";
+import type { AgentCallOpts } from "../../../orchestration/models/types.ts";
+import { resolveEngineRouting, routeEngine, routeEngineForHost, type EngineRouteOptions, type HostRouteOptions } from "../routing.ts";
+import type { EngineRouteResult } from "../routing.ts";
 
 /** 最小可运行假引擎（probe 结果可注入）。 */
 function makeFakeEngine(id: string, probeOk: boolean): EnginePort {
@@ -24,6 +26,7 @@ function makeFakeEngine(id: string, probeOk: boolean): EnginePort {
       resume: "cold",
       interrupt: "kill-only",
       permissionMode: "native",
+      maxTurns: false,
     }),
     probe: () =>
       Promise.resolve(
@@ -36,7 +39,7 @@ function makeFakeEngine(id: string, probeOk: boolean): EnginePort {
               error: { code: "engine_probe_failed", recovery: "reinstall the engine binary and retry the probe" },
             } satisfies ProbeReport,
       ),
-    run: (_t: AgentTaskSpec, _c: RunContext) => Promise.reject(new Error("fake: run not implemented")),
+    run: (_t: AgentCallOpts, _c: RunContext) => Promise.reject(new Error("fake: run not implemented")),
     interact: () => Promise.resolve({ ok: false, code: "engine_capability_unsupported", message: "stub" }),
     read: (_h: Parameters<EnginePort["read"]>[0]): Promise<SessionView> =>
       Promise.resolve({ engineId: id, turns: [], source: "outcome-only" }),
@@ -162,9 +165,10 @@ describe("routeEngine：路由 + 探针 + 守卫编排（验收 1/2）", () => {
     expect((err as EngineError).recovery).toContain("retry the probe");
   });
 
-  it("守卫 b（首期与 a 合流）：AgentTaskSpec.requires 形状预留存在且不参与首期判定", async () => {
-    // 形状预留的类型面由 typecheck 守护；行为面：frontmatter 指定（非 call）+ 无 model
-    // → 仍走 fallback（守卫 b 独立生效留给 requires 下钻，见 types.ts 注释）
+  it("守卫 b（首期与 a 合流）：能力依赖声明无独立载体，frontmatter 指定（非 call）不阻断 fallback", async () => {
+    // [D6 合流] 原 AgentTaskSpec.requires 形状预留已随任务形状合流裁撤（无生产写入方，
+    // 见 AgentCallOpts 类型注释）；行为面保持：frontmatter 指定（非 call）+ 无 model
+    // → 仍走 fallback（能力依赖声明的独立载体留给将来下钻）
     const { opts } = makeRoute({ zcodeProbeOk: false, routing: { agentEngine: "zcode" } });
     const result = await routeEngine(opts);
     expect(result.engineFallback).toBeDefined();
@@ -229,3 +233,108 @@ describe("routeEngine：路由 + 探针 + 守卫编排（验收 1/2）", () => {
     expect(result.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
   });
 });
+
+// ============================================================
+// routeEngineForHost（D3-② 路由单点：宿主两调用点的统一编排）
+// ============================================================
+
+describe("routeEngineForHost：宿主统一路由（D3-②）", () => {
+  /** 本地 pi 引擎实例替身（chat 域 = chatPiEngine / workflow 域 = SAR per-session DI）。 */
+  function makeLocalPi(): EnginePort {
+    return makeFakeEngine("local-pi", true);
+  }
+
+  /** 装配 host 路由参数（registry 面复用 makeRoute 的注入件）。 */
+  function makeHostRoute(overrides?: Parameters<typeof makeRoute>[0]): {
+    hostOpts: HostRouteOptions;
+    probeCalls: string[];
+    engines: Map<string, EnginePort>;
+    piEngine: EnginePort;
+  } {
+    const { opts, probeCalls, engines } = makeRoute(overrides);
+    const piEngine = makeLocalPi();
+    const { routing, ...rest } = opts;
+    return { hostOpts: { ...rest, routing: routing ?? {}, piEngine }, probeCalls, engines, piEngine };
+  }
+
+  it("pi 请求（缺省）：同步短路——返回值不是 Promise（零微任务，缺省路径时序契约）且免探", () => {
+    const { hostOpts, piEngine, probeCalls } = makeHostRoute();
+    const routed = routeEngineForHost(hostOpts);
+    expect(routed).not.toBeInstanceOf(Promise);
+    const route = routed as EngineRouteResult;
+    expect(route.engine).toBe(piEngine); // 本地 pi 实例接管，不经 registry
+    expect(route.engineId).toBe("pi");
+    expect(route.source).toBe("default");
+    expect(probeCalls).toEqual([]); // pi 免探（D7 轻量口径，缺省路径零 probe 开销）
+  });
+
+  it("显式 engine='pi'：同步短路同形（call source 留痕）", () => {
+    const { hostOpts, piEngine } = makeHostRoute({ routing: { callEngine: "pi" } });
+    const routed = routeEngineForHost(hostOpts);
+    expect(routed).not.toBeInstanceOf(Promise);
+    const route = routed as EngineRouteResult;
+    expect(route.engine).toBe(piEngine);
+    expect(route.source).toBe("call");
+  });
+
+  it("非 pi 请求（frontmatter zcode + probe ok）：返回 Promise，resolve 经注入获取引擎", async () => {
+    const { hostOpts, engines } = makeHostRoute({ routing: { agentEngine: "zcode" } });
+    const routed = routeEngineForHost(hostOpts);
+    expect(routed).toBeInstanceOf(Promise);
+    const route = await routed;
+    expect(route.engine).toBe(engines.get("zcode"));
+    expect(route.engineId).toBe("zcode");
+  });
+
+  it("probe 失败兜底回 pi：本地 pi 实例接管（不依赖 registry 的 pi 注册态）+ fallback 留痕", async () => {
+    const { hostOpts, piEngine } = makeHostRoute({
+      zcodeProbeOk: false,
+      routing: { agentEngine: "zcode" },
+    });
+    const route = await routeEngineForHost(hostOpts);
+    expect(route.engine).toBe(piEngine);
+    expect(route.engineId).toBe("pi");
+    expect(route.requestedEngineId).toBe("zcode");
+    expect(route.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+  });
+
+  it("registry 面未注册 pi：兜底/清单两口径都不把本地 pi 漏报（SAR 单测 mock 形态）", async () => {
+    // registry 面只含 zcode（probe 失败）——模拟「本地 pi 不在全局注册表」的注入形态
+    const engines = new Map<string, EnginePort>([["zcode", makeFakeEngine("zcode", false)]]);
+    const probeCalls: string[] = [];
+    const piEngine = makeLocalPi();
+    const mkOpts = (): HostRouteOptions => ({
+      routing: { agentEngine: "zcode" },
+      strict: false,
+      probe: (id) => {
+        probeCalls.push(id);
+        return engines.get(id)!.probe();
+      },
+      piEngine,
+      getEngineFn: (id) => {
+        const e = engines.get(id);
+        if (e === undefined) throw new EngineNotFoundError(id, [...engines.keys()]);
+        return e;
+      },
+      hasEngineFn: (id) => engines.has(id),
+      listEnginesFn: () => [...engines.keys()],
+    });
+    // probe 失败 + 无守卫 → 兜底回 pi：本地实例接管，不触 registry 的 pi 缺失
+    const route = await routeEngineForHost(mkOpts());
+    expect(route.engine).toBe(piEngine);
+    expect(route.engineId).toBe("pi");
+    expect(probeCalls).toEqual(["zcode"]);
+    // 未注册 id：engine_not_found 文案清单含 pi（本地 pi 恒可用，不漏报）
+    const ghostOpts: HostRouteOptions = {
+      ...mkOpts(),
+      routing: { callEngine: "ghost" },
+    };
+    const err = await Promise.resolve(routeEngineForHost(ghostOpts)).then(
+      (r: unknown) => r,
+      (e: unknown) => e,
+    );
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toContain("engine_not_found");
+    expect((err as EngineNotFoundError).registered).toContain("pi");
+  });
+});

package/src/execution/engine/common/capability-gate.ts

@@ -0,0 +1,92 @@
+// src/execution/engine/common/capability-gate.ts
+//
+// [D3-④ 预检 capabilities 化] 调用前预检的唯一实现（capabilities 驱动，无引擎 id
+// 特判）。设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-④ + r3 裁定
+// （EngineCapabilities 新增 maxTurns 能力位，不保留硬编码 shape 检查）+ §3.4 错误规格
+// 第 1 行（engine_capability_unsupported，既有错误族）。
+//
+// 判据形态：每个引擎拦截「自己 capabilities 声明不支持的能力」——
+//   - conversation → capabilities.conversation === 'unsupported'
+//   - fork/forkFromSessionFile → session 分叉通道族全缺（steer 与 conversation 均
+//     'unsupported'，见下方 fork 判据说明）
+//   - maxTurns → capabilities.maxTurns === false（r3 扩位）
+//   - worktree（boolean true 或 WorktreeHandle）→ capabilities.sandbox === 'none'
+//
+// 调用点仍是两处（单点的是实现，不是调用点）：
+//   - chat 域：executeViaEngine 同步段、record 创建前（engine.capabilities() 同步可得，
+//     承接「全部同步拒绝发生在 record 创建前、不产生孤儿 record」不变量）；
+//   - workflow 域：SAR.run 路由后、engine.run 前（同模块调用）。
+//
+// 行为变化声明（§3.4）：唯一有意行为变化 = workflow 域 zcode+worktree 由漏拦变拦截
+// （修复双轨清单 #7 的跨域缺口）；pi 的 maxTurns/fork/conversation/worktree 等既有
+// 合法能力零拦截（V4⑤ 反向守护——pi 声明 conversation='native'、sandbox='emulated'、
+// maxTurns=true，全数放行）。
+
+import { EngineError } from "./errors.ts";
+import type { EngineCapabilities } from "../types.ts";
+
+/**
+ * 预检输入的任务形状子集——ExecuteOptions（chat 域）与 AgentCallOpts（D6 合流后的
+ * 单一任务形状，workflow 域 SAR 直传）共有的能力相关字段面。结构子集而非具体类型：
+ * 两域的 opts 类型都能直接传入。
+ */
+export interface TaskShapeForGate {
+  conversation?: boolean;
+  fork?: boolean;
+  forkFromSessionFile?: string;
+  worktree?: boolean | { path: string };
+  maxTurns?: number;
+}
+
+/**
+ * 调用前预检：任务形状中的能力参数对引擎 capabilities 逐一对照，声明不支持即抛
+ * EngineError(engine_capability_unsupported)——同步 throw、进程/record 创建前，文案
+ * 含 capabilities 依据与恢复指引（换参数/换引擎）。
+ *
+ * fork 判据说明（借位裁定）：fork 依赖父 session 上下文继承（父会话文件作为分叉源），
+ * 引擎具备该语义的能力面信号 = 会话分叉/交互通道族（steer 或 conversation 任一非
+ * 'unsupported'）。pi conversation='native'（chatMode idle 复用）→ 放行；zcode 双
+ * 'unsupported'（argv-only spawn 单轮，无父 session 分叉通道）→ 拒绝。仅凭 steer 判
+ * 会误拦 pi（pi 的 steer 声明 'unsupported'——RPC 有但 spawn 链路未接通，与 fork 的
+ * 初始上下文继承是两条轴），故取通道族任一可用即支持的分寸。
+ */
+export function assertTaskShapeSupported(
+  engineId: string,
+  caps: EngineCapabilities,
+  task: TaskShapeForGate,
+): void {
+  if (task.conversation === true && caps.conversation === "unsupported") {
+    throw new EngineError(
+      "engine_capability_unsupported",
+      `engine '${engineId}' 不支持 conversation（capabilities.conversation = 'unsupported'，` +
+        `spawn 单轮模式无同进程 idle 复用，message/close 交互控制面不可用）`,
+      `改用 engine: pi（支持 conversation 续聊），或不传该参数（一次性任务默认形态）`,
+    );
+  }
+  if (task.fork === true || task.forkFromSessionFile !== undefined) {
+    if (caps.steer === "unsupported" && caps.conversation === "unsupported") {
+      throw new EngineError(
+        "engine_capability_unsupported",
+        `engine '${engineId}' 不支持 fork${task.forkFromSessionFile !== undefined ? "（fork-from 同为父 session 上下文继承）" : ""}（fork 依赖父 session 上下文继承，` +
+          `capabilities.steer = '${caps.steer}' / conversation = '${caps.conversation}'——引擎无父 session 分叉通道）`,
+        `把所需父上下文写进 task 正文后不传 fork，或改用 engine: pi`,
+      );
+    }
+  }
+  if (task.maxTurns !== undefined && caps.maxTurns === false) {
+    throw new EngineError(
+      "engine_capability_unsupported",
+      `engine '${engineId}' 不支持 maxTurns（capabilities.maxTurns = false，轮数上限依赖 turn_end 事件流，` +
+        `本引擎无此语义——静默丢弃会造成「传了上限却失控」的假象）`,
+      `去掉 maxTurns 参数重派，或改用 engine: pi（turn limiter 执行轮数上限）`,
+    );
+  }
+  if ((task.worktree === true || typeof task.worktree === "object") && caps.sandbox === "none") {
+    throw new EngineError(
+      "engine_capability_unsupported",
+      `engine '${engineId}' 不支持 worktree 隔离（capabilities.sandbox = 'none'，` +
+        `引擎未接文件系统隔离层）`,
+      `改用 engine: pi（worktree 隔离可用），或不传该参数（在 parent cwd 执行）`,
+    );
+  }
+}

package/src/execution/engine/common/journal-wiring.ts

@@ -0,0 +1,97 @@
+// src/execution/engine/common/journal-wiring.ts
+//
+// [D3-③ journal 接线合一] host 侧 event journal 接线的共享 helper（唯一实现，两调用
+// 点——SubagentService.runEngineTask（chat 域）与 SubprocessAgentRunner.run（workflow
+// 域））。设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-③（writer +
+// retarget + handle 回填两份提为 common 层共享 helper）+ 双轨清单 #6。
+//
+// 收敛前形态（两份同构接线）：
+//   - subagent-service.ts：new JournalWriter（占位池 key 'shared'）+ retarget 闭包 +
+//     record.engineHandle.journalPath 回填；
+//   - subprocess-agent-runner.ts：new JournalWriter（占位 PI_POOL_KEY）+ retarget 闭包 +
+//     journalingOnEvent 包装（先落盘再转发 workflow liveRecord）+ handle.data.journalPath 回填。
+//
+// 机制语义（对齐点③：路径权威 = 引擎声明的池 key）：writer 初始用占位池 key 建路径，
+// 非池化稳定引擎（zcode）在 prepare 期经 RunContext.onPoolResolved 声明实际池 key →
+// retarget——保证 journal 落盘路径与 handle.poolKey 同源。run 终态后 close（flush +
+// fsync 一次，§3.3.6 写入纪律；写失败已由 writer 内部 warn + failed 收口，close 不抛，
+// journal 是②级尽力而为数据源）。
+
+import type { AgentEvent } from "../../../shared/agent-event.ts";
+import { getEngineDataDir } from "./data-dir.ts";
+import { JournalWriter } from "./event-journal.ts";
+import { resolveJournalPath } from "../paths.ts";
+import type { EngineHandle } from "../types.ts";
+
+/**
+ * journal 初始占位池 key（= pi 的恒定池 key 'shared'）。pi 无隔离池
+ * （PI_CODING_AGENT_DIR 全局一份，设计 §3.3.9），占位即终值；zcode 在 prepare 期
+ * retarget 到实际池 key。值与 RunContext.poolKey 的初始占位同源——本常量是该值在
+ * common 层的单一权威（原先 Service 用 'shared' 字面量、SAR 用 PI_POOL_KEY，等值异名）。
+ */
+export const JOURNAL_INITIAL_POOL_KEY = "shared";
+
+/** wireEventJournal 的参数。 */
+export interface JournalWiringOptions {
+  /** 实际执行引擎 id（journal 路径分段 + line 元数据）。 */
+  engineId: string;
+  /** 宿主侧任务标识（journal 文件名与池引用计数 key：chat 域 = record.id；workflow 域 = 'sa-' 前缀占位）。 */
+  taskId: string;
+  /**
+   * journal 落盘后的事件转发（workflow 域的 liveRecord 通道）。缺省不转发（chat 域
+   * 无下游 onEvent 消费者——journal 是事件唯一出口）。
+   */
+  forwardEvents?: (event: AgentEvent) => void;
+}
+
+/** wireEventJournal 的产物（喂给 RunContext 的回调簇 + 终态收口/回填面）。 */
+export interface JournalWiring {
+  /** journaling onEvent：先落盘再转发——RunContext.onEvent 的值。 */
+  onEvent: (event: AgentEvent) => void;
+  /** RunContext.onPoolResolved 的值（引擎声明实际池 key 后重定向落盘路径）。 */
+  onPoolResolved: (poolKey: string) => void;
+  /**
+   * 终态落盘路径（writer 是路径权威——retarget 后的实际路径）。read 第②级的自描述
+   * 定位符数据源：record.engineHandle.journalPath（chat 域）与 handle.data.journalPath
+   * （workflow 域 backfillHandle）都取本值。
+   */
+  readonly path: string;
+  /** run 终态收口（flush + fsync；幂等，不抛——见文件头）。 */
+  close(): Promise<void>;
+  /**
+   * handle 回填：EngineHandleData.journalPath = writer 终态路径（read ②级经
+   * handle.journalPath 自描述定位——运行期落盘路径权威在 writer）。
+   */
+  backfillHandle(handle: EngineHandle): void;
+}
+
+/**
+ * 接线 host 侧 event journal（两域共用）：创建 writer（占位池 key）+ retarget 回调 +
+ * journaling onEvent 包装 + 终态路径访问。close 在 run 终态（成功/失败路径均达）调用。
+ */
+export function wireEventJournal(opts: JournalWiringOptions): JournalWiring {
+  const journal = new JournalWriter({
+    path: resolveJournalPath(getEngineDataDir(), opts.engineId, JOURNAL_INITIAL_POOL_KEY, opts.taskId),
+    taskId: opts.taskId,
+    engineId: opts.engineId,
+  });
+  return {
+    // 先落盘再转发（原 onEvent 未传时也恒传包装版——下游 onEvent 通道是事件生成后的
+    // 纯转发，无行为分支，仅多一次入队）
+    onEvent: (event) => {
+      journal.append(event);
+      opts.forwardEvents?.(event);
+    },
+    onPoolResolved: (poolKey) => {
+      journal.retarget(resolveJournalPath(getEngineDataDir(), opts.engineId, poolKey, opts.taskId));
+    },
+    // getter 而非快照：retarget 后取实际落盘路径（writer 是路径权威）
+    get path() {
+      return journal.path;
+    },
+    close: () => journal.close(),
+    backfillHandle: (handle) => {
+      handle.data.journalPath = journal.path;
+    },
+  };
+}

package/src/execution/engine/common/kill-chain.ts

@@ -10,8 +10,10 @@
 import { getLogger } from "../../../core/logger.ts";
 
 import { engineTimeoutDetail } from "./errors.ts";
-import type { AgentOutcome, AgentTaskSpec } from "../types.ts";
+import type { AgentCallOpts } from "../../../orchestration/models/types.ts";
+import type { AgentOutcome } from "../types.ts";
 import { DEFAULT_ENGINE_ID } from "../registry.ts";
+import { toErrorMessage } from "../../../core/error-message.ts";
 
 const logger = getLogger("subagents");
 
@@ -34,6 +36,11 @@ export interface KillableChild {
   once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
 }
 
+// 毫秒→秒换算（SIGKILL 升级 warn 日志的秒数显示）。文件内私有定义：工程内 MS_PER_SECOND
+// 惯例是各使用文件私有常量（execution-record / lifecycle-manager / session-file-gc /
+// session-runner 四处先例），无共享导出源可 import，保持同惯例不另立导出点。
+const MS_PER_SECOND = 1_000;
+
 /** SIGTERM 优雅窗口默认值（ms）。实测校准点：设计 §5 待验证检查点⑤（zcode 对 SIGTERM 的响应时序）。 */
 export const DEFAULT_KILL_GRACE_MS = 5_000;
 
@@ -47,6 +54,25 @@ const SIGKILL_REAP_TIMEOUT_MS = 10_000;
  */
 export const HOST_TIMEOUT_ABORT_REASON = "agent-call-timeout";
 
+/** killChain 的参数形状。 */
+export interface KillChainOptions {
+  /**
+   * SIGTERM 优雅窗口（ms）。grace 窗口按引擎参数化（D3-① 杀链合一）：pi 传 30s
+   * （[race-F4] 现状值）、zcode 传 5s（ZCODE_KILL_GRACE_MS）——两引擎现状逐字节保持。
+   */
+  graceMs: number;
+  /**
+   * [D3-①] 内部 timer unref。pi 路径现状 = 升级 timer unref（不阻止主进程退出，dispose
+   * killAll 兜底）；zcode 现状 = ref'd（timer 挂起时进程等待收尸）——各引擎按现状传。
+   */
+  unrefTimers?: boolean;
+  /**
+   * SIGKILL 升级时的 warn 留痕载体（如 `child sa-xxx (source: spawn watchdog)`）。
+   * 不传则升级静默（zcode 现状）——pi 侧现状有 warn，由调用方组装完整语境。
+   */
+  escalationNote?: string;
+}
+
 /**
  * 杀链：SIGTERM → 等待 graceMs → 仍存活则 SIGKILL。
  *
@@ -54,7 +80,7 @@ export const HOST_TIMEOUT_ABORT_REASON = "agent-call-timeout";
  */
 export async function killChain(
   child: KillableChild,
-  opts: { graceMs: number },
+  opts: KillChainOptions,
 ): Promise<"terminated" | "killed"> {
   // 已退出（自然/已被杀）→ 无需发信号，按优雅终止口径返回
   if (child.exitCode !== null || child.signalCode !== null) return "terminated";
@@ -62,14 +88,19 @@ export async function killChain(
   const exited = waitForExit(child);
   safeKill(child, "SIGTERM");
 
-  const graceful = await raceTimeout(exited, opts.graceMs);
+  const graceful = await raceTimeout(exited, opts.graceMs, opts.unrefTimers === true);
   if (graceful === "settled") return "terminated";
   // grace 超时后进程可能恰好在检查前一刻退出——复核退出态，避免误杀已死进程
   if (child.exitCode !== null || child.signalCode !== null) return "terminated";
 
+  if (opts.escalationNote !== undefined) {
+    logger.warn(
+      `[kill-chain] ${opts.escalationNote} still alive ${opts.graceMs / MS_PER_SECOND}s after SIGTERM, escalating to SIGKILL`,
+    );
+  }
   safeKill(child, "SIGKILL");
   // 有界收尸：无论等到与否都返回 'killed'（信号已发出，返回值表达「走了 SIGKILL」）
-  await raceTimeout(exited, SIGKILL_REAP_TIMEOUT_MS);
+  await raceTimeout(exited, SIGKILL_REAP_TIMEOUT_MS, opts.unrefTimers === true);
   return "killed";
 }
 
@@ -83,7 +114,7 @@ function safeKill(child: KillableChild, signal: NodeJS.Signals): void {
     child.kill(signal);
   } catch (err) {
     logger.debug(
-      `[kill-chain] ${signal} on exited process: ${err instanceof Error ? err.message : String(err)}`,
+      `[kill-chain] ${signal} on exited process: ${toErrorMessage(err)}`,
     );
   }
 }
@@ -98,14 +129,14 @@ function safeKill(child: KillableChild, signal: NodeJS.Signals): void {
  * exitCode: null = 被信号杀死（AgentOutcome 的杀链判据，§3.3.5）。
  */
 export function synthesizeTimeoutOutcome(
-  task: AgentTaskSpec,
+  task: AgentCallOpts,
   stdoutTail: string,
   engineId: string = DEFAULT_ENGINE_ID,
 ): AgentOutcome {
   return {
     content: "",
     // slug 进错误信息：单看 outcome（record 之外）也能定位是哪个任务超时
-    error: `engine_timeout: [slug=${task.slug}] ${engineTimeoutDetail(stdoutTail)}`,
+    error: `engine_timeout: [slug=${task.description ?? "unknown"}] ${engineTimeoutDetail(stdoutTail)}`,
     // 被信号杀死：退出码语义为 null（§3.3.5 AgentOutcome.exitCode 注释）
     exitCode: null,
     engineId,
@@ -161,7 +192,7 @@ export function abortWithFallback(
             // debug 级留诊断线索：这不是错误终态，只是该引擎优雅中断不可用
             logger.debug(
               `[kill-chain] native interrupt failed, falling back to kill chain: ${
-                err instanceof Error ? err.message : String(err)
+                toErrorMessage(err)
               }`,
             );
           }
@@ -202,10 +233,11 @@ function waitForExit(child: KillableChild): Promise<void> {
   });
 }
 
-/** promise vs 超时：超时先到返回 'timeout'（promise 继续但被放弃等待）。 */
-function raceTimeout(p: Promise<void>, ms: number): Promise<"settled" | "timeout"> {
+/** promise vs 超时：超时先到返回 'timeout'（promise 继续但被放弃等待）。unref 见 KillChainOptions。 */
+function raceTimeout(p: Promise<void>, ms: number, unref = false): Promise<"settled" | "timeout"> {
   return new Promise<"settled" | "timeout">((resolve) => {
     const timer = setTimeout(() => resolve("timeout"), ms);
+    if (unref) timer.unref();
     p.then(
       () => {
         clearTimeout(timer);