@zhushanwen/subagent-core 0.2.0

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

@@ -0,0 +1,154 @@
+// pool-manager.test.ts —— 池 acquire/release 引用计数 / 归零整池删除 / journal 保留
+// / 清理失败标记 / spawnedFiles 单次清理（D5 + §3.3.9）。
+//
+// 三视角：①构建者——计数归零才删、删除边界三硬规则逐条；②使用者——release 幂等
+// 安全（无引用 no-op）；③观察者——清理失败有 .pool-cleanup-failed 标记（可观测）。
+
+import { mkdirSync, mkdtempSync, existsSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  acquirePool,
+  cleanupSpawnedFiles,
+  POOL_CLEANUP_FAILED_MARKER,
+  releasePoolRef,
+  resetPoolRegistryForTests,
+} from "../../common/pool-manager.ts";
+import { resolvePoolDir } from "../../paths.ts";
+
+let tmpRoot: string;
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), "engine-pool-test-"));
+  resetPoolRegistryForTests();
+});
+
+afterEach(() => {
+  rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("acquirePool", () => {
+  it("mkdir -p 返回池目录（路径经 resolvePoolDir 派生），重复 acquire 幂等", async () => {
+    const dir1 = await acquirePool(tmpRoot, "zcode", "reviewer");
+    const dir2 = await acquirePool(tmpRoot, "zcode", "reviewer");
+    expect(dir1).toBe(resolvePoolDir(tmpRoot, "zcode", "reviewer"));
+    expect(dir1).toBe(dir2);
+    expect(existsSync(dir1)).toBe(true);
+  });
+
+  it("poolKey 经 sanitizeSeg 归一（脏字符不进文件系统路径）", async () => {
+    const dir = await acquirePool(tmpRoot, "zcode", "weird/key..name");
+    expect(dir).toBe(resolvePoolDir(tmpRoot, "zcode", "weird-key-name"));
+  });
+});
+
+describe("releasePoolRef 引用计数与整池删除", () => {
+  it("双引用：release 一次池仍在（原生状态未删），归零才整池删除", async () => {
+    const poolDir = resolvePoolDir(tmpRoot, "zcode", "reviewer");
+    await acquirePool(tmpRoot, "zcode", "reviewer");
+    await acquirePool(tmpRoot, "zcode", "reviewer");
+    mkdirSync(join(poolDir, "home"), { recursive: true });
+    writeFileSync(join(poolDir, "home", "config.json"), "{}");
+
+    await releasePoolRef(tmpRoot, "zcode", "reviewer");
+    expect(existsSync(join(poolDir, "home"))).toBe(true); // 计数 1，不删
+
+    await releasePoolRef(tmpRoot, "zcode", "reviewer"); // 归零
+    expect(existsSync(join(poolDir, "home"))).toBe(false); // 原生状态已删
+  });
+
+  it("journal-*.jsonl 不随池删（生命周期跟随 record），目录保留", async () => {
+    const poolDir = resolvePoolDir(tmpRoot, "zcode", "reviewer");
+    await acquirePool(tmpRoot, "zcode", "reviewer");
+    writeFileSync(join(poolDir, "journal-bg-1.jsonl"), "{}\n");
+    mkdirSync(join(poolDir, "home"), { recursive: true });
+
+    await releasePoolRef(tmpRoot, "zcode", "reviewer");
+    expect(existsSync(join(poolDir, "journal-bg-1.jsonl"))).toBe(true);
+    expect(existsSync(join(poolDir, "home"))).toBe(false);
+    // 只剩 journal：目录本体保留（journal 还在用）
+    expect(existsSync(poolDir)).toBe(true);
+    expect(readdirSync(poolDir)).toEqual(["journal-bg-1.jsonl"]);
+  });
+
+  it("无引用的 release（进程重启后 GC）→ 保守 no-op 不删池", async () => {
+    const poolDir = resolvePoolDir(tmpRoot, "zcode", "reviewer");
+    mkdirSync(join(poolDir, "home"), { recursive: true });
+    await releasePoolRef(tmpRoot, "zcode", "reviewer");
+    expect(existsSync(join(poolDir, "home"))).toBe(true);
+  });
+
+  it("池目录不存在时 release 归零 → 无原生状态可清，视为成功不抛", async () => {
+    await acquirePool(tmpRoot, "zcode", "ghost");
+    // 归零但目录已被外部删除
+    rmSync(resolvePoolDir(tmpRoot, "zcode", "ghost"), { recursive: true, force: true });
+    await expect(releasePoolRef(tmpRoot, "zcode", "ghost")).resolves.toBeUndefined();
+  });
+
+  it("删除失败置 .pool-cleanup-failed 标记文件（可观测不静默），不 throw", async () => {
+    const poolDir = resolvePoolDir(tmpRoot, "zcode", "reviewer");
+    await acquirePool(tmpRoot, "zcode", "reviewer");
+    mkdirSync(join(poolDir, "home"), { recursive: true });
+    writeFileSync(join(poolDir, "journal-bg-1.jsonl"), "{}\n");
+
+    // 注入失败 fs：rm 对 home 目录 reject（标记写入仍走真实 fs——失败要可观测）
+    const realFs = await import("node:fs/promises");
+    const injected = {
+      mkdir: (p: string, o: { recursive: boolean }) => realFs.mkdir(p, o),
+      readdir: (p: string) => realFs.readdir(p, { withFileTypes: true }),
+      rm: async (p: string, o: { recursive: boolean; force: boolean }) => {
+        if (p === join(poolDir, "home")) throw new Error("EACCES: permission denied");
+        return realFs.rm(p, o);
+      },
+      rmdir: (p: string) => realFs.rmdir(p),
+      writeFile: (p: string, d: string) => realFs.writeFile(p, d, "utf8"),
+    };
+
+    await expect(releasePoolRef(tmpRoot, "zcode", "reviewer", injected)).resolves.toBeUndefined();
+    const markerPath = join(poolDir, POOL_CLEANUP_FAILED_MARKER);
+    expect(existsSync(markerPath)).toBe(true);
+    // 标记内容是失败清单 JSON（含失败条目与原因）
+    const payload = JSON.parse(
+      (await import("node:fs")).readFileSync(markerPath, "utf8"),
+    ) as { failures: string[] };
+    expect(payload.failures.length).toBe(1);
+    expect(payload.failures[0]).toContain("home");
+    expect(payload.failures[0]).toContain("EACCES");
+  });
+});
+
+describe("cleanupSpawnedFiles（单次性产物）", () => {
+  it("keepForResume=true → 全部保留（resume 续接原 session，不重写产物）", async () => {
+    const f = join(tmpRoot, "prompt.txt");
+    writeFileSync(f, "x");
+    await cleanupSpawnedFiles([f], { keepForResume: true });
+    expect(existsSync(f)).toBe(true);
+  });
+
+  it("keepForResume=false → 删除；目录产物递归删", async () => {
+    const file = join(tmpRoot, "prompt.txt");
+    const dir = join(tmpRoot, "persona");
+    writeFileSync(file, "x");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "persona.md"), "y");
+    await cleanupSpawnedFiles([file, dir], { keepForResume: false });
+    expect(existsSync(file)).toBe(false);
+    expect(existsSync(dir)).toBe(false);
+  });
+
+  it("不存在的路径幂等（ENOENT 忽略）；单条失败不 throw 其余继续", async () => {
+    const good = join(tmpRoot, "good.txt");
+    writeFileSync(good, "x");
+    // 真实 fs 下很难制造 rm 失败——用「父路径为文件」制造 ENOTDIR 失败：
+    // rm(recursive, force) 对 «file/child» 形态报 ENOTDIR（force 只豁免 ENOENT）
+    const blocked = join(tmpRoot, "plain-file", "child");
+    writeFileSync(join(tmpRoot, "plain-file"), "not a dir");
+    await expect(
+      cleanupSpawnedFiles([blocked, good], { keepForResume: false }),
+    ).resolves.toBeUndefined();
+    expect(existsSync(good)).toBe(false);
+  });
+});

