@zhushanwen/subagent-core 0.8.0 → 0.9.0

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

@@ -1,8 +1,9 @@
 // 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 +
+// [D3-③ journal 接线合一] host 侧 event journal 接线的共享 helper（唯一实现，调用
+// 点全部在 SubagentService：workflow 域 runWorkflowEngineTask（wireEventJournal
+// taskId=record.id）+ chat 域 runEngineTask 与 tool 域 runAndFinalize 两处（同
+// record.id））。设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-③（writer +
 // retarget + handle 回填两份提为 common 层共享 helper）+ 双轨清单 #6。
 //
 // 收敛前形态（两份同构接线）：
@@ -17,6 +18,7 @@
 // fsync 一次，§3.3.6 写入纪律；写失败已由 writer 内部 warn + failed 收口，close 不抛，
 // journal 是②级尽力而为数据源）。
 
+import { SHARED_POOL_KEY } from "@zhushanwen/subagent-engine-sdk";
 import type { AgentEvent } from "../../../shared/agent-event.ts";
 import { getEngineDataDir } from "./data-dir.ts";
 import { JournalWriter } from "./event-journal.ts";
@@ -26,16 +28,17 @@ 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，等值异名）。
+ * retarget 到实际池 key。值与 RunContext.poolKey 的初始占位同源——值单源
+ * SDK SHARED_POOL_KEY（L3 收编：原先 Service 用 'shared' 字面量、SAR 用 PI_POOL_KEY，
+ * 等值异名；本名保留 journal 占位语义，值不再本地声明）。
  */
