ttsc 0.30.3 → 0.31.0

package/src/launcher/internal/runtime/interopProbe.ts

@@ -0,0 +1,8 @@
+/**
+ * An empty CommonJS module that `RuntimeLoaderCapabilities` imports from ESM to
+ * read the namespace shape this runtime gives an imported CommonJS module.
+ *
+ * It must stay free of side effects and exports: only the names the runtime
+ * adds on its own, such as `module.exports`, may appear in that namespace.
+ */
+export {};

package/src/launcher/internal/runtime/isLocalProcessGone.ts

@@ -0,0 +1,67 @@
+import os from "node:os";
+
+/**
+ * Whether the process an owner record names has certainly exited: it ran on
+ * this host, and no process with its pid is alive.
+ *
+ * A record from another host proves nothing, because its pid names a process
+ * this machine cannot see, so it is never reported gone. An `EPERM` from the
+ * probe does not establish absence, so it counts as alive. Only `ESRCH` proves
+ * absence; other probe failures remain unknown. A recycled pid makes the answer
+ * err toward "alive": a caller that reclaims on "gone" never takes a live
+ * owner's state.
+ *
+ * Callers supply a validated positive process id, not a process-group selector.
+ * Hostname comparison is a host-label convention, not machine authentication:
+ * shared-cache participants need distinct labels under this comparison. ESRCH
+ * is an observation at probe time, not a lease preventing later state changes.
+ * An optional diagnostic receives this same observation without another probe;
+ * a diagnostic failure cannot change the ownership decision.
+ *
+ * @evidence contracts/common.md#principled-implementation Reclamation requires both the recorded local hostname and ESRCH from the native pid probe; permission, invalid-pid and unknown failures cannot establish that an owner is gone.
+ * @evidence contracts/common.md#clear-and-simple-design One conservative predicate supplies the same owner-liveness decision to lock recovery and directory sweeping.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native process existence is queried through process.kill(pid, 0); no fixture pid or broad error-to-dead fallback substitutes for ownership evidence.
+ * @evidence contracts/common.md#meaningful-documentation The native explanation distinguishes a remote host, a denied or unknown probe and pid recycling, stating why ambiguity protects a live owner's state.
+ * @evidence contracts/portability.md#os-neutral-implementation Node exposes the host's process-existence probe and portable error codes; hostname comparison scopes pid identity to this host without assuming POSIX signals can terminate Windows processes.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This observation retains no handle, historical state or cache; temporary lowercase hostname strings become reclaimable after return.
+ * @evidence contracts/performance.md#efficient-algorithms Native hostname lookup and two lowercase string constructions/comparison process host-label text before at most one native pid probe; the fixed probe count is not a fixed text or operating-system cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Host labels and native process existence are current observations; this predicate coordinates no cross-call cache or reusable liveness proof.
+ */
+export function isLocalProcessGone(
+  owner: {
+    /** The process id the owner recorded. */
+    pid: number;
+
+    /** The `os.hostname()` of the machine the owner ran on. */
+    hostname: string;
+  },
+  observe?: (
+    result: "remote" | "present" | "absent" | "unknown",
+    errorCode?: string,
+  ) => void,
+): boolean {
+  const report = (
+    result: "remote" | "present" | "absent" | "unknown",
+    errorCode?: string,
+  ): void => {
+    try {
+      observe?.(result, errorCode);
+    } catch {
+      // Diagnostics own no policy.
+    }
+  };
+  if (owner.hostname.toLowerCase() !== os.hostname().toLowerCase()) {
+    report("remote");
+    return false;
+  }
+  try {
+    process.kill(owner.pid, 0);
+    report("present");
+    return false;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException | null)?.code;
+    const absent = code === "ESRCH";
+    report(absent ? "absent" : "unknown", code);
+    return absent;
+  }
+}

package/src/launcher/internal/runtime/observeMappedDescriptorResolution.ts