package/src/execution/engine/__tests__/common/schema-emulation.test.ts

@@ -0,0 +1,128 @@
+// schema-emulation.test.ts —— 三级容错提取逐级用例 + ajv 校验 + tail 载体。
+//
+// 三视角：①构建者——三级容错每级有独立触达用例（直接 parse / fence / 括号扫描）；
+// ②使用者——ok:false 时 error 简述 + tail 足以构造重试 prompt；③观察者——prompt
+// 注入段含 schema 声明与输出约定（emulated 引擎拼进 prompt 后模型可遵循）。
+
+import { describe, expect, it } from "vitest";
+
+import {
+  buildSchemaEmulationSegment,
+  extractAndValidateStructuredOutput,
+  SCHEMA_EMULATION_TAIL_CHARS,
+} from "../../common/schema-emulation.ts";
+
+const objectSchema = {
+  type: "object",
+  properties: { verdict: { type: "string" }, issues: { type: "array", items: { type: "string" } } },
+  required: ["verdict"],
+} as const;
+
+describe("buildSchemaEmulationSegment", () => {
+  it("注入段含 schema JSON 声明 + 输出格式约定（用户可见 prompt 断言）", () => {
+    const segment = buildSchemaEmulationSegment(objectSchema);
+    expect(segment).toContain("## Structured Output Requirement");
+    expect(segment).toContain(JSON.stringify(objectSchema));
+    expect(segment).toMatch(/```json/);
+    expect(segment).toMatch(/ONLY the JSON value/);
+    expect(segment).toMatch(/JSON Schema \(draft-07\)/);
+  });
+});
+
+describe("extractAndValidateStructuredOutput 三级容错", () => {
+  it("第 1 级：输出整体即合法 JSON → 直接 parse 通过 + ajv 通过", () => {
+    const text = JSON.stringify({ verdict: "pass", issues: [] });
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result).toEqual({ ok: true, parsed: { verdict: "pass", issues: [] } });
+  });
+
+  it("第 2 级：markdown code fence 包裹 → 剥 fence 后 parse 通过", () => {
+    const text = "Here is my answer:\n```json\n{\"verdict\": \"fail\", \"issues\": [\"a\", \"b\"]}\n```\n";
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result).toEqual({ ok: true, parsed: { verdict: "fail", issues: ["a", "b"] } });
+  });
+
+  it("第 2 级：无语言标注的裸 fence 也能剥", () => {
+    const text = "```\n{\"verdict\": \"pass\"}\n```";
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result).toEqual({ ok: true, parsed: { verdict: "pass" } });
+  });
+
+  it("第 3 级：前后杂文本包裹 → 首尾括号扫描提取", () => {
+    const text = "Sure! The review result is:\n\n{\"verdict\": \"fail\", \"issues\": [\"x\"]}\n\nHope this helps.";
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result).toEqual({ ok: true, parsed: { verdict: "fail", issues: ["x"] } });
+  });
+
+  it("第 3 级：array 根也支持（首个 '[' 到末个 ']'）", () => {
+    const arraySchema = { type: "array", items: { type: "string" } };
+    const result = extractAndValidateStructuredOutput("prefix [\"a\",\"b\"] suffix", arraySchema);
+    expect(result).toEqual({ ok: true, parsed: ["a", "b"] });
+  });
+
+  it("提取成功但 ajv 校验失败 → ok:false 含 ajv 错误明细与原始尾部", () => {
+    // verdict 缺失（required）+ issues 类型错
+    const text = '{"issues": "not-an-array"}';
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("Schema validation failed");
+      expect(result.error).toContain("verdict");
+      expect(result.tail).toBe(text);
+    }
+  });
+
+  it("三级提取全失败（无任何 JSON）→ ok:false 且 error 指明三级路径", () => {
+    const result = extractAndValidateStructuredOutput("no json here at all", objectSchema);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("3-stage");
+      expect(result.error).toContain("code-fence");
+      expect(result.error).toContain("bracket scan");
+    }
+  });
+
+  it("提取成功但 JSON 语法损坏（括号扫描后仍 parse 失败）→ ok:false", () => {
+    const result = extractAndValidateStructuredOutput("result: {verdict: pass}", objectSchema);
+    expect(result.ok).toBe(false);
+  });
+
+  it("ajv 编译失败（非法 schema）→ ok:false 指明 host 侧编译失败", () => {
+    // type: "foo" 是 ajv 编译期拒绝的非法类型值
+    const result = extractAndValidateStructuredOutput('{"a":1}', { type: "foo" });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("compilation failed");
+    }
+  });
+});
+
+describe("tail 载体（错误展示）", () => {
+  it(`tail 截断到原始输出尾部 ${SCHEMA_EMULATION_TAIL_CHARS} 字`, () => {
+    const head = "H".repeat(300);
+    const tailPart = "T".repeat(400);
+    const text = `${head}${tailPart}`; // 700 字，尾部 500 = 末段（100H + 400T）
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.tail.length).toBe(SCHEMA_EMULATION_TAIL_CHARS);
+      expect(result.tail).toBe("H".repeat(100) + "T".repeat(400));
+    }
+  });
+
+  it("短输出 tail 为原文（不截断）", () => {
+    const text = "short broken output";
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.tail).toBe(text);
+    }
+  });
+});
+
+describe("D4 硬分流守护（静态断言）", () => {
+  it("本模块的 ajv 只在 emulated 路径——native 引擎（pi-env 链路）不 import 本模块（由全仓 grep 守护，见任务报告）", () => {
+    // 占位用例：硬分流是 import 约束，运行时无对应断言点；保留用例记录守护方式
+    expect(typeof extractAndValidateStructuredOutput).toBe("function");
+  });
+});

