@zhushanwen/subagent-core 0.6.0 → 0.7.1

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

@@ -0,0 +1,255 @@
+// src/execution/engine/client/reverse-router.ts
+//
+// 反向请求（帧④）路由器（EngineClient 的内部模块，从 engine-client.ts 拆出——
+// max-lines 纪律 + 职责域独立：超时域二分（R9-2/R9-2b）的全部 core 侧语义都
+// 落在本文件）。
+//
+// 超时域划分（impl-plan §2.2 / 设计 §3.3 帧④注释）：
+//   - 快答数据面（host/log / host/streamDelta / host/poolResolved / host/handleReady /
+//     host/childSpawned / host/childStateChanged）：分发 + 回 {ok:true}，10s 应答守卫
+//     ——10s 未答 = 引擎故障 → 杀进程 + 在途 run 失败（REVERSE_REQUEST_TIMEOUT_MS）；
+//   - 人机交互面（host/askUser / host/permission）：ack 两阶段——收即回 {ack:true}，
+//     handler 结果异步补帧②，**不计时**（R9-2：已 ack 的等待不参与任何 in-flight
+//     超时，ADR-0047 静默 ≠ 卡死）；未注入 handler → {unsupported:true}；
+//   - 未知 host/* 通道 → {unsupported:true}（引擎自行降级，不重试）。
+
+import {
+  getLogger,
+  REVERSE_CHANNEL_TIMEOUT_CLASS,
+  REVERSE_REQUEST_TIMEOUT_MS,
+  type HostAskUserParams,
+  type HostChildSpawnedParams,
+  type HostChildStateChangedParams,
+  type HostHandleReadyParams,
+  type HostLogParams,
+  type HostPermissionParams,
+  type HostPoolResolvedParams,
+  type HostRoundLifecycleParams,
+  type HostStreamDeltaParams,
+  type UiRequest,
+} from "@zhushanwen/subagent-engine-sdk";
+
+import type { SpawnedChildrenMirror } from "./mirror.ts";
+import type { RunRoute } from "./engine-client.ts";
+
+const logger = getLogger("subagents");
+
+/** 路由器依赖面（EngineClient 注入；全部单向引用，无回环持有）。 */
+export interface ReverseRouterDeps {
+  engineId: string;
+  /** host/askUser 应答端（[D4-④] subagent-service init.uiRequestHandler 注入点）。 */
+  uiRequestHandler?: (req: UiRequest) => Promise<unknown>;
+  /** host/permission 应答端（v1 骨架注入点）。 */
+  permissionHandler?: (params: HostPermissionParams) => Promise<unknown>;
+  /** host/log 落宿主日志（缺省 SDK logger facade）。 */
+  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 数据源）。 */
+  setPartialHandle: (partial: { sessionRef: Record<string, string>; poolKey: string }) => void;
+  /** 帧②应答出口。 */
+  sendResponse: (id: string, result: unknown) => boolean;
+  /** 引擎故障拉起杀链（killAll）。 */
+  failEngine: (reason: string) => Promise<void>;
+  /** 客户端是否已停机（停机后不再写帧）。 */
+  isDisposed: () => boolean;
+}
+
+/** 帧④入口（EngineClient.handleLine 委托）。 */
+export function routeReverseRequest(deps: ReverseRouterDeps, frame: { id: string; method: string; params: unknown }): void {
+  if (frame.method === "host/askUser") {
+    handleInteractionRequest(deps, frame, deps.uiRequestHandler, (params) => (params as HostAskUserParams).request as UiRequest);
+    return;
+  }
+  if (frame.method === "host/permission") {
+    handleInteractionRequest(deps, frame, deps.permissionHandler, (params) => params as HostPermissionParams);
+    return;
+  }
+  const timeoutClass = (REVERSE_CHANNEL_TIMEOUT_CLASS as Record<string, string | undefined>)[frame.method];
+  if (timeoutClass === "data-plane") {
+    handleDataPlaneRequest(deps, frame);
+    return;
+  }
+  deps.sendResponse(frame.id, { unsupported: true });
+}
+
+/**
+ * 人机交互面 ack 两阶段（R9-2）：先回 {ack:true}，handler 结果异步补帧②。
+ * **不计时**——已 ack 的等待属人机交互异步等待，不参与任何 in-flight 超时；
+ * handler 永不 resolve（用户不答）也不判引擎故障。handler 抛错兜底
+ * {cancelled:true}（dialog-queue 应答链同款语义）。
+ */
+function handleInteractionRequest<P>(
+  deps: ReverseRouterDeps,
+  frame: { id: string; method: string; params: unknown },
+  handler: ((input: P) => Promise<unknown>) | undefined,
+  extract: (params: unknown) => P,
+): void {
+  if (handler === undefined) {
+    deps.sendResponse(frame.id, { unsupported: true });
+    return;
+  }
+  deps.sendResponse(frame.id, { ack: true });
+  let input: P;
+  try {
+    input = extract(frame.params);
+  } catch {
+    deps.sendResponse(frame.id, { cancelled: true });
+    return;
+  }
+  void (async () => {
+    try {
+      const result = await handler(input);
+      if (!deps.isDisposed()) deps.sendResponse(frame.id, result);
+    } catch (err) {
+      logger.warn(
+        `[engine-client:${deps.engineId}] ${frame.method} handler failed, answering cancelled: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+      if (!deps.isDisposed()) deps.sendResponse(frame.id, { cancelled: true });
+    }
+  })();
+}
+
+/**
+ * 快答数据面（R9-2 二分）：分发 + 回 {ok:true}，全程受 10s 应答守卫——10s 未答 =
+ * 引擎故障 → 杀进程 + 在途 run 失败。当前各通道分发都是快操作；守卫覆盖的是
+ * 「handler 返回的 promise 挂住」的演化面（挂起 = 宿主消费方死锁，须 fail-fast
+ * 拉起杀链，防止 core 被单通道拖死）。分发抛错不判引擎故障（宿主回调 bug 不该
+ * 杀引擎），仍回 {ok:true} + warn 留痕。
+ */
+function handleDataPlaneRequest(deps: ReverseRouterDeps, frame: { id: string; method: string; params: unknown }): void {
+  let settled = false;
+  const guardTimer = setTimeout(() => {
+    if (settled) return;
+    logger.error(
+      `[engine-client:${deps.engineId}] data-plane reverse request ${frame.method} `
+        + `unanswered for ${REVERSE_REQUEST_TIMEOUT_MS}ms — treating as engine fault`,
+    );
+    void deps.failEngine(
+      `data-plane reverse request ${frame.method} unanswered for ${REVERSE_REQUEST_TIMEOUT_MS}ms (engine fault)`,
+    );
+  }, REVERSE_REQUEST_TIMEOUT_MS);
+  void Promise.resolve()
+    .then(() => dispatchDataPlane(deps, frame.method, frame.params))
+    .then(
+      () => {
+        settled = true;
+        clearTimeout(guardTimer);
+        deps.sendResponse(frame.id, { ok: true });
+      },
+      (err: unknown) => {
+        settled = true;
+        clearTimeout(guardTimer);
+        logger.warn(
+          `[engine-client:${deps.engineId}] ${frame.method} dispatch failed (answering ok, host-side bug): ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+        deps.sendResponse(frame.id, { ok: true });
+      },
+    );
+}
+
+/** 数据面单通道分发器（params 形态自证——发帧前引擎侧自检，分发层只做强转）。 */
+type DataPlaneHandler = (deps: ReverseRouterDeps, params: unknown) => Promise<void> | void;
+
+/** method → 分发器表（表外 method = 无操作；路由面准入已由 REVERSE_CHANNEL_TIMEOUT_CLASS 收敛为 data-plane）。 */
+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),
+  "host/childStateChanged": (deps, params) => dispatchChildStateChanged(deps, params as HostChildStateChangedParams),
+};
+
+async function dispatchDataPlane(deps: ReverseRouterDeps, method: string, params: unknown): Promise<void> {
+  await DATA_PLANE_HANDLERS[method]?.(deps, params);
+}
+
+function dispatchLog(deps: ReverseRouterDeps, p: HostLogParams): void {
+  if (deps.log !== undefined) deps.log(p);
+  else logger[p.level](`[engine:${p.component}] ${p.message}`, p.data);
+}
+
+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;
+  }
+  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);
+}
+
+async function dispatchHandleReady(deps: ReverseRouterDeps, p: HostHandleReadyParams): Promise<void> {
+  deps.setPartialHandle({ sessionRef: p.sessionRef, poolKey: p.poolKey });
+  await deps.runRoutes.get(p.runId)?.onHandleReady?.({
+    sessionRef: p.sessionRef,
+    poolKey: p.poolKey,
+  });
+}
+
+function dispatchChildSpawned(deps: ReverseRouterDeps, p: HostChildSpawnedParams): void {
+  deps.mirror.recordSpawned(p.pid, p.recordId);
+  // POSIX 运行时组探测（W10 / A3 前提②）：任务子进程应与引擎同组（收割 =
+  // 引擎进程组级 kill(-enginePid)）。kill(-pid, 0) 成功 ⟺ 该 pid 自成进程组
+  // （setsid/detached 后代）⟺ 不在引擎收割组内 → 告警留痕（不判 fail——
+  // detached 后代是设计 §3.9 已接受代价）。Windows 无外部判据（无 kill(-pid,0)
+  // 等价物），仅 SDK 层 spawnEngineChild 形态保证，真机面挂 A3 手动门。
+  if (process.platform !== "win32" && typeof p.pid === "number") {
+    try {
+      process.kill(-p.pid, 0);
+      logger.warn(
+        `[engine-client:${deps.engineId}] childSpawned pid ${p.pid} leads its own process group `
+          + `(not in the engine harvest group — one-generation children + in-group descendants `
+          + `only; engine-detached descendants are an accepted cost per design §3.9)`,
+      );
+    } catch (err) {
+      // ESRCH = pid 非组长 = 在引擎组内（预期形态）；其余 errno 同按预期形态
+      // debug 留痕（组探测异常排查时的最低可见性，不判 fail）。
+      logger.debug(
+        `[engine-client:${deps.engineId}] childSpawned pid ${p.pid} group probe settled ` +
+          `(${err instanceof Error ? err.message : String(err)})`,
+      );
+    }
+  }
+}
+
+function dispatchChildStateChanged(deps: ReverseRouterDeps, p: HostChildStateChangedParams): void {
+  deps.mirror.recordStateChanged({
+    pid: p.pid,
+    recordId: p.recordId,
+    state: p.state,
+    killed: p.killed,
+    exitCode: p.exitCode,
+    signal: p.signal,
+  });
+}

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