@@ -0,0 +1,74 @@
+import { RESOLUTION_INPUT_RECORDER_PATH } from "../../../plugin/internal/load/RESOLUTION_INPUT_RECORDER_PATH";
+
+/**
+ * Observe mapped descriptor candidates across one actual resolution window.
+ *
+ * Both the public resolve hook and owned CommonJS resolver use this operation.
+ * The shared recorder captures declared targets before Node resolves, narrows
+ * those earlier observations to the actual selection and revalidates them at
+ * settlement. Missing proof becomes an unstable record, never a later hash.
+ * Metadata witnesses transfer with content and physical identity; reporting
+ * does not read the filesystem again to recreate a withdrawn observation.
+ *
+ * @evidence contracts/common.md#principled-implementation Shared pre-resolution content, physical and metadata observations remain authoritative through settlement. Any unavailable or contradictory proof emits unstable=true, preserving the existing runtime reader's monotone refusal.
+ * @evidence contracts/common.md#clear-and-simple-design One mapped observation operation serves both runtime callers while their relative and bare policies remain unchanged; the shared recorder owns candidate expansion and selected-root narrowing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Node still selects the actual module. This operation delegates observation to the shared recorder and neither reimplements imports resolution nor replaces foreign methods or cache protocols.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states capture, narrowing, metadata transfer and missing-proof behavior, with caller-owned activation and resolution separate from reporting.
+ * @evidence contracts/portability.md#os-neutral-implementation Shared native path, file-URL and metadata operations determine selected candidates and physical identities without an OS-specific resolver rule.
+ * @evidence contracts/performance.md#efficient-algorithms Pre/post/final observations include candidate and manifest expansion, native metadata and complete file bytes. Result/signature copies and returned records scale with this one window's inputs; no historical recorder population is rescanned.
+ * @evidence contracts/performance.md#reuse-equivalent-work Reporting transfers already-captured content, physical and metadata proof without another native observation. Each mutable resolution window receives its own recorder rather than sharing stale witnesses.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One closure retains only this window's recorder until settlement and release; synchronous observations retain no handle. Result records transfer to the caller, with uncapped candidate/path/byte costs and no global history.
+ */
+export function observeMappedDescriptorResolution(
+  specifier: string,
+  parent: string,
+  extensions: readonly string[],
+): {
+  commit(selected: string | undefined): {
+    resolved: string;
+    hash?: string | null;
+    realpath?: string | null;
+    signature?: string;
+    unstable?: boolean;
+  }[];
+} {
+  const recorder = RECORDER.createResolutionInputRecorder({ extensions });
+  const token = recorder.beginResolution(specifier, parent);
+  return {
+    commit(selected) {
+      recorder.endResolution(token, selected);
+      const result = recorder.finish();
+      const signatures = recorder.metadataSignatures();
+      return result.inputs.map((resolved) => {
+        if (
+          !result.complete ||
+          !Object.hasOwn(result.hashes, resolved) ||
+          !Object.hasOwn(result.realpaths, resolved) ||
+          !Object.hasOwn(signatures, resolved)
+        )
+          return { resolved, unstable: true };
+        return {
+          resolved,
+          hash: result.hashes[resolved],
+          realpath: result.realpaths[resolved],
+          signature: signatures[resolved],
+        };
+      });
+    },
+  };
+}
+
+/** The existing shared recorder, loaded once for its implementation. */
+const RECORDER = require(RESOLUTION_INPUT_RECORDER_PATH) as {
+  createResolutionInputRecorder(options: { extensions: readonly string[] }): {
+    beginResolution(specifier: string, parent: string): unknown;
+    endResolution(token: unknown, selected: string | undefined): void;
+    finish(): {
+      complete: boolean;
+      inputs: string[];
+      hashes: Record<string, string | null>;
+      realpaths: Record<string, string | null>;
+    };
+    metadataSignatures(): Record<string, string>;
+  };
+};