package/src/execution/engine/__tests__/conformance/__fixtures__/pi-golden-events.json

@@ -0,0 +1,28 @@
+{
+  "_meta": {
+    "engineId": "pi",
+    "description": "pi 引擎 golden 事件序列（统一 AgentEvent 形态——spawn-event-adapter/session-runner 翻译后的 onEvent 出口序列，即 journal 落盘形态）",
+    "source": "从 spawn-event-adapter.test.ts / session-runner 事件形状构造的典型流式序列：bash 工具调用（含 pendingTools 配对）→ 双段 text_delta → message_end（完整 usage）→ turn_end。字段形状与 handleSdkEvent 翻译产物逐一锚定（tool_start.toolName/args、tool_end.result/isError、text_delta.delta、message_end.usage 四项 token、turn_end）",
+    "recordedAt": "2026-08-25",
+    "usageMapping": "message_end.usage = pi SDK message.usage（input/output/cacheRead/cacheWrite 四项 + cost.total 投影为 cost）"
+  },
+  "events": [
+    { "type": "tool_start", "toolName": "bash", "args": { "command": "ls -la /tmp/probe" } },
+    {
+      "type": "tool_end",
+      "toolName": "bash",
+      "args": { "command": "ls -la /tmp/probe" },
+      "result": { "output": "total 0\ndrwxr-xr-x  2 user  staff  64 Aug 25 10:00:00 ." },
+      "isError": false
+    },
+    { "type": "thinking_delta", "delta": "目录为空，无需进一步检查。" },
+    { "type": "text_delta", "delta": "Probe directory is empty. " },
+    { "type": "text_delta", "delta": "Nothing to clean up." },
+    {
+      "type": "message_end",
+      "usage": { "input": 12599, "output": 17, "cacheRead": 512, "cacheWrite": 0, "cost": 0.0001 }
+    },
+    { "type": "turn_end" }
+  ],
+  "content": "Probe directory is empty. Nothing to clean up."
+}

