ttsc 0.18.3 → 0.19.0

package/lib/plugin/internal/buildSourcePlugin.js

@@ -4,6 +4,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildSourcePlugin = buildSourcePlugin;
+exports.acquirePluginBuildLock = acquirePluginBuildLock;
+exports.releasePluginBuildLock = releasePluginBuildLock;
+exports.reclaimPluginBuildLock = reclaimPluginBuildLock;
+exports.waitForPluginBinary = waitForPluginBinary;
+exports.inspectPluginBuildLock = inspectPluginBuildLock;
+exports.formatDuration = formatDuration;
+exports.formatGoWorkPath = formatGoWorkPath;
+exports.autoQuoteGoModToken = autoQuoteGoModToken;
 exports.resolvePluginCacheRoot = resolvePluginCacheRoot;
 exports.resolveSourceBuildCachePaths = resolveSourceBuildCachePaths;
 exports.resolveCleanTargets = resolveCleanTargets;
@@ -111,6 +119,14 @@ const PLUGIN_BUILD_LOCK_POLL_MS = 50;
 const PLUGIN_BUILD_LOCK_LEGACY_STALE_MS = 30_000;
 const PLUGIN_BUILD_LOCK_STATUS_MS = 30_000;
 const PLUGIN_BUILD_LOCK_OWNER_FILE = "owner.json";
+const PLUGIN_BUILD_LOCK_PROTOCOL_FILE = "protocol-v2";
+const PLUGIN_BUILD_LOCK_GENERATION_FILE = "generation";
+const PLUGIN_BUILD_LOCK_LEGACY_FENCE_DIR = "legacy-generation";
+const PLUGIN_BUILD_LOCK_LEGACY_FENCE_RECORD = "fence.json";
+const PLUGIN_BUILD_LOCK_CURRENT_DIR = "current";
+const PLUGIN_BUILD_LOCK_RETIRED_DIR = "retired";
+const PLUGIN_BUILD_LOCK_V2_SUFFIX = ".v2";
+const PLUGIN_BUILD_LOCK_PROTOCOL = "ttsc-plugin-build-lock-v2\n";
 // The default cache lives INSIDE the workspace, at
 // `<workspaceRoot>/node_modules/.cache/ttsc`, so `rm -rf node_modules` (or
 // deleting the repo) reclaims every compiled plugin binary and Go object file.
@@ -141,24 +157,35 @@ const PLUGIN_CACHE_ENTRY_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
 const PLUGIN_CACHE_MAX_BYTES = 2 * 1024 * 1024 * 1024;
 const PLUGIN_CACHE_TARGET_BYTES = Math.floor(PLUGIN_CACHE_MAX_BYTES * 0.8);
 const PLUGIN_CACHE_PROTECTED_AGE_MS = 60 * 60 * 1000;
