@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/execution/engine/engines/zcode/__tests__/zcode-engine-degrade.test.ts

@@ -1,44 +1,28 @@
-// zcode-engine-degrade.test.ts —— [R5] 降级链四步（D2）+ probe 冒烟（D8）单测。
-// 全部跑 __fixtures__/fake-appserver.mjs 子进程（scenario 注入），绝不 spawn 真
-// zcode.cjs。覆盖（impl-plan R5 验收条款 ①-④）：
-//   ① RA5-① 回归门：fixture 注入 -32602（create）/ -32601（send）→ 首任务降级
-//      spawn 重跑成功 + outcome.engineFallback 标注 degraded: spawn + 第二任务直走
-//      spawn（断言不再尝试 app-server 连接：boot/create 帧计数冻结）；
-//   ② probe 冒烟：探针连接帧序（create→close、无 send 帧——不发模型请求）、
-//      mtime 未变不重探、mtime 变化（fake 触碰）后重探、预算超时（hangCreate）失败降级、
-//      探针 create error 失败降级；
-//   ③ env 三态：缺省（探+降）/ appserver 定向（不探不降，失败直接报）/ spawn 定向
-//      （不探不降直 spawn）；
-//   ④ 错误分类表：-32603 → engine_credential_missing 不降级；-32004/-32010 →
-//      engine_run_failed 上报不降级（非漂移类）。
-// 探针/主连接区分判据：探针 env 带 ZCODE_APPSERVER_PROBE_CONN=1（fake env 快照记
-// probe 标志；探针 scenario 只读 FAKE_PROBE_SCENARIO——故障注入互不串扰）。
+// zcode-engine-degrade.test.ts —— appserver 错误分类回归门（降级链已删，仅存本主题）。
+// 2026-09 单一 app-server 形态重构删除了整条降级机制：CLI spawn 降级重跑、probe 冒烟
+// 门控、模式钉扎 env 三态均不复存在——协议漂移类错误直接上报可操作错误，不再换通道
+// 保底。原「首败漂移降级」「probe 冒烟」「env 三态」describe 随机制删除，本文件仅存
+// 错误规格表回归门：
+//   - -32603 "Model config is missing" → engine_credential_missing（共享宿主 HOME——
+//     凭据在 ZCode 桌面端管理），不换路径（第二任务仍走 app-server，create 帧计数增长）；
+//   - -32004 / -32010 → engine_run_failed 按任务失败上报（非漂移类，无 fallback 标注）。
+// 全部跑 __fixtures__/fake-appserver.mjs 子进程（scenario 注入），绝不 spawn 真 zcode.cjs。
 
-import { spawn, type ChildProcess } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { PassThrough } from "node:stream";
 import { fileURLToPath } from "node:url";
 
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import type { RunContext } from "../../../port.ts";
-import type { AgentTaskSpec } from "../../../types.ts";
-import { getLogger } from "../../../../../core/logger.ts";
-import { resolvePoolDir } from "../../../paths.ts";
-import { ZCODE_APPSERVER_GOLDEN, ZCODE_GOLDEN_STDOUT } from "../golden-sample.ts";
-import type { ZcodeLaunchedProcess } from "../launcher.ts";
-import { ZcodeEngine, pinnedZcodeMode, type ZcodeEngineDeps } from "../zcode-engine.ts";
+import type { AgentCallOpts } from "../../../../../orchestration/models/types.ts";
+import { ZCODE_APPSERVER_GOLDEN } from "../golden-sample.ts";
+import { ZcodeEngine, type ZcodeEngineDeps } from "../zcode-engine.ts";
 
 const FAKE_CLI = fileURLToPath(new URL("./__fixtures__/fake-appserver.mjs", import.meta.url));
 const PROVIDER = "test-provider";
 
-/** 与 zcode-engine.ts 同一 facade 单例引用（spy 它的方法即拦截引擎的 warn 出声）。 */
-const subagentsLogger = getLogger("subagents");
-
-const GOLDEN_SESSION_ID = "sess_golden_r3_01";
-
 const engines: ZcodeEngine[] = [];
 let seq = 0;
 let tmpRoot: string;