package/src/launcher/internal/runtime/projectModuleOptions.ts

@@ -0,0 +1,28 @@
+import type { OwningModuleOptions } from "./OwningModuleOptions";
+
+/**
+ * Copy the declared string module and target from resolved compiler options.
+ * Missing or non-string values stay absent so format selection applies its own
+ * compiler defaults.
+ *
+ * @evidence contracts/common.md#principled-implementation String-only projection preserves declared values and absence for the two inputs that determine emit format; unrelated or invalid option values do not masquerade as a format declaration.
+ * @evidence contracts/common.md#clear-and-simple-design One small projection keeps build metadata independent of the full compiler-options object and leaves format policy with RuntimeModuleFormat.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No consumer-specific default or guessed module mode substitutes for the resolved owning-project options.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains rejected value shapes and why absence is retained rather than repeating the two member names.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The projection returns a caller-owned two-field value and retains no configuration history, handle or task.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This fixed two-property string-shape projection chooses no traversal, index or processing strategy; format policy remains with RuntimeModuleFormat.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The projection owns no cross-request computation coordinator or configuration invalidation cache.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Module and target strings are compiler-format options, not native path, process identity or capability representations; native file/package classification belongs to the format consumer.
+ */
+export function projectModuleOptions(
+  compilerOptions: Record<string, unknown>,
+): OwningModuleOptions {
+  return {
+    ...(typeof compilerOptions.module === "string"
+      ? { module: compilerOptions.module }
+      : {}),
+    ...(typeof compilerOptions.target === "string"
+      ? { target: compilerOptions.target }
+      : {}),
+  };
+}

