@zhushanwen/subagent-core 0.6.0 → 0.7.0

package/src/execution/engine/__tests__/conformance/golden-replay.zcode.test.ts

@@ -1,6 +1,6 @@
 // golden-replay.zcode.test.ts —— zcode 引擎 golden 回放层（conformance 免 LLM 默认
 // CI 层）。语料 = app-server NDJSON 帧序列（附录 A.2 任务生命周期帧序；采集 SSOT
-// = engines/zcode/__tests__/__fixtures__/zcode-golden-appserver.json）——双副本 diff
+// = @zhushanwen/zcode-subagent-cli src/__golden__/zcode-golden-appserver.json）——双副本 diff
 // 校验（fixture 与 golden-sample.ts 内嵌副本一致，防漂移：更新样本必须同步两处，
 // 探针的干跑校验消费内嵌副本，两处不一致 = 探针在测旧契约）+ 帧形态不变量断言
 // （A8「golden 帧序列语料 diff 通过」的本仓段）。
@@ -15,13 +15,14 @@ import { fileURLToPath } from "node:url";
 
 import { describe, expect, it } from "vitest";
 
-import { ZCODE_APPSERVER_GOLDEN } from "../../engines/zcode/golden-sample.ts";
+// 基线三层②（W10）：引擎层 golden 随引擎包——内嵌副本经 zcode 包公共导出面
+// 消费，fixture SSOT = zcode 包 src/__golden__/（core 不再深路径 import 内建副本）。
+import { ZCODE_APPSERVER_GOLDEN } from "@zhushanwen/zcode-subagent-cli";
 
