@zhushanwen/subagent-core 0.2.0 → 0.5.1

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

@@ -0,0 +1,353 @@
+// zcode-engine-retry.test.ts —— [P0-1 U4/D6] 瞬时失败自动重试一次 + 预算继承测试
+// （设计权威源 docs/design/timeout-zcode-turn-and-settled-watchdog.md §6 D6、§5.2
+// F-1/F-4、§10 U4、§11 P-Z4）。全部跑 __fixtures__/fake-appserver.mjs 子进程
+// （scenario 注入；crashAfterSendMs 为 U4 扩展的崩溃收割注入通道），绝不 spawn 真
+// zcode.cjs。覆盖：
+//   - 预算继承纯函数（P-Z4「显式预算下重试轮不重置总预算」的数学本体）：剩余 =
+//     总预算 − 已耗尽的精确断言 + 下限门禁 + 非显式 unbounded；
+//   - 重试一次成功（连接崩溃形态）：crash → failAllTurns 收割 → 新会话重跑（进程
+//     死后惰性重建 + scenario 切换）→ 自然终态；
+//   - 重试仍失败两形态各一（超时族 / 连接崩溃族）：文案补「已自动重试一次」句
+//     （u-z2 留的 F-1 补句义务），连接崩溃族 boot 2 证据；
+//   - 不可重试形态不重试：RPC 错误（-32004/-32601 漂移）/ status=error 终态（D6
+//     被否③）/ 用户取消（aborted 短路）——各 create×1 无补句；
+//   - 显式预算 vs 默认配置行为差异（P-Z4 门禁集成面）：显式预算剩余充足 → 重试；
+//     剩余不足下限 → depleted 不重试；env ≤0 显式关闭上界 → unbounded 重试不受
+//     门禁（与 channel resolveTurnTimerMs 同一 env 通道，vi.stubEnv 缩短量级——
+//     真实默认 60min/300s 下限不在单测等待范围）。
+// 集成层无法在真实等待范围内让重试轮 fire 收窄后的上界（剩余 ≈ 300s 量级），「重试
+// 轮上界=剩余」的数值精确断言由纯函数层承载（turnTimeoutMs 传递链路的集成行为由
+// F1 用例的重试成功佐证）——分层等价，偏差已登记。
+
+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_GOLDEN } from "../golden-sample.ts";
+import {
+  ZcodeEngine,
+  ZCODE_TURN_RETRY_MIN_BUDGET_MS,
+  resolveTransientRetryBudget,
+  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_FULL_TEXT = "你好，任务完成";
+/** 挂起场景：send 后零推送——turn 在途等待（crash 收割 / idle 判死的注入底座）。 */
+const HANG_PUSHES: string[] = [];
+/** 权威终态 turn.terminal 的 error 帧（status='error' 终态——D6 被否③的不可重试形态）。 */
+const TERMINAL_ERROR_FRAME =
+  '{"method":"v4/telemetry/event","params":{"kind":"turn.terminal","status":"error"}}';
+
+let 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-retry-"));
+  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 RpcErrorSpec {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+interface ScenarioOverrides {
+  replaceSendPushes?: string[];
+  stopBehavior?: "terminal" | "none" | "hang";
+  sendError?: RpcErrorSpec;
+  /** send 应答后 N ms 自杀（U4 扩展通道——连接崩溃收割注入）。 */
+  crashAfterSendMs?: number;
+  /** 非首代（崩溃后惰性重建代）send 的推送序列——重试轮的不同行为通道（U4）。 */
+  rebootSendPushes?: string[];
+}
+
+interface EngineFixture {
+  engine: ZcodeEngine;
+  stateFile: string;
+  workspace: string;
+  /** 重写 scenario（新 fake 进程启动时重读——崩溃重建轮的形态切换通道）。 */
+  rewriteScenario: (overrides: ScenarioOverrides) => void;
+}
+
+function makeEngine(overrides: ScenarioOverrides = {}): 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}`);
+  const write = (o: ScenarioOverrides): void => {
+    writeJson(scenarioFile, {
+      createResult: JSON.parse(ZCODE_APPSERVER_GOLDEN.createResponse),
+      readResult: JSON.parse(ZCODE_APPSERVER_GOLDEN.readResponse),
+      sendPushes: (o.replaceSendPushes ?? HANG_PUSHES).map((l) => JSON.parse(l) as Record<string, unknown>),
+      ...(o.stopBehavior !== undefined ? { stopBehavior: o.stopBehavior } : {}),
+      ...(o.sendError !== undefined ? { sendError: o.sendError } : {}),
+      ...(o.crashAfterSendMs !== undefined ? { crashAfterSendMs: o.crashAfterSendMs } : {}),
+      ...(o.rebootSendPushes !== undefined
+        ? { rebootSendPushes: o.rebootSendPushes.map((l) => JSON.parse(l) as Record<string, unknown>) }
+        : {}),
+    });
+  };
+  write(overrides);
+  const deps: ZcodeEngineDeps = {
+    engineDataDir: () => dataDir,
+    cliPath: FAKE_CLI,
+    sources: { v2ConfigPath: v2Path },
+    processEnv: {
+      PATH: process.env.PATH ?? "",
+      // 钉扎 appserver 定向（定向不探不降）；turn 阈值走全局 env stub（session-channel
+      // 的 resolveTurnTimerMs 与引擎预算门禁都直读 process.env——D2 env 通道）
+      XYZ_ZCODE_MODE: "appserver",
+      FAKE_STATE_FILE: stateFile,
+      FAKE_SESSION_SCENARIO: scenarioFile,
+    },
+  };
+  const engine = new ZcodeEngine(deps);
+  engines.push(engine);
+  return {
+    engine,
+    stateFile,
+    workspace,
+    rewriteScenario: (o) => write(o),
+  };
+}
+
+// ── 流水读取 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 createCount(stateFile: string): number {
+  return sentMethods(stateFile).filter((m) => m === "session/create").length;
+}
+
+function bootCount(stateFile: string): number {
+  return readState(stateFile).filter((e) => e.ev === "boot").length;
+}
+
+function makeTask(overrides?: Partial<AgentCallOpts>): AgentCallOpts {
+  return { prompt: "做点什么", description: "s", model: `${PROVIDER}/m1`, ...overrides };
+}
+
+function makeCtx(overrides?: Partial<RunContext>): RunContext {
+  return { taskId: "sa-retry", poolKey: "", ...overrides };
+}
+
+// ============================================================
+// 预算继承纯函数（P-Z4 数学本体：剩余 = 总预算 − 已耗尽，不重置）
+// ============================================================
+
+describe("resolveTransientRetryBudget（P-Z4：显式预算下重试轮不重置总预算）", () => {
+  it("显式预算下剩余 = 总预算 − 已耗尽（精确数值，重试轮上界=剩余）", () => {
+    expect(resolveTransientRetryBudget(3_600_000, 1_800_000)).toEqual({ state: "inherit", remainingMs: 1_800_000 });
+    expect(resolveTransientRetryBudget(400_000, 100_000)).toEqual({ state: "inherit", remainingMs: 300_000 });
+  });
+
+  it("剩余恰为下限 → inherit（边界含）；剩余低于下限 → depleted（不重试直接终态化）", () => {
+    expect(resolveTransientRetryBudget(ZCODE_TURN_RETRY_MIN_BUDGET_MS, 0)).toEqual({
+      state: "inherit",
+      remainingMs: ZCODE_TURN_RETRY_MIN_BUDGET_MS,
+    });
+    expect(resolveTransientRetryBudget(360_000, 300_000)).toEqual({ state: "depleted" });
+  });
+
+  it("非显式预算（env 未设/非法回落/≤0 显式关闭）→ unbounded（无总预算面，重试不受门禁）", () => {
+    expect(resolveTransientRetryBudget(undefined, 0)).toEqual({ state: "unbounded" });
+    expect(resolveTransientRetryBudget(undefined, 999_999)).toEqual({ state: "unbounded" });
+  });
+});
+
+// ============================================================
+// 集成：重试一次成功（连接崩溃形态，D6/F-4 主路径）
+// ============================================================
+
+describe("瞬时失败自动重试一次（P0-1 U4：新会话重跑）", () => {
+  it("连接崩溃 → 重试轮新会话重跑成功：boot 2（惰性重建）+ create×2 + 自然终态（默认配置，无显式预算）", async () => {
+    // 首代 hang + crash（收割 conn-closed）；重建代（重试轮）走完整 golden 流自然终态
+    // ——run 整体 await 无法经 rewriteScenario 插手重试轮，rebootSendPushes 是代感知通道
+    const f = makeEngine({
+      crashAfterSendMs: 120,
+      rebootSendPushes: [...ZCODE_APPSERVER_GOLDEN.pushStream, ...ZCODE_APPSERVER_GOLDEN.terminal],
+    });
+    const r: EngineRunResult = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toBeUndefined();
+    expect(r.outcome.content).toBe(GOLDEN_FULL_TEXT);
+    expect(r.outcome.exitCode).toBe(0);
+    // 机械证据：崩溃 boot 1 + 重试轮惰性重建 boot 2；首轮 + 重试轮各自 create 新会话
+    expect(bootCount(f.stateFile)).toBe(2);
+    expect(createCount(f.stateFile)).toBe(2);
+  }, 20_000);
+
+  it("重试仍失败·超时族：文案补「已自动重试一次仍超时」句（F-1 补句义务），进程不杀（boot 1）", async () => {
+    vi.stubEnv("XYZ_ZCODE_TURN_IDLE_TIMEOUT_MS", "300");
+    const f = makeEngine(); // hang + stopBehavior 缺省 terminal（两轮止损链都 stop-acked）
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toMatch(/^engine_timeout:/);
+    // u-z2 留的补句义务：仅重试真实发生后出现（F-1 样例句逐字）
+    expect(r.outcome.error).toContain("已自动重试一次仍超时");
+    expect(r.outcome.error).toContain("重试在止损链终局后启动，无新旧任务双跑窗");
+    // 重试轮同样走止损链（stop 已送达）+ 停止损不杀共享进程（boot 1）
+    expect(r.outcome.error).toContain("session/stop 已送达");
+    expect(bootCount(f.stateFile)).toBe(1);
+    expect(createCount(f.stateFile)).toBe(2);
+  }, 20_000);
+
+  it("重试仍失败·连接崩溃族：重建轮再崩溃 → 文案补「已自动重试一次仍失败」句（F-4 已重试 1 次）", async () => {
+    const f = makeEngine({ crashAfterSendMs: 120 }); // scenario 固定 crash——重建轮同样崩溃
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toMatch(/^engine_run_failed: app-server 会话执行失败/);
+    expect(r.outcome.error).toContain("已自动重试一次仍失败");
+    // 一次封顶：首轮 + 重试轮共两次会话、两代进程（崩溃自动重建），不再第三轮
+    expect(createCount(f.stateFile)).toBe(2);
+    expect(bootCount(f.stateFile)).toBe(2);
+  }, 20_000);
+});
+
+// ============================================================
+// 不可重试形态不重试（D6 被否谱系 + 形态排除）
+// ============================================================
+
+describe("不可重试形态不重试（一次会话收口，无补句）", () => {
+  it("RPC 错误（-32004 busy）：非瞬时形态 → 不重试（create×1）", async () => {
+    const f = makeEngine({ sendError: { code: -32004, message: "Session is busy" } });
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toContain("-32004");
+    expect(r.outcome.error).not.toContain("已自动重试");
+    expect(createCount(f.stateFile)).toBe(1);
+    expect(bootCount(f.stateFile)).toBe(1);
+  }, 15_000);
+
+  it("漂移码（-32601）：R5 降级链专属语义，不进瞬时重试（D6 被否②）", async () => {
+    const f = makeEngine({ sendError: { code: -32601, message: "method not found" } });
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toContain("-32601");
+    expect(r.outcome.error).not.toContain("已自动重试");
+    expect(createCount(f.stateFile)).toBe(1);
+  }, 15_000);
+
+  it("status='error' 终态：D6 被否③（错误内容可能非瞬时）→ 不重试（create×1）", async () => {
+    const f = makeEngine({ replaceSendPushes: [TERMINAL_ERROR_FRAME] });
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toMatch(/^engine_run_failed: app-server 终态 status=error/);
+    expect(r.outcome.error).not.toContain("已自动重试");
+    expect(createCount(f.stateFile)).toBe(1);
+    expect(bootCount(f.stateFile)).toBe(1);
+  }, 15_000);
+
+  it("用户取消（turn 在途时 abort）：aborted 短路优先 → 不重试（create×1）", async () => {
+    vi.stubEnv("XYZ_ZCODE_TURN_IDLE_TIMEOUT_MS", "5000");
+    const f = makeEngine(); // hang + stopBehavior terminal（stop 优雅生效 → aborted 收口）
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 80);
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx({ signal: controller.signal }));
+    // 用户取消入口现状语义零改动（U2）：engine_run_failed 中止标记（非超时语义）
+    expect(r.outcome.error).toContain("被中止");
+    expect(r.outcome.error).not.toContain("已自动重试");
+    expect(createCount(f.stateFile)).toBe(1);
+  }, 15_000);
+});
+
+// ============================================================
+// 显式预算 vs 默认配置（P-Z4 门禁集成面）
+// ============================================================
+
+describe("显式预算门禁与默认配置的行为差异（P-Z4 集成面）", () => {
+  it("显式预算剩余充足（310s > 300s 下限 + 首轮消耗）→ 重试发生：boot 2 + create×2 + 自然终态", async () => {
+    vi.stubEnv("XYZ_ZCODE_TURN_MAX_TIMEOUT_MS", "310000");
+    const f = makeEngine({
+      crashAfterSendMs: 120,
+      rebootSendPushes: [...ZCODE_APPSERVER_GOLDEN.pushStream, ...ZCODE_APPSERVER_GOLDEN.terminal],
+    });
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    // 重试未被预算门禁拦截（剩余 ≥ 下限），重试轮成功收口
+    expect(r.outcome.error).toBeUndefined();
+    expect(r.outcome.content).toBe(GOLDEN_FULL_TEXT);
+    expect(bootCount(f.stateFile)).toBe(2);
+    expect(createCount(f.stateFile)).toBe(2);
+  }, 20_000);
+
+  it("显式预算剩余不足下限（60s − 消耗 < 300s）→ depleted 不重试：boot 1 + create×1 + 无补句", async () => {
+    vi.stubEnv("XYZ_ZCODE_TURN_MAX_TIMEOUT_MS", "60000");
+    const f = makeEngine({ crashAfterSendMs: 120 }); // scenario 固定 crash（无重试即不重建）
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toMatch(/^engine_run_failed: app-server 会话执行失败/);
+    expect(r.outcome.error).not.toContain("已自动重试");
+    expect(createCount(f.stateFile)).toBe(1);
+    expect(bootCount(f.stateFile)).toBe(1);
+  }, 15_000);
+
+  it("env ≤0 显式关闭总上界 → 无显式预算（unbounded）→ 重试不受门禁：boot 2 证据", async () => {
+    vi.stubEnv("XYZ_ZCODE_TURN_MAX_TIMEOUT_MS", "0");
+    const f = makeEngine({ crashAfterSendMs: 120 }); // scenario 固定 crash——重试轮同样崩溃
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toContain("已自动重试一次仍失败");
+    expect(createCount(f.stateFile)).toBe(2);
+    expect(bootCount(f.stateFile)).toBe(2);
+  }, 20_000);
+
+  it("超时族 + 预算门禁拦截（depleted）→ 未重试：engine_timeout 文案不含补句（补句仅随真实重试，F-1 一致性）", async () => {
+    vi.stubEnv("XYZ_ZCODE_TURN_IDLE_TIMEOUT_MS", "300");
+    vi.stubEnv("XYZ_ZCODE_TURN_MAX_TIMEOUT_MS", "60000"); // 剩余 60s − 首轮消耗 < 300s 下限
+    const f = makeEngine(); // hang + stop terminal（首轮 idle 判死 → timeout 形态）
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toMatch(/^engine_timeout:/);
+    expect(r.outcome.error).toContain("idle 判定");
+    // 目标 3 的反面断言：未重试形态不含「已自动重试」句（与行为一致）
+    expect(r.outcome.error).not.toContain("已自动重试");
+    expect(createCount(f.stateFile)).toBe(1);
+    expect(bootCount(f.stateFile)).toBe(1);
+  }, 15_000);
+});

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

@@ -0,0 +1,282 @@
+// zcode-engine-status.test.ts —— [P0-1 U3] 引擎终态 status 消费测试（设计权威源
+// docs/design/timeout-zcode-turn-and-settled-watchdog.md §6 D5、§5.2 F-3、§8 A4；
+// ⛔P-Z2 门修正：真实 status 枚举 = ["success","interrupted","failed"]（app-server
+// dist schema f.enum 实证，无 "error"）——判据 failed 主 + error 容错，v1 的
+// `=== "error"` 对真实 failed 终态漏分流即假成功（探针 /tmp/pz2-probe 实锤）。
+// 覆盖：
+//   - status:'failed'（真实帧形，errorCode/errorMessage 携带）→ run-failed 且错误
+//     详情来自 terminal 帧（errorCode/errorMessage 优先——真实形态错误详情只在
+//     terminal 帧，read/delta 携带不了；read 尾部为兜底）：
+//     ① 帧序 A：turn.terminal failed 先到（权威 settle）；
+//     ② 帧序 B：final-frame 宽松 settle success 先到 + turn.terminal failed 迟到
+//        （u-z1 lastTerminalStatus/lastTerminalError 衔接——只记录不改写落定）；
+//   - P-Z2 降级形态：failed 无 errorCode/errorMessage + read 无错误信息 → 仍
+//     run-failed 不假成功（read/finalText 尾部兜底）；
+//   - 全空形态（无 delta/收尾帧/read 内容）→ 不伪造错误详情；
+//   - status:'interrupted'（真实枚举成员）→ 不误判失败（用户中断不属引擎失败，
+//     随宿主 abort 主路径——落定语义登记）；
+//   - status:'error'（非真实枚举）→ 容错分支仍 run-failed（防协议漂移滑回假成功）；
+//   - 成功路径零回归：terminal success 先到 / final-frame 先到 + terminal success
+//     迟到 / final-frame 独走（无 turn.terminal）三形态均 parsed；
+//   - schema 任务遇 failed 终态：分流先于 schema 校验（不产 schema_emulation_failed、
+//     不进强化重试）。
+// 失败终态即时到达，idle/ceiling 默认阈值不参与——无需 env stub。
+
+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 } from "vitest";
+
+import type { EngineRunResult, RunContext } from "../../../port.ts";
+import type { AgentCallOpts } from "../../../../../orchestration/models/types.ts";
+import { ZCODE_APPSERVER_GOLDEN } from "../golden-sample.ts";
+import { ZcodeEngine, hostZcodeDbPath, 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";
+const GOLDEN_FULL_TEXT = "你好，任务完成";
+/** 真实协议 failed 终态帧（⛔P-Z2 门 credfail 实测帧形：errorCode/errorMessage 携带）。 */
+const TERMINAL_FAILED_REAL =
+  '{"method":"v4/telemetry/event","params":{"kind":"turn.terminal","status":"failed","errorCode":"model_request_failed","errorMessage":"Provider marked the request as failed (bad port / credential invalid)"}}';
+/** failed 无错误详情变体（P-Z2 降级形态注入材料）。 */
+const TERMINAL_FAILED_BARE =
+  '{"method":"v4/telemetry/event","params":{"kind":"turn.terminal","status":"failed"}}';
+/** interrupted 终态（真实枚举成员——用户中断，不误判失败的回归面）。 */
+const TERMINAL_INTERRUPTED_FRAME =
+  '{"method":"v4/telemetry/event","params":{"kind":"turn.terminal","status":"interrupted"}}';
+/** 非真实枚举的 "error" 终态（容错分支——防协议漂移滑回假成功）。 */
+const TERMINAL_ERROR_FRAME =
+  '{"method":"v4/telemetry/event","params":{"kind":"turn.terminal","status":"error"}}';
+/** 收尾帧（A.2 ⑤ response 形态）——final-frame 宽松终态的注入材料（golden terminal[1]）。 */
+const GOLDEN_FINAL_FRAME = ZCODE_APPSERVER_GOLDEN.terminal[1];
+/** read 兜底返回的服务端错误文本（read 尾部兜底路径的载体）。 */
+const READ_ERROR_TEXT = "Error: provider request failed (401 Unauthorized)";
+/** 真实 failed 终态的 terminal 帧错误详情（探针 credfail 实测值）。 */
+const TERMINAL_ERROR_CODE = "model_request_failed";
+const TERMINAL_ERROR_MESSAGE = "Provider marked the request as failed (bad port / credential invalid)";
+
+let 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(() => {
+  engines = [];
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "zcode-eng-status-"));
+  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 () => {
+  for (const engine of engines.splice(0)) await engine.dispose().catch(() => undefined);
+  fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+});
+
+interface ScenarioOverrides {
+  /** send 应答前逐帧推送的注入序列（覆盖缺省 golden 流）。 */
+  sendPushes: string[];
+  /** 覆盖 read 应答（缺省 golden readResponse——assistant 全文）。 */
+  readResult?: unknown;
+}
+
+interface EngineFixture {
+  engine: ZcodeEngine;
+  workspace: string;
+}
+
+function makeEngine(overrides: ScenarioOverrides): EngineFixture {
+  seq += 1;
+  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: overrides.readResult ?? JSON.parse(ZCODE_APPSERVER_GOLDEN.readResponse),
+    sendPushes: overrides.sendPushes.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 ?? "",
+      // 钉扎 appserver 定向（定向不探不降，与 zcode-engine-appserver.test.ts 同款）
+      XYZ_ZCODE_MODE: "appserver",
+      FAKE_SESSION_SCENARIO: scenarioFile,
+    },
+  };
+  const engine = new ZcodeEngine(deps);
+  engines.push(engine);
+  return { engine, workspace };
+}
+
+function makeTask(overrides?: Partial<AgentCallOpts>): AgentCallOpts {
+  return { prompt: "做点什么", description: "s", model: `${PROVIDER}/m1`, ...overrides };
+}
+
+function makeCtx(overrides?: Partial<RunContext>): RunContext {
+  return { taskId: "sa-status", poolKey: "", ...overrides };
+}
+
+// ============================================================
+// status='failed'（真实帧形）→ run-failed（⛔P-Z2 门修正根修回归面）
+// ============================================================
+
+describe("failed 终态分流（真实协议枚举：parsed 前消费 status → run-failed，不假成功）", () => {
+  it("帧序 A：turn.terminal failed（errorCode/errorMessage）先到 + read 有全文 → run-failed 且详情取 terminal 帧（优先于 read 尾部）", async () => {
+    const f = makeEngine({
+      sendPushes: [...ZCODE_APPSERVER_GOLDEN.pushStream, TERMINAL_FAILED_REAL],
+      // read 缺省 golden（有全文）——证明 terminal 帧详情优先级高于 read 尾部
+    });
+    const r: EngineRunResult = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    // F-3 文案形态：engine_run_failed 前缀 + 真实枚举值 failed + 会话 id（非 engine_timeout 族）
+    expect(r.outcome.error).toMatch(/^engine_run_failed: app-server 终态 status=failed/);
+    expect(r.outcome.error).toContain(`（会话 ${GOLDEN_SESSION_ID}）`);
+    expect(r.outcome.error).not.toContain("engine_timeout");
+    // ⛔P-Z2：错误详情来自 terminal 帧（read/delta 携带不了——errorCode/errorMessage 优先）
+    expect(r.outcome.error).toContain(`errorCode: ${TERMINAL_ERROR_CODE}`);
+    expect(r.outcome.error).toContain(TERMINAL_ERROR_MESSAGE);
+    // 详情已采信，read 尾部不再叠加（详情 > read 兜底的优先级裁决）
+    expect(r.outcome.error).not.toContain(GOLDEN_FULL_TEXT);
+    // 恢复指引（F-3）
+    expect(r.outcome.error).toContain("engine_credential_missing 同族排查");
+    // 失败形态（非成功）：异常终态口径 exitCode=null、content 空
+    expect(r.outcome.exitCode).toBeNull();
+    expect(r.outcome.content).toBe("");
+    // run 不 reject——正常 handle 返回（record 必须收尾），sessionId 留痕进 sessionRef
+    //（dbPath 形态随共享宿主 HOME 重构为宿主 db 绝对路径——hostZcodeDbPath）
+    expect(r.outcome.sessionId).toBe(GOLDEN_SESSION_ID);
+    expect(r.handle.data.sessionRef).toEqual({ sessionId: GOLDEN_SESSION_ID, dbPath: hostZcodeDbPath() });
+  }, 15_000);
+
+  it("帧序 B：final-frame 宽松 settle success 先到 + turn.terminal failed 迟到（lastTerminalStatus/lastTerminalError 衔接）→ 仍 run-failed", async () => {
+    const f = makeEngine({
+      // final-frame 先落定（session-channel 恒 settle success），权威 failed 只被记录
+      sendPushes: [...ZCODE_APPSERVER_GOLDEN.pushStream, GOLDEN_FINAL_FRAME, TERMINAL_FAILED_REAL],
+    });
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toMatch(/^engine_run_failed: app-server 终态 status=failed/);
+    // 迟到 terminal 帧的详情仍透传（channel 只记录不改写落定，消费层识破假成功）
+    expect(r.outcome.error).toContain(`errorCode: ${TERMINAL_ERROR_CODE}`);
+    expect(r.outcome.error).toContain(TERMINAL_ERROR_MESSAGE);
+    expect(r.outcome.exitCode).toBeNull();
+    expect(r.outcome.content).toBe("");
+  }, 15_000);
+
+  it("P-Z2 降级形态：failed 无 errorCode/errorMessage + final-frame 先到 + read 无错误信息 → 尾部兜底，仍 run-failed 不假成功", async () => {
+    const f = makeEngine({
+      sendPushes: [...ZCODE_APPSERVER_GOLDEN.pushStream, GOLDEN_FINAL_FRAME, TERMINAL_FAILED_BARE],
+      readResult: { messages: [] }, // read 无错误信息（降级形态判据）
+    });
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    // 覆盖面收窄但不假成功：final-frame 的宽松 success 不采信
+    expect(r.outcome.error).toMatch(/^engine_run_failed: app-server 终态 status=failed/);
+    expect(r.outcome.exitCode).toBeNull();
+    expect(r.outcome.content).toBe("");
+    // 尾部以 finalText 降级合成（read 空 → 收尾帧全文 → delta 聚合的既有降级链）
+    expect(r.outcome.error).toContain(GOLDEN_FULL_TEXT);
+  }, 15_000);
+
+  it("全空形态：仅 turn.terminal failed（无 delta/收尾帧/错误详情）+ read 空 → run-failed 且不伪造错误详情", async () => {
+    const f = makeEngine({
+      sendPushes: [TERMINAL_FAILED_BARE],
+      readResult: { messages: [] },
+    });
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toMatch(/^engine_run_failed: app-server 终态 status=failed/);
+    expect(r.outcome.error).toContain("服务端无返回内容");
+    expect(r.outcome.exitCode).toBeNull();
+    expect(r.outcome.content).toBe("");
+  }, 15_000);
+
+  it("schema 任务遇 failed 终态：分流先于 schema 校验（不产 schema_emulation_failed、不进强化重试）", async () => {
+    const f = makeEngine({
+      sendPushes: [...ZCODE_APPSERVER_GOLDEN.pushStream, TERMINAL_FAILED_REAL],
+    });
+    const r = await f.engine.run(
+      makeTask({ cwd: f.workspace, schema: { type: "object", properties: { answer: { type: "string" } }, required: ["answer"] } }),
+      makeCtx(),
+    );
+    expect(r.outcome.error).toMatch(/^engine_run_failed: app-server 终态 status=failed/);
+    expect(r.outcome.error).not.toContain("schema_emulation_failed");
+    expect(r.outcome.parsedOutput).toBeUndefined();
+  }, 15_000);
+});
+
+// ============================================================
+// interrupted 不误判 + error 容错分支（⛔P-Z2 门修正的两翼）
+// ============================================================
+
+describe("非失败终态裁决（interrupted 随宿主 abort 主路径；error 容错防漂移）", () => {
+  it("status:'interrupted'（真实枚举成员）→ 不误判失败：parsed 收口（用户中断不属引擎失败，落定语义登记）", async () => {
+    const f = makeEngine({
+      sendPushes: [...ZCODE_APPSERVER_GOLDEN.pushStream, TERMINAL_INTERRUPTED_FRAME],
+    });
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    // 不分流：引擎侧不抢先把它终态化为失败（宿主 abort 主路径的收口语义保留）
+    expect(r.outcome.error).toBeUndefined();
+    expect(r.outcome.content).toBe(GOLDEN_FULL_TEXT);
+    expect(r.outcome.exitCode).toBe(0);
+  }, 15_000);
+
+  it("status:'error'（非真实枚举，容错分支）→ 仍 run-failed 不假成功（防协议漂移滑回 v1 缺陷）", async () => {
+    const f = makeEngine({
+      sendPushes: [TERMINAL_ERROR_FRAME],
+      readResult: { messages: [] },
+    });
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toMatch(/^engine_run_failed: app-server 终态 status=error/);
+    expect(r.outcome.error).toContain("服务端无返回内容");
+    expect(r.outcome.exitCode).toBeNull();
+    expect(r.outcome.content).toBe("");
+  }, 15_000);
+});
+
+// ============================================================
+// 成功路径零回归（负面验证——§8 A6 同族）
+// ============================================================
+
+describe("成功路径零回归（U3 分流不误伤正常终态）", () => {
+  it("terminal success 先到（golden 流）→ parsed：content 全文、exitCode 0、无 error", async () => {
+    const f = makeEngine({
+      sendPushes: [...ZCODE_APPSERVER_GOLDEN.pushStream, ...ZCODE_APPSERVER_GOLDEN.terminal],
+    });
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toBeUndefined();
+    expect(r.outcome.content).toBe(GOLDEN_FULL_TEXT);
+    expect(r.outcome.exitCode).toBe(0);
+  }, 15_000);
+
+  it("final-frame 先到 + terminal success 迟到 → parsed（权威 success 后到不改写已落定的成功）", async () => {
+    const f = makeEngine({
+      // final-frame 在权威 terminal 之前到达（宽松终态先 settle，权威后到只记录）
+      sendPushes: [...ZCODE_APPSERVER_GOLDEN.pushStream, GOLDEN_FINAL_FRAME, ZCODE_APPSERVER_GOLDEN.terminal[0]],
+    });
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toBeUndefined();
+    expect(r.outcome.content).toBe(GOLDEN_FULL_TEXT);
+    expect(r.outcome.exitCode).toBe(0);
+  }, 15_000);
+
+  it("final-frame 独走（无 turn.terminal 到达）→ parsed（无权威 status 可消费，不判失败）", async () => {
+    const f = makeEngine({
+      sendPushes: [...ZCODE_APPSERVER_GOLDEN.pushStream, GOLDEN_FINAL_FRAME],
+    });
+    const r = await f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    expect(r.outcome.error).toBeUndefined();
+    expect(r.outcome.content).toBe(GOLDEN_FULL_TEXT);
+    expect(r.outcome.exitCode).toBe(0);
+  }, 15_000);
+});