@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/execution/__tests__/round-supervisor.test.ts

@@ -0,0 +1,293 @@
+// src/execution/__tests__/round-supervisor.test.ts
+//
+// [W4] 轮次活性监督器单测：三态判定（该等/该唤醒/该放弃）、纳管模型（死亡事件
+// 纳管、重建不解管——镜像置死只作触发信号不作持续判据）、boot 分区（重认领 vs
+// conversation 豁免 vs in-flight 跳过）、通知对账两级启发式（高置信撤销改送终止
+// 通知 / 低置信豁免声明）。timer 用 fake timers；deps 全部替身注入（不触真实
+// 数据目录——监督器对 fs 零依赖）。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { ExecutionRecord } from "../types.ts";
+import { RoundSupervisor, ROUND_SUPERVISOR_WATCHDOG_DEFAULT_MS, type RoundSupervisorDeps, type SupervisorCandidateRecord, type SupervisorRecordView } from "../round-supervisor/index.ts";
+
+function makeDeps(overrides: Partial<RoundSupervisorDeps> = {}): RoundSupervisorDeps & {
+  notices: string[];
+  guidances: Array<{ record: SupervisorRecordView; exemptionDisclaimer: boolean }>;
+  replaced: Array<{ record: SupervisorRecordView; replacementId: string }>;
+  givenUp: Array<{ recordId: string; kind: string; detail: { replacementId?: string } }>;
+  views: Map<string, SupervisorRecordView>;
+  candidates: SupervisorCandidateRecord[];
+  live: Set<string>;
+} {
+  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, { notices, guidances, replaced, givenUp, views, candidates, live });
+}
+
+/** 内存 record 替身（adoptOnProcessDeath 入参形态——字段访问面最小化）。 */
+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;
+}
+
+describe("RoundSupervisor 三态判定", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("该等：有活进程驱动 → 不干预（无指引、无放弃）", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    deps.views.set("bg-1", { id: "bg-1", status: "running", resumable: true, hasResult: false, chatMode: false, rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1, closedReason: undefined });
+    deps.live.add("bg-1");
+    supervisor.adoptOnProcessDeath(makeRecord(), "boom");
+    expect(deps.guidances).toHaveLength(0);
+    expect(deps.givenUp).toHaveLength(0);
+  });
+
+  it("该等：在途 run 记账（noteRunStarted）→ 不干预；noteRunEnded 后重评估", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    deps.views.set("bg-1", { id: "bg-1", status: "running", resumable: true, hasResult: false, chatMode: false, rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1, closedReason: undefined });
+    supervisor.noteRunStarted("bg-1");
+    supervisor.adoptOnProcessDeath(makeRecord(), "boom");
+    expect(deps.guidances).toHaveLength(0);
+    supervisor.noteRunEnded("bg-1");
+    expect(deps.guidances).toHaveLength(1);
+  });
+
+  it("该唤醒：resumable 未终态 且 无在途 run/无进程驱动 → 决策指引（一窗一次）+ 看门狗 armed", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    deps.views.set("bg-1", { id: "bg-1", status: "running", resumable: true, hasResult: false, chatMode: false, rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1, closedReason: undefined });
+    supervisor.adoptOnProcessDeath(makeRecord(), "engine crashed");
+    expect(deps.notices).toEqual(["merged:bg-1"]); // 合并单条通知（failed 如实 + 接管契约）
+    expect(deps.guidances).toHaveLength(1);
+    expect(deps.guidances[0].exemptionDisclaimer).toBe(false);
+    // 重复死亡事件不重复通知、不重复指引（幂等）
+    supervisor.adoptOnProcessDeath(makeRecord(), "again");
+    expect(deps.notices).toHaveLength(1);
+    expect(deps.guidances).toHaveLength(1);
+    expect(supervisor.supervisedIds()).toEqual(["bg-1"]);
+  });
+
+  it("[重建不解管] 镜像重填再置死（引擎被动重建）不翻转判定：指引仍只送一次、纳管持续", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    deps.views.set("bg-1", { id: "bg-1", status: "running", resumable: true, hasResult: false, chatMode: false, rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1, closedReason: undefined });
+    // 死亡事件纳管时镜像已置死（hasLiveProcess=false）→ 该唤醒。
+    supervisor.adoptOnProcessDeath(makeRecord(), "engine crashed");
+    expect(deps.guidances).toHaveLength(1);
+    // 模拟引擎被动重建：任一会话的下个请求触发 ensureConnected → 镜像重填（live=true）
+    deps.live.add("bg-1");
+    supervisor.noteRunEnded("bg-1"); // 重建后的重评估——镜像判「该等」仅解除看门狗
+    expect(deps.guidances).toHaveLength(1); // 指引不重发（已在窗内）
+    expect(supervisor.supervisedIds()).toEqual(["bg-1"]); // 纳管未解除（重建不解管）
+    // 镜像再置死（重建的进程又死）：record 级状态未变 → 监督器继续管辖（不重复指引）
+    deps.live.delete("bg-1");
+    supervisor.noteRunEnded("bg-1");
+    expect(deps.guidances).toHaveLength(1);
+    expect(supervisor.supervisedIds()).toEqual(["bg-1"]);
+  });
+
+  it("已有完成产出（SP-5 upgrade 等待态）→ 不唤醒", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    deps.views.set("bg-1", { id: "bg-1", status: "running", resumable: true, hasResult: true, chatMode: false, rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1, closedReason: undefined });
+    supervisor.adoptOnProcessDeath(makeRecord({ result: "done text" }), "x");
+    expect(deps.guidances).toHaveLength(0);
+  });
+
+  it("conversation 形态（chatMode）豁免：不纳管不通知", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    supervisor.adoptOnProcessDeath(makeRecord({ chatMode: true, resumable: true }), "x");
+    expect(deps.notices).toHaveLength(0);
+    expect(supervisor.supervisedIds()).toEqual([]);
+  });
+
+  it("该放弃：决策看门狗到期 → giveUp(watchdog-expired) 并解除纳管；record 已终态则跳过", async () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    deps.views.set("bg-1", { id: "bg-1", status: "running", resumable: true, hasResult: false, chatMode: false, rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1, closedReason: undefined });
+    supervisor.adoptOnProcessDeath(makeRecord(), "x");
+    expect(deps.givenUp).toHaveLength(0);
+    await vi.advanceTimersByTimeAsync(ROUND_SUPERVISOR_WATCHDOG_DEFAULT_MS + 1);
+    expect(deps.givenUp).toEqual([{ recordId: "bg-1", kind: "watchdog-expired", detail: {} }]);
+    expect(supervisor.supervisedIds()).toEqual([]);
+  });
+
+  it("看门狗等待期内 run 恢复（决策收敛）→ 解除看门狗，不放弃", async () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    deps.views.set("bg-1", { id: "bg-1", status: "running", resumable: true, hasResult: false, chatMode: false, rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1, closedReason: undefined });
+    supervisor.adoptOnProcessDeath(makeRecord(), "x");
+    supervisor.noteRunStarted("bg-1"); // 主 agent resume = 决策收敛
+    await vi.advanceTimersByTimeAsync(ROUND_SUPERVISOR_WATCHDOG_DEFAULT_MS + 1);
+    expect(deps.givenUp).toHaveLength(0);
+  });
+
+  it("[F5] 挂账转完成（SP-5 result 回填）→ 解除看门狗：到期不误 giveUp 已完成挂账 record", async () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    deps.views.set("bg-1", { id: "bg-1", status: "running", resumable: true, hasResult: false, chatMode: false, rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1, closedReason: undefined });
+    supervisor.adoptOnProcessDeath(makeRecord(), "x"); // 该唤醒 → 指引 + 看门狗 armed
+    expect(deps.guidances).toHaveLength(1);
+    // upgrade 完成 → result 回填（挂账态），重评估触发（noteRunEnded 携带视图更新）
+    deps.views.set("bg-1", { id: "bg-1", status: "running", resumable: true, hasResult: true, chatMode: false, rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1, closedReason: undefined });
+    supervisor.noteRunEnded("bg-1");
+    // armed 的看门狗必须已解除——2h 到期不得把已完成挂账 record 判死
+    await vi.advanceTimersByTimeAsync(ROUND_SUPERVISOR_WATCHDOG_DEFAULT_MS + 1);
+    expect(deps.givenUp).toHaveLength(0);
+    expect(supervisor.supervisedIds()).toEqual(["bg-1"]); // 挂账态保持纳管（归 idle-gc 收口）
+  });
+
+  it("env ≤0 关闭该放弃路径：只指引永不放弃（回收层 opt-out）", async () => {
+    vi.stubEnv("XYZ_SUBAGENT_ROUND_SUPERVISOR_WATCHDOG_MS", "0");
+    RoundSupervisor._resetEnvCacheForTest();
+    try {
+      const deps = makeDeps();
+      const supervisor = new RoundSupervisor(deps);
+      deps.views.set("bg-1", { id: "bg-1", status: "running", resumable: true, hasResult: false, chatMode: false, rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1, closedReason: undefined });
+      supervisor.adoptOnProcessDeath(makeRecord(), "x");
+      expect(deps.guidances).toHaveLength(1);
+      await vi.advanceTimersByTimeAsync(ROUND_SUPERVISOR_WATCHDOG_DEFAULT_MS * 3);
+      expect(deps.givenUp).toHaveLength(0);
+    } finally {
+      vi.unstubAllEnvs();
+      RoundSupervisor._resetEnvCacheForTest();
+    }
+  });
+});
+
+describe("RoundSupervisor boot 分区", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("already-resumable-idle（非 conversation）→ 重认领接管 + 送达指引", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    deps.candidates.push({ id: "bg-1", rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1 });
+    deps.views.set("bg-1", { id: "bg-1", status: "running", resumable: true, hasResult: false, chatMode: false, rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1, closedReason: undefined });
+    const { readopted } = supervisor.bootPartition();
+    expect(readopted).toEqual(["bg-1"]);
+    expect(deps.guidances).toHaveLength(1);
+    expect(supervisor.supervisedIds()).toEqual(["bg-1"]);
+  });
+
+  it("in-flight 形态（无 resumable 信号）→ 跳过（直断归孤儿恢复，防双收尾）", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    deps.candidates.push({ id: "bg-2", rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1 });
+    deps.views.set("bg-2", { id: "bg-2", status: "running", resumable: false, hasResult: false, chatMode: false, rootSessionId: "r", agent: "worker", slug: "s", startedAt: 1, closedReason: undefined });
+    const { readopted } = supervisor.bootPartition();
+    expect(readopted).toEqual([]);
+    expect(deps.guidances).toHaveLength(0);
+    expect(deps.givenUp).toHaveLength(0);
+  });
+
+  it("conversation 形态 → 豁免（现状机制管辖）", () => {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    deps.candidates.push({ id: "bg-3", rootSessionId: "r", agent: "chat", slug: "s", startedAt: 1 });
+    deps.views.set("bg-3", { id: "bg-3", status: "running", resumable: true, hasResult: false, chatMode: true, rootSessionId: "r", agent: "chat", slug: "s", startedAt: 1, closedReason: undefined });
+    const { readopted } = supervisor.bootPartition();
+    expect(readopted).toEqual([]);
+    expect(supervisor.supervisedIds()).toEqual([]);
+  });
+});
+
+describe("RoundSupervisor 通知对账（送指引前查替代）", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  function setupDeadRecord(): { deps: ReturnType<typeof makeDeps>; supervisor: RoundSupervisor } {
+    const deps = makeDeps();
+    const supervisor = new RoundSupervisor(deps);
+    deps.views.set("bg-1", { id: "bg-1", status: "running", resumable: true, hasResult: false, chatMode: false, rootSessionId: "r", agent: "worker", slug: "fix-bug", startedAt: 1, closedReason: undefined });
+    return { deps, supervisor };
+  }
+
+  it("高置信（同 root + 同 agent + 同 slug + 看门狗窗内新建）→ 撤销指引改送替代终止通知 + 该放弃", () => {
+    const { deps, supervisor } = setupDeadRecord();
+    deps.candidates.push({ id: "bg-2", rootSessionId: "r", agent: "worker", slug: "fix-bug", startedAt: Date.now() - 1000 });
+    supervisor.adoptOnProcessDeath(makeRecord(), "x");
+    expect(deps.guidances).toHaveLength(0); // 指引撤销
+    expect(deps.replaced).toHaveLength(1);
+    expect(deps.replaced[0].replacementId).toBe("bg-2");
+    expect(deps.givenUp).toEqual([{ recordId: "bg-1", kind: "superseded", detail: { replacementId: "bg-2" } }]);
+    expect(supervisor.supervisedIds()).toEqual([]);
+  });
+
+  it("低置信（仅 agent 同名）→ 不撤销指引，指引自带豁免声明", () => {
+    const { deps, supervisor } = setupDeadRecord();
+    deps.candidates.push({ id: "bg-2", rootSessionId: "r", agent: "worker", slug: "other-task", startedAt: Date.now() - 1000 });
+    supervisor.adoptOnProcessDeath(makeRecord(), "x");
+    expect(deps.guidances).toHaveLength(1);
+    expect(deps.guidances[0].exemptionDisclaimer).toBe(true);
+    expect(deps.givenUp).toHaveLength(0);
+  });
+
+  it("同名但超出看门狗窗（无时序关联）→ 无替代命中，指引不带豁免声明", () => {
+    const { deps, supervisor } = setupDeadRecord();
+    deps.candidates.push({ id: "bg-2", rootSessionId: "r", agent: "worker", slug: "fix-bug", startedAt: Date.now() - ROUND_SUPERVISOR_WATCHDOG_DEFAULT_MS - 10_000 });
+    supervisor.adoptOnProcessDeath(makeRecord(), "x");
+    expect(deps.guidances).toHaveLength(1);
+    expect(deps.guidances[0].exemptionDisclaimer).toBe(false);
+    expect(deps.givenUp).toHaveLength(0);
+  });
+
+  it("无候选 → 指引不带豁免声明", () => {
+    const { deps, supervisor } = setupDeadRecord();
+    supervisor.adoptOnProcessDeath(makeRecord(), "x");
+    expect(deps.guidances).toHaveLength(1);
+    expect(deps.guidances[0].exemptionDisclaimer).toBe(false);
+  });
+
+  it("高置信对账按 slug 改写漏判 → 落入低置信（残余双执行风险面，豁免声明兜住）", () => {
+    const { deps, supervisor } = setupDeadRecord();
+    deps.candidates.push({ id: "bg-2", rootSessionId: "r", agent: "worker", slug: "rewritten-slug", startedAt: Date.now() - 1000 });
+    supervisor.adoptOnProcessDeath(makeRecord(), "x");
+    expect(deps.guidances).toHaveLength(1);
+    expect(deps.guidances[0].exemptionDisclaimer).toBe(true);
+  });
+});

