ttsc 0.26.2 → 0.28.0

package/lib/plugin/internal/buildSourcePlugin.js

@@ -14,12 +14,16 @@ exports.formatGoWorkPath = formatGoWorkPath;
 exports.autoQuoteGoModToken = autoQuoteGoModToken;
 exports.spawnGoTool = spawnGoTool;
 exports.windowsGoCommandArgs = windowsGoCommandArgs;
+exports.ensureExecutableGoToolchain = ensureExecutableGoToolchain;
 exports.resolvePluginCacheRoot = resolvePluginCacheRoot;
 exports.resolveSourceBuildCachePaths = resolveSourceBuildCachePaths;
 exports.resolveCleanTargets = resolveCleanTargets;
 exports.legacyGlobalCacheTargets = legacyGlobalCacheTargets;
 exports.isPathWithin = isPathWithin;
 exports.computeCacheKey = computeCacheKey;
+exports.prunePluginCacheRoot = prunePluginCacheRoot;
+exports.pruneGoBuildCacheRoot = pruneGoBuildCacheRoot;
+exports.withGoBuildCacheLease = withGoBuildCacheLease;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -27,8 +31,10 @@ const node_module_1 = require("node:module");
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_url_1 = require("node:url");
+const node_worker_threads_1 = require("node:worker_threads");
 const captureProcessOutput_1 = require("../../compiler/internal/captureProcessOutput");
 const paths_1 = require("../../compiler/internal/paths");
+const createCanonicalTempDirectory_1 = require("../../internal/createCanonicalTempDirectory");
 const GO_MOD_SEARCH_MAX_DEPTH = 3;
 const TTSC_GO_MODULE_PATH = "github.com/samchon/ttsc/packages/ttsc";
 const TSGO_GO_MODULE_PATH = "github.com/microsoft/typescript-go";
@@ -161,6 +167,29 @@ 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;
+// Go's own object-cache trim is age-based and has no size ceiling. The default
+// ttsc-owned cache therefore keeps up to 8 GiB and trims oldest objects toward
+// 6 GiB. The newest target-sized set used within an hour remains protected so
+// crossing the ceiling cannot immediately force another cold build.
+const GO_BUILD_CACHE_GC_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const GO_BUILD_CACHE_MAX_BYTES = 8 * 1024 * 1024 * 1024;
+const GO_BUILD_CACHE_TARGET_BYTES = 6 * 1024 * 1024 * 1024;
+const GO_BUILD_CACHE_PROTECTED_AGE_MS = 60 * 60 * 1000;
+const GO_BUILD_CACHE_GC_MARKER_FILE = ".ttsc-gc";
+const GO_BUILD_CACHE_LEASE_DIR = ".ttsc-build-leases";
+const GO_BUILD_CACHE_MAINTENANCE_DIR = ".ttsc-maintenance";
+const GO_BUILD_CACHE_COORDINATION_STALE_MS = 60 * 60 * 1000;
+const GO_BUILD_CACHE_MAINTENANCE_STALE_MS = 60 * 1000;
+const GO_BUILD_CACHE_COORDINATION_CLOCK_SKEW_MS = 5 * 60 * 1000;
+const GO_BUILD_CACHE_COORDINATION_HEARTBEAT_MS = 5_000;
+const GO_BUILD_CACHE_COORDINATION_POLL_MS = 25;
+// Go amortizes cache-hit mtime writes over one hour. An object used inside
+// ttsc's one-hour protection window may therefore still carry an mtime almost
+// one additional hour old.
+const GO_BUILD_CACHE_ACCESS_MTIME_GRANULARITY_MS = 60 * 60 * 1000;
+const DEFAULT_SOURCE_BUILD_FILESYSTEM = Object.freeze({
+    readFile: (location) => node_fs_1.default.readFileSync(location),
+});
 /**
  * Build one Go source plugin into a cached executable.
  *
@@ -176,21 +205,30 @@ function buildSourcePlugin(opts) {
     const { dir, entry, source } = resolveSourceBuildTarget(opts);
     const overlayDirs = [...(opts.overlayDirs ?? findTtscOverlayDirs())].sort();
     const contributors = opts.contributors ?? [];
-    const goBinary = resolveGoToolForBuild(resolveGoCompiler(env), env, dir);
-    ensureExecutableGoToolchain(goBinary);
+    const compiler = resolveGoCompiler(env);
+    const goBinary = resolveGoToolForBuild(compiler.binary, env, dir);
+    ensureExecutableGoToolchain(goBinary, compiler.bundled);
     const key = computeCacheKey({
         contributors,
         dir,
         entry,
         env,
+        filesystem: opts.filesystem,
         goBinary,
         overlayDirs,
         ttscVersion: opts.ttscVersion,
         tsgoVersion: opts.tsgoVersion,
     });
     const paths = resolveSourceBuildCachePaths(opts.baseDir, opts.cacheDir, env);
-    maybePrunePluginCache(paths, opts.cacheDir, env);
-    const cacheDir = node_path_1.default.join(paths.pluginRoot, key);
+    const managePluginCache = !opts.cacheDir && !env.TTSC_CACHE_DIR;
+    const manageGoBuildCache = shouldManageSourceBuildCaches(paths, opts.cacheDir, env);
+    const pluginRoot = managePluginCache
+        ? canonicalPluginCacheRoot(paths.pluginRoot)
+        : paths.pluginRoot;
+    maybePruneSourceBuildCaches({ ...paths, pluginRoot }, opts.cacheDir, env);
+    const cacheDir = managePluginCache
+        ? canonicalPluginCacheEntry(pluginRoot, key)
+        : node_path_1.default.join(pluginRoot, key);
     const binaryName = process.platform === "win32" ? "plugin.exe" : "plugin";
     const binaryPath = node_path_1.default.join(cacheDir, binaryName);
     if (node_fs_1.default.existsSync(binaryPath)) {
@@ -200,7 +238,7 @@ function buildSourcePlugin(opts) {
     node_fs_1.default.mkdirSync(cacheDir, { recursive: true });
     const label = opts.label ?? "source plugin";
     const quiet = opts.quiet === true;
-    return buildUnderPluginLock(cacheDir, binaryPath, { label, pluginName: opts.pluginName, quiet }, () => compileSourcePlugin({
+    const built = buildUnderPluginLock(cacheDir, binaryPath, { label, pluginName: opts.pluginName, quiet }, () => compileSourcePlugin({
         binaryPath,
         cacheDir,
         contributors,
@@ -208,14 +246,26 @@ function buildSourcePlugin(opts) {
         entry,
         env,
         goBinary,
+        normalizeGoToolPermissions: compiler.bundled,
         key,
         label,
         goBuildCacheRoot: paths.goBuildRoot,
+        manageGoBuildCache,
         overlayDirs,
         pluginName: opts.pluginName,
         quiet,
         source,
     }));
+    if (managePluginCache) {
+        // The pre-build daily pass cannot account for the binary this cold build
+        // just published. Enforce the size policy after publication, once this
+        // process has released its per-key build lock.
+        prunePluginCacheRoot(pluginRoot, {
+            force: true,
+            protectedEntries: [cacheDir],
+        });
+    }
+    return built;
 }
 /** Run the actual `go build` and publish the binary; assumes the lock is held. */
 function compileSourcePlugin(opts) {
@@ -229,7 +279,7 @@ function compileSourcePlugin(opts) {
             `(this runs once per cache key and can take several minutes on a cold Go cache) ` +
             `See https://ttsc.dev/docs/ttsc/compile#plugin-cache to persist it across builds.\n`);
     }
