@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/execution/dialog-queue.ts

@@ -84,79 +84,12 @@ function dialogTimeoutLogMessage(req: UiRequest, waitedMs: number): string {
   );
 }
 
-// ── 类型定义（本模块是 UiRequest/UiResponse/UiRequestHandler 的规范来源） ──
-// session-runner.ts 和 ui-channels.ts 复用这些类型（session-runner 再导出供测试 import）。
-
-/** Pi extension_ui_request 的方法枚举（dialog + fire-and-forget 两类）。
- *  dialog 类：select/confirm/input/editor（占输入焦点，等响应）。
- *  fire-and-forget 类：notify/setStatus/setWidget/setTitle/set_editor_text（纯展示/写入）。
- *  (string & {}) 兜底：Pi 未来新增 method 或未知 method 走字符串字面量类型。 */
-export type UiMethod =
-  | "select"
-  | "confirm"
-  | "input"
-  | "editor"
-  | "notify"
-  | "setStatus"
-  | "setWidget"
-  | "setTitle"
-  | "set_editor_text"
-  | (string & {});
-
-/** UI 请求（session-runner 构造后传给 handler）。
- *
- *  method 是判别字段，决定排队策略（dialog 排队）和业务路由（channel 分发）。
- *  method 特定字段按 method 可选出现（与 ExtensionUiRequest 1:1，由 session-runner 从
- *  ExtensionUiRequest 平铺构造）。channel/channelPayload 由 parseChannel 填充。
- *
- *  契约来源：.fix-plans/00-master-summary.md §二 2.2。 */
-export interface UiRequest {
-  /** Pi rpc-types.ts 的 method（select/confirm/input/editor 为 dialog 类）。 */
-  method: UiMethod;
-  /** 请求 id（从 extension_ui_request envelope 顶层提取，用于 response 关联）。 */
-  id: string;
-  // method 特定字段（按 method 可选，与 ExtensionUiRequest 1:1）
-  title?: string;
-  options?: string[];
-  message?: string;
-  placeholder?: string;
-  prefill?: string;
-  notifyType?: string;
-  statusKey?: string;
-  statusText?: string | undefined;
-  widgetKey?: string;
-  widgetLines?: string[] | undefined;
-  widgetPlacement?: "aboveEditor" | "belowEditor";
-  text?: string;
-  timeout?: number;
-  /** channel 名（从 method 对应字段的 NUL 前缀解析）。
-   *  select → 从 title 解析；setWidget → 从 widgetLines[0] 解析；其他 → undefined。
-   *  已知值："ask_user"（select）、"gui_widget"（setWidget）。handler 按 channel 分发。 */
-  channel?: string;
-  /** channel 解析后的结构化 payload（已 JSON.parse）。
-   *  ask_user: {questions, allowCancel}；gui_widget: {component}；无 channel: undefined。 */
-  channelPayload?: unknown;
-  /** 内部元数据字段：发起该 UI 请求的子进程 pid（由 session-runner.handleUiRequest 从
-   *  child.pid 填入）。L2 队列据此关联 rejectChildDialogs（child close 时批量 reject）。
-   *  下划线前缀表示内部字段，非 Pi 协议字段，不参与 stdin 回写。 */
-  _childPid?: number;
-}
-
-/** UI 响应（handler 返回，session-runner 按 shape 回写 stdin）。
- *  - {value}: select/input/editor 的答案
- *  - {confirmed}: confirm 的答案
- *  - {cancelled}: 取消（child close / handler 抛错 / 用户取消）
- *  - {ack}: fire-and-forget（当前不透传到 TUI，留作协议完整） */
-export type UiResponse =
-  | { value: string }
-  | { confirmed: boolean }
-  | { cancelled: true }
-  | { ack: true };
-
-/** UI 请求 handler 签名（单函数，按 req.method 内部路由）。
- *  实现方负责：channel 业务路由（ask_user → AskUserComponent）+ 默认转发（ctx.ui.*）。
- *  抛错由调用方（DialogGlobalQueue / session-runner）兜底为 {cancelled:true}。 */
-export type UiRequestHandler = (req: UiRequest) => Promise<UiResponse>;
+// ── 类型再导出（W7 / R3 S-A + R4-S③：SSOT 迁 @zhushanwen/subagent-engine-sdk
+// src/ui-types.ts，结构等价；队列实现本体留 core——壳侧 host/askUser 消费端与
+// inproc 过渡链路同样消费该类型面。双向可赋值断言挂本包 typecheck 断言族
+// （contract-closure），漂移编译期可抓。 ──
+export type { UiMethod, UiRequest, UiRequestHandler, UiResponse } from "@zhushanwen/subagent-engine-sdk";
+import type { UiRequest, UiRequestHandler, UiResponse } from "@zhushanwen/subagent-engine-sdk";
 
 // ── DialogGlobalQueue 实现 ──
 

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

