From 2069c85b349937cfeac8caa37964c514c4b66d8b Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Sun, 12 Apr 2026 05:25:14 +0100
Subject: [PATCH] fix(test): skip heavy-check lock for scoped tooling runs

---
 scripts/test-projects.mjs              | 15 ++++--
 scripts/test-projects.test-support.mjs | 15 ++++++
 test/scripts/test-projects.test.ts     | 74 ++++++++++++++++++++++++++
 3 files changed, 99 insertions(+), 5 deletions(-)

diff --git a/scripts/test-projects.mjs b/scripts/test-projects.mjs
index 618d1bff34a..fc0a83b1f4a 100644
--- a/scripts/test-projects.mjs
+++ b/scripts/test-projects.mjs
@@ -16,6 +16,7 @@ import {
   parseTestProjectsArgs,
   resolveParallelFullSuiteConcurrency,
   resolveChangedTargetArgs,
+  shouldAcquireLocalHeavyCheckLock,
   writeVitestIncludeFile,
 } from "./test-projects.test-support.mjs";
 import {
@@ -26,11 +27,7 @@ import {
 
 // Keep this shim so `pnpm test -- src/foo.test.ts` still forwards filters
 // cleanly instead of leaking pnpm's passthrough sentinel to Vitest.
-const releaseLock = acquireLocalHeavyCheckLockSync({
-  cwd: process.cwd(),
-  env: process.env,
-  toolName: "test",
-});
+let releaseLock = () => {};
 let lockReleased = false;
 
 const FULL_SUITE_CONFIG_WEIGHT = new Map([
@@ -243,6 +240,14 @@ async function main() {
           cwd: process.cwd(),
         });
 
+  releaseLock = shouldAcquireLocalHeavyCheckLock(runSpecs, process.env)
+    ? acquireLocalHeavyCheckLockSync({
+        cwd: process.cwd(),
+        env: process.env,
+        toolName: "test",
+      })
+    : () => {};
+
   const isFullSuiteRun =
     targetArgs.length === 0 &&
     changedTargetArgs === null &&
diff --git a/scripts/test-projects.test-support.mjs b/scripts/test-projects.test-support.mjs
index f547ed43052..567785791c0 100644
--- a/scripts/test-projects.test-support.mjs
+++ b/scripts/test-projects.test-support.mjs
@@ -754,6 +754,21 @@ export function createVitestRunSpecs(args, params = {}) {
   });
 }
 
+export function shouldAcquireLocalHeavyCheckLock(runSpecs, env = process.env) {
+  if (env.OPENCLAW_TEST_PROJECTS_FORCE_LOCK === "1") {
+    return true;
+  }
+
+  return !(
+    env.OPENCLAW_TEST_PROJECTS_SERIAL === "1" &&
+    runSpecs.length === 1 &&
+    runSpecs[0]?.config === TOOLING_VITEST_CONFIG &&
+    runSpecs[0]?.watchMode === false &&
+    Array.isArray(runSpecs[0]?.includePatterns) &&
+    runSpecs[0].includePatterns.length > 0
+  );
+}
+
 export function writeVitestIncludeFile(filePath, includePatterns) {
   fs.writeFileSync(filePath, `${JSON.stringify(includePatterns, null, 2)}\n`);
 }
diff --git a/test/scripts/test-projects.test.ts b/test/scripts/test-projects.test.ts
index 047795801ca..16d2e4f803c 100644
--- a/test/scripts/test-projects.test.ts
+++ b/test/scripts/test-projects.test.ts
@@ -4,6 +4,7 @@ import {
   applyParallelVitestCachePaths,
   buildFullSuiteVitestRunPlans,
   buildVitestRunPlans,
+  shouldAcquireLocalHeavyCheckLock,
   resolveChangedTargetArgs,
 } from "../../scripts/test-projects.test-support.mjs";
 
@@ -195,6 +196,79 @@ describe("scripts/test-projects changed-target routing", () => {
   });
 });
 
+describe("scripts/test-projects local heavy-check lock", () => {
+  it("skips the lock for a single scoped serial tooling run", () => {
+    expect(
+      shouldAcquireLocalHeavyCheckLock(
+        [
+          {
+            config: "test/vitest/vitest.tooling.config.ts",
+            includePatterns: ["test/scripts/committer.test.ts"],
+            watchMode: false,
+          },
+        ],
+        {
+          ...process.env,
+          OPENCLAW_TEST_PROJECTS_SERIAL: "1",
+        },
+      ),
+    ).toBe(false);
+  });
+
+  it("keeps the lock for non-tooling or non-serial runs", () => {
+    expect(
+      shouldAcquireLocalHeavyCheckLock(
+        [
+          {
+            config: "test/vitest/vitest.tooling.config.ts",
+            includePatterns: ["test/scripts/committer.test.ts"],
+            watchMode: false,
+          },
+        ],
+        {
+          ...process.env,
+          OPENCLAW_TEST_PROJECTS_SERIAL: "0",
+        },
+      ),
+    ).toBe(true);
+
+    expect(
+      shouldAcquireLocalHeavyCheckLock(
+        [
+          {
+            config: "test/vitest/vitest.unit.config.ts",
+            includePatterns: ["src/infra/vitest-config.test.ts"],
+            watchMode: false,
+          },
+        ],
+        {
+          ...process.env,
+          OPENCLAW_TEST_PROJECTS_SERIAL: "1",
+        },
+      ),
+    ).toBe(true);
+  });
+
+  it("allows forcing the lock back on", () => {
+    expect(
+      shouldAcquireLocalHeavyCheckLock(
+        [
+          {
+            config: "test/vitest/vitest.tooling.config.ts",
+            includePatterns: ["test/scripts/committer.test.ts"],
+            watchMode: false,
+          },
+        ],
+        {
+          ...process.env,
+          OPENCLAW_TEST_PROJECTS_FORCE_LOCK: "1",
+          OPENCLAW_TEST_PROJECTS_SERIAL: "1",
+        },
+      ),
+    ).toBe(true);
+  });
+});
+
 describe("scripts/test-projects full-suite sharding", () => {
   it("splits untargeted runs into fixed core shards and per-extension configs", () => {
     const previousParallel = process.env.OPENCLAW_TEST_PROJECTS_PARALLEL;