@@ -61,50 +45,17 @@ beforeEach(() => {
 
 afterEach(async () => {
   for (const engine of engines.splice(0)) await engine.dispose().catch(() => undefined);
-  fs.rmSync(tmpRoot, { recursive: true, force: true });
+  fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
-// ── fake launcher（降级 spawn 重跑的成功通道——golden stdout 单轮） ──
-
-function makeFakeLaunch(stdout = ZCODE_GOLDEN_STDOUT) {
-  const calls: Array<{ cliPath: string; args: string[]; env: NodeJS.ProcessEnv }> = [];
-  const launch = (o: { cliPath: string; args: string[]; env: NodeJS.ProcessEnv }): ZcodeLaunchedProcess => {
-    calls.push(o);
-    const child: ChildProcess = spawn(process.execPath, ["-e", ""]);
-    const out = new PassThrough();
-    out.end(stdout);
-    const stderr = new PassThrough();
-    stderr.end("");
-    let killed = false;
-    return {
-      child,
-      pid: 4242,
-      stdout: out,
-      stderr,
-      abort: async () => {
-        killed = true;
-      },
-      exited: Promise.resolve({ code: 0, signal: undefined }),
-      killedByUs: () => killed,
-    };
-  };
-  return { launch, calls };
-}
-
-interface DegradeScenario {
-  /** 主连接（常驻）scenario 覆盖（缺省 golden 成功形态）。 */
+interface ErrorScenario {
+  /** 主连接（常驻）scenario 覆盖：create/send 阶段错误注入。 */
   createError?: { code: number; message: string; data?: unknown };
   sendError?: { code: number; message: string; data?: unknown };
-  /** 探针 scenario（只作用于探针连接）。 */
-  probeScenario?: Record<string, unknown>;
-  /** 探针预算（缺省走 10s 常量——测试注入短值验证超时路径）。 */
-  probeBudgetMs?: number;
-  /** env 定向（XYZ_ZCODE_MODE）。 */
-  mode?: "appserver" | "spawn";
 }
 
-/** 建一个缺省（探+降）或定向模式的引擎 + 配套 launch fake。 */
-function makeDegradeEngine(s: DegradeScenario = {}) {
+/** 建一个连到 fake 的引擎（scenario 文件随 env 固化进子进程；每测试独立 state 文件）。 */
+function makeEngine(s: ErrorScenario = {}) {
   seq += 1;
   const stateFile = path.join(tmpRoot, `state-${seq}.jsonl`);
   const scenarioFile = path.join(tmpRoot, `scenario-${seq}.json`);
@@ -119,32 +70,22 @@ function makeDegradeEngine(s: DegradeScenario = {}) {
     ...(s.createError !== undefined ? { createError: s.createError } : {}),
     ...(s.sendError !== undefined ? { sendError: s.sendError } : {}),
   });
-  let probeScenarioFile: string | undefined;
-  if (s.probeScenario !== undefined) {
-    probeScenarioFile = path.join(tmpRoot, `probe-scenario-${seq}.json`);
-    writeJson(probeScenarioFile, s.probeScenario);
-  }
-  const fakeLaunch = makeFakeLaunch();
   const deps: ZcodeEngineDeps = {
     engineDataDir: () => dataDir,
     cliPath: FAKE_CLI,
     sources: { v2ConfigPath: v2Path },
     processEnv: {
       PATH: process.env.PATH ?? "",
-      ...(s.mode !== undefined ? { XYZ_ZCODE_MODE: s.mode } : {}),
       FAKE_STATE_FILE: stateFile,
       FAKE_SESSION_SCENARIO: scenarioFile,
-      ...(probeScenarioFile !== undefined ? { FAKE_PROBE_SCENARIO: probeScenarioFile } : {}),
     },
-    ...(s.probeBudgetMs !== undefined ? { probeBudgetMs: s.probeBudgetMs } : {}),
-    launch: fakeLaunch.launch as unknown as ZcodeEngineDeps["launch"],
   };
   const engine = new ZcodeEngine(deps);
   engines.push(engine);
-  return { engine, stateFile, workspace, fakeLaunch };
+  return { engine, stateFile, workspace };
 }
 
-// ── 流水读取 helpers（与 zcode-engine-appserver.test.ts 同款 + 探针判据） ──
+// ── 流水读取 helpers（与 zcode-engine-appserver.test.ts 同款） ──
 
 interface StateEvent {
   seq: number;
@@ -179,26 +120,8 @@ function recvFrames(stateFile: string, method: string): Array<{ id: number; para
     );
 }
 
-function recvMethods(stateFile: string): string[] {
-  return readState(stateFile)
-    .filter((e) => e.ev === "recv")
-    .map((e) => e.frame)
-    .filter((f): f is Record<string, unknown> => isRecord(f) && typeof f.method === "string")
-    .map((f) => f.method as string);
-}
-
-/** 探针进程 boot 数（env 快照带 probe='1'——探针连接标记）。 */
-function probeBootCount(stateFile: string): number {
-  return readState(stateFile).filter((e) => e.ev === "env" && e["probe"] === "1").length;
-}
-
-/** 全部 boot 数（探针 + 常驻主连接）。 */
-function bootCount(stateFile: string): number {
-  return readState(stateFile).filter((e) => e.ev === "boot").length;
-}
-
-function makeTask(overrides?: Partial<AgentTaskSpec>): AgentTaskSpec {
-  return { task: "做点什么", slug: "s", model: `${PROVIDER}/m1`, ...overrides };
+function makeTask(overrides?: Partial<AgentCallOpts>): AgentCallOpts {
+  return { prompt: "做点什么", description: "s", model: `${PROVIDER}/m1`, ...overrides };
 }
 
 function makeCtx(overrides?: Partial<RunContext>): RunContext {
@@ -206,257 +129,40 @@ function makeCtx(overrides?: Partial<RunContext>): RunContext {
 }
 
 // ============================================================
-// ① RA5-① 回归门：首败漂移降级（D2②）
-// ============================================================
-
-describe("首败漂移降级（RA5-① 回归门）", () => {
-  it("-32602（create 阶段）：首任务降级 spawn 重跑成功 + 标注 degraded: spawn + 第二任务直走 spawn", async () => {
-    const { engine, stateFile, workspace, fakeLaunch } = makeDegradeEngine({
-      createError: { code: -32602, message: "Invalid params", data: [{ path: ["model"] }] },
-    });
-    // 首任务：探针过（探针连接不受主 scenario 影响）→ 主连接 create -32602 → 漂移
-    // → 同一任务 spawn 重跑（fake launch golden）成功
-    const r1 = await engine.run(makeTask({ cwd: workspace }), makeCtx({ taskId: "d1" }));
-    expect(r1.outcome.error).toBeUndefined();
-    expect(r1.outcome.content).toBe("ok"); // spawn golden 单轮回复（ZCODE_GOLDEN_STDOUT）
-    expect(r1.outcome.engineFallback).toBeDefined();
-    expect(r1.outcome.engineFallback?.from).toBe("zcode:appserver");
-    expect(r1.outcome.engineFallback?.reason).toContain("degraded: spawn");
-    expect(r1.outcome.engineFallback?.reason).toContain("protocol-drift");
-    expect(r1.outcome.engineFallback?.reason).toContain("-32602");
-    expect(fakeLaunch.calls).toHaveLength(1); // 重跑走的是 spawn 通道
-    const bootsAfter1 = bootCount(stateFile);
-    const createsAfter1 = recvFrames(stateFile, "session/create").length;
-
-    // 第二任务：直走 spawn——不再尝试 app-server 连接（boot/create 帧计数冻结）
-    const r2 = await engine.run(makeTask({ cwd: workspace }), makeCtx({ taskId: "d2" }));
-    expect(r2.outcome.error).toBeUndefined();
-    expect(r2.outcome.engineFallback?.reason).toContain("degraded: spawn");
-    expect(fakeLaunch.calls).toHaveLength(2);
-    expect(bootCount(stateFile)).toBe(bootsAfter1);
-    expect(recvFrames(stateFile, "session/create").length).toBe(createsAfter1);
-  }, 20_000);
-
-  it("-32601（send 阶段）同归类：首任务漂移降级 + 后续直走 spawn", async () => {
-    const { engine, stateFile, workspace, fakeLaunch } = makeDegradeEngine({
-      sendError: { code: -32601, message: "method not found: session/send" },
-    });
-    const r1 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
-    expect(r1.outcome.error).toBeUndefined();
-    expect(r1.outcome.content).toBe("ok"); // spawn golden 单轮回复（ZCODE_GOLDEN_STDOUT）
-    expect(r1.outcome.engineFallback?.reason).toContain("-32601");
-    expect(fakeLaunch.calls).toHaveLength(1);
-    const createsAfter1 = recvFrames(stateFile, "session/create").length;
-    const r2 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
-    expect(r2.outcome.error).toBeUndefined();
-    expect(recvFrames(stateFile, "session/create").length).toBe(createsAfter1);
-    expect(fakeLaunch.calls).toHaveLength(2);
-  }, 20_000);
-
-  it("RX2-F3：ctxModel 忽略 warn 在降级链仅一次（appserver 首跑出声，spawn 重跑不重复）", async () => {
-    // task.model 缺省走 ZCODE_FALLBACK_DEFAULT_MODEL 解析链——v2 config 需含其 provider
-    writeJson(v2Path, {
-      provider: {
-        [PROVIDER]: { options: { apiKey: "k", baseURL: "https://t.example" }, models: { m1: {} } },
-        "builtin:bigmodel-coding-plan": { options: { apiKey: "k" }, models: { "GLM-5.3": {} } },
-      },
-    });
-    const { engine, fakeLaunch } = makeDegradeEngine({
-      createError: { code: -32602, message: "Invalid params", data: [{ path: ["model"] }] },
-    });
-    const warns: string[] = [];
-    const warnSpy = vi.spyOn(subagentsLogger, "warn").mockImplementation(((msg: string) => {
-      warns.push(msg);
-    }) as typeof subagentsLogger.warn);
-    let r1: Awaited<ReturnType<typeof engine.run>>;
-    try {
-      r1 = await engine.run(
-        makeTask({ model: undefined }),
-        makeCtx({ taskId: "d-ctxmodel", ctxModel: { id: "main-model", name: "Main", provider: "p", reasoning: false } }),
-      );
-    } finally {
-      warnSpy.mockRestore();
-    }
-    // 降级重跑成功（spawn golden 单轮）
-    expect(r1.outcome.error).toBeUndefined();
-    expect(fakeLaunch.calls).toHaveLength(1);
-    // 旧实现：appserver 首跑 + spawn 重跑各 warn 一次 = 同 taskId 双份相同 warn（本断言会红）
-    const ctxModelWarns = warns.filter((m) => m.includes("ctxModel"));
-    expect(ctxModelWarns).toHaveLength(1);
-    expect(ctxModelWarns[0]).toContain("main-model");
-    // 降级宣告 warn 不受抑制（漂移降级本身仍出声）
-    expect(warns.some((m) => m.includes("漂移类错误"))).toBe(true);
-  }, 20_000);
-});
-
-// ============================================================
-// ② probe 冒烟（D8：帧序 / 无模型请求 / mtime 缓存与重探 / 预算）
-// ============================================================
-
-describe("probe 冒烟（D8）", () => {
-  it("探针通过 → 走 app-server；帧序 create→close、无 send 帧（不发模型请求）；结论记 CLI mtime", async () => {
-    const { engine, stateFile, workspace, fakeLaunch } = makeDegradeEngine();
-    const r1 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
-    expect(r1.outcome.error).toBeUndefined();
-    expect(r1.outcome.sessionId).toBe(GOLDEN_SESSION_ID); // 走的是 app-server 常驻路径
-    expect(fakeLaunch.calls).toHaveLength(0);
-    // 探针连接恰好 1 个 boot，且先于常驻主连接（首帧 env 快照带 probe 标志）
-    expect(probeBootCount(stateFile)).toBe(1);
-    const envs = readState(stateFile).filter((e) => e.ev === "env");
-    expect(envs[0]?.["probe"]).toBe("1");
-    expect(envs[1]?.["probe"]).toBeUndefined();
-    // 探针帧序：探针 create（workspace=常驻 HOME）→ 探针 close，均在主连接 create 之前
-    const creates = recvFrames(stateFile, "session/create");
-    const homeDir = resolvePoolDir(dataDir, "zcode", "home-appserver");
-    expect(creates[0]?.params["workspace"]).toMatchObject({ workspacePath: homeDir });
-    const methods = recvMethods(stateFile);
-    const firstCreate = methods.indexOf("session/create");
-    const firstClose = methods.indexOf("session/close");
-    const secondCreate = methods.indexOf("session/create", firstCreate + 1);
-    expect(firstClose).toBeGreaterThan(firstCreate);
-    expect(secondCreate).toBeGreaterThan(firstClose);
-    // 不发模型请求：探针会话（首条 close 帧的 sessionId）从未出现 send 帧
-    const probeSessionId = recvFrames(stateFile, "session/close")[0]?.params["sessionId"];
-    expect(typeof probeSessionId).toBe("string");
-    expect(probeSessionId).not.toBe(GOLDEN_SESSION_ID);
-    const sendTargets = recvFrames(stateFile, "session/send").map((f) => f.params["sessionId"]);
-    expect(sendTargets).not.toContain(probeSessionId);
-  }, 20_000);
-
-  it("mtime 未变不重探：第二任务探针 boot 计数不增；mtime 变化（触碰 CLI）后重探", async () => {
-    const { engine, stateFile, workspace } = makeDegradeEngine();
-    await engine.run(makeTask({ cwd: workspace }), makeCtx());
-    await engine.run(makeTask({ cwd: workspace }), makeCtx());
-    expect(probeBootCount(stateFile)).toBe(1); // 缓存命中
-    // 触碰 CLI 伪造 zcode 升级（mtime 前移 2s——避开 fs 时间精度）
-    const now = new Date();
-    fs.utimesSync(FAKE_CLI, new Date(now.getTime() + 2000), new Date(now.getTime() + 2000));
-    const r3 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
-    expect(r3.outcome.error).toBeUndefined();
-    expect(probeBootCount(stateFile)).toBe(2); // mtime 变化 → 首个任务前重探
-  }, 20_000);
-
-  it("探针预算超时（hangCreate + 500ms 预算）→ 探针失败 → 直接 spawn + 标注 probe-failed", async () => {
-    const { engine, stateFile, workspace, fakeLaunch } = makeDegradeEngine({
-      probeScenario: { hangCreate: true },
-      probeBudgetMs: 500,
-    });
-    const started = Date.now();
-    const r1 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
-    // 500ms 预算内收割（不真等 10s 常量），随后 spawn 重跑成功
-    expect(Date.now() - started).toBeLessThan(8_000);
-    expect(r1.outcome.error).toBeUndefined();
-    expect(r1.outcome.engineFallback?.reason).toContain("probe-failed");
-    expect(r1.outcome.engineFallback?.reason).toContain("超时");
-    expect(fakeLaunch.calls).toHaveLength(1);
-    // 探针连接未发出 close（create 挂死）——但也没有任何 send 帧
-    expect(recvMethods(stateFile)).not.toContain("session/send");
-  }, 20_000);
-
-  it("探针 create error（-32602）→ 探针失败 → 直接 spawn（主连接 scenario 不受影响也未被触碰）", async () => {
-    const { engine, stateFile, workspace, fakeLaunch } = makeDegradeEngine({
-      probeScenario: { createError: { code: -32602, message: "Invalid params" } },
-    });
-    const r1 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
-    expect(r1.outcome.error).toBeUndefined();
-    expect(r1.outcome.engineFallback?.reason).toContain("probe-failed");
-    expect(fakeLaunch.calls).toHaveLength(1);
-    // 探针失败短路：常驻主连接从未建立（boot 全部来自探针）
-    expect(bootCount(stateFile)).toBe(probeBootCount(stateFile));
-    // 失败结论同样绑 mtime 缓存（smokeConclusion 缓存命中不分成败）：同一 CLI mtime 下
-    // 第二任务不重探（探针 boot 冻结）且仍直走 spawn，不再触碰主连接
-    const probeBootsAfter1 = probeBootCount(stateFile);
-    const bootsAfter1 = bootCount(stateFile);
-    const r2 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
-    expect(r2.outcome.error).toBeUndefined();
-    expect(r2.outcome.engineFallback?.reason).toContain("probe-failed");
-    expect(fakeLaunch.calls).toHaveLength(2);
-    expect(probeBootCount(stateFile)).toBe(probeBootsAfter1);
-    expect(bootCount(stateFile)).toBe(bootsAfter1);
-  }, 20_000);
-});
-
-// ============================================================
-// ③ env 三态（D2④ 定向不探不降）
-// ============================================================
-
-describe("env 三态（XYZ_ZCODE_MODE）", () => {
-  it("pinnedZcodeMode 三态判定：定向值原样 / 缺省与未知值 undefined", () => {
-    expect(pinnedZcodeMode({ XYZ_ZCODE_MODE: "spawn" })).toBe("spawn");
-    expect(pinnedZcodeMode({ XYZ_ZCODE_MODE: "appserver" })).toBe("appserver");
-    expect(pinnedZcodeMode({})).toBeUndefined();
-    expect(pinnedZcodeMode({ XYZ_ZCODE_MODE: "garbage" })).toBeUndefined();
-  });
-
-  it("appserver 定向：不探（探针 boot 0）不降（-32602 直接上报，spawn 通道不启用）", async () => {
-    const { engine, stateFile, workspace, fakeLaunch } = makeDegradeEngine({
-      mode: "appserver",
-      createError: { code: -32602, message: "Invalid params" },
-    });
-    const r1 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
-    expect(r1.outcome.error).toContain("engine_run_failed");
-    expect(r1.outcome.error).toContain("-32602");
-    expect(r1.outcome.engineFallback).toBeUndefined(); // 不降级 → 无标注
-    expect(fakeLaunch.calls).toHaveLength(0);
-    expect(probeBootCount(stateFile)).toBe(0);
-    // 定向持续失败直接报：第二任务仍走 app-server（create 计数增长，非降级冻结）
-    const createsBefore = recvFrames(stateFile, "session/create").length;
-    const r2 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
-    expect(r2.outcome.error).toContain("-32602");
-    expect(recvFrames(stateFile, "session/create").length).toBeGreaterThan(createsBefore);
-    expect(fakeLaunch.calls).toHaveLength(0);
-  }, 20_000);
-
-  it("spawn 定向：不探不降直 spawn（零 app-server boot、零协议帧）", async () => {
-    const { engine, stateFile, workspace, fakeLaunch } = makeDegradeEngine({ mode: "spawn" });
-    const r1 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
-    expect(r1.outcome.error).toBeUndefined();
-    expect(r1.outcome.engineFallback).toBeUndefined();
-    expect(fakeLaunch.calls).toHaveLength(1);
-    expect(bootCount(stateFile)).toBe(0);
-    expect(readState(stateFile).filter((e) => e.ev === "recv")).toHaveLength(0);
-  }, 15_000);
-});
-
-// ============================================================
-// ④ 错误分类表（非漂移类：-32603 / -32004 / -32010 不降级）
+// 错误分类表（非漂移类：-32603 / -32004 / -32010 不降级）
 // ============================================================
 
 describe("错误分类（错误规格表）", () => {
   it("-32603 'Model config is missing' → engine_credential_missing，不降级（第二任务仍走 app-server）", async () => {
-    const { engine, stateFile, workspace, fakeLaunch } = makeDegradeEngine({
+    const { engine, stateFile, workspace } = makeEngine({
       createError: { code: -32603, message: "Model config is missing" },
     });
     const r1 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
     expect(r1.outcome.error).toContain("engine_credential_missing");
     expect(r1.outcome.engineFallback).toBeUndefined();
-    expect(fakeLaunch.calls).toHaveLength(0);
     const createsBefore = recvFrames(stateFile, "session/create").length;
     const r2 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
     expect(r2.outcome.error).toContain("engine_credential_missing");
     expect(recvFrames(stateFile, "session/create").length).toBeGreaterThan(createsBefore);
-    expect(fakeLaunch.calls).toHaveLength(0);
   }, 20_000);
 
   it("-32004 'Session is not active' → 任务失败上报，不降级", async () => {
-    const { engine, workspace, fakeLaunch } = makeDegradeEngine({
+    const { engine, workspace } = makeEngine({
       createError: { code: -32004, message: "Session is not active" },
     });
     const r1 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
     expect(r1.outcome.error).toContain("engine_run_failed");
     expect(r1.outcome.error).toContain("-32004");
     expect(r1.outcome.engineFallback).toBeUndefined();
-    expect(fakeLaunch.calls).toHaveLength(0);
   }, 20_000);
 
   it("-32010（send busy）→ 任务失败上报，不降级", async () => {
-    const { engine, workspace, fakeLaunch } = makeDegradeEngine({
+    const { engine, workspace } = makeEngine({
       sendError: { code: -32010, message: "A turn is already running" },
     });
     const r1 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
     expect(r1.outcome.error).toContain("engine_run_failed");
     expect(r1.outcome.error).toContain("-32010");
     expect(r1.outcome.engineFallback).toBeUndefined();
-    expect(fakeLaunch.calls).toHaveLength(0);
   }, 20_000);
 });

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

@@ -0,0 +1,210 @@
+// zcode-engine-dispose.test.ts —— P0-1 U5 dispose 收割（引擎集成面，fake-appserver
+// 子进程，绝不 spawn 真 zcode.cjs）。
+//
+// 设计权威源：docs/design/timeout-zcode-turn-and-settled-watchdog.md §3.4（退化
+// 路径）、§6 D7（dispose 收割兜底）、§11 P-Z3。真实现场（真实环境的 close 吞没）
+// 归 Gate B；本文件验证引擎层可注入的集成行为：
+//   ① dispose 时在途 turn 收敛为明确失败（不挂满 turn 预算）且不触发重试轮
+//     （u-z4 disposed 标志衔接：收割 ≠ 瞬时崩溃——boot 1 / create×1 机械证据）；
+//   ② dispose 全链窗口 = HARVEST_GRACE 量级（与 awaitConnFinalized 同源常量——
+//     行为耗时断言 + 源码常量同源静态断言）。
+// channel 层 close 吞没形态的机制断言在 session-channel-dispose-harvest.test.ts
+// （mock 连接——真实子进程形态下 Node close 事件不可吞没，P-Z3 真实现场归 Gate B）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { EngineRunResult, RunContext } from "../../../port.ts";
+import type { AgentCallOpts } from "../../../../../orchestration/models/types.ts";
+import {
+  ZCODE_APPSERVER_HARVEST_GRACE_MS,
+  ZCODE_KILL_GRACE_MS,
+} from "../constants.ts";
+import { ZCODE_APPSERVER_GOLDEN } from "../golden-sample.ts";
+import { ZcodeEngine, type ZcodeEngineDeps } from "../zcode-engine.ts";
+
+const FAKE_CLI = fileURLToPath(new URL("./__fixtures__/fake-appserver.mjs", import.meta.url));
+const PROVIDER = "test-provider";
+
+const GOLDEN_SESSION_ID = "sess_golden_r3_01";
+/** 挂起场景：send 后零推送——turn 无事件无终态（dispose 收割的形态前提）。 */
+const HANG_PUSHES: string[] = [];
+
+const engines: ZcodeEngine[] = [];
+let seq = 0;
+let tmpRoot: string;
+let dataDir: string;
+let v2Path: string;
+
+function writeJson(p: string, v: unknown): void {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(v, null, 2));
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "zcode-eng-dispose-"));
+  dataDir = path.join(tmpRoot, "data");
+  v2Path = path.join(tmpRoot, "v2.json");
+  writeJson(v2Path, {
+    provider: { [PROVIDER]: { options: { apiKey: "k", baseURL: "https://t.example" }, models: { m1: {} } } },
+  });
+});
+
+afterEach(async () => {
+  vi.unstubAllEnvs();
+  for (const engine of engines.splice(0)) await engine.dispose().catch(() => undefined);
+  fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+});
+
+interface EngineFixture {
+  engine: ZcodeEngine;
+  stateFile: string;
+  scenarioFile: string;
+  workspace: string;
+}
+
+function makeEngine(): EngineFixture {
+  seq += 1;
+  const stateFile = path.join(tmpRoot, `state-${seq}.jsonl`);
+  const scenarioFile = path.join(tmpRoot, `scenario-${seq}.json`);
+  const workspace = path.join(tmpRoot, `ws-${seq}`);
+  writeJson(scenarioFile, {
+    createResult: JSON.parse(ZCODE_APPSERVER_GOLDEN.createResponse),
+    readResult: JSON.parse(ZCODE_APPSERVER_GOLDEN.readResponse),
+    sendPushes: HANG_PUSHES.map((l) => JSON.parse(l) as Record<string, unknown>),
+  });
+  const deps: ZcodeEngineDeps = {
+    engineDataDir: () => dataDir,
+    cliPath: FAKE_CLI,
+    sources: { v2ConfigPath: v2Path },
+    processEnv: {
+      PATH: process.env.PATH ?? "",
+      XYZ_ZCODE_MODE: "appserver",
+      FAKE_STATE_FILE: stateFile,
+      FAKE_SESSION_SCENARIO: scenarioFile,
+    },
+  };
+  const engine = new ZcodeEngine(deps);
+  engines.push(engine);
+  return { engine, stateFile, scenarioFile, workspace };
+}
+
+// ── 流水读取 helpers（与 zcode-engine-timeout.test.ts 同款） ──
+
+interface StateEvent {
+  seq: number;
+  ev: string;
+  [key: string]: unknown;
+}
+
+function readState(file: string): StateEvent[] {
+  try {
+    return fs
+      .readFileSync(file, "utf8")
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l) as StateEvent);
+  } catch {
+    return [];
+  }
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function sentMethods(stateFile: string): string[] {
+  return readState(stateFile)
+    .map((e) => e.frame)
+    .filter((f): f is Record<string, unknown> => isRecord(f) && typeof f.method === "string")
+    .map((f) => f.method as string);
+}
+
+function bootCount(stateFile: string): number {
+  return readState(stateFile).filter((e) => e.ev === "boot").length;
+}
+
+/** 轮询流水直到指定 method 出现（在途 turn 已挂的同步点；超时抛错防静默空转）。 */
+async function waitForMethod(stateFile: string, method: string, timeoutMs = 5000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (sentMethods(stateFile).includes(method)) return;
+    await new Promise((r) => setTimeout(r, 20));
+  }
+  throw new Error(`流水 ${timeoutMs}ms 内未出现 ${method}——在途 turn 未建立`);
+}
+
+function makeTask(overrides?: Partial<AgentCallOpts>): AgentCallOpts {
+  return { prompt: "做点什么", description: "s", model: `${PROVIDER}/m1`, ...overrides };
+}
+
+function makeCtx(overrides?: Partial<RunContext>): RunContext {
+  return { taskId: "sa-dispose", poolKey: "", ...overrides };
+}
+
+// ============================================================
+// dispose 收割（P0-1 U5/D7：在途 turn 收敛 + 不重试 + 窗口量级）
+// ============================================================
+
+describe("dispose 收割（P0-1 U5：引擎集成面）", () => {
+  it("dispose 时在途 turn 收敛为明确失败且不重试：engine_run_failed、boot 1、create×1（收割≠瞬时崩溃，u-z4 disposed 短路）", async () => {
+    // 两 timer 显式关闭（规则 19 opt-out 形态）——排除 timeout 判死路径，
+    // 本用例的失败终态只能来自 dispose 收割链（onClose failAllTurns → dispose
+    // no-op 幂等；close 吞没变体由 channel 层 mock 测试承载）
+    vi.stubEnv("XYZ_ZCODE_TURN_IDLE_TIMEOUT_MS", "0");
+    vi.stubEnv("XYZ_ZCODE_TURN_MAX_TIMEOUT_MS", "0");
+    const f = makeEngine();
+    const runPromise: Promise<EngineRunResult> = f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    await waitForMethod(f.stateFile, "session/send"); // 在途 turn 已建立
+
+    const disposeStartedAt = Date.now();
+    await f.engine.dispose();
+    const disposeMs = Date.now() - disposeStartedAt;
+
+    // run promise 在 dispose 窗口内落定（收割生效的结构性证据——5s 保护超时）
+    const r = await Promise.race([
+      runPromise,
+      new Promise<never>((_, rej) =>
+        setTimeout(() => rej(new Error("run promise 未在 dispose 后 5s 内落定——收割未生效")), 5000),
+      ),
+    ]);
+    expect(r.outcome.error).toMatch(/^engine_run_failed:/);
+    // 收割错误带连接层崩溃 reason（close 正常到达形态：onClose 主路径先收割）
+    expect(r.outcome.error).toContain("进程退出");
+
+    // 收割 ≠ 瞬时崩溃：无重试轮、无惰性重建（boot 1 / create×1 机械证据）
+    const methods = sentMethods(f.stateFile);
+    expect(methods.filter((m) => m === "session/create").length).toBe(1);
+    expect(bootCount(f.stateFile)).toBe(1);
+
+    // 窗口量级：dispose 全链不超 kill 链 + HARVEST_GRACE + 进程调度余量——
+    // 收割在 grace 量级窗口闭合，而非挂满 turn 预算（30min/60min 量级差异）
+    expect(disposeMs).toBeLessThan(ZCODE_KILL_GRACE_MS + ZCODE_APPSERVER_HARVEST_GRACE_MS + 2000);
+  }, 30_000);
+
+  it("grace 窗口量级一致性：dispose 收割 race 窗口与 awaitConnFinalized 同源 ZCODE_APPSERVER_HARVEST_GRACE_MS（验收⑤静态断言）", async () => {
+    const engineSrc = fs.readFileSync(
+      fileURLToPath(new URL("../zcode-engine.ts", import.meta.url)),
+      "utf8",
+    );
+    // awaitConnFinalized：close 永不到达时同量级兜底（u-z2 先例）
+    expect(engineSrc).toContain("setTimeout(() => finish(), ZCODE_APPSERVER_HARVEST_GRACE_MS)");
+    // shutdownRuntimeAndDisposeChannel：dispose 收割 race 窗口（本单元挂接点）
+    expect(engineSrc).toContain("delayResolved(ZCODE_APPSERVER_HARVEST_GRACE_MS");
+    // channel dispose 收割本体是同步操作（无自有 timer）——窗口归引擎 race 单点
+    const channelSrc = fs.readFileSync(
+      fileURLToPath(new URL("../session-channel.ts", import.meta.url)),
+      "utf8",
+    );
+    const disposeBody = channelSrc.slice(
+      channelSrc.indexOf("  dispose(): void {"),
+      channelSrc.indexOf("  /** 连接死亡收割"),
+    );
+    expect(disposeBody).not.toContain("setTimeout");
+  });
+});