@@ -1,5 +1,6 @@
 // capability-gate.test.ts —— [D3-④ 预检 capabilities 化] 拦截矩阵单测。
-// 设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-④（r3 裁定：
+// 设计权威源：docs/design/subagent-engine-protocolization.md §3.3「能力位」段（manifest
+// 权威双向处置）+ 历史源 subagent-dual-track-convergence.md §3.3 D3-④（r3 裁定：
 // EngineCapabilities +maxTurns 位 pi=true/zcode=false，不保留硬编码 shape 检查）+
 // §3.4 错误规格第 1 行 + §4 V4④⑤（正反向验收）。
 //
@@ -7,21 +8,41 @@
 //   1. per-engine 拦截矩阵：pi 全放行（含 maxTurns/fork/conversation/worktree——V4⑤
 //      反向守护，pi 既有合法能力零拦截）；zcode 四参数全拦（fork/conversation/
 //      maxTurns/worktree）
-//   2. 错误族：engine_capability_unsupported + recovery 含可操作指引（换参数/换引擎）
-//   3. fork 判据（借位裁定）：session 分叉通道族任一可用即放行——pi conversation=
-//      native 放行（steer 虽 unsupported 不参与否决）；通道族全缺才拦
+//   2. 错误族：engine_capability_unsupported + recovery 含可操作指引（调参数 / 修
+//      manifest / 升级引擎包——W3 协议化口径，不再指向「engine: pi」内置兜底）
+//   3. fork 判据（借位裁定）：session 分叉通道族任一可用即放行（OR 语义，A6⑦）——
+//      pi conversation=native 放行（steer 虽 unsupported 不参与否决）；通道族全缺才拦
+//   4. [W3] 方向判定②：manifest 多声明 → assertGateCapabilitiesMatched 抛
+//      engine_capability_mismatch（gate 位逐位正反例 + 非 gate 位不判定）
 
 import { describe, expect, it } from "vitest";
 
-import { assertTaskShapeSupported, type TaskShapeForGate } from "../../common/capability-gate.ts";
+import {
+  assertGateCapabilitiesMatched,
+  assertTaskShapeSupported,
+  type TaskShapeForGate,
+} from "../../common/capability-gate.ts";
 import { EngineError } from "../../common/errors.ts";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
 import type { EngineCapabilities } from "../../types.ts";
-import { PiEngine } from "../../engines/pi/pi-engine.ts";
-import { ZcodeEngine } from "../../engines/zcode/zcode-engine.ts";
 
-/** 真实引擎的 capabilities 面单测直取（D3 声明是判据本体——pi=true/zcode=false 扩位）。 */
-const PI_CAPS = new PiEngine({ getService: () => null }).capabilities();
-const ZCODE_CAPS = new ZcodeEngine({ engineDataDir: () => "/tmp/zcode-gate" }).capabilities();
+// W10（§2.10 ②）：gate 判据源改读引擎包 manifest（package.json xyz-agent.capabilities
+// ——协议化后同步成员唯一源），不再深路径构造内建引擎实例（W11 删除）。
+function manifestCaps(relPkg: string): EngineCapabilities {
+  const pkg = JSON.parse(
+    readFileSync(
+      join(dirname(fileURLToPath(import.meta.url)), "../../../../../../", relPkg, "package.json"),
+      "utf8",
+    ),
+  ) as { "xyz-agent": { subagentEngine: { capabilities: EngineCapabilities } } };
+  return pkg["xyz-agent"].subagentEngine.capabilities;
+}
+
+const PI_CAPS = manifestCaps("pi-subagent-cli");
+const ZCODE_CAPS = manifestCaps("zcode-subagent-cli");
 
 /** 会话分叉通道族可用的 zcode 形态变体（fork 判据用）。 */
 const ZCODE_CAPS_WITH_CONVERSATION: EngineCapabilities = { ...ZCODE_CAPS, conversation: "native" };
