@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/execution/engine/__tests__/conformance/registry-fork-filter.test.ts

@@ -0,0 +1,221 @@
+// registry-fork-filter.test.ts —— [W6] 翻档 × fork 继承残留的读侧过滤契约 +
+// bash 跨 session 可见性显式断言（R4 一刀语义钉住）+ 偏差 #4 探针（goal 守卫口径）。
+//
+// 设计权威源：chat-domain-v1x-liveness-governance.md §3.2 D4（翻档三连带——读侧
+// 过滤三口 + PENDING_LIFECYCLE 翻 process 档）+ 修订记录 v5-⑤（bash 跨 session
+// 可见性一刀钉成显式选择）+ 验收 A9② + impl-plan §5 偏差 #4（W4 交接：goal 守卫
+// 消费点未传基准，W6 实测裁决是否需 goal 侧两行传参）。
+//
+// 被测函数 = `extensions/universal/pending-notifications/src/state.ts` 的导出纯函数
+// （零依赖、不触 Pi 运行时——文件头注自证；经相对路径源码消费，subagent-core 无该
+// workspace 依赖声明，不加 phantom dep）。分工：
+//   - 过滤函数本体 / rebuild 投影的两口径行为：本套件钉语义（conformance 视角）；
+//   - 过滤①②③的**接线**（goal/subagent-workflow/pending-notifications 三消费点
+//     透传 currentSessionId）：W4 包内测试已承载（pi-pending-notifications
+//     __tests__ :523/:532、subagent-workflow pi-host.test :199-223）；
+//   - 后代判定口（读侧过滤②）的差集口径与①共用同一函数——本套件①的断言即其
+//     语义核心；接线透传由上述 W4 测试守护。
+//
+// 探针结论（偏差 #4，实测证据 = 「goal 守卫口径」describe）：**有虚增**——fork 后
+// 父 session 仍活跃的后台任务残留使 goal 守卫现状口径（无基准）幻 defer；确需的
+// 两行传参改动点列于该 describe 注释，留给主会话裁决（本单元不改 goal——红线）。
+
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+// 相对路径源码消费（7 层上溯到仓库根）：state.ts 是零依赖纯函数（不触 Pi 运行时），
+// 无需为探针/契约测试给 subagent-core 添加 workspace 依赖声明。
+import {
+  PENDING_LIFECYCLE,
+  PENDING_TTL_MS,
+  countActiveFromEntries,
+  createRegistry,
+  rebuildFromEntries,
+} from "../../../../../../../extensions/universal/pending-notifications/src/state.ts";
+
+import { runReconcileSweep } from "../../../round-supervisor/index.ts";
+
+/** pending:register entry 的落盘形态（对齐 pending-notifications 写入侧契约）。 */
+function registerEntry(
+  id: string,
+  type: "subagent" | "workflow" | "bash",
+  sessionId: string,
+  overrides: { expiresAt?: number } = {},
+): { customType: string; data: Record<string, unknown> } {
+  return {
+    customType: "pending:register",
+    data: {
+      id,
+      type,
+      name: id,
+      registeredAt: 1_000,
+      sessionId,
+      // bash 真实落盘无 expiresAt 键（写入侧省略，D16）；subagent/workflow 翻
+      // process 档后同理——overrides 仅用于 TTL 对照面。
+      ...(overrides.expiresAt !== undefined ? { expiresAt: overrides.expiresAt } : {}),
+    },
+  };
+}
+
+/** 语义对照面的基准时刻（远超旧 1h TTL——钉「无 TTL 清理」而非「窗口内未到期」假绿）。 */
+const NOW = 10 * PENDING_TTL_MS + 1;
+
+let tmpDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tmpDirs) rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  tmpDirs = [];
+});
+
+describe("[W6/D4 翻档] PENDING_LIFECYCLE 三类型全 process 档（跨时长无 TTL 清理的判据锚）", () => {
+  it("subagent/workflow 翻 process 档（bash 原生 process 档）——翻档事实钉住", () => {
+    expect(PENDING_LIFECYCLE).toEqual({ subagent: "process", workflow: "process", bash: "process" });
+  });
+
+  it("翻档后跨时长（远超旧 1h TTL）无 TTL 清理：三类型 register 均不进 expiredToFlush", () => {
+    const registry = createRegistry();
+    const entries = [
+      registerEntry("bg-1", "subagent", "sess-root", { expiresAt: 1_000 + 1 }), // 远过去
+      registerEntry("wf-1", "workflow", "sess-root", { expiresAt: 1_000 + 1 }),
+      registerEntry("bt-1", "bash", "sess-root"), // 真实落盘形态：无 expiresAt 键
+    ];
+    const result = rebuildFromEntries(registry, entries, "sess-root", NOW);
+    // 旧 session 档语义（1h TTL + 跨 session 补注销）曾把长任务/跨重启注册静默
+    // 清除 → 守卫失明（事故环 4 放大器）；翻档后三类型全部续存。
+    expect(result.expiredToFlush).toEqual([]);
+    expect(result.activeIds).toEqual(["bg-1", "wf-1", "bt-1"]);
+  });
+});
+
+describe("[W6/D4 读侧过滤①] fork 继承残留 × countActiveFromEntries 基准", () => {
+  it("带基准（currentSessionId）→ 父 session 残留不入差集、本 session 注册计入", () => {
+    const entries = [
+      registerEntry("parent-bg", "subagent", "sess-parent"),
+      registerEntry("own-bg", "subagent", "sess-child"),
+      registerEntry("own-bt", "bash", "sess-child"),
+    ];
+    const result = countActiveFromEntries(entries, { currentSessionId: "sess-child" });
+    expect(result.ids).toEqual(["own-bg", "own-bt"]);
+  });
+
+  it("缺 sessionId 的旧形态条目视为本 session（宁放行不误杀——防误逐活跃计数）", () => {
+    const entries = [{ customType: "pending:register", data: { id: "legacy-bg", type: "subagent" } }];
+    expect(countActiveFromEntries(entries, { currentSessionId: "sess-child" }).ids).toEqual(["legacy-bg"]);
+  });
+});
+
+describe("[W6/R4 一刀] bash 跨 session 可见性显式断言（钉成显式选择的语义变更）", () => {
+  it("读侧过滤一刀后：子 session 的 goal 不再为父 session 的 bash 任务 defer（带基准口径）", () => {
+    // fork 继承：子 session entries 复制父 session 的 bash 后台任务注册
+    // （process 档跨 session 存活——U4 补注销对翻档类型不再中性化，残留永久留存）。
+    const childEntries = [
+      registerEntry("parent-bt", "bash", "sess-parent"),
+      registerEntry("child-bt", "bash", "sess-child"),
+    ];
+    // 设计选择（R4）：按当前 session 过滤——父 session 的 bash 任务不再让子
+    // session 的 goal 守卫 defer（子 session 有自己的等待域）。
+    const scoped = countActiveFromEntries(childEntries, { currentSessionId: "sess-child" });
+    expect(scoped.ids).toEqual(["child-bt"]);
+    expect(scoped.count).toBe(1); // 只数本 session 的任务
+  });
+
+  it("旧行为显式登记：无基准口径（goal 守卫现状）父 bash 残留仍入计数（= defer 驱动）", () => {
+    const childEntries = [registerEntry("parent-bt", "bash", "sess-parent")];
+    // 显式钉住「一刀的对照面」：不传基准 = 不过滤 = 子 session goal 仍为父 bash
+    // 任务 defer。这是读侧过滤一刀**改变的旧行为**——保留此断言防止有人误以为
+    // 过滤是缺省语义（偏差 #4：goal 消费点现状即此口径，见探针结论）。
+    expect(countActiveFromEntries(childEntries).count).toBe(1);
+  });
+});
+
+describe("[W6/D4 读侧过滤③] registry rebuild 投影（pending_notifications 工具读侧）", () => {
+  it("跨 session 残留不入 registry、不补 unregister entry（跳过不补注销——落盘收口归 core sweep）", () => {
+    const registry = createRegistry();
+    const entries = [
+      registerEntry("parent-bg", "subagent", "sess-parent"),
+      registerEntry("own-bg", "subagent", "sess-child"),
+    ];
+    const result = rebuildFromEntries(registry, entries, "sess-child", NOW);
+    // 工具投影面（count/list）不虚报继承残留（A9②：count/list 不含继承残留）。
+    expect(result.activeIds).toEqual(["own-bg"]);
+    expect(registry.operations.has("parent-bg")).toBe(false);
+    // 「跳过不补注销」：残留 entry 留在 session 文件（读侧①③口各自兜住差集消费
+    // 方），禁止 rebuild 写侧补发——跨 session 写达域缺口由 core 对账 sweep 收口。
+    expect(result.expiredToFlush).toEqual([]);
+  });
+});
+
+describe("[W6/偏差 #4 探针] goal 守卫口径（无基准）× fork 残留——实测结论", () => {
+  // 偏差 #4（impl-plan §5，W4 交接）：W4 读侧过滤①的 currentSessionId 为可选参数，
+  // goal 守卫消费点未传基准。本探针在 fork 场景实测该口径是否被父 session 注册
+  // 残留虚增，结论二选一回写报告：
+  //   (a) 无影响（其他机制覆盖）→ 偏差 #4 关闭，goal 零改动；
+  //   (b) 有虚增 → 列出确需的两行传参改动点（不改 goal——红线），留主会话裁决。
+  //
+  // **实测结论：(b) 有虚增。**
+  //   证据链：goal 守卫两处消费点现状均无基准调用——
+  //     `extensions/universal/goal/src/adapters/event-handlers/agent-end.ts:198`
+  //       `const pendingOps = countActiveFromEntries(entries);`（defer 分支判据
+  //        = `pendingOps.count > 0`）
+  //     `extensions/universal/goal/src/adapters/event-handlers/agent-end.ts:294`
+  //       `if (countActiveFromEntries(ctx.sessionManager.getEntries()).count > 0) return;`
+  //       （backoff 延迟发射前守卫）
+  //   下方用例 1 证明该口径在 fork 残留下 count>0 → defer 命中（幻 defer）；
+  //   用例 2 证明仅当父任务 record 已终态（core sweep 补注销落盘）才归零——
+  //   「父任务仍活跃」窗口内无任何机制覆盖（W4 翻档后 U4 不再中性化）。
+  //
+  //   确需的两行改动点（主会话裁决后由 goal 侧单元执行）：
+  //     agent-end.ts:198 → `countActiveFromEntries(entries, { currentSessionId: ctx.sessionManager.getSessionId() })`
+  //     agent-end.ts:294 → `countActiveFromEntries(ctx.sessionManager.getEntries(), { currentSessionId: ctx.sessionManager.getSessionId() })`
+  //   （getSessionId 是 extension 侧既有取 sessionId 形态——pending-notifications
+  //   index.ts:216、subagent-workflow session-lifecycle.ts 同款先例。）
+
+  it("用例 1：父 session 活跃 subagent 残留 → goal 现状口径（无基准）count>0 → defer 分支命中（虚增）", () => {
+    // fork 时刻快照：父 session 派了后台子代理（record 仍 running-resumable），
+    // 子 session 继承其 register 残留；goal 守卫读到的 entries = 本 session 文件
+    // 全量（含继承残留）。现状口径 = 无基准调用（agent-end.ts:198 逐字形态）。
+    const childEntries = [
+      registerEntry("parent-bg", "subagent", "sess-parent"),
+      registerEntry("child-bg", "subagent", "sess-child"),
+    ];
+    const pendingOps = countActiveFromEntries(childEntries); // ← goal 现状口径
+    // defer 分支判据（agent-end.ts:199 `if (pendingOps.count > 0)`）命中：
+    // 父 session 的任务让子 session 的 goal 停发 continuation 并 notify
+    // 「Goal waiting for 2 background task(s)」——计数含非本 session 任务 = 虚增。
+    expect(pendingOps.count).toBe(2);
+    expect(pendingOps.ids).toContain("parent-bg");
+  });
+
+  it("用例 2：父任务 record 终态后，core sweep 补注销落盘使现状口径归零（虚增仅限活跃窗口）", () => {
+    const dir = mkdtempSync(join(tmpdir(), "w6-goal-probe-sweep-"));
+    tmpDirs.push(dir);
+    const sessionFile = join(dir, "session-child.jsonl");
+    writeFileSync(
+      sessionFile,
+      `${JSON.stringify(registerEntry("parent-bg", "subagent", "sess-parent"))}\n`,
+      "utf8",
+    );
+    // 父任务 record 已终态（closed）：core 对账 sweep 差集补发——appendEntry 权威
+    // 落盘到子 session 文件（sweep 的注销对「无基准口径」也生效：差集读侧不过滤，
+    // 补发的 unregister entry 抵消 register）。
+    const result = runReconcileSweep({
+      sessionFile,
+      lookupRecordState: () => ({ terminal: true, closedReason: "completed" }),
+      appendEntry: (customType, data) => {
+        writeFileSync(sessionFile, `${JSON.stringify({ customType, data })}\n`, { flag: "a" });
+      },
+    });
+    expect(result.reconciled).toEqual(["parent-bg"]);
+
+    // 落盘后 goal 守卫（无基准口径）重读 entries：计数归零——sweep 是现状口径的
+    // 唯一收敛通道，且只覆盖「record 可判定终态」的窗口；「父任务仍活跃」窗口
+    // （用例 1）无机制覆盖 → 虚增结论 (b) 成立。
+    const entriesAfter = readFileSync(sessionFile, "utf8")
+      .trim()
+      .split("\n")
+      .map((l) => JSON.parse(l));
+    expect(countActiveFromEntries(entriesAfter).count).toBe(0);
+  });
+});

