@zhushanwen/subagent-core 0.8.0 → 0.9.0

package/src/execution/engine/client/__tests__/remote-engine.test.ts

@@ -15,6 +15,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { EngineClient } from "../engine-client.ts";
 import { RemoteEngine, type RemoteEngineManifestSnapshot } from "../remote-engine.ts";
 import { SubagentStream } from "../../../stream-sink.ts";
+import { getSubagentSessionDir } from "../../../path-encoding.ts";
 import { isProcessAlive } from "../pid-file.ts";
 import { getLogger, type UiRequest } from "@zhushanwen/subagent-engine-sdk";
 
@@ -253,6 +254,49 @@ describe("RemoteEngine run 帧映射", () => {
     await cleanup();
   });
 
+  it("ctx.sessionRootId → wire ctx.sessionRootId 逐字保真；缺省不传 → wire 无该键（F6 additive）", async () => {
+    // 正向：根 session id 上 wire（pi 引擎 relay 归属键 SESSION_ID 的权威来源）
+    const withRoot = makeEngine();
+    const { ctx: ctxRoot, events: eventsRoot } = makeCtx({ sessionRootId: "root-sess-f6" });
+    await withRoot.engine.run({ prompt: "p" }, ctxRoot);
+    expect(extractRunParams(eventsRoot).ctx.sessionRootId).toBe("root-sess-f6");
+
+    // 负向：缺省 → wire ctx 不出现该键（undefined 不上 wire，旧引擎 additive 兼容）
+    const bare = makeEngine();
+    const { ctx: ctxBare, events: eventsBare } = makeCtx();
+    await bare.engine.run({ prompt: "p" }, ctxBare);
+    expect(extractRunParams(eventsBare).ctx).not.toHaveProperty("sessionRootId");
+
+    await withRoot.cleanup();
+    await bare.cleanup();
+  });
+
+  it("[Option C] wire ctx.sessionDir = getSubagentSessionDir(env 同源推导)；ctx 显式注入优先", async () => {
+    // stub env 固定推导输入（测试进程可能已带这两键——stub 后期望值确定）
+    vi.stubEnv("PI_CODING_AGENT_DIR", join(dataDir, "agent-dir"));
+    vi.stubEnv("PI_SUBAGENT_ROOT_CWD", join(dataDir, "root-cwd"));
+    try {
+      // 正向：env 同源推导值上 wire（宿主单一权威 getSubagentSessionDir，引擎不自推导）
+      const derived = makeEngine();
+      const { ctx, events } = makeCtx();
+      await derived.engine.run({ prompt: "p" }, ctx);
+      expect(extractRunParams(events).ctx.sessionDir).toBe(
+        getSubagentSessionDir(join(dataDir, "agent-dir"), join(dataDir, "root-cwd")),
+      );
+
+      // 宿主编排层显式注入（ctx.sessionDir）优先于 env 推导
+      const injected = makeEngine();
+      const { ctx: ctxInj, events: eventsInj } = makeCtx({ sessionDir: "/explicit/session-dir" });
+      await injected.engine.run({ prompt: "p" }, ctxInj);
+      expect(extractRunParams(eventsInj).ctx.sessionDir).toBe("/explicit/session-dir");
+
+      await derived.cleanup();
+      await injected.cleanup();
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
   it("poolResolved / handleReady → RunContext 回调（journal 路径权威 + 运行中句柄回填）", async () => {
     const pools: string[] = [];
     const readies: Array<{ sessionRef: Record<string, string>; poolKey: string }> = [];
@@ -393,7 +437,7 @@ describe("gate 位多声明 run 期判定（W3 契约⑤接线：manifest vs ini
   });
 });
 
-describe("interact / read / probe / dispose 门面", () => {
+describe("read / probe / dispose 门面（[H1 U6] interact 断言随 interact 面退役删除）", () => {
   it("read 协议帧携带 dataDir（必填：存量池时代相对 dbPath 定位）", async () => {
     const { engine, cleanup } = makeEngine();
     const view = await engine.read({
@@ -411,21 +455,11 @@ describe("interact / read / probe / dispose 门面", () => {
     await cleanup();
   });
 
-  it("probe → ProbeReport；interact → delivered；dispose → client 停机（幂等）", async () => {
+  it("probe → ProbeReport；dispose → client 停机（幂等）", async () => {
     const { engine, cleanup } = makeEngine();
     const report = await engine.probe();
     expect(report.ok).toBe(true);
     expect(report.engineVersion).toBe("fake-1.0.0");
-    const interact = await engine.interact({
-      data: {
-        v: 1,
-        engineId: "fake",
-        sessionRef: { sessionId: "s-1" },
-        poolKey: "shared",
-        adapterVersion: "fake-adapter",
-      },
-    }, { kind: "message", payload: "hi" });
-    expect(interact).toEqual({ ok: true, delivered: true });
     await engine.dispose();
     await expect(engine.dispose()).resolves.toBeUndefined(); // 幂等
     await cleanup();

package/src/execution/engine/client/engine-client.ts

@@ -104,8 +104,7 @@ export type EngineClientState =
 /**
  * run 作用域反向通知路由（RemoteEngine.run 注册，终态后注销）。
  * 回调允许返回 Promise（数据面 10s 应答守卫的计时对象；同步回调不受守卫影响）。
- * [W3 v1.x] onRoundLifecycle：host/roundLifecycle 消费口（首轮 runId 键；续聊轮
- * recordId 键走 registerRecordRoute，D1-A 关联键分路）。
+ * [H1 U6] 轮次相位消费口（旧第 9 反向通道）已随 chat 域相位机退役删除。
  */
 export interface RunRoute {
   onEvent?: (event: unknown) => void | Promise<void>;
@@ -114,7 +113,6 @@ export interface RunRoute {
   onHandleReady?: (
     partial: Pick<EngineHandleData, "sessionRef" | "poolKey">,
   ) => void | Promise<void>;
-  onRoundLifecycle?: (phase: unknown) => void | Promise<void>;
 }
 
 /** spawn 引擎 CLI 平台形态（impl-plan §2.2 必写死的两行）。 */
@@ -163,9 +161,6 @@ export class EngineClient {
   private nextRequestId = 1;
   private readonly pending = new Map<number, PendingRequest>();
   private readonly runRoutes = new Map<string, RunRoute>();
-  /** [W3 v1.x] chat 轮次路由（recordId 键，D1-A——续聊轮无 runId）；注册经
-   *  RemoteEngine.registerChatRoundRoute，record 终态注销。 */
-  private readonly recordRoutes = new Map<string, RunRoute>();
   private stderrTail = "";
   private unavailableReason: EngineSdkError | undefined;
   private connectInFlight: Promise<void> | undefined;
@@ -186,7 +181,6 @@ export class EngineClient {
       permissionHandler: opts.permissionHandler,
       log: opts.log,
       runRoutes: this.runRoutes,
-      recordRoutes: this.recordRoutes,
       mirror: this.mirror,
       setPartialHandle: (partial) => {
         this.lastPartialHandle = partial;
@@ -560,15 +554,6 @@ export class EngineClient {
     };
   }
 
-  /** [W3 v1.x] 注册 chat 轮次路由（recordId 键）；分发见 reverse-router.ts
-   *  （与 runRoutes 同构，键空间互斥：runId=run 帧分配 / recordId=宿主铸造）。 */
-  registerRecordRoute(recordId: string, route: RunRoute): () => void {
-    this.recordRoutes.set(recordId, route);
-    return () => {
-      if (this.recordRoutes.get(recordId) === route) this.recordRoutes.delete(recordId);
-    };
-  }
-
   /** 健康检查（ADR-0047：静默 ≠ 卡死，不据此杀任务）。 */
   async ping(): Promise<void> {
     await this.ensureConnected();
@@ -635,10 +620,12 @@ export class EngineClient {
   }
 
   /**
-   * 进程死亡 / 失败后的统一清理：镜像整体置死（失效语义 2+3：killed=true 广播后
-   * 清空）→ pidfile 删 → 在途请求 engine_crashed（附 stderr 尾）→ run 路由清空。
+   * 进程死亡 / 失败后的统一清理（收割/组杀分支各成子函数，此处只做顺序编排）：
+   * 孤儿收割（镜像置死前）→ 镜像置死（失效语义 2+3）→ pidfile 删 → 在途请求
+   * engine_crashed（附 stderr 尾）→ run 路由清空 → 活引擎组杀兜底。
    */
   private teardownProcess(detail: string): void {
+    this.reapOrphansAfterUnexpectedDeath(detail);
     this.mirror.killAll();
     if (this.pidfileWritten !== undefined) {
       removePidfile(this.pidfileWritten);
@@ -651,23 +638,92 @@ export class EngineClient {
     }
     this.pending.clear();
     this.runRoutes.clear();
-    this.recordRoutes.clear();
     this.lastPartialHandle = undefined;
+    this.killLeakedAliveChild(detail);
+    if (this.state !== "unavailable" && this.state !== "disposed") {
+      this.state = "exited";
+    }
+  }
+
+  /**
+   * [H1 U2 / 红线①收割链] 非主动死亡且引擎已死的路径，在镜像置死**之前**补发收割
+   * 信号：孤儿真因 = 引擎意外死时宿主未发收割信号（原先 alreadyDead 分支直接跳过
+   * killProcessTree），任务子进程留在无主进程组继续写 session 文件。插入点约束：
+   *   - 位置 = mirror.killAll() 置死清空之前——Windows 通道依赖镜像快照过滤活孤儿
+   *     （置死后全量项 killed=true 不可过滤）；
+   *   - 条件 = !intentionalKill && alreadyDead——主动 dispose 链已有两层杀（引擎
+   *     killAllActiveChildren SIGTERM+30s + 宿主 killAll 组杀 5s 升级），跳过即不叠加、
+   *     优雅窗零压缩、pi trap-flush 零截断；进程仍活的路径（握手失败重建）由
+   *     killLeakedAliveChild 组杀兜底承接。
+   */
+  private reapOrphansAfterUnexpectedDeath(detail: string): void {
+    if (!this.intentionalKill && this.child !== undefined) {
+      const dying = this.child;
+      const alreadyDead = dying.exitCode !== null || dying.signalCode !== null;
+      if (alreadyDead && dying.pid !== undefined) {
+        if (process.platform === "win32") {
+          // Windows：killProcessTree 的 taskkill 以引擎 pid 为树根，树根已死 → not
+          // found → 空操作（不可复用）——镜像通道收割（置死前快照，见下）。
+          this.reapOrphansViaMirrorSnapshot(detail);
+        } else {
+          // POSIX：复用 killProcessTree 负 pid 组杀（SIGTERM → 5s grace → SIGKILL
+          // 升级链内建，fire-and-forget 不阻塞同步 teardown）。组长死后进程组存活到
+          // 最后一员退出，组杀可达任务子进程（引擎 detached:true spawn = 组长，任务
+          // 子进程 detached:false 同组，组杀目标 -child.pid 不依赖镜像）。
+          // 无外层逐 pid 兜底（SIGTERM 同步返回后 5s 窗内孤儿必然仍活，同步校验恒
+          // 命中、立即兜底 = 优雅窗归零截断 trap-flush——升级链已覆盖残余职责）。
+          killProcessTree(
+            dying.pid,
+            `reap orphaned children after unexpected engine death (${detail})`,
+            { engineId: this.engineId },
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * 握手失败路径（版本越界/握手超时/启动僵死）引擎进程仍活着：必须组杀，否则
+   * crash 重建循环每次 spawn 泄漏一个常驻孤儿（测试机实测积累 370+）。主动杀
+   * （intentionalKill=true）与进程已死（exitCode/signalCode 非空）跳过重复发信号。
+   */
+  private killLeakedAliveChild(detail: string): void {
     if (this.child !== undefined) {
       const child = this.child;
       this.child = undefined;
-      // 握手失败路径（版本越界 / 握手超时 / 启动僵死）引擎进程仍活着：必须组杀，
-      // 否则泄漏为常驻孤儿（crash 重建循环每次 spawn 泄漏一个；测试机实测积累
-      // 370+ 假引擎进程）。主动杀路径（killAll 已发信号，intentionalKill=true）与
-      // 进程已死路径（onEngineExit，exitCode/signalCode 非空）跳过重复发信号。
       const alreadyDead = child.exitCode !== null || child.signalCode !== null;
       if (!alreadyDead && !this.intentionalKill && child.pid !== undefined) {
         killProcessTree(child.pid, detail, { engineId: this.engineId });
       }
       child.removeAllListeners();
     }
-    if (this.state !== "unavailable" && this.state !== "disposed") {
-      this.state = "exited";
+  }
+
+  /**
+   * [H1 U2 / 红线①Windows 通道] 镜像快照收割活孤儿：镜像快照同步抓清单（置死前，
+   * 全量项含引擎一生历史死 pid——镜像对已退出子进程只改 state 不删项、唯一清空点 =
+   * killAll）→ 过滤活孤儿（state === "running" && !killed，活孤儿 ≤ 并发数）→ 逐 pid
+   * **异步 spawn** taskkill /T /F fire-and-forget（树根 = 活着的任务子进程自身，树杀
+   * 有效；快照同步抓、杀动作异步发——与 POSIX fire-and-forget 对称；禁 spawnSync：
+   * 逐个同步 N×10s 上界会冻结 onEngineExit 同步回调、推迟 pending reject（Continuation
+   * 失败通知链源头）与宿主事件循环）。
+   */
+  private reapOrphansViaMirrorSnapshot(detail: string): void {
+    const liveOrphans = this.mirror.snapshot().filter((e) => e.state === "running" && !e.killed);
+    if (liveOrphans.length === 0) return;
+    logger.warn(
+      `[engine-client:${this.engineId}] reaping ${liveOrphans.length} orphaned task child(ren) via mirror snapshot after unexpected engine death (${detail})`,
+    );
+    for (const entry of liveOrphans) {
+      const killer = spawn("taskkill", ["/PID", String(entry.pid), "/T", "/F"], { stdio: "ignore" });
+      killer.unref();
+      killer.on("error", (err: Error) => {
+        // spawn 失败（taskkill 缺失等）留 debug 痕迹——残余孤儿由红线③登记承接
+        //（下一轮派发前兜底 / 宿主重启窗口）。
+        logger.debug(
+          `[engine-client:${this.engineId}] taskkill spawn failed for orphan pid ${entry.pid} (${err.message})`,
+        );
+      });
     }
   }
 

package/src/execution/engine/client/mirror.ts

@@ -19,6 +19,8 @@
 
 import { getLogger } from "@zhushanwen/subagent-engine-sdk";
 
+import { notifyChildProcessExited } from "../../dialog-queue.ts";
+
 const logger = getLogger("subagents");
 
 /** 镜像项（childSpawned/childStateChanged 载荷的落库形态）。 */
@@ -90,6 +92,11 @@ export class SpawnedChildrenMirror {
     };
     this.entries.set(patch.pid, entry);
     this.emit({ reason: "childStateChanged", pid: patch.pid, recordId: patch.recordId });
+    // [SR-4 接线] 子进程退出 → 取消其挂起 dialog：原绑定点（宿主 spawn pi 子进程时代
+    // 的 session-runner child close）随协议化消失（宿主不再持句柄），新落点 = 引擎经
+    // host/childStateChanged 上报 → 本镜像消费。未接线时该子进程的 pending dialog 要
+    // 占住队列串行位直到 30min 队列级超时（延迟清理，非死锁）。
+    if (patch.state === "exited") notifyChildProcessExited(patch.pid);
   }
 
   /**
@@ -106,6 +113,8 @@ export class SpawnedChildrenMirror {
       entry.state = "exited";
       entry.updatedAt = Date.now();
       this.emit({ reason: "killedAll", pid: entry.pid, recordId: entry.recordId });
+      // [SR-4 接线] 引擎进程消亡 = 其全部子进程已死 → 逐 pid 取消挂起 dialog
+      notifyChildProcessExited(entry.pid);
     }
     this.entries.clear();
   }

package/src/execution/engine/client/remote-engine.ts

@@ -1,7 +1,8 @@
 // src/execution/engine/client/remote-engine.ts
 //
 // RemoteEngine：cli 形态 EnginePort 适配（W2，impl-plan §2.2「RemoteEngine 同步成员
-// 形态映射」必写死）。把 core EnginePort 的 9 成员映射到 EngineClient 协议请求；
+// 形态映射」必写死；[H1 U6] 交互控制面与 recordId 键路由面已随 chat 域退役删除）。
+// 把 core EnginePort 的成员映射到 EngineClient 协议请求；
 // 同步成员（capabilities / listModels / validateModel）**只读 manifest 注册期快照**
 // ——单源化原则（设计 §3.3「同步成员清单」v6 减法）：无握手缓存、无失效时机，
 // initialize 应答仅诊断（warn 由 EngineClient 留痕）。
@@ -12,31 +13,31 @@
 //
 // W3 消费契约：routing/registry 的 cli 形态 EnginePort 实例 = 本类（先写后读）。
 
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 import {
   CANCEL_SETTLE_GRACE_MS,
   EngineSdkError,
   type AgentCallOpts as SdkAgentCallOpts,
   type AgentOutcome as SdkAgentOutcome,
   type EngineHandleData as SdkEngineHandleData,
-  type InteractAction as SdkInteractAction,
-  type InteractResult as SdkInteractResult,
   type ModelCatalogEntry,
   type ProbeReport as SdkProbeReport,
   type SessionView as SdkSessionView,
 } from "@zhushanwen/subagent-engine-sdk";
 
 import type { AgentCallOpts } from "../../../orchestration/models/types.ts";
+import { getSubagentSessionDir } from "../../path-encoding.ts";
 import { assertGateCapabilitiesMatched } from "../common/capability-gate.ts";
 import type {
   EngineCapabilities,
   EngineHandle,
   EngineHandleData,
-  InteractAction,
-  InteractResult,
   ProbeReport,
   SessionView,
 } from "../types.ts";
-import type { ChatRoundRoute, EnginePort, EngineRunResult, RunContext } from "../port.ts";
+import type { EnginePort, EngineRunResult, RunContext } from "../port.ts";
 import type { EngineClient, RunRoute } from "./engine-client.ts";
 
 /** manifest 注册期快照（发现器/注册表读取，构造时注入——同步成员唯一源）。 */
@@ -91,7 +92,7 @@ export class RemoteEngine implements EnginePort {
       // **不实现**（消费方 model-validation.ts:62 `typeof validateModel !== "function"`
       // → 跳过校验恒放行）。实例 own property 置 undefined 遮蔽原型方法——
       // typeof engine.validateModel === "undefined"。
-      (this as unknown as { validateModel?: unknown }).validateModel = undefined;
+      (this as { validateModel?: unknown }).validateModel = undefined;
     }
   }
 
@@ -232,24 +233,6 @@ export class RemoteEngine implements EnginePort {
     }
   }
 
-  async interact(handle: EngineHandle, action: InteractAction): Promise<InteractResult> {
-    await this.opts.client.ensureConnected();
-    const result = (await this.opts.client.request("interact", {
-      handle: handle.data,
-      action: action as SdkInteractAction,
-    })) as SdkInteractResult;
-    return result;
-  }
-
-  /**
-   * [W3 v1.x] chat 轮次反向通道路由注册（recordId 键，EnginePort 可选面实现）：
-   * interact 续聊轮的 streamDelta / roundLifecycle 分发目标。薄委托 EngineClient
-   * 的 recordRoutes（键分发见 reverse-router.ts）。
-   */
-  registerChatRoundRoute(recordId: string, route: ChatRoundRoute): () => void {
-    return this.opts.client.registerRecordRoute(recordId, route as RunRoute);
-  }
-
   /** 协议 read（dataDir 必填——引擎数据根，构造注入）。 */
   async read(handle: EngineHandle): Promise<SessionView> {
     await this.opts.client.ensureConnected();
@@ -308,16 +291,47 @@ interface WireRunParams {
     ctxModel: string | undefined;
     engineFallback: RunContext["engineFallback"];
     streamMode: "stream" | undefined;
+    sessionRootId?: string;
+    /** [Option C] 恒有值（宿主注入 ?? 同源 env 推导）——与 sessionRootId 的
+     * "undefined 不上 wire" 不同，本字段派生恒产出字符串。 */
+    sessionDir: string;
   };
-  chat?: NonNullable<RunContext["chat"]>;
+  resume?: NonNullable<RunContext["resume"]>;
+}
+
+// pi 壳宿主进程内贯穿的两条 env（与 subagent-service / workflow-state-root 同源推导）：
+//   - PI_CODING_AGENT_DIR：pi SDK getAgentDir 的 env 覆盖通道——xyz-agent 生产链路由
+//     runtime spawn pi 时显式注入（rpc-client buildPiOutboundEnv，经
+//     buildOutboundChildEnv 共享构建器出站）；缺省 ~/.pi/agent 与 pi
+//     实装版 dist config.js getAgentDir 逐字同构（锚定先例 workflow-state-root.ts）。
+//   - PI_SUBAGENT_ROOT_CWD：真 ROOT 的 cwd（MF-3 贯穿）——嵌套 subagent 场景宿主
+//     spawn 子进程时注入，与 subagent-service 构造处的 rootCwd 同 env 同值。
+const PI_AGENT_DIR_ENV = "PI_CODING_AGENT_DIR";
+const PI_ROOT_CWD_ENV = "PI_SUBAGENT_ROOT_CWD";
+
+/**
+ * [Option C 协议化] 宿主权威 subagent session 目录（Gate B S6 修复）：宿主进程内
+ * 同源 env 推导 agentDir/rootCwd 后调 getSubagentSessionDir（宿主单一权威推导，
+ * path-encoding.ts——引擎本地推导与宿主布局三处不等价，已降级 [LEGACY] fallback）。
+ * 每次调用重新解析（env 读取零成本，不缓存防测试/宿主切换读旧值，对齐
+ * common/data-dir.ts getEngineDataDir 惯例）。rootCwd 缺省 process.cwd()：pi 壳
+ * ctx.cwd = pi 进程启动 cwd（session-lifecycle 侧同用进程 cwd 的既有锚定）。
+ */
+function deriveHostSubagentSessionDir(): string {
+  const agentDir = process.env[PI_AGENT_DIR_ENV];
+  const resolvedAgentDir =
+    agentDir !== undefined && agentDir !== "" ? agentDir : join(homedir(), ".pi", "agent");
+  const rootCwd = process.env[PI_ROOT_CWD_ENV];
+  const resolvedRootCwd = rootCwd !== undefined && rootCwd !== "" ? rootCwd : process.cwd();
+  return getSubagentSessionDir(resolvedAgentDir, resolvedRootCwd);
 }
 
 /**
  * run 帧 wire 载荷构建。协议 ctx 承载（RunContext 字段映射表）：cwd 取任务声明值
  * （缺省进程 cwd）；ctxModel 投影 canonical 词形（provider/id，ModelInfo 字段裁决）。
- * [W3 v1.x] chat 会话形态参数直传（RunContext.chat → run.params.chat；结构由
- * RunContext.chat 注释与 SDK RunChatParams 的 implements 互证承载）。非 chat 轮
- * ctx.chat === undefined → wire 上不出现该键（协议 additive 语义）。
+ * [H1 U6] 会话形态参数直传（RunContext.resume → run.params.resume；结构由
+ * RunContext.resume 注释与 SDK RunResumeParams 的 implements 互证承载）。一次性轮
+ * ctx.resume === undefined → wire 上不出现该键（协议 additive 语义）。
  */
 function buildRunParams(task: AgentCallOpts, ctx: RunContext, runId: string): WireRunParams {
   const ctxModelRef = ctx.ctxModel ? `${ctx.ctxModel.provider}/${ctx.ctxModel.id}` : undefined;
@@ -332,21 +346,25 @@ function buildRunParams(task: AgentCallOpts, ctx: RunContext, runId: string): Wi
       ctxModel: ctxModelRef,
       engineFallback: ctx.engineFallback,
       streamMode: ctx.stream !== undefined ? ("stream" as const) : undefined,
+      // [F6] 根 session id（relay 归属键 SESSION_ID 权威源）——undefined 不上 wire
+      //（additive 语义，与顶层 chat 参数同写法）。
+      ...(ctx.sessionRootId !== undefined ? { sessionRootId: ctx.sessionRootId } : {}),
+      // [Option C 协议化] 权威 subagent session 目录（Gate B S6）：宿主注入值优先，
+      // 缺省同源 env 推导（deriveHostSubagentSessionDir）——恒有值恒上 wire，引擎
+      // 据此组装 --session-dir 不自推导（引擎本地推导降级 [LEGACY] fallback）。
+      sessionDir: ctx.sessionDir ?? deriveHostSubagentSessionDir(),
     },
-    ...(ctx.chat !== undefined ? { chat: ctx.chat } : {}),
+    ...(ctx.resume !== undefined ? { resume: ctx.resume } : {}),
   };
 }
 
-/** run 作用域事件路由（event / streamDelta / poolResolved / handleReady / roundLifecycle）。 */
+/** run 作用域事件路由（event / streamDelta / poolResolved / handleReady）。 */
 function buildRunRouteHandlers(ctx: RunContext): RunRoute {
   return {
     onEvent: (event) => ctx.onEvent?.(event as Parameters<NonNullable<RunContext["onEvent"]>>[0]),
     onStreamDelta: (delta) => ctx.stream?.onDelta(delta),
     onPoolResolved: (poolKey) => ctx.onPoolResolved?.(poolKey),
     onHandleReady: (partial) => ctx.onHandleReady?.(partial),
-    // [W3 v1.x] 首轮（run 会话形态）轮次生命周期帧（runId 键）→ 宿主消费口。
-    onRoundLifecycle: (phase) =>
-      ctx.onRoundLifecycle?.(phase as Parameters<NonNullable<RunContext["onRoundLifecycle"]>>[0]),
   };
 }
 

package/src/execution/engine/client/reverse-router.ts

@@ -24,7 +24,6 @@ import {
   type HostLogParams,
   type HostPermissionParams,
   type HostPoolResolvedParams,
-  type HostRoundLifecycleParams,
   type HostStreamDeltaParams,
   type UiRequest,
 } from "@zhushanwen/subagent-engine-sdk";
@@ -45,8 +44,6 @@ export interface ReverseRouterDeps {
   log?: (params: HostLogParams) => void;
   /** run 作用域通知路由表（EngineClient 持有，EngineClient 生命周期内同一引用）。 */
   runRoutes: Map<string, RunRoute>;
-  /** [W3 v1.x] chat 轮次路由表（recordId 键；EngineClient 持有，同上）。 */
-  recordRoutes: Map<string, RunRoute>;
   /** childSpawned/childStateChanged 的镜像落点。 */
   mirror: SpawnedChildrenMirror;
   /** handleReady 的 partial handle 回填（崩溃合成 handle 数据源）。 */
@@ -159,11 +156,11 @@ function handleDataPlaneRequest(deps: ReverseRouterDeps, frame: { id: string; me
 /** 数据面单通道分发器（params 形态自证——发帧前引擎侧自检，分发层只做强转）。 */
 type DataPlaneHandler = (deps: ReverseRouterDeps, params: unknown) => Promise<void> | void;
 
-/** method → 分发器表（表外 method = 无操作；路由面准入已由 REVERSE_CHANNEL_TIMEOUT_CLASS 收敛为 data-plane）。 */
+/** method → 分发器表（表外 method = 无操作；路由面准入已由 REVERSE_CHANNEL_TIMEOUT_CLASS 收敛为 data-plane）。
+ *  [H1 U6] 旧轮次相位反向通道已随 chat 域相位机退役删除（交棒改 run 应答驱动）。 */
 const DATA_PLANE_HANDLERS: Record<string, DataPlaneHandler> = {
   "host/log": (deps, params) => dispatchLog(deps, params as HostLogParams),
   "host/streamDelta": (deps, params) => dispatchStreamDelta(deps, params as HostStreamDeltaParams),
-  "host/roundLifecycle": (deps, params) => dispatchRoundLifecycle(deps, params as HostRoundLifecycleParams),
   "host/poolResolved": (deps, params) => dispatchPoolResolved(deps, params as HostPoolResolvedParams),
   "host/handleReady": (deps, params) => dispatchHandleReady(deps, params as HostHandleReadyParams),
   "host/childSpawned": (deps, params) => dispatchChildSpawned(deps, params as HostChildSpawnedParams),
@@ -180,31 +177,13 @@ function dispatchLog(deps: ReverseRouterDeps, p: HostLogParams): void {
 }
 
 async function dispatchStreamDelta(deps: ReverseRouterDeps, p: HostStreamDeltaParams): Promise<void> {
-  // [W3 v1.x 接线（W1 偏差 #1 的替换落地）] 关联键分路（D1-A）：
-  //   - recordId 键 = chat 续聊轮 delta（interact 发起，无独立 runId）→ recordRoutes；
-  //   - runId 键 = run 域轮（含 run 会话形态首轮）→ runRoutes（v1 现状不变）。
-  // 无注册路由 = 该轮宿主消费面未挂（诊断形态）——静默丢弃（数据面已 ack，
-  // 引擎侧不重发；路由缺席非引擎故障）。
-  if (p.recordId !== undefined) {
-    await deps.recordRoutes.get(p.recordId)?.onStreamDelta?.(p.delta);
-    return;
-  }
+  // [H1 U6] 关联键收敛为 runId 单键（recordId 分路随 chat 续聊轮 interact 面退役——
+  // 每轮 = 新 run，delta 恒经 run 作用域路由）。无注册路由 = 该轮宿主消费面未挂
+  //（诊断形态）——静默丢弃（数据面已 ack，引擎侧不重发；路由缺席非引擎故障）。
+  if (p.runId === undefined) return;
   await deps.runRoutes.get(p.runId)?.onStreamDelta?.(p.delta);
 }
 
-async function dispatchRoundLifecycle(deps: ReverseRouterDeps, p: HostRoundLifecycleParams): Promise<void> {
-  // [W3 v1.x] 第 9 反向通道消费（settled/idle/failed 三相位 × runId|recordId 键）。
-  // 相位语义（arm/disarm/交棒/失败分诊）归宿主编排层——本路由只做键分发，
-  // 消费方 = RunContext.onRoundLifecycle（首轮 runId 键）与 registerChatRoundRoute
-  // 路由（续聊轮 recordId 键）。载荷形状自证（isHostRoundLifecycleParams）归
-  // 引擎侧发帧前自检 + 消费方，分发层不重复判别（与 streamDelta 一致的薄分发）。
-  if (p.recordId !== undefined) {
-    await deps.recordRoutes.get(p.recordId)?.onRoundLifecycle?.(p);
-    return;
-  }
-  await deps.runRoutes.get(p.runId)?.onRoundLifecycle?.(p);
-}
-
 async function dispatchPoolResolved(deps: ReverseRouterDeps, p: HostPoolResolvedParams): Promise<void> {
   await deps.runRoutes.get(p.runId)?.onPoolResolved?.(p.poolKey);
 }

package/src/execution/engine/common/__tests__/run-signals.test.ts

@@ -0,0 +1,79 @@
+// src/execution/engine/common/__tests__/run-signals.test.ts
+//
+// [H2 W4] mergeRunSignals 纯函数行为测试——自 subprocess-agent-runner-timeout.test.ts
+// 迁移改写：原 mergeTimeoutSignal 薄包装（timeoutMs 无守护信号源时原样返回 external
+// signal；有则返回 .signal 视图）随 SAR.run 掏空删除（生产零消费），断言面改直测
+// 公共 helper 权威实现（engine/common/run-signals.ts，W2 迁移步⑥自 SAR 提取）。
+// 原用例行为语义逐条保持（T3.6 / T3.17 编号沿用）。
+
+import { describe, expect, it, vi } from "vitest";
+
+import { mergeRunSignals } from "../run-signals.ts";
+
+describe("mergeRunSignals (D-A9 / H2 W2 迁移步⑥)", () => {
+  it("T3.6 timeoutMs===undefined → 原样返回 external signal", () => {
+    const ctrl = new AbortController();
+    const handle = mergeRunSignals(ctrl.signal, undefined);
+    expect(handle.signal).toBe(ctrl.signal);
+    handle.dispose();
+  });
+
+  it("T3.6 timeoutMs<=0 → 原样返回 external signal", () => {
+    const ctrl = new AbortController();
+    const handle = mergeRunSignals(ctrl.signal, 0);
+    expect(handle.signal).toBe(ctrl.signal);
+    handle.dispose();
+  });
+
+  it("T3.6 timeoutMs>0 → 返回新 signal（合并外部+超时两路）", () => {
+    const ctrl = new AbortController();
+    const handle = mergeRunSignals(ctrl.signal, 50);
+    expect(handle.signal).not.toBe(ctrl.signal);
+    expect(handle.signal.aborted).toBe(false);
+    handle.dispose();
+  });
+
+  it("T3.6 timeoutMs 到期 → merged signal abort", () => {
+    vi.useFakeTimers();
+    const ctrl = new AbortController();
+    const handle = mergeRunSignals(ctrl.signal, 50);
+
+    expect(handle.signal.aborted).toBe(false);
+    vi.advanceTimersByTime(51);
+    expect(handle.signal.aborted).toBe(true);
+    handle.dispose();
+    vi.useRealTimers();
+  });
+
+  it("T3.6 外部 signal abort → merged signal abort", () => {
+    const ctrl = new AbortController();
+    const handle = mergeRunSignals(ctrl.signal, 5000);
+    ctrl.abort();
+    expect(handle.signal.aborted).toBe(true);
+    handle.dispose();
+  });
+
+  it("T3.6 外部 signal 已 abort → 返回已 abort 的 signal", () => {
+    const ctrl = new AbortController();
+    ctrl.abort();
+    const handle = mergeRunSignals(ctrl.signal, 5000);
+    expect(handle.signal.aborted).toBe(true);
+    handle.dispose();
+  });
+
+  it("T3.17 NFR: merged signal abort → timeout timer 清理", () => {
+    vi.useFakeTimers();
+    const ctrl = new AbortController();
+    const handle = mergeRunSignals(ctrl.signal, 50);
+
+    ctrl.abort(); // 外部 abort → merged 也 abort
+    expect(handle.signal.aborted).toBe(true);
+
+    // 推进时间，不应再有副作用
+    vi.advanceTimersByTime(100);
+    // timer 应被清理（通过 abort event listener）
+    // 无异常 = timer 已正确清理
+    handle.dispose();
+    vi.useRealTimers();
+  });
+});

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

@@ -168,6 +168,33 @@ export function assertGateCapabilitiesMatched(
   }
 }
 
+// ============================================================
+// 能力位方向判定③：SP-5 升级 gate（H1 U2 / D5 双写点共用文案单源）
+// ============================================================
+
+/**
+ * [H1 U2 / D5 双写点] SP-5 升级（one-shot → chatMode）被 conversation 位拒绝时的
+ * 统一错误构造（文案/错误码/恢复指引单一权威）。
+ *
+ * 两个写点共同消费（现场契约「改动这两处必须协同」的 gate 化落点）：
+ *   - 写点①进程内热升级：subagent-actions-core messageHandler；
+ *   - 写点②跨重启冷升级（D4 revive 格）：conversation-continuation（U6 已删
+ *     cold-resurrect 无条件置位——语义迁入本格，磁盘重建只水合持久化 chatMode）。
+ *
+ * unsupported 引擎（zcode）的 one-shot 收到 message 不升级——升级后续聊行为悬空
+ * （Continuation 续聊轮依赖引擎 resume 能力），guard 文案指引 fork/重派。
+ */
+export function engineConversationUpgradeUnsupportedError(engineId: string): EngineError {
+  return new EngineError(
+    "engine_capability_unsupported",
+    `subagent completed as one-shot on engine '${engineId}' (capabilities.conversation = 'unsupported') — ` +
+      `it cannot be upgraded to a resumable conversation, so the message is rejected.`,
+    `Recovery: re-dispatch the follow-up as a new subagent (action:'start'), ` +
+      `or branch from its session history with action:'fork-from', ` +
+      `or pick an engine that declares the conversation capability.`,
+  );
+}
+
 /** engine_capability_mismatch 的统一构造（manifest 权威 + 恢复指引 = 修 manifest / 升级引擎包）。 */
 function gateMismatchError(engineId: string, cap: string, declared: string, answered: string): EngineError {
   return new EngineError(

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

@@ -5,8 +5,9 @@
 // 顶层（journal / 隔离池的父目录），extension 写侧与 runtime 校验侧同源推导。
 //
 // 通道调查结论（2026-08-25，P2 实测证据链）：
-//   - runtime spawn pi 主会话时 RpcClient.buildSafeEnv 从 runtime process.env 继承
-//     XYZ_ 前缀白名单变量（rpc-client.ts:14-30），且显式设置 PI_CODING_AGENT_DIR；
+//   - runtime spawn pi 主会话时 RpcClient 出站 env 从 runtime process.env 继承
+//     XYZ_ 前缀白名单变量（调查当时经私有 buildSafeEnv，现已被 buildPiOutboundEnv
+//     → buildOutboundChildEnv 共享构建器取代），且显式设置 PI_CODING_AGENT_DIR；
 //   - dev 模式 Electron main 设置 XYZ_AGENT_DATA_DIR（apps/electron/main/main.ts:122），
 //     经 process-control.ts:262 透传给 runtime → 透传链成立；
 //   - prod 默认路径（~/.xyz-agent 缺省）下 runtime 进程 env 中**没有**该变量

package/src/execution/engine/common/errors.ts

@@ -59,7 +59,7 @@ export class EngineError extends Error {
     this.recovery = recovery;
   }
 
-  /** 结构化投影（InteractResult.code/message 与 GUI 警告条共用形态）。 */
+  /** 结构化投影（code/message 与 GUI 警告条共用形态）。 */
   toStructured(): { code: EngineErrorCode; message: string; recovery: string } {
     return { code: this.code, message: this.message, recovery: this.recovery };
   }