ttsc 0.31.6 → 0.32.1

package/src/internal/pathIdentity/createFilesystemPathIdentityContext.ts

@@ -1,13 +1,10 @@
-import childProcess from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 
-import { E2ETrace } from "../E2ETrace";
-import { OwnedSynchronousProcess } from "../OwnedSynchronousProcess";
-import { parseWindowsDirectoryCaseSensitivity } from "../parseWindowsDirectoryCaseSensitivity";
 import type { FilesystemPathIdentity } from "./FilesystemPathIdentity";
 import type { FilesystemPathIdentityContext } from "./FilesystemPathIdentityContext";
 import type { FilesystemPathIdentityOperations } from "./FilesystemPathIdentityOperations";
+import { createCaseSensitivityObservations } from "./createCaseSensitivityObservations";
 import { isFilesystemPathIdentityWithin } from "./isFilesystemPathIdentityWithin";
 import { resolveFilesystemPath } from "./resolveFilesystemPath";
 
@@ -47,19 +44,7 @@ export function createFilesystemPathIdentityContext(
   const readdir = operations.readdir ?? fs.readdirSync;
   const caseSensitive =
     operations.caseSensitive ??
-    ((directory: string) => {
-      try {
-        return filesystemDirectoryIsCaseSensitive(directory, platform, {
-          lstat,
-          readdir,
-          realpath,
-        });
-      } catch {
-        // A failed capability observation is unknown. This does not suppress
-        // strict physical identity errors in the separate realpath resolver.
-        return undefined;
-      }
-    });
+    createCaseSensitivityObservations({ lstat, platform, readdir, realpath });
 
   const resolve = (location: string): FilesystemPathIdentity => {
     const normalized = resolveFilesystemPath(location, platform);
@@ -262,150 +247,6 @@ function physicalRealpath(location: string): string {
   return fs.realpathSync.native?.(location) ?? fs.realpathSync(location);
 }
 
-function filesystemDirectoryIsCaseSensitive(
-  directory: string,
-  platform: NodeJS.Platform,
-  operations: {
-    lstat(location: string): fs.Stats | fs.BigIntStats;
-    readdir(directory: string): string[];
-    realpath(location: string): string;
-  },
-): boolean | undefined {
-  const pathApi = platform === "win32" ? path.win32 : path.posix;
-  let entries: string[];
-  try {
-    entries = operations.readdir(directory);
-  } catch {
-    return undefined;
-  }
-  const foldedNames = new Map<string, string>();
-  for (const name of entries) {
-    const folded = foldAsciiCase(name);
-    const previous = foldedNames.get(folded);
-    if (previous !== undefined && previous !== name) return true;
-    foldedNames.set(folded, name);
-  }
-  for (const name of entries) {
-    const alternate = alternateCase(name);
-    if (alternate === name) continue;
-    try {
-      operations.lstat(pathApi.join(directory, alternate));
-    } catch (error) {
-      if (isMissingFilesystemEntry(error)) {
-        // Enumeration is not an atomic snapshot. An absent alternate proves
-        // sensitivity only if the original spelling still names an entry.
-        try {
-          operations.lstat(pathApi.join(directory, name));
-          return true;
-        } catch (originalError) {
-          if (isMissingFilesystemEntry(originalError) === false)
-            throw originalError;
-        }
-        continue;
-      }
-      throw error;
-    }
-    try {
-      const actual = resolveFilesystemPath(
-        operations.realpath(pathApi.join(directory, name)),
-        platform,
-      );
-      const alias = resolveFilesystemPath(
-        operations.realpath(pathApi.join(directory, alternate)),
-        platform,
-      );
-      return actual !== alias;
-    } catch (error) {
-      if (isMissingFilesystemEntry(error) === false) throw error;
-    }
-  }
-  if (platform === "darwin") {
-    // APFS/HFS case semantics are volume-wide. An empty directory has no child
-    // name to probe, so ask the same read-only question of its existing name in
-    // the parent and walk upward until a name with ASCII case is available.
-    // This avoids a write probe while still distinguishing default APFS from a
-    // case-sensitive volume.
-    let current = resolveFilesystemPath(directory, platform);
-    while (true) {
-      const parent = pathApi.dirname(current);
-      if (parent === current) break;
-      // Names are interpreted by their parent; another mount is not evidence
-      // of the directory's own volume case policy.
-      if (operations.lstat(current).dev !== operations.lstat(parent).dev)
-        return undefined;
-      const name = pathApi.basename(current);
-      const alternate = alternateCase(name);
-      if (alternate !== name) {
-        try {
-          const actual = resolveFilesystemPath(
-            operations.realpath(current),
-            platform,
-          );
-          const alias = resolveFilesystemPath(
-            operations.realpath(pathApi.join(parent, alternate)),
-            platform,
-          );
-          return actual !== alias;
-        } catch (error) {
-          if (isMissingFilesystemEntry(error) === false) throw error;
-        }
-      }
-      current = parent;
-    }
-    return undefined;
-  }
-  if (platform !== "win32") return undefined;
-  // Node does not expose the Windows per-directory flag. Prefer fsutil's
-  // read-only answer; unavailable capability remains unknown.
-  const queried = queryWindowsDirectoryCaseSensitivity(directory);
-  if (queried !== undefined) return queried;
-  return undefined;
-}
-
-/**
- * Read the per-directory flag without depending on fsutil's display language.
- *
- * English output is cheap to recognize directly. Other Windows locales write
- * console-code-page bytes that Node cannot reliably decode, so their raw
- * message is interpreted against the volume-root query.
- */
-function queryWindowsDirectoryCaseSensitivity(
-  directory: string,
-): boolean | undefined {
-  const result = queryWindowsDirectoryCaseSensitivityBytes(directory);
-  if (result === undefined) return undefined;
-  const volumeRoot = path.win32.parse(directory).root;
-  const direct = parseWindowsDirectoryCaseSensitivity(
-    result,
-    undefined,
-    volumeRoot,
-  );
-  if (direct !== undefined) return direct;
-  const volume = queryWindowsDirectoryCaseSensitivityBytes(volumeRoot);
-  return parseWindowsDirectoryCaseSensitivity(result, volume, volumeRoot);
-}
-
-function queryWindowsDirectoryCaseSensitivityBytes(
-  directory: string,
-): Buffer | undefined {
-  const args = ["file", "queryCaseSensitiveInfo", directory];
-  const result = E2ETrace.synchronous(
-    "fsutil.exe",
-    args,
-    {},
-    "path-case-probe",
-    () =>
-      OwnedSynchronousProcess.launch("fsutil.exe", args, {
-        windowsHide: true,
-      }) ?? childProcess.spawnSync("fsutil.exe", args, { windowsHide: true }),
-  );
-  return result.error === undefined &&
-    result.status === 0 &&
-    Buffer.isBuffer(result.stdout)
-    ? result.stdout
-    : undefined;
-}
-
 function filesystemPathIdentityKey(
   location: string,
   platform: NodeJS.Platform,
@@ -415,14 +256,6 @@ function filesystemPathIdentityKey(
   return `${root.toLowerCase()}${location.slice(root.length)}`;
 }
 
-function alternateCase(value: string): string {
-  return value.replace(/[A-Za-z]/g, (character) =>
-    character === character.toLowerCase()
-      ? character.toUpperCase()
-      : character.toLowerCase(),
-  );
-}
-
 /** ASCII folding is the case equivalence observed by the read-only probes. */
 function foldAsciiCase(value: string): string {
   return value.replace(/[A-Z]/g, (character) => character.toLowerCase());

package/src/internal/projectInputPathIdentity.ts

@@ -16,6 +16,7 @@
 export * from "./pathIdentity/FilesystemPathIdentity";
 export * from "./pathIdentity/FilesystemPathIdentityOperations";
 export * from "./pathIdentity/FilesystemPathIdentityContext";
+export * from "./pathIdentity/createCaseSensitivityObservations";
 export * from "./pathIdentity/createFilesystemPathIdentityContext";
 export * from "./pathIdentity/isFilesystemPathIdentityWithin";
 export * from "./pathIdentity/resolveFilesystemPath";

package/src/internal/workerModuleUrl.ts

@@ -0,0 +1,34 @@
+import path from "node:path";
+
+/**
+ * Load an owned CommonJS worker through a module URL while retaining Node's
+ * inherited execution options and preload hooks.
+ *
+ * A parent launched with --input-type interprets stdin or evaluated source.
+ * With a preload, module resolution rejects that inherited option at a file
+ * worker entry before the worker can start. A supported data URL supplies
+ * module source that requires the real entry. Setting execArgv instead would
+ * replace Node's inherited-option handling and can reject otherwise valid
+ * process options such as --max-old-space-size. createRequire preserves the
+ * entry's CommonJS resolution, including literal POSIX backslashes that file
+ * URL imports reject as encoded separators. The worker entry must use the
+ * package's CommonJS source or emitted format.
+ *
+ * @param filename Native entry path, resolved from cwd when relative.
+ * @returns A data URL accepted by the Worker constructor; it owns no thread.
+ * @evidence contracts/common.md#principled-implementation Node documents data URL worker entries and inherited options; a module-source entry requires the selected CommonJS owner without applying the parent's stdin-only input type to that file's initial module resolution.
+ * @evidence contracts/common.md#clear-and-simple-design One URL constructor owns the bootstrap representation while callers retain worker options, thread lifetime and actual entry selection.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported createRequire loads the actual CommonJS owner; no flags are guessed, stripped or replaced and no foreign process state is changed.
+ * @evidence contracts/common.md#meaningful-documentation Prose explains the stdin inheritance failure, the explicit-execArgv hazard, CommonJS entry requirements and the native path input.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path resolution and createRequire retain filesystem path spelling, including POSIX literal backslashes; JSON string encoding and data URL encoding separate that path from JavaScript and URL syntax without routing it through ESM file-URL separator rules.
+ * @evidence contracts/performance.md#efficient-algorithms Native path resolution, string encoding and data URL construction each visit entry-path text; the returned URL and its module source occupy linear space in that text.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call represents its selected entry and retains no computed answer.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This operation returns a URL without acquiring a worker, file handle or persistent state; the caller owns the URL and thread.
+ * @see https://nodejs.org/api/worker_threads.html#new-workerfilename-options
+ * @see https://nodejs.org/api/cli.html#--input-typetype
+ */
+export function workerModuleUrl(filename: string): URL {
+  const entry = JSON.stringify(path.resolve(filename));
+  const source = `import { createRequire } from "node:module"; createRequire(${entry})(${entry});`;
+  return new URL(`data:text/javascript,${encodeURIComponent(source)}`);
+}

package/src/launcher/internal/buildSingleRootProject.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { runBuild } from "../../compiler/internal/build/runBuild";
 import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
 import { readEffectiveCompilerOptions } from "../../compiler/internal/readEffectiveCompilerOptions";
+import { SidecarEnvironment } from "../../compiler/internal/sharedHost/SidecarEnvironment";
 import { createFilesystemPathIdentityContext } from "../../internal/pathIdentity/createFilesystemPathIdentityContext";
 import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
 import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
@@ -186,6 +187,7 @@ export function buildSingleRootProject(props: {
       project,
       options.passthrough,
       options.binary,
+      SidecarEnvironment.merge(process.env, options.env),
     );
     const result = runBuild({
       binary: options.binary,

package/src/launcher/internal/getCompilerVersionText.ts

@@ -24,10 +24,11 @@ import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOpti
 export function getCompilerVersionText(
   options: TtscCommonOptions = {},
 ): string {
-  const tsgo = resolveTsgo(options);
+  const env = SidecarEnvironment.merge(process.env, options.env);
+  const tsgo = resolveTsgo({ ...options, env });
   const res = spawnNative(tsgo.binary, ["--version"], {
     cwd: options.cwd,
-    env: SidecarEnvironment.merge(process.env, options.env),
+    env,
   });
   if (res.error || res.status !== 0) {
     throw new Error(

package/src/launcher/internal/parseTtsxCLI.ts

@@ -14,10 +14,11 @@ import { assertTtsxNoWatch } from "./assertTtsxNoWatch";
  * Compiler flags before the first entry, repeated preloads and launcher-owned
  * settings are separated once through the shared flag schema. Terminal requests
  * are recognized only before the entry; unsupported watch/build requests fail
- * before a check, build or program is started. These decisions inspect the supplied
- * argv frame; this parser does not read response-file contents or certify their
- * eventual native effects. Preparation inspects response frames at the selected
- * project's actual compiler directory before requesting its build.
+ * before a check, build or program is started. These decisions inspect the
+ * supplied argv frame; this parser does not read response-file contents or
+ * certify their eventual native effects. Preparation inspects response frames
+ * at the selected project's actual compiler directory before requesting its
+ * build.
  *
  * @param argv Command tokens as received from the launcher.
  * @returns A terminal request or the launcher's typed option record.

package/src/launcher/internal/prepareExecution.ts

@@ -324,8 +324,12 @@ function createProjectContext(
     project,
     options.passthrough,
     options.binary,
+    env,
+  );
+  const privateEmitRootDir = resolveRuntimeSourceRoot(
+    project,
+    effectiveOptions,
   );
-  const privateEmitRootDir = resolveRuntimeSourceRoot(project, effectiveOptions);
   // Resolved once: resolution costs a realpath (and, for a missing directory on
   // Windows, a case-sensitivity probe).
   const runtimeRootDir = createFilesystemPathIdentityContext({
@@ -437,6 +441,7 @@ function discoverOwningProject(
   });
   const owning = resolveOwningProjectConfig({
     binary: options.binary,
+    env: SidecarEnvironment.merge(process.env, options.env),
     file,
     tsconfig: nearest.path,
   });

package/src/launcher/internal/resolveSingleFileOutput.ts

@@ -14,15 +14,14 @@ import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscPa
  * then copies one transformed JavaScript file to this path, so project-mode
  * declaration, map, build-info, outFile, and broad outDir products are not
  * positional outputs. Explicit output mirrors cwd for contained sources and
- * uses the source basename for outside-layout or different-volume sources.
- * A supplied invocation project owns placement without
- * resolving the original locator again. Forwarded JSX uses the supplied native
- * argv frames and does not expand response-file requests here. CLI enum
- * normalization; an explicit reset selects the default suffix instead of
- * reviving the configured JSX. Placement-setting read failures use the
- * no-project fallback; that fallback does not certify a successful build or
- * valid configuration. Physical spelling is a current native observation, not a
- * pinned filesystem object.
+ * uses the source basename for outside-layout or different-volume sources. A
+ * supplied invocation project owns placement without resolving the original
+ * locator again. Forwarded JSX uses the supplied native argv frames and does
+ * not expand response-file requests here. CLI enum normalization; an explicit
+ * reset selects the default suffix instead of reviving the configured JSX.
+ * Placement-setting read failures use the no-project fallback; that fallback
+ * does not certify a successful build or valid configuration. Physical spelling
+ * is a current native observation, not a pinned filesystem object.
  *
  * @evidence contracts/common.md#principled-implementation CLI output wins over the selected project output; a contained cwd-relative source mirrors its layout while an outside-layout or cross-volume source uses its basename inside that explicit root. Supported extensions choose the emitted suffix, and physical root/file relation preserves configured project layout through links.
  * @evidence contracts/common.md#clear-and-simple-design Output placement delegates project settings and isolates containment, extension and forwarded-option readers; it does not materialize compiler side products.

package/src/launcher/internal/runTtsc.ts

@@ -35,8 +35,9 @@ import { resolveCacheDir } from "./resolveCacheDir";
 import { resolveSingleFileOutput } from "./resolveSingleFileOutput";
 import { resolveRuntimeCleanTargets } from "./runtime/resolveRuntimeCleanTargets";
 import { withRuntimeDirectoryLock } from "./runtime/withRuntimeDirectoryLock";
+import { AsyncWatchTopology } from "./watch/AsyncWatchTopology";
 import { type WatchInputChange } from "./watch/WatchInputChange";
-import { WatchTopology } from "./watch/WatchTopology";
+import { WatchSettlement } from "./watch/WatchSettlement";
 
 /**
  * CLI entry point for `ttsc`. Dispatches argv to the appropriate lane (build,
@@ -578,16 +579,30 @@ function printCacheHelp(): void {
 
 /**
  * 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.
+ * 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. The async
+ * watch executor awaits input publication before building; ordinary CLI calls
+ * keep their synchronous return contract and share output planning.
  */
 function runSingleFile(
   options: ReturnType<typeof parseTtscBuildArgs> &
     Pick<TtscSingleFileEmitOptions, "onProjectInputs" | "onWatchInputs">,
-): number {
+): number;
+function runSingleFile(
+  options: ReturnType<typeof parseTtscBuildArgs> &
+    Pick<TtscSingleFileEmitOptions, "onProjectInputs" | "onWatchInputs">,
+  execute: typeof runSingleFileEmit.async,
+): Promise<number>;
+function runSingleFile(
+  options: ReturnType<typeof parseTtscBuildArgs> &
+    Pick<TtscSingleFileEmitOptions, "onProjectInputs" | "onWatchInputs">,
+  execute:
+    | typeof runSingleFileEmit
+    | typeof runSingleFileEmit.async = runSingleFileEmit,
+): number | Promise<number> {
   if (options.files.length !== 1) {
     throw new Error(
       "ttsc: single-file mode currently accepts exactly one input file",
@@ -610,20 +625,25 @@ function runSingleFile(
         project,
       )
     : undefined;
-  runSingleFileEmit({ ...options, cwd, file, out }, selection);
-  if (options.quiet === false) {
-    process.stdout.write(
-      `// ttsc: tsconfig=${project.path} cwd=${cwd} emit=${emit}\n`,
-    );
+  const result = execute({ ...options, cwd, file, out }, selection);
+  const report = (): number => {
+    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(`// ttsc: emitted=1 files\n`);
-      process.stdout.write(`  + ${relativeToCwd(cwd, out) || out}\n`);
+      process.stdout.write(
+        `${relativeToCwd(cwd, out) || path.basename(out)}\n`,
+      );
     }
-  }
-  if (out !== undefined) {
-    process.stdout.write(`${relativeToCwd(cwd, out) || path.basename(out)}\n`);
-  }
-  return 0;
+    return 0;
+  };
+  return typeof result === "string" ? report() : result.then(report);
 }
 
 function runWatch(
@@ -631,7 +651,7 @@ function runWatch(
   checkOnly: boolean,
 ): number {
   const cwd = path.resolve(options.cwd ?? process.cwd());
-  let topology: WatchTopology | undefined;
+  let topology: AsyncWatchTopology | undefined;
   const invocation = {
     ...(checkOnly ? { ...options, emit: false } : options),
     cwd,
@@ -639,10 +659,10 @@ function runWatch(
       inputs: readonly string[],
       identities?: PluginContentIdentities.Store,
     ) => {
-      topology?.setExtraInputs(inputs, identities);
+      return topology?.setExtraInputs(inputs, identities);
     },
     onProjectInputs: (inputs: ITtscProjectInputSnapshot) => {
-      topology?.setProjectInputs(inputs);
+      return topology?.setProjectInputs(inputs);
     },
     quiet: true,
   };
@@ -653,6 +673,8 @@ function runWatch(
   let closing: Promise<void> | undefined;
   let rerun = false;
   let timer: NodeJS.Timeout | null = null;
+  const settlement = new WatchSettlement();
+  let completedBuilds = 0;
   const resident =
     invocation.files.length === 0 ? new ResidentCheckWatchSession() : undefined;
   const pendingChanges = new PendingResidentCheckWatchChanges();
@@ -664,6 +686,7 @@ function runWatch(
   const runOnce = async () => {
     if (closed) return;
     running = true;
+    settlement.changed();
     const change = pendingChanges.take();
     if (process.env.TTSC_WATCH_DEBUG_INPUTS)
       debugWatchInputs(`cycle ${JSON.stringify(change)}`);
@@ -682,14 +705,14 @@ function runWatch(
       // rebuild reports a clear failure and the watcher keeps running instead
       // of crashing the process with an uncaught exception.
       const status = await (invocation.files.length !== 0
-        ? Promise.resolve(runSingleFile(invocation))
+        ? runSingleFile(invocation, runSingleFileEmit.async)
         : (async () => {
             const buildOptions = checkOnly
               ? { ...invocation, emit: false }
               : invocation;
             const result =
               resident === undefined
-                ? runBuild(buildOptions)
+                ? await runBuild.async(buildOptions)
                 : await resident.run(buildOptions, change);
             // Watch output is one ordered stream. The diagnostics a build
             // produced and the "[ttsc] watch build …" marker that concludes
@@ -710,6 +733,7 @@ function runWatch(
       process.stdout.write(
         `[ttsc] ${status === 0 ? "watch build complete" : "watch build failed"}\n`,
       );
+      ++completedBuilds;
     } catch (error) {
       if (closed) return;
       // Same ordered-stream rule as the build path: the failure text goes on
@@ -719,30 +743,33 @@ function runWatch(
       lastStatus = lastStatus === 0 ? 2 : lastStatus;
       completedBuild = true;
       process.stdout.write(`[ttsc] watch build failed\n`);
+      ++completedBuilds;
     } finally {
-      running = false;
       if (completed && !closed) {
         try {
           // A filesystem event can arrive after the build reports completion
-          // but before this synchronous cleanup reaches its re-resolution.
+          // but before post-build reconciliation reaches its re-resolution.
           // Notify for a membership change here as well, otherwise that new
           // input is silently absorbed into the watch set without a rebuild.
-          topology?.refresh(true);
+          await topology?.refresh(true);
         } catch (error) {
           process.stderr.write(
             `[ttsc] watch error on ${watchMessagePath(cwd, root)}: ${formatError(error)}\n`,
           );
         }
       }
+      running = false;
     }
     if (rerun) {
       rerun = false;
       trigger();
     }
+    settlement.changed();
   };
   const trigger = (change?: WatchInputChange, reload = false) => {
     if (closed) return;
     pendingChanges.push(change, reload);
+    settlement.changed();
     if (running) {
       rerun = true;
       return;
@@ -758,33 +785,30 @@ function runWatch(
       activeSelected: active !== undefined,
     });
     closed = true;
+    settlement.changed();
     if (timer) clearTimeout(timer);
     timer = null;
     process.off("SIGINT", onInterrupt);
     process.off("SIGTERM", onTerminate);
     process.off("message", onMessage);
     process.off("disconnect", onDisconnect);
-    let topologyError: unknown;
-    try {
-      topology?.close();
-    } catch (error) {
-      topologyError = error;
-    }
+    const topologyClosing = topology?.close() ?? Promise.resolve();
     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] : [],
+    closing = Promise.allSettled([
+      topologyClosing,
+      residentClosing,
+      activeClosing,
+    ]).then((results) => {
+      const errors = results.flatMap((result) =>
+        result.status === "rejected" ? [result.reason] : [],
+      );
+      if (errors.length !== 0)
+        throw new AggregateError(
+          errors,
+          `ttsc: watch shutdown failed: ${errors.map(formatError).join("; ")}`,
         );
-        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(
@@ -893,9 +917,48 @@ function runWatch(
       const id = message.id;
       E2ETrace.watchShutdown("ipc-stop-received", { stopId: id });
       void finish(id);
+    } else if (
+      typeof message === "object" &&
+      message !== null &&
+      "type" in message &&
+      message.type === "ttsc.watch.settle" &&
+      "id" in message &&
+      typeof message.id === "string" &&
+      message.id.length !== 0
+    ) {
+      const id = message.id;
+      // Build markers retain their exact text and one marker per cycle. IPC
+      // travels on another pipe, so its receipt carries the completed count:
+      // a caller must drain those stdout markers before using the boundary.
+      void settlement
+        .wait(
+          async () => {
+            await topology?.whenIdle();
+            if (closed) throw new Error("ttsc: watch closed before settling");
+            return !running && !rerun && timer === null;
+          },
+          async () => {
+            if (process.connected && process.send !== undefined)
+              await new Promise<void>((resolve, reject) => {
+                process.send!(
+                  { type: "ttsc.watch.settled", id, builds: completedBuilds },
+                  (error: Error | null) =>
+                    error === null ? resolve() : reject(error),
+                );
+              });
+          },
+        )
+        .catch((error: unknown) => {
+          if (!closed) {
+            process.stderr.write(`${formatError(error)}\n`);
+            lastStatus = lastStatus === 0 ? 2 : lastStatus;
+            void finish();
+          }
+        });
     }
   };
   const startRun = () => {
+    timer = null;
     active = runOnce();
     void active.catch((error: unknown) => {
       process.stderr.write(`${formatError(error)}\n`);
@@ -904,7 +967,13 @@ function runWatch(
     });
   };
 
-  topology = new WatchTopology(invocation, {
+  topology = new AsyncWatchTopology(invocation, {
+    onFailure: (error) => {
+      if (closed) return;
+      lastStatus = lastStatus === 0 ? 2 : lastStatus;
+      process.stderr.write(`${formatError(error)}\n`);
+      void finish();
+    },
     onError: (location, error) => {
       process.stderr.write(
         `[ttsc] watch error on ${watchMessagePath(cwd, location)}: ${formatError(error)}\n`,
@@ -934,16 +1003,25 @@ function runWatch(
     },
     onTopologyChange: () => trigger(undefined, true),
   });
+  const start = async (): Promise<void> => {
+    await topology!.refresh(false);
+    if (closed) return;
+    process.stdout.write(`[ttsc] watching ${watchMessagePath(cwd, root)}\n`);
+    startRun();
+  };
   try {
-    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();
+    void start().catch((error: unknown) => {
+      if (closed) return;
+      lastStatus = lastStatus === 0 ? 2 : lastStatus;
+      process.stderr.write(`${formatError(error)}\n`);
+      void finish();
+    });
   } catch (error) {
     // Refresh may fail after acquiring only part of the watch set. Release that
     // partial ownership as well as setup's signal listeners before returning.