ttsc 0.30.3 → 0.31.0

package/lib/launcher/internal/runTtsc.js

@@ -3,33 +3,64 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PendingResidentCheckWatchChanges = void 0;
 exports.runTtsc = runTtsc;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const TtscCompiler_1 = require("../../TtscCompiler");
-const readProjectConfig_1 = require("../../compiler/internal/project/readProjectConfig");
+const ResidentCheckWatchSession_1 = require("../../compiler/internal/build/ResidentCheckWatchSession");
+const runBuild_1 = require("../../compiler/internal/build/runBuild");
+const CompilerProjectSelection_1 = require("../../compiler/internal/project/CompilerProjectSelection");
 const resolveProjectConfig_1 = require("../../compiler/internal/project/resolveProjectConfig");
-const runBuild_1 = require("../../compiler/internal/runBuild");
 const runSingleFileEmit_1 = require("../../compiler/internal/runSingleFileEmit");
-const parser_1 = require("../../flags/parser");
-const schema_1 = require("../../flags/schema");
+const SidecarEnvironment_1 = require("../../compiler/internal/sharedHost/SidecarEnvironment");
+const getString_1 = require("../../flags/getString");
+const parseFlags_1 = require("../../flags/parseFlags");
+const resolveFlagSpec_1 = require("../../flags/resolveFlagSpec");
+const E2ETrace_1 = require("../../internal/E2ETrace");
+const cacheEntryExists_1 = require("../../internal/cacheEntryExists");
+const createFilesystemPathIdentityContext_1 = require("../../internal/pathIdentity/createFilesystemPathIdentityContext");
+const isFilesystemPathIdentityWithin_1 = require("../../internal/pathIdentity/isFilesystemPathIdentityWithin");
+const resolvePhysicalPath_1 = require("../../internal/pathIdentity/resolvePhysicalPath");
 const resolveSafeCacheCleanupTargets_1 = require("../../internal/resolveSafeCacheCleanupTargets");
-const buildSourcePlugin_1 = require("../../plugin/internal/buildSourcePlugin");
-const assertNoSolutionBuild_1 = require("./assertNoSolutionBuild");
+const SourceBuildCacheLayout_1 = require("../../plugin/internal/source/SourceBuildCacheLayout");
+const legacyGlobalCacheTargets_1 = require("../../plugin/internal/source/legacyGlobalCacheTargets");
+const resolveCleanTargets_1 = require("../../plugin/internal/source/resolveCleanTargets");
+const resolveSourceBuildCachePaths_1 = require("../../plugin/internal/source/resolveSourceBuildCachePaths");
+const PendingResidentCheckWatchChanges_1 = require("./PendingResidentCheckWatchChanges");
 const getCompilerVersionText_1 = require("./getCompilerVersionText");
+const parseTtscBuildArgs_1 = require("./parseTtscBuildArgs");
+const prepareTtscBuildMode_1 = require("./prepareTtscBuildMode");
 const resolveCacheDir_1 = require("./resolveCacheDir");