@@ -34,12 +55,24 @@ function gate(
   assertTaskShapeSupported(engineId, caps, task);
 }
 
-function gateError(caps: EngineCapabilities, task: TaskShapeForGate, engineId = "zcode"): EngineError {
+/** 断言载体（结构化面）：EngineError（core）与 EngineSdkError（SDK 构造器）共用
+ *  code/message/recovery 契约，测试按结构断言不绑类。 */
+interface GateErrorShape {
+  code: string;
+  message: string;
+  recovery: string;
+}
+
+function gateError(caps: EngineCapabilities, task: TaskShapeForGate, engineId = "zcode"): GateErrorShape {
   try {
     gate(caps, task, engineId);
   } catch (err) {
-    expect(err).toBeInstanceOf(EngineError);
-    return err as EngineError;
+    // [W1 交接防漂移项落地] conversation 分支抛 SDK EngineSdkError
+    //（engineConversationUnsupportedError——core 与引擎侧判据单源，W3 接线）；其余
+    // 分支仍为 core EngineError。code/recovery/message 前缀契约两侧一致。
+    expect(err).toHaveProperty("code");
+    expect(err).toHaveProperty("recovery");
+    return err as unknown as GateErrorShape;
   }
   throw new Error("expected assertTaskShapeSupported to throw");
 }
@@ -71,8 +104,10 @@ describe("capability-gate（D3-④ 拦截矩阵）", () => {
       expect(err.code).toBe("engine_capability_unsupported");
       expect(err.message).toMatch(pattern);
       expect(err.message).toContain("capabilities");
-      // 错误信息可操作（§3.4）：恢复指引指向换参数/换引擎
-      expect(err.recovery).toMatch(/engine: pi|不传|去掉/);
+      // 错误信息可操作（§3.4 + W3 协议化口径）：恢复指引 = 调整参数 / 修 manifest /
+      // 升级引擎包（能力声明的载体），不再指向「engine: pi」内置兜底
+      expect(err.recovery).toMatch(/去掉|不传/);
+      expect(err.recovery).toMatch(/修 manifest|升级引擎包/);
     }
   });
 
@@ -89,3 +124,68 @@ describe("capability-gate（D3-④ 拦截矩阵）", () => {
     expect(() => gate({ ...ZCODE_CAPS, steer: "native" }, { fork: true })).not.toThrow();
   });
 });
