ttsc 0.18.3 → 0.19.0

package/src/plugin/internal/buildSourcePlugin.ts

@@ -107,6 +107,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.
@@ -158,35 +166,47 @@ export interface ITtscSourceBuildCachePaths {
   goBuildRootSource: "ttsc-cache" | "TTSC_GO_CACHE_DIR" | "GOCACHE";
 }
 
-/** 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.
+ */
 export function buildSourcePlugin(opts: {
   source: string;
   pluginName: string;
   baseDir: string;
   cacheDir?: string;
   contributors?: readonly ITtscBuildContributor[];
+  env?: NodeJS.ProcessEnv;
   label?: string;
   overlayDirs?: readonly string[];
   quiet?: boolean;
   ttscVersion: string;
   tsgoVersion: string;
 }): string {
+  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 = path.join(paths.pluginRoot, key);
   const binaryName = process.platform === "win32" ? "plugin.exe" : "plugin";
   const binaryPath = path.join(cacheDir, binaryName);
@@ -208,6 +228,7 @@ export function buildSourcePlugin(opts: {
         contributors,
         dir,
         entry,
+        env,
         goBinary,
         key,
         label,
@@ -227,6 +248,7 @@ function compileSourcePlugin(opts: {
   contributors: readonly ITtscBuildContributor[];
   dir: string;
   entry: string;
+  env: NodeJS.ProcessEnv;
   goBinary: string;
   goBuildCacheRoot: string;
   key: string;
@@ -254,7 +276,11 @@ function compileSourcePlugin(opts: {
   );
   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,
@@ -264,7 +290,13 @@ 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(
@@ -274,6 +306,7 @@ function compileSourcePlugin(opts: {
       opts.pluginName,
       opts.goBinary,
       opts.goBuildCacheRoot,
+      opts.env,
     );
     const builtBinary = path.join(scratchDir, scratchBinaryName);
     publishBuiltBinary(builtBinary, opts.binaryPath);
@@ -289,17 +322,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:
  *
- * 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.
+ * - `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.
+ *
+ * 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: string,
@@ -317,33 +361,38 @@ function buildUnderPluginLock(
       touchCacheEntry(cacheDir);
       return binaryPath;
     }
+    let lease: PluginBuildLockLease | null;
     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.
-      fs.mkdirSync(lockDir);
-      writePluginBuildLockOwner(lockDir);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).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();
-      }
+      lease = acquirePluginBuildLock(lockDir);
+    } 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.
-      fs.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 {
@@ -354,13 +403,263 @@ function buildUnderPluginLock(
       }
       return build();
     } finally {
-      fs.rmSync(lockDir, { force: true, recursive: true });
+      releasePluginBuildLock(lockDir, lease);
+    }
+  }
+}
+
+/** Opaque identity of one observed lock generation. */
+export type PluginBuildLockFence = {
+  protocol: "legacy" | "v2";
+  generation: string;
+};
+
+/** Ownership token returned only to the process that acquired `current`. */
+export type PluginBuildLockLease = {
+  protocol: "v2";
+  generation: string;
+};
+
+/**
+ * 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.
+ */
+export function acquirePluginBuildLock(
+  lockDir: string,
+): PluginBuildLockLease | null {
+  // 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 = crypto.randomBytes(16).toString("hex");
+  const candidateDir = path.join(protocolDir, `candidate-${generation}`);
+  fs.mkdirSync(candidateDir);
+  try {
+    fs.writeFileSync(
+      path.join(candidateDir, PLUGIN_BUILD_LOCK_GENERATION_FILE),
+      `${generation}\n`,
+      { encoding: "utf8", flag: "wx" },
+    );
+    writePluginBuildLockOwner(candidateDir, generation);
+    try {
+      fs.renameSync(
+        candidateDir,
+        path.join(protocolDir, PLUGIN_BUILD_LOCK_CURRENT_DIR),
+      );
+    } catch (error) {
+      if (
+        isMissingPathError(error) ||
+        isRenameDestinationOccupied(
+          error,
+          path.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.
+    fs.rmSync(candidateDir, { force: true, recursive: true });
+  }
+}
+
+/** Retire a held generation during the holder's `finally`. */
+export function releasePluginBuildLock(
+  lockDir: string,
+  lease: PluginBuildLockLease,
+): boolean {
+  return retireV2PluginBuildLock(
+    pluginBuildLockProtocolDir(lockDir),
+    lease.generation,
+  );
+}
+
+/**
+ * Retire exactly the generation carried by an abandoned observation.
+ *
+ * Exported for deterministic multi-process tests.
+ */
+export function reclaimPluginBuildLock(
+  lockDir: string,
+  fence: PluginBuildLockFence,
+): boolean {
+  if (fence.protocol === "v2") {
+    return retireV2PluginBuildLock(
+      pluginBuildLockProtocolDir(lockDir),
+      fence.generation,
+    );
+  }
+  return retireLegacyPluginBuildLock(lockDir, fence.generation);
+}
+
+function pluginBuildLockProtocolDir(lockDir: string): string {
+  return `${lockDir}${PLUGIN_BUILD_LOCK_V2_SUFFIX}`;
+}
+
+function ensurePluginBuildLockProtocol(protocolDir: string): void {
+  if (isPluginBuildLockProtocolV2(protocolDir)) {
+    return;
+  }
+
+  const generation = crypto.randomBytes(16).toString("hex");
+  const candidateDir = `${protocolDir}.candidate-${generation}`;
+  fs.mkdirSync(candidateDir);
+  try {
+    fs.mkdirSync(path.join(candidateDir, PLUGIN_BUILD_LOCK_RETIRED_DIR));
+    fs.writeFileSync(
+      path.join(candidateDir, PLUGIN_BUILD_LOCK_PROTOCOL_FILE),
+      PLUGIN_BUILD_LOCK_PROTOCOL,
+      { encoding: "utf8", flag: "wx" },
+    );
+    try {
+      fs.renameSync(candidateDir, protocolDir);
+    } catch (error) {
+      if (
+        isRenameDestinationOccupied(error, protocolDir) &&
+        isPluginBuildLockProtocolV2(protocolDir)
+      ) {
+        return;
+      }
+      throw error;
+    }
+  } finally {
+    fs.rmSync(candidateDir, { force: true, recursive: true });
+  }
+}
+
+function isPluginBuildLockProtocolV2(lockDir: string): boolean {
+  try {
+    return (
+      fs.readFileSync(
+        path.join(lockDir, PLUGIN_BUILD_LOCK_PROTOCOL_FILE),
+        "utf8",
+      ) === PLUGIN_BUILD_LOCK_PROTOCOL
+    );
+  } catch {
+    return false;
+  }
+}
+
+function retireV2PluginBuildLock(lockDir: string, generation: string): boolean {
+  if (!isPluginBuildLockGeneration(generation)) return false;
+  const retiredDir = path.join(lockDir, PLUGIN_BUILD_LOCK_RETIRED_DIR);
+  try {
+    fs.mkdirSync(retiredDir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      if (isMissingPathError(error)) return false;
+      throw error;
+    }
+  }
+
+  const destination = path.join(retiredDir, generation);
+  try {
+    fs.renameSync(
+      path.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: string,
+  generation: string,
+): boolean {
+  if (!isPluginBuildLockGeneration(generation)) return false;
+  const captured = readLegacyPluginBuildLockFence(
+    path.join(lockDir, PLUGIN_BUILD_LOCK_LEGACY_FENCE_DIR),
+  );
+  if (captured?.fence.generation !== generation) {
+    return false;
+  }
+  const destination = `${lockDir}.retired-${generation}`;
+  try {
+    fs.renameSync(lockDir, destination);
+    return true;
+  } catch (error) {
+    if (
+      isMissingPathError(error) ||
+      isRenameDestinationOccupied(error, destination)
+    ) {
+      return false;
     }
+    throw error;
+  }
+}
+
+function isMissingPathError(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+
+function isRenameDestinationOccupied(
+  error: unknown,
+  destination: string,
+): boolean {
+  const code = (error as NodeJS.ErrnoException).code;
+  if (code === "EEXIST" || code === "ENOTEMPTY") {
+    return true;
   }
+  return (code === "EACCES" || code === "EPERM") && fs.existsSync(destination);
 }
 
-/** Poll for the locked builder to publish its binary, up to `timeoutMs`. */
-function waitForPluginBinary(opts: {
+/**
+ * Outcome of one waiting session on another process's plugin build lock.
+ *
+ * - `published`: the binary exists and can be reused.
+ * - `released`: the observed generation no longer exists and no binary appeared —
+ *   the holder freed the key normally, so the caller should retry ordinary
+ *   acquisition without reporting or removing anything.
+ * - `abandoned`: the lock still exists but is provably stale (dead owner, old
+ *   legacy lock) or the wait budget expired; the caller may report and retire
+ *   precisely the attached generation.
+ *
+ * Exported for unit tests.
+ */
+export type PluginBinaryWaitResult =
+  | { outcome: "published" }
+  | { outcome: "released" }
+  | {
+      outcome: "abandoned";
+      reason: string;
+      fence: PluginBuildLockFence;
+    };
+
+/**
+ * Poll for the locked builder to publish its binary, up to `timeoutMs`.
+ *
+ * Exported for unit tests.
+ */
+export function waitForPluginBinary(opts: {
   binaryPath: string;
   lockDir: string;
   lockInfo: {
@@ -369,25 +668,36 @@ function waitForPluginBinary(opts: {
     quiet: boolean;
   };
   timeoutMs: number;
-}): { published: boolean; reason?: string } {
+}): PluginBinaryWaitResult {
   const startedAt = Date.now();
   let nextStatusAt = startedAt + PLUGIN_BUILD_LOCK_STATUS_MS;
   for (;;) {
     if (fs.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 fs.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) {
@@ -396,7 +706,7 @@ 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;
     }
@@ -404,66 +714,295 @@ function waitForPluginBinary(opts: {
   }
 }
 
-function writePluginBuildLockOwner(lockDir: string): void {
-  try {
-    fs.writeFileSync(
-      path.join(lockDir, PLUGIN_BUILD_LOCK_OWNER_FILE),
-      `${JSON.stringify(
-        {
-          hostname: os.hostname(),
-          pid: process.pid,
-          startedAt: new Date().toISOString(),
-        },
-        null,
-        2,
-      )}\n`,
-      "utf8",
+function writePluginBuildLockOwner(
+  generationDir: string,
+  generation: string,
+): void {
+  fs.writeFileSync(
+    path.join(generationDir, PLUGIN_BUILD_LOCK_OWNER_FILE),
+    `${JSON.stringify(
+      {
+        generation,
+        hostname: os.hostname(),
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+}
+
+/**
+ * One observation of a plugin build lock directory's state.
+ *
+ * - `active`: the lock exists and its owner is alive (or cannot be disproven:
+ *   another host, no metadata but young). Keep waiting.
+ * - `abandoned`: the lock still exists and the evidence says nobody will ever
+ *   release it — a same-host owner that is no longer running, or an old
+ *   metadata-less legacy lock. Retiring its fenced generation is justified.
+ * - `released`: the observed generation no longer exists. In v2 the persistent
+ *   coordination root remains while `current` is absent. This is a routine
+ *   handoff, never an infinitely old abandoned lock (issue #421).
+ *
+ * Exported for unit tests.
+ */
+export type PluginBuildLockObservation =
+  | {
+      state: "active";
+      owner: string;
+      fence: PluginBuildLockFence;
+    }
+  | {
+      state: "abandoned";
+      reason: string;
+      fence: PluginBuildLockFence;
+    }
+  | { state: "released" };
+
+/**
+ * Classify the current state of a plugin build lock directory.
+ *
+ * Exported for unit tests.
+ */
+export function inspectPluginBuildLock(
+  lockDir: string,
+  now: number,
+): PluginBuildLockObservation {
+  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.
+  }
+}
+
+function inspectV2PluginBuildLock(
+  lockDir: string,
+  now: number,
+): PluginBuildLockObservation {
+  const generationDir = path.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}`,
     );
-  } catch {
-    // Best-effort metadata: the mkdir lock still serializes the build.
   }
+  const fence: PluginBuildLockFence = { 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,
+  };
+}
+
+interface LegacyPluginBuildLockFence {
+  fence: PluginBuildLockFence;
+  legacyMtimeMs: number;
 }
 
-function inspectPluginBuildLock(
+function inspectLegacyPluginBuildLock(
   lockDir: string,
   now: number,
-): {
-  abandoned: boolean;
-  owner: string;
-  reason?: string;
-} {
+  legacy: LegacyPluginBuildLockFence,
+): PluginBuildLockObservation {
   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: string,
+): LegacyPluginBuildLockFence | null {
+  if (isPluginBuildLockProtocolV2(lockDir)) {
+    return null;
+  }
+
+  let legacyMtimeMs: number;
+  try {
+    legacyMtimeMs = fs.statSync(lockDir).mtimeMs;
+  } catch (error) {
+    if (isMissingPathError(error)) return null;
+    throw error;
+  }
+
+  const fenceDir = path.join(lockDir, PLUGIN_BUILD_LOCK_LEGACY_FENCE_DIR);
+  let captured = readLegacyPluginBuildLockFence(fenceDir);
+  if (captured === null) {
+    const generation = crypto.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 {
+      fs.mkdirSync(candidateDir);
+      fs.writeFileSync(
+        path.join(candidateDir, PLUGIN_BUILD_LOCK_LEGACY_FENCE_RECORD),
+        `${JSON.stringify({ generation, legacyMtimeMs })}\n`,
+        "utf8",
+      );
+      try {
+        fs.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 {
+      fs.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: string,
+): LegacyPluginBuildLockFence | null {
+  try {
+    const parsed = JSON.parse(
+      fs.readFileSync(
+        path.join(fenceDir, PLUGIN_BUILD_LOCK_LEGACY_FENCE_RECORD),
+        "utf8",
+      ),
+    ) as Record<string, unknown>;
+    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: string): string | null {
+  try {
+    const generation = fs
+      .readFileSync(
+        path.join(generationDir, PLUGIN_BUILD_LOCK_GENERATION_FILE),
+        "utf8",
+      )
+      .trim();
+    return isPluginBuildLockGeneration(generation) ? generation : null;
+  } catch {
+    return null;
+  }
+}
+
+function isPluginBuildLockGeneration(value: unknown): value is string {
+  return typeof value === "string" && /^[0-9a-f]{32}$/.test(value);
+}
+
 function readPluginBuildLockOwner(
   lockDir: string,
 ): { hostname: string; pid: number; startedAt?: string } | null {
@@ -490,11 +1029,33 @@ function readPluginBuildLockOwner(
   }
 }
 
-function pluginBuildLockAgeMs(lockDir: string, now: number): number {
+/**
+ * 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: string, now: number): number | null {
   try {
     return Math.max(0, now - fs.statSync(lockDir).mtimeMs);
-  } catch {
-    return Number.POSITIVE_INFINITY;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    return code === "ENOENT" || code === "ENOTDIR" ? null : 0;
+  }
+}
+
+function pluginBuildLockPathExists(lockDir: string): boolean {
+  try {
+    fs.statSync(lockDir);
+    return true;
+  } catch (error) {
+    if (isMissingPathError(error)) return false;
+    throw error;
   }
 }
 
@@ -547,17 +1108,29 @@ function reportPluginLockSteal(
     pluginName: string;
     quiet: boolean;
   },
-  reason: string | undefined,
+  reason: string,
 ): void {
   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`,
   );
 }
 
-function formatDuration(ms: number): string {
+/**
+ * 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.
+ */
+export function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms)) {
+    return "an unknown time";
+  }
   if (ms < 1_000) {
     return `${Math.max(0, Math.round(ms))}ms`;
   }
@@ -808,8 +1381,9 @@ function writeGoWork(
   useDirs: readonly string[],
   goBinary: string,
   pluginName: string,
+  env: NodeJS.ProcessEnv,
 ): void {
-  const goModReader = createGoModReader(goBinary, pluginName);
+  const goModReader = createGoModReader(goBinary, pluginName, env);
   validateSourceReplacements(scratchDir, useDirs, goModReader, pluginName);
   const sourceInfo = goModReader.read(scratchDir);
   const effectiveUseDirs =
@@ -821,7 +1395,7 @@ function writeGoWork(
       : useDirs;
   const useLines = ["\t."];
   for (const dir of effectiveUseDirs) {
-    useLines.push(`\t${dir.replace(/\\/g, "/")}`);
+    useLines.push(`\t${formatGoWorkPath(dir)}`);
   }
   const replaceLines = sourceBuildWorkspaceReplacements(
     effectiveUseDirs,
@@ -873,10 +1447,136 @@ function sourceBuildWorkspaceReplacements(
     return [];
   }
   return [
-    `replace ${TTSC_GO_MODULE_PATH} v0.0.0 => ${ttscRoot.replace(/\\/g, "/")}`,
+    `replace ${TTSC_GO_MODULE_PATH} v0.0.0 => ${formatGoWorkPath(ttscRoot)}`,
   ];
 }
 
+/**
+ * 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.
+ */
+export function formatGoWorkPath(p: string): string {
+  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.
+ */
+export function autoQuoteGoModToken(token: string): string {
+  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: string): boolean {
+  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: string): string {
+  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: string): string {
+  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: string): boolean {
+  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: string): boolean {
+  return ch === " " || GO_PRINTABLE_RE.test(ch);
+}
+
 interface GoModReplacement {
   readonly modulePath: string;
 }
@@ -910,7 +1610,11 @@ interface GoModJson {
   }[];
 }
 
-function createGoModReader(goBinary: string, pluginName: string): GoModReader {
+function createGoModReader(
+  goBinary: string,
+  pluginName: string,
+  env: NodeJS.ProcessEnv,
+): GoModReader {
   const cache = new Map<string, GoModInfo>();
   return {
     read(dir) {
@@ -919,7 +1623,7 @@ function createGoModReader(goBinary: string, pluginName: string): GoModReader {
       if (cached !== undefined) {
         return cached;
       }
-      const info = readGoModInfo(resolved, goBinary, pluginName);
+      const info = readGoModInfo(resolved, goBinary, pluginName, env);
       cache.set(resolved, info);
       return info;
     },
@@ -930,6 +1634,7 @@ function readGoModInfo(
   dir: string,
   goBinary: string,
   pluginName: string,
+  env: NodeJS.ProcessEnv,
 ): GoModInfo {
   if (!fs.existsSync(path.join(dir, "go.mod"))) {
     return emptyGoModInfo();
@@ -938,7 +1643,7 @@ function readGoModInfo(
   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,
   });
@@ -1023,12 +1728,13 @@ function runGoBuild(
   pluginName: string,
   goBinary: string,
   goBuildCacheRoot: string,
+  env: NodeJS.ProcessEnv,
 ): void {
   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,
   });
@@ -1078,8 +1784,9 @@ function shouldSpawnGoToolThroughShell(goBinary: string): boolean {
 function goBuildEnv(
   goBinary: string,
   goBuildCacheRoot?: string,
+  effectiveEnv: NodeJS.ProcessEnv = process.env,
 ): NodeJS.ProcessEnv {
-  const env = { ...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
@@ -1188,9 +1895,10 @@ function walkForGoMod(dir: string, out: string[]): void {
 export function resolvePluginCacheRoot(
   projectRoot: string,
   cacheDir?: string,
+  env: NodeJS.ProcessEnv = process.env,
 ): string {
-  const paths = resolveSourceBuildCachePaths(projectRoot, cacheDir);
-  maybePrunePluginCache(paths, cacheDir);
+  const paths = resolveSourceBuildCachePaths(projectRoot, cacheDir, env);
+  maybePrunePluginCache(paths, cacheDir, env);
   return paths.pluginRoot;
 }
 
@@ -1355,12 +2063,15 @@ function resolveGoBuildCacheRoot(
 
 function maybePrunePluginCache(
   paths: ITtscSourceBuildCachePaths,
-  cacheDir?: string,
+  cacheDir: string | undefined,
+  env: NodeJS.ProcessEnv = process.env,
 ): void {
   // 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);
   }
 }
@@ -1444,8 +2155,8 @@ export function isPathWithin(child: string, parent: string): boolean {
   );
 }
 
-function resolveGoCompiler(): string {
-  const explicit = process.env.TTSC_GO_BINARY;
+function resolveGoCompiler(env: NodeJS.ProcessEnv = process.env): string {
+  const explicit = env.TTSC_GO_BINARY;
   if (explicit && explicit.length > 0) return explicit;
 
   try {
@@ -1484,7 +2195,7 @@ function resolveGoCompiler(): string {
   if (fs.existsSync(local)) return local;
 
   const homeSdk = path.join(
-    process.env.HOME ?? "",
+    env.HOME ?? "",
     "go-sdk",
     "go",
     "bin",
@@ -1510,21 +2221,23 @@ export function computeCacheKey(inputs: {
   contributors?: readonly ITtscBuildContributor[];
   dir: string;
   entry: string;
+  env?: NodeJS.ProcessEnv;
   goBinary?: string;
   overlayDirs?: readonly string[];
   ttscVersion: string;
   tsgoVersion: string;
 }): string {
+  const env = inputs.env ?? process.env;
   const hash = crypto.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);
@@ -1619,8 +2332,11 @@ function isHashableFile(name: string): boolean {
 // cwd/custom env (the spawn passes neither), so cwd is not part of the key.
 const goCompilerIdentityCache = new Map<string, string>();
 
-function resolveGoCompilerIdentity(goBinary: string): string {
-  const resolved = resolveExecutableIdentityPath(goBinary);
+function resolveGoCompilerIdentity(
+  goBinary: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const resolved = resolveExecutableIdentityPath(goBinary, env);
   const memoKey = goCompilerIdentityMemoKey(goBinary, resolved);
   if (memoKey !== null) {
     const cached = goCompilerIdentityCache.get(memoKey);
@@ -1666,14 +2382,17 @@ function computeGoCompilerIdentity(goBinary: string, resolved: string): string {
   return `sha256:${binaryHash}:${versionText}`;
 }
 
-function resolveExecutableIdentityPath(binary: string): string {
+function resolveExecutableIdentityPath(
+  binary: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
   if (path.isAbsolute(binary)) {
     return resolveRealPath(binary);
   }
   if (binary.includes(path.sep)) {
     return resolveRealPath(path.resolve(binary));
   }
-  for (const dir of readPathEnvironment().split(path.delimiter)) {
+  for (const dir of readPathEnvironment(env).split(path.delimiter)) {
     if (dir.length === 0) continue;
     const candidate = path.join(dir, binary);
     if (fs.existsSync(candidate)) {
@@ -1684,7 +2403,7 @@ function resolveExecutableIdentityPath(binary: string): string {
       // 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 (fs.existsSync(executable)) {
           return resolveRealPath(executable);
@@ -1695,8 +2414,10 @@ function resolveExecutableIdentityPath(binary: string): string {
   return binary;
 }
 
-function windowsExecutableExtensions(): readonly string[] {
-  const pathext = process.env.PATHEXT;
+function windowsExecutableExtensions(
+  env: NodeJS.ProcessEnv = process.env,
+): readonly string[] {
+  const pathext = env.PATHEXT;
   const raw = pathext && pathext.length > 0 ? pathext : ".COM;.EXE;.BAT;.CMD";
   return raw
     .split(";")
@@ -1704,8 +2425,8 @@ function windowsExecutableExtensions(): readonly string[] {
     .filter((ext) => ext.length > 0);
 }
 
-function readPathEnvironment(): string {
-  return process.env.PATH ?? process.env.Path ?? "";
+function readPathEnvironment(env: NodeJS.ProcessEnv = process.env): string {
+  return env.PATH ?? env.Path ?? "";
 }
 
 function resolveRealPath(location: string): string {
@@ -1726,8 +2447,9 @@ function hashGoBuildEnvironment(
   hash: crypto.Hash,
   goBinary: string | undefined,
   cwd: string,
+  env: NodeJS.ProcessEnv,
 ): void {
-  const values = resolveGoBuildEnvironment(goBinary, cwd);
+  const values = resolveGoBuildEnvironment(goBinary, cwd, env);
   for (const key of GO_BUILD_ENV_KEYS) {
     const value = values.get(key);
     if (value !== undefined && value !== "") {
@@ -1739,6 +2461,7 @@ function hashGoBuildEnvironment(
 function resolveGoBuildEnvironment(
   goBinary: string | undefined,
   cwd: string,
+  env: NodeJS.ProcessEnv,
 ): Map<string, string> {
   const values = new Map<string, string>();
   if (goBinary !== undefined) {
@@ -1748,7 +2471,7 @@ function resolveGoBuildEnvironment(
       {
         cwd,
         encoding: "utf8",
-        env: goBuildEnv(goBinary),
+        env: goBuildEnv(goBinary, undefined, env),
         maxBuffer: 1024 * 1024,
         windowsHide: true,
       },
@@ -1759,41 +2482,48 @@ function resolveGoBuildEnvironment(
         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: string, value: string): string {
+function normalizeGoBuildEnvValue(
+  key: string,
+  value: string,
+  env: NodeJS.ProcessEnv,
+): string {
   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: string): string {
+function resolveCommandCacheIdentity(
+  command: string,
+  env: NodeJS.ProcessEnv,
+): string {
   const executable = firstCommandToken(command);
   if (executable === null) {
     return "command:empty";
   }
-  const resolved = resolveExecutableIdentityPath(executable);
+  const resolved = resolveExecutableIdentityPath(executable, env);
   if (!fs.existsSync(resolved)) {
     return `command:missing:${executable}`;
   }
@@ -1817,9 +2547,12 @@ function firstCommandToken(command: string): string | null {
   return trimmed.split(/\s+/)[0] ?? null;
 }
 
-function hashExternalGoBuildEnvironment(hash: crypto.Hash): void {
+function hashExternalGoBuildEnvironment(
+  hash: crypto.Hash,
+  env: NodeJS.ProcessEnv,
+): void {
   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`);
     }
@@ -1977,7 +2710,11 @@ function collectPluginCacheEntries(
     return entries;
   }
   for (const dirent of dirents) {
-    if (!dirent.isDirectory()) {
+    if (
+      !dirent.isDirectory() ||
+      dirent.name.endsWith(".lock") ||
+      dirent.name.includes(".lock.")
+    ) {
       continue;
     }
     const dir = path.join(root, dirent.name);