@@ -1,26 +1,49 @@
 // 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，既有错误族）。
+// 特判）。设计权威源（现行）：docs/design/subagent-engine-protocolization.md §3.3
+// 「能力位」段（manifest 权威 + 方向判定表）+ 历史源 docs/design/subagent-dual-track-
+// convergence.md §3.3 D3-④ + r3 裁定（EngineCapabilities 新增 maxTurns 能力位）+
+// 错误规格（engine_capability_unsupported / engine_capability_mismatch）。
 //
 // 判据形态：每个引擎拦截「自己 capabilities 声明不支持的能力」——
 //   - conversation → capabilities.conversation === 'unsupported'
 //   - fork/forkFromSessionFile → session 分叉通道族全缺（steer 与 conversation 均
-//     'unsupported'，见下方 fork 判据说明）
+//     'unsupported'，OR 语义任一可用即放行，见下方 fork 判据说明）
 //   - maxTurns → capabilities.maxTurns === false（r3 扩位）
 //   - worktree（boolean true 或 WorktreeHandle）→ capabilities.sandbox === 'none'
 //
+// [W3 协议化能力位方向判定（设计 §3.3 能力位表）] capabilities 的同步源 = manifest
+// 快照（注册期读，非握手缓存）。被 gate 四类判据涉及的能力位（conversation /
+// steer+conversation / maxTurns / sandbox）**manifest 是权威契约**，双向处置：
+//   - **少声明**（任务要求的能力 manifest 未声明）→ 本文件同步拒
+//     engine_capability_unsupported；恢复指引 = 「修 manifest / 升级引擎包」——不写
+//     「先派一次任务触发握手」（gate 读 manifest，握手不参与同步判据，那个指引是空转）；
+//   - **多声明**（manifest 声明支持而引擎实际不支持）→ gate 读不到（同步面只有
+//     manifest），由首个 run 的协议握手 `initialize` 发现 → engine_capability_mismatch
+//     该 run 失败 + record 标 failed + **清理 run 前已建的前置副作用**（worktree：
+//     executeViaEngine 在 kickOffEngineRun 前创建，经 finalizeFailed → finalizeRecord
+//     Step 3b cleanupWorktreeIfBound 清理）。判定函数 = 本文件
+//     assertGateCapabilitiesMatched（core 侧判据；协议客户端握手尾接线归 client/ 领地）。
+//   - **非 gate 位**（personaInjection / eventGranularity / sessionRead / resume /
+//     interrupt / permissionMode / schemaEnforcement）不一致（无论强弱）→ 一律 warn
+//     留痕不阻断（诊断面 = EngineClient.warnOnManifestDiagnostics）。
+//
 // 调用点仍是两处（单点的是实现，不是调用点）：
 //   - 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，全数放行）。