package/src/execution/engine/__tests__/conformance/round-liveness-supervisor.test.ts

@@ -0,0 +1,302 @@
+// round-liveness-supervisor.test.ts —— [W6] 轮次活性监督器的 conformance 黑盒场景。
+//
+// 设计权威源：chat-domain-v1x-liveness-governance.md §3.2 D2（record 去向单一裁决
+// 表 + 三态判定 + 通知对账 + 纳管模型）+ D5（H9 keep-alive-no-progress 承接落点）
+// + 验收 A2/A5/A8。
+//
+// 与 W4 单测（execution/__tests__/round-supervisor.test.ts）的分工：W4 用替身 deps
+// 全排列覆盖判定矩阵（白盒视角）；本套件是**语义钉住层**——把设计裁决表的场景链
+// （协议事件 → record 处置 → 监督动作）按黑盒视角钉成契约，只经公共出口
+// （`round-supervisor/index.ts`）消费，不 import 内部符号。每条链对应一个真实验收
+// 场景，替身 deps 是场景道具而非判定逻辑复制品：
+//
+//   场景一（表 3 行 1 全链，事故主链）：run 在途 → 引擎进程被 SIGTERM（crash
+//     message 形态取自 engine-crash.test.ts 的协议实证）→ noteRunEnded +
+//     adoptOnProcessDeath → 合并单条通知 + 决策指引（该唤醒）→ 看门狗到期 →
+//     该放弃（giveUp(watchdog-expired)，此时可重派）。
+//   场景二（裁决表 conversation 行）：chatMode record 死亡事件 → 豁免不纳管
+//     （轮终 idle / settled-watchdog 管辖，D2 前置 1）。
+//   场景三（表 3 行 2/3 × A5 落盘断言）：boot 分区重认领（already-resumable-idle）
+//     vs conversation 豁免；in-flight 直断后的注册残留由对账 sweep **appendEntry
+//     权威落盘**补发（A5「注销落盘可查」的构造性证据——sweep 写法钉死：不经 bus
+//     emit 作权威）。
+//   场景四（通知对账两级启发式，R4）：高置信替代 → 撤销指引改送终止通知 + 该放弃
+//     （superseded）；低置信 → 指引自带豁免声明。
+//   场景五（纳管模型：死亡事件纳管、重建不解管）：crash 纳管后引擎被动重建
+//     （镜像重填）不解除纳管、不重发指引——判定只消费 record 级状态。
+//
+// timer 用 fake timers；监督器对 fs 零依赖（场景三的 session file 由 sweep 读侧
+// 消费，mkdtempSync 自建自删）。
+
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  ROUND_SUPERVISOR_WATCHDOG_DEFAULT_MS,
+  RoundSupervisor,
+  runReconcileSweep,
+  type RoundSupervisorDeps,
+  type SupervisorCandidateRecord,
+  type SupervisorRecordView,
+} from "../../../round-supervisor/index.ts";
+import type { ExecutionRecord } from "../../../types.ts";
+
+// ── 场景道具（替身 deps——黑盒观测面：通知/指引/替代/放弃四出口 + 三状态源）────
+
+function makeDeps() {
+  const views = new Map<string, SupervisorRecordView>();
+  const candidates: SupervisorCandidateRecord[] = [];
+  const live = new Set<string>();
+  const notices: string[] = [];
+  const guidances: Array<{ record: SupervisorRecordView; exemptionDisclaimer: boolean }> = [];
+  const replaced: Array<{ record: SupervisorRecordView; replacementId: string }> = [];
+  const givenUp: Array<{ recordId: string; kind: string; detail: { replacementId?: string } }> = [];
+  const deps: RoundSupervisorDeps = {
+    now: () => Date.now(),
+    getRecordView: (id) => views.get(id),
+    listCandidateRecords: () => candidates,
+    hasLiveProcess: (recordId) => live.has(recordId),
+    sendMergedFailureNotice: (record) => notices.push(`merged:${record.id}`),
+    sendDecisionGuidance: (record, opts) =>
+      guidances.push({ record, exemptionDisclaimer: opts.exemptionDisclaimer }),
+    sendReplacedNotice: (record, replacementId) => replaced.push({ record, replacementId }),
+    giveUp: (recordId, kind, detail) => givenUp.push({ recordId, kind, detail }),
+  };
+  return Object.assign(deps, { views, candidates, live, notices, guidances, replaced, givenUp });
+}
+
+/** 后台子代理 record 替身（死亡事件纳管入口的入参形态）。 */
+function makeRecord(overrides: Partial<ExecutionRecord> = {}): ExecutionRecord {
+  return {
+    id: "bg-1",
+    agent: "worker",
+    model: "m",
+    mode: "background",
+    task: "t",
+    slug: "fix-bug",
+    startedAt: Date.now() - 1000,
+    status: "running",
+    resumable: true,
+    rootSessionId: "sess-root",
+    turnCount: 0,
+    ...overrides,
+  } as ExecutionRecord;
+}
+
+function viewOf(record: ExecutionRecord, overrides: Partial<SupervisorRecordView> = {}): SupervisorRecordView {
+  return {
+    id: record.id,
+    status: record.status === "closed" ? "closed" : "running",
+    resumable: record.resumable === true,
+    hasResult: record.result !== undefined,
+    chatMode: record.chatMode === true,
+    rootSessionId: record.rootSessionId,
+    agent: record.agent,
+    slug: record.slug,
+    startedAt: record.startedAt,
+    closedReason: record.closedReason,
+    ...overrides,
+  };
+}
+
+/**
+ * 引擎进程信号死亡的真实错误 message 形态（engine-crash.test.ts 的协议实证——
+ * EngineClient.onEngineExit signal 分支 → engineCrashedError）。
+ */
+const SIGTERM_CRASH_MESSAGE =
+  "engine_crashed: engine process exited unexpectedly: signal SIGTERM. stderr tail: (captured diagnostics)";
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("[W6/D2 表 3 行 1] 引擎死亡 → failed 如实 + 监督器接管（事故主链）", () => {
+  it("run 在途 → SIGTERM crash → 纳管：合并单条通知 + 决策指引（该唤醒）→ 看门狗到期 giveUp（该放弃）", async () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    const record = makeRecord();
+    deps.views.set(record.id, viewOf(record));
+
+    // 该等：run 在途（协议 run 帧受理——noteRunStarted 记账）→ 死亡事件前不干预。
+    supervisor.noteRunStarted(record.id);
+
+    // 死亡事件：run 终态 failed（engine_crashed，SIGTERM 形态）→ 驱动记账解除 +
+    // record 保持 resumable（subagent-service adoptResumableAfterEngineDeath 的
+    // 生产序列）→ 监督器纳管。
+    supervisor.noteRunEnded(record.id);
+    supervisor.adoptOnProcessDeath(record, SIGTERM_CRASH_MESSAGE);
+
+    // 表 3 行 1 通知契约：failed 如实 + 已接管契约合并为**单条**通知（无双通知
+    // 时序窗口）；主 agent 是唯一决策者——监督器不自动复活，只送决策指引。
+    expect(deps.notices).toEqual([`merged:${record.id}`]);
+    expect(deps.guidances).toHaveLength(1);
+    expect(deps.guidances[0].exemptionDisclaimer).toBe(false);
+    expect(supervisor.supervisedIds()).toEqual([record.id]);
+
+    // 该唤醒后的等待有主：决策看门狗 armed（默认 2h）——到期且无决策/无收敛 →
+    // 该放弃（failed 终态化 + 注销 + 终止通知，此时可重派）。
+    await vi.advanceTimersByTimeAsync(ROUND_SUPERVISOR_WATCHDOG_DEFAULT_MS + 1);
+    expect(deps.givenUp).toEqual([{ recordId: record.id, kind: "watchdog-expired", detail: {} }]);
+    expect(supervisor.supervisedIds()).toEqual([]);
+  });
+
+  it("死亡事件重复（二次 crash 事件）幂等：不重复通知、不重复指引", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    const record = makeRecord();
+    deps.views.set(record.id, viewOf(record));
+    supervisor.adoptOnProcessDeath(record, SIGTERM_CRASH_MESSAGE);
+    supervisor.adoptOnProcessDeath(record, SIGTERM_CRASH_MESSAGE);
+    expect(deps.notices).toHaveLength(1);
+    expect(deps.guidances).toHaveLength(1);
+  });
+});
+
+describe("[W6/D2 裁决表 conversation 行] chat 域豁免", () => {
+  it("chatMode record 的死亡事件不入监督域（轮终 idle / settled-watchdog 管辖）", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    supervisor.adoptOnProcessDeath(makeRecord({ chatMode: true, resumable: true }), SIGTERM_CRASH_MESSAGE);
+    expect(deps.notices).toHaveLength(0);
+    expect(deps.guidances).toHaveLength(0);
+    expect(supervisor.supervisedIds()).toEqual([]);
+  });
+});
+
+describe("[W6/D2 表 3 行 2/3 × A5] boot 分区与 sweep 落盘衔接", () => {
+  it("already-resumable-idle（非 conversation）→ 重认领接管并送达指引", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    const record = makeRecord({ id: "bg-survivor" });
+    deps.candidates.push({ id: record.id, rootSessionId: record.rootSessionId, agent: record.agent, slug: record.slug, startedAt: record.startedAt });
+    deps.views.set(record.id, viewOf(record));
+    const { readopted } = supervisor.bootPartition();
+    expect(readopted).toEqual([record.id]);
+    expect(deps.guidances).toHaveLength(1);
+    expect(supervisor.supervisedIds()).toEqual([record.id]);
+  });
+
+  it("in-flight 直断后的注册残留 → 对账 sweep appendEntry 权威落盘（A5「注销落盘可查」）", () => {
+    const dir = mkdtempSync(join(tmpdir(), "w6-supervisor-sweep-"));
+    try {
+      const sessionFile = join(dir, "session-child.jsonl");
+      // 子 session 文件里的 register 残留（进程死亡窗口内注销发射源已消失——
+      // notify-host getPi() 为 null 的缺位形态）。
+      writeFileSync(
+        sessionFile,
+        `${JSON.stringify({ customType: "pending:register", data: { id: "bg-inflight", type: "subagent", name: "worker", sessionId: "sess-root" } })}\n`,
+        "utf8",
+      );
+      const appended: Array<{ customType: string; data: unknown }> = [];
+      const result = runReconcileSweep({
+        sessionFile,
+        lookupRecordState: (id) =>
+          id === "bg-inflight" ? { terminal: true, closedReason: "boot-abort" } : "active",
+        appendEntry: (customType, data) => {
+          appended.push({ customType, data });
+          // 权威落盘 = 直接 appendEntry（写法钉死：不经 bus emit 作权威）——
+          // 用真实文件追加复现「落盘可查」。
+          writeFileSync(
+            sessionFile,
+            `${JSON.stringify({ customType, data })}\n`,
+            { flag: "a" },
+          );
+        },
+      });
+      expect(result.reconciled).toEqual(["bg-inflight"]);
+      expect(appended).toHaveLength(1);
+      expect(appended[0].customType).toBe("pending:unregister");
+      // 差集消费方（goal 守卫）从持久化 entries 算差集——文件里补发的 unregister
+      // 对守卫直接生效（守卫计数归零，A5 断言「重开后守卫计数归零」）。
+      const lines = readFileSync(sessionFile, "utf8").trim().split("\n").map((l) => JSON.parse(l));
+      expect(lines.some((l) => l.customType === "pending:unregister" && l.data.id === "bg-inflight")).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+    }
+  });
+
+  it("sweep 保守性：record 仍活跃的注册跳过（不误注销活跃后台任务）", () => {
+    const dir = mkdtempSync(join(tmpdir(), "w6-supervisor-sweep-active-"));
+    try {
+      const sessionFile = join(dir, "session-child.jsonl");
+      writeFileSync(
+        sessionFile,
+        `${JSON.stringify({ customType: "pending:register", data: { id: "bg-alive", type: "subagent", name: "worker", sessionId: "sess-root" } })}\n`,
+        "utf8",
+      );
+      const result = runReconcileSweep({
+        sessionFile,
+        lookupRecordState: () => "active",
+      });
+      expect(result.reconciled).toEqual([]);
+      expect(result.skippedActive).toEqual(["bg-alive"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+    }
+  });
+});
+
+describe("[W6/D2 通知对账（R4 两级启发式）]", () => {
+  it("高置信替代（同 root + 同 agent + 同 slug + 窗内）→ 撤销指引改送终止通知 + 该放弃(superseded)", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    const record = makeRecord();
+    deps.views.set(record.id, viewOf(record));
+    // 主 agent 在指引送达前已重派同任务（唯一决策者，重派合法）。
+    deps.candidates.push({ id: "bg-2", rootSessionId: "sess-root", agent: "worker", slug: "fix-bug", startedAt: Date.now() - 1000 });
+
+    supervisor.adoptOnProcessDeath(record, SIGTERM_CRASH_MESSAGE);
+
+    expect(deps.guidances).toHaveLength(0); // 指引撤销（无双执行残径）
+    expect(deps.replaced).toHaveLength(1);
+    expect(deps.replaced[0].replacementId).toBe("bg-2");
+    expect(deps.givenUp).toEqual([{ recordId: record.id, kind: "superseded", detail: { replacementId: "bg-2" } }]);
+    expect(supervisor.supervisedIds()).toEqual([]);
+  });
+
+  it("低置信（仅 agent 同名）→ 不撤销指引，指引自带豁免声明（残余决策交还主 agent）", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    const record = makeRecord();
+    deps.views.set(record.id, viewOf(record));
+    deps.candidates.push({ id: "bg-2", rootSessionId: "sess-root", agent: "worker", slug: "other-task", startedAt: Date.now() - 1000 });
+
+    supervisor.adoptOnProcessDeath(record, SIGTERM_CRASH_MESSAGE);
+
+    expect(deps.guidances).toHaveLength(1);
+    expect(deps.guidances[0].exemptionDisclaimer).toBe(true);
+    expect(deps.givenUp).toHaveLength(0);
+  });
+});
+
+describe("[W6/D2 纳管模型] 死亡事件纳管、重建不解管", () => {
+  it("crash 纳管后引擎被动重建（镜像重填再置死）不解除纳管、不重发指引", async () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    const record = makeRecord();
+    deps.views.set(record.id, viewOf(record));
+
+    supervisor.adoptOnProcessDeath(record, SIGTERM_CRASH_MESSAGE);
+    expect(deps.guidances).toHaveLength(1);
+
+    // 引擎被动重建（ensureConnected 退避重填镜像——任一会话的下个请求触发）：
+    // 镜像判「该等」仅解除看门狗计时；record 级状态未变 → 纳管持续、指引不重发。
+    deps.live.add(record.id);
+    supervisor.noteRunEnded(record.id);
+    expect(supervisor.supervisedIds()).toEqual([record.id]);
+    expect(deps.guidances).toHaveLength(1);
+
+    // 重建后的进程又死（镜像再置死）——判定仍只消费 record 级状态。
+    deps.live.delete(record.id);
+    supervisor.noteRunEnded(record.id);
+    expect(supervisor.supervisedIds()).toEqual([record.id]);
+    expect(deps.guidances).toHaveLength(1);
+    expect(deps.givenUp).toHaveLength(0);
+  });
+});