+
+// ============================================================
+// [W3] 方向判定②：manifest 多声明 → engine_capability_mismatch（impl-plan §2.3）
+// ============================================================
+
+describe("assertGateCapabilitiesMatched（manifest vs initialize 应答，gate 位方向判定）", () => {
+  function mismatchError(
+    manifestCaps: EngineCapabilities,
+    answeredCaps: EngineCapabilities,
+  ): EngineError {
+    try {
+      assertGateCapabilitiesMatched("fake", manifestCaps, answeredCaps);
+    } catch (err) {
+      expect(err).toBeInstanceOf(EngineError);
+      return err as EngineError;
+    }
+    throw new Error("expected assertGateCapabilitiesMatched to throw");
+  }
+
+  it("conversation：manifest 非 unsupported、应答 unsupported → engine_capability_mismatch", () => {
+    const err = mismatchError(
+      { ...ZCODE_CAPS, conversation: "native" },
+      { ...ZCODE_CAPS, conversation: "unsupported" },
+    );
+    expect(err.code).toBe("engine_capability_mismatch");
+    expect(err.message).toContain("conversation");
+    expect(err.recovery).toMatch(/manifest|升级引擎包/);
+  });
+
+  it("fork 通道族（OR 对偶）：manifest 任一可用、应答双 unsupported → mismatch", () => {
+    const err = mismatchError(
+      { ...ZCODE_CAPS, steer: "native" },
+      { ...ZCODE_CAPS, steer: "unsupported", conversation: "unsupported" },
+    );
+    expect(err.code).toBe("engine_capability_mismatch");
+    expect(err.message).toContain("fork");
+  });
+
+  it("maxTurns：manifest true、应答 false → mismatch", () => {
+    const err = mismatchError({ ...ZCODE_CAPS, maxTurns: true }, { ...ZCODE_CAPS, maxTurns: false });
+    expect(err.code).toBe("engine_capability_mismatch");
+    expect(err.message).toContain("maxTurns");
+  });
+
+  it("sandbox：manifest 非 none、应答 none → mismatch", () => {
+    const err = mismatchError({ ...ZCODE_CAPS, sandbox: "emulated" }, { ...ZCODE_CAPS, sandbox: "none" });
+    expect(err.code).toBe("engine_capability_mismatch");
+    expect(err.message).toContain("sandbox");
+  });
+
+  it("应答强于 manifest（引擎兑现更多）→ 不抛；同值对齐 → 不抛（无多声明）", () => {
+    const weak = { ...ZCODE_CAPS, conversation: "unsupported" as const, maxTurns: false, sandbox: "none" as const };
+    const strong = { ...ZCODE_CAPS, conversation: "native" as const, maxTurns: true, sandbox: "emulated" as const };
+    // 应答强于 manifest：引擎兑现 manifest 全部声明，无多声明
+    expect(() => assertGateCapabilitiesMatched("fake", weak, strong)).not.toThrow();
+    // 同值对齐：无差异
+    expect(() => assertGateCapabilitiesMatched("fake", strong, strong)).not.toThrow();
+  });
+
+  it("非 gate 位不一致 → 不判定不抛（无论强弱一律 warn 留痕，归 EngineClient 诊断面）", () => {
+    const manifest = { ...ZCODE_CAPS, personaInjection: "file" as const, eventGranularity: "stream" as const, sessionRead: "full" as const, resume: "native" as const, interrupt: "native" as const, permissionMode: "native" as const, schemaEnforcement: "native" as const };
+    const weaker = { ...ZCODE_CAPS, personaInjection: "prompt" as const, eventGranularity: "coarse" as const, sessionRead: "outcome-only" as const, resume: "unsupported" as const, interrupt: "kill-only" as const, permissionMode: "fixed" as const, schemaEnforcement: "emulated" as const };
+    expect(() => assertGateCapabilitiesMatched("fake", manifest, weaker)).not.toThrow();
+  });
+});

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

@@ -1,7 +1,9 @@
 // errors.test.ts —— 引擎层错误 SSOT 的结构锁定。
 //
-// 三视角：①构建者——11 条 code 与设计 §3.3.3 全表一致；②使用者——错误消息
-// code 前缀格式可被字符串匹配分流；③观察者——每条错误必有非空恢复指引（可操作）。
+// 三视角：①构建者——12 条 code 与设计错误规格全表一致（[W3] 协议化增
+// engine_capability_mismatch——manifest 多声明的 run 期握手阻断面，与 SDK 协议错误码
+// 词表同源）；②使用者——错误消息 code 前缀格式可被字符串匹配分流；③观察者——每条
+// 错误必有非空恢复指引（可操作）。
 
 import { describe, expect, it } from "vitest";
 