-// conformance 目录（engine/__tests__/conformance）→ engine 根的相对定位
+// conformance 目录（engine/__tests__/conformance）→ 引擎包 __golden__ 的相对定位
 const appserverFixturePath = join(
   dirname(fileURLToPath(import.meta.url)),
-  "..", "..", // conformance → __tests__ → engine
-  "engines", "zcode", "__tests__", "__fixtures__", "zcode-golden-appserver.json",
+  "../../../../../../zcode-subagent-cli/src/__golden__", "zcode-golden-appserver.json",
 );
 
 interface AppServerGoldenFile {

package/src/execution/engine/__tests__/conformance/protocol-blackbox.test.ts

@@ -0,0 +1,398 @@
+// protocol-blackbox.test.ts —— W10 协议黑盒套件（基线三层①的自动层）。
+//
+// 覆盖（impl-plan §2.10 / 设计 §4 探针挂钩①）：
+//   - 10 正向方法（initialize/probe/run/cancel/interact/read/listModels/
+//     validateModel/dispose/ping）× fake 引擎 CLI 往返；
+//   - 8 反向通道（host/log、host/askUser、host/permission、host/streamDelta、
+//     host/poolResolved、host/handleReady、host/childSpawned、host/childStateChanged）
+//     的 core 侧到达断言；
+//   - 错误帧：run 失败帧 / 未知方法帧（码原样透传）/ initialize 版本越界
+//     （engine_protocol_mismatch → 客户端直接不可用，不重建）；
+//   - fixture 回放结构等价：事件类型序列 / 顺序 / seq 单调 / 字段白名单逐字段比对
+//     （排除 text_delta 文本内容等不可复现字段——设计 §4 基线三层①）+ journal 往返
+//     保真 + assertAgentEventInvariants；
+//   - POSIX 组探测（R9-4/A3 前提）：childSpawned 上报的 pid 做 kill(-pid, 0)，
+//     不在同组即告警——本套件验证探测通路；Windows 无外部判据，仅 SDK 层保证
+//     （显式登记，见文件末 describe 与 deviations）。
+//
+// 措辞统一（R9-1）：「子进程零残留」一律指一代子进程 + 组内后代；引擎自身
+// detached 后代不判 fail（设计 §3.9 已接受代价）。
+
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { EngineClient } from "../../client/engine-client.ts";
+import type { MirrorChangeEvent } from "../../client/mirror.ts";
+import { JournalWriter, replayJournal } from "../../common/event-journal.ts";
+import type { AgentEvent } from "../../../types.ts";
+import { assertAgentEventInvariants } from "./agent-event-invariants.ts";
+
+const FIXTURE_DIR = join(dirname(fileURLToPath(import.meta.url)), "__fixtures__", "engine-protocol");
+const FAKE_ENGINE = join(FIXTURE_DIR, "fake-engine-protocol.mjs");
+const FIXTURE = join(FIXTURE_DIR, "smoke-run.fixture.json");
+
+/** fixture 的白名单可比形态（record:engine-fixtures 产物 schema v1）。 */
+interface EngineProtocolFixture {
+  schemaVersion: number;
+  engineId: string;
+  protocolVersion: number;
+  run: {
+    params: { runId: string; ctx: Record<string, unknown> };
+    result: { handle: Record<string, unknown>; outcome: Record<string, unknown> };
+  };
+  events: Array<{ type: string }>;
+}
+
+const fixture: EngineProtocolFixture = JSON.parse(readFileSync(FIXTURE, "utf8"));
+if (fixture.schemaVersion !== 1) {
+  throw new Error(`unsupported fixture schemaVersion ${String(fixture.schemaVersion)}`);
+}
+
+/** AgentEvent 字段白名单（结构等价比对的逐字段面；text_delta.delta 内容显式排除）。 */
+const FIELD_WHITELIST: Record<string, readonly string[]> = {
+  text_delta: ["type", "delta"],
+  message_end: ["type", "usage"],
+  turn_end: ["type", "usage"],
+  error: ["type", "message"],
+  tool_start: ["type", "toolName", "input"],
+  tool_end: ["type", "toolName", "output", "isError"],
+};
+
+let dataDir: string;
+
+beforeEach(() => {
+  dataDir = mkdtempSync(join(tmpdir(), "w10-engine-protocol-"));
+});
+
+afterEach(() => {
+  rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+});
+
+interface Harness {
+  client: EngineClient;
+  events: AgentEvent[];
+  mirrorEvents: MirrorChangeEvent[];
+  logs: Array<{ level: string; message: string }>;
+  askUserRequests: unknown[];
+  permissionRequests: unknown[];
+  streamDeltas: string[];
+  poolResolved: string[];
+  handleReady: Array<{ sessionRef: Record<string, string>; poolKey: string }>;
+}
+
+function makeHarness(extraEnv: Record<string, string> = {}, routeRunId = fixture.run.params.runId): Harness {
+  const h: Harness = {
+    client: undefined as unknown as EngineClient,
+    events: [],
+    mirrorEvents: [],
+    logs: [],
+    askUserRequests: [],
+    permissionRequests: [],
+    streamDeltas: [],
+    poolResolved: [],
+    handleReady: [],
+  };
+  h.client = new EngineClient({
+    engineId: fixture.engineId,
+    command: process.execPath,
+    args: [FAKE_ENGINE],
+    hostKind: "test",
+    hostVersion: "w10-protocol-blackbox",
+    dataDir,
+    envPrefixes: [],
+    log: (p) => h.logs.push({ level: p.level, message: p.message }),
+    uiRequestHandler: async (req) => {
+      h.askUserRequests.push(req);
+      return { value: "option-a" };
+    },
+    permissionHandler: async (params) => {
+      h.permissionRequests.push(params);
+      return { approved: true };
+    },
+    onMirrorChanged: (event) => h.mirrorEvents.push(event),
+    baseEnv: {
+      ...process.env,
+      FAKE_PROTOCOL_FIXTURE: FIXTURE,
+      ...extraEnv,
+    },
+  });
+  const unregister = h.client.registerRunRoute(routeRunId, {
+    onEvent: (event) => {
+      h.events.push(event as AgentEvent);
+    },
+    onStreamDelta: (delta) => {
+      h.streamDeltas.push(delta);
+    },
+    onPoolResolved: (poolKey) => {
+      h.poolResolved.push(poolKey);
+    },
+    onHandleReady: (partial) => {
+      h.handleReady.push(partial);
+    },
+  });
+  void unregister;
+  return h;
+}
+
+describe("协议黑盒：10 正向方法 × fake 引擎回放", () => {
+  it("initialize/probe/listModels/validateModel/interact/read/ping 往返（fixture 白名单比对）", async () => {
+    const h = makeHarness();
+    try {
+      await h.client.ensureConnected();
+      expect(h.client.currentState).toBe("ready");
+
+      const probe = (await h.client.request("probe", {}, { timeoutMs: 5_000 })) as {
+        ok: boolean; checks: Array<{ name: string; ok: boolean }>;
+      };
+      expect(probe.ok).toBe(true);
+      expect(probe.checks.every((c) => typeof c.name === "string" && typeof c.ok === "boolean")).toBe(true);
+
+      const models = (await h.client.request("listModels", {}, { timeoutMs: 5_000 })) as {
+        models: Array<{ id: string }>;
+      };
+      expect(models.models.map((m) => m.id)).toEqual(["fake-1"]);
+
+      const validated = (await h.client.request(
+        "validateModel",
+        { modelRef: "fake/fake-1" },
+        { timeoutMs: 5_000 },
+      )) as { canonicalRef: string };
+      expect(validated.canonicalRef).toBe("fake/fake-1");
+
+      const interact = (await h.client.request(
+        "interact",
+        { handle: fixture.run.result.handle, action: { kind: "message", text: "hi" } },
+        { timeoutMs: 5_000 },
+      )) as { accepted: boolean };
+      expect(interact.accepted).toBe(true);
+
+      const view = (await h.client.request(
+        "read",
+        { handle: fixture.run.result.handle, dataDir },
+        { timeoutMs: 5_000 },
+      )) as { entries: unknown[] };
+      expect(Array.isArray(view.entries)).toBe(true);
+
+      await h.client.ping(); // 诊断面：不 throw 即通
+    } finally {
+      await h.client.dispose();
+    }
+  });
+
+  it("run：终态应答 handle+outcome 与 fixture 白名单逐字段一致", async () => {
+    const h = makeHarness();
+    try {
+      await h.client.ensureConnected();
+      const result = (await h.client.request("run", fixture.run.params)) as {
+        handle: Record<string, unknown>;
+        outcome: Record<string, unknown>;
+      };
+      expect(result.handle).toEqual(fixture.run.result.handle);
+      expect(result.outcome).toEqual(fixture.run.result.outcome);
+    } finally {
+      await h.client.dispose();
+    }
+  });
+
+  it("cancel：受理应答（收敛语义由 W2 client 套件的 3s 窗口用例覆盖，此处断言帧往返）", async () => {
+    const h = makeHarness();
+    try {
+      await h.client.ensureConnected();
+      const ack = (await h.client.request(
+        "cancel",
+        { runId: "run-smoke-1", reason: "test" },
+        { timeoutMs: 5_000 },
+      )) as { ok: boolean };
+      expect(ack.ok).toBe(true);
+    } finally {
+      await h.client.dispose();
+    }
+  });
+
+  it("dispose：幂等收口（应答 ok + 进程退出）", async () => {
+    const h = makeHarness();
+    await h.client.ensureConnected();
+    const r = (await h.client.request("dispose", {}, { timeoutMs: 5_000 })) as { ok: boolean };
+    expect(r.ok).toBe(true);
+    await h.client.dispose();
+    await expect(h.client.dispose()).resolves.toBeUndefined();
+  });
+});
+
+describe("协议黑盒：8 反向通道 core 侧到达", () => {
+  it("run 期间全部 8 通道到达并被正确路由", async () => {
+    const h = makeHarness();
+    try {
+      await h.client.ensureConnected();
+      await h.client.request("run", fixture.run.params);
+
+      // host/log
+      expect(h.logs.some((l) => l.message.includes("run started"))).toBe(true);
+      // host/streamDelta
+      expect(h.streamDeltas).toEqual(["Hello", " world"]);
+      // host/poolResolved
+      expect(h.poolResolved).toEqual(["shared"]);
+      // host/handleReady
+      expect(h.handleReady).toEqual([{ sessionRef: { sessionId: "sess-fixture" }, poolKey: "shared" }]);
+      // host/childSpawned + host/childStateChanged（镜像落项 + 状态更新）
+      const spawned = h.mirrorEvents.filter((e) => e.reason === "childSpawned");
+      expect(spawned).toHaveLength(1);
+      expect(typeof spawned[0]?.pid).toBe("number");
+      const stateChanged = h.mirrorEvents.filter((e) => e.reason === "childStateChanged");
+      expect(stateChanged).toHaveLength(1);
+      expect(stateChanged[0]?.recordId).toBe(fixture.run.params.runId);
+      // host/askUser + host/permission（交互面 ack 两阶段）
+      expect(h.askUserRequests).toHaveLength(1);
+      expect(h.permissionRequests).toHaveLength(1);
+    } finally {
+      await h.client.dispose();
+    }
+  });
+});
+
+describe("协议黑盒：错误帧", () => {
+  it("run 失败帧 → EngineSdkError（code/message/recovery 透传）", async () => {
+    const h = makeHarness({ FAKE_PROTOCOL_ERROR: "run_failed" });
+    try {
+      await h.client.ensureConnected();
+      await expect(h.client.request("run", fixture.run.params)).rejects.toMatchObject({
+        code: "engine_run_failed",
+        message: expect.stringContaining("scripted run failure"),
+      });
+    } finally {
+      await h.client.dispose();
+    }
+  });
+
+  it("未知方法帧 → 错误码原样透传（帧形态权威，非码表枚举）", async () => {
+    const h = makeHarness({ FAKE_PROTOCOL_ERROR: "unknown_method" });
+    try {
+      await h.client.ensureConnected();
+      await expect(h.client.request("bogus/method", {}, { timeoutMs: 5_000 })).rejects.toMatchObject({
+        code: "engine_method_unknown",
+      });
+    } finally {
+      await h.client.dispose();
+    }
+  });
+
+  it("initialize 版本越界 → engine_protocol_mismatch + 客户端直接不可用（不重建）", async () => {
+    const h = makeHarness({ FAKE_PROTOCOL_VERSION: "99" });
+    try {
+      await expect(h.client.ensureConnected()).rejects.toMatchObject({ code: "engine_protocol_mismatch" });
+      expect(h.client.currentState).toBe("unavailable");
+    } finally {
+      await h.client.dispose();
+    }
+  });
+});
+
+describe("协议黑盒：fixture 回放结构等价（基线三层①）", () => {
+  it("事件类型序列/顺序/seq 单调/字段白名单（排除 text_delta 文本内容）", async () => {
+    const h = makeHarness();
+    try {
+      await h.client.ensureConnected();
+      const result = (await h.client.request("run", fixture.run.params)) as {
+        outcome: { content: string };
+      };
+
+      // ① 类型序列 + 顺序（与 fixture.events 白名单形态逐项一致）
+      expect(h.events.map((e) => e.type)).toEqual(fixture.events.map((e) => e.type));
+
+      // ② seq 单调（协议通知帧的 seq 字段经 fake 引擎按 fixture 播放）
+      //    ——事件流本身不透传 seq，单调性由通知帧序承担；此处断言到达顺序稳定。
+
+      // ③ 字段白名单：每条事件的实际键 ⊆ 白名单
+      for (const event of h.events) {
+        const whitelist = FIELD_WHITELIST[event.type];
+        expect(whitelist, `missing whitelist for event type ${event.type}`).toBeDefined();
+        for (const key of Object.keys(event)) {
+          expect(whitelist).toContain(key);
+        }
+      }
+
+      // ④ 排除项自证：text_delta 文本内容参与流式拼接不变量（3a），但内容本身
+      //    不做逐字段 diff（不可复现字段——设计 §4）
+      assertAgentEventInvariants(h.events, { granularity: "stream", content: result.outcome.content });
+
+      // ⑤ journal 往返保真（回放层事件落 journal 后重读等价）
+      const journalPath = join(dataDir, "blackbox-journal.jsonl");
+      const writer = new JournalWriter({
+        path: journalPath,
+        taskId: "w10-blackbox",
+        engineId: fixture.engineId,
+      });
+      for (const event of h.events) writer.append(event);
+      await writer.close();
+      const replayed = replayJournal(journalPath) as AgentEvent[];
+      expect(replayed.map((e) => e.type)).toEqual(h.events.map((e) => e.type));
+      expect(JSON.stringify(replayed)).toBe(JSON.stringify(h.events));
+    } finally {
+      await h.client.dispose();
+    }
+  });
+
+  it("录制产物回放校验：recorded.fixture.json（record:engine-fixtures 产物）结构不变量", async () => {
+    // 录制/复跑闭环（设计 §4）：录制脚本产物 schemaVersion 1 + 脱敏不变量 +
+    // 事件通知 seq 单调 + 反向通道覆盖。真机引擎录制时产物替换本文件即可把同一
+    // 套结构断言升格为该引擎的协议层基线（不逐字段 diff 正文）。
+    const recorded = JSON.parse(
+      readFileSync(join(FIXTURE_DIR, "recorded.fixture.json"), "utf8"),
+    ) as {
+      schemaVersion: number;
+      wire: {
+        engineToHost: Array<{ method?: string; params?: { seq?: number; runId?: string } }>;
+        hostToEngine: Array<{ id: number | string; method: string }>;
+      };
+      events: Array<{ type: string }>;
+    };
+    expect(recorded.schemaVersion).toBe(1);
+
+    // 事件通知 seq 单调（同 runId）
+    const seqs = recorded.wire.engineToHost
+      .filter((f) => f.method === "event" && typeof f.params?.seq === "number")
+      .map((f) => f.params!.seq!);
+    expect(seqs).toEqual([...seqs].sort((a, b) => a - b));
+
+    // 反向通道覆盖（录制期间 8 通道全部上线）
+    const reverse = new Set(
+      recorded.wire.engineToHost
+        .filter((f) => typeof (f as { id?: string }).id === "string")
+        .map((f) => (f as { method: string }).method),
+    );
+    for (const ch of [
+      "host/log", "host/askUser", "host/permission", "host/streamDelta",
+      "host/poolResolved", "host/handleReady", "host/childSpawned", "host/childStateChanged",
+    ]) {
+      expect(reverse.has(ch)).toBe(true);
+    }
+
+    // 结构白名单形态与 curated fixture 同源
+    expect(recorded.events).toEqual(fixture.events);
+  });
+
+  it("POSIX 组探测：childSpawned 上报 pid 非组长（在引擎收割组内；A3 前提；Windows 显式跳过）", async () => {
+    if (process.platform === "win32") {
+      // Windows 无外部组判据（无 kill(-pid,0) 等价物）——仅 SDK 层 spawnEngineChild
+      // 的 detached/stdio 规约保证，真机面挂 A3 手动门（taskkill /T /F 形态）。
+      return;
+    }
+    const h = makeHarness();
+    try {
+      await h.client.ensureConnected();
+      await h.client.request("run", fixture.run.params);
+      const spawned = h.mirrorEvents.find((e) => e.reason === "childSpawned");
+      expect(spawned?.pid).toBeDefined();
+      // 预期形态（reverse-router 组探测同款语义）：任务子进程与引擎同组（收割 =
+      // 引擎组级 kill(-enginePid)）→ 该 pid 非组长 → kill(-pid,0) ESRCH。
+      // kill(-pid,0) 成功 = 自成进程组 = 不在收割组内 = 告警面（R9-1 限定：一代
+      // 子进程 + 组内后代；引擎自身 detached 后代不判 fail，设计 §3.9 已接受代价）。
+      expect(() => process.kill(-spawned!.pid!, 0)).toThrow();
+    } finally {
+      await h.client.dispose();
+    }
+  });
+});

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);
+  });
+});