@zhushanwen/pi-subagent-workflow 7.3.4 → 8.0.0

package/src/execution/__tests__/index-session-start.test.ts

@@ -91,6 +91,7 @@ vi.mock("../subagent-service.ts", () => ({
     initSession = mockInitSession;
     setUiRequestHandler = mockSetUiRequestHandler;
     recoverManifestTmpFiles = mockRecoverManifestTmpFiles;
+    startGcTimer = vi.fn();
     getStreamSink = () => null;
     dispose = vi.fn();
   },
@@ -124,16 +125,38 @@ vi.mock("../session-file-gc.ts", () => ({
   maybeCleanupExpiredSessionFiles: vi.fn(),
 }));
 
-// JsonlRunStore mock：loadAll 默认空数组（session_start 后段不抛即可）
+// JsonlRunStore mock：loadAll 默认空数组（session_start 后段不抛即可）。
+// dispose/flushPendingSaves：session_shutdown handler 会调 state.store.dispose()（W2C5）；
+// dispose 用 hoisted spy 以便 W2TC16 断言（instance.dispose 即 spy）。
+const { mockStoreDispose, mockStoreFlushPendingSaves } = vi.hoisted(() => ({
+  mockStoreDispose: vi.fn(async () => {}),
+  mockStoreFlushPendingSaves: vi.fn(async () => {}),
+}));
 vi.mock("../../orchestration/jsonl-run-store.ts", () => ({
   JsonlRunStore: class {
     loadAll = mockLoadAll;
     save = vi.fn(async () => {});
+    dispose = mockStoreDispose;
+    flushPendingSaves = mockStoreFlushPendingSaves;
   },
 }));
 
+// lifecycle mock：仅替换 terminateRunningRuns 为 hoisted spy（W2TC16 断言
+// terminate→dispose 顺序用），其余导出（scheduleTimeBudget/runWorkflow/abortRun/
+// evictDoneRunsBeyondCap）经 importOriginal 保留真实实现——本文件不执行真实
+// workflow，替换只影响 shutdown handler 的 terminate 调用点。
+const { mockTerminateRunningRuns } = vi.hoisted(() => ({
+  mockTerminateRunningRuns: vi.fn(async () => {}),
+}));
+vi.mock("../../orchestration/lifecycle.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../orchestration/lifecycle.ts")>();
+  return { ...actual, terminateRunningRuns: mockTerminateRunningRuns };
+});
+
 // interface 层 mock：避免触发真实 pi.registerTool（pi 是 Proxy，真实模块访问 pi
 // 属性时可能抛错）。路径相对 src/execution/__tests/ → ../../interface/...
+// registerWorkflowTool / registerWorkflowsCommand 用 hoisted spy——W3TC7/8 需在
+// it 内读 mock.calls 捕获 lazyDeps 与 runs getter（对齐 mockStoreDispose 先例）。
 vi.mock("../../interface/subagent-tool.ts", () => ({
   registerSubagentTool: vi.fn(),
 }));