-    const scratchDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), `ttsc-plugin-${opts.key}-`));
+    const scratchDir = (0, createCanonicalTempDirectory_1.createCanonicalTempDirectory)(`ttsc-plugin-${opts.key}-`);
     try {
         materializeScratchDir(opts.dir, scratchDir);
         const goModReader = createGoModReader(opts.goBinary, opts.pluginName, opts.env);
@@ -244,7 +294,22 @@ function compileSourcePlugin(opts) {
         }
         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, opts.env);
+        let attemptedGoBuildCacheRoot;
+        try {
+            withGoBuildCacheLease(opts.goBuildCacheRoot, opts.manageGoBuildCache, (goBuildCacheRoot) => {
+                attemptedGoBuildCacheRoot = goBuildCacheRoot;
+                runGoBuild(scratchDir, opts.entry, scratchBinaryName, opts.pluginName, opts.goBinary, goBuildCacheRoot, opts.env, opts.normalizeGoToolPermissions);
+            });
+        }
+        finally {
+            if (opts.manageGoBuildCache && attemptedGoBuildCacheRoot !== undefined) {
+                // The daily pre-build pass cannot see objects the build is about to
+                // add, including objects left behind by a failed compile. Enforce the
+                // size policy after every actual cold-build attempt so churn cannot
+                // grow the cache unchecked behind a fresh daily marker.
+                pruneGoBuildCacheRoot(attemptedGoBuildCacheRoot, { force: true });
+            }
+        }
         const builtBinary = node_path_1.default.join(scratchDir, scratchBinaryName);
         publishBuiltBinary(builtBinary, opts.binaryPath);
         touchCacheEntry(opts.cacheDir);