-const singleFileOutput_1 = require("./singleFileOutput");
-const watchTopology_1 = require("./watchTopology");
+const resolveSingleFileOutput_1 = require("./resolveSingleFileOutput");
+const resolveRuntimeCleanTargets_1 = require("./runtime/resolveRuntimeCleanTargets");
+const withRuntimeDirectoryLock_1 = require("./runtime/withRuntimeDirectoryLock");
+const WatchTopology_1 = require("./watch/WatchTopology");
 /**
- * CLI entry point for `ttsc`. Dispatches argv to the appropriate build lane
- * (build, check, fix, format, prepare, clean, or native-delegate) and returns
- * an exit code. Errors thrown by any lane are caught here and written to stderr
- * so the process can exit cleanly.
+ * CLI entry point for `ttsc`. Dispatches argv to the appropriate lane (build,
+ * check, fix, format, cache, prepare, clean, help or version) and returns an
+ * exit code. Synchronous lane errors are caught here and reported to stderr; an
+ * error thrown by reporting itself can still escape this entry.
+ *
+ * Watch setup returns before its asynchronous first build finishes. Signal
+ * shutdown and supported Node IPC stop requests await the resident close and
+ * active cycle promises before reporting the latest completed build status.
+ * Their settlement is not a descendant-process or inherited-stdio drain proof.
+ * Topology failure initiates cleanup, whose asynchronous failure is reported
+ * separately. Cache cleanup validates its full target set against the project
+ * and caller's Go cache before removal; this is not an atomic filesystem
+ * transaction against concurrent path replacement.
  *
  * @param argv - Command-line arguments (defaults to `process.argv.slice(2)`).
- * @returns The exit code: `0` on success, `1` on binary-not-found, `2` on user
- *   error or build failure.
+ * @returns The selected lane's status, or `2` for an error caught by this
+ *   entry.
+ * @evidence contracts/common.md#principled-implementation Command and schema identities select the declared build, check, edit and cache lanes; emit tri-state and ordered passthrough values preserve compiler authority. Cleanup prevalidates the complete target population and protected physical identities before removals, without atomic replacement or rollback guarantees.
+ * @evidence contracts/common.md#clear-and-simple-design One public entry owns dispatch and reporting; private argument, cleanup, single-file and watch operations isolate their distinct lifecycles while sharing the package's flag and build owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Command names and debounce timing are declared CLI policy, not consumer-specific answers; completed build statuses are reported while entry exceptions map to 2 and process exit normalization remains explicit. Reuse validity belongs to maintained source-build owners rather than an assumed historical binary.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish synchronous dispatch from watch lifetime and explain cleanup authority; parameter and result descriptions are separated from acknowledgments following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native cwd resolution and physical identities anchor reporting, cache containment and deletion; environment lookup preserves native name identity, and process/watch behavior is delegated to supported package boundaries rather than shell commands.
+ * @evidence contracts/performance.md#efficient-algorithms Dispatch copies argv tails and delegates parsing, project/plugin discovery, compiler/process work, native identity queries and cache traversal/deletion; these have input-byte/path/dependency and delegated callback costs beyond token cursors. Cleanup deduplicates accepted paths; watch adds topology discovery, fingerprinting and serialized rebuild work, not a fixed total-work bound.
+ * @evidence contracts/performance.md#reuse-equivalent-work A watch lifetime retains one resident check coordinator and forwards ordered change deltas; topology changes reset that selection, while ordinary effectful builds remain separate and source-built binaries reuse only their validated input identity.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Watch retains uncapped input/topology/pending-change state and callbacks across cycles. Close marks closed, removes owned timers/listeners, attempts topology cleanup and awaits resident/active settlements; cleanup rejection is reported, not successful backend/descendant closure certification. Returned setup status does not end this lifetime; cache target/identity/output collections are call-local and uncapped.
  */
 function runTtsc(argv = process.argv.slice(2)) {
     try {
@@ -42,7 +73,7 @@ function runTtsc(argv = process.argv.slice(2)) {
         // falling through to the build lane where nothing reads it back out.
         // `resolveFlagSpec` ignores dash-less tokens, so the bare `help` / `version`
         // subcommand words below keep their own meaning.
-        const leadingFlag = (0, schema_1.resolveFlagSpec)(command)?.name;
+        const leadingFlag = (0, resolveFlagSpec_1.resolveFlagSpec)(command)?.name;
         switch (leadingFlag ?? command) {
             case "--help":
             case "help":
@@ -95,41 +126,12 @@ function isBuildAlias(command) {
 }
 function runCompatibleBuild(argv, mode) {
     const checkOnly = mode !== "build";
-    const options = normalizeBuildOptions(parseBuildArgs(argv));
-    if (mode === "fix") {
-        if (options.emit === true) {
-            throw new Error("ttsc: fix and --emit are mutually exclusive");
-        }
-        options.fix = true;
-        options.emit = false;
-    }
-    if (mode === "format") {
-        if (options.emit === true) {
-            throw new Error("ttsc: format and --emit are mutually exclusive");
-        }
-        options.format = true;
-        options.emit = false;
-    }
-    if (options.watch) {
-        if (mode === "fix") {
-            throw new Error("ttsc: fix does not support watch mode; use ttsc --noEmit --watch for incremental checks");
-        }
-        if (mode === "format") {
-            throw new Error("ttsc: format does not support watch mode; use ttsc --noEmit --watch for incremental checks");
-        }
+    const options = (0, prepareTtscBuildMode_1.prepareTtscBuildMode)(normalizeBuildOptions((0, parseTtscBuildArgs_1.parseTtscBuildArgs)(argv)), mode);
+    if (options.watch)
         return runWatch(options, checkOnly);
-    }
-    const buildOptions = checkOnly ? { ...options, emit: false } : options;
-    if (buildOptions.files.length !== 0) {
-        if (mode === "fix") {
-            throw new Error("ttsc: fix requires a project, not single-file mode");
-        }
-        if (mode === "format") {
-            throw new Error("ttsc: format requires a project, not single-file mode");
-        }
-        return runSingleFile(buildOptions);
-    }
-    const result = (0, runBuild_1.runBuild)(buildOptions);
+    if (options.files.length !== 0)
+        return runSingleFile(options);
+    const result = (0, runBuild_1.runBuild)(options);
     if (result.stdout)
         process.stdout.write(result.stdout);
     if (result.stderr)
@@ -173,6 +175,21 @@ function runClean(argv) {
     const explicitCacheDir = options.cacheDir
         ? node_path_1.default.resolve(cwd, options.cacheDir)
         : undefined;
+    if (explicitCacheDir !== undefined) {
+        return runCleanWithContext(cwd, projectRoot, explicitCacheDir, false);
+    }
+    const runtimeRoot = node_path_1.default.join((0, resolveSourceBuildCachePaths_1.resolveSourceBuildCachePaths)(projectRoot).root, SourceBuildCacheLayout_1.SourceBuildCacheLayout.RUNTIME_CACHE_DIRNAME);
+    return (0, cacheEntryExists_1.cacheEntryExists)(runtimeRoot)
+        ? (0, withRuntimeDirectoryLock_1.withRuntimeDirectoryLock)(runtimeRoot, () => runCleanWithContext(cwd, projectRoot, undefined, true))
+        : runCleanWithContext(cwd, projectRoot, undefined, false);
+}
+/** Resolve and remove the complete safe target set inside the runtime lock. */
+function runCleanWithContext(cwd, projectRoot, explicitCacheDir, includeRuntime) {
+    // The runtime directories of runs no process still owns. A run that may
+    // still be in progress keeps its own, and is reported.
+    const runtime = includeRuntime && explicitCacheDir === undefined
+        ? (0, resolveRuntimeCleanTargets_1.resolveRuntimeCleanTargets)((0, resolveSourceBuildCachePaths_1.resolveSourceBuildCachePaths)(projectRoot).root)
+        : { kept: [], targets: [] };
     const targets = explicitCacheDir
         ? // Explicit `ttsc clean --cache-dir X`: the user names X as the cache to
             // remove for this command, so remove it wholesale plus the legacy
@@ -185,35 +202,50 @@ function runClean(argv) {
         : // Default / TTSC_CACHE_DIR: remove only ttsc-owned subdirectories (a
             // possibly-shared root is never deleted) plus the pre-0.17 machine-global
             // cache so upgraders reclaim that disk.
-            [...(0, buildSourcePlugin_1.resolveCleanTargets)(projectRoot), ...(0, buildSourcePlugin_1.legacyGlobalCacheTargets)()];
+            [
+                ...(0, resolveCleanTargets_1.resolveCleanTargets)(projectRoot),
+                ...runtime.targets,
+                ...(0, legacyGlobalCacheTargets_1.legacyGlobalCacheTargets)(),
+            ];
     // Check the complete deletion set before removing the first directory. An
     // environment-selected TTSC_GO_CACHE_DIR and a legacy-global cache can be as
     // destructive as an explicit --cache-dir when either equals or contains the
     // project through its lexical spelling or a filesystem alias.
-    const safeTargets = (0, resolveSafeCacheCleanupTargets_1.resolveSafeCacheCleanupTargets)(projectRoot, targets);
+    const providedGoCache = SidecarEnvironment_1.SidecarEnvironment.read(process.env, "GOCACHE")?.trim();
+    const protectedDirectories = providedGoCache === undefined ||
+        providedGoCache.length === 0 ||
+        providedGoCache === "off"
+        ? []
+        : [node_path_1.default.resolve(projectRoot, providedGoCache)];
+    // Every lane, including explicit and legacy/runtime candidates, preserves
+    // the caller's Go cache even when a ttsc-owned spelling overlaps it.
+    const safeTargets = (0, resolveSafeCacheCleanupTargets_1.resolveSafeCacheCleanupTargets)(projectRoot, targets, {}, protectedDirectories);
     const removed = [];
     const visited = new Set();
     for (const target of safeTargets) {
         if (visited.has(target.path))
             continue;
         visited.add(target.path);
-        if (!target.exists || !node_fs_1.default.existsSync(target.path))
+        if (!target.exists || !(0, cacheEntryExists_1.cacheEntryExists)(target.path))
             continue;
         node_fs_1.default.rmSync(target.path, { recursive: true, force: true });
         removed.push(target.requestedPath);
     }
-    if (removed.length === 0) {
+    if (removed.length === 0 && runtime.kept.length === 0) {
         process.stdout.write(`ttsc: no cache directories found under ${projectRoot}\n`);
-        return 0;
     }
     for (const target of removed) {
         process.stdout.write(`ttsc: removed ${formatProjectPath(cwd, target)}\n`);
     }
+    for (const directory of runtime.kept) {
+        process.stdout.write(`ttsc: kept ${formatProjectPath(cwd, directory)}: a run that may still be in progress owns it\n`);
+    }
     return 0;
 }
 function runCache(argv) {
     const [command, ...rest] = argv;
-    switch (command) {
+    const leadingFlag = command === undefined ? undefined : (0, resolveFlagSpec_1.resolveFlagSpec)(command)?.name;
+    switch (leadingFlag ?? command) {
         case "paths":
             return runCachePaths(rest);
         case "-h":
@@ -233,13 +265,18 @@ function runCachePaths(argv) {
     const cwd = node_path_1.default.resolve(options.cwd ?? process.cwd());
     const cacheDir = (0, resolveCacheDir_1.resolveCacheDir)(cwd, options.cacheDir);
     const projectRoot = resolveCleanProjectRoot(cwd, options.tsconfig);
-    const paths = (0, buildSourcePlugin_1.resolveSourceBuildCachePaths)(projectRoot, cacheDir);
+    const paths = (0, resolveSourceBuildCachePaths_1.resolveSourceBuildCachePaths)(projectRoot, cacheDir);
+    const identities = (0, createFilesystemPathIdentityContext_1.createFilesystemPathIdentityContext)();
+    const rootIdentity = identities.resolve(paths.root);
+    const goIdentity = identities.resolve(paths.goBuildRoot);
     // Legacy combined roots retained for JSON compatibility. `requiredRoots`
     // identifies the compiled binaries that skip cold builds;
     // `acceleratorRoots` separately identifies the optional Go object cache.
     const cacheableRoots = [
         paths.root,
-        ...((0, buildSourcePlugin_1.isPathWithin)(paths.goBuildRoot, paths.root) ? [] : [paths.goBuildRoot]),
+        ...((0, isFilesystemPathIdentityWithin_1.isFilesystemPathIdentityWithin)(rootIdentity.key, goIdentity.key)
+            ? []
+            : [paths.goBuildRoot]),
     ];
     const requiredRoots = [paths.pluginRoot];
     const acceleratorRoots = [paths.goBuildRoot];
@@ -273,11 +310,23 @@ function runCachePaths(argv) {
 }
 function parseCachePathsArgs(argv) {
     const out = { json: false };
-    const rest = [...argv];
-    while (rest.length !== 0) {
-        const token = rest.shift();
+    let index = 0;
+    const readValue = (flag, inlineValue) => {
+        if (inlineValue !== undefined)
+            return inlineValue;
+        const value = argv[index++];
+        if (value === undefined) {
+            throw new Error(`ttsc: ${flag} requires a value`);
+        }
+        if (value.startsWith("-")) {
+            throw new Error(`ttsc: ${flag} requires a value (next token ${JSON.stringify(value)} starts with "-")`);
+        }
+        return value;
+    };
+    while (index < argv.length) {
+        const token = argv[index++];
         const [rawFlag, inlineValue] = splitInlineFlag(token);
-        const flag = (0, schema_1.resolveFlagSpec)(rawFlag);
+        const flag = (0, resolveFlagSpec_1.resolveFlagSpec)(rawFlag);
         if (flag?.subcommands.includes("cache") !== true) {
             throw new Error(`ttsc: cache paths does not support ${JSON.stringify(token)}`);
         }
@@ -289,13 +338,13 @@ function parseCachePathsArgs(argv) {
                 out.json = true;
                 break;
             case "--cache-dir":
-                out.cacheDir = readCachePathsValue(flag.name, inlineValue, rest);
+                out.cacheDir = readValue(flag.name, inlineValue);
                 break;
             case "--cwd":
-                out.cwd = readCachePathsValue(flag.name, inlineValue, rest);
+                out.cwd = readValue(flag.name, inlineValue);
                 break;
             case "--tsconfig":
-                out.tsconfig = readCachePathsValue(flag.name, inlineValue, rest);
+                out.tsconfig = readValue(flag.name, inlineValue);
                 break;
             default:
                 throw new Error(`ttsc: cache paths does not support ${JSON.stringify(token)}`);
@@ -312,20 +361,6 @@ function splitInlineFlag(token) {
         ? [token, undefined]
         : [token.slice(0, equals), token.slice(equals + 1)];
 }
-function readCachePathsValue(flag, inlineValue, rest) {
-    if (inlineValue !== undefined) {
-        return inlineValue;
-    }
-    const value = rest.shift();
-    if (value === undefined) {
-        throw new Error(`ttsc: ${flag} requires a value`);
-    }
-    if (value.startsWith("-")) {
-        rest.unshift(value);
-        throw new Error(`ttsc: ${flag} requires a value (next token ${JSON.stringify(value)} starts with "-")`);
-    }
-    return value;
-}
 function resolveCleanProjectRoot(cwd, tsconfig) {
     try {
         return node_path_1.default.dirname((0, resolveProjectConfig_1.resolveProjectConfig)({ cwd, tsconfig }));
@@ -337,11 +372,27 @@ function resolveCleanProjectRoot(cwd, tsconfig) {
     }
 }
 function formatProjectPath(cwd, target) {
-    const relative = node_path_1.default.relative(cwd, target);
-    if (!relative || isOutsideRelativePath(relative)) {
-        return target;
-    }
-    return relative;
+    const relative = relativeToCwd(cwd, target);
+    return !relative || isOutsideRelativePath(relative) ? target : relative;
+}
+/**
+ * `target` relative to `cwd`, both as the filesystem names them.
+ *
+ * The project, its caches, and its outputs resolve to their physical directory,
+ * while the cwd is spelled as the user reached it, possibly through a link or
+ * macOS's `/var`. Relating two spellings of one directory walks out through the
+ * link and back in, so both sides go through the one resolver that names paths
+ * physically (`resolvePhysicalPath`).
+ */
+function relativeToCwd(cwd, target) {
+    return node_path_1.default.relative((0, resolvePhysicalPath_1.resolvePhysicalPath)(cwd), (0, resolvePhysicalPath_1.resolvePhysicalPath)(target));
+}
+/**
+ * `location` as a watch message names it: relative to the cwd, `.` for the cwd
+ * itself, and through `..` when it lies outside.
+ */
+function watchMessagePath(cwd, location) {
+    return relativeToCwd(cwd, location) || ".";
 }
 function isOutsideRelativePath(relative) {
     return (relative === ".." ||
@@ -351,88 +402,19 @@ function isOutsideRelativePath(relative) {
 function parseProjectArgs(argv) {
     // `prepare` and `clean` are project-shaped commands. They share the same
     // schema as the build lane; the engine forwards unknown flags as well as
-    // build-only flags (e.g. `--strict`) to the launcher's passthrough list
-    // so the legacy "unknown option" behaviour is no longer a separate trap
-    // (RC-3 + RC-4 prevention; see issue #125 §5 in the RCA).
-    const result = (0, parser_1.parseFlags)({
+    // build-only flags (e.g. `--strict`) to the launcher's passthrough list, so
+    // an unknown option is not a separate error path.
+    const result = (0, parseFlags_1.parseFlags)({
         argv,
         errorPrefix: "ttsc:",
         subcommand: "prepare",
     });
     return {
-        cacheDir: (0, parser_1.getString)(result, "--cache-dir"),
-        cwd: (0, parser_1.getString)(result, "--cwd"),
-        tsconfig: (0, parser_1.getString)(result, "--tsconfig"),
-    };
-}
-function parseBuildArgs(argv) {
-    const result = (0, parser_1.parseFlags)({
-        argv,
-        errorPrefix: "ttsc:",
-        // A bare token is a single-file input only when it carries a TypeScript
-        // source extension; any other bare token is the space-separated value of a
-        // preceding forwarded flag (e.g. the `es2020` in `--target es2020`). The
-        // parser routes those values into `passthrough` in place, so the forwarded
-        // flag/value pairs reach tsgo in their original order.
-        isPositional: looksLikeInputFile,
-        subcommand: "build",
-    });
-    (0, assertNoSolutionBuild_1.assertNoSolutionBuild)(result, "ttsc:");
-    // Defaults: pinned by the previous hand-parser. `quiet` defaults true,
-    // `--verbose` flips it to false; `emit` defaults `undefined` so the resolved
-    // project controls ordinary build mode. `runCompatibleBuild` applies the
-    // check/fix/format no-emit decision before either execution lane runs.
-    const verbose = (0, parser_1.getBoolean)(result, "--verbose");
-    const quietFlag = (0, parser_1.getBoolean)(result, "--quiet");
-    const quiet = verbose === true ? false : (quietFlag ?? true);
-    const explicitEmit = (0, parser_1.getBoolean)(result, "--emit");
-    const explicitNoEmit = (0, parser_1.getBoolean)(result, "--noEmit");
-    const emit = resolveExplicitEmit(explicitEmit, explicitNoEmit);
-    // `isPositional: looksLikeInputFile` guarantees every `result.positional`
-    // token is a TypeScript input file; forwarded flag values already live in
-    // `result.passthrough` in their original order, so no reconstruction is
-    // needed here (the previous `[...passthrough, ...trailingValues]` concat
-    // reordered every flag ahead of every value).
-    const files = [...result.positional];
-    const passthrough = [...result.passthrough];
-    return {
-        binary: (0, parser_1.getString)(result, "--binary"),
-        cacheDir: (0, parser_1.getString)(result, "--cache-dir"),
-        checkers: (0, parser_1.getNumber)(result, "--checkers"),
-        cwd: (0, parser_1.getString)(result, "--cwd"),
-        emit,
-        files,
-        fix: false,
-        format: false,
-        outDir: (0, parser_1.getString)(result, "--outDir"),
-        passthrough,
-        preserveWatchOutput: (0, parser_1.getBoolean)(result, "--preserveWatchOutput") === true,
-        quiet,
-        singleThreaded: (0, parser_1.getBoolean)(result, "--singleThreaded") === true,
-        tsconfig: (0, parser_1.getString)(result, "--tsconfig"),
-        watch: (0, parser_1.getBoolean)(result, "--watch") === true,
+        cacheDir: (0, getString_1.getString)(result, "--cache-dir"),
+        cwd: (0, getString_1.getString)(result, "--cwd"),
+        tsconfig: (0, getString_1.getString)(result, "--tsconfig"),
     };
 }
-/**
- * Collapse the two launcher-owned emit switches into the tri-state consumed by
- * `runBuild` and the single-file lane. A specified boolean is significant even
- * when it is `false`: `--emit=false` is analysis-only and `--noEmit=false`
- * explicitly overrides a project's `noEmit`. `--emit` retains precedence when
- * callers supply both switches, matching the legacy true-only resolution.
- */
-function resolveExplicitEmit(explicitEmit, explicitNoEmit) {
-    if (explicitEmit !== undefined)
-        return explicitEmit;
-    return explicitNoEmit === undefined ? undefined : !explicitNoEmit;
-}
-/**
- * Report whether a bare CLI token is a TypeScript source file ttsc should
- * compile in single-file mode. Anything without a TypeScript source extension
- * is treated as a forwarded flag value rather than an input file.
- */
-function looksLikeInputFile(token) {
-    return [".ts", ".tsx", ".mts", ".cts"].some((ext) => token.endsWith(ext));
-}
 function printHelp() {
     process.stdout.write([
         "ttsc — standalone compiler adapter and plugin host for tsgo.",
@@ -501,60 +483,45 @@ function printCacheHelp() {
     ].join("\n"));
     process.stdout.write("\n");
 }
+/**
+ * Adapt one normalized CLI request to its selected private producer and public
+ * copy. The existing selection owns config and original argument anchoring;
+ * the full request retains cache, reporting and watch callbacks. Only the
+ * private helper writes the selected public file. Success presentation follows
+ * that completed copy and describes public emission, without private products
+ * or a fabricated transform-site count. Watch supplies quiet true itself.
+ */
 function runSingleFile(options) {
     if (options.files.length !== 1) {
         throw new Error("ttsc: single-file mode currently accepts exactly one input file");
     }
     const cwd = node_path_1.default.resolve(options.cwd ?? process.cwd());
     const file = node_path_1.default.resolve(cwd, options.files[0]);
-    const emit = singleFileShouldEmit(options, cwd, file);
+    const selection = CompilerProjectSelection_1.CompilerProjectSelection.read({ ...options, cwd, file });
+    const project = selection.project;
+    const emit = options.emit ?? project.compilerOptions.noEmit !== true;
     const out = emit
-        ? (0, singleFileOutput_1.resolveSingleFileOutput)({
+        ? (0, resolveSingleFileOutput_1.resolveSingleFileOutput)({
             cliOutDir: options.outDir,
             cwd,
             file,
             passthrough: options.passthrough,
             tsconfig: options.tsconfig,
-        })
+        }, project)
         : undefined;
-    const text = (0, runSingleFileEmit_1.runSingleFileEmit)({
-        binary: options.binary,
-        checkers: options.checkers,
-        cwd,
-        file,
-        onProjectInputs: options.onProjectInputs,
-        onWatchInputs: options.onWatchInputs,
-        out,
-        passthrough: options.passthrough,
-        singleThreaded: options.singleThreaded,
-        tsconfig: options.tsconfig,
-    });
-    if (out !== undefined && !node_fs_1.default.existsSync(out)) {
-        node_fs_1.default.mkdirSync(node_path_1.default.dirname(out), { recursive: true });
-        node_fs_1.default.writeFileSync(out, text, "utf8");
+    (0, runSingleFileEmit_1.runSingleFileEmit)({ ...options, cwd, file, out }, selection);
+    if (options.quiet === false) {
+        process.stdout.write(`// ttsc: tsconfig=${project.path} cwd=${cwd} emit=${emit}\n`);
+        if (out !== undefined) {
+            process.stdout.write(`// ttsc: emitted=1 files\n`);
+            process.stdout.write(`  + ${relativeToCwd(cwd, out) || out}\n`);
+        }
     }
     if (out !== undefined) {
-        process.stdout.write(`${node_path_1.default.relative(cwd, out) || node_path_1.default.basename(out)}\n`);
+        process.stdout.write(`${relativeToCwd(cwd, out) || node_path_1.default.basename(out)}\n`);
     }
     return 0;
 }
-/**
- * Resolve the same effective emit decision used by the project lane before
- * entering the single-file compatibility path. The compatibility path still
- * emits into a private temporary directory to obtain transformed text and
- * diagnostics, but only this boundary is allowed to write into the user's
- * tree.
- */
-function singleFileShouldEmit(options, cwd, file) {
-    if (options.emit !== undefined)
-        return options.emit;
-    const project = (0, readProjectConfig_1.readProjectConfig)({
-        cwd,
-        file,
-        tsconfig: options.tsconfig,
-    });
-    return project.compilerOptions.noEmit !== true;
-}
 function runWatch(options, checkOnly) {
     const cwd = node_path_1.default.resolve(options.cwd ?? process.cwd());
     let topology;
@@ -569,21 +536,26 @@ function runWatch(options, checkOnly) {
         },
         quiet: true,
     };
-    const root = node_path_1.default.dirname((0, resolveProjectConfig_1.resolveProjectConfig)({
-        cwd,
-        tsconfig: options.tsconfig,
-    }));
+    const root = CompilerProjectSelection_1.CompilerProjectSelection.read(invocation).project.root;
     let running = false;
+    let closed = false;
+    let active;
+    let closing;
     let rerun = false;
     let timer = null;
-    const resident = invocation.files.length === 0 ? new runBuild_1.ResidentCheckWatchSession() : undefined;
-    const pendingChanges = new PendingResidentCheckWatchChanges();
+    const resident = invocation.files.length === 0 ? new ResidentCheckWatchSession_1.ResidentCheckWatchSession() : undefined;
+    const pendingChanges = new PendingResidentCheckWatchChanges_1.PendingResidentCheckWatchChanges();
     // Tracks the most recent build's exit code so the watch session can exit
     // non-zero when its latest rebuild failed, instead of always reporting 0.
     let lastStatus = 0;
+    let completedBuild = false;
     const runOnce = async () => {
+        if (closed)
+            return;
         running = true;
         const change = pendingChanges.take();
+        if (process.env.TTSC_WATCH_DEBUG_INPUTS)
+            debugWatchInputs(`cycle ${JSON.stringify(change)}`);
         let completed = false;
         try {
             if (!options.preserveWatchOutput) {
@@ -619,21 +591,27 @@ function runWatch(options, checkOnly) {
                         process.stdout.write(result.stderr);
                     return result.status;
                 })());
+            if (closed)
+                return;
             lastStatus = status;
+            completedBuild = true;
             completed = true;
             process.stdout.write(`[ttsc] ${status === 0 ? "watch build complete" : "watch build failed"}\n`);
         }
         catch (error) {
+            if (closed)
+                return;
             // Same ordered-stream rule as the build path: the failure text goes on
             // the stream the marker below uses, so a merged reader sees them in order
             // rather than racing two pipes.
             process.stdout.write(`${formatError(error)}\n`);
             lastStatus = lastStatus === 0 ? 2 : lastStatus;
+            completedBuild = true;
             process.stdout.write(`[ttsc] watch build failed\n`);
         }
         finally {
             running = false;
-            if (completed) {
+            if (completed && !closed) {
                 try {
                     // A filesystem event can arrive after the build reports completion
                     // but before this synchronous cleanup reaches its re-resolution.
@@ -642,7 +620,7 @@ function runWatch(options, checkOnly) {
                     topology?.refresh(true);
                 }
                 catch (error) {
-                    process.stderr.write(`[ttsc] watch error on ${node_path_1.default.relative(cwd, root) || "."}: ${formatError(error)}\n`);
+                    process.stderr.write(`[ttsc] watch error on ${watchMessagePath(cwd, root)}: ${formatError(error)}\n`);
                 }
             }
         }
@@ -652,6 +630,8 @@ function runWatch(options, checkOnly) {
         }
     };
     const trigger = (change, reload = false) => {
+        if (closed)
+            return;
         pendingChanges.push(change, reload);
         if (running) {
             rerun = true;
@@ -659,112 +639,182 @@ function runWatch(options, checkOnly) {
         }
         if (timer)
             clearTimeout(timer);
-        timer = setTimeout(() => void runOnce(), 60);
+        timer = setTimeout(startRun, 60);
+    };
+    const close = () => {
+        if (closing !== undefined)
+            return closing;
+        E2ETrace_1.E2ETrace.watchShutdown("close-start", {
+            residentSelected: resident !== undefined,
+            activeSelected: active !== undefined,
+        });
+        closed = true;
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+        process.off("SIGINT", onInterrupt);
+        process.off("SIGTERM", onTerminate);
+        process.off("message", onMessage);
+        process.off("disconnect", onDisconnect);
+        let topologyError;
+        try {
+            topology?.close();
+        }
+        catch (error) {
+            topologyError = error;
+        }
+        const residentClosing = resident?.close() ?? Promise.resolve();
+        const activeClosing = active ?? Promise.resolve();
+        closing = Promise.allSettled([residentClosing, activeClosing]).then((results) => {
+            const errors = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+            if (topologyError !== undefined)
+                errors.push(topologyError);
+            if (errors.length !== 0)
+                throw new AggregateError(errors, `ttsc: watch shutdown failed: ${errors.map(formatError).join("; ")}`);
+        });
+        if (process.env.TTSC_E2E_TRACE) {
+            // Observe the original promises without substituting their settlements.
+            void residentClosing.then(() => E2ETrace_1.E2ETrace.watchShutdown("resident-settled", { outcome: "fulfilled" }), () => E2ETrace_1.E2ETrace.watchShutdown("resident-settled", { outcome: "rejected" }));
+            void activeClosing.then(() => E2ETrace_1.E2ETrace.watchShutdown("active-settled", { outcome: "fulfilled" }), () => E2ETrace_1.E2ETrace.watchShutdown("active-settled", { outcome: "rejected" }));
+            void closing.then(() => E2ETrace_1.E2ETrace.watchShutdown("close-promise-settled", {
+                outcome: "fulfilled",
+            }), () => E2ETrace_1.E2ETrace.watchShutdown("close-promise-settled", {
+                outcome: "rejected",
+            }));
+        }
+        void closing.catch(() => { });
+        return closing;
+    };
+    const finish = async (id) => {
+        E2ETrace_1.E2ETrace.watchShutdown("finish-start", { stopId: id });
+        try {
+            await close();
+            E2ETrace_1.E2ETrace.watchShutdown("close-settled", {
+                stopId: id,
+                outcome: "fulfilled",
+            });
+            process.exitCode = toExitCode(lastStatus);
+            if (id !== undefined && process.connected && process.send !== undefined) {
+                E2ETrace_1.E2ETrace.watchShutdown("ack-send", { stopId: id });
+                await new Promise((resolve, reject) => {
+                    process.send({
+                        type: "ttsc.watch.stopped",
+                        id,
+                        status: completedBuild ? lastStatus : null,
+                    }, (error) => {
+                        E2ETrace_1.E2ETrace.watchShutdown("ack-callback", {
+                            stopId: id,
+                            outcome: error === null ? "fulfilled" : "rejected",
+                        });
+                        error === null ? resolve() : reject(error);
+                    });
+                });
+            }
+        }
+        catch (error) {
+            E2ETrace_1.E2ETrace.watchShutdown("finish-rejected", { stopId: id });
+            process.stderr.write(`${formatError(error)}\n`);
+            process.exitCode = toExitCode(lastStatus === 0 ? 2 : lastStatus);
+        }
+        finally {
+            if (process.connected) {
+                E2ETrace_1.E2ETrace.watchShutdown("disconnect-start", {
+                    stopId: id,
+                    selected: process.disconnect !== undefined,
+                });
+                try {
+                    process.disconnect?.();
+                    E2ETrace_1.E2ETrace.watchShutdown("disconnect-return", {
+                        stopId: id,
+                        outcome: "fulfilled",
+                    });
+                }
+                catch (error) {
+                    E2ETrace_1.E2ETrace.watchShutdown("disconnect-return", {
+                        stopId: id,
+                        outcome: "rejected",
+                    });
+                    process.stderr.write(`${formatError(error)}\n`);
+                    process.exitCode = toExitCode(lastStatus === 0 ? 2 : lastStatus);
+                }
+            }
+            E2ETrace_1.E2ETrace.watchShutdown("finish-end", {
+                stopId: id,
+                exitCode: process.exitCode,
+            });
+        }
     };
-    topology = new watchTopology_1.WatchTopology(invocation, {
+    const onInterrupt = () => {
+        void finish();
+    };
+    const onTerminate = () => {
+        void finish();
+    };
+    const onDisconnect = () => {
+        void finish();
+    };
+    const onMessage = (message) => {
+        if (typeof message === "object" &&
+            message !== null &&
+            "type" in message &&
+            message.type === "ttsc.watch.stop" &&
+            "id" in message &&
+            typeof message.id === "string" &&
+            message.id.length !== 0) {
+            const id = message.id;
+            E2ETrace_1.E2ETrace.watchShutdown("ipc-stop-received", { stopId: id });
+            void finish(id);
+        }
+    };
+    const startRun = () => {
+        active = runOnce();
+        void active.catch((error) => {
+            process.stderr.write(`${formatError(error)}\n`);
+            lastStatus = lastStatus === 0 ? 2 : lastStatus;
+            void finish();
+        });
+    };
+    topology = new WatchTopology_1.WatchTopology(invocation, {
         onError: (location, error) => {
-            process.stderr.write(`[ttsc] watch error on ${node_path_1.default.relative(cwd, location) || "."}: ${formatError(error)}\n`);
+            process.stderr.write(`[ttsc] watch error on ${watchMessagePath(cwd, location)}: ${formatError(error)}\n`);
         },
         onProjectInputWatchUnavailable: (roots) => {
             for (const root of roots) {
-                process.stderr.write(`[ttsc] project-input watch unavailable on ${node_path_1.default.relative(cwd, root) || "."}; changes under this root are not being observed\n`);
+                process.stderr.write(`[ttsc] project-input watch unavailable on ${watchMessagePath(cwd, root)}; changes under this root are not being observed\n`);
             }
         },
         onInputChange: (change) => {
             debugWatchInputs(`change ${change.kind}${change.invalidate === true ? " invalidate" : ""} ${change.path === undefined
                 ? "(unnamed)"
-                : node_path_1.default.relative(cwd, change.path)}`);
+                : watchMessagePath(cwd, change.path)}`);
             trigger(change);
         },
         onProjectInputWatchRoots: (roots) => {
-            debugWatchInputs(`roots ${JSON.stringify(roots.map((root) => node_path_1.default.relative(cwd, root) || "."))}`);
+            debugWatchInputs(`roots ${JSON.stringify(roots.map((root) => watchMessagePath(cwd, root)))}`);
         },
         onTopologyChange: () => trigger(undefined, true),
     });
-    topology.refresh(false);
-    const close = () => {
-        if (timer)
-            clearTimeout(timer);
-        topology?.close();
-        resident?.dispose();
-    };
-    process.on("SIGINT", () => {
-        close();
-        process.exit(toExitCode(lastStatus));
-    });
-    process.on("SIGTERM", () => {
-        close();
-        process.exit(toExitCode(lastStatus));
-    });
-    process.stdout.write(`[ttsc] watching ${node_path_1.default.relative(cwd, root) || "."}\n`);
     try {
-        void runOnce();
+        topology.refresh(false);
+        process.on("SIGINT", onInterrupt);
+        process.on("SIGTERM", onTerminate);
+        if (process.connected) {
+            process.on("message", onMessage);
+            process.on("disconnect", onDisconnect);
+        }
+        process.stdout.write(`[ttsc] watching ${watchMessagePath(cwd, root)}\n`);
+        startRun();
     }
     catch (error) {
-        // runOnce already swallows build throws, but guard against any unforeseen
-        // throw escaping the first pass: tear down the persistent watchers so the
-        // event loop drains and the process exits cleanly with a non-zero code
-        // instead of hanging on live fs.watch handles.
-        close();
+        // Refresh may fail after acquiring only part of the watch set. Release that
+        // partial ownership as well as setup's signal listeners before returning.
+        lastStatus = lastStatus === 0 ? 2 : lastStatus;
         process.stderr.write(`${formatError(error)}\n`);
-        return toExitCode(lastStatus === 0 ? 2 : lastStatus);
+        void finish();
+        return toExitCode(lastStatus);
     }
     return toExitCode(lastStatus);
 }
-/**
- * Coalesces filesystem events until the next resident check-watch cycle.
- *
- * A full reload dominates every narrower signal. Program invalidation remains
- * distinct so a project-input module creation/deletion can cold-load the
- * Program without discarding the selected execution or restarting the sidecar.
- */
-class PendingResidentCheckWatchChanges {
-    changed = new Set();
-    external = new Set();
-    invalidate = false;
-    reload = false;
-    push(change, reload = false) {
-        if (reload || change?.kind === "config" || change?.kind === "plugin") {
-            this.reload = true;
-            this.invalidate = false;
-            this.changed.clear();
-            this.external.clear();
-            return;
-        }
-        if (this.reload)
-            return;
-        if (change?.invalidate === true)
-            this.invalidate = true;
-        if (change?.path === undefined) {
-            if (change?.kind === "compiler") {
-                this.reload = true;
-                this.invalidate = false;
-                this.changed.clear();
-                this.external.clear();
-            }
-            return;
-        }
-        this.changed.add(change.path);
-        if (change.kind === "project")
-            this.external.add(change.path);
-    }
-    take() {
-        const change = {
-            ...(this.reload ? { reload: true } : {}),
-            ...(this.invalidate ? { invalidate: true } : {}),
-            ...(this.changed.size === 0 ? {} : { changed: [...this.changed].sort() }),
-            ...(this.external.size === 0
-                ? {}
-                : { external: [...this.external].sort() }),
-        };
-        this.reload = false;
-        this.invalidate = false;
-        this.changed.clear();
-        this.external.clear();
-        return change;
-    }
-}
-exports.PendingResidentCheckWatchChanges = PendingResidentCheckWatchChanges;
 // Coerces a build status into a valid process exit code: 0 stays 0, any
 // non-zero (or non-finite) status collapses to 1 so the session signals failure.
 function toExitCode(status) {