package/src/launcher/internal/runtime/readDependencyCache.ts

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+
+import { DependencyBuildGeneration } from "./DependencyBuildGeneration";
+import { RuntimeEmitProvenance } from "./RuntimeEmitProvenance";
+import { projectModuleOptions } from "./projectModuleOptions";
+
+/**
+ * Reuse a dependency another process (or an earlier import) already built.
+ *
+ * The marker selects one generation, then a separate native walk checks for
+ * JavaScript presence. With cooperative publication, noncolliding ids and
+ * retained immutable generations, replacement builds leave the previous
+ * marker's directory available until marker replacement. These sequential reads
+ * do not pin an artifact snapshot or authenticate its current bytes.
+ *
+ * Unreadable, malformed or incomplete markers are cache misses and leave
+ * rebuilding to the dependency-build owner.
+ *
+ * Markers without the producer's emit-provenance record shape are historical
+ * misses even when output filenames resemble the requested source. Shape
+ * validation preserves supplied observations; it does not authenticate their
+ * producer or establish current artifact integrity.
+ *
+ * @evidence contracts/common.md#principled-implementation Metadata and provenance shape checks select one JavaScript-bearing generation under cooperative publication/retention premises; malformed or legacy records are misses without reconstructing membership from filenames or authenticating supplied observations.
+ * @evidence contracts/common.md#clear-and-simple-design Marker decoding, generation selection and the built-project result form one read boundary; module-option projection and physical identity use their shared owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing historical module, output or emitted-source fields trigger owning rebuild rather than guessing emit format or reconstructing source membership from a stem.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish sequential marker/presence reads and cooperative publication from artifact or producer authentication, and explain historical misses and root context.
+ * @evidence contracts/portability.md#os-neutral-implementation Native fs and generation path construction preserve platform spelling; the source root uses the shared filesystem-identity resolver with its documented best-effort fallback.
+ * @evidence contracts/performance.md#efficient-algorithms Reading/parsing costs uncapped marker bytes; output and provenance checks process entries and native path text. The early-exit emit walk costs visited entries/listings/name/path text and active recursion listings/depth. Root resolution adds delegated identity-context/native case observations; no fixed metadata-check count bounds that work.
+ * @evidence contracts/performance.md#reuse-equivalent-work The caller supplies the computed cache directory; ensureProjectBuilt memoizes success/failure by that directory, including selected compiler identity, while a miss reaches build admission. This reader validates current marker shape and presence each invocation but does not independently authenticate producer records, immutable retention or the caller's cache-key equivalence.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Marker text, decoded metadata, validation pairs and native-walk/context temporaries are call-local; returned arrays/records escape to the caller's build cache. Synchronous reads retain no handle here, while the caller owns cached metadata and generation storage lifetime; this reader imposes no historical quota or artifact-release policy.
+ */
+export function readDependencyCache(
+  cacheDir: string,
+  metaPath: string,
+): DependencyBuildGeneration.BuiltProject | null {
+  let meta: DependencyBuildGeneration.DependencyCacheMeta;
+  try {
+    meta = JSON.parse(
+      fs.readFileSync(metaPath, "utf8"),
+    ) as DependencyBuildGeneration.DependencyCacheMeta;
+  } catch {
+    return null;
+  }
+  if (
+    meta === null ||
+    typeof meta !== "object" ||
+    Array.isArray(meta) ||
+    !DependencyBuildGeneration.isDependencyGeneration(meta.generation) ||
+    typeof meta.rootDir !== "string" ||
+    // A marker with no `moduleOptions` object predates this field and cannot
+    // say which format its emit carries. Treating the absence as "no options"
+    // would classify a CommonJS emit as an ES module, so the generation is
+    // rejected and rebuilt instead. Every marker this version writes carries
+    // the object, empty or not.
+    typeof meta.moduleOptions !== "object" ||
+    meta.moduleOptions === null ||
+    Array.isArray(meta.moduleOptions) ||
+    (meta.moduleOptions.module !== undefined &&
+      typeof meta.moduleOptions.module !== "string") ||
+    (meta.moduleOptions.target !== undefined &&
+      typeof meta.moduleOptions.target !== "string") ||
+    !Array.isArray(meta.outputs) ||
+    !meta.outputs.every((output) => typeof output === "string") ||
+    !RuntimeEmitProvenance.isRecord(meta.emittedSources)
+  ) {
+    return null;
+  }
+  const emitDir = DependencyBuildGeneration.dependencyGenerationDir(
+    cacheDir,
+    meta.generation,
+  );
+  if (!DependencyBuildGeneration.emittedAnything(emitDir)) {
+    return null;
+  }
+  return {
+    emitDir,
+    outputs: meta.outputs,
+    emittedSources: meta.emittedSources,
+    emittedSourceProofFailures: meta.emittedSourceProofFailures,
+    moduleOptions: projectModuleOptions(
+      meta.moduleOptions as Record<string, unknown>,
+    ),
+    // Resolve source-root context through the shared native identity owner.
+    // Exact source ownership comes from captured emittedSources, not this
+    // root's spelling or a reconstruction of the output layout.
+    rootDir: DependencyBuildGeneration.resolvePhysicalPath(meta.rootDir),
+  };
+}

package/src/launcher/internal/runtime/realPath.ts

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+
+/**
+ * Best-effort physical lookup using the launcher's native realpath preference.
+ *
+ * Prefer `realpathSync.native`, falling back to the ordinary API only when the
+ * native entry point is unavailable. Using the same lookup preference aligns
+ * successful link and short-name observations rather than manufacturing a
+ * second spelling policy; separate queries still observe their current paths.
+ *
+ * On a failed lookup the input is retained. That fallback is a serving or
+ * lookup spelling, not proven authority for recursive cleanup.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful native realpath aligns hook paths with launcher identity, including Windows short names; failed resolution explicitly preserves the input without claiming physical identity.
+ * @evidence contracts/common.md#clear-and-simple-design One best-effort resolver shares the runtime's successful-path spelling rule and keeps cleanup's stricter ownership boundary elsewhere.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No OS-label case folding or path-name exception substitutes for filesystem resolution; the documented unresolved fallback does not authorize deletion.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain native short-name normalization and the limit of failed resolution, following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation fs.realpathSync.native resolves native links and Windows 8.3 spelling; the ordinary API fallback preserves supported hosts without assuming a universal filesystem case rule.
+ * @evidence contracts/performance.md#efficient-algorithms One realpath request avoids an explicit directory-wide source search, but native path/text/link resolution and latency are not bounded by that call count. Caught failure returns the supplied spelling without an additional probe.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Links and paths may change; this lookup owns no stable invalidation identity and does not cache a previous filesystem result.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous path query retains no descriptor, task or historical mapping.
+ */
+export function realPath(target: string): string {
+  try {
+    return fs.realpathSync.native?.(target) ?? fs.realpathSync(target);
+  } catch {
+    return target;
+  }
+}