package/src/execution/engine/__tests__/conformance/static-spawn-guard.test.ts

@@ -0,0 +1,58 @@
+// static-spawn-guard.test.ts —— W10 静态断言「任务子进程 spawn 必经 SDK
+// spawnEngineChild」的 CI 挂载点（vitest 内执行 scripts/check-engine-spawn-guard.mjs，
+// 不依赖 W9 的 workflows 领地；进 CI invariants job 的落点与 W9 协调——本地经本
+// 测试即恒绿门）。
+//
+// 正例：两引擎包 src 干净 + 存在 spawnEngineChild 消费点（防空转）。
+// 负例：临时 root 内放置直接 spawn 的源文件 → 脚本必须红（守卫有牙，A12 同款
+// 负例自证）。
+//
+// 与 C-proc-09（check_spawn_env_boundary.py）分工互不代偿：C-proc-09 盖 spawn 点
+// env 出站卫生（全仓），本守卫盖引擎包 spawn 单一入口（形态 + stdin fd 不外泄）。
+
+import { execFile } from "node:child_process";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { afterEach, describe, expect, it } from "vitest";
+
+const execFileAsync = promisify(execFile);
+const GUARD = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../../../scripts/check-engine-spawn-guard.mjs",
+);
+
+let tmpRoots: string[] = [];
+
+afterEach(() => {
+  for (const root of tmpRoots) rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  tmpRoots = [];
+});
+
+describe("静态断言：引擎包任务子进程必经 spawnEngineChild", () => {
+  it("正例：两引擎包 src 干净且存在 spawnEngineChild 消费点", async () => {
+    const { stdout } = await execFileAsync("node", [GUARD]);
+    expect(stdout).toContain("[engine-spawn-guard] PASS");
+    expect(stdout).toMatch(/spawnEngineChild/);
+  });
+
+  it("负例：直接 spawn 的源文件必须被检出（守卫有牙）", async () => {
+    const root = mkdtempSync(join(tmpdir(), "spawn-guard-neg-"));
+    tmpRoots.push(root);
+    mkdirSync(join(root, "__tests__"), { recursive: true });
+    // __tests__ 排除面（测试文件可用 child_process mock）——放一个不触发的样本
+    writeFileSync(join(root, "__tests__", "mock.test.ts"), 'import { spawn } from "node:child_process";\n');
+    // src 直陈违规：直接 spawn（未走 SDK spawnEngineChild）
+    mkdirSync(join(root, "engine"), { recursive: true });
+    writeFileSync(
+      join(root, "engine", "bypass.ts"),
+      'import { spawn } from "node:child_process";\nexport const p = spawn("ls");\n',
+    );
+    await expect(execFileAsync("node", [GUARD, "--roots", root])).rejects.toMatchObject({
+      code: 1,
+      stderr: expect.stringContaining("spawn"),
+    });
+  });
+});