From d62279a9b2cd9da34718af6b3a9df49e07218459 Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Sun, 12 Apr 2026 05:35:22 +0100
Subject: [PATCH] fix(tsgo): skip heavy-check lock for metadata commands

---
 scripts/lib/local-heavy-check-runtime.mjs     | 11 +++++++++
 scripts/run-tsgo.mjs                          | 13 +++++++----
 .../scripts/local-heavy-check-runtime.test.ts | 23 +++++++++++++++++++
 3 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/scripts/lib/local-heavy-check-runtime.mjs b/scripts/lib/local-heavy-check-runtime.mjs
index eeed321d057..c3697ba67e6 100644
--- a/scripts/lib/local-heavy-check-runtime.mjs
+++ b/scripts/lib/local-heavy-check-runtime.mjs
@@ -114,6 +114,17 @@ export function shouldAcquireLocalHeavyCheckLockForOxlint(
   });
 }
 
+export function shouldAcquireLocalHeavyCheckLockForTsgo(args, env = process.env) {
+  if (env.OPENCLAW_TSGO_FORCE_LOCK === "1") {
+    return true;
+  }
+
+  return !args.some(
+    (arg) =>
+      arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v" || arg === "--init",
+  );
+}
+
 export function shouldThrottleLocalHeavyChecks(env, hostResources) {
   if (!isLocalCheckEnabled(env)) {
     return false;
diff --git a/scripts/run-tsgo.mjs b/scripts/run-tsgo.mjs
index f7906a74477..9663eefb769 100644
--- a/scripts/run-tsgo.mjs
+++ b/scripts/run-tsgo.mjs
@@ -4,6 +4,7 @@ import path from "node:path";
 import {
   acquireLocalHeavyCheckLockSync,
   applyLocalTsgoPolicy,
+  shouldAcquireLocalHeavyCheckLockForTsgo,
 } from "./lib/local-heavy-check-runtime.mjs";
 
 const { args: finalArgs, env } = applyLocalTsgoPolicy(process.argv.slice(2), process.env);
@@ -13,11 +14,13 @@ const tsBuildInfoFile = readFlagValue(finalArgs, "--tsBuildInfoFile");
 if (tsBuildInfoFile) {
   fs.mkdirSync(path.dirname(path.resolve(tsBuildInfoFile)), { recursive: true });
 }
-const releaseLock = acquireLocalHeavyCheckLockSync({
-  cwd: process.cwd(),
-  env,
-  toolName: "tsgo",
-});
+const releaseLock = shouldAcquireLocalHeavyCheckLockForTsgo(finalArgs, env)
+  ? acquireLocalHeavyCheckLockSync({
+      cwd: process.cwd(),
+      env,
+      toolName: "tsgo",
+    })
+  : () => {};
 
 try {
   const result = spawnSync(tsgoPath, finalArgs, {
diff --git a/test/scripts/local-heavy-check-runtime.test.ts b/test/scripts/local-heavy-check-runtime.test.ts
index cb655f8cd3c..b1527328588 100644
--- a/test/scripts/local-heavy-check-runtime.test.ts
+++ b/test/scripts/local-heavy-check-runtime.test.ts
@@ -6,6 +6,7 @@ import {
   applyLocalOxlintPolicy,
   applyLocalTsgoPolicy,
   shouldAcquireLocalHeavyCheckLockForOxlint,
+  shouldAcquireLocalHeavyCheckLockForTsgo,
 } from "../../scripts/lib/local-heavy-check-runtime.mjs";
 import { createScriptTestHarness } from "./test-helpers.js";
 
@@ -174,6 +175,28 @@ describe("local-heavy-check-runtime", () => {
     expect(env.GOMEMLIMIT).toBeUndefined();
   });
 
+  it("skips the heavy-check lock for tsgo metadata commands", () => {
+    expect(shouldAcquireLocalHeavyCheckLockForTsgo(["--help"])).toBe(false);
+    expect(shouldAcquireLocalHeavyCheckLockForTsgo(["-h"])).toBe(false);
+    expect(shouldAcquireLocalHeavyCheckLockForTsgo(["--version"])).toBe(false);
+    expect(shouldAcquireLocalHeavyCheckLockForTsgo(["-v"])).toBe(false);
+    expect(shouldAcquireLocalHeavyCheckLockForTsgo(["--init"])).toBe(false);
+  });
+
+  it("keeps the heavy-check lock for real tsgo runs", () => {
+    expect(shouldAcquireLocalHeavyCheckLockForTsgo([])).toBe(true);
+    expect(shouldAcquireLocalHeavyCheckLockForTsgo(["--extendedDiagnostics"])).toBe(true);
+  });
+
+  it("allows forcing the tsgo lock back on", () => {
+    expect(
+      shouldAcquireLocalHeavyCheckLockForTsgo(
+        ["--help"],
+        makeEnv({ OPENCLAW_TSGO_FORCE_LOCK: "1" }),
+      ),
+    ).toBe(true);
+  });
+
   it("serializes local oxlint runs onto one thread on constrained hosts", () => {
     const { args } = applyLocalOxlintPolicy([], makeEnv(), CONSTRAINED_HOST);