@@ -431,6 +496,9 @@ function ensurePluginBuildLockProtocol(protocolDir) {
 }
 function isPluginBuildLockProtocolV2(lockDir) {
     try {
+        const stats = node_fs_1.default.lstatSync(lockDir);
+        if (!stats.isDirectory() || stats.isSymbolicLink())
+            return false;
         return (node_fs_1.default.readFileSync(node_path_1.default.join(lockDir, PLUGIN_BUILD_LOCK_PROTOCOL_FILE), "utf8") === PLUGIN_BUILD_LOCK_PROTOCOL);
     }
     catch {
@@ -794,7 +862,10 @@ function pluginBuildLockAgeMs(lockDir, now) {
 }
 function pluginBuildLockPathExists(lockDir) {
     try {
-        node_fs_1.default.statSync(lockDir);
+        const stats = node_fs_1.default.lstatSync(lockDir);
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            throw new Error(`ttsc: unsafe plugin build lock path: ${lockDir}`);
+        }
         return true;
     }
     catch (error) {
@@ -1293,8 +1364,8 @@ function isTtscManagedModulePath(modulePath) {
         modulePath === TSGO_GO_MODULE_PATH ||
         modulePath.startsWith("github.com/microsoft/typescript-go/shim/"));
 }
-function runGoBuild(cwd, entry, binaryName, pluginName, goBinary, goBuildCacheRoot, env) {
-    ensureExecutableGoToolchain(goBinary);
+function runGoBuild(cwd, entry, binaryName, pluginName, goBinary, goBuildCacheRoot, env, normalizeGoToolPermissions) {
+    ensureExecutableGoToolchain(goBinary, normalizeGoToolPermissions);
     const result = spawnGoTool(goBinary, ["build", "-o", binaryName, entry], {
         cwd,
         encoding: "utf8",
@@ -1428,30 +1499,42 @@ function inferGoRoot(goBinary) {
     const goRoot = node_path_1.default.dirname(binDir);
     return node_fs_1.default.existsSync(node_path_1.default.join(goRoot, "src", "runtime")) ? goRoot : null;
 }
-function ensureExecutableGoToolchain(goBinary) {
+function ensureExecutableGoToolchain(goBinary, normalizeBundledPermissions) {
     if (process.platform === "win32")
         return;
     if (!node_path_1.default.isAbsolute(goBinary) || !node_fs_1.default.existsSync(goBinary))
         return;
     try {
-        node_fs_1.default.chmodSync(goBinary, 0o755);
+        ensureExecutableFile(goBinary, normalizeBundledPermissions);
         const goRoot = inferGoRoot(goBinary);
         if (!goRoot)
             return;
         const gofmt = node_path_1.default.join(node_path_1.default.dirname(goBinary), "gofmt");
-        if (node_fs_1.default.existsSync(gofmt))
-            node_fs_1.default.chmodSync(gofmt, 0o755);
+        if (node_fs_1.default.existsSync(gofmt)) {
+            ensureExecutableFile(gofmt, normalizeBundledPermissions);
+        }
         const toolDir = node_path_1.default.join(goRoot, "pkg", "tool");
         if (!node_fs_1.default.existsSync(toolDir))
             return;
         for (const file of walkToolFiles(toolDir)) {
-            node_fs_1.default.chmodSync(file, 0o755);
+            ensureExecutableFile(file, normalizeBundledPermissions);
         }
     }
     catch {
         // Let the subsequent go build spawn fail with the real OS error.
     }
 }
+/** Repair tool execution without widening an explicitly selected toolchain. */
+function ensureExecutableFile(file, normalizeBundledPermissions) {
+    const mode = node_fs_1.default.statSync(file).mode & 0o7777;
+    if (normalizeBundledPermissions) {
+        if (mode !== 0o755)
+            node_fs_1.default.chmodSync(file, 0o755);
+    }
+    else if ((mode & 0o111) === 0) {
+        node_fs_1.default.chmodSync(file, mode | 0o100);
+    }
+}
 function walkToolFiles(dir) {
     const out = [];
     let entries;
@@ -1519,16 +1602,16 @@ function walkForGoMod(dir, out) {
  */
 function resolvePluginCacheRoot(projectRoot, cacheDir, env = process.env) {
     const paths = resolveSourceBuildCachePaths(projectRoot, cacheDir, env);
-    maybePrunePluginCache(paths, cacheDir, env);
+    maybePruneSourceBuildCaches(paths, cacheDir, env);
     return paths.pluginRoot;
 }
 /**
  * Resolve all source-plugin build cache directories for one invocation.
  *
  * `pluginRoot` stores compiled plugin binaries; `goBuildRoot` is the Go object
- * cache passed as `GOCACHE` while ttsc builds those binaries. Both live under a
- * single `root`, so persisting one directory covers the whole source-build
- * cache without depending on ttsc internals.
+ * cache passed as `GOCACHE` while ttsc builds those binaries. The default Go
+ * cache lives under `root`; an explicit `TTSC_GO_CACHE_DIR` or `GOCACHE` keeps
+ * its independently resolved location and ownership policy.
  */
 function resolveSourceBuildCachePaths(projectRoot, cacheDir, env = process.env) {
     const root = resolveSourceBuildCacheRoot(projectRoot, cacheDir, env);
@@ -1655,7 +1738,7 @@ function resolveGoBuildCacheRoot(root, projectRoot, env) {
         source: "ttsc-cache",
     };
 }
-function maybePrunePluginCache(paths, cacheDir, env = process.env) {
+function maybePruneSourceBuildCaches(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. `env` is the effective instance
@@ -1663,16 +1746,23 @@ function maybePrunePluginCache(paths, cacheDir, env = process.env) {
     // `context.env` is honored without leaning on the shared `process.env`.
     if (!cacheDir && !env.TTSC_CACHE_DIR) {
         prunePluginCacheRoot(paths.pluginRoot);
+        if (paths.goBuildRootSource === "ttsc-cache") {
+            pruneGoBuildCacheRoot(paths.goBuildRoot);
+        }
     }
 }
+/** Report whether this invocation owns and automatically maintains both caches. */
+function shouldManageSourceBuildCaches(paths, cacheDir, env) {
+    return (!cacheDir && !env.TTSC_CACHE_DIR && paths.goBuildRootSource === "ttsc-cache");
+}
 /**
  * Return every directory `ttsc clean` should remove for `projectRoot`.
  *
- * Covers the resolved cache root (which holds `plugins/` and, when ttsc-owned,
- * `go-build/`), a ttsc-owned Go build cache that lives OUTSIDE that root
- * (`TTSC_GO_CACHE_DIR`), and the two legacy project-local caches. A
- * user-provided `GOCACHE` is never removed. Pure over `env`, so the CLI passes
- * `process.env` and a programmatic caller can pass an injected environment.
+ * Covers the resolved plugin-binary root, a safely named nested `go-build/`, a
+ * ttsc-owned Go build cache that lives OUTSIDE that root (`TTSC_GO_CACHE_DIR`),
+ * and the two legacy project-local caches. A user-provided `GOCACHE` is never
+ * removed. Pure over `env`, so the CLI passes `process.env` and a programmatic
+ * caller can pass an injected environment.
  */
 function resolveCleanTargets(projectRoot, cacheDir, env = process.env) {
     const paths = resolveSourceBuildCachePaths(projectRoot, cacheDir, env);
@@ -1737,24 +1827,29 @@ function isPathWithin(child, parent) {
 }
 function resolveGoCompiler(env = process.env) {
     const explicit = env.TTSC_GO_BINARY;
-    if (explicit && explicit.length > 0)
-        return explicit;
+    if (explicit && explicit.length > 0) {
+        return { binary: explicit, bundled: false };
+    }
     try {
-        return (0, node_module_1.createRequire)(__filename).resolve(`@ttsc/${process.platform}-${process.arch}/bin/go/bin/${process.platform === "win32" ? "go.exe" : "go"}`);
+        return {
+            binary: (0, node_module_1.createRequire)(__filename).resolve(`@ttsc/${process.platform}-${process.arch}/bin/go/bin/${process.platform === "win32" ? "go.exe" : "go"}`),
+            bundled: true,
+        };
     }
     catch {
         /* fall through */
     }
     const platformPackage = node_path_1.default.resolve(__dirname, "..", "..", "..", "..", `ttsc-${process.platform}-${process.arch}`, "bin", "go", "bin", process.platform === "win32" ? "go.exe" : "go");
-    if (node_fs_1.default.existsSync(platformPackage))
-        return platformPackage;
+    if (node_fs_1.default.existsSync(platformPackage)) {
+        return { binary: platformPackage, bundled: true };
+    }
     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;
+        return { binary: local, bundled: true };
     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";
+        return { binary: homeSdk, bundled: false };
+    return { binary: "go", bundled: false };
 }
 /**
  * Compute a deterministic SHA-256 cache key for a plugin build.
@@ -1769,6 +1864,9 @@ function resolveGoCompiler(env = process.env) {
  */
 function computeCacheKey(inputs) {
     const env = inputs.env ?? process.env;
+    const filesystem = {
+        readFile: inputs.filesystem?.readFile ?? DEFAULT_SOURCE_BUILD_FILESYSTEM.readFile,
+    };
     const goBinary = inputs.goBinary === undefined
         ? undefined
         : resolveGoToolForBuild(inputs.goBinary, env, inputs.dir);
@@ -1780,7 +1878,7 @@ function computeCacheKey(inputs) {
     if (goBinary !== undefined) {
         hash.update(`go=${resolveGoCompilerIdentity(goBinary, env, inputs.dir)}\n`);
     }
-    hashGoBuildEnvironment(hash, goBinary, inputs.dir, env);
+    hashGoBuildEnvironment(hash, goBinary, inputs.dir, env, filesystem);
     hashExternalGoBuildEnvironment(hash, env);
     hashSourceDirectory(hash, "plugin", inputs.dir);
     for (const [index, dir] of [...(inputs.overlayDirs ?? [])].sort().entries()) {
@@ -1860,8 +1958,9 @@ function isHashableFile(name) {
 // binary hashes for a value that does not change between plugins. The result
 // is a pure function of the go binary's resolved real path plus its on-disk
 // content; the memo key therefore mixes the resolved real path with a cheap
-// content signature (byte size + nanosecond mtime). That signature changes if
-// a long-lived host rewrites the binary in place between calls, so the memo
+// content signature (filesystem identity, mode, byte size, and nanosecond
+// change/modify times). That signature changes if a long-lived host rewrites
+// or atomically replaces the binary between calls, so the memo
 // re-derives the identity exactly as the un-memoized code would and the
 // cache-key bytes stay byte-for-byte identical to today. The selected compiler
 // path is shared by every build subprocess on Windows, while `go version` uses
@@ -1893,7 +1992,7 @@ function resolveGoCompilerIdentity(goBinary, env = process.env, cwd = process.cw
 // stat-ed, so the rare unstattable case never serves a stale identity.
 function goCompilerIdentityMemoKey(goBinary, resolved, env, cwd) {
     try {
-        const stat = node_fs_1.default.statSync(resolved);
+        const stat = node_fs_1.default.statSync(resolved, { bigint: true });
         const context = node_crypto_1.default.createHash("sha256");
         context.update(cwd);
         for (const [key, value] of Object.entries(env).sort(([left], [right]) => left === right ? 0 : left < right ? -1 : 1)) {
@@ -1901,7 +2000,17 @@ function goCompilerIdentityMemoKey(goBinary, resolved, env, cwd) {
                 continue;
             context.update(`\0${key.length}:${key}${value.length}:${value}`);
         }
-        return `${goBinary}\0${resolved}\0${stat.size}\0${stat.mtimeMs}\0${context.digest("hex")}`;
+        return [
+            goBinary,
+            resolved,
+            stat.dev,
+            stat.ino,
+            stat.mode,
+            stat.size,
+            stat.mtimeNs,
+            stat.ctimeNs,
+            context.digest("hex"),
+        ].join("\0");
     }
     catch {
         return null;
@@ -2094,8 +2203,8 @@ function hashFile(file) {
     hash.update(node_fs_1.default.readFileSync(file));
     return hash.digest("hex");
 }
-function hashGoBuildEnvironment(hash, goBinary, cwd, env) {
-    const values = resolveGoBuildEnvironment(goBinary, cwd, env);
+function hashGoBuildEnvironment(hash, goBinary, cwd, env, filesystem) {
+    const values = resolveGoBuildEnvironment(goBinary, cwd, env, filesystem);
     for (const key of GO_BUILD_ENV_KEYS) {
         const value = values.get(key);
         if (value !== undefined && value !== "") {
@@ -2103,7 +2212,7 @@ function hashGoBuildEnvironment(hash, goBinary, cwd, env) {
         }
     }
 }
-function resolveGoBuildEnvironment(goBinary, cwd, env) {
+function resolveGoBuildEnvironment(goBinary, cwd, env, filesystem) {
     const values = new Map();
     if (goBinary !== undefined) {
         const result = spawnGoTool(goBinary, ["env", "-json", ...GO_BUILD_ENV_KEYS], {
@@ -2118,7 +2227,7 @@ function resolveGoBuildEnvironment(goBinary, cwd, env) {
                 for (const key of GO_BUILD_ENV_KEYS) {
                     const raw = parsed[key];
                     if (typeof raw === "string" && raw !== "") {
-                        values.set(key, normalizeGoBuildEnvValue(key, raw, env));
+                        values.set(key, normalizeGoBuildEnvValue(key, raw, env, filesystem));
                     }
                 }
             }
@@ -2133,14 +2242,14 @@ function resolveGoBuildEnvironment(goBinary, cwd, env) {
             continue;
         const value = env[key];
         if (value !== undefined && value !== "") {
-            values.set(key, normalizeGoBuildEnvValue(key, value, env));
+            values.set(key, normalizeGoBuildEnvValue(key, value, env, filesystem));
         }
     }
     return values;
 }
-function normalizeGoBuildEnvValue(key, value, env) {
+function normalizeGoBuildEnvValue(key, value, env, filesystem) {
     if (key === "GOROOT") {
-        return resolveGoRootCacheIdentity(value);
+        return resolveGoRootCacheIdentity(value, filesystem);
     }
     if (GO_BUILD_COMMAND_ENV_KEYS.has(key)) {
         return `${value}\0${resolveCommandCacheIdentity(value, env)}`;
@@ -2183,32 +2292,81 @@ function hashExternalGoBuildEnvironment(hash, env) {
         }
     }
 }
-function resolveGoRootCacheIdentity(goRoot) {
+// GOROOT is immutable during normal use but contributes roughly 140 MiB of
+// source/tool content to every plugin key. Retain only the final pathless
+// content identity, guarded by a fresh metadata manifest on every call. A
+// changed or incomplete manifest falls through to the historical full read.
+const goRootIdentityCache = new Map();
+function resolveGoRootCacheIdentity(goRoot, filesystem) {
     const resolved = resolveRealPath(goRoot);
     if (!node_fs_1.default.existsSync(resolved)) {
         return `missing:${goRoot}`;
     }
+    const snapshot = collectGoRootIdentitySnapshot(resolved);
+    if (snapshot.complete) {
+        const cached = goRootIdentityCache.get(resolved);
+        if (cached?.signature === snapshot.signature) {
+            return cached.identity;
+        }
+    }
     const hash = node_crypto_1.default.createHash("sha256");
-    for (const file of collectGoRootIdentityFiles(resolved)) {
+    for (const file of snapshot.files) {
         const relative = node_path_1.default.relative(resolved, file).replace(/\\/g, "/");
         hash.update(`f=${relative}\n`);
-        hash.update(node_fs_1.default.readFileSync(file));
+        hash.update(filesystem.readFile(file));
         hash.update("\n");
     }
-    return `sha256:${hash.digest("hex")}`;
+    const identity = `sha256:${hash.digest("hex")}`;
+    if (snapshot.complete) {
+        goRootIdentityCache.set(resolved, {
+            identity,
+            signature: snapshot.signature,
+        });
+    }
+    return identity;
 }
-function collectGoRootIdentityFiles(root) {
+function collectGoRootIdentitySnapshot(root) {
     const out = [];
-    walkGoRootIdentity(root, root, out);
+    const state = { complete: true };
+    walkGoRootIdentity(root, root, out, state);
     out.sort();
-    return out;
+    const signature = node_crypto_1.default.createHash("sha256");
+    for (const file of out) {
+        const relative = node_path_1.default.relative(root, file).replace(/\\/g, "/");
+        try {
+            const stats = node_fs_1.default.statSync(file, { bigint: true });
+            if (!stats.isFile()) {
+                state.complete = false;
+                continue;
+            }
+            signature.update([
+                relative,
+                stats.dev,
+                stats.ino,
+                stats.mode,
+                stats.size,
+                stats.mtimeNs,
+                stats.ctimeNs,
+            ].join("\0"));
+            signature.update("\n");
+        }
+        catch {
+            state.complete = false;
+        }
+    }
+    return {
+        complete: state.complete,
+        files: out,
+        signature: signature.digest("hex"),
+    };
 }
-function walkGoRootIdentity(root, dir, out) {
+function walkGoRootIdentity(root, dir, out, state) {
     let entries;
     try {
         entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
     }
     catch {
+        state.complete = false;
         return;
     }
     for (const entry of entries) {
@@ -2216,7 +2374,7 @@ function walkGoRootIdentity(root, dir, out) {
         const rel = node_path_1.default.relative(root, file).replace(/\\/g, "/");
         if (entry.isDirectory()) {
             if (shouldHashGoRootPath(rel, true)) {
-                walkGoRootIdentity(root, file, out);
+                walkGoRootIdentity(root, file, out, state);
             }
         }
         else if (entry.isFile() && shouldHashGoRootPath(rel, false)) {
@@ -2265,50 +2423,554 @@ function shouldHashGoRootPath(rel, isDir) {
 function touchCacheEntry(cacheDir) {
     try {
         node_fs_1.default.mkdirSync(cacheDir, { recursive: true });
-        node_fs_1.default.writeFileSync(node_path_1.default.join(cacheDir, CACHE_LAST_USED_FILE), `${Date.now()}\n`);
+        replaceCacheMetadataFile(node_path_1.default.join(cacheDir, CACHE_LAST_USED_FILE), `${Date.now()}\n`);
     }
     catch {
         // Cache hits must not fail because metadata touch failed.
     }
 }
-function prunePluginCacheRoot(root) {
+function prunePluginCacheRoot(root, options = {}) {
     try {
-        node_fs_1.default.mkdirSync(root, { recursive: true });
-        const marker = node_path_1.default.join(root, CACHE_GC_MARKER_FILE);
-        const now = Date.now();
+        const cacheRoot = canonicalPluginCacheRoot(root);
+        const marker = node_path_1.default.join(cacheRoot, CACHE_GC_MARKER_FILE);
+        const now = options.now ?? Date.now();
         const lastRun = readTimestamp(marker);
-        if (lastRun !== null && now - lastRun < PLUGIN_CACHE_GC_INTERVAL_MS) {
+        if (options.force !== true &&
+            lastRun !== null &&
+            lastRun <= now &&
+            now - lastRun < PLUGIN_CACHE_GC_INTERVAL_MS) {
             return;
         }
-        node_fs_1.default.writeFileSync(marker, `${now}\n`);
-        prunePluginCacheEntries(root, now);
+        const remainingBytes = prunePluginCacheEntries(cacheRoot, {
+            maxBytes: options.maxBytes ?? PLUGIN_CACHE_MAX_BYTES,
+            now,
+            protectedEntries: canonicalPluginCacheProtectedEntries(cacheRoot, options.protectedEntries ?? []),
+            protectedAgeMs: options.protectedAgeMs ?? PLUGIN_CACHE_PROTECTED_AGE_MS,
+            targetBytes: options.targetBytes ?? PLUGIN_CACHE_TARGET_BYTES,
+        });
+        const maxBytes = options.maxBytes ?? PLUGIN_CACHE_MAX_BYTES;
+        const protectedAgeMs = options.protectedAgeMs ?? PLUGIN_CACHE_PROTECTED_AGE_MS;
+        const markerTimestamp = remainingBytes > maxBytes
+            ? now - PLUGIN_CACHE_GC_INTERVAL_MS + protectedAgeMs
+            : now;
+        replaceCacheMetadataFile(marker, `${markerTimestamp}\n`);
     }
     catch {
         // Plugin-cache GC is opportunistic; builds still proceed when it fails.
     }
 }
-function prunePluginCacheEntries(root, now) {
-    const entries = collectPluginCacheEntries(root, now);
+/** Resolve explicit GC exclusions without allowing an alias outside root. */
+function canonicalPluginCacheProtectedEntries(root, entries) {
+    const protectedEntries = new Set();
+    for (const entry of entries) {
+        const candidate = node_path_1.default.resolve(entry);
+        const stats = node_fs_1.default.lstatSync(candidate);
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            throw new Error(`ttsc: unsafe protected plugin cache entry: ${entry}`);
+        }
+        const physical = node_fs_1.default.realpathSync.native(candidate);
+        if (node_path_1.default.dirname(physical) !== root) {
+            throw new Error(`ttsc: protected plugin cache entry escaped root: ${entry}`);
+        }
+        protectedEntries.add(physical);
+    }
+    return protectedEntries;
+}
+/** Pin the default plugin cache to one ordinary physical directory. */
+function canonicalPluginCacheRoot(root) {
+    node_fs_1.default.mkdirSync(root, { recursive: true });
+    const physicalParent = node_fs_1.default.realpathSync.native(node_path_1.default.dirname(root));
+    const stats = node_fs_1.default.lstatSync(root);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error(`ttsc: unsafe plugin cache root: ${root}`);
+    }
+    // If an ancestor alias is retargeted after this point, all later cache work
+    // stays on the original physical directory rather than following it.
+    const physicalRoot = node_fs_1.default.realpathSync.native(root);
+    if (node_path_1.default.dirname(physicalRoot) !== physicalParent) {
+        throw new Error(`ttsc: plugin cache root escaped its parent: ${root}`);
+    }
+    return physicalRoot;
+}
+/** Create one content-addressed cache entry without following a leaf alias. */
+function canonicalPluginCacheEntry(root, key) {
+    const directory = node_path_1.default.join(root, key);
+    node_fs_1.default.mkdirSync(directory, { recursive: true });
+    const stats = node_fs_1.default.lstatSync(directory);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error(`ttsc: unsafe plugin cache entry: ${directory}`);
+    }
+    const physicalDirectory = node_fs_1.default.realpathSync.native(directory);
+    if (node_path_1.default.dirname(physicalDirectory) !== root) {
+        throw new Error(`ttsc: plugin cache entry escaped its root: ${directory}`);
+    }
+    return physicalDirectory;
+}
+function prunePluginCacheEntries(root, options) {
+    const entries = collectPluginCacheEntries(root, options.now);
     for (const entry of entries) {
-        if (now - entry.lastUsedAt <= PLUGIN_CACHE_ENTRY_MAX_AGE_MS) {
+        if (options.now - entry.lastUsedAt <= PLUGIN_CACHE_ENTRY_MAX_AGE_MS ||
+            options.protectedEntries.has(entry.dir) ||
+            pluginCacheEntryHasActiveBuild(entry, options.now)) {
             continue;
         }
         removeCacheEntry(entry);
     }
-    const remaining = collectPluginCacheEntries(root, now);
+    const remaining = collectPluginCacheEntries(root, options.now);
     let total = remaining.reduce((sum, entry) => sum + entry.size, 0);
-    if (total <= PLUGIN_CACHE_MAX_BYTES) {
-        return;
+    if (total <= options.maxBytes) {
+        return total;
+    }
+    const protectedEntries = new Set(options.protectedEntries);
+    let protectedBytes = 0;
+    for (const entry of [...remaining].sort((a, b) => b.lastUsedAt - a.lastUsedAt)) {
+        if (pluginCacheEntryHasActiveBuild(entry, options.now)) {
+            protectedEntries.add(entry.dir);
+            continue;
+        }
+        if (options.now - entry.lastUsedAt > options.protectedAgeMs)
+            continue;
+        if (protectedBytes >= options.targetBytes)
+            continue;
+        if (protectedBytes + entry.size > options.targetBytes)
+            continue;
+        protectedEntries.add(entry.dir);
+        protectedBytes += entry.size;
     }
     for (const entry of remaining.sort((a, b) => a.lastUsedAt - b.lastUsedAt)) {
-        if (total <= PLUGIN_CACHE_TARGET_BYTES) {
+        if (total <= options.targetBytes) {
+            return total;
+        }
+        if (protectedEntries.has(entry.dir))
+            continue;
+        if (removeCacheEntry(entry))
+            total -= entry.size;
+    }
+    return total;
+}
+/** Conservatively protect an entry while any build generation owns its key. */
+function pluginCacheEntryHasActiveBuild(entry, now) {
+    const lockDir = `${entry.dir}.lock`;
+    try {
+        return inspectPluginBuildLock(lockDir, now).state === "active";
+    }
+    catch {
+        // Malformed or unreadable coordination state cannot disprove ownership.
+        return true;
+    }
+}
+/**
+ * Opportunistically bound one ttsc-owned Go object cache.
+ *
+ * A maintenance intent blocks new build leases. If any existing lease remains,
+ * maintenance yields without touching the cache; the next invocation retries.
+ * Only Go's two-hex object directories are scanned, so coordination metadata
+ * and Go's own trim marker remain outside the size policy.
+ */
+function pruneGoBuildCacheRoot(root, options = {}) {
+    let intent;
+    try {
+        const cacheRoot = canonicalGoBuildCacheRoot(root);
+        const marker = node_path_1.default.join(cacheRoot, GO_BUILD_CACHE_GC_MARKER_FILE);
+        const now = options.now ?? Date.now();
+        const lastRun = readTimestamp(marker);
+        if (options.force !== true &&
+            lastRun !== null &&
+            lastRun <= now &&
+            now - lastRun < GO_BUILD_CACHE_GC_INTERVAL_MS) {
             return;
         }
-        if (now - entry.lastUsedAt <= PLUGIN_CACHE_PROTECTED_AGE_MS) {
+        intent = createGoBuildCacheCoordinationRecord(cacheRoot, GO_BUILD_CACHE_MAINTENANCE_DIR);
+        if (!intent.startHeartbeat()) {
+            // Maintenance is opportunistic. Without an independent heartbeat a
+            // synchronous scan could look abandoned while it is still deleting, so
+            // yield instead of weakening the build/maintenance exclusion.
+            return;
+        }
+        if (collectLiveGoBuildCacheCoordinationRecords(cacheRoot, GO_BUILD_CACHE_LEASE_DIR, now).length !== 0) {
+            return;
+        }
+        const remainingBytes = pruneGoBuildCacheEntries(cacheRoot, {
+            maxBytes: options.maxBytes ?? GO_BUILD_CACHE_MAX_BYTES,
+            now,
+            protectedAgeMs: options.protectedAgeMs ?? GO_BUILD_CACHE_PROTECTED_AGE_MS,
+            targetBytes: options.targetBytes ?? GO_BUILD_CACHE_TARGET_BYTES,
+        });
+        // If recent protection or a transient delete failure left the cache above
+        // the ceiling, retry after the protection window instead of suppressing
+        // every maintenance attempt for a full day.
+        const maxBytes = options.maxBytes ?? GO_BUILD_CACHE_MAX_BYTES;
+        const protectedAgeMs = options.protectedAgeMs ?? GO_BUILD_CACHE_PROTECTED_AGE_MS;
+        const markerTimestamp = remainingBytes > maxBytes
+            ? now - GO_BUILD_CACHE_GC_INTERVAL_MS + protectedAgeMs
+            : now;
+        replaceCacheMetadataFile(marker, `${markerTimestamp}\n`);
+    }
+    catch {
+        // Go-cache GC is opportunistic; builds still proceed when it fails.
+    }
+    finally {
+        intent?.finish();
+    }
+}
+/**
+ * Run one Go build under a cross-process cache lease when ttsc owns the cache.
+ *
+ * The lease is published before checking maintenance. A maintenance process
+ * that arrived first keeps its intent visible, so this builder withdraws and
+ * retries; one that arrives second sees the lease and yields. That ordering
+ * closes the scan/start race without serializing independent Go builds.
+ */
+function withGoBuildCacheLease(root, managed, callback) {
+    if (!managed) {
+        return callback(root);
+    }
+    const cacheRoot = canonicalGoBuildCacheRoot(root);
+    const started = Date.now();
+    for (;;) {
+        const lease = createGoBuildCacheCoordinationRecord(cacheRoot, GO_BUILD_CACHE_LEASE_DIR);
+        const maintenance = collectLiveGoBuildCacheCoordinationRecords(cacheRoot, GO_BUILD_CACHE_MAINTENANCE_DIR, Date.now());
+        if (maintenance.length === 0) {
+            try {
+                if (!lease.startHeartbeat()) {
+                    throw new Error(`ttsc: unable to start Go build cache lease heartbeat at ${cacheRoot}`);
+                }
+                return callback(cacheRoot);
+            }
+            finally {
+                lease.finish();
+            }
+        }
+        lease.finish();
+        if (Date.now() - started > PLUGIN_BUILD_LOCK_STEAL_MS) {
+            throw new Error(`ttsc: timed out waiting for Go build cache maintenance at ${cacheRoot}`);
+        }
+        sleepSync(GO_BUILD_CACHE_COORDINATION_POLL_MS);
+    }
+}
+/**
+ * Create and pin the owned Go cache to an ordinary physical directory.
+ *
+ * The leaf may be user-controlled inside `node_modules/.cache`; accepting a
+ * symlink or junction there would let LRU deletion escape into an arbitrary
+ * two-hex directory. Returning the canonical spelling also keeps the build,
+ * leases, and maintenance on the same directory if an ancestor alias moves.
+ */
+function canonicalGoBuildCacheRoot(root) {
+    node_fs_1.default.mkdirSync(root, { recursive: true });
+    const physicalParent = node_fs_1.default.realpathSync.native(node_path_1.default.dirname(root));
+    const stats = node_fs_1.default.lstatSync(root);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error(`ttsc: unsafe Go build cache root: ${root}`);
+    }
+    const physicalRoot = node_fs_1.default.realpathSync.native(root);
+    if (node_path_1.default.dirname(physicalRoot) !== physicalParent) {
+        throw new Error(`ttsc: Go build cache root escaped its parent: ${root}`);
+    }
+    return physicalRoot;
+}
+/** Prune oldest Go cache objects to the requested deterministic size target. */
+function pruneGoBuildCacheEntries(root, options) {
+    const entries = collectGoBuildCacheObjects(root);
+    let total = entries.reduce((sum, entry) => sum + entry.size, 0);
+    if (total <= options.maxBytes) {
+        return total;
+    }
+    // Protect the newest recent objects only up to one target-sized cohort
+    // reserve. Protecting every object younger than an hour would let repeated
+    // 2.9 GiB cold builds grow without bound during that hour.
+    const protectedFiles = new Set();
+    let protectedBytes = 0;
+    for (const entry of [...entries].sort((a, b) => b.lastUsedAt - a.lastUsedAt)) {
+        if (options.now - entry.lastUsedAt >
+            options.protectedAgeMs + GO_BUILD_CACHE_ACCESS_MTIME_GRANULARITY_MS) {
             continue;
         }
-        removeCacheEntry(entry);
-        total -= entry.size;
+        if (protectedBytes >= options.targetBytes) {
+            break;
+        }
+        if (protectedBytes + entry.size > options.targetBytes) {
+            break;
+        }
+        protectedFiles.add(entry.file);
+        protectedBytes += entry.size;
+    }
+    for (const entry of entries.sort((a, b) => a.lastUsedAt - b.lastUsedAt)) {
+        if (total <= options.targetBytes) {
+            return total;
+        }
+        if (protectedFiles.has(entry.file)) {
+            continue;
+        }
+        try {
+            node_fs_1.default.rmSync(entry.file, { force: true });
+            total -= entry.size;
+        }
+        catch {
+            // A concurrent antivirus/indexer can transiently hold a file on Windows.
+        }
+    }
+    return total;
+}
+function collectGoBuildCacheObjects(root) {
+    const output = [];
+    let buckets;
+    try {
+        buckets = node_fs_1.default.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return output;
+    }
+    for (const bucket of buckets) {
+        if (!bucket.isDirectory() || !/^[0-9a-f]{2}$/.test(bucket.name)) {
+            continue;
+        }
+        const directory = node_path_1.default.join(root, bucket.name);
+        let files;
+        try {
+            files = node_fs_1.default.readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            if (!file.isFile()) {
+                continue;
+            }
+            const absolute = node_path_1.default.join(directory, file.name);
+            try {
+                const stats = node_fs_1.default.statSync(absolute);
+                output.push({
+                    file: absolute,
+                    lastUsedAt: stats.mtimeMs,
+                    size: stats.size,
+                });
+            }
+            catch { }
+        }
+    }
+    return output;
+}
+function createGoBuildCacheCoordinationRecord(root, directoryName) {
+    const directory = goBuildCacheCoordinationDirectory(root, directoryName, true);
+    const record = node_path_1.default.join(directory, `${process.pid}-${node_crypto_1.default.randomBytes(16).toString("hex")}.json`);
+    const metadata = {
+        directoryName,
+        hostname: node_os_1.default.hostname(),
+        pid: process.pid,
+        startedAt: Date.now(),
+    };
+    writeGoBuildCacheCoordinationRecord(record, metadata, "active");
+    let heartbeat;
+    return {
+        file: record,
+        finish: () => {
+            heartbeat?.stop();
+            heartbeat = undefined;
+            // A failed unlink must not leave a completed task looking active until
+            // its stale timeout. Persist completion first; collectors discard it.
+            try {
+                writeGoBuildCacheCoordinationRecord(record, metadata, "complete");
+            }
+            catch { }
+            try {
+                node_fs_1.default.rmSync(record, { force: true });
+            }
+            catch { }
+        },
+        startHeartbeat: () => {
+            heartbeat ??= startGoBuildCacheHeartbeat(record);
+            return heartbeat !== undefined;
+        },
+    };
+}
+function writeGoBuildCacheCoordinationRecord(file, metadata, status) {
+    replaceCacheMetadataFile(file, `${JSON.stringify({ ...metadata, status, version: 1 })}\n`);
+}
+/** Refresh one synchronous cache task's record from a background worker. */
+function startGoBuildCacheHeartbeat(file) {
+    const control = new SharedArrayBuffer(4);
+    const state = new Int32Array(control);
+    try {
+        const worker = new node_worker_threads_1.Worker([
+            'const fs = process.getBuiltinModule("node:fs");',
+            'const { workerData } = process.getBuiltinModule("node:worker_threads");',
+            "const state = new Int32Array(workerData.control);",
+            "for (;;) {",
+            "  const result = Atomics.wait(state, 0, 0, workerData.interval);",
+            '  if (result !== "timed-out" || Atomics.load(state, 0) !== 0) break;',
+            "  try {",
+            "    const now = new Date();",
+            "    fs.utimesSync(workerData.file, now, now);",
+            "  } catch {}",
+            "}",
+        ].join("\n"), {
+            eval: true,
+            workerData: {
+                control,
+                file,
+                interval: GO_BUILD_CACHE_COORDINATION_HEARTBEAT_MS,
+            },
+        });
+        worker.unref();
+        return {
+            stop: () => {
+                Atomics.store(state, 0, 1);
+                Atomics.notify(state, 0);
+                void worker.terminate();
+            },
+        };
+    }
+    catch { }
+    // Node's permission model can deny Worker construction while still allowing
+    // the child process required for `go build`. An IPC-bound helper provides
+    // the same independent heartbeat and exits automatically if its parent dies.
+    try {
+        const child = (0, node_child_process_1.spawn)(process.execPath, [
+            "-e",
+            [
+                'const fs = require("node:fs");',
+                "const file = process.argv[1];",
+                "const interval = Number(process.argv[2]);",
+                "const timer = setInterval(() => {",
+                "  try {",
+                "    const now = new Date();",
+                "    fs.utimesSync(file, now, now);",
+                "  } catch {}",
+                "}, interval);",
+                'process.on("disconnect", () => {',
+                "  clearInterval(timer);",
+                "  process.exit(0);",
+                "});",
+            ].join("\n"),
+            file,
+            String(GO_BUILD_CACHE_COORDINATION_HEARTBEAT_MS),
+        ], {
+            stdio: ["ignore", "ignore", "ignore", "ipc"],
+            windowsHide: true,
+        });
+        child.unref();
+        child.channel?.unref();
+        return {
+            stop: () => {
+                if (child.connected)
+                    child.disconnect();
+                child.kill();
+            },
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function collectLiveGoBuildCacheCoordinationRecords(root, directoryName, now) {
+    const directory = goBuildCacheCoordinationDirectory(root, directoryName, false);
+    if (directory === undefined)
+        return [];
+    let records;
+    try {
+        records = node_fs_1.default.readdirSync(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const live = [];
+    for (const record of records) {
+        if (!record.isFile()) {
+            continue;
+        }
+        const file = node_path_1.default.join(directory, record.name);
+        if (goBuildCacheCoordinationRecordIsLive(file, directoryName, now)) {
+            live.push(file);
+            continue;
+        }
+        try {
+            node_fs_1.default.rmSync(file, { force: true });
+        }
+        catch { }
+    }
+    return live;
+}
+/**
+ * Resolve one private coordination directory without following a project-
+ * supplied symlink or junction outside the owned Go cache.
+ */
+function goBuildCacheCoordinationDirectory(root, directoryName, create) {
+    if (create)
+        node_fs_1.default.mkdirSync(root, { recursive: true });
+    const directory = node_path_1.default.join(root, directoryName);
+    if (create) {
+        try {
+            node_fs_1.default.mkdirSync(directory);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    let stats;
+    try {
+        stats = node_fs_1.default.lstatSync(directory);
+    }
+    catch (error) {
+        if (!create && error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error(`ttsc: unsafe Go build cache coordination directory: ${directory}`);
+    }
+    const physicalRoot = node_fs_1.default.realpathSync.native(root);
+    const physicalDirectory = node_fs_1.default.realpathSync.native(directory);
+    if (node_path_1.default.dirname(physicalDirectory) !== physicalRoot) {
+        throw new Error(`ttsc: Go build cache coordination directory escaped its root: ${directory}`);
+    }
+    return physicalDirectory;
+}
+function goBuildCacheCoordinationRecordIsLive(file, directoryName, now) {
+    let contents;
+    try {
+        contents = node_fs_1.default.readFileSync(file, "utf8");
+        const parsed = JSON.parse(contents);
+        if (parsed.status === "complete")
+            return false;
+        // Parse valid records for forward compatibility, but do not equate a PID's
+        // lifetime with one task. A failed unlink can leave a record owned by a
+        // still-running Vite process, while a dead Node parent can leave its
+        // spawnSync Go child alive. The heartbeat/grace below models the task.
+        void parsed;
+    }
+    catch { }
+    try {
+        const age = now - node_fs_1.default.statSync(file).mtimeMs;
+        if (age < -GO_BUILD_CACHE_COORDINATION_CLOCK_SKEW_MS) {
+            // A restored cache can carry a far-future timestamp, but the same state
+            // also occurs when the system clock moves backward during a real build.
+            // Rebase the record and grant one ordinary grace period; an active
+            // heartbeat keeps refreshing it, while an orphan then expires normally.
+            // Treat a failed rebase as live too: the safe failure mode is to defer
+            // opportunistic maintenance, never to delete under a possibly live Go.
+            // Replace the directory entry rather than changing its inode in place.
+            // A restored or user-modified cache can contain a hard-linked record;
+            // utimesSync(file) would then mutate metadata outside the owned cache.
+            if (contents !== undefined) {
+                try {
+                    replaceCacheMetadataFile(file, contents);
+                }
+                catch { }
+            }
+            return true;
+        }
+        const staleMs = directoryName === GO_BUILD_CACHE_MAINTENANCE_DIR
+            ? GO_BUILD_CACHE_MAINTENANCE_STALE_MS
+            : GO_BUILD_CACHE_COORDINATION_STALE_MS;
+        return age <= staleMs;
+    }
+    catch (error) {
+        return error.code !== "ENOENT";
     }
 }
 function collectPluginCacheEntries(root, now) {
@@ -2370,6 +3032,24 @@ function readTimestamp(file) {
         return null;
     }
 }
+/** Replace cache metadata without following a pre-existing link or hard link. */
+function replaceCacheMetadataFile(file, contents) {
+    const temporary = node_path_1.default.join(node_path_1.default.dirname(file), `.${node_path_1.default.basename(file)}.${process.pid}-${node_crypto_1.default
+        .randomBytes(16)
+        .toString("hex")}.tmp`);
+    try {
+        node_fs_1.default.writeFileSync(temporary, contents, { encoding: "utf8", flag: "wx" });
+        // rename replaces the directory entry itself. Unlike writeFile(file), it
+        // cannot follow a symlink or mutate another hard link to the old inode.
+        node_fs_1.default.renameSync(temporary, file);
+    }
+    finally {
+        try {
+            node_fs_1.default.rmSync(temporary, { force: true });
+        }
+        catch { }
+    }
+}
 function directorySize(dir) {
     let total = 0;
     let entries;
@@ -2396,9 +3076,11 @@ function directorySize(dir) {
 function removeCacheEntry(entry) {
     try {
         node_fs_1.default.rmSync(entry.dir, { recursive: true, force: true });
+        return !node_fs_1.default.existsSync(entry.dir);
     }
     catch {
         // Windows may reject removal while a plugin binary is still running.
+        return false;
     }
 }
 //# sourceMappingURL=buildSourcePlugin.js.map