-/** Build one Go source plugin into a cached executable. */
+/**
+ * Build one Go source plugin into a cached executable.
+ *
+ * `opts.env` is the effective environment for this build — the caller merges `{
+ * ...process.env, ...context.env }` so a programmatic `TtscCompiler` instance
+ * can pin its own Go toolchain (`TTSC_GO_BINARY`), Go build cache
+ * (`TTSC_GO_CACHE_DIR`), and Go build variables (`GOFLAGS`, `CGO_*`, …) without
+ * mutating the shared `process.env`. CLI callers omit it and inherit
+ * `process.env`, so ambient behavior is unchanged.
+ */
 function buildSourcePlugin(opts) {
+    const env = opts.env ?? process.env;
     const { dir, entry, source } = resolveSourceBuildTarget(opts);
     const overlayDirs = [...(opts.overlayDirs ?? findTtscOverlayDirs())].sort();
     const contributors = opts.contributors ?? [];
-    const goBinary = resolveGoCompiler();
+    const goBinary = resolveGoCompiler(env);
     ensureExecutableGoToolchain(goBinary);
     const key = computeCacheKey({
         contributors,
         dir,
         entry,
+        env,
         goBinary,
         overlayDirs,
         ttscVersion: opts.ttscVersion,
         tsgoVersion: opts.tsgoVersion,
     });
-    const paths = resolveSourceBuildCachePaths(opts.baseDir, opts.cacheDir);
-    maybePrunePluginCache(paths, opts.cacheDir);
+    const paths = resolveSourceBuildCachePaths(opts.baseDir, opts.cacheDir, env);
+    maybePrunePluginCache(paths, opts.cacheDir, env);
     const cacheDir = node_path_1.default.join(paths.pluginRoot, key);
     const binaryName = process.platform === "win32" ? "plugin.exe" : "plugin";
     const binaryPath = node_path_1.default.join(cacheDir, binaryName);
@@ -175,6 +202,7 @@ function buildSourcePlugin(opts) {
         contributors,
         dir,
         entry,
+        env,
         goBinary,
         key,
         label,
@@ -199,7 +227,7 @@ function compileSourcePlugin(opts) {
     const scratchDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), `ttsc-plugin-${opts.key}-`));
     try {
         materializeScratchDir(opts.dir, scratchDir);
-        const goModReader = createGoModReader(opts.goBinary, opts.pluginName);
+        const goModReader = createGoModReader(opts.goBinary, opts.pluginName, opts.env);
         if (opts.contributors.length > 0) {
             mergeContributors({
                 contributors: opts.contributors,
@@ -209,9 +237,9 @@ function compileSourcePlugin(opts) {
                 scratchDir,
             });
         }
-        writeGoWork(scratchDir, opts.overlayDirs, opts.goBinary, opts.pluginName);
+        writeGoWork(scratchDir, opts.overlayDirs, opts.goBinary, opts.pluginName, opts.env);
         const scratchBinaryName = process.platform === "win32" ? ".ttsc-plugin.exe" : ".ttsc-plugin";
-        runGoBuild(scratchDir, opts.entry, scratchBinaryName, opts.pluginName, opts.goBinary, opts.goBuildCacheRoot);
+        runGoBuild(scratchDir, opts.entry, scratchBinaryName, opts.pluginName, opts.goBinary, opts.goBuildCacheRoot, opts.env);
         const builtBinary = node_path_1.default.join(scratchDir, scratchBinaryName);
         publishBuiltBinary(builtBinary, opts.binaryPath);
         touchCacheEntry(opts.cacheDir);
@@ -226,17 +254,28 @@ function compileSourcePlugin(opts) {
  * cache key, so concurrent fan-out (parallel suites, a benchmark, a worker
  * pool) runs the `go build` once instead of once per process.
  *
- * The lock is an atomic `mkdir` on `<cacheDir>.lock`. The winner builds and
- * publishes the binary; every loser polls for that binary to appear and reuses
- * it. A loser that waits past `PLUGIN_BUILD_LOCK_STEAL_MS` (the builder crashed
- * without publishing) steals the abandoned lock and retries. This is the same
- * shape as `withBuildLock` in the runtime hooks, keyed on the plugin binary's
- * existence instead of a JSON meta marker.
+ * `<cacheDir>.lock.v2` is a persistent coordination directory. The adjacent
+ * `<cacheDir>.lock` path remains reserved for legacy holders and is never
+ * reused for a v2 generation: an old holder or stale legacy reclaimer can
+ * therefore remove only the legacy path, never a v2 successor. A contender
+ * writes a non-empty candidate and atomically renames it to `current`; only one
+ * rename wins. The winner builds and publishes while every loser polls and
+ * reuses the resulting binary. A loser distinguishes two ways a generation
+ * stops blocking:
+ *
+ * - `released`: the holder retired `current` itself — it published, or its build
+ *   threw and its `finally` freed the key. The loser simply retries the
+ *   ordinary acquisition; nothing is stale and nothing is reported.
+ * - `abandoned`: `current` still exists but its owner is provably dead, it is an
+ *   old metadata-less legacy lock, or the wait budget
+ *   (`PLUGIN_BUILD_LOCK_STEAL_MS`) expired. Only then does the loser report and
+ *   retire precisely that generation before retrying.
  *
- * Correctness still rests on `publishBuiltBinary`'s atomic rename: the lock is
- * an optimisation to avoid duplicate work, not the only guard against a corrupt
- * binary, so a stolen lock that races a slow builder cannot ship a half-written
- * file.
+ * Retired generations remain as non-empty tombstones. Release and reclaim both
+ * rename `current` to the observed generation's deterministic tombstone path.
+ * Once generation A is retired, a stale observer or old finalizer for A cannot
+ * rename successor B there because replacing the non-empty tombstone fails
+ * atomically. `publishBuiltBinary`'s atomic rename remains defense in depth.
  */
 function buildUnderPluginLock(cacheDir, binaryPath, lockInfo, build) {
     const lockDir = `${cacheDir}.lock`;
@@ -245,34 +284,39 @@ function buildUnderPluginLock(cacheDir, binaryPath, lockInfo, build) {
             touchCacheEntry(cacheDir);
             return binaryPath;
         }
+        let lease;
         try {
-            // Plain mkdir (no `recursive`): recursive mode is idempotent and would
-            // not throw EEXIST, defeating the lock. The parent `cacheDir` already
-            // exists, so a single-level mkdir is all that is needed and its EEXIST
-            // is exactly the "someone else holds the lock" signal.
-            node_fs_1.default.mkdirSync(lockDir);
-            writePluginBuildLockOwner(lockDir);
+            lease = acquirePluginBuildLock(lockDir);
         }
-        catch (error) {
-            if (error.code !== "EEXIST") {
-                // A lock dir we cannot create for an unexpected reason (e.g. a
-                // read-only cache) must not silently skip the build. Fall back to an
-                // unlocked build — correctness is preserved by the atomic publish.
-                return build();
-            }
+        catch {
+            // An unusable coordination directory must not silently skip the build.
+            // Atomic publication still preserves binary integrity.
+            return build();
+        }
+        if (lease === null) {
             const waited = waitForPluginBinary({
                 binaryPath,
                 lockDir,
                 lockInfo,
                 timeoutMs: PLUGIN_BUILD_LOCK_STEAL_MS,
             });
-            if (waited.published) {
+            if (waited.outcome === "published") {
                 touchCacheEntry(cacheDir);
                 return binaryPath;
             }
-            reportPluginLockSteal(lockDir, binaryPath, lockInfo, waited.reason);
-            // Builder appears to have crashed: steal the abandoned lock and retry.
-            node_fs_1.default.rmSync(lockDir, { force: true, recursive: true });
+            if (waited.outcome === "abandoned") {
+                // Retire only the generation that produced this observation. Losing
+                // the rename race means another waiter (or the holder's normal
+                // finalizer) already made progress, so do not report a stale result as
+                // an abandonment.
+                if (reclaimPluginBuildLock(lockDir, waited.fence)) {
+                    reportPluginLockSteal(lockDir, binaryPath, lockInfo, waited.reason);
+                }
+            }
+            // "released" needs no repair: the holder freed the key normally (its
+            // build published or failed), so retry the ordinary atomic acquisition.
+            // Reporting a steal or force-removing the path here would misclassify a
+            // routine handoff as abandonment (issue #421).
             continue;
         }
         try {
@@ -284,30 +328,203 @@ function buildUnderPluginLock(cacheDir, binaryPath, lockInfo, build) {
             return build();
         }
         finally {
-            node_fs_1.default.rmSync(lockDir, { force: true, recursive: true });
+            releasePluginBuildLock(lockDir, lease);
+        }
+    }
+}
+/**
+ * Atomically acquire the current generation in a v2 coordination directory.
+ *
+ * A non-empty candidate is renamed to `current`. Directory rename cannot
+ * replace a non-empty `current`, so exactly one contender wins without an
+ * empty-owner publication window. `null` means either another v2 holder won or
+ * the path is a legacy lock that must be observed before it can be reclaimed.
+ *
+ * Exported for deterministic multi-process tests.
+ */
+function acquirePluginBuildLock(lockDir) {
+    // A legacy holder owns the old path. Never publish v2 ownership into that
+    // deletable namespace; wait until the legacy generation is released or
+    // reclaimed, then use the orthogonal persistent v2 directory.
+    if (pluginBuildLockPathExists(lockDir)) {
+        return null;
+    }
+    const protocolDir = pluginBuildLockProtocolDir(lockDir);
+    ensurePluginBuildLockProtocol(protocolDir);
+    // Close the initialization window as far as the legacy protocol permits. A
+    // legacy holder that appeared while v2 was initialized still blocks this
+    // acquisition. (A legacy executable cannot provide a true cross-path CAS.)
+    if (pluginBuildLockPathExists(lockDir)) {
+        return null;
+    }
+    const generation = node_crypto_1.default.randomBytes(16).toString("hex");
+    const candidateDir = node_path_1.default.join(protocolDir, `candidate-${generation}`);
+    node_fs_1.default.mkdirSync(candidateDir);
+    try {
+        node_fs_1.default.writeFileSync(node_path_1.default.join(candidateDir, PLUGIN_BUILD_LOCK_GENERATION_FILE), `${generation}\n`, { encoding: "utf8", flag: "wx" });
+        writePluginBuildLockOwner(candidateDir, generation);
+        try {
+            node_fs_1.default.renameSync(candidateDir, node_path_1.default.join(protocolDir, PLUGIN_BUILD_LOCK_CURRENT_DIR));
+        }
+        catch (error) {
+            if (isMissingPathError(error) ||
+                isRenameDestinationOccupied(error, node_path_1.default.join(protocolDir, PLUGIN_BUILD_LOCK_CURRENT_DIR))) {
+                return null;
+            }
+            throw error;
+        }
+        return { protocol: "v2", generation };
+    }
+    finally {
+        // The candidate name contains this process's random generation and can
+        // never alias `current` or another contender's candidate.
+        node_fs_1.default.rmSync(candidateDir, { force: true, recursive: true });
+    }
+}
+/** Retire a held generation during the holder's `finally`. */
+function releasePluginBuildLock(lockDir, lease) {
+    return retireV2PluginBuildLock(pluginBuildLockProtocolDir(lockDir), lease.generation);
+}
+/**
+ * Retire exactly the generation carried by an abandoned observation.
+ *
+ * Exported for deterministic multi-process tests.
+ */
+function reclaimPluginBuildLock(lockDir, fence) {
+    if (fence.protocol === "v2") {
+        return retireV2PluginBuildLock(pluginBuildLockProtocolDir(lockDir), fence.generation);
+    }
+    return retireLegacyPluginBuildLock(lockDir, fence.generation);
+}
+function pluginBuildLockProtocolDir(lockDir) {
+    return `${lockDir}${PLUGIN_BUILD_LOCK_V2_SUFFIX}`;
+}
+function ensurePluginBuildLockProtocol(protocolDir) {
+    if (isPluginBuildLockProtocolV2(protocolDir)) {
+        return;
+    }
+    const generation = node_crypto_1.default.randomBytes(16).toString("hex");
+    const candidateDir = `${protocolDir}.candidate-${generation}`;
+    node_fs_1.default.mkdirSync(candidateDir);
+    try {
+        node_fs_1.default.mkdirSync(node_path_1.default.join(candidateDir, PLUGIN_BUILD_LOCK_RETIRED_DIR));
+        node_fs_1.default.writeFileSync(node_path_1.default.join(candidateDir, PLUGIN_BUILD_LOCK_PROTOCOL_FILE), PLUGIN_BUILD_LOCK_PROTOCOL, { encoding: "utf8", flag: "wx" });
+        try {
+            node_fs_1.default.renameSync(candidateDir, protocolDir);
+        }
+        catch (error) {
+            if (isRenameDestinationOccupied(error, protocolDir) &&
+                isPluginBuildLockProtocolV2(protocolDir)) {
+                return;
+            }
+            throw error;
+        }
+    }
+    finally {
+        node_fs_1.default.rmSync(candidateDir, { force: true, recursive: true });
+    }
+}
+function isPluginBuildLockProtocolV2(lockDir) {
+    try {
+        return (node_fs_1.default.readFileSync(node_path_1.default.join(lockDir, PLUGIN_BUILD_LOCK_PROTOCOL_FILE), "utf8") === PLUGIN_BUILD_LOCK_PROTOCOL);
+    }
+    catch {
+        return false;
+    }
+}
+function retireV2PluginBuildLock(lockDir, generation) {
+    if (!isPluginBuildLockGeneration(generation))
+        return false;
+    const retiredDir = node_path_1.default.join(lockDir, PLUGIN_BUILD_LOCK_RETIRED_DIR);
+    try {
+        node_fs_1.default.mkdirSync(retiredDir);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST") {
+            if (isMissingPathError(error))
+                return false;
+            throw error;
         }
     }
+    const destination = node_path_1.default.join(retiredDir, generation);
+    try {
+        node_fs_1.default.renameSync(node_path_1.default.join(lockDir, PLUGIN_BUILD_LOCK_CURRENT_DIR), destination);
+        return true;
+    }
+    catch (error) {
+        if (isMissingPathError(error) ||
+            isRenameDestinationOccupied(error, destination)) {
+            return false;
+        }
+        throw error;
+    }
+}
+function retireLegacyPluginBuildLock(lockDir, generation) {
+    if (!isPluginBuildLockGeneration(generation))
+        return false;
+    const captured = readLegacyPluginBuildLockFence(node_path_1.default.join(lockDir, PLUGIN_BUILD_LOCK_LEGACY_FENCE_DIR));
+    if (captured?.fence.generation !== generation) {
+        return false;
+    }
+    const destination = `${lockDir}.retired-${generation}`;
+    try {
+        node_fs_1.default.renameSync(lockDir, destination);
+        return true;
+    }
+    catch (error) {
+        if (isMissingPathError(error) ||
+            isRenameDestinationOccupied(error, destination)) {
+            return false;
+        }
+        throw error;
+    }
+}
+function isMissingPathError(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR";
 }
-/** Poll for the locked builder to publish its binary, up to `timeoutMs`. */
+function isRenameDestinationOccupied(error, destination) {
+    const code = error.code;
+    if (code === "EEXIST" || code === "ENOTEMPTY") {
+        return true;
+    }
+    return (code === "EACCES" || code === "EPERM") && node_fs_1.default.existsSync(destination);
+}
+/**
+ * Poll for the locked builder to publish its binary, up to `timeoutMs`.
+ *
+ * Exported for unit tests.
+ */
 function waitForPluginBinary(opts) {
     const startedAt = Date.now();
     let nextStatusAt = startedAt + PLUGIN_BUILD_LOCK_STATUS_MS;
     for (;;) {
         if (node_fs_1.default.existsSync(opts.binaryPath)) {
-            return { published: true };
+            return { outcome: "published" };
         }
         const now = Date.now();
-        const lockStatus = inspectPluginBuildLock(opts.lockDir, now);
-        if (lockStatus.abandoned) {
+        const lock = inspectPluginBuildLock(opts.lockDir, now);
+        if (lock.state === "released") {
+            // The holder retired its generation between the binary check above and
+            // this observation. That is a normal release, not abandonment: prefer the
+            // binary when it landed inside that window, otherwise hand the free key
+            // back to the caller.
+            return node_fs_1.default.existsSync(opts.binaryPath)
+                ? { outcome: "published" }
+                : { outcome: "released" };
+        }
+        if (lock.state === "abandoned") {
             return {
-                published: false,
-                reason: lockStatus.reason,
+                outcome: "abandoned",
+                reason: lock.reason,
+                fence: lock.fence,
             };
         }
         if (now - startedAt > opts.timeoutMs) {
             return {
-                published: false,
+                outcome: "abandoned",
                 reason: `timed out after ${formatDuration(now - startedAt)}`,
+                fence: lock.fence,
             };
         }
         if (!opts.lockInfo.quiet && now >= nextStatusAt) {
@@ -316,55 +533,221 @@ function waitForPluginBinary(opts) {
                 elapsedMs: now - startedAt,
                 lockDir: opts.lockDir,
                 lockInfo: opts.lockInfo,
-                owner: lockStatus.owner,
+                owner: lock.owner,
             });
             nextStatusAt = now + PLUGIN_BUILD_LOCK_STATUS_MS;
         }
         sleepSync(PLUGIN_BUILD_LOCK_POLL_MS);
     }
 }
-function writePluginBuildLockOwner(lockDir) {
-    try {
-        node_fs_1.default.writeFileSync(node_path_1.default.join(lockDir, PLUGIN_BUILD_LOCK_OWNER_FILE), `${JSON.stringify({
-            hostname: node_os_1.default.hostname(),
-            pid: process.pid,
-            startedAt: new Date().toISOString(),
-        }, null, 2)}\n`, "utf8");
+function writePluginBuildLockOwner(generationDir, generation) {
+    node_fs_1.default.writeFileSync(node_path_1.default.join(generationDir, PLUGIN_BUILD_LOCK_OWNER_FILE), `${JSON.stringify({
+        generation,
+        hostname: node_os_1.default.hostname(),
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    }, null, 2)}\n`, "utf8");
+}
+/**
+ * Classify the current state of a plugin build lock directory.
+ *
+ * Exported for unit tests.
+ */
+function inspectPluginBuildLock(lockDir, now) {
+    const protocolDir = pluginBuildLockProtocolDir(lockDir);
+    for (;;) {
+        if (isPluginBuildLockProtocolV2(protocolDir)) {
+            const v2 = inspectV2PluginBuildLock(protocolDir, now);
+            if (v2.state !== "released") {
+                return v2;
+            }
+        }
+        const legacy = captureLegacyPluginBuildLockFence(lockDir);
+        if (legacy !== null) {
+            return inspectLegacyPluginBuildLock(lockDir, now, legacy);
+        }
+        if (pluginBuildLockAgeMs(lockDir, now) === null) {
+            return { state: "released" };
+        }
+        // The path changed while its legacy fence was being captured. Re-observe
+        // the replacement rather than attaching the old state to a new owner.
     }
-    catch {
-        // Best-effort metadata: the mkdir lock still serializes the build.
+}
+function inspectV2PluginBuildLock(lockDir, now) {
+    const generationDir = node_path_1.default.join(lockDir, PLUGIN_BUILD_LOCK_CURRENT_DIR);
+    const generation = readPluginBuildLockGeneration(generationDir);
+    if (generation === null) {
+        if (pluginBuildLockAgeMs(generationDir, now) === null) {
+            return { state: "released" };
+        }
+        throw new Error(`ttsc plugin build lock has no valid ${PLUGIN_BUILD_LOCK_GENERATION_FILE}: ${generationDir}`);
     }
+    const fence = { protocol: "v2", generation };
+    const owner = readPluginBuildLockOwner(generationDir);
+    if (owner !== null) {
+        const label = describePluginBuildLockOwner(owner);
+        if (isLocalHostName(owner.hostname) && !isProcessAlive(owner.pid)) {
+            return {
+                state: "abandoned",
+                reason: `${label} is no longer running`,
+                fence,
+            };
+        }
+        return {
+            state: "active",
+            owner: label,
+            fence,
+        };
+    }
+    const ageMs = pluginBuildLockAgeMs(generationDir, now);
+    if (ageMs === null) {
+        return { state: "released" };
+    }
+    if (ageMs > PLUGIN_BUILD_LOCK_LEGACY_STALE_MS) {
+        return {
+            state: "abandoned",
+            reason: `lock generation has no ${PLUGIN_BUILD_LOCK_OWNER_FILE} and is ` +
+                `${formatDuration(ageMs)} old`,
+            fence,
+        };
+    }
+    return {
+        state: "active",
+        owner: `lock generation with no ${PLUGIN_BUILD_LOCK_OWNER_FILE}`,
+        fence,
+    };
 }
-function inspectPluginBuildLock(lockDir, now) {
+function inspectLegacyPluginBuildLock(lockDir, now, legacy) {
     const owner = readPluginBuildLockOwner(lockDir);
     if (owner !== null) {
         const label = describePluginBuildLockOwner(owner);
         if (isLocalHostName(owner.hostname) && !isProcessAlive(owner.pid)) {
             return {
-                abandoned: true,
-                owner: label,
+                state: "abandoned",
                 reason: `${label} is no longer running`,
+                fence: legacy.fence,
             };
         }
         return {
-            abandoned: false,
+            state: "active",
             owner: label,
+            fence: legacy.fence,
         };
     }
-    const ageMs = pluginBuildLockAgeMs(lockDir, now);
+    const ageMs = Math.max(0, now - legacy.legacyMtimeMs);
     if (ageMs > PLUGIN_BUILD_LOCK_LEGACY_STALE_MS) {
         return {
-            abandoned: true,
-            owner: `legacy lock with no ${PLUGIN_BUILD_LOCK_OWNER_FILE}`,
+            state: "abandoned",
             reason: `legacy lock has no ${PLUGIN_BUILD_LOCK_OWNER_FILE} and is ` +
                 `${formatDuration(ageMs)} old`,
+            fence: legacy.fence,
         };
     }
     return {
-        abandoned: false,
+        state: "active",
         owner: `legacy lock with no ${PLUGIN_BUILD_LOCK_OWNER_FILE}`,
+        fence: legacy.fence,
     };
 }
+function captureLegacyPluginBuildLockFence(lockDir) {
+    if (isPluginBuildLockProtocolV2(lockDir)) {
+        return null;
+    }
+    let legacyMtimeMs;
+    try {
+        legacyMtimeMs = node_fs_1.default.statSync(lockDir).mtimeMs;
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return null;
+        throw error;
+    }
+    const fenceDir = node_path_1.default.join(lockDir, PLUGIN_BUILD_LOCK_LEGACY_FENCE_DIR);
+    let captured = readLegacyPluginBuildLockFence(fenceDir);
+    if (captured === null) {
+        const generation = node_crypto_1.default.randomBytes(16).toString("hex");
+        // Keep candidates beside the legacy lock. Creating one inside `lockDir`
+        // would advance its mtime before a contender publishes the shared fence;
+        // a concurrent contender could then record an old lock as freshly created.
+        const candidateDir = `${lockDir}.legacy-candidate-${generation}`;
+        try {
+            node_fs_1.default.mkdirSync(candidateDir);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(candidateDir, PLUGIN_BUILD_LOCK_LEGACY_FENCE_RECORD), `${JSON.stringify({ generation, legacyMtimeMs })}\n`, "utf8");
+            try {
+                node_fs_1.default.renameSync(candidateDir, fenceDir);
+                captured = {
+                    fence: { protocol: "legacy", generation },
+                    legacyMtimeMs,
+                };
+            }
+            catch (error) {
+                if (isRenameDestinationOccupied(error, fenceDir)) {
+                    captured = readLegacyPluginBuildLockFence(fenceDir);
+                }
+                else if (isMissingPathError(error)) {
+                    return null;
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        catch (error) {
+            if (isMissingPathError(error)) {
+                return null;
+            }
+            throw error;
+        }
+        finally {
+            node_fs_1.default.rmSync(candidateDir, { force: true, recursive: true });
+        }
+    }
+    if (captured === null) {
+        throw new Error(`invalid legacy plugin build lock fence: ${fenceDir}`);
+    }
+    // A stale observer can resume after the legacy holder released or another
+    // process retired the path. Confirm both the legacy layout and token after
+    // publication; v2 ownership is kept in the orthogonal sibling directory.
+    const confirmed = readLegacyPluginBuildLockFence(fenceDir);
+    if (isPluginBuildLockProtocolV2(lockDir) ||
+        confirmed === null ||
+        confirmed.fence.generation !== captured.fence.generation) {
+        return null;
+    }
+    return captured;
+}
+function readLegacyPluginBuildLockFence(fenceDir) {
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(fenceDir, PLUGIN_BUILD_LOCK_LEGACY_FENCE_RECORD), "utf8"));
+        if (!isPluginBuildLockGeneration(parsed.generation) ||
+            typeof parsed.legacyMtimeMs !== "number" ||
+            !Number.isFinite(parsed.legacyMtimeMs) ||
+            parsed.legacyMtimeMs < 0) {
+            return null;
+        }
+        return {
+            fence: { protocol: "legacy", generation: parsed.generation },
+            legacyMtimeMs: parsed.legacyMtimeMs,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function readPluginBuildLockGeneration(generationDir) {
+    try {
+        const generation = node_fs_1.default
+            .readFileSync(node_path_1.default.join(generationDir, PLUGIN_BUILD_LOCK_GENERATION_FILE), "utf8")
+            .trim();
+        return isPluginBuildLockGeneration(generation) ? generation : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isPluginBuildLockGeneration(value) {
+    return typeof value === "string" && /^[0-9a-f]{32}$/.test(value);
+}
 function readPluginBuildLockOwner(lockDir) {
     try {
         const parsed = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(lockDir, PLUGIN_BUILD_LOCK_OWNER_FILE), "utf8"));
@@ -384,12 +767,35 @@ function readPluginBuildLockOwner(lockDir) {
         return null;
     }
 }
+/**
+ * Age of an observed lock directory, or `null` when it no longer exists. The
+ * holder may have retired it between the caller's checks. "Missing" is a
+ * observation, never encoded as a numeric age: the previous
+ * `Number.POSITIVE_INFINITY` encoding made a just-released lock look like an
+ * infinitely old abandoned legacy lock (issue #421).
+ *
+ * A stat failure that does not prove absence (e.g. `EPERM`) clamps to age 0:
+ * the lock is treated as fresh so a waiter never steals on ambiguous evidence,
+ * while the caller's wait budget still bounds the stall.
+ */
 function pluginBuildLockAgeMs(lockDir, now) {
     try {
         return Math.max(0, now - node_fs_1.default.statSync(lockDir).mtimeMs);
     }
-    catch {
-        return Number.POSITIVE_INFINITY;
+    catch (error) {
+        const code = error.code;
+        return code === "ENOENT" || code === "ENOTDIR" ? null : 0;
+    }
+}
+function pluginBuildLockPathExists(lockDir) {
+    try {
+        node_fs_1.default.statSync(lockDir);
+        return true;
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return false;
+        throw error;
     }
 }
 function isLocalHostName(hostname) {
@@ -416,11 +822,23 @@ function reportPluginLockWait(opts) {
 function reportPluginLockSteal(lockDir, binaryPath, lockInfo, reason) {
     if (lockInfo.quiet)
         return;
-    const suffix = reason === undefined ? "" : ` (${reason})`;
     process.stderr.write(`ttsc: reclaiming abandoned ${lockInfo.label} "${lockInfo.pluginName}" ` +
-        `cache lock at ${lockDir}; binary=${binaryPath}${suffix}\n`);
+        `cache lock at ${lockDir}; binary=${binaryPath} (${reason})\n`);
 }
+/**
+ * Render a millisecond duration for lock diagnostics (`137ms`, `42s`, `9m 3s`).
+ *
+ * Total over every number: no caller produces a non-finite duration anymore
+ * (the lock state machine reports "released" instead of an Infinity age), but
+ * as defense in depth a non-finite input renders as `an unknown time` so no
+ * public diagnostic can ever print `Infinitym NaNs` again (issue #421).
+ *
+ * Exported for unit tests.
+ */
 function formatDuration(ms) {
+    if (!Number.isFinite(ms)) {
+        return "an unknown time";
+    }
     if (ms < 1_000) {
         return `${Math.max(0, Math.round(ms))}ms`;
     }
@@ -628,8 +1046,8 @@ function materializeScratchDir(source, scratch) {
         },
     });
 }
-function writeGoWork(scratchDir, useDirs, goBinary, pluginName) {
-    const goModReader = createGoModReader(goBinary, pluginName);
+function writeGoWork(scratchDir, useDirs, goBinary, pluginName, env) {
+    const goModReader = createGoModReader(goBinary, pluginName, env);
     validateSourceReplacements(scratchDir, useDirs, goModReader, pluginName);
     const sourceInfo = goModReader.read(scratchDir);
     const effectiveUseDirs = sourceInfo.modulePath === TTSC_GO_MODULE_PATH
@@ -640,7 +1058,7 @@ function writeGoWork(scratchDir, useDirs, goBinary, pluginName) {
         : useDirs;
     const useLines = ["\t."];
     for (const dir of effectiveUseDirs) {
-        useLines.push(`\t${dir.replace(/\\/g, "/")}`);
+        useLines.push(`\t${formatGoWorkPath(dir)}`);
     }
     const replaceLines = sourceBuildWorkspaceReplacements(effectiveUseDirs, goModReader);
     const replaceBlock = replaceLines.length === 0 ? "" : `\n\n${replaceLines.join("\n")}\n`;
@@ -672,10 +1090,125 @@ function sourceBuildWorkspaceReplacements(useDirs, goModReader) {
         return [];
     }
     return [
-        `replace ${TTSC_GO_MODULE_PATH} v0.0.0 => ${ttscRoot.replace(/\\/g, "/")}`,
+        `replace ${TTSC_GO_MODULE_PATH} v0.0.0 => ${formatGoWorkPath(ttscRoot)}`,
     ];
 }
-function createGoModReader(goBinary, pluginName) {
+/**
+ * Format an absolute filesystem path as a single `go.work`/`go.mod` token.
+ *
+ * The modfile grammar shared by `go.mod` and `go.work` (parsed by
+ * `golang.org/x/mod/modfile`) is whitespace-tokenized, so a `use`/`replace`
+ * path that contains a space — a home or project directory such as `/Users/John
+ * Smith/...` or `C:\Users\John Smith\...` — must be emitted as a quoted string
+ * or `go` cannot parse the generated `go.work`. Normalize Windows separators to
+ * `/` (the workspace convention) and then delegate to
+ * {@link autoQuoteGoModToken}, which mirrors `modfile.AutoQuote`.
+ *
+ * Exported for unit tests.
+ */
+function formatGoWorkPath(p) {
+    return autoQuoteGoModToken(p.replace(/\\/g, "/"));
+}
+/**
+ * Quote `token` for a `go.mod`/`go.work` line exactly as
+ * `golang.org/x/mod/modfile`'s `AutoQuote` does: return it unchanged when it is
+ * already a clean bare token, otherwise return its Go double-quoted form so the
+ * value round-trips through the modfile lexer. A space-free path is therefore
+ * emitted byte-for-byte as before; only tokens that would otherwise
+ * mis-tokenize are quoted.
+ *
+ * Exported for unit tests.
+ */
+function autoQuoteGoModToken(token) {
+    return mustQuoteGoModToken(token) ? goQuoteString(token) : token;
+}
+// Mirror `modfile.MustQuote`: report whether `s` must be quoted to appear as a
+// single token on a modfile line.
+function mustQuoteGoModToken(s) {
+    for (const ch of s) {
+        if (ch === " " || ch === '"' || ch === "'" || ch === "`") {
+            return true;
+        }
+        if (ch === "(" ||
+            ch === ")" ||
+            ch === "[" ||
+            ch === "]" ||
+            ch === "{" ||
+            ch === "}" ||
+            ch === ",") {
+            // Go tests `len(s) > 1` (byte length): a lone bracket/comma is a legal
+            // bare token, but one embedded in a longer token forces quoting.
+            if (Buffer.byteLength(s, "utf8") > 1) {
+                return true;
+            }
+            continue;
+        }
+        if (!isGoGraphic(ch)) {
+            return true;
+        }
+    }
+    return s === "" || s === "//" || s === "/*";
+}
+// Mirror `strconv.Quote`: wrap in double quotes, backslash-escape `"` and `\`,
+// emit Go-printable runes verbatim (including the ASCII space and printable
+// Unicode), and escape everything else with Go's `\a\b\f\n\r\t\v` / `\xNN` /
+// `\uNNNN` / `\UNNNNNNNN` forms so the token round-trips through
+// `strconv.Unquote` in the modfile lexer.
+function goQuoteString(s) {
+    let out = '"';
+    for (const ch of s) {
+        if (ch === '"' || ch === "\\") {
+            out += `\\${ch}`;
+            continue;
+        }
+        if (isGoPrintable(ch)) {
+            out += ch;
+            continue;
+        }
+        out += escapeGoRune(ch);
+    }
+    return `${out}"`;
+}
+function escapeGoRune(ch) {
+    switch (ch) {
+        case "\x07":
+            return "\\a";
+        case "\b":
+            return "\\b";
+        case "\f":
+            return "\\f";
+        case "\n":
+            return "\\n";
+        case "\r":
+            return "\\r";
+        case "\t":
+            return "\\t";
+        case "\v":
+            return "\\v";
+        default: {
+            const cp = ch.codePointAt(0) ?? 0;
+            if (cp < 0x20 || cp === 0x7f) {
+                return `\\x${cp.toString(16).padStart(2, "0")}`;
+            }
+            if (cp < 0x10000) {
+                return `\\u${cp.toString(16).padStart(4, "0")}`;
+            }
+            return `\\U${cp.toString(16).padStart(8, "0")}`;
+        }
+    }
+}
+// `unicode.IsGraphic`: categories L, M, N, P, S, Zs (all spacing).
+const GO_GRAPHIC_RE = /^[\p{L}\p{M}\p{N}\p{P}\p{S}\p{Zs}]$/u;
+function isGoGraphic(ch) {
+    return GO_GRAPHIC_RE.test(ch);
+}
+// `strconv.IsPrint`: the graphic categories except that the ONLY spacing
+// character is the ASCII space (U+0020); other Unicode spaces are escaped.
+const GO_PRINTABLE_RE = /^[\p{L}\p{M}\p{N}\p{P}\p{S}]$/u;
+function isGoPrintable(ch) {
+    return ch === " " || GO_PRINTABLE_RE.test(ch);
+}
+function createGoModReader(goBinary, pluginName, env) {
     const cache = new Map();
     return {
         read(dir) {
@@ -684,20 +1217,20 @@ function createGoModReader(goBinary, pluginName) {
             if (cached !== undefined) {
                 return cached;
             }
-            const info = readGoModInfo(resolved, goBinary, pluginName);
+            const info = readGoModInfo(resolved, goBinary, pluginName, env);
             cache.set(resolved, info);
             return info;
         },
     };
 }
-function readGoModInfo(dir, goBinary, pluginName) {
+function readGoModInfo(dir, goBinary, pluginName, env) {
     if (!node_fs_1.default.existsSync(node_path_1.default.join(dir, "go.mod"))) {
         return emptyGoModInfo();
     }
     const result = spawnGoTool(goBinary, ["mod", "edit", "-json"], {
         cwd: dir,
         encoding: "utf8",
-        env: goBuildEnv(goBinary),
+        env: goBuildEnv(goBinary, undefined, env),
         maxBuffer: 1024 * 1024 * 16,
         windowsHide: true,
     });
@@ -754,12 +1287,12 @@ function isTtscManagedModulePath(modulePath) {
         modulePath === TSGO_GO_MODULE_PATH ||
         modulePath.startsWith("github.com/microsoft/typescript-go/shim/"));
 }
-function runGoBuild(cwd, entry, binaryName, pluginName, goBinary, goBuildCacheRoot) {
+function runGoBuild(cwd, entry, binaryName, pluginName, goBinary, goBuildCacheRoot, env) {
     ensureExecutableGoToolchain(goBinary);
     const result = spawnGoTool(goBinary, ["build", "-o", binaryName, entry], {
         cwd,
         encoding: "utf8",
-        env: goBuildEnv(goBinary, goBuildCacheRoot),
+        env: goBuildEnv(goBinary, goBuildCacheRoot, env),
         maxBuffer: 1024 * 1024 * 64,
         windowsHide: true,
     });
@@ -792,8 +1325,8 @@ function spawnGoTool(goBinary, args, options) {
 function shouldSpawnGoToolThroughShell(goBinary) {
     return process.platform === "win32" && /\.(?:bat|cmd)$/i.test(goBinary);
 }
-function goBuildEnv(goBinary, goBuildCacheRoot) {
-    const env = { ...process.env };
+function goBuildEnv(goBinary, goBuildCacheRoot, effectiveEnv = process.env) {
+    const env = { ...effectiveEnv };
     env.GOWORK = "auto";
     // Only the actual `go build` needs ttsc's GOCACHE; read-only metadata spawns
     // (`go mod edit`, `go env`, `go version`) call goBuildEnv with no cache root
@@ -906,9 +1439,9 @@ function walkForGoMod(dir, out) {
  * callers (and tests) that only need the plugin-binary root. Triggers the
  * opportunistic project-cache GC as a side effect for the default location.
  */
-function resolvePluginCacheRoot(projectRoot, cacheDir) {
-    const paths = resolveSourceBuildCachePaths(projectRoot, cacheDir);
-    maybePrunePluginCache(paths, cacheDir);
+function resolvePluginCacheRoot(projectRoot, cacheDir, env = process.env) {
+    const paths = resolveSourceBuildCachePaths(projectRoot, cacheDir, env);
+    maybePrunePluginCache(paths, cacheDir, env);
     return paths.pluginRoot;
 }
 /**
@@ -1044,11 +1577,13 @@ function resolveGoBuildCacheRoot(root, projectRoot, env) {
         source: "ttsc-cache",
     };
 }
-function maybePrunePluginCache(paths, cacheDir) {
+function maybePrunePluginCache(paths, cacheDir, env = process.env) {
     // GC only the default (workspace-local) location. When the user pins an
     // explicit `cacheDir`/`TTSC_CACHE_DIR`, they own its lifetime, so ttsc must
-    // not delete entries out from under them.
-    if (!cacheDir && !process.env.TTSC_CACHE_DIR) {
+    // not delete entries out from under them. `env` is the effective instance
+    // environment so a programmatic caller that pins `TTSC_CACHE_DIR` only in
+    // `context.env` is honored without leaning on the shared `process.env`.
+    if (!cacheDir && !env.TTSC_CACHE_DIR) {
         prunePluginCacheRoot(paths.pluginRoot);
     }
 }
@@ -1122,8 +1657,8 @@ function isPathWithin(child, parent) {
     return (rel === "" ||
         (rel !== ".." && !rel.startsWith(`..${node_path_1.default.sep}`) && !node_path_1.default.isAbsolute(rel)));
 }
-function resolveGoCompiler() {
-    const explicit = process.env.TTSC_GO_BINARY;
+function resolveGoCompiler(env = process.env) {
+    const explicit = env.TTSC_GO_BINARY;
     if (explicit && explicit.length > 0)
         return explicit;
     try {
@@ -1138,7 +1673,7 @@ function resolveGoCompiler() {
     const local = node_path_1.default.resolve(__dirname, "..", "..", "..", "..", "native", "go", "bin", process.platform === "win32" ? "go.exe" : "go");
     if (node_fs_1.default.existsSync(local))
         return local;
-    const homeSdk = node_path_1.default.join(process.env.HOME ?? "", "go-sdk", "go", "bin", process.platform === "win32" ? "go.exe" : "go");
+    const homeSdk = node_path_1.default.join(env.HOME ?? "", "go-sdk", "go", "bin", process.platform === "win32" ? "go.exe" : "go");
     if (node_fs_1.default.existsSync(homeSdk))
         return homeSdk;
     return "go";
@@ -1155,16 +1690,17 @@ function resolveGoCompiler() {
  * Exposed for testing and for the `ttsc cache` CLI command.
  */
 function computeCacheKey(inputs) {
+    const env = inputs.env ?? process.env;
     const hash = node_crypto_1.default.createHash("sha256");
     hash.update(`ttsc=${inputs.ttscVersion}\n`);
     hash.update(`tsgo=${inputs.tsgoVersion}\n`);
     hash.update(`platform=${process.platform}/${process.arch}\n`);
     hash.update(`entry=${inputs.entry}\n`);
     if (inputs.goBinary !== undefined) {
-        hash.update(`go=${resolveGoCompilerIdentity(inputs.goBinary)}\n`);
+        hash.update(`go=${resolveGoCompilerIdentity(inputs.goBinary, env)}\n`);
     }
-    hashGoBuildEnvironment(hash, inputs.goBinary, inputs.dir);
-    hashExternalGoBuildEnvironment(hash);
+    hashGoBuildEnvironment(hash, inputs.goBinary, inputs.dir, env);
+    hashExternalGoBuildEnvironment(hash, env);
     hashSourceDirectory(hash, "plugin", inputs.dir);
     for (const [index, dir] of [...(inputs.overlayDirs ?? [])].sort().entries()) {
         hashSourceDirectory(hash, `overlay:${index}`, dir);
@@ -1249,8 +1785,8 @@ function isHashableFile(name) {
 // cache-key bytes stay byte-for-byte identical to today. `go version` reads no
 // cwd/custom env (the spawn passes neither), so cwd is not part of the key.
 const goCompilerIdentityCache = new Map();
-function resolveGoCompilerIdentity(goBinary) {
-    const resolved = resolveExecutableIdentityPath(goBinary);
+function resolveGoCompilerIdentity(goBinary, env = process.env) {
+    const resolved = resolveExecutableIdentityPath(goBinary, env);
     const memoKey = goCompilerIdentityMemoKey(goBinary, resolved);
     if (memoKey !== null) {
         const cached = goCompilerIdentityCache.get(memoKey);
@@ -1290,14 +1826,14 @@ function computeGoCompilerIdentity(goBinary, resolved) {
     const binaryHash = hashFile(resolved);
     return `sha256:${binaryHash}:${versionText}`;
 }
-function resolveExecutableIdentityPath(binary) {
+function resolveExecutableIdentityPath(binary, env = process.env) {
     if (node_path_1.default.isAbsolute(binary)) {
         return resolveRealPath(binary);
     }
     if (binary.includes(node_path_1.default.sep)) {
         return resolveRealPath(node_path_1.default.resolve(binary));
     }
-    for (const dir of readPathEnvironment().split(node_path_1.default.delimiter)) {
+    for (const dir of readPathEnvironment(env).split(node_path_1.default.delimiter)) {
         if (dir.length === 0)
             continue;
         const candidate = node_path_1.default.join(dir, binary);
@@ -1309,7 +1845,7 @@ function resolveExecutableIdentityPath(binary) {
             // a `.cmd`/`.bat` wrapper resolves to its real file and is hashed into the
             // cache key. Otherwise the wrapper reads as "missing" and a change to it
             // would not invalidate the cached plugin binary.
-            for (const ext of windowsExecutableExtensions()) {
+            for (const ext of windowsExecutableExtensions(env)) {
                 const executable = `${candidate}${ext}`;
                 if (node_fs_1.default.existsSync(executable)) {
                     return resolveRealPath(executable);
@@ -1319,16 +1855,16 @@ function resolveExecutableIdentityPath(binary) {
     }
     return binary;
 }
-function windowsExecutableExtensions() {
-    const pathext = process.env.PATHEXT;
+function windowsExecutableExtensions(env = process.env) {
+    const pathext = env.PATHEXT;
     const raw = pathext && pathext.length > 0 ? pathext : ".COM;.EXE;.BAT;.CMD";
     return raw
         .split(";")
         .map((ext) => ext.trim().toLowerCase())
         .filter((ext) => ext.length > 0);
 }
-function readPathEnvironment() {
-    return process.env.PATH ?? process.env.Path ?? "";
+function readPathEnvironment(env = process.env) {
+    return env.PATH ?? env.Path ?? "";
 }
 function resolveRealPath(location) {
     try {
@@ -1343,8 +1879,8 @@ function hashFile(file) {
     hash.update(node_fs_1.default.readFileSync(file));
     return hash.digest("hex");
 }
-function hashGoBuildEnvironment(hash, goBinary, cwd) {
-    const values = resolveGoBuildEnvironment(goBinary, cwd);
+function hashGoBuildEnvironment(hash, goBinary, cwd, env) {
+    const values = resolveGoBuildEnvironment(goBinary, cwd, env);
     for (const key of GO_BUILD_ENV_KEYS) {
         const value = values.get(key);
         if (value !== undefined && value !== "") {
@@ -1352,13 +1888,13 @@ function hashGoBuildEnvironment(hash, goBinary, cwd) {
         }
     }
 }
-function resolveGoBuildEnvironment(goBinary, cwd) {
+function resolveGoBuildEnvironment(goBinary, cwd, env) {
     const values = new Map();
     if (goBinary !== undefined) {
         const result = spawnGoTool(goBinary, ["env", "-json", ...GO_BUILD_ENV_KEYS], {
             cwd,
             encoding: "utf8",
-            env: goBuildEnv(goBinary),
+            env: goBuildEnv(goBinary, undefined, env),
             maxBuffer: 1024 * 1024,
             windowsHide: true,
         });
@@ -1368,41 +1904,41 @@ function resolveGoBuildEnvironment(goBinary, cwd) {
                 for (const key of GO_BUILD_ENV_KEYS) {
                     const raw = parsed[key];
                     if (typeof raw === "string" && raw !== "") {
-                        values.set(key, normalizeGoBuildEnvValue(key, raw));
+                        values.set(key, normalizeGoBuildEnvValue(key, raw, env));
                     }
                 }
             }
             catch {
-                // Fall back to process.env below; a cache key is still better than
-                // failing before `go build` can produce the actionable error.
+                // Fall back to the effective env below; a cache key is still better
+                // than failing before `go build` can produce the actionable error.
             }
         }
     }
     for (const key of GO_BUILD_ENV_KEYS) {
         if (values.has(key))
             continue;
-        const value = process.env[key];
+        const value = env[key];
         if (value !== undefined && value !== "") {
-            values.set(key, normalizeGoBuildEnvValue(key, value));
+            values.set(key, normalizeGoBuildEnvValue(key, value, env));
         }
     }
     return values;
 }
-function normalizeGoBuildEnvValue(key, value) {
+function normalizeGoBuildEnvValue(key, value, env) {
     if (key === "GOROOT") {
         return resolveGoRootCacheIdentity(value);
     }
     if (GO_BUILD_COMMAND_ENV_KEYS.has(key)) {
-        return `${value}\0${resolveCommandCacheIdentity(value)}`;
+        return `${value}\0${resolveCommandCacheIdentity(value, env)}`;
     }
     return value;
 }
-function resolveCommandCacheIdentity(command) {
+function resolveCommandCacheIdentity(command, env) {
     const executable = firstCommandToken(command);
     if (executable === null) {
         return "command:empty";
     }
-    const resolved = resolveExecutableIdentityPath(executable);
+    const resolved = resolveExecutableIdentityPath(executable, env);
     if (!node_fs_1.default.existsSync(resolved)) {
         return `command:missing:${executable}`;
     }
@@ -1425,9 +1961,9 @@ function firstCommandToken(command) {
     }
     return trimmed.split(/\s+/)[0] ?? null;
 }
-function hashExternalGoBuildEnvironment(hash) {
+function hashExternalGoBuildEnvironment(hash, env) {
     for (const key of EXTERNAL_GO_BUILD_ENV_KEYS) {
-        const value = process.env[key];
+        const value = env[key];
         if (value !== undefined && value !== "") {
             hash.update(`${key}=${value}\n`);
         }
@@ -1571,7 +2107,9 @@ function collectPluginCacheEntries(root, now) {
         return entries;
     }
     for (const dirent of dirents) {
-        if (!dirent.isDirectory()) {
+        if (!dirent.isDirectory() ||
+            dirent.name.endsWith(".lock") ||
+            dirent.name.includes(".lock.")) {
             continue;
         }
         const dir = node_path_1.default.join(root, dirent.name);