ttsc 0.26.2 → 0.28.0

package/src/index.ts

@@ -7,6 +7,7 @@
  * package surface remains small and stable.
  */
 
+export * from "./plugin/resolveCapabilityPlugins";
 export * from "./TtscCompiler";
 export * from "./TtscService";
 export * from "./structures/index";

package/src/internal/createCanonicalTempDirectory.ts

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export interface CanonicalTempDirectoryOperations {
+  lstat(location: string): { isDirectory(): boolean };
+  mkdtemp(prefix: string): string;
+  realpath(location: string): string;
+}
+
+const FILESYSTEM_OPERATIONS: CanonicalTempDirectoryOperations = {
+  lstat: fs.lstatSync,
+  mkdtemp: fs.mkdtempSync,
+  realpath: fs.realpathSync.native,
+};
+
+/**
+ * Create a unique temporary directory under a frozen physical parent.
+ *
+ * The parent is resolved before creation so retargeting the caller's
+ * TEMP/TMPDIR alias cannot redirect later writes or recursive cleanup. The
+ * postflight accepts only a real directory that resolves to a direct child of
+ * that same parent; a rejected child is deliberately left untouched because no
+ * safe ownership identity was established.
+ */
+export function createCanonicalTempDirectory(
+  prefix: string,
+  parent: string = os.tmpdir(),
+  operations: CanonicalTempDirectoryOperations = FILESYSTEM_OPERATIONS,
+): string {
+  if (prefix.length === 0 || path.basename(prefix) !== prefix) {
+    throw new TypeError("ttsc: temporary directory prefix must be a basename");
+  }
+  const physicalParent = operations.realpath(path.resolve(parent));
+  if (!operations.lstat(physicalParent).isDirectory()) {
+    throw new Error(
+      `ttsc: temporary directory parent is not a directory: ${physicalParent}`,
+    );
+  }
+  const directory = operations.mkdtemp(path.join(physicalParent, prefix));
+  if (!operations.lstat(directory).isDirectory()) {
+    throw new Error(
+      `ttsc: temporary directory postflight is not a directory: ${directory}`,
+    );
+  }
+  const physicalDirectory = operations.realpath(directory);
+  if (path.dirname(physicalDirectory) !== physicalParent) {
+    throw new Error(
+      `ttsc: temporary directory escaped its physical parent: ${physicalDirectory}`,
+    );
+  }
+  return physicalDirectory;
+}

package/src/internal/projectInputPathIdentity.ts