-export const JOURNAL_INITIAL_POOL_KEY = "shared";
+export const JOURNAL_INITIAL_POOL_KEY = SHARED_POOL_KEY;
 
 /** wireEventJournal 的参数。 */
 export interface JournalWiringOptions {
   /** 实际执行引擎 id（journal 路径分段 + line 元数据）。 */
   engineId: string;
-  /** 宿主侧任务标识（journal 文件名与池引用计数 key：chat 域 = record.id；workflow 域 = 'sa-' 前缀占位）。 */
+  /** 宿主侧任务标识（journal 文件名与池引用计数 key；三处调用点统一 = record.id）。 */
   taskId: string;
   /**
    * journal 落盘后的事件转发（workflow 域的 liveRecord 通道）。缺省不转发（chat 域
@@ -77,9 +80,15 @@ export function wireEventJournal(opts: JournalWiringOptions): JournalWiring {
   });
   return {
     // 先落盘再转发（原 onEvent 未传时也恒传包装版——下游 onEvent 通道是事件生成后的
-    // 纯转发，无行为分支，仅多一次入队）
+    // 纯转发，无行为分支，仅多一次入队）。
+    //
+    // activity 豁免 append：纯活性信号不进持久/重放面——双侧 reducer（SDK
+    // journal-replay / core execution-record）对其 no-op，豁免不破坏 live≡reload
+    // 重放等价性；seq 由 append 铸造、过滤在 append 前故无 seq 空洞；
+    // forwardEvents 照发（workflow liveRecord reducer no-op，chat/守护刷新面在
+    // observedEvent 上游不受影响）；取证面由 pi stdout/stderr tee 覆盖。
     onEvent: (event) => {
-      journal.append(event);
+      if (event.type !== "activity") journal.append(event);
       opts.forwardEvents?.(event);
     },
     onPoolResolved: (poolKey) => {

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

@@ -0,0 +1,83 @@
+// src/execution/engine/common/run-signals.ts
+//
+// [H2 W2 迁移步⑥] 运行期 signal 合流公共 helper——原定义在 subprocess-agent-runner.ts
+// （模块内直调），随 service 统一编排入口 executeWorkflowAgent 接管 workflow 派发
+// （设计 docs/design/subagent-workflow-record-unification.md §5 W2 八步迁移表）提为
+// engine/common 公共面：SAR 与 SubagentService 两调用点共用同一实现（行为逐字节
+// 等价搬移，函数体不改）。SAR 侧经 re-export 保持既有 import 路径（测试消费面零
+// 改动），W4 掏空 SAR.run 后本文件成为唯一权威落点。
+
+import { HOST_TIMEOUT_ABORT_REASON } from "./kill-chain.ts";
+
+/** 合并 signal 的句柄：signal 供 engine.run 消费，dispose 移除桥接 listener（finally 必达）。 */
+export interface MergedRunSignalHandle {
+  signal: AbortSignal;
+  /** 移除全部桥接 listener（幂等）。run 正常收敛（merged 不 abort）时是唯一清理通道。 */
+  dispose(): void;
+}
+
+/**
+ * D-A9 + [M3] 运行期 signal 合流：外部 signal（run 级 abort）+ per-call 墙钟 timeoutMs
+ * + [M3] no-progress watchdog abort —— 任一 abort 都让返回 signal abort。
+ *
+ * reason 语义保持 D-A9 原样：timeoutMs 到期 abort 带 HOST_TIMEOUT_ABORT_REASON 标记
+ *（引擎合成终态时判别「宿主超时」vs「外部 cancel」）；外部 signal 与 watchdog 的
+ * abort 不带标记（wireAbortSignal 只消费 abort 事实，不读 reason）。
+ *
+ * 无任何信号源（timeoutMs 缺省/<=0 且无 watchdog）时原样返回 external signal（零新对象，
+ * 既有行为逐点不变）。
+ *
+ * dispose 的必要性：merged signal 正常收敛（不 abort）时，桥接在外部 run 级 signal 上的
+ * listener 不会自行移除——同一 run 多次 agent 调用会累积 listener 直至
+ * MaxListenersExceededWarning，故由调用方 finally 调 dispose。
+ */
+export function mergeRunSignals(
+  signal: AbortSignal,
+  timeoutMs?: number,
+  noProgressSignal?: AbortSignal,
+): MergedRunSignalHandle {
+  const hasTimeout = timeoutMs !== undefined && timeoutMs > 0;
+  if (!hasTimeout && noProgressSignal === undefined) {
+    return { signal, dispose: () => {} };
+  }
+
+  const controller = new AbortController();
+  const bridges: Array<{ source: AbortSignal; handler: () => void }> = [];
+  let timer: NodeJS.Timeout | undefined;
+
+  const dispose = (): void => {
+    for (const bridge of bridges) bridge.source.removeEventListener("abort", bridge.handler);
+    bridges.length = 0;
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  // 先挂清理 listener：任一信号源已 abort 时 bridge 会同步 abort controller，若清理
+  // listener 尚未就位，timeout timer / 已挂 listener 将不会被回收（原实现的既有时序盲区）。
+  controller.signal.addEventListener(
+    "abort",
+    () => dispose(),
+    { once: true },
+  );
+
+  if (hasTimeout) {
+    timer = setTimeout(() => controller.abort(HOST_TIMEOUT_ABORT_REASON), timeoutMs);
+    timer.unref();
+  }
+
+  const bridge = (source: AbortSignal): void => {
+    // 已 abort（前序信号源抢先 / 外部 signal 传入时已中止）后不再挂新 listener：
+    // 否则该 listener 永远等不到 controller 的清理（已过 abort 时点）。
+    if (controller.signal.aborted) return;
+    const handler = (): void => controller.abort();
+    bridges.push({ source, handler });
+    if (source.aborted) handler();
+    else source.addEventListener("abort", handler, { once: true });
+  };
+  bridge(signal);
+  if (noProgressSignal !== undefined) bridge(noProgressSignal);
+
+  return { signal: controller.signal, dispose };
+}

package/src/execution/engine/d8-compat.ts

@@ -32,7 +32,7 @@ import { EngineClient } from "./client/engine-client.ts";
 import { RemoteEngine, type RemoteEngineManifestSnapshot } from "./client/remote-engine.ts";
 import {
   readRelayForwardEnv,
-} from "../relay-env.ts";
+} from "@zhushanwen/subagent-engine-sdk";
 import { getEngineDataDir } from "./common/data-dir.ts";
 import {
   CONSERVATIVE_CAPABILITIES,

package/src/execution/engine/host/__tests__/host-bridge.test.ts

@@ -1,6 +1,6 @@
-// HostBridge 契约 + core 实现 单测（W6，impl-plan §2.6 第 2 条 / 设计 §3.8 最小示例 9 方法）。
-// 覆盖：9 方法委托行为、getRecordForAction 异常 → null、cancel 的 void 包装、
-// takeChatRound 未提供 → null、armIdleTimer/disarmIdleTimer 对 lifecycle-manager 的
+// HostBridge 契约 + core 实现 单测（W6；[H1 U6] takeChatRound 交接面用例随 chat 域
+// 退役删除）。覆盖：方法委托行为、getRecordForAction 异常 → null、cancel 的 void 包装、
+// armIdleTimer/disarmIdleTimer 对 lifecycle-manager 的
 // 接线（含超时回调 onIdleTimeout 触发，fake timers）。
 
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
@@ -9,7 +9,6 @@ import {
   createHostBridge,
   type HostBridge,
   type HostBridgeServiceFace,
-  type HostChatRoundTicket,
 } from "../host-bridge.ts";
 import {
   _resetLifecycleState,
@@ -32,7 +31,6 @@ function makeService(): HostBridgeServiceFace & {
     closeSubagent: vi.fn(async () => {}),
     cancel: vi.fn(() => true),
     collectRecords: vi.fn((): SubagentRecord[] => [{ id: "r1" } as SubagentRecord]),
-    takeChatRound: vi.fn(() => undefined),
     reportRecordTransition: vi.fn(() => {}),
   };
   return {
@@ -42,7 +40,6 @@ function makeService(): HostBridgeServiceFace & {
     closeSubagent: spies.closeSubagent,
     cancel: spies.cancel,
     collectRecords: spies.collectRecords,
-    takeChatRound: spies.takeChatRound as HostBridgeServiceFace["takeChatRound"],
     reportRecordTransition: spies.reportRecordTransition,
   };
 }
@@ -96,18 +93,6 @@ describe("HostBridge（W6，设计 §3.8 最小示例 9 方法）", () => {
     expect(service.spies.cancel).toHaveBeenCalledWith("r1");
   });
 
-  it("takeChatRound：有票 → 透传；无票 / 服务面未提供 → null", () => {
-    expect(bridge.takeChatRound("t1")).toBeNull();
-    const ticket: HostChatRoundTicket = {
-      record: fakeRecord("r1"),
-      opts: {} as HostChatRoundTicket["opts"],
-      signal: undefined,
-      priority: 1,
-    };
-    (service.spies.takeChatRound as ReturnType<typeof vi.fn>).mockReturnValue(ticket);
-    expect(bridge.takeChatRound("t1")).toBe(ticket);
-  });
-
   it("reportRecordTransition 委托（record 整体上报，无 patch 形态——见契约头注释）", () => {
     const record = fakeRecord("r1");
     bridge.reportRecordTransition(record);

package/src/execution/engine/host/host-bridge.ts

@@ -2,12 +2,12 @@
 //
 // HostBridge 契约 + core 侧实现（W6，impl-plan §2.6 / 设计 §3.8 D2 表 + 最小示例）。
 //
-// 归属裁定（设计 §3.8 D2 表逐条）：PiEngineService 的 9 成员中——executeAndAwait /
-// getRecordForAction / collectRecords / closeSubagent / cancel / ChatRoundTicket /
-// record 状态回写 / idle+activate lock 定时器——都是「宿主执行链 / 数据所有权在宿主」，
-// 归 HostBridge（core）；pi 包（W7）经 host/* 反向请求消费本面。spawnedChildren 归
-// 引擎进程（core 镜像见同目录 spawned-children.ts）；sendPromptCommand / EPIPE 兜底 /
-// 冷续轮 resume（stdin-writer）归 pi 包（W7 迁移物）。
+// 归属裁定（设计 §3.8 D2 表逐条）：executeAndAwait / getRecordForAction /
+// collectRecords / closeSubagent / cancel / record 状态回写 / idle+activate lock
+// 定时器——都是「宿主执行链 / 数据所有权在宿主」，归 HostBridge（core）；pi 包（W7）
+// 经 host/* 反向请求消费本面。spawnedChildren 归引擎进程（core 镜像见同目录
+// spawned-children.ts）；sendPromptCommand / EPIPE 兜底归 pi 包（W7 迁移物）。
+// [H1 U6] ChatRoundTicket 交接面与冷续轮 resume（stdin-writer）已随 chat 域退役。
 //
 // 本文件只依赖 core 公共类型（types.ts / record-store / stream-sink /
 // lifecycle-manager / orchestration 类型），不 import inproc pi 引擎目录 内部——它是 pi 包
@@ -26,34 +26,21 @@ import type { StatusFilter } from "../../record-store.ts";
 import type { SubagentStream } from "../../stream-sink.ts";
 import type {
   AgentEvent,
-  AgentResult,
   ExecuteOptions,
   ExecutionRecord,
   SubagentRecord,
 } from "../../types.ts";
 
-/**
- * chat 域轮次交接包的 core 契约基座（设计 §3.8 D2「ChatRoundTicket → HostBridge」）。
- * pi 专有扩展（identity / SessionRunnerContext / SpawnResumeOpts resume）在
- * pi-engine.ChatRoundTicket extends 本接口（W7 随包迁移；过渡期 record/opts/signal/
- * priority/stream 五字段的宿主编排语义在此单一权威）。
- */
-export interface HostChatRoundTicket {
-  record: ExecutionRecord;
-  opts: ExecuteOptions;
-  signal: AbortSignal | undefined;
-  priority: number;
-  stream?: SubagentStream;
-}
-
 /**
  * HostBridge 的服务实现面（SubagentService 的结构子集，鸭子类型——与原 pi-engine 的
- * PiEngineService 同一形态的协议化泛化：chat 域轮次面泛型参数化，pi 绑定 =
- * HostBridgeServiceFace<ChatRoundTicket>，见 pi-host-binding.ts 的 re-export）。
- * 为什么用结构接口而非 import SubagentService 类型：防 Service 内部演进连锁影响
- * 契约面 + 测试可注入 fake（PiEngineService 的既有先例，语义照搬）。
+ * PiEngineService 同一形态的协议化泛化）。为什么用结构接口而非 import SubagentService
+ * 类型：防 Service 内部演进连锁影响契约面 + 测试可注入 fake（PiEngineService 的既有
+ * 先例，语义照搬）。
+ * [H1 U6] chat 域轮次交接可选面（HostChatRoundTicket / takeChatRound / runChatRound /
+ * resumeChatRound）已随 chat 域退役删除——续聊 = Continuation → 新 run + resume，
+ * 引擎经协议 converse，不再回调宿主编排面。
  */
-export interface HostBridgeServiceFace<TTicket extends HostChatRoundTicket = HostChatRoundTicket> {
+export interface HostBridgeServiceFace {
   executeAndAwait(
     opts: ExecuteOptions,
     signal?: AbortSignal,
@@ -64,23 +51,18 @@ export interface HostBridgeServiceFace<TTicket extends HostChatRoundTicket = Hos
   closeSubagent(record: ExecutionRecord, force: boolean): Promise<void>;
   cancel(id: string): boolean;
   collectRecords(limit: number, statusFilter?: StatusFilter): SubagentRecord[];
-  /** chat 域轮次交接（run 的 chat 分支入口）：按 taskId 取走预备包（一次性消费）。 */
-  takeChatRound?(taskId: string): TTicket | undefined;
-  /** 执行预备的 chat 轮次（编排归 Service：pool 槽 + runSpawn + 终态迁移）。 */
-  runChatRound?(ticket: TTicket): Promise<AgentResult>;
-  /** 冷路径续轮（interact message 分支的编排回调：守卫 + record 迁移 + kick-off）。 */
-  resumeChatRound?(record: ExecutionRecord, text: string): void;
   /** record 状态迁移上报（热路径投递后让 runtime 派生缓存失效 / GUI 回流）。 */
   reportRecordTransition?(record: ExecutionRecord): void;
 }
 
 /**
- * HostBridge 接口（设计 §3.8 最小示例，9 方法）。core 侧实现；pi 包经 host/* 反向
- * 请求消费。签名与最小示例的两处实现级偏差（均按现状语义落地）：
+ * HostBridge 接口（设计 §3.8 最小示例的协议化视图）。core 侧实现；pi 包经 host/*
+ * 反向请求消费。签名与最小示例的实现级偏差（均按现状语义落地）：
  *   - getRecordForAction 返回 ExecutionRecord | null（现状实现面的活 record 形态；
  *     不存在 / 不可达 → null，引擎侧 resolveRecord 的 try/catch 语义内聚到本面）；
  *   - reportRecordTransition 收 record 对象（现状状态回写以 record 为单位整体上报，
  *     无 patch 增量形态——造 patch 形态属凭空造词，W7 反向通道载荷再议）。
+ * [H1 U6] takeChatRound（chat 域轮次交接）已随 chat 域退役删除。
  */
 export interface HostBridge {
   executeAndAwait(
@@ -93,7 +75,6 @@ export interface HostBridge {
   collectRecords(limit: number, filter?: StatusFilter): SubagentRecord[];
   closeSubagent(record: ExecutionRecord, force: boolean): Promise<void>;
   cancel(id: string): Promise<void>;
-  takeChatRound(taskId: string): HostChatRoundTicket | null;
   reportRecordTransition(record: ExecutionRecord): void;
   armIdleTimer(id: string, ms: number): void;
   disarmIdleTimer(id: string): void;
@@ -111,10 +92,8 @@ export interface HostBridgeDeps {
   onIdleTimeout: (recordId: string) => void;
   // [F-3 删除登记] 曾有的 waitForRoundTerminal / escalateKill 可选注入（W3 D3 cancel
   // 终态等待面）已删：createHostBridge 全仓无生产调用点，且该面与生产 cancel 链结构
-  // 冲突（cancelBackground 同步 unregisterChatRoundRoute 后，waitForRoundTerminal 再
-  // race 轮终相位恒等满 3s 超时）。D3 core 侧收敛语义由引擎面等价承接 =
-  // chat-session.cancel（waiter 先于 kill 注册 + killChain 有界升级），偏差登记见
-  // chat-domain-v1x-liveness-governance.impl-plan.md §5。
+  // 冲突（waitForRoundTerminal race 轮终相位恒等满 3s 超时）。[H1 U6] 注释内旧符号
+  // （chat 轮路由注销 / chat-session.cancel）已随 chat 域退役消亡。
 }
 
 /** HostBridge core 实现（SubagentService 编排面的协议化视图）。 */
@@ -136,14 +115,13 @@ export function createHostBridge(deps: HostBridgeDeps): HostBridge {
      * cancel 语义 = 受理即返回（service.cancel 同步布尔 → 契约 void）。
      * [F-3 删除登记] 终态等待/杀链升级面已删（无生产装配点 + 与 cancelBackground 的
      * 路由注销冲突，见 HostBridgeDeps 尾注）；生产收敛语义由引擎面承接 =
-     * chat-session.cancel（waiter 先于 kill 注册 → 等 roundLifecycle 终态相位 →
+     * chat-session.cancel（waiter 先于 kill 注册 → 等轮次终态相位 →
      * CANCEL_SETTLE_GRACE_MS 未收敛走 killChain 有界升级）。resolve 语义归引擎侧
      * 判 notResumable（契约注释，W6 起如此）。
      */
     cancel: async (id) => {
       service.cancel(id);
     },
-    takeChatRound: (taskId) => service.takeChatRound?.(taskId) ?? null,
     reportRecordTransition: (record) => service.reportRecordTransition?.(record),
     armIdleTimer: (id, ms) => {
       armIdleTimer(id, () => deps.onIdleTimeout(id), ms);

package/src/execution/engine/host/pi-host-binding.ts

@@ -23,11 +23,12 @@
 // （pi-subagent-cli spawn-runner 的 spawn watchdog）保持同源常量，漂移由 conformance
 // chat golden（spawn-args 断言）在引擎包侧守护。
 
+import { SHARED_POOL_KEY } from "@zhushanwen/subagent-engine-sdk";
 import type { EnginePort } from "../port.ts";
 import { EngineNotFoundError, getEngine, hasEngine, listEngines } from "../registry.ts";
 
 /** pi 无隔离池（PI_CODING_AGENT_DIR 全局一份，协议化设计 §3.3.9），poolKey 恒 'shared'。 */
-export const PI_POOL_KEY = "shared";
+export const PI_POOL_KEY = SHARED_POOL_KEY;
 
 /** watchdog 换算下限（分钟）：与引擎包 spawn-runner 的 floor 同源（30min）。 */
 const WATCHDOG_FLOOR_MINUTES = 30;
@@ -46,9 +47,9 @@ export function maxTurnsToWatchdogMs(maxTurns: number): number {
 }
 
 /**
- * 宿主侧 pi EnginePort 解析（SAR / chat 域路由）：registry 的 'pi'（发现器装载的
- * cli descriptor → RemoteEngine）直接返回——chat 轮次与 run 域同路（协议 run(interact)
- * 发往 pi-subagent-cli 引擎进程）。
+ * 宿主侧 pi EnginePort 解析（SAR / 会话形态轮路由）：registry 的 'pi'（发现器装载的
+ * cli descriptor → RemoteEngine）直接返回——续聊轮与 run 域同路（协议 run 帧发往
+ * pi-subagent-cli 引擎进程）。
  * [U-2 一致性修复] pi **未注册**（引擎包未装/发现失败）时返回不可用 stub，不静默
  * 直构任何本地实例——保留设计 D4「全不可用 → 派发期 engine_not_found + 安装指引」
  * 错误契约（zcode 侧 d8-compat 同语义，两引擎对称）。
@@ -85,7 +86,6 @@ function piUnavailableEnginePort(): EnginePort {
     }),
     probe: () => fail(),
     run: () => fail(),
-    interact: () => fail(),
     read: () => fail(),
   };
 }

package/src/execution/engine/port.ts

@@ -16,20 +16,16 @@
 //     （滚动重启推迟谓词输入）。权威源：
 //     docs/design/crash-forensics-and-watchdog.md §3.3 D5。
 //
-// 四个能力面（D1）：
-//   run        —— 主语义：一次性 fire-to-completion 任务执行；
-//   interact   —— 交互控制面（chatMode 的 message/close/cancel + idle，可选能力面，
-//                 capabilities.conversation 声明接通与否）；
+// 三个能力面（D1；[H1 U6] interact 面已随 chat 域退役删除——续聊统一为新 run + resume）：
+//   run        —— 主语义：一次性 fire-to-completion 任务执行（会话形态续聊轮同走 run，
+//                 resume 锚点经 RunContext.resume 携带）；
 //   read       —— session 历史读取（D6 三级降级链）；
 //   probe      —— 探针（D7：二进制存在/版本解析/干跑校验）。
 // capabilities() 同步无副作用——「调用前拒绝」（D11 处置三级）的判据。
 
 import type { ChildProcess } from "node:child_process";
 
-import type {
-  HostRoundLifecycleParams,
-  ResumeAnchor,
-} from "@zhushanwen/subagent-engine-sdk";
+import type { ResumeAnchor } from "@zhushanwen/subagent-engine-sdk";
 
 import type { AgentCallOpts } from "../../orchestration/models/types.ts";
 import type { ModelInfo } from "../model-resolver.ts";
@@ -40,8 +36,6 @@ import type {
   EngineCapabilities,
   EngineHandle,
   EngineHandleData,
-  InteractAction,
-  InteractResult,
   ProbeReport,
   SessionView,
 } from "./types.ts";
@@ -96,6 +90,25 @@ export interface RunContext {
    * pi 引擎另经 ExecuteOptions 投影进 record）。
    */
   engineFallback?: { from: string; reason: string };
+  /**
+   * [F6] 根 session id（SubagentService.sessionRootId 注入）——pi 引擎 relay 归属键
+   * SESSION_ID 的权威来源（经 wire ctx.sessionRootId → server 还原 → SpawnRunParams
+   * → buildChildEnv）。刻意走 per-run ctx 而非 EngineClient 的进程级 env：客户端按
+   * 引擎缓存为惰性单例，进程级 env 在 pi fork 换 sessionId 后会陈旧；per-run ctx 恒
+   * 新鲜，且与 RECORD_ID 已有的 per-run 形态一致。additive：undefined/null/空串不
+   * 上 wire，zcode 等引擎忽略。
+   */
+  sessionRootId?: string;
+  /**
+   * [Option C 协议化] 权威 subagent session 目录（getSubagentSessionDir(agentDir,
+   * rootCwd) 宿主推导值）——经 wire ctx.sessionDir 送达 pi 引擎组装 `--session-dir`。
+   * 生产注入方 = RemoteEngine（cli 形态引擎的唯一宿主侧适配点，env 同源推导，见
+   * remote-engine buildRunParams）；编排层显式注入（ctx.sessionDir 有值）时优先于
+   * RemoteEngine 自推导。zcode 等不消费 session 目录的引擎忽略本字段。编排层可
+   * 不注入；RemoteEngine 缺省以同源 env 推导值补齐后恒上 wire；[LEGACY] fallback
+   * 仅旧宿主/独立运行引擎形态可达。
+   */
+  sessionDir?: string;
   /**
    * [P4 对齐点③] 引擎声明实际隔离池 key（journal 落盘路径权威）。宿主创建 journal
    * writer 时只能用缺省占位 poolKey（pi 恒 'shared'），非池化稳定的引擎（zcode 按
@@ -129,33 +142,16 @@ export interface RunContext {
    */
   onChildSpawned?: (child: ChildProcess) => void;
   /**
-   * [W3 v1.x] chat 会话形态参数（协议 run.params.chat 的 RunContext 承载位）：
-   *   - recordId：core 预建 record 的关联键（引擎据此上报首轮 runId 键之外的反向
-     *     载荷与 interact 定位）——task.conversation === true 的 chat 轮必传；
-   *   - resume：冷续锚点（重开已 idle 的 session 续聊；pi 消费 sessionRef.sessionFile
-     *     ——对照协议化设计前 SpawnResumeOpts.sessionFile 的锚点面）。
-   * 类型权威 = SDK RunChatParams（remote-engine 直传，结构互证由 implements 关系
-   * 在 typecheck 期承载）。非 chat 轮不传，wire 上不出现该键。
+   * [W3 v1.x → H1 U6 终态] 会话形态参数（协议 run.params.resume 的 RunContext
+   * 承载位，键已随 U6 键切换从 `chat` 泛化为 `resume`）：
+   *   - recordId：core 预建 record 的关联键（引擎据此上报 childSpawned/childStateChanged
+   *     的 record 键形态与 handle 锚定）——会话形态轮（task.conversation === true）必传；
+   *   - resume：续聊锚点（record.sessionFile 续写原文件；pi 消费
+   *     sessionRef.sessionFile——对照协议化设计前 SpawnResumeOpts.sessionFile 的锚点面）。
+   * 类型权威 = SDK RunResumeParams（remote-engine 直传，结构互证由 implements 关系
+   * 在 typecheck 期承载）。一次性轮不传，wire 上不出现该键。
    */
-  chat?: { recordId: string; resume?: ResumeAnchor };
-  /**
-   * [W3 v1.x] host/roundLifecycle 轮次生命周期消费口（第 9 反向通道，settled/idle/
-   * failed 三相位；关联键 runId|recordId 互斥）。首轮（run 会话形态）经 run 作用域
-   * 路由到达（runId 键）；续聊轮（interact）无 runId——经 EnginePort
-   * registerChatRoundRoute 的 recordId 键路由到达（见下）。消费语义（arm/disarm/
-   * settled 交棒）归宿主编排层（settled-watchdog 协议事件面接线，W4 三入口）。
-   */
-  onRoundLifecycle?: (phase: HostRoundLifecycleParams) => void;
-}
-
-/**
- * [W3 v1.x] chat 轮次反向通道路由（recordId 键）——interact 续聊轮的 streamDelta /
- * roundLifecycle 分发目标（协议关联键裁定 D1-A：续聊轮无独立 runId）。与 run 作用域
- * RunRoute 同构的薄消费面；注册/注销时机归宿主 chat 编排（轮开始注册、record 终态注销）。
- */
-export interface ChatRoundRoute {
-  onStreamDelta?: (delta: string) => void | Promise<void>;
-  onRoundLifecycle?: (phase: HostRoundLifecycleParams) => void | Promise<void>;
+  resume?: { recordId: string; resume?: ResumeAnchor };
 }
 
 // ============================================================
@@ -197,29 +193,13 @@ export interface EnginePort {
   probe(opts?: { force?: boolean }): Promise<ProbeReport>;
 
   /** D1 主语义：fire-to-completion。[D6 合流] task = AgentCallOpts（单一任务形状，
-   *  原 AgentTaskSpec 已并入——字段裁定见 orchestration/models/types.ts）。 */
+   *  原 AgentTaskSpec 已并入——字段裁定见 orchestration/models/types.ts）。会话形态
+   *  续聊轮同走本方法（resume 锚点经 ctx.resume 携带，[H1 U6] interact 面退役）。 */
   run(task: AgentCallOpts, ctx: RunContext): Promise<EngineRunResult>;
 
-  /**
-   * D1 可选面：交互控制面。pi 首期原生实现（现有 chatMode 行为直通）；不支持
-   * conversation 的引擎返回 engine_capability_unsupported（同步拒绝、不创建进程）。
-   */
-  interact(handle: EngineHandle, action: InteractAction): Promise<InteractResult>;
-
   /** D6 三级降级链：①引擎原生读取 → ②宿主 event journal（P2）→ ③outcome-only。 */
   read(handle: EngineHandle): Promise<SessionView>;
 
-  /**
-   * [W3 v1.x] 可选面：chat 轮次反向通道路由注册（recordId 键）。interact 续聊轮的
-   * streamDelta / roundLifecycle 按 recordId 关联（无 runId，D1-A），引擎进程发射后
-   * 经协议客户端分发到本路由。与 validateModel/listModels 同款的 additively-optional
-   * 演进：宿主 feature-detect（`typeof registerChatRoundRoute === "function"`），
-   * 未实现的引擎（不支持 chat 域或旧客户端）续聊轮 delta/生命周期静默不可达——
-   * conversation gate 已在派发前拦住无 chat 能力的引擎，本缺省只在「能力声明与
-   * 客户端实现错位」的诊断形态出现。返回注销函数（record 终态时宿主调用）。
-   */
-  registerChatRoundRoute?(recordId: string, route: ChatRoundRoute): () => void;
-
   /**
    * [U7] 可选面：模型可发现性——引擎自带 provider/model 体系时（如 zcode 的 v2 桌面
    * 登录态），列出当前环境实际可用的模型清单（带凭据校验），供 system prompt 引擎段

package/src/execution/engine/types.ts

@@ -4,10 +4,11 @@
 // §3.3.5（EnginePort 与中立类型完整契约）+ §3.3.6（EngineHandle/journal/SessionView 格式）。
 //
 // [S4 簇 3 收编] 契约类型单源化（type-only）：AgentOutcome / EngineHandleData /
-// ReplayedTurn / SessionView / EngineCapabilities / ProbeReport / InteractAction /
-// InteractResult 的本地定义已删除，自 @zhushanwen/subagent-engine-sdk re-export
-// （SDK protocol/contract-types.ts 是类型闭包 SSOT，core 反向 re-export 保上层消费面
-// ——import 方路径零改动；结构等价由 protocol-closure.test.ts 断言族守卫）。
+// ReplayedTurn / SessionView / EngineCapabilities / ProbeReport 的本地定义已删除，
+// 自 @zhushanwen/subagent-engine-sdk re-export（SDK protocol/contract-types.ts 是
+// 类型闭包 SSOT，core 反向 re-export 保上层消费面——import 方路径零改动；结构等价
+// 由 protocol-closure.test.ts 断言族守卫）。[H1 U5/U6] InteractAction / InteractResult
+// 已随 chat 域 interact 面退役删除。
 // EngineHandle 留守本地：SDK 无此类型（协议面用裸 data 载荷），宿主侧句柄包装接口
 // 是 core 域概念。
 //
@@ -20,7 +21,7 @@
 
 import type { EngineHandleData } from "@zhushanwen/subagent-engine-sdk";
 
-// AgentEvent 8 种事件：权威定义在 SDK contract-types，经 execution/types.ts re-export
+// AgentEvent 9 种事件：权威定义在 SDK contract-types，经 execution/types.ts re-export
 // → shared/agent-event.ts 转发层 → 本文件（链条保持，维持「shared/ 是类型共享层」的
 // 架构约定）。新增粗粒度约束（coarse 引擎至少合成一次 message_end + 一次 turn_end）
 // 由 conformance 套件断言（P4），不在类型层编码。
@@ -34,26 +35,22 @@ export type {
   AgentOutcome,
   EngineCapabilities,
   EngineHandleData,
-  InteractAction,
-  InteractResult,
   ProbeReport,
   ReplayedTurn,
   SessionView,
 } from "@zhushanwen/subagent-engine-sdk";
 
 // ============================================================
-// EngineHandle（run/interact/read 三面的连接件，D1/§3.3.6）——core 域类型留宿主侧
+// EngineHandle（run/read 两面的连接件，D1/§3.3.6）——core 域类型留宿主侧
 // ============================================================
 
 /**
- * 引擎会话句柄（run 返回、interact/read 入参）。
+ * 引擎会话句柄（run 返回、read 入参；[H1 U5/U6] interact 面退役后不再有 interact
+ * 消费方）。
  *
  * 契约三条（D1）：不透明（上层不解构——唯一例外是 record 持久化层序列化 data 字段与
- * read 降级链）、可持久化（data 是纯 JSON，主会话 reload 后 read/interact 仍可用）、
- * 自描述（data 含 engineId + 引擎 session 定位符 + pool key + adapter 版本）。
- *
- * 对进程已死的 handle 调 interact 必须返回 engine_session_not_resumable（指向 cold
- * resume 路径），而非笼统失败——由各引擎 interact 实现保证。
+ * read 降级链）、可持久化（data 是纯 JSON，主会话 reload 后 read 仍可用）、自描述
+ * （data 含 engineId + 引擎 session 定位符 + pool key + adapter 版本）。
  */
 export interface EngineHandle {
   /** 持久化数据。上层不得解构其内部字段（见契约三条）。 */