@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/engine/engines/zcode/__tests__/parser.test.ts

@@ -1,51 +1,14 @@
-// parser.test.ts —— golden 样本回归（验收 2）+ 损坏 stdout 错误路径 + 缓冲有界性。
-// golden 原文来自 2026-08-25 真机实录（zcode 0.16.5），采集元数据见 fixture _meta。
-
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
+// parser.test.ts —— usage 字段映射（事件层 execution 版）+ coarse 事件合成不变量回归。
+// 原 stdout 有界收集/终 JSON 解析/运行失败文案一族（含 golden spawn 样本回归）已随
+// CLI spawn 链删除（2026-09 单一 app-server 形态——终态来自 session-channel 收尾帧，
+// 不经 stdout 解析）；mapZcodeOutcomeUsage（终态层映射）经 zcode-engine-appserver.test.ts
+// 的 outcome.usage 断言覆盖。
 
 import { describe, expect, it } from "vitest";
 
-import {
-  buildRunFailedMessage,
-  createBoundedLineBuffer,
-  mapZcodeUsage,
-  parseZcodeStdoutJson,
-  parseZcodeTerminal,
-  synthesizeCoarseEvents,
-} from "../parser.ts";
-
-interface GoldenFixture {
-  stdoutRaw: string;
-  _meta: { engineVersion: string; exitCode: number; usageMapping: string };
-}
-
-const golden: GoldenFixture = JSON.parse(
-  readFileSync(fileURLToPath(new URL("./__fixtures__/zcode-golden-spawn.json", import.meta.url)), "utf8"),
-);
-
-describe("parseZcodeTerminal：golden 回归", () => {
-  it("实录样本解析出完整终态（sessionId/response/usage/turnCount）", () => {
-    const r = parseZcodeTerminal(golden.stdoutRaw);
-    expect(r.ok).toBe(true);
-    if (!r.ok) return;
-    expect(r.payload.sessionId).toBe("sess_35852a0f-1302-4e20-9e48-87f47527abe3");
-    expect(r.payload.response).toBe("ok");
-    expect(r.payload.usage).toEqual({ input: 12599, output: 17, cacheRead: 512, cacheWrite: 0 });
-    expect(r.payload.turnCount).toBe(1);
-    // 终态层 usage（orchestration 版）：cost 显式 0（zcode 不回传）、contextTokens=
-    // projection.contextUsed、turns=projection.turnCount
-    expect(r.payload.outcomeUsage).toEqual({
-      input: 12599,
-      output: 17,
-      cacheRead: 512,
-      cacheWrite: 0,
-      cost: 0,
-      contextTokens: 12616,
-      turns: 1,
-    });
-  });
+import { mapZcodeUsage, synthesizeCoarseEvents } from "../parser.ts";
 
+describe("mapZcodeUsage：字段名映射", () => {
   it("usage 字段名映射：inputTokens→input 等四项（cost 无来源不出现）", () => {
     const u = mapZcodeUsage({
       inputTokens: 10,
@@ -64,42 +27,6 @@ describe("parseZcodeTerminal：golden 回归", () => {
   });
 });
 
-describe("parseZcodeTerminal：损坏 stdout → ok:false（engine_run_failed 输入）", () => {
-  it("非 JSON 文本", () => {
-    const r = parseZcodeTerminal("Error: something broke\n");
-    expect(r.ok).toBe(false);
-    if (r.ok) return;
-    expect(r.reason).toContain("不是 JSON");
-  });
-
-  it("JSON 但缺 string 型 response（格式漂移形态）", () => {
-    const r = parseZcodeTerminal('{"sessionId": "sess_x", "usage": {}}');
-    expect(r.ok).toBe(false);
-    if (r.ok) return;
-    expect(r.reason).toContain("response");
-  });
-
-  it("数组/标量 JSON 拒收", () => {
-    expect(parseZcodeTerminal("[1,2,3]").ok).toBe(false);
-    expect(parseZcodeTerminal("42").ok).toBe(false);
-  });
-
-  it("混入日志行时首尾大括号容错提取", () => {
-    const mixed = '[info] boot\n{"sessionId":"sess_a","response":"done"}\n[info] exit';
-    const r = parseZcodeTerminal(mixed);
-    expect(r.ok).toBe(true);
-    if (!r.ok) return;
-    expect(r.payload.sessionId).toBe("sess_a");
-    expect(r.payload.response).toBe("done");
-  });
-});
-
-describe("parseZcodeStdoutJson：空对象形态防御", () => {
-  it("无大括号文本返回 null", () => {
-    expect(parseZcodeStdoutJson("plain text")).toBeNull();
-  });
-});
-
 describe("synthesizeCoarseEvents：coarse 不变量", () => {
   it("message_end（含 usage）在前、turn_end 最后", () => {
     const usage = { input: 1, output: 2, cacheRead: 0, cacheWrite: 0 };
@@ -114,133 +41,3 @@ describe("synthesizeCoarseEvents：coarse 不变量", () => {
     expect(evs[evs.length - 1]).toEqual({ type: "turn_end" });
   });
 });
-
-describe("buildRunFailedMessage：错误规格（stdout 尾部 + exit code + 恢复指引）", () => {
-  it("含 exit code、尾部内容与三段恢复动作", () => {
-    const msg = buildRunFailedMessage({
-      exitCode: 3,
-      stdoutTail: "x".repeat(5000),
-      stderrTail: "boom",
-      parseReason: "stdout 不是 JSON 对象",
-    });
-    expect(msg).toContain("engine_run_failed");
-    expect(msg).toContain("exit code: 3");
-    expect(msg).toContain("解析失败");
-    expect(msg).toContain("stderr 尾部: boom");
-    // stdout 尾部截断到 2000 字
-    expect(msg).toContain("x".repeat(2000));
-    expect(msg).not.toContain("x".repeat(2001));
-    expect(msg).toContain("--version");
-    expect(msg).toContain("golden");
-    expect(msg).toContain("engine: pi");
-  });
-
-  it("null exit code 标注被信号杀死", () => {
-    const msg = buildRunFailedMessage({ exitCode: null, stdoutTail: "" });
-    expect(msg).toContain("null（被信号杀死）");
-  });
-
-  it("空 stdout 不产生空 part（防「stdout 尾部: <指引段>」视觉嵌套误读）", () => {
-    const msg = buildRunFailedMessage({ exitCode: 1, stdoutTail: "   " });
-    expect(msg).not.toContain("stdout 尾部");
-  });
-
-  it("LLM API 失败（AI_APICallError）归因到端点/凭据指引，不再给 probe 指引", () => {
-    const msg = buildRunFailedMessage({
-      cliPath: "/fake/zcode.cjs",
-      exitCode: 1,
-      stdoutTail: "",
-      stderrTail: "AI_APICallError: 500 Internal Server Error\nError: Turn execution failed",
-      modelRef: "router/mimo-v2.5-pro",
-      configPath: "/pool/.zcode/cli/config.json",
-    });
-    expect(msg).toContain("模型 API 调用失败");
-    expect(msg).toContain("router/mimo-v2.5-pro");
-    expect(msg).toContain("/pool/.zcode/cli/config.json");
-    expect(msg).toContain("baseURL");
-    expect(msg).toContain("engine: pi");
-    // probe/golden 指引不出现（误导排查方向——2026-08-25 真机教训）
-    expect(msg).not.toContain("--version");
-    expect(msg).not.toContain("golden");
-    expect(msg).not.toContain("stdout 尾部");
-  });
-
-  it("401 有响应形态（无 AI_APICallError 类名）也归因，且带 HTTP 状态与凭据定向", () => {
-    const stderr401 = [
-      "  'x-mife-upstream-status': '401'",
-      "  },",
-      "  responseStatus: 401,",
-      "  statusCode: 401",
-      "}",
-      "Error: Turn execution failed (traceId: a487a9b3)",
-    ].join("\n");
-    const msg = buildRunFailedMessage({
-      cliPath: "/fake/zcode.cjs",
-      exitCode: 1,
-      stdoutTail: "",
-      stderrTail: stderr401,
-      modelRef: "router/mimo-v2.5-pro",
-      configPath: "/pool/.zcode/cli/config.json",
-    });
-    expect(msg).toContain("模型 API 调用失败");
-    expect(msg).toContain("HTTP 401");
-    expect(msg).toContain("凭据无效或过期");
-    expect(msg).toContain("apiKey 大概率无效或过期");
-    expect(msg).not.toContain("--version");
-    expect(msg).not.toContain("golden");
-  });
-
-  it("LLM 归因在缺省 modelRef/configPath 时兜底可读", () => {
-    const msg = buildRunFailedMessage({
-      cliPath: "/fake/zcode.cjs",
-      exitCode: 1,
-      stdoutTail: "ok",
-      stderrTail: "Symbol(vercel.ai.error.AI_APICallError): true",
-    });
-    expect(msg).toContain("模型 API 调用失败");
-    expect(msg).toContain("provider 的 baseURL 可达性");
-    expect(msg).not.toContain("undefined");
-  });
-
-  it("stderr 的 [Object] 噪音行折叠为计数", () => {
-    const noisy = [
-      "AIError: fail",
-      ...Array.from({ length: 12 }, () => "  [Object], [Object],"),
-      "    statusCode: undefined,",
-    ].join("\n");
-    const msg = buildRunFailedMessage({ cliPath: "/c", exitCode: 1, stdoutTail: "", stderrTail: noisy });
-    expect(msg).toContain("[Object]×12");
-    expect(msg).not.toContain("[Object], [Object]");
-  });
-});
-
-describe("createBoundedLineBuffer：有界双缓冲", () => {
-  it("头 4K + 尾 64K 保留，中间丢弃并标记", () => {
-    const buf = createBoundedLineBuffer();
-    const line = "a".repeat(100) + "\n"; // 每行 101 字节
-    for (let i = 0; i < 2000; i++) buf.push(line); // ~202KB，远超 4K+64K
-    const text = buf.text();
-    expect(text.startsWith("a".repeat(100))).toBe(true); // 头部保留
-    expect(text).toContain("已丢弃"); // 中间丢弃标记
-    expect(text.endsWith("\n")).toBe(true);
-    // 尾部窗口 ≈ 64K：总长有界
-    expect(text.length).toBeLessThan(4 * 1024 + 64 * 1024 + 200);
-  });
-
-  it("单行超整个尾部窗口时保留行尾（错误信息在末尾）", () => {
-    const buf = createBoundedLineBuffer({ headLimit: 0, tailLimit: 1000 });
-    buf.push("B".repeat(5000) + "\n");
-    const text = buf.text();
-    // 有效载荷 ≤ 1000（text 里另有「已丢弃 N 字节」标记行）
-    expect(text.match(/B/g)?.length ?? 0).toBeLessThanOrEqual(1000);
-    expect(text.endsWith("\n")).toBe(true);
-    expect(text).toContain("已丢弃");
-  });
-
-  it("未超限时原文完整（golden 646 字节场景）", () => {
-    const buf = createBoundedLineBuffer();
-    buf.push(golden.stdoutRaw);
-    expect(buf.text()).toBe(golden.stdoutRaw);
-    expect(buf.tail(10)).toBe(golden.stdoutRaw.slice(-10));
-  });
-});

package/src/execution/engine/engines/zcode/__tests__/preparer.test.ts

@@ -1,6 +1,8 @@
-// preparer.test.ts —— 池目录 SSOT / 原子写 / mtime 免重写 / 无 plugins 块 / 凭据与模型
-// 前置错误（验收 3）。凭据源 = v2 config 单源（2026-08-25 拍板：不读
-// ~/.zcode/cli/config.json——GUI 不管理该文件，可能残留历史验证配置）。
+// preparer.test.ts —— v2 单源模型解析 / 模型可发现性 / 凭据与模型前置错误。
+// 凭据源 = v2 config 单源（2026-08-25 拍板：不读 ~/.zcode/cli/config.json——GUI 不
+// 管理该文件，可能残留历史验证配置）。原 HOME 池化面（池目录 SSOT / 原子写 /
+// mtime 免重写 / 池 config 无 plugins 块）已随「共享宿主 HOME」重构删除（2026-09：
+// app-server 侧凭据经 appserver-launcher fs 拦截注入，不再建池写 config）。
 
 import * as fs from "node:fs";
 import * as os from "node:os";
@@ -8,17 +10,9 @@ import * as path from "node:path";
 
 import { beforeEach, describe, expect, it } from "vitest";
 
-import { resolvePoolDir } from "../../../paths.ts";
-import {
-  ZcodePrepareError,
-  computeZcodePoolKey,
-  listZcodeModels,
-  prepareZcodeHome,
-  resolveZcodeModelRef,
-} from "../preparer.ts";
+import { ZcodePrepareError, listZcodeModels, resolveZcodeModelRef } from "../preparer.ts";
 
 let tmpRoot: string;
-let dataDir: string;
 let v2Path: string;
 
 function writeJson(p: string, v: unknown): void {
@@ -41,7 +35,6 @@ function seedSources(): void {
 
 beforeEach(() => {
   tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "zcode-preparer-"));
-  dataDir = path.join(tmpRoot, "data");
   v2Path = path.join(tmpRoot, "v2-config.json");
   seedSources();
 });
@@ -129,100 +122,3 @@ describe("listZcodeModels（U7 可发现性）", () => {
     expect(listZcodeModels({ v2ConfigPath: path.join(tmpRoot, "absent.json") })).toEqual([]);
   });
 });
-
-describe("computeZcodePoolKey", () => {
-  it("provider 特殊字符安全化 + model 短名保留点号（zsub homePoolDir 同构）", () => {
-    expect(computeZcodePoolKey("builtin:bigmodel-coding-plan/GLM-5.3")).toBe(
-      "home-builtin-bigmodel-coding-plan-GLM-5.3",
-    );
-    expect(computeZcodePoolKey("router/mimo-v2.5-pro")).toBe("home-router-mimo-v2.5-pro");
-  });
-});
-
-describe("prepareZcodeHome（验收 3）", () => {
-  it("池目录 = resolvePoolDir SSOT，config.json 原子写且无 plugins 块", () => {
-    const prepared = prepareZcodeHome({
-      engineDataDir: dataDir,
-      modelRef: `${PROVIDER_A}/GLM-5.3`,
-      sources: { v2ConfigPath: v2Path },
-    });
-    expect(prepared.wroteConfig).toBe(true);
-    // 池目录必须与 paths.ts SSOT 同源（禁自拼）
-    expect(prepared.homeDir).toBe(resolvePoolDir(dataDir, "zcode", prepared.poolKey));
-    expect(prepared.poolKey).toBe("home-builtin-bigmodel-coding-plan-GLM-5.3");
-
-    const written = JSON.parse(fs.readFileSync(prepared.configPath, "utf8")) as Record<string, unknown>;
-    expect(written["model"]).toEqual({ main: `${PROVIDER_A}/GLM-5.3` });
-    expect(Object.keys(written["provider"] as Record<string, unknown>)).toEqual([PROVIDER_A]);
-    // 第二重门禁：刻意不写 plugins 块（防递归 + 不加载宿主插件）
-    expect("plugins" in written).toBe(false);
-    // 原子写：无 tmp 残留
-    const leftovers = fs.readdirSync(path.dirname(prepared.configPath)).filter((f) => f.includes(".tmp-"));
-    expect(leftovers).toEqual([]);
-    // 只写目标 provider（每池单 provider 单模型，凭据落盘面最小）
-    const providerEntry = (written["provider"] as Record<string, { options?: { apiKey?: string } }>)[PROVIDER_A]!;
-    expect(providerEntry.options?.apiKey).toBe("key-a");
-  });
-
-  it("mtime 比对免重写：源未变时第二次 prepare 零写入", () => {
-    const opts = {
-      engineDataDir: dataDir,
-      modelRef: `${PROVIDER_A}/GLM-5.3`,
-      sources: { v2ConfigPath: v2Path },
-    };
-    const first = prepareZcodeHome(opts);
-    expect(first.wroteConfig).toBe(true);
-    const statAfterFirst = fs.statSync(first.configPath);
-    const second = prepareZcodeHome(opts);
-    expect(second.wroteConfig).toBe(false);
-    expect(fs.statSync(second.configPath).mtimeMs).toBe(statAfterFirst.mtimeMs);
-  });
-
-  it("源 config 变新（mtime 推进）触发重写（凭据刷新传播）", async () => {
-    const opts = {
-      engineDataDir: dataDir,
-      modelRef: `${PROVIDER_A}/GLM-5.3`,
-      sources: { v2ConfigPath: v2Path },
-    };
-    prepareZcodeHome(opts);
-    // 源 mtime 推到未来（模拟桌面端刷新 apiKey）
-    const future = new Date(Date.now() + 10_000);
-    fs.utimesSync(v2Path, future, future);
-    const again = prepareZcodeHome(opts);
-    expect(again.wroteConfig).toBe(true);
-  });
-
-  it("池 config 损坏（torn write 形态）时重建", () => {
-    const opts = {
-      engineDataDir: dataDir,
-      modelRef: `${PROVIDER_A}/GLM-5.3`,
-      sources: { v2ConfigPath: v2Path },
-    };
-    const first = prepareZcodeHome(opts);
-    fs.writeFileSync(first.configPath, "{ torn", "utf8");
-    const again = prepareZcodeHome(opts);
-    expect(again.wroteConfig).toBe(true);
-    expect(() => JSON.parse(fs.readFileSync(again.configPath, "utf8"))).not.toThrow();
-  });
-
-  it("v2 注册表内非默认 provider（如自定义 UUID provider）也能建池", () => {
-    const prepared = prepareZcodeHome({
-      engineDataDir: dataDir,
-      modelRef: `${PROVIDER_B}/mimo-v2.5-pro`,
-      sources: { v2ConfigPath: v2Path },
-    });
-    const written = JSON.parse(fs.readFileSync(prepared.configPath, "utf8")) as {
-      provider: Record<string, { options?: { apiKey?: string } }>;
-    };
-    expect(written.provider[PROVIDER_B]!.options?.apiKey).toBe("key-b");
-  });
-
-  it("模型引用在 v2 不存在 → model_not_available", () => {
-    try {
-      prepareZcodeHome({ engineDataDir: dataDir, modelRef: "ghost/m", sources: { v2ConfigPath: v2Path } });
-      expect.unreachable("should throw");
-    } catch (err) {
-      expect((err as ZcodePrepareError).code).toBe("model_not_available");
-    }
-  });
-});

package/src/execution/engine/engines/zcode/__tests__/session-channel-dispose-harvest.test.ts

@@ -0,0 +1,247 @@
+// session-channel-dispose-harvest.test.ts —— P0-1 U5 dispose 前收割单测（机制层）。
+//
+// 设计权威源：docs/design/timeout-zcode-turn-and-settled-watchdog.md §3.4（退化路径）、
+// §6 D7（dispose 收割兜底）、§11 P-Z3（close 吞没 → dispose 触发 failAllTurns）。
+// P-Z3 的「close 事件吞没」在真实子进程形态不可确定性注入（Node child 进程退出后
+// stdio 关闭即触发 close 事件）——真实现场归 Gate B；本文件用 mock 连接承载机制层
+// 可判定形态：不触发 onClose（= close 吞没的机制等价物）→ dispose → 在途 turn 收敛
+// 为明确失败。与 zcode-engine-dispose.test.ts（fake-appserver 子进程集成面）互补。
+//
+// 覆盖：
+//   ① close 吞没形态：dispose 触发 failAllTurns——在途 turn 于 dispose 时收割
+//     （P-Z3 核心断言），收割后到达的终态不再改写（settled 守卫）；
+//   ② grace 窗口内全部终态化：并发多会话 turn 全量收割，不留永久 pending；
+//   ③ 正常 close 主路径零回归：onClose 收割先行 → dispose no-op 不改写收割错误；
+//   ④ 终态已落定（成功）后 dispose：settled 守卫不改写已成功结果；
+//   ⑤ dispose 收割后 closeSession 短路：runTurn finally 不再发 session/close
+//     （防写死进程/惰性重建——D7 收割语义的必要闭环）+ 正常完成对照（发 close）；
+//   ⑥ 二次 dispose 幂等。
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import type { AppServerConnection } from "../connection.ts";
+import {
+  SessionChannel,
+  type SessionTurnResult,
+  type SessionTurnOptions,
+} from "../session-channel.ts";
+
+// ============================================================
+// mock 连接 + 驱动器（与 session-channel-turn-timers.test.ts 同形态，
+// 增补 onClose handler 的手动触发面——close 吞没注入的机制等价物）
+// ============================================================
+
+interface MockChannel {
+  ch: SessionChannel;
+  /** 我方发出的请求帧流水（method 序可断言）。 */
+  requests: Array<{ method: string; params: unknown }>;
+  /** 手动触发连接崩溃广播（close 吞没形态 = 不触发；正常形态 = 测试显式触发）。 */
+  emitClose: (reason: string) => void;
+  emit: (method: string, params: unknown) => void;
+  emitTerminal: (sessionId: string | undefined, status: string) => void;
+}
+
+let sidSeq = 0;
+
+function makeMockChannel(): MockChannel {
+  const notifications = new Map<string, (params: unknown) => void>();
+  const requests: Array<{ method: string; params: unknown }> = [];
+  const closeHandlers = new Set<(reason: string) => void>();
+  const conn = {
+    alive: true,
+    onNotification: (method: string, h: (params: unknown) => void) => {
+      notifications.set(method, h);
+      return () => notifications.delete(method);
+    },
+    onClose: (h: (reason: string) => void) => {
+      closeHandlers.add(h);
+      return () => closeHandlers.delete(h);
+    },
+    request: (method: string, params: unknown) => {
+      requests.push({ method, params });
+      if (method === "session/create") {
+        sidSeq += 1;
+        return Promise.resolve({ session: { sessionId: `sess_h${sidSeq}` } });
+      }
+      if (method === "session/send") return Promise.resolve({ accepted: true });
+      if (method === "session/read") return Promise.resolve({ messages: [] });
+      return Promise.resolve({});
+    },
+  } as unknown as AppServerConnection;
+  const ch = new SessionChannel(conn);
+  return {
+    ch,
+    requests,
+    emitClose: (reason) => {
+      for (const fn of [...closeHandlers]) fn(reason);
+    },
+    emit: (method, params) => notifications.get(method)?.(params),
+    emitTerminal: (sessionId, status) =>
+      notifications
+        .get("v4/telemetry/event")
+        ?.({ kind: "turn.terminal", status, sessionId }),
+  };
+}
+
+interface TurnTracker {
+  outcome: "pending" | "fulfilled" | "rejected";
+  result: SessionTurnResult | undefined;
+  error: unknown;
+  promise: Promise<SessionTurnResult>;
+  /** onSessionCreated 回填（getter——回调晚于 tracker 构造，值拷贝会恒空）。 */
+  readonly sessionId: string;
+}
+
+function startTurn(ch: SessionChannel, opts: SessionTurnOptions = {}): TurnTracker {
+  let sessionId = "";
+  const promise = ch.runTurn({ workspacePath: "/tmp/ws-harvest", mode: "yolo" }, "任务", {
+    onSessionCreated: (sid) => {
+      sessionId = sid;
+    },
+    ...opts,
+  });
+  const t: TurnTracker = {
+    outcome: "pending",
+    result: undefined,
+    error: undefined,
+    promise,
+    get sessionId(): string {
+      return sessionId;
+    },
+  };
+  void promise.then(
+    (r) => {
+      t.outcome = "fulfilled";
+      t.result = r;
+    },
+    (e) => {
+      t.outcome = "rejected";
+      t.error = e;
+    },
+  );
+  return t;
+}
+
+/** 排空微任务链（create→subscribe→send 全是已 resolve 的 promise——一拍 setTimeout 足够）。 */
+function flush(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+async function settle(t: TurnTracker): Promise<void> {
+  await t.promise.then(
+    () => undefined,
+    () => undefined,
+  );
+}
+
+let enginesChannels: SessionChannel[] = [];
+afterEach(() => {
+  for (const ch of enginesChannels.splice(0)) ch.dispose();
+});
+
+// ============================================================
+// dispose 收割（P0-1 U5/D7：close 缺失/被吞没的退化路径闭合）
+// ============================================================
+
+describe("dispose 收割（P-Z3 机制层：close 吞没 → dispose 触发 failAllTurns）", () => {
+  it("close 吞没形态：dispose 时在途 turn 收割为明确失败，迟到终态不再改写", async () => {
+    const m = makeMockChannel();
+    enginesChannels.push(m.ch);
+    const t = startTurn(m.ch);
+    await flush();
+    expect(t.outcome).toBe("pending"); // send 已发、无终态——在途
+
+    m.ch.dispose(); // close 吞没（onClose 未触发）→ dispose 收割兜底
+    await settle(t);
+
+    expect(t.outcome).toBe("rejected");
+    const err = t.error as Error;
+    expect(err).toBeInstanceOf(Error);
+    expect(err.message).toContain("已 dispose");
+    expect(err.message).toContain("收割");
+    expect(err.message).toContain("恢复指引");
+    // 收割后到达的权威终态：settled 守卫——落定结果不改写
+    m.emitTerminal(t.sessionId, "success");
+    expect(t.outcome).toBe("rejected");
+    expect((t.error as Error).message).toBe(err.message);
+  });
+
+  it("grace 窗口内全部终态化：并发双会话 turn 全量收割，不留永久 pending", async () => {
+    const m = makeMockChannel();
+    enginesChannels.push(m.ch);
+    const t1 = startTurn(m.ch);
+    const t2 = startTurn(m.ch);
+    await flush();
+    expect(t1.sessionId).not.toBe(t2.sessionId); // 双会话确实并发
+    expect(t1.outcome).toBe("pending");
+    expect(t2.outcome).toBe("pending");
+
+    m.ch.dispose();
+    await Promise.all([settle(t1), settle(t2)]);
+
+    expect(t1.outcome).toBe("rejected");
+    expect(t2.outcome).toBe("rejected");
+    expect((t1.error as Error).message).toContain("已 dispose");
+    expect((t2.error as Error).message).toContain("已 dispose");
+  });
+
+  it("正常 close 主路径零回归：onClose 收割先行（错误=连接层 reason），dispose no-op 不改写", async () => {
+    const m = makeMockChannel();
+    enginesChannels.push(m.ch);
+    const t = startTurn(m.ch);
+    await flush();
+
+    m.emitClose("进程退出（code=0 signal=SIGTERM）"); // onClose 主路径收割（正常 close 到达）
+    await settle(t);
+    expect(t.outcome).toBe("rejected");
+    const onCloseErr = t.error as Error;
+    expect(onCloseErr.message).toContain("app-server 进程退出");
+
+    m.ch.dispose(); // activeTurns 已空——幂等 no-op，收割错误不被 dispose 文案改写
+    expect(t.outcome).toBe("rejected");
+    expect((t.error as Error).message).toBe(onCloseErr.message);
+  });
+
+  it("终态已落定（成功）后 dispose：settled 守卫不改写已成功结果", async () => {
+    const m = makeMockChannel();
+    enginesChannels.push(m.ch);
+    const t = startTurn(m.ch);
+    await flush();
+    m.emitTerminal(t.sessionId, "success");
+    await settle(t);
+    expect(t.outcome).toBe("fulfilled");
+
+    m.ch.dispose(); // 已成功收尾的 turn 不受 dispose 收割影响
+    expect(t.outcome).toBe("fulfilled");
+    expect(t.result?.terminal).toEqual({ status: "success", source: "turn.terminal" });
+  });
+
+  it("dispose 收割后 closeSession 短路：finally 不发 session/close（防写死进程/惰性重建）；正常完成对照=发 close", async () => {
+    const m1 = makeMockChannel();
+    enginesChannels.push(m1.ch);
+    const t1 = startTurn(m1.ch);
+    await flush();
+    m1.ch.dispose();
+    await settle(t1);
+    await flush(); // runTurn finally 的 closeSession 已过
+    expect(t1.outcome).toBe("rejected");
+    expect(m1.requests.map((r) => r.method)).not.toContain("session/close");
+
+    // 对照：正常完成的 turn，finally 发 session/close（D4 用后即毁——零回归面）
+    const m2 = makeMockChannel();
+    enginesChannels.push(m2.ch);
+    const t2 = startTurn(m2.ch);
+    await flush();
+    m2.emitTerminal(t2.sessionId, "success");
+    await settle(t2);
+    expect(t2.outcome).toBe("fulfilled");
+    expect(m2.requests.map((r) => r.method)).toContain("session/close");
+  });
+
+  it("二次 dispose 幂等：无在途 turn 时 dispose 是 no-op 不抛", async () => {
+    const m = makeMockChannel();
+    enginesChannels.push(m.ch);
+    expect(() => m.ch.dispose()).not.toThrow();
+    expect(() => m.ch.dispose()).not.toThrow();
+  });
+});