package/src/launcher/internal/runtime/reclaimDependencyBuildLock.ts

@@ -0,0 +1,27 @@
+import type { DependencyBuildLockFence } from "./DependencyBuildLockFence";
+import { DependencyBuildLockProtocol } from "./DependencyBuildLockProtocol";
+
+/**
+ * Retire exactly the generation carried by an abandoned observation. Returns
+ * false when that generation is no longer the held one.
+ *
+ * @evidence contracts/common.md#principled-implementation Delegating the observation's generation to fenced retirement prevents a stale recovery attempt from moving a successor's current directory.
+ * @evidence contracts/common.md#clear-and-simple-design This recovery adapter accepts a fence rather than acquisition authority and keeps the retirement algorithm in the shared protocol.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No unconditional recursive deletion or timeout-only removal substitutes for generation-fenced retirement.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states exact-generation recovery and the false result when ownership changed.
+ * @evidence contracts/portability.md#os-neutral-implementation Native rename behavior and contention handling remain in the shared retirement owner; the adapter preserves the caller's native lock path.
+ * @evidence contracts/performance.md#efficient-algorithms The field projection adds constant adapter work to actual generation/path text and native retirement/probe/retry/yield cost. It does not scan holder or tombstone history; delegated contention can still grow total call work.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Reclaim is an ownership-changing effect; a prior result cannot authorize another generation's recovery.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Successful retirement transfers current into its tombstone; false or native failure does not certify recovery. Historical tombstones remain until container removal, and native peer-handle waiting/probe cleanup have no independent bounded completion here.
+ */
+export function reclaimDependencyBuildLock(
+  lockDir: string,
+  fence: DependencyBuildLockFence,
+): boolean {
+  return DependencyBuildLockProtocol.retireDependencyBuildLock(
+    lockDir,
+    fence.generation,
+  );
+}

package/src/launcher/internal/runtime/releaseDependencyBuildLock.ts

@@ -0,0 +1,27 @@
+import type { DependencyBuildLockLease } from "./DependencyBuildLockLease";
+import { DependencyBuildLockProtocol } from "./DependencyBuildLockProtocol";
+
+/**
+ * Retire a held generation during the holder's `finally`. Returns false when
+ * the lease was already retired or no longer holds current.
+ *
+ * @evidence contracts/common.md#principled-implementation The acquired lease supplies the exact retirement generation, so a late finalizer cannot release a successor after recovery.
+ * @evidence contracts/common.md#clear-and-simple-design The holder adapter uses the same fenced retirement owner as reclaim while accepting the distinct acquisition token.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Release preserves the generation fence instead of deleting whichever directory occupies the shared current name.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies finally ownership and explains false after retirement or replacement.
+ * @evidence contracts/portability.md#os-neutral-implementation Native lock-path representation and platform rename semantics stay with the shared protocol implementation.
+ * @evidence contracts/performance.md#efficient-algorithms The field projection delegates one retirement without a history scan; actual generation/path text, native mkdir/rename/sibling probes and peer-handle retry/yield work remain part of this call's cost and can grow with contention.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Release is a generation-specific ownership effect rather than a reusable computation.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Successful retirement moves current into its retained tombstone; false and native failures do not certify release. Peer-handle waiting has no separate deadline and probe-cleanup failures can retain artifacts; container cleanup owns historical state.
+ */
+export function releaseDependencyBuildLock(
+  lockDir: string,
+  lease: DependencyBuildLockLease,
+): boolean {
+  return DependencyBuildLockProtocol.retireDependencyBuildLock(
+    lockDir,
+    lease.generation,
+  );
+}