+// 行为变化声明：唯一有意行为变化 = workflow 域 zcode+worktree 由漏拦变拦截（修复
+// 双轨清单 #7 的跨域缺口）；pi 的 maxTurns/fork/conversation/worktree 等既有合法
+// 能力零拦截（V4⑤ 反向守护）。[W3] recovery 文案随协议化变更：恢复指引主指向
+// 「修 manifest / 升级引擎包」（引擎包是能力声明的载体，换引擎不再是缺省指引——
+// 协议化后不存在「内置 pi 恒可用」兜底）。
+
+// [W3 v1.x] conversation gate 判据单源 = SDK 具名构造器（W1 交接防漂移项：core 内联
+// 文案与引擎侧 assertChatConversationSupported 双份文案的漂移面消除——同一构造器
+// 两侧消费，错误码/恢复指引契约单一权威）。
+import { engineConversationUnsupportedError } from "@zhushanwen/subagent-engine-sdk";
 
 import { EngineError } from "./errors.ts";
 import type { EngineCapabilities } from "../types.ts";
@@ -38,17 +61,20 @@ export interface TaskShapeForGate {
   maxTurns?: number;
 }
 
+/** 恢复指引公共尾段（W3 协议化口径：能力声明的修复通道 = manifest / 引擎包升级）。 */
+const MANIFEST_RECOVERY_TAIL = "修 manifest capabilities / 升级引擎包（若引擎实际支持该能力）";
+
 /**
  * 调用前预检：任务形状中的能力参数对引擎 capabilities 逐一对照，声明不支持即抛
  * EngineError(engine_capability_unsupported)——同步 throw、进程/record 创建前，文案
- * 含 capabilities 依据与恢复指引（换参数/换引擎）。
+ * 含 capabilities 依据与恢复指引（修 manifest / 升级引擎包 / 调整任务参数）。
  *
  * 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 的
- * 初始上下文继承是两条轴），故取通道族任一可用即支持的分寸。
+ * 'unsupported'，**OR 语义任一可用即放行**）。pi conversation='native'（chatMode idle
+ * 复用）→ 放行；zcode 双 'unsupported'（argv-only spawn 单轮，无父 session 分叉通道）
+ * → 拒绝。仅凭 steer 判会误拦 pi（pi 的 steer 声明 'unsupported'——RPC 有但 spawn
+ * 链路未接通，与 fork 的初始上下文继承是两条轴），故取通道族任一可用即支持的分寸。
  */
 export function assertTaskShapeSupported(
   engineId: string,
@@ -56,12 +82,11 @@ export function assertTaskShapeSupported(
   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 续聊），或不传该参数（一次性任务默认形态）`,
-    );
+    // [W1 交接防漂移项落地] 文案/错误码/恢复指引单源 = SDK engineConversationUnsupportedError
+    // （引擎侧 server.run chat gate 消费同一构造器——A6 双向负向面两侧同文案）。
+    // 错误载体类型 EngineError → EngineSdkError（code/recovery/message 前缀契约不变，
+    // name 变化不影响消费方——无 instanceof EngineError 判据，code 字段分流）。
+    throw engineConversationUnsupportedError(engineId);
   }
   if (task.fork === true || task.forkFromSessionFile !== undefined) {
     if (caps.steer === "unsupported" && caps.conversation === "unsupported") {
@@ -69,7 +94,7 @@ export function assertTaskShapeSupported(
         "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`,
+        `把所需父上下文写进 task 正文后不传 fork，或 ${MANIFEST_RECOVERY_TAIL}`,
       );
     }
   }
