@zhushanwen/subagent-engine-sdk 0.2.1 → 0.3.0

package/src/port-contract.ts

@@ -28,8 +28,6 @@ import type {
   AgentOutcome,
   EngineCapabilities,
   EngineHandleData,
-  InteractAction,
-  InteractResult,
   ProbeReport,
   ResumeAnchor,
   SessionView,
@@ -64,7 +62,17 @@ export interface EngineStream {
   onDelta(delta: string): void;
 }
 
-/** run 的运行期上下文（core RunContext 结构等价镜像；chat? = 会话形态参数，缺省一次性任务）。 */
+/**
+ * 无隔离池引擎的恒定池 key（pi / zcode 共用；值锚定）：两引擎进程内全局一份运行态
+ * （pi = PI_CODING_AGENT_DIR 全局一份，zcode = 共享宿主 HOME + journal 固定分组），
+ * poolKey 恒本值。core（PI_POOL_KEY / JOURNAL_INITIAL_POOL_KEY）与两引擎包
+ * （PI_POOL_KEY / ZCODE_SHARED_POOL_KEY）的等值异名常量一律 = 本常量——**值逐字
+ * 不变**（存量 journal 落盘路径与记录含该值分段，改名不改值）。zcode 池化引擎在
+ * prepare 期经 ctx.onPoolResolved retarget 到实际池 key，与本占位值不冲突。
+ */
+export const SHARED_POOL_KEY = "shared";
+
+/** run 的运行期上下文（core RunContext 结构等价镜像；resume? = 会话形态参数，缺省一次性任务）。 */
 export interface RunContext {
   taskId: string;
   poolKey: string;
@@ -74,16 +82,41 @@ export interface RunContext {
   stream?: EngineStream;
   schemaEnv?: string;
   engineFallback?: { from: string; reason: string };
+  /**
+   * [F6] 根 session id（协议 run.params.ctx.sessionRootId 的进程内还原）——pi 引擎
+   * relay 归属键 SESSION_ID 的权威来源。additive 可选：宿主缺省不传。
+   */
+  sessionRootId?: string;
+  /**
+   * [Option C 协议化] 权威 subagent session 目录（协议 run.params.ctx.sessionDir 的
+   * 进程内还原）——pi 引擎组装 `--session-dir` 的唯一权威值（宿主
+   * getSubagentSessionDir 推导，引擎不自推导）。additive 可选：缺省走引擎内
+   * [LEGACY] fallback（独立运行/测试形态）。
+   */
+  sessionDir?: string;
   onPoolResolved?: (poolKey: string) => void;
   onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef" | "poolKey">) => void;
   /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议面）。 */
   onChildSpawned?: (child: { pid: number | undefined; killed: boolean }) => void;
   /**
-   * [v1.x] chat 会话形态参数（协议 run.params.chat 的进程内还原；缺省 = 一次性任务
-   * 形态）。recordId = chat 轮次关联键与 interact 定位键；resume 锚点存在 = 冷续
-   * （--session 续写原文件），不存在 = 首轮新建。
+   * 子进程退出态上报（host/childStateChanged 载荷形态；SR-4 接线：宿主镜像据此取消
+   * 该 pid 的挂起 dialog）。引擎侧只在 exited 相位上报——running 由 onChildSpawned 覆盖。
+   */
+  onChildStateChanged?: (p: {
+    pid: number;
+    recordId: string;
+    state: "running" | "exited";
+    killed: boolean;
+    exitCode?: number;
+    signal?: string;
+  }) => void;
+  /**
+   * [H1 U6 终态] resume 续聊参数（协议 run.params.resume 的进程内还原；唯一会话形态
+   * 键——原 v1.x `chat` 字段已随键切换退役）。recordId = 轮次关联键与镜像帧锚定键；
+   * resume 锚点存在 = 冷续（--session 续写原文件），不存在 = 首轮新建。缺省 =
+   * 一次性任务形态。
    */
-  chat?: { recordId: string; resume?: ResumeAnchor };
+  resume?: { recordId: string; resume?: ResumeAnchor };
 }
 
 export interface EngineHandle {
@@ -101,7 +134,6 @@ export interface EnginePort {
   capabilities(): EngineCapabilities;
   probe(opts?: { force?: boolean }): Promise<ProbeReport>;
   run(task: EngineAgentCallOpts, ctx: RunContext): Promise<EngineRunResult>;
-  interact(handle: EngineHandle, action: InteractAction): Promise<InteractResult>;
   read(handle: EngineHandle): Promise<SessionView>;
   listModels?(): Array<{ id: string; name?: string }> | null;
   validateModel?(modelRef: string | undefined): { canonicalRef: string };

package/src/protocol/contract-types.ts

@@ -8,12 +8,15 @@
 //   - AgentEvent / AgentUsage / AgentUsageTotal / ToolCallResult / ToolCall /
 //     InternalToolCall / Turn ← core execution/types.ts（2026-09-09 实测 :164-:313）
 //   - ReplayedTurn / SessionView / EngineHandleData / EngineCapabilities / ProbeReport /
-//     InteractAction / InteractResult / AgentOutcome ← core execution/engine/types.ts
+//     AgentOutcome ← core execution/engine/types.ts
 //   - AgentFailureKind / AgentOutcomeUsage（core 名 AgentUsage，orchestration 版）/
 //     ToolCallEntry / AgentCallOpts 子集 ← core orchestration/models/types.ts
 //   - WorktreeHandle ← core execution/types.ts:349（SDK 结构等价副本——设计 §3.5.1
 //     点名「AgentCallOpts.worktree 的 WorktreeHandle 即这类副本」）
 //
+// [H1] InteractAction / InteractResult 已随 chat-run 统一退役（U5 删除；
+// docs/design/subagent-chat-run-unification.md §3.3 D5——续聊统一为新 run + resume）。
+//
 // core 域类型（ExecutionRecord / Turn 的宿主内部态消费）留 core；SDK 侧一切类型为
 // 结构等价形态，漂移由双向可赋值断言（AssertMutuallyAssignable）在 typecheck 期抓出
 // ——core 侧断言挂靠归 W2（本文件导出该类型助手供其复用），SDK 侧样板见
@@ -96,8 +99,12 @@ export interface Turn {
 }
 
 /**
- * 引擎事件（8 种，协议 event.params.event 逐字序列化——「事件与 handle 序列化逐字
+ * 引擎事件（9 种，协议 event.params.event 逐字序列化——「事件与 handle 序列化逐字
  * 兼容」不变量 3 的类型面）。语义锚点 = pi（ACP 词汇对照见 core execution/types.ts 注释）。
+ *
+ * activity = 纯活性信号：双侧 reducer no-op、不开 turn、不写状态、不落 journal
+ * （core journal-wiring 对其豁免 append），只承诺「引擎活跃时周期性出现」——供宿主
+ * 无进展守护刷新判活（长工具执行期）。节流属生产者实现细节，不进协议承诺。
  */
 export type AgentEvent =
   | { type: "tool_start"; toolName: string; args?: unknown }
@@ -107,6 +114,7 @@ export type AgentEvent =
   | { type: "turn_end"; summary?: string }
   | { type: "message_end"; usage?: AgentUsage; error?: string }
   | { type: "compaction" }
+  | { type: "activity" }
   | { type: "error"; message: string };
 
 // ============================================================
@@ -114,7 +122,7 @@ export type AgentEvent =
 // ============================================================
 
 /**
- * EngineHandle 的持久化形态（JSON v1）。协议 run 终态应答 / interact / read 的
+ * EngineHandle 的持久化形态（JSON v1）。协议 run 终态应答 / read 的
  * handle 载荷（引擎不持有宿主运行时引用，data 即全部）。
  */
 export interface EngineHandleData {
@@ -135,11 +143,10 @@ export interface EngineHandleData {
 
 /**
  * [v1.x] 冷续 resume 锚点——EngineHandleData 定位键的投影子集（诊断字段
- * v/engineVersion/adapterVersion 不属锚点语义，不随锚点走）。两处消费：
- *   - run.params.chat.resume（宿主 → 引擎：冷续重开已 idle 的 session，pi 消费
- *     sessionRef.sessionFile —— 对照 core SpawnResumeOpts.sessionFile 的锚点面）；
- *   - host/roundLifecycle 载荷 anchor（引擎 → 宿主：轮次终态时回填当前锚点，
- *     宿主据此刷新冷续依据——pi 定位键形态同 EngineHandleData.sessionRef 注释）。
+ * v/engineVersion/adapterVersion 不属锚点语义，不随锚点走）。消费点：
+ *   - run.params.resume（宿主 → 引擎：冷续重开已 idle 的 session，pi 消费
+ *     sessionRef.sessionFile —— 对照 core SpawnResumeOpts.sessionFile 的锚点面）。
+ * [H1 U6 已切换] 键切换单批完成（读写端同批），锚点仅经 resume 键携带。
  * 类型层与 EngineHandleData 定位形态的对照由测试断言（Pick 可赋值闭包）锁定。
  */
 export interface ResumeAnchor {
@@ -188,7 +195,11 @@ export interface EngineCapabilities {
   schemaEnforcement: "native" | "emulated";
   /** 注意区分「引擎 RPC 层有此能力」与「subagent 链路已接通」。 */
   steer: "native" | "emulated" | "unsupported";
-  /** interact 控制面（message/close/cancel + idle）。 */
+  /**
+   * [H1 D5 语义收窄] resume 能力位（chat 续聊 = 新 run + resume 锚点的承载前提；
+   * 原名字沿用——conversation 位保留、语义从「interact 长驻控制面」收窄为
+   * 「resume 续聊能力」，gate 判据与消费方不变）。
+   */
   conversation: "native" | "unsupported";
   /** 决定 persona 路由策略（file/flag/prompt 通道）。 */
   personaInjection: "file" | "flag" | "prompt";
@@ -218,20 +229,6 @@ export interface ProbeReport {
   error?: { code: string; recovery: string };
 }
 
-/**
- * interact 的 action（交互控制面）。interrupt: true = steer（抢占）/ false|缺省 =
- * followUp（排队）；不支持抢占的引擎忽略。
- */
-export type InteractAction =
-  | { kind: "message"; payload: string; interrupt?: boolean }
-  | { kind: "close"; payload?: { force: boolean } }
-  | { kind: "cancel" };
-
-/** interact 的结果（失败码 = engine_session_not_resumable / engine_capability_unsupported 等）。 */
-export type InteractResult =
-  | { ok: true; delivered: true }
-  | { ok: false; code: string; message: string };
-
 // ============================================================
 // 终态 / 任务声明
 // ============================================================

package/src/protocol/engine-protocol.ts

@@ -10,14 +10,25 @@
 // engine_protocol_mismatch（含双方版本 + 升级指引），该引擎标记不可用，
 // 不影响其他引擎与宿主。
 //
-// [v1.x 增量语义（chat-domain 设计 §3.2 D1-A/§3.3）]：chat 域增量（run.params.chat
-// 可选参数、host/roundLifecycle 通道、host/streamDelta 的 recordId 关联形态）以
-// **可选载荷/可选参数**形态向后兼容，major 不 bump、不引入 minor 协商位：
-//   - 新 core × 旧引擎：chat 请求被 conversation gate 同步拒（manifest 无 gate 位，
+// [v1.x 增量语义（chat-domain 设计 §3.2 D1-A/§3.3）][H1 后历史叙述——run.params.chat
+// 已随 U6 删除，现唯一会话形态键 = run.params.resume]：chat 域增量（原 run.params.chat
+// 可选参数、host/streamDelta 的 recordId 关联形态）曾以**可选载荷/可选参数**形态向后
+// 兼容，major 不 bump、不引入 minor 协商位：
+//   - 新 core × 旧引擎：conversation 请求（resume 续聊形态）被 conversation gate
+//     同步拒（manifest 无 gate 位，
 //     A6 方向——engine_capability_unsupported + 升级引擎包指引）；run 域零影响；
-//   - 旧 core × 新引擎：新引擎可能发出旧 core 词表外的 host/roundLifecycle——
-//     既有反向路由对未知 host/* 通道回 {unsupported:true} 引擎自行降级，无需
-//     独立负向场景（设计已裁决）。
+//   事件变体增量同政策（例：activity 活性信号变体）：新变体以可选载荷形态进
+//   union，旧宿主 runtime 对其 no-op（reducer default 分支安全落空 / journal
+//   豁免面不感知），协议版本维持 1、不 bump。
+//
+// [H1 双键过渡（chat-run 统一，docs/design/subagent-chat-run-unification.md §3.3
+// D3 + §5 U1 行）][H1 U6 已切换]：run.params.resume 曾与原 run.params.chat 载荷
+// 同形并存（additive 可选，协议版本维持 1）；U1 只加键——U2-U5 过渡期 core 恒
+// 构造旧 `chat` 键、pi 引擎恒读 `ctx.chat`。U6 已单批同时切换写端（core 构造
+// resume）与读端（pi 改读）并删 `chat` 键，resume 现为唯一会话形态键——全程不存在
+// 「写新读旧」窗口（错配 = resume 静默失效、每轮新文件、sessionFile 被覆盖）。
+// 同批退役已落地：轮次相位反向通道与 interact 方法已随 U5 删除（D5——续聊轮统一
+// 为新 run + resume 锚点，轮次终态由 run 应答承载）。
 
 /** 协议版本（引擎包 manifest `xyz-agent.subagentEngine.protocol` 与 initialize 应答同值）。 */
 export const ENGINE_PROTOCOL_VERSION = 1;
@@ -73,8 +84,7 @@ export const ENGINE_EVENT_COALESCE_DEFAULT = "0";
 /**
  * 反向请求超时二分（帧④注释，R9-2）：
  * - 数据面类（host/log / host/streamDelta / host/poolResolved / host/handleReady /
- *   host/childSpawned / host/childStateChanged / host/roundLifecycle[v1.x]）：10s 未答 =
- *   引擎故障；
+ *   host/childSpawned / host/childStateChanged）：10s 未答 = 引擎故障；
  * - 人机交互类（host/askUser / host/permission）：不设统一超时——core 先回 {ack:true}，
  *   结果异步到达；按 ADR-0047「静默 ≠ 卡死」用无进展检测/用户取消，不据此判引擎故障。
  */

package/src/protocol/error-codes.ts

@@ -101,12 +101,13 @@ export function engineProtocolMismatchError(engineVersion: number): EngineSdkErr
 }
 
 // ============================================================
-// [v1.x] conversation gate 位负向：chat 请求（run 会话形态）同步拒
+// [v1.x] conversation gate 位负向：conversation 请求（resume 续聊会话形态）同步拒
 // ============================================================
 
 /**
- * [v1.x] chat 会话形态的 gate 拒绝具名错误（chat-domain 设计 §3.2 D1-A +
- * 验收 A6：manifest 无 conversation gate 位的引擎收到 chat 请求 → 同步拒）。
+ * [v1.x] resume 会话形态（run.params.resume）的 gate 拒绝具名错误（chat-domain
+ * 设计 §3.2 D1-A + 验收 A6：manifest 无 conversation gate 位的引擎收到
+ * conversation 请求 → 同步拒；[H1] 文案随 D5 语义收窄——续聊 = resume 续聊）。
  * 文案契约对齐 core capability-gate.ts conversation 分支（错误码
  * engine_capability_unsupported + 「去掉参数 / 修 manifest / 升级引擎包」恢复指引）
  * ——W3 chat 路由切协议客户端时以本构造器替换 core 内联文案，保持两侧一致。
@@ -114,15 +115,15 @@ export function engineProtocolMismatchError(engineVersion: number): EngineSdkErr
 export function engineConversationUnsupportedError(engineId: string): EngineSdkError {
   return new EngineSdkError(
     "engine_capability_unsupported",
-    `engine '${engineId}' 不支持 conversation（capabilities.conversation = 'unsupported'，` +
-      `manifest 无 conversation gate 位——无同进程 idle 复用，message/close 交互控制面不可用）`,
+    `engine '${engineId}' 不支持 resume 续聊（capabilities.conversation = 'unsupported'，` +
+      `manifest 无 conversation gate 位）`,
     `去掉 conversation 参数（一次性任务默认形态），或修 manifest capabilities / 升级引擎包（若引擎实际支持该能力）`,
     { engineId, capability: "conversation", declared: "unsupported" },
   );
 }
 
 /**
- * [v1.x] chat 会话形态（run.params.chat / task.conversation=true）派发前的同步 gate：
+ * [v1.x] resume 会话形态（run.params.resume / task.conversation=true）派发前的同步 gate：
  * manifest conversation 位 unsupported 即抛 engineConversationUnsupportedError——
  * 进程/record 创建前同步拒（A6：run 域不受影响，仅 chat 面被拦）。
  * 判据单源：core 侧 capability-gate.assertTaskShapeSupported 的 conversation 分支

package/src/protocol/methods.ts

@@ -1,11 +1,12 @@
 // src/protocol/methods.ts
 //
-// 10 正向方法（core → 引擎）params/result 逐方法写死（v1）。设计权威源：
-// 设计 §3.3 方法集表 + impl-plan §2.1「10 正向方法」。
+// 9 正向方法（core → 引擎）params/result 逐方法写死（v1）。设计权威源：
+// 设计 §3.3 方法集表 + impl-plan §2.1「10 正向方法」（[H1] 收敛为 9）。
 //
-// [v1.x 增量（chat-domain 设计 §3.2 D1-A）]：方法集不变（chat 轮次 = run 会话形态
-// + 既有 interact，不新造 chatRound 方法——D1-B 被否）；增量以可选参数形态落在
-// run.params.chat（会话形态参数 + 冷续 resume 锚点），major 不 bump。
+// [v1.x 增量（chat-domain 设计 §3.2 D1-A）]：增量以可选参数形态落在 run.params.chat
+// （会话形态参数 + 冷续 resume 锚点），major 不 bump。[H1] chat-run 统一后续聊 =
+// 新 run + resume 锚点（docs/design/subagent-chat-run-unification.md §3.3 D5/D7），
+// 既有 interact 方法已随 U5 删除，方法集收敛为 9 个。
 //
 // 应答面补充约定（设计 §3.3）：initialize 应答仅诊断（与 manifest 不一致 → warn 留痕，
 // 不参与同步成员判据；唯一阻断面 = 被 gate 能力位多声明 → engine_capability_mismatch）；
@@ -17,21 +18,22 @@ import type {
   EngineCapabilities,
   EngineHandleData,
   AgentOutcome,
-  InteractAction,
-  InteractResult,
   ModelCatalogEntry,
   ProbeReport,
   ResumeAnchor,
   SessionView,
 } from "./contract-types.ts";
 
-/** 正向方法名联合（恰好 10 个；PROTOCOL_METHODS 常量数组与之同源互证）。 */
+/**
+ * 正向方法名联合（恰好 9 个；PROTOCOL_METHODS 常量数组与之同源互证）。
+ * [H1] `interact` 成员已随 chat-run 统一退役（docs/design/subagent-chat-run-unification.md
+ * §3.3 D5：续聊轮统一为「新 run + resume 锚点」，U5 删除）。
+ */
 export type ProtocolMethod =
   | "initialize"
   | "probe"
   | "run"
   | "cancel"
-  | "interact"
   | "read"
   | "listModels"
   | "validateModel"
@@ -44,7 +46,6 @@ export const PROTOCOL_METHODS = [
   "probe",
   "run",
   "cancel",
-  "interact",
   "read",
   "listModels",
   "validateModel",
@@ -74,24 +75,40 @@ export interface RunContextParams {
   engineFallback?: { from: string; reason: string };
   /** 事件粒度请求（引擎按 capabilities.eventGranularity 实际能力执行）。 */
   streamMode?: "stream" | "coarse";
+  /**
+   * [F6] 根 session id——pi 引擎 relay 归属键 SESSION_ID 的权威来源（生产三来源
+   * ①本字段 ②宿主 env ③根进程 env 中，宿主派发恒走①）。additive 可选：旧引擎忽略
+   * 未知字段，undefined 不上 wire。
+   */
+  sessionRootId?: string;
+  /**
+   * [Option C 协议化] 权威 subagent session 目录——宿主以 getSubagentSessionDir
+   * (agentDir, rootCwd) 推导（宿主单一权威，Fix Gate B S6：引擎本地推导与宿主布局
+   * 三处不等价 → 跨重启续聊链断裂）。引擎用它组装 pi `--session-dir`，不自推导；
+   * 缺省（独立运行/测试）走引擎内 [LEGACY] fallback。additive 可选：旧引擎忽略
+   * 未知字段，undefined 不上 wire。
+   */
+  sessionDir?: string;
 }
 
 // ============================================================
-// [v1.x] run 的 chat 会话形态参数（chat-domain 设计 §3.2 D1-A）
+// [H1] run 的 resume 会话形态参数（chat-run 统一终态；原 v1.x chat 键已退役）
 // ============================================================
 
 /**
- * [v1.x] chat 会话形态参数——HostChatRoundTicket 五字段过协议映射中「record」的
- * 承载位（docs/design/chat-domain-v1x-liveness-governance.md §3.2 D1 五字段映射）：
+ * [H1] run 的 resume 会话形态参数（设计 docs/design/subagent-chat-run-unification.md
+ * §3.3 D3 + §5 U1/U6 行）：原 RunChatParams（v1.x chat 会话形态参数）的泛化改名终态，
+ * 载荷同形（recordId + resume 锚点，ResumeAnchor 不变），仅键名从「chat 会话形态」
+ * 泛化为「resume 续聊」。
  *   - recordId：core 预建 record 的关联键（引擎据此回填 handle.sessionRef、上报
- *     host/childSpawned|childStateChanged 与 host/roundLifecycle 的 record 键形态）；
+ *     host/childSpawned|childStateChanged 的 record 键形态）；
  *   - resume：冷续锚点（重开已 idle 的 session 续聊；缺省 = 新 session）。对照
  *     core SpawnResumeOpts——sessionFile 经 anchor.sessionRef 携带，model/
  *     thinkingLevel 防漂移覆盖走既有 task/ctx 字段，不双写。
- * task.conversation === true 时必传（chat 路由前置 gate：manifest conversation 位
- * unsupported 的引擎同步拒 engine_capability_unsupported——见 error-codes.ts）。
+ * [H1 U6 已切换] `chat` 键整体退役（读写端同批切换，无「写新读旧」窗口），本键为
+ * 唯一会话形态参数。载荷 schema 权威 = runSessionParamsSchema（schema.ts）。
  */
-export interface RunChatParams {
+export interface RunResumeParams {
   recordId: string;
   resume?: ResumeAnchor;
 }
@@ -127,11 +144,11 @@ export interface RunParams {
   task: AgentCallOpts;
   ctx: RunContextParams;
   /**
-   * [v1.x 可选增量] chat 会话形态参数（task.conversation=true 的 chat 路由承载）。
-   * 缺省 = 一次性任务形态，v1 引擎/宿主语义不变（向后兼容：旧引擎忽略未知字段，
-   * 帧级 schema params 不做深校验）。续聊/关断不经此参数——走既有 interact。
+   * [H1 U6 终态] resume 续聊参数（唯一会话形态键；原 v1.x `chat` 键已随键切换退役，
+   * 见 RunResumeParams）。缺省 = 一次性任务形态（向后兼容：旧引擎忽略未知字段，
+   * 帧级 schema params 不做深校验）。additive 可选：undefined 不上 wire。
    */
-  chat?: RunChatParams;
+  resume?: RunResumeParams;
 }
 
 /** run 终态应答（期间事件经 event 通知；长运行方法，应答到达即终态）。 */
@@ -153,11 +170,6 @@ export interface CancelResult {
   ok: true;
 }
 
-export interface InteractParams {
-  handle: EngineHandleData;
-  action: InteractAction;
-}
-
 export interface ReadParams {
   handle: EngineHandleData;
   /** 数据根必填：存量池时代引擎自算池/journal 相对 dbPath 的定位需要它（设计钉死）。 */
@@ -206,7 +218,6 @@ export interface ProtocolParamsMap {
   probe: ProbeParams;
   run: RunParams;
   cancel: CancelParams;
-  interact: InteractParams;
   read: ReadParams;
   listModels: ListModelsParams;
   validateModel: ValidateModelParams;
@@ -220,7 +231,6 @@ export interface ProtocolResultMap {
   probe: ProbeReport;
   run: RunResult;
   cancel: CancelResult;
-  interact: InteractResult;
   read: SessionView;
   listModels: ListModelsResult;
   validateModel: ValidateModelResult;

package/src/protocol/reverse-channels.ts

@@ -1,9 +1,10 @@
 // src/protocol/reverse-channels.ts
 //
-// 9 反向通道（引擎 → core，帧④，必须应答）载荷与超时二分。设计权威源：
-// 设计 §3.3 方法集表 host/* 行 + impl-plan §2.1「8 反向通道」与「反向请求超时二分」
-// + chat 域 v1.x 增量（docs/design/chat-domain-v1x-liveness-governance.md §3.2 D1-A：
-// 第 9 通道 host/roundLifecycle 承载轮次终态事件与 record 回写）。
+// 8 反向通道（引擎 → core，帧④，必须应答）载荷与超时二分。设计权威源：
+// 设计 §3.3 方法集表 host/* 行 + impl-plan §2.1「8 反向通道」与「反向请求超时二分」。
+// [H1] chat 域 v1.x 增量曾新增的第 9 通道（轮次相位帧）已随 chat-run 统一退役
+// （docs/design/subagent-chat-run-unification.md §3.3 D5，U5 删除）——轮次终态
+// 改由 run 应答（agent_settled resolve）承载，通道集收敛回 8 个。
 //
 // 应答约定：数据面类回 {ok:true}（REVERSE_REQUEST_TIMEOUT_MS=10s 未答 = 引擎故障 →
 // 杀进程 + 在途 run 失败）；人机交互类走 ack 两阶段——先回 {ack:true}，结果异步到达
@@ -12,10 +13,10 @@
 
 import type { ReverseRequestTimeoutClass } from "./engine-protocol.ts";
 import type { UiRequest, UiResponse } from "../ui-types.ts";
-import type { AgentUsage, ResumeAnchor } from "./contract-types.ts";
-import type { ProtocolError } from "./frames.ts";
 
-/** 反向通道名联合（恰好 9 个；REVERSE_CHANNELS 常量数组与之同源互证）。 */
+/**
+ * 反向通道名联合（恰好 8 个；REVERSE_CHANNELS 常量数组与之同源互证）。
+ */
 export type ReverseChannel =
   | "host/log"
   | "host/askUser"
@@ -24,9 +25,11 @@ export type ReverseChannel =
   | "host/poolResolved"
   | "host/handleReady"
   | "host/childSpawned"
-  | "host/childStateChanged"
-  | "host/roundLifecycle";
+  | "host/childStateChanged";
 
+/**
+ * 通道名全集（运行时顺序化枚举；与 ReverseChannel 的同源关系由测试断言）。
+ */
 export const REVERSE_CHANNELS = [
   "host/log",
   "host/askUser",
@@ -36,13 +39,11 @@ export const REVERSE_CHANNELS = [
   "host/handleReady",
   "host/childSpawned",
   "host/childStateChanged",
-  "host/roundLifecycle",
 ] as const satisfies readonly ReverseChannel[];
 
 /**
  * 超时二分归属（10s 数据面 / 不设统一超时的人机交互面）。实现归 W2 EngineClient；
  * 引擎侧自灭计时（W12）复用同表——已 ack 的 askUser 等待不计入 in-flight（R9-2）。
- * host/roundLifecycle 属数据面（终态回执语义：宿主必须确认收到，10s 未答 = 引擎故障）。
  */
 export const REVERSE_CHANNEL_TIMEOUT_CLASS: Record<ReverseChannel, ReverseRequestTimeoutClass> = {
   "host/log": "data-plane",
@@ -51,7 +52,6 @@ export const REVERSE_CHANNEL_TIMEOUT_CLASS: Record<ReverseChannel, ReverseReques
   "host/handleReady": "data-plane",
   "host/childSpawned": "data-plane",
   "host/childStateChanged": "data-plane",
-  "host/roundLifecycle": "data-plane",
   "host/askUser": "interaction",
   "host/permission": "interaction",
 };
@@ -97,11 +97,9 @@ export type HostPermissionResult = { approved: boolean } | { unsupported: true }
 /**
  * host/streamDelta：UI 实时通道（双通道之一；与 event 通知并行的渲染加速面）。
  *
- * [v1.x 关联键扩展——D1-A 裁定，W1 落地不再临场选择]：
- *   - run 域轮（含 run 会话形态首轮）：runId 关联（v1 现状不变，runId 由 core 在
- *     run 帧分配）；
- *   - interact 发起的续聊轮：**recordId** 关联（续聊轮无独立 runId——InteractParams/
- *     InteractResult 均不含，recordId 经 handle.sessionRef 送达引擎）。
+ * [H1 U6 现行语义] 关联键恒 runId（run 域轮与 chat 续聊轮已统一为 run——续聊轮
+ * 是携带 resume 锚点的新 run，runId 由 core 在 run 帧分配）。recordId 键分支是
+ * v1.x 旧引擎的兼容载荷形态（存量兼容读，现行引擎不写）。
  * 两键互斥（undefined 孪生位防双填），消费侧经 isHostStreamDeltaParams 收窄。
  */
 export type HostStreamDeltaParams =
@@ -163,90 +161,6 @@ export interface HostChildStateChangedParams {
   signal?: string;
 }
 
-// ============================================================
-// [v1.x] host/roundLifecycle：轮次生命周期载荷（chat 域 v1.x 唯一新通道）
-// ============================================================
-
-/**
- * 轮次关联键（D1-A 裁定的类型面）：run 域轮 = runId（v1 现状）；interact 续聊轮 =
- * recordId（经 handle.sessionRef）。undefined 孪生位保证两键互斥。
- */
-export interface RoundKeyedByRun {
-  runId: string;
-  recordId?: undefined;
-}
-
-export interface RoundKeyedByRecord {
-  recordId: string;
-  runId?: undefined;
-}
-
-/**
- * 轮次终态相位（事件即 record 回写载体——chat 域 record 处置由相位一一映射，
- * 设计 D2 裁决表 conversation 行：settled/idle 轮收口不终态、failed 标 failed）：
- *   - settled：轮收敛（输出完整）。消费点 = settled-watchdog disarm + D3 abort
- *     收敛判据（cancel 受理后等本事件，超 CANCEL_SETTLE_GRACE_MS 走杀链）；
- *   - idle：轮收口 + 会话进 idle 稳态（core 侧 doFinalizeRoundToIdle + idle 定时器
- *     锚点）。settled 与 idle 是两个锚点：watchdog 在 settled 即解除，idle 管置闲；
- *   - failed：轮异常终止（引擎自知失败，如 EPIPE 兜底耗尽）——error 如实上报，
- *     record 标 failed（与 run 域 AgentOutcome.error 的「失败收口」语义对齐）。
- * usage 为本轮 message_end 增量（interact 续聊轮无 event 通知通道，用量经本帧回填）。
- * 不设 seq：stdio NDJSON 单连接有序 + 数据面应答确认，无重排/重放面（与 event
- * 通知的 seq 对照——后者镜像进程内事件流基线，本帧无基线可镜像）。
- */
-export interface RoundSettledPhase {
-  phase: "settled";
-  usage?: AgentUsage;
-}
-
-export interface RoundIdlePhase {
-  phase: "idle";
-  usage?: AgentUsage;
-  /** 冷续锚点回填（session 滚动/compaction 后锚点可能变化，宿主按帧刷新）。 */
-  anchor?: ResumeAnchor;
-}
-
-export interface RoundFailedPhase {
-  phase: "failed";
-  /** 失败原因（结构对齐协议 error 帧——code/message/recovery 可操作闭环）。 */
-  error: ProtocolError;
-  anchor?: ResumeAnchor;
-}
-
-/** 相位联合（消费侧 switch(phase) 判别用）。 */
-export type RoundLifecyclePhase = RoundSettledPhase | RoundIdlePhase | RoundFailedPhase;
-
-/** host/roundLifecycle 载荷：关联键（run|record）× 相位（settled|idle|failed）。 */
-export type HostRoundLifecycleParams =
-  | (RoundKeyedByRun & RoundSettledPhase)
-  | (RoundKeyedByRun & RoundIdlePhase)
-  | (RoundKeyedByRun & RoundFailedPhase)
-  | (RoundKeyedByRecord & RoundSettledPhase)
-  | (RoundKeyedByRecord & RoundIdlePhase)
-  | (RoundKeyedByRecord & RoundFailedPhase);
-
-/**
- * roundLifecycle 载荷结构判定：关联键互斥 + phase 词表 + 各相位专属形状
- * （failed 必含 error.code/message）。引擎侧发帧前自检与 core 侧消费共用，
- * 防两侧各写一份判别（与 isHostStreamDeltaParams 同理）。
- */
-export function isHostRoundLifecycleParams(value: unknown): value is HostRoundLifecycleParams {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value as Record<string, unknown>;
-  const hasRunId = typeof v.runId === "string";
-  const hasRecordId = typeof v.recordId === "string";
-  if (hasRunId === hasRecordId) return false;
-  if (v.phase === "settled" || v.phase === "idle") return true;
-  if (v.phase !== "failed") return false;
-  const err = v.error;
-  return (
-    typeof err === "object" &&
-    err !== null &&
-    typeof (err as Record<string, unknown>).code === "string" &&
-    typeof (err as Record<string, unknown>).message === "string"
-  );
-}
-
 /** 通道 → 载荷类型映射。 */
 export interface ReverseChannelParamsMap {
   "host/log": HostLogParams;
@@ -257,7 +171,6 @@ export interface ReverseChannelParamsMap {
   "host/handleReady": HostHandleReadyParams;
   "host/childSpawned": HostChildSpawnedParams;
   "host/childStateChanged": HostChildStateChangedParams;
-  "host/roundLifecycle": HostRoundLifecycleParams;
 }
 
 /** 通道 → 异步/同步结果类型映射（ack 两阶段通道的第二阶段 result）。 */
@@ -270,5 +183,4 @@ export interface ReverseChannelResultMap {
   "host/handleReady": { ok: true };
   "host/childSpawned": { ok: true };
   "host/childStateChanged": { ok: true };
-  "host/roundLifecycle": { ok: true };
 }

package/src/protocol/schema.ts

@@ -103,6 +103,7 @@ export const notificationFrameSchema = {
                 "turn_end",
                 "message_end",
                 "compaction",
+                "activity",
                 "error",
               ],
             },
@@ -152,3 +153,38 @@ export const FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS = [
 
 /** 反向通道名词表导出（schema enum 与 W2 路由同源）。 */
 export const REVERSE_CHANNEL_NAMES: readonly ReverseChannel[] = REVERSE_CHANNELS;
+
+// ============================================================
+// [H1] run 会话形态参数载荷 schema（resume 单键校验权威）
+// ============================================================
+
+/**
+ * run.params 的会话形态参数载荷 schema（draft-07 深载荷片段）。设计权威源：
+ * docs/design/subagent-chat-run-unification.md §3.3 D3 + §5 U1/U6 行。
+ *
+ * [H1 U6 已切换] 键切换单批完成后本 schema 面向唯一键 `resume`（RunResumeParams：
+ * recordId + 可选 ResumeAnchor），形状不变。帧级 schema（requestFrameSchema.params）
+ * 刻意不做深校验（见本文件头注释），本片段供消费方（引擎读端结构化报错 / 测试正负
+ * 样本）按需深校验。
+ */
+export const runSessionParamsSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineRunSessionParams",
+  type: "object",
+  additionalProperties: false,
+  required: ["recordId"],
+  properties: {
+    recordId: { type: "string" },
+    resume: {
+      type: "object",
+      additionalProperties: false,
+      required: ["sessionRef", "poolKey"],
+      properties: {
+        // ResumeAnchor.sessionRef = Record<string, string>（引擎定位键值对）
+        sessionRef: { type: "object", additionalProperties: { type: "string" } },
+        poolKey: { type: "string" },
+        journalPath: { type: "string" },
+      },
+    },
+  },
+} as const;