package/src/launcher/internal/runtime/resolveRuntimeCleanTargets.ts

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { E2ETrace } from "../../../internal/E2ETrace";
+import { SourceBuildCacheLayout } from "../../../plugin/internal/source/SourceBuildCacheLayout";
+import { ProcessOwnedDirectory } from "./ProcessOwnedDirectory";
+
+/**
+ * What `ttsc clean` removes of a cache root's ttsx runtime directory.
+ *
+ * The runtime directory holds one directory per prepared run, owned by the
+ * processes of that run (`ProcessOwnedDirectory`). A run still in progress
+ * keeps its directory, which clean reports instead of removing. Every other
+ * entry whose owners are all provably gone goes. A run without an owner record
+ * may still belong to an older executable that does not use the lock, so it is
+ * kept alongside live and unreadable owners. When nothing is kept, the whole
+ * runtime directory goes.
+ *
+ * Call while holding `withRuntimeDirectoryLock` for this runtime root, so a new
+ * cooperating run cannot appear between inspection and removal. Physical
+ * spelling and the cooperative lock do not pin native objects or authenticate
+ * owner records against independent mutation.
+ *
+ * @param cacheRoot The resolved cache root.
+ * @returns The directories to remove, and the run directories kept.
+ * @evidence contracts/common.md#principled-implementation Under the root lock, only provably abandoned owner sets become removal targets; live, unknown and unowned runs are preserved, and the physical run index pins external targets before unlinking an empty runtime tree.
+ * @evidence contracts/common.md#clear-and-simple-design The function plans targets and kept runs without performing deletion, separating ownership classification from the clean command's removal effects. Optional observations report the same scan/probe and selected branch to the existing private writer; selection is not a removal receipt.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No unreadable-owner or legacy unowned run is treated as abandoned merely to make clean remove more directories; physical target selection corrects alias identity rather than compensating with lexical retries.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain kept ownership, the required lock and whole-tree removal, with parameters and return fields documented following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native realpath pins a linked run index; path joins retain host spelling and ProcessOwnedDirectory uses conservative local process evidence instead of OS-name case or signal assumptions.
+ * @evidence contracts/performance.md#efficient-algorithms One native realpath/listing and one delegated ownership scan per run process E entries plus owner filenames/JSON bytes, host labels and native process observations. Native path text and IO latency are additional costs; returned target/kept strings scale with listed entries and their path bytes, not only entry count.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Ownership can change between clean invocations; the caller's held lock validates only this plan, not a reusable historical plan.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The call returns a removal plan and closes synchronous reads; the clean command owns deletion, and live processes retain their own run resources.
+ */
+export function resolveRuntimeCleanTargets(cacheRoot: string): {
+  /** Run directories protected by live, unknown or absent ownership evidence. */
+  kept: string[];
+
+  /** Pinned abandoned targets, followed by the runtime tree when none is kept. */
+  targets: string[];
+} {
+  const runtime = path.join(
+    cacheRoot,
+    SourceBuildCacheLayout.RUNTIME_CACHE_DIRNAME,
+  );
+  const runs = path.join(
+    runtime,
+    SourceBuildCacheLayout.RUNTIME_PROJECT_DIRNAME,
+  );
+  let entries: string[];
+  let physicalRuns: string;
+  try {
+    // The run index can be reached through a junction. Record its current
+    // physical spelling so a later index retarget alone does not redirect
+    // planned children; this is not a pinned native object handle.
+    physicalRuns = fs.realpathSync.native(runs);
+    entries = fs.readdirSync(physicalRuns);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return { kept: [], targets: [runtime] };
+    }
+    throw error;
+  }
+  const kept: string[] = [];
+  const removable: string[] = [];
+  for (const entry of entries) {
+    const directory = path.join(physicalRuns, entry);
+    const observe = E2ETrace.runtimeCleanup(directory, runtime, "runtime-clean-selection");
+    observe?.("selection-started");
+    let ownership: ReturnType<typeof ProcessOwnedDirectory.ownership>;
+    try {
+      ownership = ProcessOwnedDirectory.ownership(directory, false,
+        observe === undefined ? undefined : (observation) =>
+          observe("owner-observation", undefined, undefined, observation));
+    } catch (cause) {
+      observe?.("selection-failed", undefined, cause);
+      throw cause;
+    }
+    observe?.("ownership", ownership);
+    if (ownership !== "abandoned") kept.push(directory);
+    else removable.push(directory);
+    observe?.(ownership === "abandoned" ? "removal-selected" : "retention-selected", ownership);
+  }
+  return {
+    kept,
+    // Remove pinned external run targets before removing a runtime link. A
+    // whole-tree removal alone would only unlink the index and strand those
+    // abandoned generations in its old physical target.
+    targets: kept.length === 0 ? [...removable, runtime] : removable,
+  };
+}