@@ -11,7 +11,9 @@ export type FilesystemPathIdentity = {
 
 export type FilesystemPathIdentityOperations = {
   caseSensitive(directory: string): boolean;
+  lstat?(location: string): fs.Stats | fs.BigIntStats;
   platform: NodeJS.Platform;
+  readdir?(directory: string): string[];
   realpath(location: string): string;
   throwOnRealpathError: boolean;
 };
@@ -53,10 +55,16 @@ export function createFilesystemPathIdentityContext(
   const pathApi = platform === "win32" ? path.win32 : path;
   const throwOnRealpathError = operations.throwOnRealpathError ?? true;
   const realpath = operations.realpath ?? physicalRealpath;
+  const lstat = operations.lstat ?? fs.lstatSync;
+  const readdir = operations.readdir ?? fs.readdirSync;
   const caseSensitive =
     operations.caseSensitive ??
     ((directory: string) =>
-      filesystemDirectoryIsCaseSensitive(directory, platform));
+      filesystemDirectoryIsCaseSensitive(directory, platform, {
+        lstat,
+        readdir,
+        realpath,
+      }));
 
   const resolve = (location: string): FilesystemPathIdentity => {
     const normalized = resolveFilesystemPath(location, platform);
@@ -210,10 +218,15 @@ function physicalRealpath(location: string): string {
 function filesystemDirectoryIsCaseSensitive(
   directory: string,
   platform: NodeJS.Platform,
+  operations: {
+    lstat(location: string): fs.Stats | fs.BigIntStats;
+    readdir(directory: string): string[];
+    realpath(location: string): string;
+  },
 ): boolean {
   let entries: string[];
   try {
-    entries = fs.readdirSync(directory);
+    entries = operations.readdir(directory);
   } catch {
     return unprovenCaseSensitivity(platform);
   }
@@ -229,7 +242,7 @@ function filesystemDirectoryIsCaseSensitive(
     const alternate = alternateCase(name);
     if (alternate === name) continue;
     try {
-      fs.lstatSync(path.join(directory, alternate));
+      operations.lstat(path.join(directory, alternate));
       return false;
     } catch (error) {
       if (isMissingFilesystemEntry(error)) {
@@ -254,7 +267,7 @@ function filesystemDirectoryIsCaseSensitive(
       const alternate = alternateCase(name);
       if (alternate !== name) {
         try {
-          physicalRealpath(path.join(parent, alternate));
+          operations.realpath(path.join(parent, alternate));
           return false;
         } catch (error) {
           if (isMissingFilesystemEntry(error) === false) throw error;

package/src/internal/resolveNodeBinary.ts

@@ -0,0 +1,173 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+export type JavaScriptRuntimeCapabilities = {
+  bun: boolean;
+  executable?: string;
+  registerHooks: boolean;
+};
+
+type RuntimeCapabilityCacheEntry = {
+  capabilities: JavaScriptRuntimeCapabilities;
+  identity: string;
+};
+
+const runtimeCapabilityCache = new Map<string, RuntimeCapabilityCacheEntry>();
+
+/** Probe an interpreter instead of inferring its identity from the host. */
+export function javascriptRuntimeCapabilities(
+  runtime: string,
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+): JavaScriptRuntimeCapabilities {
+  const effectiveEnv = { ...process.env, ...env };
+  const cacheKey = runtimeCapabilityCacheKey(runtime, effectiveEnv);
+  const beforeIdentity = runtimeExecutableIdentity(runtime);
+  if (cacheKey !== undefined && beforeIdentity !== undefined) {
+    const cached = runtimeCapabilityCache.get(cacheKey);
+    if (cached?.identity === beforeIdentity) return { ...cached.capabilities };
+    runtimeCapabilityCache.delete(cacheKey);
+  }
+  const result = childProcess.spawnSync(
+    runtime,
+    [
+      "-e",
+      `const Module = require("node:module"); process.stdout.write(JSON.stringify({ bun: typeof globalThis.Bun === "object", executable: process.execPath, registerHooks: typeof Module.registerHooks === "function" }));`,
+    ],
+    {
+      cwd,
+      encoding: "utf8",
+      env: effectiveEnv,
+      timeout: 30_000,
+      windowsHide: true,
+    },
+  );
+  let capabilities: JavaScriptRuntimeCapabilities = {
+    bun: false,
+    registerHooks: false,
+  };
+  if (result.status === 0) {
+    try {
+      const parsed = JSON.parse(
+        result.stdout,
+      ) as Partial<JavaScriptRuntimeCapabilities>;
+      capabilities = {
+        bun: parsed.bun === true,
+        ...(typeof parsed.executable === "string" &&
+        path.isAbsolute(parsed.executable)
+          ? { executable: path.resolve(parsed.executable) }
+          : {}),
+        registerHooks: parsed.registerHooks === true,
+      };
+    } catch {
+      // An incompatible executable is not a Node runtime candidate.
+    }
+  }
+  // Cache successful absolute candidates only when the child reports that same
+  // executable and both its lexical link and physical target retain the same
+  // filesystem identity. Relative/bare commands and wrappers can resolve
+  // differently by cwd/PATH/environment, negative probes can become valid later,
+  // and NODE_OPTIONS can load mutable user code, so none of those states are
+  // memoized. This removes a process spawn from the common path without
+  // authorizing a replaced or redirected runtime in a long-lived host.
+  const afterIdentity = runtimeExecutableIdentity(runtime);
+  if (
+    cacheKey !== undefined &&
+    capabilities.executable !== undefined &&
+    beforeIdentity !== undefined &&
+    beforeIdentity === afterIdentity &&
+    sameRuntimeExecutable(runtime, capabilities.executable)
+  ) {
+    runtimeCapabilityCache.set(cacheKey, {
+      capabilities: { ...capabilities },
+      identity: afterIdentity,
+    });
+  }
+  return capabilities;
+}
+
+/** True when a probe ran the candidate itself rather than a mutable wrapper. */
+function sameRuntimeExecutable(candidate: string, executable: string): boolean {
+  try {
+    const candidateStats = fs.statSync(candidate, { bigint: true });
+    const executableStats = fs.statSync(executable, { bigint: true });
+    return (
+      (candidateStats.ino !== 0n &&
+        candidateStats.dev === executableStats.dev &&
+        candidateStats.ino === executableStats.ino) ||
+      fs.realpathSync.native(candidate) === fs.realpathSync.native(executable)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Stable cache key only for an absolute runtime with no preload authority. */
+function runtimeCapabilityCacheKey(
+  runtime: string,
+  env: NodeJS.ProcessEnv,
+): string | undefined {
+  if (!path.isAbsolute(runtime) || env.NODE_OPTIONS?.trim()) return undefined;
+  return path.resolve(runtime);
+}
+
+/** Identity of an executable spelling and the physical file it selects. */
+function runtimeExecutableIdentity(runtime: string): string | undefined {
+  if (!path.isAbsolute(runtime)) return undefined;
+  try {
+    const lexical = fs.lstatSync(runtime, { bigint: true });
+    const physicalPath = fs.realpathSync.native(runtime);
+    const physical = fs.statSync(physicalPath, { bigint: true });
+    return [
+      physicalPath,
+      lexical.dev,
+      lexical.ino,
+      lexical.mode,
+      lexical.size,
+      lexical.mtimeNs,
+      lexical.ctimeNs,
+      physical.dev,
+      physical.ino,
+      physical.mode,
+      physical.size,
+      physical.mtimeNs,
+      physical.ctimeNs,
+    ].join("\0");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Locate a real Node runtime for ttsx and native JavaScript config loaders.
+ *
+ * Bun can directly evaluate a descriptor, but it does not implement the
+ * synchronous `module.registerHooks` contract used by those loaders.
+ */
+export function resolveNodeBinary(
+  env: NodeJS.ProcessEnv = process.env,
+  cwd: string = process.cwd(),
+): string | undefined {
+  const candidates = [
+    env.TTSC_NODE_BINARY,
+    process.env.TTSC_NODE_BINARY,
+    process.execPath,
+    "node",
+  ];
+  const seen = new Set<string>();
+  for (const candidate of candidates) {
+    if (candidate === undefined || candidate.trim() === "") continue;
+    if (seen.has(candidate)) continue;
+    seen.add(candidate);
+    const capabilities = javascriptRuntimeCapabilities(candidate, env, cwd);
+    if (
+      !capabilities.bun &&
+      capabilities.registerHooks &&
+      capabilities.executable !== undefined
+    ) {
+      return capabilities.executable;
+    }
+  }
+  return undefined;
+}

package/src/internal/resolveSafeCacheCleanupTargets.ts

@@ -0,0 +1,85 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  type FilesystemPathIdentityOperations,
+  createFilesystemPathIdentityContext,
+  isFilesystemPathIdentityWithin,
+  resolveFilesystemPath,
+} from "./projectInputPathIdentity";
+
+export interface SafeCacheCleanupTarget {
+  exists: boolean;
+  path: string;
+  requestedPath: string;
+}
+
+/**
+ * Resolve one cache-clean transaction to physical deletion targets.
+ *
+ * Every target is proved before the caller removes the first one. Existing
+ * aliases are pinned to their physical spelling, while a missing suffix keeps
+ * the identity of its nearest existing parent. Identity errors other than a
+ * genuinely missing path fail closed.
+ */
+export function resolveSafeCacheCleanupTargets(
+  projectRoot: string,
+  cacheDirectories: readonly string[],
+  operations: Partial<FilesystemPathIdentityOperations> = {},
+): SafeCacheCleanupTarget[] {
+  const identities = createFilesystemPathIdentityContext(operations);
+  const lstat = operations.lstat ?? fs.lstatSync;
+  const project = identities.resolve(projectRoot);
+  return cacheDirectories.map((cacheDirectory) => {
+    const requestedCache = resolveFilesystemPath(cacheDirectory);
+    // Fix every mutable alias ancestor before inspecting the terminal entry.
+    // All later identity checks and deletion paths use this physical-parent
+    // candidate, so a concurrent retarget cannot move ownership mid-proof.
+    const pinnedCache = path.join(
+      identities.resolve(path.dirname(requestedCache)).path,
+      path.basename(requestedCache),
+    );
+    const cache = identities.resolve(pinnedCache);
+    if (
+      requestedCache === path.parse(requestedCache).root ||
+      cache.path === path.parse(cache.path).root
+    ) {
+      throw new Error(
+        `ttsc: refusing to clean cache directory ${JSON.stringify(requestedCache)} because filesystem roots are never valid cache directories`,
+      );
+    }
+    if (isFilesystemPathIdentityWithin(cache.key, project.key)) {
+      throw new Error(
+        `ttsc: refusing to clean cache directory ${JSON.stringify(requestedCache)} because it equals or contains project root ${JSON.stringify(project.path)}; choose a dedicated cache directory`,
+      );
+    }
+    const status = lstatIfPresent(pinnedCache, lstat);
+    // Recursive rm removes a terminal symlink or junction itself rather than
+    // following it. Preserve that behavior while pinning any mutable alias in
+    // its ancestors to the physical parent selected by this transaction.
+    const deletionPath = status?.isSymbolicLink() ? pinnedCache : cache.path;
+    return {
+      exists: status !== undefined,
+      path: deletionPath,
+      requestedPath: requestedCache,
+    };
+  });
+}
+
+function lstatIfPresent(
+  location: string,
+  lstat: NonNullable<FilesystemPathIdentityOperations["lstat"]>,
+): fs.Stats | fs.BigIntStats | undefined {
+  try {
+    return lstat(location);
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error.code === "ENOENT" || error.code === "ENOTDIR")
+    ) {
+      return undefined;
+    }
+    throw error;
+  }
+}

package/src/launcher/internal/prepareExecution.ts

@@ -10,8 +10,6 @@ import { createFilesystemPathIdentityContext } from "../../internal/projectInput
 import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
 import { type OwningModuleOptions, projectModuleOptions } from "./runtimeHooks";
 
-/** Subdirectory name that isolates concurrent ttsx processes by PID. */
-const PROCESS_CACHE_KEY = String(process.pid);
 /**
  * Maximum number of ancestor directories above the project root that the
  * virtual filesystem overlay mirrors. Three levels covers the common monorepo
@@ -32,12 +30,15 @@ export function prepareExecution(
   options: TtscCommonOptions & {
     cacheDir?: string;
     project?: string;
+    /** Internal cache key for more than one checked entry in this process. */
+    runtimeCacheKey?: string;
   } = {},
 ): {
   cleanupDir: string;
   emitDir: string;
   emittedFiles?: readonly string[];
   entryFile: string;
+  entrySource: string;
   moduleOptions: OwningModuleOptions;
   projectRoot: string;
   rootDir: string;
@@ -74,6 +75,7 @@ export function prepareExecution(
       emitDir: context.emitDir,
       emittedFiles: context.emittedFiles ?? undefined,
       entryFile: emittedEntry,
+      entrySource: entry,
       moduleOptions: context.moduleOptions,
       projectRoot: context.root,
       rootDir: context.runtimeRootDir,
@@ -147,6 +149,19 @@ function resolveEntrySpelling(cwd: string, entryFile: string): string {
   return identities.resolve(path.resolve(cwd, entryFile)).path;
 }
 
+/**
+ * Directory-safe identity for one prepared runtime. Direct `ttsx` retains its
+ * historical PID directory; the public preload supplies a distinct key for
+ * every late TypeScript root so one preparation cannot erase another's emit.
+ */
+function resolveRuntimeCacheKey(runtimeCacheKey: string | undefined): string {
+  const key = runtimeCacheKey ?? String(process.pid);
+  if (!/^[A-Za-z0-9._-]+$/.test(key) || key === "." || key === "..") {
+    throw new Error(`ttsx: invalid runtime cache key ${JSON.stringify(key)}`);
+  }
+  return key;
+}
+
 /**
  * @param discoveryFile - The entry as the user named it. Project discovery
  *   walks up from here, so it must not be retargeted through a symlink.
@@ -168,21 +183,30 @@ function createProjectContext(
   const tsconfig = project.path;
   const root = project.root;
   const explicitCacheDir = resolveCacheDir(cwd, options.cacheDir);
-  const cacheDir =
+  const cacheDirSpelling =
     explicitCacheDir ??
     path.join(root, "node_modules", ".cache", "ttsc", "ttsx");
-  const processDir = path.join(cacheDir, "project", PROCESS_CACHE_KEY);
-  const virtualRoot = path.join(processDir, "fs");
+  const runtimeCacheKey = resolveRuntimeCacheKey(options.runtimeCacheKey);
   // Resolved once: it now costs a realpath (and, for a missing directory on
   // Windows, a case-sensitivity probe) rather than a string join.
   const runtimeRootDir = resolveRuntimeSourceRoot(project);
+  fs.mkdirSync(cacheDirSpelling, { recursive: true });
+  // Pin the cache parent before deriving a generation path. Descriptors run
+  // after this point and may retarget a caller-controlled symlink or junction;
+  // every later runtime write and recursive cleanup must remain below the
+  // physical parent selected here.
+  const cacheDir =
+    createFilesystemPathIdentityContext().resolve(cacheDirSpelling).path;
+  const processDir = path.join(cacheDir, "project", runtimeCacheKey);
+  const virtualRoot = path.join(processDir, "fs");
   return {
     project,
     tsconfig,
     root,
     cacheDir,
+    runtimeCacheKey,
     processDir,
-    pluginCacheDir: explicitCacheDir,
+    pluginCacheDir: explicitCacheDir === undefined ? undefined : cacheDir,
     virtualRoot,
     emitDir: project.compilerOptions.outDir
       ? virtualPath(virtualRoot, project.compilerOptions.outDir)
@@ -361,7 +385,7 @@ function buildEntryProject(
   const rootDir = commonAncestorDirectory(path.dirname(entry), context.root);
   const tsconfig = path.join(
     context.root,
-    `.ttsx-entry.${PROCESS_CACHE_KEY}.tsconfig.json`,
+    `.ttsx-entry.${context.runtimeCacheKey}.tsconfig.json`,
   );
   fs.writeFileSync(
     tsconfig,
@@ -430,8 +454,8 @@ function buildEntryProject(
       fs.rmSync(tsconfig, { force: true });
     } catch {
       // Best effort: a leftover synthesized tsconfig must not mask a build
-      // failure, and it is PID-scoped so it can never be mistaken for a real
-      // project config.
+      // failure, and it is runtime-scoped so it can never be mistaken for a
+      // real project config.
     }
   }
 }
@@ -575,6 +599,9 @@ function isDirectorySymlinkTarget(realEntry: string): boolean {
  */
 function collectLinkDirectories(projectRoot: string): string[] {
   const out: string[] = [];
+  const identities = createFilesystemPathIdentityContext({
+    throwOnRealpathError: false,
+  });
   let current = projectRoot;
   for (let depth = 0; depth <= MAX_VIRTUAL_PARENT_DEPTH; depth += 1) {
     out.push(current);
@@ -586,7 +613,7 @@ function collectLinkDirectories(projectRoot: string): string[] {
       break;
     }
     const parent = path.dirname(current);
-    if (parent === current || isUnsafeVirtualParent(parent)) {
+    if (parent === current || isUnsafeVirtualParent(parent, identities)) {
       break;
     }
     current = parent;
@@ -594,10 +621,19 @@ function collectLinkDirectories(projectRoot: string): string[] {
   return out.reverse();
 }
 
-function isUnsafeVirtualParent(directory: string): boolean {
-  const resolved = path.resolve(directory);
-  const root = path.parse(resolved).root;
-  return resolved === root || resolved === path.resolve(os.tmpdir());
+/**
+ * Whether mirroring `directory` would reach a filesystem or temporary root.
+ * Identity comparison is required on Windows, where `os.tmpdir()` can carry an
+ * 8.3 component while a project created below it is returned in long spelling.
+ */
+function isUnsafeVirtualParent(
+  directory: string,
+  identities: ReturnType<typeof createFilesystemPathIdentityContext>,
+): boolean {
+  const resolved = identities.resolve(directory);
+  const root = identities.resolve(path.parse(resolved.path).root);
+  const temporaryRoot = identities.resolve(os.tmpdir());
+  return resolved.key === root.key || resolved.key === temporaryRoot.key;
 }
 
 /**

package/src/launcher/internal/runTtsc.ts

@@ -17,7 +17,7 @@ import {
   parseFlags,
 } from "../../flags/parser";
 import { resolveFlagSpec } from "../../flags/schema";
-import { assertSafeExplicitCacheDirectory } from "../../internal/assertSafeExplicitCacheDirectory";
+import { resolveSafeCacheCleanupTargets } from "../../internal/resolveSafeCacheCleanupTargets";
 import {
   isPathWithin,
   legacyGlobalCacheTargets,
@@ -207,9 +207,6 @@ function runClean(argv: readonly string[]): number {
   const explicitCacheDir = options.cacheDir
     ? path.resolve(cwd, options.cacheDir)
     : undefined;
-  if (explicitCacheDir !== undefined) {
-    assertSafeExplicitCacheDirectory(projectRoot, explicitCacheDir);
-  }
   const targets = explicitCacheDir
     ? // Explicit `ttsc clean --cache-dir X`: the user names X as the cache to
       // remove for this command, so remove it wholesale plus the legacy
@@ -223,11 +220,19 @@ function runClean(argv: readonly string[]): number {
       // possibly-shared root is never deleted) plus the pre-0.17 machine-global
       // cache so upgraders reclaim that disk.
       [...resolveCleanTargets(projectRoot), ...legacyGlobalCacheTargets()];
+  // Check the complete deletion set before removing the first directory. An
+  // environment-selected TTSC_GO_CACHE_DIR and a legacy-global cache can be as
+  // destructive as an explicit --cache-dir when either equals or contains the
+  // project through its lexical spelling or a filesystem alias.
+  const safeTargets = resolveSafeCacheCleanupTargets(projectRoot, targets);
   const removed: string[] = [];
-  for (const target of targets) {
-    if (!fs.existsSync(target)) continue;
-    fs.rmSync(target, { recursive: true, force: true });
-    removed.push(target);
+  const visited = new Set<string>();
+  for (const target of safeTargets) {
+    if (visited.has(target.path)) continue;
+    visited.add(target.path);
+    if (!target.exists || !fs.existsSync(target.path)) continue;
+    fs.rmSync(target.path, { recursive: true, force: true });
+    removed.push(target.requestedPath);
   }
   if (removed.length === 0) {
     process.stdout.write(
@@ -269,24 +274,28 @@ function runCachePaths(argv: readonly string[]): number {
   const cacheDir = resolveCacheDir(cwd, options.cacheDir);
   const projectRoot = resolveCleanProjectRoot(cwd, options.tsconfig);
   const paths = resolveSourceBuildCachePaths(projectRoot, cacheDir);
-  // The minimal directory set a CI cache step must persist. The Go build cache
-  // is folded in only when it lives outside the ttsc cache root (an explicit
-  // GOCACHE / TTSC_GO_CACHE_DIR); by default it nests under `root`.
+  // Legacy combined roots retained for JSON compatibility. `requiredRoots`
+  // identifies the compiled binaries that skip cold builds;
+  // `acceleratorRoots` separately identifies the optional Go object cache.
   const cacheableRoots = [
     paths.root,
     ...(isPathWithin(paths.goBuildRoot, paths.root) ? [] : [paths.goBuildRoot]),
   ];
+  const requiredRoots = [paths.pluginRoot];
+  const acceleratorRoots = [paths.goBuildRoot];
   if (options.json) {
     process.stdout.write(
       `${JSON.stringify(
         {
           cacheRoot: paths.root,
+          acceleratorRoots,
           cacheableRoots,
           cwd,
           goBuildCacheRoot: paths.goBuildRoot,
           goBuildCacheSource: paths.goBuildRootSource,
           pluginCacheRoot: paths.pluginRoot,
           projectRoot,
+          requiredRoots,
         },
         null,
         2,
@@ -301,8 +310,10 @@ function runCachePaths(argv: readonly string[]): number {
       `  plugin binaries  ${paths.pluginRoot}`,
       `  go build cache   ${paths.goBuildRoot} (${paths.goBuildRootSource})`,
       "",
-      "Persist these between CI jobs to skip cold plugin rebuilds:",
-      ...cacheableRoots.map((root) => `  ${root}`),
+      "Persist this required cache to skip cold plugin rebuilds:",
+      ...requiredRoots.map((root) => `  ${root}`),
+      "Optionally persist this Go object accelerator for future cache misses:",
+      ...acceleratorRoots.map((root) => `  ${root}`),
       "",
     ].join("\n"),
   );