@@ -78,7 +103,7 @@ export function assertTaskShapeSupported(
       "engine_capability_unsupported",
       `engine '${engineId}' 不支持 maxTurns（capabilities.maxTurns = false，轮数上限依赖 turn_end 事件流，` +
         `本引擎无此语义——静默丢弃会造成「传了上限却失控」的假象）`,
-      `去掉 maxTurns 参数重派，或改用 engine: pi（turn limiter 执行轮数上限）`,
+      `去掉 maxTurns 参数重派，或 ${MANIFEST_RECOVERY_TAIL}`,
     );
   }
   if ((task.worktree === true || typeof task.worktree === "object") && caps.sandbox === "none") {
@@ -86,7 +111,69 @@ export function assertTaskShapeSupported(
       "engine_capability_unsupported",
       `engine '${engineId}' 不支持 worktree 隔离（capabilities.sandbox = 'none'，` +
         `引擎未接文件系统隔离层）`,
-      `改用 engine: pi（worktree 隔离可用），或不传该参数（在 parent cwd 执行）`,
+      `去掉 worktree 参数（在 parent cwd 执行），或 ${MANIFEST_RECOVERY_TAIL}`,
     );
   }
 }
+
+// ============================================================
+// 能力位方向判定②：manifest 多声明 → run 期握手发现（engine_capability_mismatch）
+// ============================================================
+
+/**
+ * manifest vs `initialize` 应答的 gate 位方向判定（设计 §3.3 能力位表「多声明」行）。
+ *
+ * 只判被 gate 四类判据涉及的能力位中「manifest 声明可用、引擎应答不支持」的多声明
+ * 方向（少声明方向在派发前已被 assertTaskShapeSupported 同步拦，握手不会发生——gate
+ * 先行的结构性结果）；命中抛 EngineError(engine_capability_mismatch)，由首个 run 的
+ * 协议路径转化为该 run 失败 + record 标 failed + 清理前置副作用（契约变更⑤）。
+ * 非 gate 位不一致不进本判定（无论强弱一律 warn 留痕，归 EngineClient 诊断面）。
+ *
+ * 各 gate 位的「manifest 可用」取值语义与 assertTaskShapeSupported 逐条对偶：
+ *   conversation 应答 'unsupported' 而 manifest 非 'unsupported' → mismatch；
+ *   fork 通道族应答双 'unsupported' 而 manifest 任一可用 → mismatch（OR 对偶）；
+ *   maxTurns 应答 false 而 manifest true → mismatch；
+ *   sandbox 应答 'none' 而 manifest 非 'none' → mismatch。
+ *
+ * 接线位置（领地边界声明）：本函数是 core 侧判据单源；协议客户端在首个 run 前握手
+ * 后（EngineClient.initialize 应答 → RemoteEngine.run 发 run 帧前）调用——client/ 为
+ * W2 已交付领地，接线归后续单元（W8/W10），不属本文件。
+ */
+export function assertGateCapabilitiesMatched(
+  engineId: string,
+  manifestCaps: EngineCapabilities,
+  answeredCaps: EngineCapabilities,
+): void {
+  if (
+    manifestCaps.conversation !== "unsupported" &&
+    answeredCaps.conversation === "unsupported"
+  ) {
+    throw gateMismatchError(engineId, "conversation", manifestCaps.conversation, answeredCaps.conversation);
+  }
+  const manifestForkCapable = manifestCaps.steer !== "unsupported" || manifestCaps.conversation !== "unsupported";
+  const answeredForkCapable = answeredCaps.steer !== "unsupported" || answeredCaps.conversation !== "unsupported";
+  if (manifestForkCapable && !answeredForkCapable) {
+    throw gateMismatchError(
+      engineId,
+      "fork（steer/conversation 通道族）",
+      `steer=${manifestCaps.steer}/conversation=${manifestCaps.conversation}`,
+      `steer=${answeredCaps.steer}/conversation=${answeredCaps.conversation}`,
+    );
+  }
+  if (manifestCaps.maxTurns === true && answeredCaps.maxTurns === false) {
+    throw gateMismatchError(engineId, "maxTurns", String(manifestCaps.maxTurns), String(answeredCaps.maxTurns));
+  }
+  if (manifestCaps.sandbox !== "none" && answeredCaps.sandbox === "none") {
+    throw gateMismatchError(engineId, "sandbox（worktree）", manifestCaps.sandbox, answeredCaps.sandbox);
+  }
+}
+
+/** engine_capability_mismatch 的统一构造（manifest 权威 + 恢复指引 = 修 manifest / 升级引擎包）。 */
+function gateMismatchError(engineId: string, cap: string, declared: string, answered: string): EngineError {
+  return new EngineError(
+    "engine_capability_mismatch",
+    `engine '${engineId}' manifest 声明的能力位 '${cap}'（${declared}）与引擎 initialize 应答不符（${answered}）` +
+      `——manifest 多声明，任务按 gate 判据放行后引擎无法兑现`,
+    `修 manifest capabilities（与引擎实际能力对齐）或升级引擎包；若任务不再需要该能力，调整任务参数后重派`,
+  );
+}

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