package/src/launcher/internal/runtime/restoreStrippedNodeBuiltinScheme.ts

@@ -0,0 +1,32 @@
+import { isBuiltin } from "node:module";
+
+import type { ResolveResult } from "./ResolveResult";
+
+/**
+ * Restore a `node:` builtin URL when affected Node releases return the exact
+ * prefix-stripped spelling from their synchronous CommonJS resolver.
+ *
+ * Every other result passes through unchanged. In particular, a user hook that
+ * intentionally remaps a `node:` specifier to another URL retains ownership of
+ * that mapping, while ordinary and ESM builtin results already carrying the
+ * scheme avoid an unnecessary copy.
+ *
+ * @evidence contracts/common.md#principled-implementation Restoration requires a real builtin, an explicit node: request and the exact stripped result; any other mapping remains owned by the resolver that produced it.
+ * @evidence contracts/common.md#clear-and-simple-design One result adapter isolates the documented synchronous CommonJS scheme difference without rerunning resolution or duplicating builtin tables.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The compatibility path addresses an actual supported Node result shape through isBuiltin; it neither overrides intentional user remaps nor patches a foreign resolver.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain exact restoration scope, user-hook ownership and unchanged ESM/builtin results.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returns the supplied result or one shallow copy and retains nothing.
+ * @evidence contracts/performance.md#efficient-algorithms Builtin lookup and prefix/sliced-text equality observe the supplied specifier and URL text; restoration allocates one shallow result copy, observing its enumerable fields. There is no recursive filesystem scan or retained result memo.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A pure function of its two arguments with nothing to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Compares specifier and URL strings and checks isBuiltin; it builds no path and touches no filesystem.
+ */
+export function restoreStrippedNodeBuiltinScheme(
+  specifier: string,
+  result: ResolveResult,
+): ResolveResult {
+  return isBuiltin(specifier) &&
+    specifier.startsWith("node:") &&
+    result.url === specifier.slice("node:".length)
+    ? { ...result, url: specifier }
+    : result;
+}

package/src/launcher/internal/runtime/runtimeRunKey.ts