@@ -143,30 +166,39 @@ vi.mock("../../interface/subagents.ts", () => ({
 vi.mock("../../interface/bg-notify-render.ts", () => ({
   renderBgNotifyMessage: vi.fn(),
 }));
+const { mockRegisterWorkflowTool, mockRegisterWorkflowsCommand } = vi.hoisted(() => ({
+  mockRegisterWorkflowTool: vi.fn(),
+  mockRegisterWorkflowsCommand: vi.fn(),
+}));
 vi.mock("../../interface/tool-workflow.ts", () => ({
-  registerWorkflowTool: vi.fn(),
+  registerWorkflowTool: mockRegisterWorkflowTool,
 }));
 vi.mock("../../interface/tool-workflow-script.ts", () => ({
   registerWorkflowScriptTool: vi.fn(),
 }));
 vi.mock("../../interface/commands.ts", () => ({
-  registerWorkflowsCommand: vi.fn(),
+  registerWorkflowsCommand: mockRegisterWorkflowsCommand,
 }));
 
 // ── import 被测工厂 ──
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import subagentsExtension from "../../index.ts";
+import { Budget } from "../../orchestration/models/budget.ts";
+import { Trace } from "../../orchestration/models/trace.ts";
+import { WorkflowRun } from "../../orchestration/models/workflow-run.ts";
 
 // ── helpers ──
 
-/** 创建可观察的 mock ExtensionAPI，捕获 session_start handler。
+/** 创建可观察的 mock ExtensionAPI，捕获 session_start / session_shutdown handler。
  *  Proxy 兜底：未显式处理的 pi.xxx 返回 noop，避免抛错。 */
 function createMockPi(): {
   pi: ExtensionAPI;
   getSessionStartHandler: () => ((event: unknown, ctx: unknown) => Promise<void>) | undefined;
+  getSessionShutdownHandler: () => ((event: unknown, ctx: unknown) => Promise<void>) | undefined;
 } {
   let sessionStartHandler: ((event: unknown, ctx: unknown) => Promise<void>) | undefined;
+  let sessionShutdownHandler: ((event: unknown, ctx: unknown) => Promise<void>) | undefined;
   const events = { emit: vi.fn() };
   const noop = (): void => {
     /* mock */
@@ -178,6 +210,9 @@ function createMockPi(): {
           if (event === "session_start") {
             sessionStartHandler = handler as (event: unknown, ctx: unknown) => Promise<void>;
           }
+          if (event === "session_shutdown") {
+            sessionShutdownHandler = handler as (event: unknown, ctx: unknown) => Promise<void>;
+          }
         };
       }
       if (prop === "events") return events;
@@ -186,7 +221,11 @@ function createMockPi(): {
       return noop;
     },
   });
-  return { pi, getSessionStartHandler: () => sessionStartHandler };
+  return {
+    pi,
+    getSessionStartHandler: () => sessionStartHandler,
+    getSessionShutdownHandler: () => sessionShutdownHandler,
+  };
 }
 
 /** 最小 ExtensionContext mock。mode 由参数控制（决定 handler 注入行为）。 */
@@ -253,6 +292,7 @@ describe("session_start UI handler 注入链路（SR-3）", () => {
       // ADR-035：与 SubagentService mock class 形状一致——session_start
       // 会调 service.recoverManifestTmpFiles()，缺方法会抛 TypeError 被吞为 console.warn
       recoverManifestTmpFiles: mockRecoverManifestTmpFiles,
+      startGcTimer: vi.fn(),
       getStreamSink: () => null,
       dispose: vi.fn(),
     };
@@ -339,3 +379,215 @@ describe("session_start UI handler 注入链路（SR-3）", () => {
     expect(mockRecoverManifestTmpFiles).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("session_shutdown: store.dispose 接线（W2TC16）", () => {
+  it("W2TC16: session_shutdown 触发后 store 实例 dispose 被调用（terminate 完成之后、sessionState 清理之前）", async () => {
+    // 预热：session_start 建立一个 sessionState 条目（含 mock store 实例）。
+    // loadAll 注入 running run 使其进入 sessionState.runs——duck-typed 对象 +
+    // no-op transition：session_start 的 kill-9 恢复会把 running run 转 done,failed
+    // （真实 WorkflowRun.reconstruct 无法保持 running），no-op transition 吞掉该转换
+    // 让 run 以 running 进入 sessionState.runs。运行时形状由消费路径保证：handler
+    // 只读 state.status（string）与 transition（可调用），duck typing 满足。
+    mockStoreDispose.mockClear();
+    const runningRun = {
+      runId: "wf-w2tc16-1",
+      state: { status: "running", error: undefined as string | undefined },
+      transition: vi.fn(),
+    } as unknown as WorkflowRun;
+    mockLoadAll.mockResolvedValue([runningRun]);
+    const { pi, getSessionStartHandler, getSessionShutdownHandler } = createMockPi();
+    subagentsExtension(pi);
+
+    const startHandler = getSessionStartHandler();
+    expect(startHandler).toBeDefined();
+    await startHandler!({ type: "session_start" }, createMockCtx("tui"));
+
+    // terminate gate：deferred 模拟 terminateRunningRuns 内部 `await store.save(run)`
+    // 落盘边界——resolve 前 dispose 不得发生（terminate 未完成 = failed 状态未落盘，
+    // 此刻 dispose 刷 pending 批会把未定稿的 running 尾巴刷出去，重启后 kill-9
+    // 恢复误判）。
+    let resolveTerminate = (): void => {};
+    mockTerminateRunningRuns.mockImplementationOnce(async () => {
+      await new Promise<void>((r) => {
+        resolveTerminate = r;
+      });
+    });
+
+    // 触发 session_shutdown（event 触发模式对齐本文件 session_start 既有写法）
+    const shutdownHandler = getSessionShutdownHandler();
+    expect(shutdownHandler).toBeDefined();
+    const shutdownDone = shutdownHandler!({ type: "session_shutdown" }, createMockCtx("tui"));
+
+    // terminate 未完成（save 未落盘）→ dispose 未被调（await 边界真实生效）
+    await Promise.resolve();
+    expect(mockStoreDispose).not.toHaveBeenCalled();
+
+    resolveTerminate();
+    await shutdownDone;
+
+    // 每 sessionState 条目一次：session_start 建了 1 个 session → terminate 调用 1 次
+    expect(mockTerminateRunningRuns).toHaveBeenCalledTimes(1);
+    // 原因串字面值（session_shutdown 路径，接口契约锁定）
+    expect(mockTerminateRunningRuns.mock.calls[0]?.[1]).toBe("Session shutdown: run terminated");
+    // dispose 在 terminate 完成后被调（每 session 1 次）
+    expect(mockStoreDispose).toHaveBeenCalledTimes(1);
+
+    // 顺序断言「sessionState 清理之前」（标题后半）：sessionState.delete 是 Map
+    // 同步操作、无外部可观察 spy——用第二次 shutdown 的幂等性间接证明：第一次
+    // handler 内条目已删（delete 在 dispose await 之后执行），重复 shutdown 遍历
+    // 空 Map 不再二次 terminate/dispose。若清理被跳过，此处会涨到 2 次。
+    await shutdownHandler!({ type: "session_shutdown" }, createMockCtx("tui"));
+    expect(mockTerminateRunningRuns).toHaveBeenCalledTimes(1);
+    expect(mockStoreDispose).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ── W-N: done run 淘汰接线（loadAll 裁剪 + onRunDone 裁剪） ──
+
+/** fixture 基准时刻（过去时刻，保证 now 恒晚于全部 fixture completedAt）。 */
+const W3_T0 = Date.parse("2020-01-01T00:00:00.000Z");
+function w3IsoAt(min: number): string {
+  return new Date(W3_T0 + min * 60_000).toISOString();
+}
+
+/** loadAll 重水合输入 fixture：done run（status done reason completed + completedAt）。 */
+function makeLoadedDoneRun(runId: string, completedAt: string): WorkflowRun {
+  return WorkflowRun.reconstruct(
+    runId,
+    {
+      scriptSource: "execute() {}",
+      args: {},
+      scriptName: "test",
+      scriptPath: "/fake/test.js",
+    },
+    {
+      status: "done",
+      reason: "completed",
+      budget: new Budget({ maxTokens: 1000 }),
+      calls: new Map(),
+      trace: new Trace(),
+      errorLogs: [],
+    },
+    { startedAt: completedAt, completedAt },
+  );
+}
+
+/** loadAll 重水合输入 fixture：running run（kill-9 恢复输入，reconstruct 跳 I1 合法）。 */
+function makeLoadedRunningRun(runId: string): WorkflowRun {
+  return WorkflowRun.reconstruct(
+    runId,
+    {
+      scriptSource: "execute() {}",
+      args: {},
+      scriptName: "test",
+      scriptPath: "/fake/test.js",
+    },
+    {
+      status: "running",
+      budget: new Budget({ maxTokens: 1000 }),
+      calls: new Map(),
+      trace: new Trace(),
+      errorLogs: [],
+    },
+    { startedAt: w3IsoAt(0) },
+  );
+}
+
+describe("W-3: done run 淘汰接线（loadAll 裁剪 + onRunDone 裁剪）", () => {
+  it("W3TC7: session_start loadAll 灌入后裁剪到 K（21 done + 1 running kill-9 恢复）", async () => {
+    // 21 个 done（completedAt 递增）+ 1 个 running（kill-9 恢复输入）
+    const doneRuns = Array.from({ length: 21 }, (_, i) =>
+      makeLoadedDoneRun(`wf-loaded-${i}`, w3IsoAt(i)));
+    const runningRun = makeLoadedRunningRun("wf-recovered-1");
+    mockLoadAll.mockResolvedValue([...doneRuns, runningRun]);
+
+    const { pi, getSessionStartHandler } = createMockPi();
+    subagentsExtension(pi);
+    const handler = getSessionStartHandler();
+    expect(handler).toBeDefined();
+    await handler!({ type: "session_start" }, createMockCtx("tui"));
+
+    // runs Map 观察点 = registerWorkflowsCommand 第二参数的 runs getter
+    //（工厂入口同步调用，mock.calls[0] 恒存在）
+    const getRuns = mockRegisterWorkflowsCommand.mock.calls[0]?.[1] as
+      | (() => Map<string, WorkflowRun>)
+      | undefined;
+    expect(typeof getRuns).toBe("function");
+    const runs = getRuns!();
+
+    // kill-9 恢复链把 running 转 done,failed（既有语义）后共 22 done → 裁到 20
+    expect(runs.size).toBe(20);
+    // 恢复 run 的 completedAt 为 transition 时刻（now，晚于全部 fixture 过去时间戳）
+    // → 必在保留端
+    expect(runs.has("wf-recovered-1")).toBe(true);
+    expect(runs.get("wf-recovered-1")?.state.status).toBe("done");
+    expect(runs.get("wf-recovered-1")?.state.reason).toBe("failed");
+    // 被淘汰 2 个 = fixture 最旧两个
+    expect(runs.has("wf-loaded-0")).toBe(false);
+    expect(runs.has("wf-loaded-1")).toBe(false);
+    for (let i = 2; i < 21; i++) {
+      expect(runs.has(`wf-loaded-${i}`)).toBe(true);
+    }
+  });
+
+  it("W3TC8: onRunDone 回调接线——notify → track → evict，本轮 run 不被自身触发的裁剪淘汰", async () => {
+    // session_start 预热：恰好 20 个 done（completedAt t0..t19）
+    const doneRuns = Array.from({ length: 20 }, (_, i) =>
+      makeLoadedDoneRun(`wf-pre-${i}`, w3IsoAt(i)));
+    mockLoadAll.mockResolvedValue(doneRuns);
+
+    const { pi, getSessionStartHandler } = createMockPi();
+    subagentsExtension(pi);
+    const handler = getSessionStartHandler();
+    expect(handler).toBeDefined();
+    await handler!({ type: "session_start" }, createMockCtx("tui"));
+
+    // lazyDeps = registerWorkflowTool 第二参数（getter 转发 makeDeps 的 onRunDone）
+    const lazyDeps = mockRegisterWorkflowTool.mock.calls[0]?.[1] as
+      | { onRunDone: (run: WorkflowRun) => void }
+      | undefined;
+    expect(lazyDeps).toBeDefined();
+
+    // 本轮 newDoneRun：completedAt = now（晚于全部 fixture 过去时间戳）
+    const newDoneRun = WorkflowRun.reconstruct(
+      "wf-current-1",
+      {
+        scriptSource: "execute() {}",
+        args: {},
+        scriptName: "test",
+        scriptPath: "/fake/test.js",
+      },
+      {
+        status: "done",
+        reason: "completed",
+        budget: new Budget({ maxTokens: 1000 }),
+        calls: new Map(),
+        trace: new Trace(),
+        errorLogs: [],
+      },
+      { startedAt: w3IsoAt(999), completedAt: new Date().toISOString() },
+    );
+
+    // 模拟真实流程的注册步骤：lifecycle.ts runWorkflow 在创建时 deps.runs.set(runId, run)
+    //（onRunDone 回调只裁剪不注册——本轮 run 必须先在 Map 中，「保留端」断言才有对象）
+    const getRuns = mockRegisterWorkflowsCommand.mock.calls[0]?.[1] as
+      | (() => Map<string, WorkflowRun>)
+      | undefined;
+    expect(typeof getRuns).toBe("function");
+    const runs = getRuns!();
+    runs.set("wf-current-1", newDoneRun);
+
+    // 回调不抛错（notifyDone 对 mock pi Proxy 安全：sendMessage 返回 noop；
+    // toGuiCtx(tui ctx) isGuiCapable false 走无 __gui__ 分支）
+    expect(() => lazyDeps!.onRunDone(newDoneRun)).not.toThrow();
+
+    // 21 done 裁 1：size 回到 20
+    expect(runs.size).toBe(20);
+    // 被淘汰的是 t0 最旧 run 而非本轮 run（completedAt 最新恒在保留端）
+    expect(runs.has("wf-current-1")).toBe(true);
+    expect(runs.has("wf-pre-0")).toBe(false);
+    for (let i = 1; i < 20; i++) {
+      expect(runs.has(`wf-pre-${i}`)).toBe(true);
+    }
+  });
+});

package/src/execution/__tests__/lifecycle-manager-lock.test.ts

@@ -0,0 +1,211 @@
+// acquireActivateLock 30s 超时兜底单测 —— v4-lifecycle-convergence.md §3.3 A-2。
+//
+// 验证：前序 holder 持锁不 release（崩溃/死锁模拟）时，waiter
+//   - 等待 29999ms 仍 pending（未误伤正常排队）
+//   - 到 30001ms 抛含恢复指引的超时错误（'activation timed out' + 'retry action: message'）
+//
+// 测试策略：纯 Promise 链 + setTimeout 超时，用 vi.useFakeTimers() 控时，
+// advanceTimersByTimeAsync 同时推进 fake timer 与 microtask flush。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  _getActivateLockTailCountForTest,
+  _resetLifecycleState,
+  acquireActivateLock,
+} from "../lifecycle-manager.ts";
+
+describe("acquireActivateLock 30s 超时兜底 (v4 A-2)", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    _resetLifecycleState();
+  });
+
+  afterEach(() => {
+    _resetLifecycleState();
+    vi.useRealTimers();
+  });
+
+  it("waiter 等待 29999ms 仍 pending；到 30001ms 抛含恢复指引的超时错误", async () => {
+    // 第一个 holder 持锁后不 release（模拟崩溃/死锁）
+    await acquireActivateLock("sa-stuck");
+
+    // 第二个 waiter 必然排队（前序未 release）
+    let errMsg: string | null = null;
+    let gotRelease: (() => void) | null = null;
+    const waiter = acquireActivateLock("sa-stuck")
+      .then((release) => {
+        gotRelease = release;
+      })
+      .catch((err: unknown) => {
+        errMsg = err instanceof Error ? err.message : String(err);
+      });
+
+    // flush microtask：waiter 进入 prev.then 等待链
+    await vi.advanceTimersByTimeAsync(0);
+    expect(gotRelease).toBe(null); // 尚未拿到锁
+    expect(errMsg).toBe(null);
+
+    // 29999ms：未满 30s，waiter 仍 pending
+    await vi.advanceTimersByTimeAsync(29999);
+    expect(gotRelease).toBe(null);
+    expect(errMsg).toBe(null);
+
+    // 再推进 2ms（累计 30001ms）：超时 timer 触发 → reject
+    await vi.advanceTimersByTimeAsync(2);
+    await waiter;
+
+    // 超时：未拿到锁，抛含恢复指引的错误
+    expect(gotRelease).toBe(null);
+    expect(errMsg).not.toBe(null);
+    expect(errMsg).toContain("activation timed out");
+    expect(errMsg).toContain("retry action: message");
+    expect(errMsg).toContain("sa-stuck");
+  });
+
+  it("首次 acquire（无前序 holder）立即返回 release，不触发超时", async () => {
+    // 首次 acquire：prev=Promise.resolve()，立即 resolve，timer 被 clearTimeout 取消
+    const release = await acquireActivateLock("sa-fresh");
+    expect(typeof release).toBe("function");
+
+    // 推进远超 30s，不应有任何未捕获的超时 reject（timer 已清除）
+    await vi.advanceTimersByTimeAsync(60000);
+    release();
+  });
+
+  it("[review 修复] 超时后前序 release → 链可推进：二次 acquire 立即获锁（锁链不瘫痪）", async () => {
+    // 瘫痪路径回归：waiter 超时 reject 后，若其 current 永久 pending，tail 永久
+    // pending → 前序 release 后后续 acquire 也只能 30s 超时（只能重启恢复）。
+    // 修复后超时回调 resolve 自身 current 放行链尾：release1 后 tail settle，
+    // 二次 acquire 的 prev 已 settle → 立即拿到 releaseFn。
+    const release1 = await acquireActivateLock("sa-recover");
+
+    let waiterErr: string | null = null;
+    const waiter = acquireActivateLock("sa-recover").catch((err: unknown) => {
+      waiterErr = err instanceof Error ? err.message : String(err);
+    });
+    await vi.advanceTimersByTimeAsync(0); // waiter 挂链
+    await vi.advanceTimersByTimeAsync(30001); // 超时 reject（+ 超时放行链尾）
+    await waiter;
+    expect(waiterErr).toContain("activation timed out");
+
+    release1(); // 前序释放 → tail settle（current 已被超时放行 resolve）
+    await vi.advanceTimersByTimeAsync(0); // flush microtask 链
+
+    // 二次 acquire：prev 是已 settle 的 tail → 立即拿到锁，不等 30s
+    const release2 = await acquireActivateLock("sa-recover");
+    expect(typeof release2).toBe("function");
+    release2();
+    await vi.advanceTimersByTimeAsync(0);
+  });
+
+  it("[review 修复] 前序持续持锁时超时不放行后续 waiter 提前获锁（互斥保持）", async () => {
+    // 超时放行只 resolve 自身 current（tail 仍等 prev）；前序未 release 时，
+    // 新 acquire 依然排队等待，不会与前序 holder 形成双写者。
+    const release1 = await acquireActivateLock("sa-mutex");
+
+    const waiter1 = acquireActivateLock("sa-mutex").catch(() => {});
+    await vi.advanceTimersByTimeAsync(30001); // waiter1 超时放行自身 current
+    await waiter1;
+
+    // 前序仍持锁：新 acquire 的 prev（= waiter1 的 tail）等待 release1，不提前获锁
+    let gotRelease2 = false;
+    const waiter2 = acquireActivateLock("sa-mutex").then(() => {
+      gotRelease2 = true;
+    });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(gotRelease2).toBe(false); // 未提前获锁
+
+    release1();
+    await vi.advanceTimersByTimeAsync(0);
+    await waiter2; // release1 后链推进，waiter2 获锁
+    expect(gotRelease2).toBe(true);
+  });
+
+  it("[review 修复] 超时者对称自清：前序 release 推进链尾后 Map 条目回收；前序持锁期间不提前删", async () => {
+    // round2 INFO 残留：超时者 releaseFn 永不被调用，原实现条目滞留 Map 直到下次
+    // 同 recordId acquire 覆盖。修复后挂 tail 尾部自清——tail settle（前序已
+    // release）时回收；tail pending（前序仍持锁）时回调不执行，条目保留（后续
+    // acquire 仍排队等待，互斥不被破坏）。
+    const release1 = await acquireActivateLock("sa-timeout-gc");
+
+    const waiter = acquireActivateLock("sa-timeout-gc").catch(() => {});
+    await vi.advanceTimersByTimeAsync(0); // waiter 挂链，Map 链尾已覆盖为 waiter 的 tail
+    expect(_getActivateLockTailCountForTest()).toBe(1);
+
+    await vi.advanceTimersByTimeAsync(30001); // 超时：reject + settleCurrent + tail.then 自清排队
+    await waiter;
+    // 前序仍持锁 → tail 仍 pending → 自清回调未执行 → 条目仍在
+    expect(_getActivateLockTailCountForTest()).toBe(1);
+
+    release1(); // 前序释放 → tail settle → 自清回调执行（identity 匹配，无新 waiter）
+    await vi.advanceTimersByTimeAsync(0);
+    expect(_getActivateLockTailCountForTest()).toBe(0);
+  });
+});
+
+describe("activateLockTails tail-identity 自清（release 后回收）", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    _resetLifecycleState();
+  });
+
+  afterEach(() => {
+    _resetLifecycleState();
+    vi.useRealTimers();
+  });
+
+  it("W3TC14: 无 waiter 时 release 后 Map 空 + release 后可再次 acquire", async () => {
+    const release = await acquireActivateLock("sa-gc");
+    // 自清新增的 test-only 观察点：acquire 后 Map 有 1 条链尾
+    expect(_getActivateLockTailCountForTest()).toBe(1);
+
+    release();
+    // 自清经 queueMicrotask 异步执行——advanceTimersByTimeAsync(0) flush microtask
+    await vi.advanceTimersByTimeAsync(0);
+    // 无 waiter：Map 中链尾即本链尾，identity 匹配 → delete 回收
+    expect(_getActivateLockTailCountForTest()).toBe(0);
+
+    // release 后可再次 acquire：prev 回落 Promise.resolve()，立即 resolve 返回 release
+    const release2 = await acquireActivateLock("sa-gc");
+    expect(typeof release2).toBe("function");
+    release2();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(_getActivateLockTailCountForTest()).toBe(0);
+  });
+
+  it("W3TC15: 有 waiter 排队不删、最后释放者回收；不同 recordId 链独立", async () => {
+    const release1 = await acquireActivateLock("sa-q");
+
+    // 发起 acquire#2 同 recordId（不 await，.then 捕获 release2）
+    let release2: (() => void) | null = null;
+    const waiter = acquireActivateLock("sa-q").then((r) => {
+      release2 = r;
+    });
+    // #2 进入等待链——此刻 Map 链尾已被 #2 覆盖
+    await vi.advanceTimersByTimeAsync(0);
+
+    release1();
+    await vi.advanceTimersByTimeAsync(0);
+    // ES7 核心：waiter 的链尾仍在——identity 不匹配不删
+    expect(_getActivateLockTailCountForTest()).toBe(1);
+
+    // acquire#2 在 release1 后正常 resolve（等待链不被 delete 破坏——waiter 持
+    // acquire 时刻捕获的 prev Promise 引用而非 Map 查询）
+    await waiter;
+    expect(typeof release2).toBe("function");
+
+    // 另一 recordId 独立链：同时持有时各自独立计数
+    const releaseA = await acquireActivateLock("sa-a");
+    expect(_getActivateLockTailCountForTest()).toBe(2); // sa-q + sa-a
+
+    release2!();
+    await vi.advanceTimersByTimeAsync(0);
+    // 最后释放者回收：release2 的 identity 匹配 → sa-q 条目回收，sa-a 仍在
+    expect(_getActivateLockTailCountForTest()).toBe(1);
+
+    releaseA();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(_getActivateLockTailCountForTest()).toBe(0);
+  });
+});