ttsc 0.31.6 → 0.32.1

package/src/compiler/internal/compileProjectInMemory.ts

@@ -68,11 +68,13 @@ export function compileProjectInMemory(options: ITtscCompilerContext): {
     return compileProjectWithPlugins(options, cwd, project);
   }
   const tsconfig = project.path;
+  const env = inheritedSidecarEnv(options.env, options.binary);
   const binary = buildNativeCompiler({
     cacheBaseDir: project.root,
     cacheDir:
       options.cacheDir ??
       SidecarEnvironment.read(options.env, "TTSC_CACHE_DIR"),
+    env,
     packageRoot: packageRootDir(),
   });
   const res = spawnNative(
@@ -80,7 +82,7 @@ export function compileProjectInMemory(options: ITtscCompilerContext): {
     ["api-compile", "--cwd", project.root, "--tsconfig", tsconfig],
     {
       cwd: project.root,
-      env: inheritedSidecarEnv(options.env, options.binary),
+      env,
     },
   );
   if (res.error) {
@@ -110,7 +112,11 @@ function hasConfiguredPlugins(
   options: ITtscCompilerContext,
   project: ITtscParsedProjectConfig,
 ): boolean {
-  return hasProjectPluginEntries(project, options.plugins);
+  return hasProjectPluginEntries(
+    project,
+    options.plugins,
+    options.pluginConfigDir,
+  );
 }
 
 /**

package/src/compiler/internal/project/CompilerProjectSelection.ts

@@ -24,11 +24,11 @@ export namespace CompilerProjectSelection {
    * Resolve one compiler project without rebasing its original argument frame.
    *
    * Validated visible selectors retain their positions beside original response
-   * tokens. The existing observed inspector projects those frames for selection;
-   * the native producer still receives their original bytes and owns validation.
-   * Positional discovery starts at the supplied file until an observed project
-   * assignment selects another config. Explicit resolvedProject callers retain
-   * their independent API authority.
+   * tokens. The existing observed inspector projects those frames for
+   * selection; the native producer still receives their original bytes and owns
+   * validation. Positional discovery starts at the supplied file until an
+   * observed project assignment selects another config. Explicit
+   * resolvedProject callers retain their independent API authority.
    * Observations are sequential and do not pin bytes across a later producer.
    *
    * @evidence contracts/common.md#principled-implementation Existing schema occurrence metadata and observed response inspection establish ordered canonical project assignments; one selected config is returned separately from the retained compiler argument cwd.
@@ -49,7 +49,8 @@ export namespace CompilerProjectSelection {
     },
   ) {
     const cwd = path.resolve(options.cwd ?? process.cwd());
-    const file = options.file ??
+    const file =
+      options.file ??
       (options.files?.length === 1 ? options.files[0] : undefined);
     let initial = options.resolvedProject?.identity;
     let initialError: unknown;
@@ -117,7 +118,8 @@ export namespace CompilerProjectSelection {
     if (responseFrames.length !== 0 && inspectionError === undefined) {
       projectGuard = ["-p", project.path];
     } else if (
-      options.resolvedProject !== undefined && assignments.has("project")
+      options.resolvedProject !== undefined &&
+      assignments.has("project")
     ) {
       // A reporting/selection guard must not become a missing top-level scalar
       // operand. An unsafe native request retains its original diagnostic frame.
@@ -141,8 +143,8 @@ export namespace CompilerProjectSelection {
   }
 
   /**
-   * Reject a changed response generation before a consumer publishes or runs it.
-   * This is a sequential reobservation, not an atomic producer snapshot.
+   * Reject a changed response generation before a consumer publishes or runs
+   * it. This is a sequential reobservation, not an atomic producer snapshot.
    *
    * @evidence contracts/common.md#principled-implementation Current physical/content observations must match every response input admitted by this selection before its consumer proceeds.
    * @evidence contracts/common.md#clear-and-simple-design One loop delegates actual file observation to the existing owner and propagates read failures.
@@ -154,10 +156,7 @@ export namespace CompilerProjectSelection {
    * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous observation retains no handle or history; the selection belongs to its caller.
    */
   export function assertCurrent(
-    selection: Pick<
-      ReturnType<typeof read>,
-      "observations"
-    >,
+    selection: Pick<ReturnType<typeof read>, "observations">,
   ): void {
     for (const [file, observation] of selection.observations)
       if (CompilerArgumentsInspection.observeInputFile(file) !== observation)
@@ -169,7 +168,8 @@ export namespace CompilerProjectSelection {
   /**
    * Pin an established project only after the current forwarded frame is safe.
    * A phase may filter or extend argv after context acquisition; it must retain
-   * that live payload without letting a final flag satisfy an incomplete scalar.
+   * that live payload without letting a final flag satisfy an incomplete
+   * scalar.
    *
    * @evidence contracts/common.md#principled-implementation An unchanged observed frame reuses its admitted guard; changed phase arguments receive the existing conservative inspection before the selected project can be pinned.
    * @evidence contracts/common.md#clear-and-simple-design One guard reader preserves live argv and the context's selected project without duplicating option arity or response grammar.

package/src/compiler/internal/project/resolveOwningProjectConfig.ts

@@ -39,16 +39,21 @@ import { selectReferencedProject } from "./selectReferencedProject";
  * realpaths and case capabilities, retaining best-effort spelling when native
  * identity lookup is unavailable.
  *
- * Graph observations are shared only within this lookup. Later requests can see
- * changed configs, inherited options, directory membership or compiler inputs;
- * a config pathname alone cannot establish that the expansion is still valid.
- * The callback observes direct config reads, not every inherited config or
- * compiler input consulted by expansion. Synchronous compiler work has no
- * explicit execution deadline in this operation.
+ * Graph observations are shared only within this lookup, unless the caller
+ * hands in `expansions`, which keeps each config's expanded roots for as long
+ * as the caller keeps the map. Later requests can otherwise see changed
+ * configs, inherited options, directory membership or compiler inputs; a config
+ * pathname alone cannot establish that the expansion is still valid. A file
+ * created after a kept expansion was taken is still expanded for afresh. The
+ * callback observes direct config reads, not every inherited config or compiler
+ * input consulted by expansion. Synchronous compiler work has no explicit
+ * execution deadline in this operation.
  *
  * @param props.tsconfig - The config project discovery found for the file.
  * @param props.file - The file whose project is asked for.
  * @param props.binary - An explicit TypeScript-Go binary, when one was given.
+ * @param props.env - Complete environment shared by compiler selection and
+ *   root-file expansion; omission inherits the current process environment.
  * @param props.onConfig - Called with every config this reads, so a caller that
  *   fingerprints its inputs can record them.
  * @evidence contracts/common.md#principled-implementation Successful compiler showConfig supplies root membership observations, best-effort filesystem identity compares aliases, and visited identity keys terminate repeated graph states while declaration-order DFS selects the first observed containing project. Failed observations preserve the discovered fallback without certifying membership.
@@ -57,8 +62,8 @@ import { selectReferencedProject } from "./selectReferencedProject";
  * @evidence contracts/common.md#meaningful-documentation Native paragraphs state ownership order, fallback, callbacks and lookup-scoped reuse, with parameter explanations separated from acknowledgments.
  * @evidence contracts/portability.md#os-neutral-implementation Node path operations select native config spellings, actual filesystem identity compares target and roots, and spawnNative owns executable representation rather than applying OS-name case guesses.
  * @evidence contracts/performance.md#efficient-algorithms Each distinct observed config identity key is visited once in the DFS and receives at most one expansion plus one ctime-based retry; ctime can change for metadata updates as well as creation. Direct config reads/parsing, reference path text/stat work, delegated identity/case probes and binary selection precede or accompany compiler execution. Root-list decoding and membership scans cost their bytes and entries; DFS stack depth follows the reference chain and native recursion limits still apply. The no-reference path avoids a compiler subprocess, not config I/O.
- * @evidence contracts/performance.md#reuse-equivalent-work The lookup reuses discovered reference edges and filesystem identity observations; visited keys prevent expansion of a repeated observed identity, while later requests rerun because paths alone cannot prove unchanged inheritance, directory membership or compiler selection. Best-effort identity cannot guarantee deduplication of every physical alias.
- * @evidence contracts/performance.md#bound-retention-and-release-resources Identity maps, visited keys and root observations are lookup-local with no historical population retained here. Synchronous expansion delegates capture cleanup to spawnNative's finally path, whose cleanup failures are suppressed; output storage and child duration have no configured ceiling here. A nonterminating child prevents the lookup from finishing, rather than being released by this graph traversal.
+ * @evidence contracts/performance.md#reuse-equivalent-work The lookup reuses discovered reference edges and filesystem identity observations; visited keys prevent expansion of a repeated observed identity, while later requests rerun because paths alone cannot prove unchanged inheritance, directory membership or compiler selection, unless the caller keeps expansions for a lifetime its own builds already assume. Best-effort identity cannot guarantee deduplication of every physical alias.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Identity maps, visited keys and root observations are lookup-local; only a caller-supplied expansions map retains root lists, one per config, for the caller's lifetime. Synchronous expansion delegates capture cleanup to spawnNative's finally path, whose cleanup failures are suppressed; output storage and child duration have no configured ceiling here. A nonterminating child prevents the lookup from finishing, rather than being released by this graph traversal.
  */
 export function resolveOwningProjectConfig(props: {
   /** Absolute or invocation-relative spelling of the discovered config. */
@@ -73,8 +78,19 @@ export function resolveOwningProjectConfig(props: {
    */
   binary?: string;
 
+  /** Complete environment for compiler selection and root-file expansion. */
+  env?: NodeJS.ProcessEnv;
+
   /** Observe each directly read config, including ones with no reference edges. */
   onConfig?: (config: string) => void;
+
+  /**
+   * Expanded root files kept across lookups, by config path, for a caller whose
+   * selected builds and compiler environment already hold for the same
+   * lifetime: ttsx builds each owning project once per process
+   * (samchon/ttsc#1747).
+   */
+  expansions?: Map<string, { files: readonly string[]; takenAt: number }>;
 }): string {
   const discovered = path.resolve(props.tsconfig);
   const discoveredReferences = readReferences(discovered, props.onConfig);
@@ -108,14 +124,19 @@ export function resolveOwningProjectConfig(props: {
    * root observations.
    */
   function contains(config: string): boolean {
-    const roots = rootFiles(config, props.binary);
+    const roots = props.expansions?.get(config) ?? expand(config);
     if (listed(roots)) return true;
     // Recent ctime permits one retry after a miss; it can reflect a metadata
-    // change rather than creation and is not an atomic freshness proof.
-    return (
-      createdSince(props.file, roots.takenAt) &&
-      listed(rootFiles(config, props.binary))
-    );
+    // change rather than creation and is not an atomic freshness proof. A kept
+    // expansion taken before the file appeared is retried the same way.
+    return createdSince(props.file, roots.takenAt) && listed(expand(config));
+  }
+
+  /** Expand `config` now, and keep the expansion when the caller asked to. */
+  function expand(config: string): RootFiles {
+    const roots = rootFiles(config, props.binary, props.env);
+    props.expansions?.set(config, roots);
+    return roots;
   }
   return selectReferencedProject(discovered, discoveredReferences, {
     identity: (config) => identities.resolve(config).key,
@@ -199,14 +220,19 @@ interface RootFiles {
  * include approximation or permanent failed answer substitutes for compiler
  * behavior.
  */
-function rootFiles(config: string, binary: string | undefined): RootFiles {
+function rootFiles(
+  config: string,
+  binary: string | undefined,
+  env: NodeJS.ProcessEnv | undefined,
+): RootFiles {
   const takenAt = Date.now();
   let files: string[] = [];
   try {
     const directory = path.dirname(config);
-    const tsgo = resolveTsgo({ binary, cwd: directory });
+    const tsgo = resolveTsgo({ binary, cwd: directory, env });
     const result = spawnNative(tsgo.binary, ["-p", config, "--showConfig"], {
       cwd: directory,
+      env,
       encoding: "utf8",
     });
     if (result.status === 0) {

package/src/compiler/internal/readEffectiveCompilerOptions.ts

@@ -84,7 +84,7 @@ export function readEffectiveCompilerOptions(
     } catch {
       return null;
     }
-    const tsgo = resolveTsgo({ cwd: project.root, binary });
+    const tsgo = resolveTsgo({ cwd: project.root, binary, env });
     const result = spawnNative(
       tsgo.binary,
       ["-p", project.path, ...passthrough, "-p", project.path, "--showConfig"],

package/src/compiler/internal/resolveBinary.ts

@@ -29,7 +29,10 @@ import { SidecarEnvironment } from "./sharedHost/SidecarEnvironment";
  * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Resolution owns no persistent map, descriptor or task and returns only the selected path spelling.
  */
 export function resolveBinary(
-  opts: { env?: NodeJS.ProcessEnv } = {},
+  opts: {
+    /** Complete selection environment; omission reads the current process. */
+    env?: NodeJS.ProcessEnv;
+  } = {},
 ): string | null {
   const env = opts.env ?? process.env;
   const explicit = SidecarEnvironment.read(env, "TTSC_BINARY");

package/src/compiler/internal/resolveTsgo.ts

@@ -41,6 +41,13 @@ export function resolveTsgo(
 
     /** Directory from which to discover `typescript`. */
     cwd?: string;
+
+    /**
+     * Complete environment for executable selection; omission reads the current
+     * process environment. Public compiler owners merge caller overrides before
+     * invoking this resolver, retaining their original overlay for channel
+     * ownership.
+     */
     env?: NodeJS.ProcessEnv;
 
     /**

package/src/compiler/internal/runSingleFileEmit.ts

@@ -4,10 +4,12 @@ import path from "node:path";
 import { createCanonicalTempDirectory } from "../../internal/createCanonicalTempDirectory";
 import type { TtscSingleFileEmitOptions } from "../../structures/internal/TtscSingleFileEmitOptions";
 import { EmitOwnershipIndex } from "./EmitOwnershipIndex";
+import { WatchInputPublication } from "./build/WatchInputPublication";
 import { runBuild } from "./build/runBuild";
 import { CompilerProjectSelection } from "./project/CompilerProjectSelection";
 import { readProjectConfig } from "./project/readProjectConfig";
 import { readEffectiveCompilerOptions } from "./readEffectiveCompilerOptions";
+import { SidecarEnvironment } from "./sharedHost/SidecarEnvironment";
 
 /**
  * Emit one source file by building its project into a temporary directory.
@@ -20,10 +22,12 @@ import { readEffectiveCompilerOptions } from "./readEffectiveCompilerOptions";
  * failure propagates on success and is aggregated with an earlier operation
  * failure rather than replacing it.
  *
- * A launcher-supplied selection shares its project and original compiler argument
- * cwd with public output planning. Response freshness is checked before native
- * work and publication; these sequential checks do not pin bytes atomically.
- * Callers without that record retain explicit config/nearest-file discovery.
+ * A launcher-supplied selection shares its project and original compiler
+ * argument cwd with public output planning. Response freshness is checked
+ * before native work and publication; these sequential checks do not pin bytes
+ * atomically. Callers without that record retain explicit config/nearest-file
+ * discovery. Watch-input handlers must complete synchronously; use
+ * {@link runSingleFileEmit.async} for promise-returning handlers.
  *
  * @returns The transformed JavaScript source text.
  * @throws When the build exits non-zero, proves no JavaScript for the requested
@@ -43,107 +47,147 @@ export function runSingleFileEmit(
   options: TtscSingleFileEmitOptions,
   selection?: ReturnType<typeof CompilerProjectSelection.read>,
 ): string {
-  const cwd = path.resolve(options.cwd ?? process.cwd());
-  const sourceFile = realpathIfExists(
-    path.isAbsolute(options.file)
-      ? options.file
-      : path.resolve(cwd, options.file),
-  );
-  const project =
-    selection?.project ??
-    readProjectConfig({
-      cwd,
-      file: options.file,
-      projectRoot: options.projectRoot,
-      tsconfig: options.tsconfig,
-    });
-  const tsconfig = project.path;
-  const compilerArgsCwd = selection?.compilerArgsCwd ?? project.root;
-  if (selection !== undefined) CompilerProjectSelection.assertCurrent(selection);
-  // The root tsgo lays the outputs against: a `--rootDir` forwarded on the
-  // command line, which reaches it after the config; otherwise the declared
-  // one, which `readProjectConfig` already absolutized; otherwise the project's
-  // own directory, which `pinInferredRootDir` hands it below.
-  const effective = readEffectiveCompilerOptions(
-    project,
-    options.passthrough,
-    options.binary,
-    options.env,
-    compilerArgsCwd,
-  )?.("rootDir");
-  const rootDir =
-    typeof effective === "string"
-      ? path.resolve(compilerArgsCwd, effective)
-      : project.root;
-  if (selection !== undefined) CompilerProjectSelection.assertCurrent(selection);
-  const outDir = createCanonicalTempDirectory("ttsc-single-file-");
-  let failed = false;
-  let failure: unknown;
-  try {
-    const result = runBuild({
-      ...options,
-      cwd,
+  return WatchInputPublication.run(runSingleFileEmit.steps(options, selection));
+}
+
+/**
+ * Keep synchronous and awaited single-file emission on one temporary lifetime.
+ *
+ * @evidence contracts/common.md#principled-implementation Both entries share project/root selection, producing build, response freshness, provenance lookup and temporary-output cleanup; awaited completion joins every nested publication before compilation and output selection.
+ * @evidence contracts/common.md#clear-and-simple-design One generator owns project emission, optional public output and cleanup for both completion modes; the companion adds a runner without another output-selection implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Pending registration cannot authorize a build, and rejected publication reaches the same temporary cleanup path. Completion mode preserves response checks and provenance instead of reconstructing source ownership from filenames.
+ * @evidence contracts/common.md#meaningful-documentation Each entry states completion mode and the shared temporary lifetime; sequence prose requires rejection delivery into its finally path, while the primary entry documents output selection and cleanup failures.
+ * @evidence contracts/portability.md#os-neutral-implementation The shared sequence retains existing native source/output identity, cwd bases and private-directory handling across suspension without another native boundary.
+ * @evidence contracts/performance.md#efficient-algorithms One project selection and full-project build serve one provenance lookup; each handoff is awaited once with no additional source or output traversal.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each sequence owns fresh compiler effects rather than an output cache or shared generation; higher-level owners decide equivalent build reuse.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One accepted private output directory spans nested handoff and build work, and the existing finally path removes it on success or failure and preserves cleanup error aggregation.
+ */
+export namespace runSingleFileEmit {
+  /**
+   * Await watch-input registration before emitting and selecting one source's
+   * JavaScript. Rejected publication follows the same temporary cleanup path.
+   */
+  export function async(
+    options: TtscSingleFileEmitOptions,
+    selection?: ReturnType<typeof CompilerProjectSelection.read>,
+  ): Promise<string> {
+    return WatchInputPublication.runAsync(steps(options, selection));
+  }
+
+  /**
+   * Emit through one selected project while suspending at watch handoffs.
+   * Internal completion runners must deliver rejection into this sequence so
+   * its finally block retains temporary-output cleanup ownership.
+   */
+  export function* steps(
+    options: TtscSingleFileEmitOptions,
+    selection?: ReturnType<typeof CompilerProjectSelection.read>,
+  ): WatchInputPublication.Sequence<string> {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const sourceFile = realpathIfExists(
+      path.isAbsolute(options.file)
+        ? options.file
+        : path.resolve(cwd, options.file),
+    );
+    const project =
+      selection?.project ??
+      readProjectConfig({
+        cwd,
+        file: options.file,
+        projectRoot: options.projectRoot,
+        tsconfig: options.tsconfig,
+      });
+    const tsconfig = project.path;
+    const compilerArgsCwd = selection?.compilerArgsCwd ?? project.root;
+    if (selection !== undefined)
+      CompilerProjectSelection.assertCurrent(selection);
+    // The root tsgo lays the outputs against: a `--rootDir` forwarded on the
+    // command line, which reaches it after the config; otherwise the declared
+    // one, which `readProjectConfig` already absolutized; otherwise the project's
+    // own directory, which `pinInferredRootDir` hands it below.
+    const effective = readEffectiveCompilerOptions(
+      project,
+      options.passthrough,
+      options.binary,
+      SidecarEnvironment.merge(process.env, options.env),
       compilerArgsCwd,
-      emit: true,
-      forceEmitProvenance: true,
-      isolateOutputsTo: outDir,
-      outDir,
-      // The private temp directory above is an `outDir` this lane injected, not
-      // one the project declared, and tsgo answers an inferred common source
-      // directory with TS5011 as soon as any `outDir` is in play. Pinning the
-      // root tsgo would infer keeps `ttsc <file.ts>` working on a project that
-      // declares no output at all, while the producing invocation reports its
-      // actual source/output ownership separately.
-      pinInferredRootDir: true,
-      resolvedProject: project,
-      tsconfig,
-    });
-    if (result.status !== 0) {
-      throw new Error(
-        "ttsc single-file emit exited " +
-          result.status +
-          "\n" +
-          (result.stderr || result.stdout),
-      );
-    }
-    const emitted = new EmitOwnershipIndex({
-      emitDir: outDir,
-      rootDir,
-      emittedSources: result.emittedSources,
-      emittedSourceProofFailures: result.emittedSourceProofFailures,
-      outputs: EmitOwnershipIndex.listOutputs(outDir),
-    }).find(sourceFile);
-    if (emitted === null) {
-      throw new Error(
-        `ttsc single-file emit: ${tsconfig} emitted no JavaScript owned by ${sourceFile}; check that the project includes the source and its options permit JavaScript emission`,
-      );
-    }
-    const transformed = fs.readFileSync(emitted, "utf8");
-    if (selection !== undefined) CompilerProjectSelection.assertCurrent(selection);
-    if (options.out) {
-      const target = path.isAbsolute(options.out)
-        ? options.out
-        : path.resolve(cwd, options.out);
-      fs.mkdirSync(path.dirname(target), { recursive: true });
-      fs.writeFileSync(target, transformed, "utf8");
-    }
-    return transformed;
-  } catch (error) {
-    failed = true;
-    failure = error;
-    throw error;
-  } finally {
+    )?.("rootDir");
+    const rootDir =
+      typeof effective === "string"
+        ? path.resolve(compilerArgsCwd, effective)
+        : project.root;
+    if (selection !== undefined)
+      CompilerProjectSelection.assertCurrent(selection);
+    const outDir = createCanonicalTempDirectory("ttsc-single-file-");
+    let failed = false;
+    let failure: unknown;
     try {
-      fs.rmSync(outDir, { recursive: true, force: true });
-    } catch (cleanupError) {
-      if (failed) {
-        throw new AggregateError(
-          [failure, cleanupError],
-          "ttsc: single-file emission and temporary output cleanup failed",
-          { cause: failure },
+      const result = yield* runBuild.steps({
+        ...options,
+        cwd,
+        compilerArgsCwd,
+        emit: true,
+        forceEmitProvenance: true,
+        isolateOutputsTo: outDir,
+        outDir,
+        // The private temp directory above is an `outDir` this lane injected, not
+        // one the project declared, and tsgo answers an inferred common source
+        // directory with TS5011 as soon as any `outDir` is in play. Pinning the
+        // root tsgo would infer keeps `ttsc <file.ts>` working on a project that
+        // declares no output at all, while the producing invocation reports its
+        // actual source/output ownership separately.
+        pinInferredRootDir: true,
+        resolvedProject: project,
+        tsconfig,
+      });
+      if (result.status !== 0) {
+        throw new Error(
+          "ttsc single-file emit exited " +
+            result.status +
+            "\n" +
+            (result.stderr || result.stdout),
         );
       }
-      throw cleanupError;
+      const emitted = new EmitOwnershipIndex({
+        emitDir: outDir,
+        rootDir,
+        emittedSources: result.emittedSources,
+        emittedSourceProofFailures: result.emittedSourceProofFailures,
+        outputs: EmitOwnershipIndex.listOutputs(outDir),
+      }).find(sourceFile);
+      if (emitted === null) {
+        throw new Error(
+          `ttsc single-file emit: ${tsconfig} emitted no JavaScript owned by ${sourceFile}; check that the project includes the source and its options permit JavaScript emission`,
+        );
+      }
+      const transformed = fs.readFileSync(emitted, "utf8");
+      if (selection !== undefined)
+        CompilerProjectSelection.assertCurrent(selection);
+      if (options.out) {
+        const target = path.isAbsolute(options.out)
+          ? options.out
+          : path.resolve(cwd, options.out);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, transformed, "utf8");
+      }
+      return transformed;
+    } catch (error) {
+      failed = true;
+      failure = error;
+      throw error;
+    } finally {
+      try {
+        fs.rmSync(outDir, { recursive: true, force: true });
+      } catch (cleanupError) {
+        if (failed) {
+          throw new AggregateError(
+            [failure, cleanupError],
+            "ttsc: single-file emission and temporary output cleanup failed",
+            { cause: failure },
+          );
+        }
+        throw cleanupError;
+      }
     }
   }
 }

package/src/compiler/internal/startResidentTransform.ts

@@ -62,7 +62,10 @@ export function startResidentTransform(
     tsconfig: context.tsconfig,
   });
   const loaded = loadProjectPlugins({
-    binary: resolveBinary(context) ?? "",
+    binary:
+      resolveBinary({
+        env: SidecarEnvironment.merge(process.env, context.env),
+      }) ?? "",
     cacheDir:
       context.cacheDir ??
       SidecarEnvironment.read(context.env, "TTSC_CACHE_DIR"),
@@ -85,7 +88,11 @@ export function startResidentTransform(
   assertSharedHostCompatibility(transformers, "source-to-source");
 
   const host = selectSharedHostPlugin(transformers);
-  const tsgoBinary = resolveTsgo({ ...context, cwd: project.root }).binary;
+  const tsgoBinary = resolveTsgo({
+    ...context,
+    cwd: project.root,
+    env: SidecarEnvironment.merge(process.env, context.env),
+  }).binary;
   const resident = new ResidentTransformProcess({
     args: [
       "serve",

package/src/compiler/internal/transformProjectInMemory.ts

@@ -109,7 +109,10 @@ export function transformProjectInMemory(options: ITtscCompilerContext): {
 } {
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const loaded = loadProjectPlugins({
-    binary: resolveBinary(options) ?? "",
+    binary:
+      resolveBinary({
+        env: SidecarEnvironment.merge(process.env, options.env),
+      }) ?? "",
     cacheDir:
       options.cacheDir ??
       SidecarEnvironment.read(options.env, "TTSC_CACHE_DIR"),
@@ -188,11 +191,13 @@ function transformProjectWithNativeHost(
     baseline?.hostInputs ?? [],
     projectHostInputs,
   );
+  const env = inheritedSidecarEnv(options.env);
   const binary = buildNativeCompiler({
     cacheBaseDir: project.root,
     cacheDir:
       options.cacheDir ??
       SidecarEnvironment.read(options.env, "TTSC_CACHE_DIR"),
+    env,
     packageRoot: packageRootDir(),
   });
   const res = spawnNative(
@@ -200,7 +205,7 @@ function transformProjectWithNativeHost(
     ["api-transform", "--cwd", project.root, "--tsconfig", project.path],
     {
       cwd: project.root,
-      env: inheritedSidecarEnv(options.env),
+      env,
     },
   );
   if (res.error) {
@@ -295,7 +300,11 @@ function transformProjectWithPlugins(
   const tsgoBinary =
     loaded.nativePlugins.length === 0
       ? ""
-      : resolveTsgo({ ...options, cwd: project.root }).binary;
+      : resolveTsgo({
+          ...options,
+          cwd: project.root,
+          env: SidecarEnvironment.merge(process.env, options.env),
+        }).binary;
   const checked = runNativeChecks(
     options,
     project,

package/src/compiler/internal/transformProjectInWorker.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { Worker } from "node:worker_threads";
 
 import { CompilerContextSnapshot } from "../../internal/CompilerContextSnapshot";
+import { workerModuleUrl } from "../../internal/workerModuleUrl";
 import type { ITtscCompilerContext } from "../../structures/ITtscCompilerContext";
 import type { TransformProjectWorkerReply } from "./TransformProjectWorkerReply";
 import type { TransformProjectWorkerRequest } from "./TransformProjectWorkerRequest";
@@ -50,7 +51,7 @@ import type { transformProjectInMemory } from "./transformProjectInMemory";
  * @evidence contracts/common.md#clear-and-simple-design The public operation owns checkout, exclusive event listeners and return to the idle pool; two private helpers isolate idle-worker retirement from active request settlement.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts Blocking work runs in a supported worker boundary rather than rewriting the caller's environment around synchronous work; failures preserve real exceptions and do not substitute measured or expected results.
  * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why all transform phases move off-thread, environment isolation, warm reuse and retained-population limits following the documentation skill.
- * @evidence contracts/portability.md#os-neutral-implementation Worker entry is a native path and the environment snapshot uses native name identity; Windows worker copies are case-sensitive, so canonical merging prevents aliases from defeating caller overrides inside the worker.
+ * @evidence contracts/portability.md#os-neutral-implementation A supported module URL requires the native CommonJS source or emitted worker entry while Node retains inherited execution options and preload hooks. The environment snapshot uses native name identity; Windows worker copies are case-sensitive, so canonical merging prevents aliases from defeating caller overrides inside the worker.
  * @evidence contracts/performance.md#efficient-algorithms Pool checkout removes one entry and listeners; environment merge and plugin JSON serialization visit caller data before structured cloning, whose cost includes context, serialized payload and environment bytes. Caller JSON conversion can add arbitrary work. Idle-worker retirement searches/compacts at most the pool budget; worker startup and native transform costs remain delegated, and output cloning is transport work rather than a second transform.
  * @evidence contracts/performance.md#reuse-equivalent-work An exclusively checked-out warm worker reuses the loader's input-validated caches; each request adopts its complete current environment and still executes the transform, so thread reuse is not an unsupported response cache.
  * @evidence contracts/performance.md#bound-retention-and-release-resources At most the module-initialization CPU budget remains in the idle pool with event-loop references removed. Excess/failed workers receive unawaited termination requests; retiring native threads are not covered by the reusable-entry count. Terminal settlement removes active listeners, while pooled module caches retain their owning data policy. Active requests and live transforms have no concurrency cap or implicit deadline.
@@ -65,7 +66,14 @@ export function transformProjectInWorker(
   };
   const worker =
     takeIdleWorker() ??
-    new Worker(path.join(__dirname, "transformProjectWorker.js"));
+    new Worker(
+      workerModuleUrl(
+        path.join(
+          __dirname,
+          `transformProjectWorker${path.extname(__filename)}`,
+        ),
+      ),
+    );
   worker.ref();
   return new Promise((resolve, reject) => {
     let settled = false;

package/src/flags/ParseOptions.ts

@@ -29,8 +29,8 @@ export interface ParseOptions {
   readonly errorPrefix: string;
 
   /**
-   * Observe a validated launcher assignment at its compiler-frame position.
-   * The canonical schema name and parsed value retain alias/value semantics;
+   * Observe a validated launcher assignment at its compiler-frame position. The
+   * canonical schema name and parsed value retain alias/value semantics;
    * passthroughIndex counts compiler tokens already forwarded at this point.
    * Exceptions propagate from the caller's observer.
    *