package/src/execution/__tests__/session-file-gc.test.ts

@@ -34,7 +34,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
-  fs.rmSync(tmpAgentDir, { recursive: true, force: true });
+  fs.rmSync(tmpAgentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   vi.restoreAllMocks();
 });
 

package/src/execution/__tests__/session-pending.test.ts

@@ -27,9 +27,11 @@ import * as path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { configureNotifyDomain, resetNotifyDomainForTests } from "../../core/notify-ports.ts";
 
+// [D5 消亡] listActivePendingFromSessionFile（后代补杀清单口径）随 inproc pi 引擎目录
+// 删除消亡（消费方全在待删 session-runner；止损语义由 W4 监督器该放弃承接）——
+// 本文件覆盖收敛为 count 口径 + 游标剪枝原语。
 import {
   clearPendingCursors,
-  listActivePendingFromSessionFile,
   prunePendingCursor,
   readActivePendingFromSessionFile,
 } from "../session-pending.ts";
@@ -175,7 +177,10 @@ describe("readActivePendingFromSessionFile", () => {
   });
 
   it("fork 继承的主 session register 已被 expired unregister 抵消 → 不干扰", () => {
-    // 模拟 P fork 主 session：继承 register（sessionId 不匹配），session_start 重建补 unregister(expired)
+    // 模拟 P fork 主 session：继承 register 且文件里已有对应 unregister 抵消行
+    // （历史 session 档 U4 产物）。翻 process 档后 U4 不再补写抵消行，fork 残留的
+    // 现行收口 = 读侧过滤②（见文末 [F1] describe）——本用例锁「文件内抵消行仍生效」
+    // 的差集语义本身，不锁清理机制。
     const file = makeTmpSessionFile([
       mkRegister("parent-bg"),
       mkUnregister("parent-bg", "expired"),
@@ -319,9 +324,6 @@ describe("[LC-6] 差集计数语义等值", () => {
     expect(r.count).toBe(1); // 2 register − 1 unregister
     expect(counter.mock.calls[0]?.[0]).toHaveLength(1); // 端口收到差集（非全量 3 行）
     expect((counter.mock.calls[0]?.[0] as unknown[])[0]).toMatchObject({ customType: "pending:register" });
-
-    const list = listActivePendingFromSessionFile(f);
-    expect(list.items.map((i) => i.id)).toEqual(["bg-2"]);
   });
 
   it("同 id 重 register（未 unregister）覆盖 → 仍 1 个活跃", () => {
@@ -330,9 +332,7 @@ describe("[LC-6] 差集计数语义等值", () => {
     fs.writeFileSync(f, entryLine("pending:register", registerData("bg-1", "sess-1")));
     fs.appendFileSync(f, entryLine("pending:register", registerData("bg-1", "sess-1-moved")));
 
-    const list = listActivePendingFromSessionFile(f);
-    expect(list.items).toHaveLength(1);
-    expect(list.items[0]?.sessionId).toBe("sess-1-moved");
+    expect(readActivePendingFromSessionFile(f).count).toBe(1);
   });
 
   it("unregister 后同 id 再 register → 恢复活跃", () => {
@@ -345,9 +345,6 @@ describe("[LC-6] 差集计数语义等值", () => {
         entryLine("pending:register", registerData("bg-1", "sess-2")),
     );
 
-    const list = listActivePendingFromSessionFile(f);
-    expect(list.items.map((i) => i.id)).toEqual(["bg-1"]);
-    expect(list.items[0]?.sessionId).toBe("sess-2");
     expect(readActivePendingFromSessionFile(f).count).toBe(1);
   });
 
@@ -382,8 +379,7 @@ describe("[LC-6] 差集计数语义等值", () => {
         entryLine("pending:register", registerData("bg-2", "sess-2")),
     );
 
-    const list = listActivePendingFromSessionFile(f);
-    expect(list.items.map((i) => i.id)).toEqual(["bg-2"]);
+    expect(readActivePendingFromSessionFile(f).count).toBe(1); // 畸形行丢弃，好行入差集
   });
 });
 
@@ -410,8 +406,7 @@ describe("[LC-6] 游标剪枝", () => {
     expect(Buffer.byteLength(gen2, "utf-8")).toBeGreaterThan(150);
     fs.writeFileSync(f, gen2);
 
-    const list = listActivePendingFromSessionFile(f);
-    expect(list.items.map((i) => i.id)).toEqual(["bg-x"]); // 剪枝生效：从头全量读
+    expect(readActivePendingFromSessionFile(f).count).toBe(1); // 剪枝生效：从头全量读
   });
 
   it("prunePendingCursor：回收后重新判定等值（全量重读差集不变）", () => {
@@ -429,7 +424,6 @@ describe("[LC-6] 游标剪枝", () => {
     fs.appendFileSync(f, entryLine("pending:unregister", { id: "bg-1" }));
     const r = readActivePendingFromSessionFile(f);
     expect(r.count).toBe(1); // 重建后差集正确（无重复无丢失）
-    expect(listActivePendingFromSessionFile(f).items.map((i) => i.id)).toEqual(["bg-2"]);
   });
 
   it("prunePendingCursor：prune 后覆写文件（size ≥ 旧 offset）→ 新内容完整可见", () => {
@@ -446,7 +440,7 @@ describe("[LC-6] 游标剪枝", () => {
     fs.writeFileSync(f, gen2); // 覆写（模拟文件替换），size > 旧 offset
     prunePendingCursor(f);
 
-    expect(listActivePendingFromSessionFile(f).items.map((i) => i.id)).toEqual(["bg-y"]);
+    expect(readActivePendingFromSessionFile(f).count).toBe(1);
   });
 
   it("prunePendingCursor 不存在的条目为 no-op（不抛错）", () => {
@@ -469,3 +463,111 @@ describe("[LC-6] 游标剪枝", () => {
     expect(readActivePendingFromSessionFile(f).count).toBe(1);
   });
 });
+
+// ─── [F1 读侧过滤②] 跨 session 残留基准 = 被读文件所属 session ───
+//
+// fork 继承的父级 register 残留（翻 process 档后 U4 补注销不再中性化，永久留存）
+// 由读侧过滤收口：本文件读侧以「被读文件所属 session id」（pi session 文件首行
+// SessionHeader.id）为基准经端口第二参传入，端口实现按 entry sessionId ≠ 基准
+// 跳过——后代判定差集不含跨 session 残留，层主不被残留误判「尚有活跃后代」。
+
+describe("[F1 读侧过滤②] 后代判定差集的跨 session 残留基准", () => {
+  const tmpFiles: string[] = [];
+
+  afterEach(() => {
+    for (const f of tmpFiles.splice(0)) {
+      try {
+        fs.rmSync(path.dirname(f), { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+      } catch {
+        // 清理失败不影响断言
+      }
+    }
+  });
+
+  /** pi session 文件首行 SessionHeader（session-manager.js newSession 形态）。 */
+  const mkSessionHeader = (sessionId: string) =>
+    JSON.stringify({ type: "session", version: 3, id: sessionId, timestamp: "2026-09-01T00:00:00.000Z", cwd: "/tmp" });
+
+  /** 带 sessionId 的 register（pending-notifications listener 落盘形态）。 */
+  const mkRegisterIn = (id: string, sessionId: string) =>
+    JSON.stringify({ type: "custom", customType: "pending:register", data: { id, type: "subagent", name: id, registeredAt: 1, sessionId } });
+
+  /** 端口等价实现（消费基准）：按 currentSessionId 过滤后直数——pending-notifications
+   *  filterActiveRegisters 的最小转写（缺 sessionId 的旧形态条目视为本 session，不过滤）。 */
+  function filteredCountingPort(): ReturnType<typeof vi.fn<(entries: unknown[], opts?: { currentSessionId?: string }) => number>> {
+    const counter = vi.fn((entries: unknown[], opts?: { currentSessionId?: string }) => {
+      const seen = new Set<string>();
+      let count = 0;
+      for (const raw of entries) {
+        if (!raw || typeof raw !== "object") continue;
+        const data = (raw as { data?: { id?: unknown; sessionId?: unknown } }).data ?? {};
+        if (typeof data.id !== "string" || seen.has(data.id)) continue;
+        seen.add(data.id);
+        if (
+          opts?.currentSessionId !== undefined &&
+          typeof data.sessionId === "string" &&
+          data.sessionId !== opts.currentSessionId
+        ) {
+          continue;
+        }
+        count += 1;
+      }
+      return count;
+    }) as ReturnType<typeof vi.fn<(entries: unknown[], opts?: { currentSessionId?: string }) => number>>;
+    configureNotifyDomain({ countActiveFromEntries: counter });
+    return counter;
+  }
+
+  it("带 session header 的文件 → 端口收到的基准 = header.id（被读文件所属 session）", () => {
+    const counter = filteredCountingPort();
+    const file = makeTmpSessionFile([
+      mkSessionHeader("sess-child"),
+      mkRegisterIn("bg-own", "sess-child"),
+    ]);
+    tmpFiles.push(file);
+    expect(readActivePendingFromSessionFile(file).count).toBe(1);
+    const call = counter.mock.calls[0] as unknown[];
+    expect(call[1]).toEqual({ currentSessionId: "sess-child" });
+  });
+
+  it("端到端：fork 继承的父级 register 残留（sessionId = 父 session）不进后代判定差集", () => {
+    filteredCountingPort();
+    // 子 session 文件 = header(sess-child) + fork 继承的父级注册残留 + 子进程自己的注册
+    const file = makeTmpSessionFile([
+      mkSessionHeader("sess-child"),
+      mkRegisterIn("bg-parent", "sess-parent"),
+      mkRegisterIn("wf-parent", "sess-parent"),
+      mkRegisterIn("bg-own", "sess-child"),
+    ]);
+    tmpFiles.push(file);
+    // 无读侧过滤时差集为 3（层主误判「尚有活跃后代」空等）；过滤后只数本 session = 1
+    expect(readActivePendingFromSessionFile(file)).toEqual({ count: 1, recentUnregister: false });
+  });
+
+  it("无 session header（旧 fixture 形态）→ 基准 undefined = 不过滤（向后兼容）", () => {
+    const counter = filteredCountingPort();
+    const file = makeTmpSessionFile([
+      mkRegisterIn("bg-parent", "sess-parent"),
+      mkRegisterIn("bg-own", "sess-child"),
+    ]);
+    tmpFiles.push(file);
+    expect(readActivePendingFromSessionFile(file).count).toBe(2);
+    const call = counter.mock.calls[0] as unknown[];
+    expect(call[1]).toBeUndefined();
+  });
+
+  it("增量读（cursor 已热）时基准仍从 cursor 缓存透传（不依赖重读首行）", () => {
+    const counter = filteredCountingPort();
+    const file = makeTmpSessionFile([
+      mkSessionHeader("sess-child"),
+      mkRegisterIn("bg-own", "sess-child"),
+    ]);
+    tmpFiles.push(file);
+    expect(readActivePendingFromSessionFile(file).count).toBe(1); // 首读建 cursor
+    // 追加新 register 后增量读——offset > 0 不重读首行，基准取 cursor 缓存
+    fs.appendFileSync(file, mkRegisterIn("bg-own-2", "sess-child") + "\n", "utf-8");
+    expect(readActivePendingFromSessionFile(file).count).toBe(2);
+    const lastCall = counter.mock.calls[counter.mock.calls.length - 1] as unknown[];
+    expect(lastCall[1]).toEqual({ currentSessionId: "sess-child" });
+  });
+});