@@ -12,14 +14,12 @@ import {
   engineRunFailedDetail,
   engineTimeoutDetail,
   isEngineErrorCode,
-  nestedSpawnRejectedError,
   promptTooLargeError,
-  schemaEmulationFailedDetail,
   STDOUT_TAIL_ECHO_CHARS,
 } from "../../common/errors.ts";
 
 describe("ENGINE_ERROR_CODES（§3.3.3 全表）", () => {
-  it("11 条错误码与设计文档错误规格表逐条一致", () => {
+  it("12 条错误码与设计文档错误规格表逐条一致（[W3] 协议化增 engine_capability_mismatch）", () => {
     expect([...ENGINE_ERROR_CODES]).toEqual([
       "engine_not_found",
       "engine_probe_failed",
@@ -28,6 +28,7 @@ describe("ENGINE_ERROR_CODES（§3.3.3 全表）", () => {
       "schema_emulation_failed",
       "engine_timeout",
       "engine_capability_unsupported",
+      "engine_capability_mismatch",
       "engine_session_not_resumable",
       "model_not_available",
       "prompt_too_large",
@@ -90,13 +91,6 @@ describe("具名构造器", () => {
     expect(err.recovery).toMatch(/stdin/);
   });
 
-  it("nestedSpawnRejectedError：说明防护规则 + 指向 task 内自行完成", () => {
-    const err = nestedSpawnRejectedError();
-    expect(err.code).toBe("nested_spawn_rejected");
-    expect(err.message).toContain("XYZ_AGENT_SUBAGENT");
-    expect(err.recovery).toMatch(/inside the current task/);
-  });
-
   it("engineTimeoutDetail：含 stdout 尾部 + engine: pi 重跑建议", () => {
     const detail = engineTimeoutDetail("partial stdout output");
     expect(detail).toContain("partial stdout output");
@@ -123,10 +117,9 @@ describe("具名构造器", () => {
     expect(engineRunFailedDetail("crash", null, "t")).toContain("killed by signal");
   });
 
-  it("schemaEmulationFailedDetail：含错误明细 + 原始输出尾部 + 重试一次语义", () => {
-    const detail = schemaEmulationFailedDetail("Schema validation failed: /a must be number", '{"a":"x"}');
-    expect(detail).toContain("Schema validation failed");
-    expect(detail).toContain('{"a":"x"}');
-    expect(detail).toMatch(/retry once/i);
-  });
+  // nestedSpawnRejectedError 用例已随构造器删除（nesting-guard 收编 SDK 后死导出，
+  // 活体单源 SDK nesting-guard.ts NestedSpawnRejectedError，其行为由 SDK
+  // __tests__/primitives.test.ts + 本目录 nesting-guard.test.ts 覆盖）。
+  // schemaEmulationFailedDetail 用例已随函数删除（test-only 死镜像收口，活体单源
+  // SDK error-codes.ts，其行为由 SDK __tests__/primitives.test.ts 覆盖）。
 });

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

@@ -25,7 +25,7 @@ function tmpPath(name: string): string {
 
 afterEach(() => {
   if (tmpRoot !== undefined) {
-    rmSync(tmpRoot, { recursive: true, force: true });
+    rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     tmpRoot = undefined;
   }
 });

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

@@ -1,5 +1,11 @@
 // kill-chain.test.ts —— 杀链两分支 + 超时终态合成 + abort 两级编排（fake timers）。
 //
+// 实现体已收编 @zhushanwen/subagent-engine-sdk（common/kill-chain.ts 为 re-export
+// shim，s4-reuse 簇 1）：SDK 侧 __tests__/kill-chain.test.ts 是超集演进版（+
+// LoggerSink 捕获 + kill 抛错幂等用例），本文件保留 core 侧独有断言——engine: pi
+// 重跑建议文案、stdout 尾部 2000 字截断、signalCode 形态退出、grace 贴边不升级。
+// SDK 版 synthesizeTimeoutOutcome 的 engineId 必填（core 原缺省 "pi" 已删），用例显式传。
+//
 // 三视角：①构建者——SIGTERM 优雅 / 超时 SIGKILL 两分支的信号序列正确；②使用者——
 // abortWithFallback 对 CLI-only 与 native-interrupt 引擎都收敛不悬挂；③观察者——
 // 合成终态的 error 含 stdout 尾部与 exitCode=null（被信号杀死判据）。
@@ -120,6 +126,7 @@ describe("synthesizeTimeoutOutcome", () => {
     const outcome = synthesizeTimeoutOutcome(
       { prompt: "review files", description: "review-files" },
       "last stdout lines...",
+      "pi",
     );
     expect(outcome.error!).toContain("engine_timeout");
     expect(outcome.error).toContain("review-files");

package/src/execution/engine/__tests__/common/nesting-guard.test.ts

@@ -1,5 +1,11 @@
 // nesting-guard.test.ts —— 嵌套标记注入与原生标记剥离（D8 双层防护）。
 //
+// 实现体已收编 @zhushanwen/subagent-engine-sdk（common/nesting-guard.ts 为
+// re-export shim，s4-reuse 簇 2）：SDK 侧 __tests__/primitives.test.ts 已有同语义
+// 断言，本文件保留 core 侧独有细粒度断言——精确名 vs 前缀剥离边界（CLAUDE_UNRELATED）、
+// 非 '1' 值不抛、空白 env 最小产出。错误形态随收编改 NestedSpawnRejectedError
+//（code/recovery 文案与 core 词表逐字一致）。
+//
 // 三视角：①构建者——三引擎原生标记（PI_SUBAGENT_* / CLAUDECODE / ZSW_NESTED）全部
 // 剥离且其余 env 保留；②使用者——子代理进程内 assertNotNestedSpawn 同步拒绝且文案
 // 可操作；③观察者——产出的 env 是新对象（不污染入参）。
@@ -9,9 +15,9 @@ import { describe, expect, it } from "vitest";
 import {
   assertNotNestedSpawn,
   buildNestedSpawnEnv,
+  NestedSpawnRejectedError,
   NESTED_SPAWN_ENV,
 } from "../../common/nesting-guard.ts";
-import { EngineError } from "../../common/errors.ts";
 
 describe("buildNestedSpawnEnv", () => {
   it("注入统一标记 XYZ_AGENT_SUBAGENT=1", () => {
@@ -60,12 +66,12 @@ describe("buildNestedSpawnEnv", () => {
 
 describe("assertNotNestedSpawn", () => {
   it("检测到统一标记（本进程已是 subagent）→ 抛 nested_spawn_rejected", () => {
-    expect(() => assertNotNestedSpawn({ [NESTED_SPAWN_ENV]: "1" })).toThrowError(EngineError);
+    expect(() => assertNotNestedSpawn({ [NESTED_SPAWN_ENV]: "1" })).toThrowError(NestedSpawnRejectedError);
     try {
       assertNotNestedSpawn({ [NESTED_SPAWN_ENV]: "1" });
       expect.unreachable("should throw");
     } catch (err) {
-      const e = err as EngineError;
+      const e = err as NestedSpawnRejectedError;
       expect(e.code).toBe("nested_spawn_rejected");
       // 文案说明防护规则（标记名）+ 指向 task 内自行完成
       expect(e.message).toContain("XYZ_AGENT_SUBAGENT");

package/src/execution/engine/__tests__/common/pool-manager.test.ts

@@ -29,7 +29,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
-  rmSync(tmpRoot, { recursive: true, force: true });
+  rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 /** 读池 refs.json 的解析形态。 */
@@ -142,7 +142,7 @@ describe("releasePoolRef 引用计数与整池删除", () => {
   it("池目录不存在时 release → 无原生状态可清，视为成功不抛", () => {
     acquirePool(tmpRoot, "zcode", "ghost", "bg-1");
     // 归零但目录已被外部删除
-    rmSync(resolvePoolDir(tmpRoot, "zcode", "ghost"), { recursive: true, force: true });
+    rmSync(resolvePoolDir(tmpRoot, "zcode", "ghost"), { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     expect(() => releasePoolRef(tmpRoot, "zcode", "ghost", "bg-1")).not.toThrow();
   });
 

package/src/execution/engine/__tests__/common/session-view-service.test.ts

@@ -34,7 +34,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
-  rmSync(dataDir, { recursive: true, force: true });
+  rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   // reader registry 是进程级状态——重置回内置集，防 fake 注入跨用例泄漏
   resetNativeSessionReaders();
 });
@@ -163,7 +163,13 @@ describe("降级链编排", () => {
     });
   });
 
-  it("①级 db 不存在（真 zcode reader throw）→ ②级 journal 命中", async () => {
+  it("[W11/H1] ①级 reader 不可达（协议 read 失败降级形态）→ ②级 journal 命中", async () => {
+    // W11 后①级 reader 全经注入（生产 = runtime 协议 read，失败在其内部 catch 后
+    // 返回 undefined）：注入一个恒 undefined 的 reader 复现「协议失败降②级」语义
+    // （原「真 zcode reader 对不存在 db 内部 catch 降级」分支随 H1 内建 reader
+    // 删除，sqlite 侧行为由 zcode 包 e2e 接替；NativeSessionReader 契约 = 不抛，
+    // 失败以 undefined 表达）。
+    registerNativeSessionReader("zcode", async () => undefined);
     const journalPath = join(dataDir, "engines", "zcode", "shared", "journal-sub-1.jsonl");
     await writeJournal(journalPath, [
       { type: "text_delta", delta: "part one. " },
@@ -190,7 +196,7 @@ describe("降级链编排", () => {
   });
 
   it("②级也不可达（无 journalPath）→ ③级 outcome-only，永不返回空数组", async () => {
-    // 真 zcode reader：dbPath 指向不存在文件 → ①级 throw 降级；handle 无 journalPath → ③级
+    // ①级无注册 reader（W11 后注册表初始为空）→ 直落②级；handle 无 journalPath → ③级
     const messages = await readSubagentHistoryMessages(
       makeRecord({ result: "final answer", endedAt: 2_000 }),
       dataDir,
@@ -228,6 +234,87 @@ describe("降级链编排", () => {
     expect(messages).toHaveLength(2);
     expect(messages[1]).toMatchObject({ content: "r" });
   });
+
+  // ============================================================
+  // ①级判空降级矩阵（设计 D3：turns 无实质内容 = 本级不可用，与②级同语义）
+  // ============================================================
+
+  it("①级 defined 空 turns（{turns:[], source:'native'}）→ 降②级，journal 内容命中（不返回 [task] 空壳）", async () => {
+    const journalPath = join(dataDir, "engines", "zcode", "shared", "journal-sub-1.jsonl");
+    await writeJournal(journalPath, [
+      { type: "text_delta", delta: "journal answer" },
+      { type: "turn_end" },
+    ]);
+    registerNativeSessionReader("zcode", async () => ({
+      engineId: "zcode",
+      sessionId: "sess-1",
+      turns: [],
+      source: "native",
+    }));
+    const record = makeRecord({
+      engineHandle: {
+        sessionRef: { sessionId: "sess-1", dbPath: ".zcode/cli/db/db.sqlite" },
+        poolKey: "shared",
+        journalPath,
+      },
+    });
+    const messages = await readSubagentHistoryMessages(record, dataDir);
+    expect(messages).toHaveLength(2);
+    expect(messages[0]).toMatchObject({ role: "user", content: "do the thing" });
+    expect(messages[1]).toMatchObject({ role: "assistant", content: "journal answer" });
+  });
+
+  it("①级非空数组但全空 turn（截断/被杀残留形态）→ 同样降级：无 journalPath 落③级 outcome-only", async () => {
+    registerNativeSessionReader("zcode", async () => ({
+      engineId: "zcode",
+      sessionId: "sess-1",
+      // closeTurn 对 step-finish 无条件 push + applyPartToTurn 空 acc 创建——形态代码级可达
+      turns: [{ text: "", thinking: "", toolCalls: [], closed: true }],
+      source: "native",
+    }));
+    const messages = await readSubagentHistoryMessages(
+      makeRecord({ result: "outcome text" }),
+      dataDir,
+    );
+    // 不是「仅 task」空壳：①级空 turn 被判不可用 → ③级占位投影
+    expect(messages).toHaveLength(2);
+    expect(messages[1]).toMatchObject({ role: "assistant", content: "outcome text" });
+  });
+
+  it("①级混合 turn（含空 turn 但任一有实质内容）→ 不降级，真实内容原样投影", async () => {
+    registerNativeSessionReader("zcode", async () => ({
+      engineId: "zcode",
+      sessionId: "sess-1",
+      turns: [
+        { text: "", thinking: "", toolCalls: [], closed: true },
+        { text: "real answer", thinking: "", toolCalls: [], closed: true },
+      ],
+      source: "native",
+    }));
+    const messages = await readSubagentHistoryMessages(makeRecord(), dataDir);
+    // task + 两个 turn（空 turn 也随①级放行原样投影）
+    expect(messages).toHaveLength(3);
+    expect(messages[2]).toMatchObject({ role: "assistant", content: "real answer" });
+  });
+
+  it("①空（defined 空 turns）②亦不可达（无 journalPath）→ 落③级 outcome-only 占位", async () => {
+    registerNativeSessionReader("zcode", async () => ({
+      engineId: "zcode",
+      sessionId: "sess-1",
+      turns: [],
+      source: "native",
+    }));
+    const messages = await readSubagentHistoryMessages(
+      makeRecord({ result: undefined, error: undefined }),
+      dataDir,
+    );
+    expect(messages).toHaveLength(2);
+    expect(messages[1]).toMatchObject({
+      role: "assistant",
+      content: "(no outcome recorded)",
+      status: "complete",
+    });
+  });
 });
 
 // ============================================================