@@ -25,6 +25,7 @@ export const ENGINE_ERROR_CODES = [
   "schema_emulation_failed",
   "engine_timeout",
   "engine_capability_unsupported",
+  "engine_capability_mismatch",
   "engine_session_not_resumable",
   "model_not_available",
   "prompt_too_large",
@@ -94,8 +95,11 @@ export const DEFAULT_RECOVERY_HINTS: Record<EngineErrorCode, string> = {
     "The engine was killed by the host timeout chain. Inspect the captured stdout tail, then re-run with a larger " +
     "timeout, a narrower task, or `engine: pi`.",
   engine_capability_unsupported:
-    "This engine declares the capability unsupported. Use a single-shot call instead of interactive steering, " +
-    "or dispatch with `engine: pi` which supports it.",
+    "This engine declares the capability unsupported. Adjust the task parameters, " +
+    "or fix the manifest capabilities / upgrade the engine package if it actually supports it.",
+  engine_capability_mismatch:
+    "The engine manifest declares a capability its initialize handshake did not confirm. " +
+    "Fix the manifest capabilities (align with actual engine behavior) or upgrade the engine package.",
   engine_session_not_resumable:
     "Idle-process reuse does not survive a main-session reload. Use a cold resume path " +
     "(engine --resume / --session with the recorded session reference), or start a new subagent.",
@@ -113,9 +117,6 @@ export const DEFAULT_RECOVERY_HINTS: Record<EngineErrorCode, string> = {
 // P2 消费的具名构造器（动态参数进 detail/recovery）
 // ============================================================
 
-/** 错误回显长度上限（截断长输出，避免错误消息爆炸——对齐 structured-output echo 上限量级）。 */
-const DETAIL_ECHO_MAX_CHARS = 200;
-
 /** truncate(text, max)：尾部截断 + 省略号标记（模板共用）。 */
 function truncate(text: string, max: number): string {
   return text.length <= max ? text : `${text.slice(0, max)}...`;
@@ -133,15 +134,6 @@ export function promptTooLargeError(actualBytes: number, limitBytes: number): En
   );
 }
 
-/** nested_spawn_rejected（nesting-guard 消费）：文案说明防护规则 + 指向 task 内自行完成。 */
-export function nestedSpawnRejectedError(): EngineError {
-  return new EngineError(
-    "nested_spawn_rejected",
-    "this process is already a subagent (XYZ_AGENT_SUBAGENT=1)",
-    DEFAULT_RECOVERY_HINTS.nested_spawn_rejected,
-  );
-}
-
 /** stdout 尾部回显上限（engine_timeout / engine_run_failed 的错误规格载体系数）。 */
 export const STDOUT_TAIL_ECHO_CHARS = 2000;
 
@@ -170,14 +162,6 @@ export function engineRunFailedDetail(reason: string, exitCode: number | null, s
   );
 }
 
-/**
- * schema_emulation_failed 的终报文案（宿主编排层「重试一次仍失败」后消费）：
- * 与 structured-output 的重试语义对齐（重试一次 → 报错含原始输出尾部）。
- */
-export function schemaEmulationFailedDetail(error: string, tail: string): string {
-  return (
-    `structured output emulation failed after tolerant extraction and one host-side retry: ${error}. ` +
-    `Raw output tail: ${truncate(tail, DETAIL_ECHO_MAX_CHARS)}. ` +
-    `Recovery: ${DEFAULT_RECOVERY_HINTS.schema_emulation_failed}`
-  );
-}
+// schema_emulation_failed 的终报文案（schemaEmulationFailedDetail）已随 schema-emulation
+// 死镜像收口删除：活体单源 SDK error-codes.ts（emulated 引擎的宿主编排层经 SDK 消费），
+// core 侧此前仅剩自身测试引用（test-only）。

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

@@ -14,7 +14,6 @@
 // warn 一次 + 置 failed，后续 append 丢弃、close 立即返回（不静默：warn 有留痕）。
 
 import { appendFile, mkdir, open } from "node:fs/promises";
-import { readFileSync } from "node:fs";
 import { dirname } from "node:path";
 
 import { getLogger } from "../../../core/logger.ts";
@@ -203,52 +202,7 @@ function defaultWarn(msg: string): void {
 // 重放
 // ============================================================
 
-/**
- * 重放 journal：读取路径下全部事件，重放即得 AgentEvent 流（read 第②级）。
- *
- * - 文件不存在 → []（降级链语义：②级不可达不算错误，调用方落 ③级）；
- * - 损坏行跳过（追加写产物末行可能截断；跳过优于整体失败——设计 C5「三级都不 throw」）；
- * - 按 seq 稳定排序后返回（重放顺序权威是 seq，不依赖文件行序的隐式保证，§3.3.6）。
- */
-export function replayJournal(path: string): AgentEvent[] {
-  let raw: string;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch {
-    return [];
-  }
-  const lines: JournalLine[] = [];
-  for (const row of raw.split("\n")) {
-    const trimmed = row.trim();
-    if (trimmed === "") continue;
-    const parsed = parseLine(trimmed);
-    if (parsed !== undefined) lines.push(parsed);
-  }
-  lines.sort((a, b) => a.seq - b.seq);
-  return lines.map((l) => l.event);
-}
-
-/** 单行 parse + 结构 guard（v=1 + event 形状最小判别：object 且 type 为 string）。 */
-function parseLine(trimmed: string): JournalLine | undefined {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(trimmed);
-  } catch {
-    return undefined;
-  }
-  if (typeof parsed !== "object" || parsed === null) return undefined;
-  const rec = parsed as Record<string, unknown>;
-  const event = rec.event;
-  if (rec.v !== 1 || typeof rec.ts !== "number" || typeof rec.seq !== "number") return undefined;
-  if (typeof event !== "object" || event === null || typeof (event as Record<string, unknown>).type !== "string") {
-    return undefined;
-  }
-  return {
-    v: 1,
-    ts: rec.ts,
-    taskId: typeof rec.taskId === "string" ? rec.taskId : "",
-    engineId: typeof rec.engineId === "string" ? rec.engineId : "",
-    seq: rec.seq,
-    event: event as AgentEvent,
-  };
-}
+// replayJournal/parseLine 已收编 SDK journal-io（S4 簇 6：zcode 引擎包不能 import
+// core，双包逐字等价副本单源落 SDK；此处 re-export 保 journal-replay.ts /
+// session-view-service.ts 消费路径零改动）。行格式权威仍 §3.3.6，行为逐字等价。
+export { replayJournal } from "@zhushanwen/subagent-engine-sdk";

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

@@ -10,9 +10,11 @@
 
 import { createRecord, updateFromEvent } from "../../execution-record.ts";
 import type { AgentEvent } from "../../types.ts";
+// aggregateUsage / toReplayedTurn 单源 SDK（自 session-view-projection.ts 逐字等价
+// 迁入后收口——双活副本删除，live ≡ replay 的投影语义不再靠双份手工同步）。
+import { aggregateUsage, toReplayedTurn } from "@zhushanwen/subagent-engine-sdk";
 import type { EngineHandle, SessionView } from "../types.ts";
 import { replayJournal } from "./event-journal.ts";
-import { aggregateUsage, toReplayedTurn } from "./session-view-projection.ts";
 
 /**
  * journal → SessionView（read 第②级）。