package/src/execution/engine/__tests__/conformance/agent-event-invariants.ts

@@ -0,0 +1,141 @@
+// agent-event-invariants.ts —— AgentEvent 产出不变量断言器（conformance C3 的实现体）。
+//
+// 设计权威源：docs/architecture/subagent-engine-abstraction.md §3.3.7「AgentEvent 产出
+// 不变量」五条（全部引擎必须满足）。任何 adapter 的 conformance 套件（golden 回放层 /
+// 合成样本）都经本断言器校验——负例守护（A12「套件有牙」）靠注入坏序列证明它转红。
+//
+// 为什么独立成模块（非内联在测试文件）：pi/zcode 两套 golden 回放 + 负例元测试共用
+// 同一断言逻辑；断言规则漂移会同步影响所有引擎的 conformance，单点维护。
+
+import type { AgentEvent, AgentUsage } from "../../../types.ts";
+
+/** 单条不变量违例。invariant 是规则编号（"1"/"2a"...），detail 是定位信息。 */
+export interface InvariantFinding {
+  invariant: string;
+  detail: string;
+}
+
+/** 断言选项。granularity 决定不变量 3 走流式（byte 级拼接）还是 coarse 口径。 */
+export interface InvariantOptions {
+  granularity: "stream" | "coarse";
+  /** 流式引擎的终态 content（不变量 3a：text_delta 拼接 === content，byte 级）。 */
+  content?: string;
+}
+
+/** 五条不变量的纯校验（不 throw，返回违例清单——元测试要拿清单做反证）。 */
+export function checkAgentEventInvariants(
+  events: readonly AgentEvent[],
+  opts: InvariantOptions,
+): InvariantFinding[] {
+  const findings: InvariantFinding[] = [];
+  if (events.length === 0) {
+    return [{ invariant: "0", detail: "事件序列为空——至少需要 turn_end 终态" }];
+  }
+
+  // 不变量 1：终态序唯一——最后一个非 error 事件必是 turn_end；message_end（若出现）
+  // 必在其前（turn_end 之后不允许任何非 error 事件）
+  const nonError = events.filter((e) => e.type !== "error");
+  const last = nonError[nonError.length - 1];
+  if (last === undefined || last.type !== "turn_end") {
+    findings.push({
+      invariant: "1",
+      detail: `最后一个非 error 事件是 ${String(last?.type ?? "(none)")}，必须唯一且为 turn_end`,
+    });
+  }
+  const lastTurnEndIdx = findLastIndex(events, (e) => e.type === "turn_end");
+  if (lastTurnEndIdx >= 0) {
+    for (let i = lastTurnEndIdx + 1; i < events.length; i++) {
+      const ev = events[i];
+      if (ev !== undefined && ev.type !== "error") {
+        findings.push({ invariant: "1", detail: `turn_end 之后出现非 error 事件 ${ev.type}（idx ${i}）` });
+      }
+    }
+  }
+  const lastMessageEndIdx = findLastIndex(events, (e) => e.type === "message_end");
+  if (lastMessageEndIdx >= 0 && lastTurnEndIdx >= 0 && lastMessageEndIdx > lastTurnEndIdx) {
+    findings.push({ invariant: "1", detail: "message_end 出现在 turn_end 之后（必须在其前）" });
+  }
+
+  // 不变量 2：message_end.usage 出现时为完整 AgentUsage 形状——给不出完整 usage 时
+  // 显式缺省整个字段，不给残缺对象（NaN/缺键 = 残缺）
+  events.forEach((ev, idx) => {
+    if (ev.type !== "message_end") return;
+    if (ev.usage === undefined) return; // 显式缺省 = 合法
+    if (!isCompleteUsage(ev.usage)) {
+      findings.push({ invariant: "2", detail: `message_end(idx ${idx}).usage 残缺（四项 token 必须全为有限数）` });
+    }
+  });
+
+  // 不变量 3a（流式）：全部 text_delta 拼接 === content（byte 级）
+  if (opts.granularity === "stream") {
+    if (opts.content === undefined) {
+      findings.push({ invariant: "3a", detail: "流式口径必须提供 content 供拼接比对" });
+    } else {
+      const joined = events.filter((e) => e.type === "text_delta").map((e) => (e as { delta: string }).delta).join("");
+      if (Buffer.from(joined, "utf8").toString("hex") !== Buffer.from(opts.content, "utf8").toString("hex")) {
+        findings.push({ invariant: "3a", detail: "text_delta 拼接与 content 不一致（byte 级比对失败）" });
+      }
+    }
+  } else {
+    // 不变量 3b（coarse）：turn_end 前至少一个 message_end
+    if (lastTurnEndIdx < 0 || !events.slice(0, lastTurnEndIdx).some((e) => e.type === "message_end")) {
+      findings.push({ invariant: "3b", detail: "coarse 引擎 turn_end 前必须至少一个 message_end" });
+    }
+  }
+
+  // 不变量 4：tool_start/tool_end 按名配对——终态前未配对的 tool_start 必须有配对
+  // tool_end（isError 可）或后续 error 事件兜底
+  const openTools: Array<{ toolName: string; idx: number }> = [];
+  let errorSeen = false;
+  events.forEach((ev, idx) => {
+    if (ev.type === "error") {
+      errorSeen = true;
+      return;
+    }
+    if (ev.type === "tool_start") {
+      openTools.push({ toolName: ev.toolName, idx });
+      return;
+    }
+    if (ev.type === "tool_end") {
+      const at = openTools.findIndex((t) => t.toolName === ev.toolName);
+      if (at >= 0) openTools.splice(at, 1);
+      return;
+    }
+  });
+  for (const t of openTools) {
+    if (!errorSeen) {
+      findings.push({
+        invariant: "4",
+        detail: `tool_start(${t.toolName}, idx ${t.idx}) 终态前未配对（无 tool_end 也无 error 兜底）`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/** 断言形态（conformance 用例直接消费——违例 throw，测试转红）。 */
+export function assertAgentEventInvariants(events: readonly AgentEvent[], opts: InvariantOptions): void {
+  const findings = checkAgentEventInvariants(events, opts);
+  if (findings.length > 0) {
+    const lines = findings.map((f) => `  [不变量 ${f.invariant}] ${f.detail}`).join("\n");
+    throw new Error(`AgentEvent 不变量违例（§3.3.7 五条）：\n${lines}`);
+  }
+}
+
+/** AgentUsage 完整形状判定（四项 token 有限数；cost 可选）。 */
+function isCompleteUsage(u: AgentUsage): boolean {
+  return (
+    Number.isFinite(u.input) && Number.isFinite(u.output) &&
+    Number.isFinite(u.cacheRead) && Number.isFinite(u.cacheWrite)
+  );
+}
+
+/** Array.prototype.findLastIndex 的 ES2022 前兼容（node 18+ 有原生，防御口径手写）。 */
+function findLastIndex<T>(arr: readonly T[], pred: (v: T) => boolean): number {
+  for (let i = arr.length - 1; i >= 0; i--) {
+    const v = arr[i];
+    if (v !== undefined && pred(v)) return i;
+  }
+  return -1;
+}

package/src/execution/engine/__tests__/conformance/contract.abort.test.ts

@@ -0,0 +1,109 @@
+// contract.abort.test.ts —— conformance C4（abort 行为）：运行中 cancel → 宿主合成
+// 终态（exitCode=null）、无悬挂 promise（run 正常 resolve、exited 收口）、错误事件
+// 先于终态 emit（不变量 5 的事件面）。fake launcher 注入（不依赖真机）。
+
+import { spawn } 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 { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import type { RunContext } from "../../port.ts";
+import type { AgentEvent, AgentTaskSpec } from "../../types.ts";
+import { ZcodeEngine, type ZcodeEngineDeps } from "../../engines/zcode/zcode-engine.ts";
+import type { ZcodeLaunchedProcess } from "../../engines/zcode/launcher.ts";
+
+const PROVIDER = "provider-x";
+
+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));
+}
+
+/** 长驻 fake 进程：stdout 永不结束（模拟运行中），abort 由测试主动触发。 */
+function makeHangingLaunch(): {
+  launch: ZcodeEngineDeps["launch"];
+  proc: () => ZcodeLaunchedProcess | undefined;
+  triggerAbort: () => void;
+} {
+  let launched: ZcodeLaunchedProcess | undefined;
+  const stdout = new PassThrough();
+  const stderr = new PassThrough();
+  let killTriggered = false;
+  let resolveExited: (v: { code: number | null; signal: string | undefined }) => void = () => {};
+  const exited = new Promise<{ code: number | null; signal: string | undefined }>((resolve) => {
+    resolveExited = resolve;
+  });
+  const launch = (): ZcodeLaunchedProcess => {
+    launched = {
+      // D10 记账形态：child = 立即退出的真实 node 短进程（本用例不消费记账面）
+      child: spawn(process.execPath, ["-e", ""]),
+      pid: 4242,
+      stdout,
+      stderr,
+      abort: async () => {
+        killTriggered = true;
+        // 杀链语义：进程被信号杀死（code=null）——微任务后 settle 模拟 kill 时序
+        setTimeout(() => resolveExited({ code: null, signal: "SIGTERM" }), 5);
+      },
+      exited,
+      killedByUs: () => killTriggered,
+    };
+    return launched;
+  };
+  return { launch, proc: () => launched, triggerAbort: () => resolveExited({ code: null, signal: "SIGTERM" }) };
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "c4-abort-"));
+  dataDir = path.join(tmpRoot, "data");
+  v2Path = path.join(tmpRoot, "v2.json");
+  writeJson(v2Path, {
+    provider: { [PROVIDER]: { options: { apiKey: "k" }, models: { m1: {} } } },
+  });
+});
+
+afterEach(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("conformance C4：abort 行为（运行中 cancel → 合成终态、无悬挂）", () => {
+  it("abort → run 正常 resolve（不悬挂）：exitCode=null + error 事件合成 + killedByUs", async () => {
+    const fake = makeHangingLaunch();
+    const engine = new ZcodeEngine({
+      engineDataDir: () => dataDir,
+      sources: { v2ConfigPath: v2Path },
+      processEnv: { PATH: "/usr/bin" },
+      launch: fake.launch,
+    });
+
+    const controller = new AbortController();
+    const events: AgentEvent[] = [];
+    const ctx: RunContext = {
+      taskId: "sa-c4",
+      poolKey: "",
+      signal: controller.signal,
+      onEvent: (ev) => events.push(ev),
+    };
+    const task: AgentTaskSpec = { task: "hang", slug: "abort", model: `${PROVIDER}/m1` };
+
+    const runP = engine.run(task, ctx);
+    // run 进行中触发 abort（等待 spawn 完成——微任务两拍让 launch 已执行）
+    await new Promise((r) => setTimeout(r, 20));
+    controller.abort();
+    const { handle, outcome } = await runP; // 必须正常 resolve（杀链合成终态，不悬挂）
+
+    expect(outcome.exitCode).toBeNull();
+    expect(outcome.error).toContain("中止");
+    // 终态前 error 事件已 emit（不变量 5 的事件面——journal 可重放出失败事实）
+    expect(events.some((e) => e.type === "error")).toBe(true);
+    expect(fake.proc()?.killedByUs()).toBe(true);
+    expect(handle.data.engineId).toBe("zcode");
+  }, 15_000);
+});

package/src/execution/engine/__tests__/conformance/contract.agent-events.test.ts

@@ -0,0 +1,101 @@
+// contract.agent-events.test.ts —— conformance C3（AgentEvent 不变量）+ 负例自证
+// （A12「套件有牙」：故意破坏一个不变量的样本必须被断言器检出——用「注入坏
+// parser」的形态：wrap 真实 synthesizeCoarseEvents 抽掉 message_end，断言套件转红；
+// 若断言器检不出破坏则本元测试失败）。
+
+import { describe, expect, it } from "vitest";
+
+import type { AgentEvent } from "../../../types.ts";
+import { ZCODE_GOLDEN_STDOUT } from "../../engines/zcode/golden-sample.ts";
+import { parseZcodeTerminal, synthesizeCoarseEvents } from "../../engines/zcode/parser.ts";
+import {
+  assertAgentEventInvariants,
+  checkAgentEventInvariants,
+} from "./agent-event-invariants.ts";
+
+/** golden 实录的 coarse 事件流（真实 parser + 真实合成器的产出）。 */
+function goldenCoarseEvents(): AgentEvent[] {
+  const terminal = parseZcodeTerminal(ZCODE_GOLDEN_STDOUT);
+  if (!terminal.ok) throw new Error("golden 样本解析失败");
+  return synthesizeCoarseEvents(terminal.payload.response, terminal.payload.usage);
+}
+
+describe("conformance C3：AgentEvent 不变量（真实 parser 产出全绿）", () => {
+  it("zcode golden 合成事件满足五条不变量（coarse 口径）", () => {
+    assertAgentEventInvariants(goldenCoarseEvents(), { granularity: "coarse" });
+  });
+
+  it("不变量 1：终态唯一——turn_end 后不得再出现非 error 事件", () => {
+    const events: AgentEvent[] = [{ type: "message_end" }, { type: "turn_end" }, { type: "text_delta", delta: "x" }];
+    const findings = checkAgentEventInvariants(events, { granularity: "coarse" });
+    expect(findings.some((f) => f.invariant === "1")).toBe(true);
+  });
+
+  it("不变量 2：message_end.usage 残缺对象（NaN token）被判违例", () => {
+    const events: AgentEvent[] = [
+      { type: "message_end", usage: { input: Number.NaN, output: 1, cacheRead: 0, cacheWrite: 0 } },
+      { type: "turn_end" },
+    ];
+    const findings = checkAgentEventInvariants(events, { granularity: "coarse" });
+    expect(findings.some((f) => f.invariant === "2")).toBe(true);
+  });
+
+  it("不变量 2 正例：usage 显式缺省整个字段 = 合法（不给残缺）", () => {
+    const events: AgentEvent[] = [{ type: "message_end" }, { type: "turn_end" }];
+    expect(checkAgentEventInvariants(events, { granularity: "coarse" })).toEqual([]);
+  });
+
+  it("不变量 3a：流式 text_delta 拼接 ≠ content 判违例（byte 级）", () => {
+    const events: AgentEvent[] = [
+      { type: "text_delta", delta: "abc" },
+      { type: "message_end", usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0 } },
+      { type: "turn_end" },
+    ];
+    const findings = checkAgentEventInvariants(events, { granularity: "stream", content: "abd" });
+    expect(findings.some((f) => f.invariant === "3a")).toBe(true);
+  });
+
+  it("不变量 3b：coarse 序列缺 message_end（turn_end 裸终态）判违例", () => {
+    const events: AgentEvent[] = [{ type: "turn_end" }];
+    const findings = checkAgentEventInvariants(events, { granularity: "coarse" });
+    expect(findings.some((f) => f.invariant === "3b")).toBe(true);
+  });
+
+  it("不变量 4：未配对 tool_start 且无 error 兜底判违例；error 兜底合法", () => {
+    const unpaired: AgentEvent[] = [
+      { type: "tool_start", toolName: "bash" },
+      { type: "turn_end" },
+    ];
+    expect(checkAgentEventInvariants(unpaired, { granularity: "coarse" }).some((f) => f.invariant === "4")).toBe(true);
+
+    const withError: AgentEvent[] = [
+      { type: "tool_start", toolName: "bash" },
+      { type: "error", message: "boom" },
+      { type: "turn_end" },
+    ];
+    expect(checkAgentEventInvariants(withError, { granularity: "coarse" }).some((f) => f.invariant === "4")).toBe(false);
+  });
+});
+
+describe("conformance 负例自证（A12：套件有牙）", () => {
+  it("注入坏 parser（抽掉 message_end 的合成器）：断言器必须检出（不变量 3b 转红）", () => {
+    // 坏 parser 形态：zcode 新版本漂移后合成器丢 message_end——不变量 3b 应抓到
+    const badParser = (): AgentEvent[] => [{ type: "turn_end" }];
+    const events = badParser();
+    const findings = checkAgentEventInvariants(events, { granularity: "coarse" });
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings.some((f) => f.invariant === "3b")).toBe(true);
+    // 断言形态同步转红（conformance 用例消费的入口）
+    expect(() => assertAgentEventInvariants(events, { granularity: "coarse" })).toThrowError(/不变量/);
+  });
+
+  it("注入坏 parser（usage 半映射）：断言器必须检出（不变量 2 转红）", () => {
+    // 坏 parser 形态：新版本 usage 字段改名，数值映射 Number(undefined) → NaN 渗入
+    const badParser = (): AgentEvent[] => [
+      { type: "message_end", usage: { input: Number.NaN, output: 2, cacheRead: 0, cacheWrite: 0 } },
+      { type: "turn_end" },
+    ];
+    const findings = checkAgentEventInvariants(badParser(), { granularity: "coarse" });
+    expect(findings.some((f) => f.invariant === "2")).toBe(true);
+  });
+});