@@ -0,0 +1,31 @@
+import crypto from "node:crypto";
+
+/**
+ * This process's run key, which names the runtime directories it prepares: the
+ * process id, so a person reading the cache can tell which process a directory
+ * belongs to, followed by a nonce.
+ *
+ * A process id alone names a directory another run may hold too. A process of
+ * another host sharing the cache root can have the same id, and a later process
+ * given the id of one that was killed would claim the directory a sweep is
+ * removing as abandoned (`ProcessOwnedDirectory.sweep`). The nonce lowers this
+ * collision risk; a finite random identifier cannot guarantee uniqueness. The
+ * memoized key belongs to this loaded module instance. Another instance or
+ * worker can own another key even when Node reports the same process id.
+ *
+ * @returns The same key for every call to this module instance.
+ * @evidence contracts/common.md#principled-implementation Combining the diagnostic pid with a random 64-bit nonce distinguishes successive and cross-host runs that may share a pid; the identifier is probabilistic rather than a security credential.
+ * @evidence contracts/common.md#clear-and-simple-design One module-local lazy value supplies its callers' run identity without caller-specific naming schemes.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Cryptographic randomness avoids a pid-only identity policy without certifying collision absence; the pid remains explanatory metadata rather than globally unique authority.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain shared-host/recycled-pid collision risk and finite randomness, and state module-instance stability without promising process-wide singleton identity.
+ * @evidence contracts/performance.md#efficient-algorithms One eight-byte native random draw, hex encoding and native pid text initialize a fixed-size identifier; entropy acquisition can fail or add native latency. Cached access returns its stored string without another draw.
+ * @evidence contracts/performance.md#reuse-equivalent-work Preparations using this loaded module share its identity; a new module instance obtains its own nonce rather than trusting a recycled pid alone.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One identifier remains per loaded module instance for its lifetime; repeated calls do not grow that slot, while module-instance populations and named-directory reclamation belong to their owners.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The reported pid is explanatory scalar text beside random hex, not a process-liveness or filesystem-identity authority. Native path construction, ownership probes and process lifecycle remain with callers.
+ */
+export function runtimeRunKey(): string {
+  key ??= `${process.pid}-${crypto.randomBytes(8).toString("hex")}`;
+  return key;
+}
+
+let key: string | undefined;

package/src/launcher/internal/runtime/selectRuntimePluginPolicy.ts

@@ -0,0 +1,28 @@
+import type { RuntimeManifest } from "./RuntimeManifest";
+
+/**
+ * Select the plugin policy shared by runtime project and isolated-root builds.
+ * Descriptor evaluation disables plugins to prevent recursive self-hosting. A
+ * run that disabled them retains that policy for every subsequently loaded
+ * project, independent of which manifest supplied its runtime cache.
+ *
+ * @evidence contracts/common.md#principled-implementation Descriptor evaluation or any manifest with plugins false selects disabled loading; otherwise the owning project's ordinary discovery remains available.
+ * @evidence contracts/common.md#clear-and-simple-design One pure selection owns the same policy for project builds, isolated roots and their cache identity; runtime observation stays with the hook owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit run and evaluator policy determine selection without recognizing plugin names, replacing module methods or manufacturing successful builds.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain evaluator recursion and the inherited run policy across project boundaries, with inputs documented beside the signature.
+ * @evidence contracts/performance.md#efficient-algorithms Descriptor evaluation exits immediately; ordinary selection scans at most M manifest policy fields and stops on the first disabled one without copying inputs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This predicate selects current supplied policy; the build coordinator includes its result in the generation key before admitting reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Supplied manifests remain caller-owned and no history, process or handle is retained.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The body selects only the supplied descriptor boolean and manifest plugins discriminant; native project paths, runtime environment reads and build execution belong to the caller, not this predicate.
+ */
+export function selectRuntimePluginPolicy(
+  /** Build manifests already admitted to the current runtime. */
+  manifests: readonly Pick<RuntimeManifest, "plugins">[],
+  /** Whether this invocation evaluates a plugin descriptor. */
+  descriptorLoad: boolean,
+): false | undefined {
+  return descriptorLoad ||
+    manifests.some((manifest) => manifest.plugins === false)
+    ? false
+    : undefined;
+}