ttsc 0.30.3 → 0.31.0

package/src/plugin/internal/source/resolveSourceBuildCachePaths.ts

@@ -0,0 +1,276 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { SidecarEnvironment } from "../../../compiler/internal/sharedHost/SidecarEnvironment";
+import type { ITtscSourceBuildCachePaths } from "./ITtscSourceBuildCachePaths";
+import { SourceBuildCacheLayout } from "./SourceBuildCacheLayout";
+
+/**
+ * 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. The default Go
+ * cache lives under `root`; `TTSC_GO_CACHE_DIR` is independently resolved,
+ * while external `GOCACHE` preserves its supplied value for Go to validate.
+ * Their selection provenance keeps the ownership policies distinct.
+ *
+ * @evidence contracts/common.md#principled-implementation Plugin and Go paths derive from one root while provenance preserves dedicated ttsc ownership versus external GOCACHE.
+ * @evidence contracts/common.md#clear-and-simple-design Root selection and Go override selection are separate helpers; the result carries paths with their ownership discriminant.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Workspace markers and environment overrides are supported configuration inputs rather than project-name exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain each payload and independent Go ownership, separated from tags under the documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path APIs anchor ttsc overrides; environment names use Windows case-insensitive lookup, and external GOCACHE preserves Go's supplied spelling and validation semantics.
+ * @evidence contracts/performance.md#efficient-algorithms Default discovery walks ancestor directories, reading each inspected manifest's bytes and snapshotting entries at the node_modules/.cache/ttsc layout levels; those entry populations are not capped or recursively traversed. Path processing depends on visited text, while Windows override lookup scans current environment names. Explicit root selection skips ancestor discovery; Go provenance selection still observes its overrides.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Shared workspace placement permits producer caches to be shared, but this path query coordinates neither completed nor in-flight computations and establishes no answer equivalence.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returning paths and provenance acquires no retained cache entry or handle.
+ */
+export function resolveSourceBuildCachePaths(
+  projectRoot: string,
+  cacheDir?: string,
+  env: NodeJS.ProcessEnv = process.env,
+): ITtscSourceBuildCachePaths {
+  const root = resolveSourceBuildCacheRoot(projectRoot, cacheDir, env);
+  const goBuild = resolveGoBuildCacheRoot(root, projectRoot, env);
+  return {
+    root,
+    pluginRoot: path.join(root, PLUGIN_CACHE_DIRNAME),
+    goBuildRoot: goBuild.root,
+    goBuildRootSource: goBuild.source,
+  };
+}
+
+const LOCAL_CACHE_PARENT_DIRNAME = ".cache";
+
+const PLUGIN_CACHE_DIRNAME = "plugins";
+
+// Directories whose presence marks a monorepo/workspace root, so every package
+// in the workspace can select one cache location. Reuse of a compiled plugin
+// still requires the build owner's key and artifact validity. `package.json`
+// with a `workspaces` field (yarn/npm/bun) is checked
+// separately in isWorkspaceRootDir.
+const WORKSPACE_ROOT_MARKER_FILES: readonly string[] = ["pnpm-workspace.yaml"];
+
+/**
+ * Resolve the cache root for one invocation.
+ *
+ * Priority:
+ *
+ * 1. Explicit `cacheDir` option (resolved relative to `projectRoot`);
+ * 2. `TTSC_CACHE_DIR` environment variable (relative to `projectRoot`);
+ * 3. `<workspaceRoot>/node_modules/.cache/ttsc` — project-local by default.
+ *
+ * There is no automatic global (`~/.cache`) fallback. Removing the selected
+ * workspace's node_modules reclaims its default cache; explicit and environment
+ * overrides may select storage elsewhere and keep their own lifetime.
+ */
+function resolveSourceBuildCacheRoot(
+  projectRoot: string,
+  cacheDir: string | undefined,
+  env: NodeJS.ProcessEnv,
+): string {
+  if (cacheDir) {
+    return path.resolve(projectRoot, cacheDir);
+  }
+  const configured = SidecarEnvironment.read(env, "TTSC_CACHE_DIR");
+  if (configured) {
+    // Anchor a relative TTSC_CACHE_DIR to the project root (not the process
+    // cwd) so a programmatic host whose cwd differs from the project still
+    // resolves — and later cleans — the same cache. Absolute values pass
+    // through path.resolve unchanged.
+    return path.resolve(projectRoot, configured);
+  }
+  return path.join(
+    resolveWorkspaceRoot(projectRoot),
+    SourceBuildCacheLayout.NODE_MODULES_DIRNAME,
+    LOCAL_CACHE_PARENT_DIRNAME,
+    SourceBuildCacheLayout.TTSC_CACHE_DIRNAME,
+  );
+}
+
+/**
+ * Resolve the monorepo/workspace root for `projectRoot` so packages can select
+ * the same default cache location. This query does not certify artifact reuse.
+ *
+ * Walks up from `projectRoot` and returns, in order of preference: the NEAREST
+ * ancestor that is a workspace root (holds `pnpm-workspace.yaml`, or a
+ * `package.json` with a `workspaces` field); else the nearest ancestor that
+ * contains an installation; else the outermost ttsc-only cache owner at or
+ * below the nearest ordinary package manifest, or `projectRoot` itself.
+ *
+ * A nonempty, unmarked ttsc-only `.cache/ttsc` payload is fallback cache
+ * evidence rather than an installation. Empty or marked ttsc roots remain
+ * installation evidence, including the interval before marker publication.
+ * Remembering the outermost fallback owner avoids choosing a nearer unmarked
+ * payload merely because it contains previously produced ttsc output.
+ *
+ * Nearest (not highest) so an unrelated ancestor that happens to declare
+ * `workspaces` — for example a `package.json` in the user's home directory —
+ * cannot override a nearer declared workspace root.
+ */
+function resolveWorkspaceRoot(projectRoot: string): string {
+  let dir = path.resolve(projectRoot);
+  let nearestNodeModulesOwner: string | null = null;
+  let outermostTtscCacheOwner: string | null = null;
+  let packageBoundarySeen = false;
+  for (;;) {
+    if (isWorkspaceRootDir(dir)) {
+      return dir;
+    }
+    const nodeModules = classifyNodeModulesBoundary(dir);
+    if (nearestNodeModulesOwner === null && nodeModules === "installation") {
+      nearestNodeModulesOwner = dir;
+    } else if (nodeModules === "ttsc-cache" && !packageBoundarySeen) {
+      outermostTtscCacheOwner = dir;
+    }
+    packageBoundarySeen ||= hasPackageManifest(dir);
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  return (
+    nearestNodeModulesOwner ??
+    outermostTtscCacheOwner ??
+    path.resolve(projectRoot)
+  );
+}
+
+/**
+ * Classify the evidence carried by `dir/node_modules`.
+ *
+ * An empty directory remains installation evidence for package managers and
+ * callers that materialize the root before populating it. The distinguished
+ * `ttsc-cache` shape is an ordinary `.cache/ttsc` layout with no sibling.
+ * Counting an unmarked legacy layout as an installation would let ttsc's output
+ * change its own workspace-root query. This is placement evidence, not proof of
+ * every descendant's ownership: selected cache owners validate their actual
+ * roots and entries before writes or deletion. Aliases and unreadable
+ * directories at the inspected layout levels remain installation evidence.
+ */
+function classifyNodeModulesBoundary(
+  dir: string,
+): "absent" | "installation" | "ttsc-cache" {
+  const nodeModules = path.join(
+    dir,
+    SourceBuildCacheLayout.NODE_MODULES_DIRNAME,
+  );
+  if (!fs.existsSync(nodeModules)) return "absent";
+  try {
+    if (fs.lstatSync(nodeModules).isSymbolicLink()) return "installation";
+    const entries = fs.readdirSync(nodeModules, { withFileTypes: true });
+    const cache = entries.length === 1 ? entries[0] : undefined;
+    if (!isOrdinaryDirectory(cache, LOCAL_CACHE_PARENT_DIRNAME)) {
+      return "installation";
+    }
+
+    const cacheEntries = fs.readdirSync(
+      path.join(nodeModules, LOCAL_CACHE_PARENT_DIRNAME),
+      { withFileTypes: true },
+    );
+    const ttsc = cacheEntries.length === 1 ? cacheEntries[0] : undefined;
+    if (!isOrdinaryDirectory(ttsc, SourceBuildCacheLayout.TTSC_CACHE_DIRNAME)) {
+      return "installation";
+    }
+    const ttscRoot = path.join(
+      nodeModules,
+      LOCAL_CACHE_PARENT_DIRNAME,
+      SourceBuildCacheLayout.TTSC_CACHE_DIRNAME,
+    );
+    if (
+      SourceBuildCacheLayout.isEmptyOrMarkedDefaultWorkspaceCacheRoot(ttscRoot)
+    ) {
+      return "installation";
+    }
+    return "ttsc-cache";
+  } catch {
+    return "installation";
+  }
+}
+
+/** Probe for the package boundary used by fallback discovery. */
+function hasPackageManifest(dir: string): boolean {
+  try {
+    return fs.statSync(path.join(dir, "package.json")).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** Match one named ordinary directory in a collected snapshot. */
+function isOrdinaryDirectory(
+  entry: fs.Dirent | undefined,
+  name: string,
+): boolean {
+  return entry?.name === name && entry.isDirectory() && !entry.isSymbolicLink();
+}
+
+/** Recognize a supported workspace declaration at one ancestor. */
+function isWorkspaceRootDir(dir: string): boolean {
+  for (const marker of WORKSPACE_ROOT_MARKER_FILES) {
+    if (fs.existsSync(path.join(dir, marker))) {
+      return true;
+    }
+  }
+  return packageJsonDeclaresWorkspaces(path.join(dir, "package.json"));
+}
+
+/** Recognize nonempty array and packages-array workspace declarations. */
+function packageJsonDeclaresWorkspaces(packageJsonPath: string): boolean {
+  let text: string;
+  try {
+    text = fs.readFileSync(packageJsonPath, "utf8");
+  } catch {
+    return false;
+  }
+  try {
+    const workspaces = (JSON.parse(text) as { workspaces?: unknown })
+      .workspaces;
+    // A real workspace root declares a NON-EMPTY package list (an array, or an
+    // object with a `packages` array). Ignore `false`, `[]`, `null`, or `{}` so
+    // a disabled or empty declaration on an unrelated ancestor cannot hijack
+    // the cache location.
+    if (Array.isArray(workspaces)) {
+      return workspaces.length > 0;
+    }
+    if (workspaces !== null && typeof workspaces === "object") {
+      const packages = (workspaces as { packages?: unknown }).packages;
+      return Array.isArray(packages) && packages.length > 0;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/** Select a Go object path together with cleanup-ownership provenance. */
+function resolveGoBuildCacheRoot(
+  root: string,
+  projectRoot: string,
+  env: NodeJS.ProcessEnv,
+): {
+  root: string;
+  source: ITtscSourceBuildCachePaths["goBuildRootSource"];
+} {
+  const dedicated = SidecarEnvironment.read(env, "TTSC_GO_CACHE_DIR");
+  if (dedicated) {
+    // Anchor a relative TTSC_GO_CACHE_DIR to the project root, matching
+    // TTSC_CACHE_DIR, so the build and a later `clean` from a different cwd
+    // agree on the directory. Absolute values pass through unchanged.
+    return {
+      root: path.resolve(projectRoot, dedicated),
+      source: "TTSC_GO_CACHE_DIR",
+    };
+  }
+  const external = SidecarEnvironment.read(env, "GOCACHE");
+  if (external && external.length > 0) {
+    return {
+      root: external,
+      source: "GOCACHE",
+    };
+  }
+  return {
+    root: path.join(root, SourceBuildCacheLayout.GO_BUILD_CACHE_DIRNAME),
+    source: "ttsc-cache",
+  };
+}

package/src/plugin/internal/source/selectPluginModuleReplaceDirectories.ts

@@ -0,0 +1,80 @@
+import path from "node:path";
+
+import type { IPluginModuleReplaceDirectory } from "./IPluginModuleReplaceDirectory";
+
+/**
+ * Select unversioned local replacement targets outside the observed physical
+ * module root, preserving Go's module identity and original target spelling.
+ *
+ * The caller supplies directives parsed by Go and its actual physical-path
+ * observer. This selection neither parses go.mod nor proves an observation's
+ * native identity. Internal targets, including observed aliases, stay in the
+ * module's own source population.
+ *
+ * @evidence contracts/common.md#principled-implementation Go-local path syntax admits only absolute or dot-relative unversioned targets; observed native containment separates the external population, and module/version sorting preserves the existing record order.
+ * @evidence contracts/common.md#clear-and-simple-design Directive filtering, original-root anchoring and physical containment form one internal selection operation; parsing and native observation remain supplied by the owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual parsed directives and observed paths drive selection, not a handwritten go.mod parser or fixture-specific module names.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies parsed-input and physical-observation premises and distinguishes internal source ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native path operations anchor relative targets and compare containment; Go dot-relative backslash syntax is accepted only on Windows as before. Supplied physical observations retain their owner's best-effort limitations.
+ * @evidence contracts/performance.md#efficient-algorithms All directive entries are visited; selected local targets require native path text work and delegated physical observation, followed by sorting returned module/version text. Observations can traverse ancestors and are not claimed constant.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This selection adds no historical directive or identity cache; the supplied observer and upstream source-key owner retain their existing reuse policies.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Selected records transfer to the caller; no native handle, child, task or historical population is retained by this operation.
+ */
+export function selectPluginModuleReplaceDirectories(
+  root: string,
+  replacements: readonly {
+    New?: { Path?: string; Version?: string };
+    Old?: { Path?: string; Version?: string };
+  }[],
+  physicalPath: (location: string) => string,
+): IPluginModuleReplaceDirectory[] {
+  const physicalRoot = physicalPath(root);
+  const out: IPluginModuleReplaceDirectory[] = [];
+  for (const replacement of replacements) {
+    const modulePath = replacement.Old?.Path;
+    const spelled = replacement.New?.Path;
+    if (
+      modulePath === undefined ||
+      spelled === undefined ||
+      replacement.New?.Version !== undefined ||
+      !isFilesystemPath(spelled)
+    )
+      continue;
+    const directory = physicalPath(path.resolve(root, spelled));
+    const relative = path.relative(physicalRoot, directory);
+    if (
+      relative !== ".." &&
+      !relative.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(relative)
+    )
+      continue;
+    out.push({
+      directory,
+      modulePath,
+      spelled,
+      ...(replacement.Old?.Version === undefined
+        ? {}
+        : { version: replacement.Old.Version }),
+    });
+  }
+  return out.sort((left, right) =>
+    left.modulePath === right.modulePath
+      ? (left.version ?? "") < (right.version ?? "")
+        ? -1
+        : 1
+      : left.modulePath < right.modulePath
+        ? -1
+        : 1,
+  );
+}
+
+/** Go local target syntax: absolute or dot-relative with native separators. */
+function isFilesystemPath(target: string): boolean {
+  return (
+    path.isAbsolute(target) ||
+    target.startsWith("./") ||
+    target.startsWith("../") ||
+    (process.platform === "win32" &&
+      (target.startsWith(".\\") || target.startsWith("..\\")))
+  );
+}

package/src/plugin/internal/source/spawnGoTool.ts

@@ -0,0 +1,204 @@
+import {
+  type SpawnSyncOptionsWithStringEncoding,
+  type SpawnSyncReturns,
+  type StdioOptions,
+  spawnSync,
+} from "node:child_process";
+import crypto from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import util from "node:util";
+
+import { captureProcessOutput } from "../../../compiler/internal/captureProcessOutput";
+import { E2ETrace } from "../../../internal/E2ETrace";
+import { OwnedSynchronousProcess } from "../../../internal/OwnedSynchronousProcess";
+import { spawnSyncResilient } from "../../../internal/spawnSyncResilient";
+import { GoToolResolution } from "./GoToolResolution";
+import { windowsGoCommandArgs } from "./windowsGoCommandArgs";
+
+/**
+ * Run a Go tool command synchronously and return its complete output.
+ *
+ * Output is captured through files rather than pipes, so no buffer ceiling can
+ * turn a verbose `go build` into a failure. On Windows a `.cmd` or `.bat`
+ * wrapper is run through a generated shim with exact argument quoting; a
+ * descriptor-exhaustion failure on POSIX is retried through the low-descriptor
+ * broker.
+ *
+ * @evidence contracts/common.md#principled-implementation Child streams are routed to owned files and then reconstructed as the normal SpawnSyncReturns shape; Windows wrappers receive one-pass environment expansion and native argv quoting rather than unsafe shell concatenation.
+ * @evidence contracts/common.md#clear-and-simple-design Output capture lifetime is separate from process selection and wrapper quoting; finally covers spawn failures and output-read failures alike.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts POSIX broker retry handles actual descriptor exhaustion and Windows cmd handles supported batch wrappers; neither changes a failed build into an assumed success.
+ * @evidence contracts/common.md#meaningful-documentation Native comments explain file capture, missing-wrapper ENOENT and the platform errno/quoting semantics; prose and tags remain distinct.
+ * @evidence contracts/portability.md#os-neutral-implementation Windows cmd wrappers are isolated with verbatim arguments and case-insensitive environment lookup; native binaries and POSIX go use Node spawning and the descriptor broker.
+ * @evidence contracts/performance.md#efficient-algorithms File capture avoids the pipe buffer ceiling but performs native acquisition/spawn/full output reads and decoding. Windows selection adds PATH/PATHEXT/native queries; wrapper environment/payload construction processes full argument/name bytes and regex quoting whose backtracking is not asserted linear here. Complete stdout/stderr strings and transient buffers/serialized argv data contribute memory beyond argument count.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Go commands can write build/module state and cannot share a result merely because executable and arguments match.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The call delegates file/descriptor acquisition to the capture owner and disposes it in finally; cleanup can fail and replace an earlier result/error. Returned decoded output belongs to the caller with no independent byte ceiling. Synchronous completion concerns the selected command, not proof that arbitrary inherited-handle descendants have terminated.
+ */
+export function spawnGoTool(
+  goBinary: string,
+  args: readonly string[],
+  options: SpawnSyncOptionsWithStringEncoding,
+): SpawnSyncReturns<string> {
+  // The child's streams go to files rather than pipes, so no output ceiling
+  // applies: `spawnSync` only bounds what it must hold in this process's
+  // memory, and a `go build` that says a great deal is not a failure to invent
+  // a limit for. See `captureProcessOutput`.
+  const capture = captureProcessOutput();
+  const spawnOptions = {
+    ...options,
+    stdio: ["ignore", capture.stdoutFd, capture.stderrFd] as StdioOptions,
+  };
+  try {
+    const result = spawnGoToolProcess(goBinary, args, spawnOptions, {
+      stderr: capture.stderrPath,
+      stdout: capture.stdoutPath,
+    });
+    const stdout = capture.read("stdout", "utf8") as string;
+    const stderr = capture.read("stderr", "utf8") as string;
+    return {
+      ...result,
+      output: [null, stdout, stderr],
+      stderr,
+      stdout,
+    };
+  } finally {
+    capture.dispose();
+  }
+}
+
+/**
+ * Launch the Go tool, routing through cmd.exe only where Windows needs a
+ * wrapper. Output routing is the caller's concern; this owns process
+ * selection.
+ */
+function spawnGoToolProcess(
+  goBinary: string,
+  args: readonly string[],
+  options: SpawnSyncOptionsWithStringEncoding,
+  output: { stderr: string; stdout: string },
+): ReturnType<typeof spawnSync> {
+  if (process.platform !== "win32") {
+    return spawnSyncResilient(goBinary, args, options, output);
+  }
+  const inheritedEnv = options.env ?? process.env;
+  const resolved = GoToolResolution.resolveWindowsGoTool(
+    goBinary,
+    inheritedEnv,
+    spawnWorkingDirectory(options.cwd),
+  );
+  if (!resolved.wrapper) {
+    const nativeArgs = [...args];
+    return E2ETrace.synchronous(
+      goBinary,
+      nativeArgs,
+      options,
+      "windows-go-tool",
+      () =>
+        OwnedSynchronousProcess.launch(goBinary, nativeArgs, options) ??
+        spawnSync(goBinary, nativeArgs, options),
+    );
+  }
+  // Supply the install-guidance ENOENT result when no regular wrapper candidate
+  // was selected, before cmd.exe becomes the actual child. Candidate stat
+  // failures do not distinguish every absence/permission cause. Node refuses to
+  // launch a `.cmd` or `.bat` without a shell (CVE-2024-27980) and answers
+  // EINVAL, which would hide that the file does not exist.
+  if (resolved.location === null) {
+    return missingGoTool(goBinary, args);
+  }
+  const shim = createWindowsGoCommandShim([resolved.location, ...args]);
+  const command =
+    GoToolResolution.readWindowsEnvironmentValue(inheritedEnv, "COMSPEC") ??
+    GoToolResolution.readWindowsEnvironmentValue(process.env, "COMSPEC") ??
+    "cmd.exe";
+  const commandArgs = windowsGoCommandArgs(shim.payload);
+  const trace = E2ETrace.begin(
+    command,
+    commandArgs,
+    options,
+    "windows-go-wrapper",
+  );
+  const wrapperOptions = {
+    ...options,
+    env: { ...inheritedEnv, ...shim.environment },
+    shell: false,
+    // The /c payload is already one fully quoted Windows command line.
+    windowsVerbatimArguments: true,
+  };
+  const result =
+    OwnedSynchronousProcess.launch(command, commandArgs, wrapperOptions) ??
+    spawnSync(command, commandArgs, wrapperOptions);
+  E2ETrace.result(trace, result);
+  return result;
+}
+
+/**
+ * Construct a no-process ENOENT-shaped result for unavailable wrapper
+ * selection. Errno comes from Node's system-error map; this is not a recorded
+ * native spawn failure proving the wrapper's exact absence/permission cause.
+ */
+function missingGoTool(
+  goBinary: string,
+  args: readonly string[],
+): ReturnType<typeof spawnSync> {
+  const error = Object.assign(new Error(`spawnSync ${goBinary} ENOENT`), {
+    code: "ENOENT",
+    errno: systemErrno("ENOENT"),
+    path: goBinary,
+    spawnargs: [...args],
+    syscall: `spawnSync ${goBinary}`,
+  });
+  return {
+    error,
+    output: [null, "", ""],
+    pid: 0,
+    signal: null,
+    status: null,
+    stderr: "",
+    stdout: "",
+  };
+}
+
+/** The platform errno Node reports for the named system error. */
+function systemErrno(name: string): number | undefined {
+  for (const [errno, [errorName]] of util.getSystemErrorMap()) {
+    if (errorName === name) return errno;
+  }
+  return undefined;
+}
+
+function spawnWorkingDirectory(
+  cwd: SpawnSyncOptionsWithStringEncoding["cwd"],
+): string {
+  if (cwd === undefined) return process.cwd();
+  return path.resolve(typeof cwd === "string" ? cwd : fileURLToPath(cwd));
+}
+
+/** Pass volatile cmd wrapper arguments through one-pass environment expansion. */
+function createWindowsGoCommandShim(args: readonly string[]): {
+  environment: NodeJS.ProcessEnv;
+  payload: string;
+} {
+  const prefix = `TTSC_GO_COMMAND_SHIM_${crypto
+    .randomBytes(8)
+    .toString("hex")
+    .toUpperCase()}_ARG_`;
+  const environment = Object.fromEntries(
+    args.map((arg, index) => [prefix + index, quoteWindowsCommandArg(arg)]),
+  );
+  return {
+    environment,
+    // cmd expands each placeholder exactly once. Percent-shaped text inside an
+    // expanded value is not scanned as a second environment reference.
+    payload: `"${args.map((_, index) => `%${prefix}${index}%`).join(" ")}"`,
+  };
+}
+
+/** Quote one argv value for the Windows command-line parser used by cmd. */
+function quoteWindowsCommandArg(arg: string): string {
+  return `"${String(arg)
+    .replace(/(\\*)"/g, '$1$1\\"')
+    .replace(/(\\*)$/, "$1$1")}"`;
+}

package/src/plugin/internal/source/touchPluginCacheEntryInUse.ts

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { SourceBuildCacheLayout } from "./SourceBuildCacheLayout";
+
+/**
+ * Mark the plugin cache entry holding `binary` as used now, when the binary
+ * lives in one.
+ *
+ * The cache's collector considers recent use when selecting its protected byte
+ * cohort; freshness is not an unconditional pin. A build or cache hit records a
+ * use. A long-lived consumer, such as a `ttsc --watch` session reusing its
+ * resident check plugins, runs the binary again and again without either, so
+ * its entry aged out and could be removed while the session still needed it to
+ * respawn a sidecar. The consumer records each cycle's use here instead. This
+ * improves its recency priority but does not give it ownership of a permanently
+ * retained binary. A binary outside the cache, whose directory carries no
+ * last-use record, is left alone.
+ *
+ * @param binary The plugin executable being used.
+ * @evidence contracts/common.md#principled-implementation An observed regular last-use marker selects the cache convention for refresh, rather than authenticating the binary or its producer. Atomic entry replacement avoids modifying an aliased marker inode; sequential checks do not pin the containing pathname.
+ * @evidence contracts/common.md#clear-and-simple-design The binary's containing entry is projected directly, with a marker-presence gate before publication.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The marker is authored cache provenance, not a filename exception for a particular plugin or consumer.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains resident-use refresh, the absent-marker boundary and tolerated refresh failures.
+ * @evidence contracts/portability.md#os-neutral-implementation Native dirname/join and metadata replacement handle platform paths; locked or missing files remain a tolerated refresh failure.
+ * @evidence contracts/performance.md#efficient-algorithms Containing-path construction, marker stat and atomic timestamp replacement use a fixed operation count without reading binary bytes; costs still include native path resolution and timestamp/pending-name text.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This helper does not validate the resident binary's build inputs or coordinate its production.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Refresh changes recency priority, not reader ownership or a storage bound. The collector owns eviction attempts and retained history; refresh failures are swallowed and atomic writer cleanup is best-effort. This operation retains no worker or handle.
+ */
+export function touchPluginCacheEntryInUse(binary: string): void {
+  const record = path.join(
+    path.dirname(binary),
+    SourceBuildCacheLayout.CACHE_LAST_USED_FILE,
+  );
+  try {
+    if (!fs.statSync(record).isFile()) return;
+    SourceBuildCacheLayout.replaceCacheMetadataFile(record, `${Date.now()}\n`);
+  } catch {
+    // Not a cache entry, or the record cannot be written: the use goes
+    // unrecorded, and a removed binary is rebuilt at the next resolution.
+  }
+}