ttsc 0.32.0 → 0.32.1

package/src/launcher/internal/watch/AsyncWatchTopology.ts

@@ -0,0 +1,267 @@
+import path from "node:path";
+import { Worker } from "node:worker_threads";
+
+import { SidecarEnvironment } from "../../../compiler/internal/sharedHost/SidecarEnvironment";
+import { workerModuleUrl } from "../../../internal/workerModuleUrl";
+import type { PluginContentIdentities } from "../../../plugin/internal/source/PluginContentIdentities";
+import type { ITtscProjectInputSnapshot } from "../../../structures/internal/ITtscProjectInputSnapshot";
+import type { WatchTopologyWorkerProtocol } from "./WatchTopologyWorkerProtocol";
+
+/**
+ * Keep one watch topology and its native subscriptions on a worker thread.
+ *
+ * Case-policy probes, content digests and compiler listings must retain their
+ * actual observations. Replacing them with path-only case caches or size/mtime
+ * digests can miss directory replacements and source edits. They instead run
+ * off the launcher's loop so their cost cannot delay resident-host retirement
+ * or queued build decisions (#1758). This moves the cost; it does not remove
+ * it. Options and publications are cloned, while callbacks stay on the caller.
+ *
+ * Await a publication before the build reads its inputs. Moving that baseline
+ * past the build could absorb an intervening edit (#1728). Callback messages
+ * and completion replies share one FIFO channel, so whenIdle completes after
+ * the notifications its barrier observed have reached the launcher (#1756).
+ *
+ * @evidence contracts/common.md#principled-implementation A dedicated supported worker executes the unchanged topology algorithm on selected cloneable data while callbacks remain caller-owned; worker events and correlated replies settle actual operations, and one FIFO channel orders callbacks before completion.
+ * @evidence contracts/common.md#clear-and-simple-design The facade separates option capture, reply dispatch and worker lifetime; the synchronous core retains filesystem policy and watcher ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Existing native case observations, compiler membership and content proofs remain authoritative. The explicit worker factory supplies transport without replacing globals, and the default starts the actual packaged CommonJS entry without a synchronous barrier or metadata shortcut.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains off-thread cost, baseline-before-build ordering, FIFO replies and lifetime failures; constructor prose identifies data capture, callback ownership and the optional factory.
+ * @evidence contracts/portability.md#os-neutral-implementation Native joins locate the packaged CommonJS entry, and the supported module bootstrap loads it through createRequire while retaining Node-owned inherited execution options and loader hooks. Structured cloning preserves maps and bigint device references; SidecarEnvironment merges native environment names before startup.
+ * @evidence contracts/performance.md#efficient-algorithms One thread serves the topology lifetime. Construction copies fixed option references before cloning, with costs for option/environment bytes and module initialization; each operation clones its publication bytes and adds one pending entry while the core retains native costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work Construction starts a fresh worker lifetime; that worker retains current registrations, listing premises and baselines across requests, but completion grants no reuse for another filesystem generation.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One referenced worker, listeners, exit promise and uncapped pending map belong to the facade; creation failure precedes ownership transfer. Replies prune entries and failure rejects all entries. Close joins worker exit after native subscription close; failed close terminates and joins the thread while retaining error. Requests have no implicit deadline.
+ */
+export class AsyncWatchTopology {
+  private readonly worker: Worker;
+  private readonly exited: Promise<void>;
+  private readonly pending = new Map<
+    number,
+    { resolve(): void; reject(error: unknown): void }
+  >();
+  private sequence = 0;
+  private failure: unknown;
+  private failed = false;
+  private terminating = false;
+  private closing: Promise<void> | undefined;
+
+  /**
+   * Capture data options and start the worker; callbacks remain caller-owned.
+   * The optional factory observes worker transport without replacing globals.
+   */
+  public constructor(
+    options: WatchTopologyWorkerProtocol.Options,
+    private readonly callbacks: WatchTopologyWorkerProtocol.Callbacks,
+    createWorker: (options: WatchTopologyWorkerProtocol.Options) => Worker = (
+      selected,
+    ) =>
+      new Worker(
+        workerModuleUrl(
+          path.join(
+            __dirname,
+            `watchTopologyWorker${path.extname(__filename)}`,
+          ),
+        ),
+        {
+          env: SidecarEnvironment.merge(process.env, selected.env),
+          workerData: selected,
+        },
+      ),
+  ) {
+    // Callers also carry build callbacks. Select only the core's data options:
+    // sending the invocation wholesale would attempt to clone those functions.
+    const {
+      binary,
+      compilerArgsCwd,
+      compilerProjectSelections,
+      cwd,
+      emit,
+      env,
+      files,
+      outDir,
+      passthrough,
+      pinCompilerProject,
+      projectRoot,
+      tsconfig,
+    } = options;
+    this.worker = createWorker({
+      binary,
+      compilerArgsCwd,
+      compilerProjectSelections,
+      cwd,
+      emit,
+      env,
+      files,
+      outDir,
+      passthrough,
+      pinCompilerProject,
+      projectRoot,
+      tsconfig,
+    });
+    this.worker.on("message", (reply: WatchTopologyWorkerProtocol.Reply) => {
+      if ("id" in reply) {
+        const waiting = this.pending.get(reply.id);
+        if (waiting === undefined) return;
+        this.pending.delete(reply.id);
+        if (reply.ok) waiting.resolve();
+        else waiting.reject(reply.error);
+        return;
+      }
+      switch (reply.event) {
+        case "input":
+          this.callbacks.onInputChange(reply.change);
+          break;
+        case "topology":
+          this.callbacks.onTopologyChange();
+          break;
+        case "error":
+          this.callbacks.onError(reply.location, reply.error);
+          break;
+        case "roots":
+          this.callbacks.onProjectInputWatchRoots?.(reply.roots);
+          break;
+        case "unavailable":
+          this.callbacks.onProjectInputWatchUnavailable?.(reply.roots);
+          break;
+      }
+    });
+    this.worker.on("error", (error) => this.fail(error));
+    this.exited = new Promise<void>((resolve) => {
+      this.worker.once("exit", (code) => {
+        if (
+          this.closing === undefined ||
+          this.pending.size !== 0 ||
+          (code !== 0 && !this.terminating)
+        )
+          this.fail(
+            new Error(`ttsc: watch topology worker exited with code ${code}`),
+          );
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Reconcile actual compiler membership and wait for its publication.
+   *
+   * @evidence contracts/common.md#principled-implementation The worker executes the core's actual refresh before replying, so completion does not stand for a predicted membership.
+   * @evidence contracts/common.md#clear-and-simple-design This operation frames one refresh and delegates transport correlation to request.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Membership still comes from the core's native compiler-input reader.
+   * @evidence contracts/common.md#meaningful-documentation Prose states the membership and publication boundary.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The method frames a boolean; the worker and core own native execution.
+   * @evidence contracts/performance.md#efficient-algorithms Fixed-size framing adds one pending entry; the core retains listing, traversal and hashing costs off-thread.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Every requested refresh executes; listing reuse remains the core's decision.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Correlation remains live until reply or worker failure; no deadline is imposed.
+   */
+  public refresh(notify: boolean): Promise<void> {
+    return this.request({ method: "refresh", notify });
+  }
+
+  /**
+   * Capture plugin baselines before the caller starts reading or building.
+   *
+   * @evidence contracts/common.md#principled-implementation Awaited completion follows the core's baseline capture and preserves the supplied record store's separability references through structured cloning.
+   * @evidence contracts/common.md#clear-and-simple-design One publication carries inputs and their existing proof store together.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The actual content identity owner still judges every record; transport invents no digest or metadata equivalence.
+   * @evidence contracts/common.md#meaningful-documentation Prose states the required pre-build ordering.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Paths and bigint maps are cloned as data; the core owns native interpretation.
+   * @evidence contracts/performance.md#efficient-algorithms Framing is fixed structural work and cloning visits input paths and record references; digest and registration work stays with the core.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each publication reaches the core, which owns baseline and listing reuse premises.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Publication data and one pending correlation remain live through completion or worker failure without a size or deadline cap.
+   */
+  public setExtraInputs(
+    inputs: readonly string[],
+    identities?: PluginContentIdentities.Store,
+  ): Promise<void> {
+    return this.request({ method: "setExtraInputs", inputs, identities });
+  }
+
+  /**
+   * Capture rule-input baselines before the caller consumes those inputs.
+   *
+   * @evidence contracts/common.md#principled-implementation Completion follows actual declaration normalization, population capture and subscription reconciliation in the core.
+   * @evidence contracts/common.md#clear-and-simple-design One operation carries the complete declared snapshot without splitting population and baseline ownership.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The core retains missing-path, alias and empty-population semantics; transport filters no inputs.
+   * @evidence contracts/common.md#meaningful-documentation Prose states capture timing relative to consumption.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The snapshot crosses as data; the core owns filesystem identity and case policy.
+   * @evidence contracts/performance.md#efficient-algorithms Cloning visits the snapshot's path text; matching, fingerprinting and registrations keep their owning core costs.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The core decides whether a publication is equivalent; transport reuses no earlier result.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Snapshot bytes and one pending correlation remain live until reply or worker failure without a population cap.
+   */
+  public setProjectInputs(inputs: ITtscProjectInputSnapshot): Promise<void> {
+    return this.request({ method: "setProjectInputs", inputs });
+  }
+
+  /**
+   * Wait for delivered topology work and its preceding callback messages.
+   *
+   * @evidence contracts/common.md#principled-implementation The worker's core barrier observes its scheduled owners, and callbacks sent before the completion reply arrive first on the same FIFO channel.
+   * @evidence contracts/common.md#clear-and-simple-design One request exposes the core's complete queue ownership instead of duplicating queue flags here.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual queue completion replaces elapsed quiet-time estimates.
+   * @evidence contracts/common.md#meaningful-documentation Prose identifies delivered work and callback ordering.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The operation uses portable MessagePort ordering without a native path or process call.
+   * @evidence contracts/performance.md#efficient-algorithms Fixed-size framing adds one correlation; the core checks flags per yielded turn and still pays its pending operations' costs.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each barrier observes current pending work rather than a previous receipt.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources One request remains live until idle, close or failure; continuous new work can keep it pending without an implicit deadline.
+   */
+  public whenIdle(): Promise<void> {
+    return this.request({ method: "whenIdle" });
+  }
+
+  /**
+   * Close subscriptions and join the thread. Repeated calls share retirement;
+   * close or worker failures remain rejection even after thread termination.
+   *
+   * @evidence contracts/common.md#principled-implementation Successful close follows core subscription release, outstanding barrier answers and actual worker exit; failed close terminates and joins the thread while preserving rejection.
+   * @evidence contracts/common.md#clear-and-simple-design One retained promise owns idempotent shutdown and finishClose owns its two retirement paths.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Shutdown joins actual thread exit rather than treating a posted close as completion.
+   * @evidence contracts/common.md#meaningful-documentation Prose states joined completion, repeated-call sharing and failure retention.
+   * @evidence contracts/portability.md#os-neutral-implementation Node's supported worker exit and termination APIs own thread retirement; the core owns backend subscription closure.
+   * @evidence contracts/performance.md#efficient-algorithms One close message and shared promise add fixed structural work; subscription traversal, outstanding replies and thread retirement retain delegated costs.
+   * @evidence contracts/performance.md#reuse-equivalent-work Every repeated close shares this lifetime's single retirement result, including rejection.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Closure rejects new requests and joins the worker; pending requests settle by replies or terminal failure. Native FSEvents stop errors are suppressed by its existing backend, so thread joining alone cannot certify that optional binding's physical cleanup.
+   */
+  public close(): Promise<void> {
+    this.closing ??= this.finishClose();
+    return this.closing;
+  }
+
+  private async finishClose(): Promise<void> {
+    try {
+      await this.request({ method: "close" });
+    } catch (error) {
+      this.terminating = true;
+      await this.worker.terminate();
+      await this.exited;
+      throw error;
+    }
+    await this.exited;
+    if (this.failed) throw this.failure;
+  }
+
+  private request(
+    operation: WatchTopologyWorkerProtocol.Operation,
+  ): Promise<void> {
+    if (this.failed) return Promise.reject(this.failure);
+    if (this.closing !== undefined)
+      return Promise.reject(new Error("ttsc: watch topology is closing"));
+    const id = ++this.sequence;
+    return new Promise<void>((resolve, reject) => {
+      this.pending.set(id, { reject, resolve });
+      try {
+        this.worker.postMessage({ ...operation, id });
+      } catch (error) {
+        this.pending.delete(id);
+        reject(error);
+      }
+    });
+  }
+
+  private fail(error: unknown): void {
+    if (this.failed) return;
+    this.failed = true;
+    this.failure = error;
+    for (const waiting of this.pending.values()) waiting.reject(error);
+    this.pending.clear();
+    this.callbacks.onFailure(error);
+  }
+}

package/src/launcher/internal/watch/WatchSettlement.ts

@@ -0,0 +1,67 @@
+/**
+ * Waits for an owner's idle observation without losing changes during that
+ * observation. The owner announces every scheduling and terminal transition.
+ *
+ * Elapsed silence cannot certify idle: a queued build or an asynchronous input
+ * decision can remain silent until it starts. A changed revision therefore
+ * requires another observation, even when the earlier one reported idle.
+ *
+ * @evidence contracts/common.md#principled-implementation A monotonic revision detects transitions across an asynchronous idle query; wait registration and the final revision comparison share one JavaScript turn, preventing a lost wake.
+ * @evidence contracts/common.md#clear-and-simple-design The owner supplies its actual idle predicate and announces state changes; this class owns only revision validation and waiting callbacks.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No timeout, retry limit, process hook or consumer-specific decision substitutes for the owner's state.
+ * @evidence contracts/common.md#meaningful-documentation Prose defines idle-query ownership and why silent queued work and intervening changes require a fresh observation; methods describe notification and failure effects.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Revisions and promises have no native path, filesystem or process boundary.
+ * @evidence contracts/performance.md#efficient-algorithms Each transition visits current waiters once; each observation is constant bookkeeping plus the supplied owner's work, without polling.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each wait observes mutable owner state independently; no computed result is cached across transitions.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources A non-idle wait registers one callback until the next transition; an in-flight idle query or publication retains its call closure until settlement. Errors reject directly. The owner must announce terminal transitions so registered callbacks can recheck and reject. Concurrent caller population has no fixed cap.
+ */
+export class WatchSettlement {
+  private revision = 0;
+  private readonly waiters = new Set<() => void>();
+
+  /**
+   * Announces a scheduling or terminal transition and releases current waits.
+   *
+   * @evidence contracts/common.md#principled-implementation Advancing the revision invalidates queries already in flight, and releasing the current callback population permits each pending wait to query again.
+   * @evidence contracts/common.md#clear-and-simple-design One notification handles both ordinary scheduling and terminal transitions without interpreting the owner's state.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Callbacks observe a real owner transition without polling or replacing owner operations.
+   * @evidence contracts/common.md#meaningful-documentation The prose states which transitions callers announce and that current waits are released.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This in-memory notification has no native boundary.
+   * @evidence contracts/performance.md#efficient-algorithms Copying and waking current callbacks costs linear time and temporary space in pending waits.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This effectful transition does not compute a reusable result.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Clearing the set releases its references before callbacks run; each resumed wait owns any later registration.
+   */
+  public changed(): void {
+    ++this.revision;
+    const waiters = [...this.waiters];
+    this.waiters.clear();
+    for (const wake of waiters) wake();
+  }
+
+  /**
+   * Publishes and resolves after an idle query spans no transition; errors
+   * reject. The owner must reject its query after shutdown and announce that
+   * shutdown. Publication starts in the same turn as the final revision check.
+   *
+   * @evidence contracts/common.md#principled-implementation The revision comparison validates the complete awaited observation; publication starts synchronously after that comparison, and a non-idle result registers its wake in the same turn, so neither path loses an intervening transition.
+   * @evidence contracts/common.md#clear-and-simple-design The loop retries only after a real transition and delegates all idle and terminal meaning to the supplied owner query.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No elapsed silence, deadline or fixed retry count stands for the owner's actual pending work.
+   * @evidence contracts/common.md#meaningful-documentation The prose describes successful observation, same-turn publication, error propagation and the terminal notification obligation.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Awaiting an owner query imposes no native path or process policy.
+   * @evidence contracts/performance.md#efficient-algorithms Each query adds constant revision bookkeeping and at most one callback; query work belongs to the supplied owner, and no timer polls state.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Queries observe mutable state and are not cached across transitions.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources A non-idle observation retains one resolver until changed clears it; successful and failed queries retain no registered callback, while an in-flight query or publication retains this call until settlement. Terminal wake and rejection are the owner's obligation.
+   */
+  public async wait(
+    idle: () => Promise<boolean>,
+    publish: () => void | Promise<void> = () => {},
+  ): Promise<void> {
+    for (;;) {
+      const revision = this.revision;
+      const observed = await idle();
+      if (revision !== this.revision) continue;
+      if (observed) return await publish();
+      await new Promise<void>((resolve) => this.waiters.add(resolve));
+    }
+  }
+}

package/src/launcher/internal/watch/WatchTopology.ts

@@ -7,6 +7,7 @@ import { CompilerProjectSelection } from "../../../compiler/internal/project/Com
 import { readJsoncFile } from "../../../compiler/internal/project/readJsoncFile";
 import { readProjectConfig } from "../../../compiler/internal/project/readProjectConfig";
 import { resolveTsgo } from "../../../compiler/internal/resolveTsgo";
+import { SidecarEnvironment } from "../../../compiler/internal/sharedHost/SidecarEnvironment";
 import { spawnNative } from "../../../compiler/internal/spawnNative";
 import { normalizeCompilerEnumValue } from "../../../flags/normalizeCompilerEnumValue";
 import { readCompilerOptionValues } from "../../../flags/readCompilerOptionValues";
@@ -64,7 +65,7 @@ import { watchDirectory } from "./watchDirectory";
  * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain membership authority, plugin fingerprinting, publication races, physical registration and public lifecycle operations following the documentation skill. Parameters identify each supplied operation and native default beside the constructor. Project-input attribution: Native paragraphs explain stale attention, directory causality, accompanying resolution digests and unselected immediate entries.
  * @evidence contracts/portability.md#os-neutral-implementation Native paths use Node APIs and registration uses realpath; compiler/plugin maps preserve lexical aliases and fold only measured insensitive ASCII components. Project inputs use physical identities, while unknown/native Unicode relations remain conservative event candidates rather than identity proof. Registration paths and read options are passed unchanged; compiler-input readers supply absolute membership paths without replacing the topology's native identity policy. Project-input attribution: The supplied filesystem identity transaction establishes selected names and ancestry without an OS-wide case assumption or lexical alias guess.
  *
- * @evidence contracts/performance.md#efficient-algorithms Identity-keyed maps separate membership, baselines and handle registries; reconciliation delegates project/config discovery, native compiler listing, filesystem traversal/hashing and backend callbacks, with costs described by its members. Construction retains operation references and empty indexes without a filesystem observation or build. Attribution indexed visits additionally pay path/key text, ancestor and native identity work; shared ancestor keys avoid repeating the same walk within a transaction.
+ * @evidence contracts/performance.md#efficient-algorithms Identity-keyed maps separate membership, baselines and handle registries; reconciliation delegates project/config discovery, native compiler listing, filesystem traversal/hashing and backend callbacks, with costs described by its members. A directory-triggered refresh additionally visits R active reload files even on failure and compares their metadata/owner snapshots, reading bytes only when those snapshots changed. Changed-owner and notification arrays and a reported-key set require O(R) references; moved owners share one existing watcher synchronization and post-registration reconciliation, whose selected-file traversal remains part of the operation. No additional compiler listing is requested. Construction retains operation references and empty indexes without a filesystem observation or build. Attribution indexed visits additionally pay path/key text, ancestor and native identity work; shared ancestor keys avoid repeating the same walk within a transaction.
  * @evidence contracts/performance.md#reuse-equivalent-work Current membership, content baselines and live registrations belong to one topology; reconciliation owners decide their reuse against fresh premises. Supplied operation identities are retained without assuming changed inputs remain equivalent. Each project's last compiler listing is kept with its arguments and answers only a plugin-input change, which cannot move Program membership; every other refresh lists again. Notifications delivered in one poll iteration are decided together in the check phase, so one change lists and rescans once. Project-input attribution: This classifier borrows one scan's deltas and identity transaction without retaining cross-event answers.
  * @evidence contracts/performance.md#bound-retention-and-release-resources Current and pending maps and live subscriptions remain topology-owned without a population cap; compiler listings are replaced by each resolution and hold only its projects; reconciliation attempts obsolete handle retirement. Constructor acquires no handle; directory arrays and attribution deltas are call-local. close invokes supplied close methods but does not await backend closure, and a thrown close can interrupt later map cleanup; retained snapshots remain until the facade is released.
  */
@@ -216,6 +217,39 @@ export class WatchTopology {
     this.refreshCompilerInputs(notify, false);
   }
 
+  /**
+   * Wait until delivered notifications and registration reconciliation finish.
+   *
+   * A completed build does not imply a quiet topology: its final refresh can
+   * queue another decision and another build (#1756). Yield through the check
+   * phase before inspecting every scheduled owner so a decision queued by
+   * another decision remains part of this barrier. Later filesystem changes
+   * belong to a later barrier; this does not freeze the filesystem.
+   *
+   * @evidence contracts/common.md#principled-implementation A check-phase observation follows delivered events, and every notification, recovery and registration queue must be empty before completion.
+   * @evidence contracts/common.md#clear-and-simple-design The topology owns the barrier because it alone owns all five scheduled queues.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Queue state establishes completion without a quiet-time estimate or an invented filesystem snapshot.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes delivered work from later mutations and explains the post-build queued-decision race.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The barrier observes owned JavaScript queues without a separate native operation.
+   * @evidence contracts/performance.md#efficient-algorithms Each check turn inspects five flags and two map sizes; notification processing retains its owning traversal and native-operation costs.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call observes current work rather than reusing an earlier completion.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources One immediate callback and promise remain live per waiting call; continuous new work can prevent completion and no deadline is imposed.
+   */
+  public async whenIdle(): Promise<void> {
+    do {
+      await new Promise<void>((resolve) => setImmediate(resolve));
+    } while (
+      !this.closed &&
+      (this.notificationsScheduled ||
+        this.pluginNotificationsScheduled ||
+        this.compilerPostRegistrationReconciliationScheduled ||
+        this.projectInputRecoveryScheduled ||
+        this.projectInputPostRegistrationReconciliationScheduled ||
+        this.pendingNotifications.size !== 0 ||
+        this.pendingPluginNotifications.size !== 0)
+    );
+  }
+
   /**
    * @param reuseListings Answer each project's membership with its last listing
    *   under the same arguments instead of asking the compiler again. Only a
@@ -1711,6 +1745,15 @@ export class WatchTopology {
    * Refresh compiler membership once for every directory a decision asked
    * about. A failed refresh still reports, once each, the reload inputs every
    * requested change names.
+   *
+   * A replacement can be delivered under only its vanished temporary name,
+   * including when its malformed bytes prevent refresh. Reconcile active
+   * reload-file snapshots on either outcome, deduplicate failed-refresh
+   * recovery against actual reported movement, and preserve the original
+   * refresh error after recovery. Batch moved owners through the existing rearm
+   * operation before notifying, because a POSIX per-file handle still owns the
+   * old inode. Unchanged snapshots stay quiet unless the existing
+   * failed-refresh selector explicitly names or cannot find the reload input.
    */
   private refreshFromDirectories(refreshes: readonly DirectoryRefresh[]): void {
     for (const { changed } of refreshes) {
@@ -1723,23 +1766,50 @@ export class WatchTopology {
         this.observedDirectories.set(this.pathKey(changed), changed);
       }
     }
+    let refreshFailure: { error: unknown } | undefined;
     try {
       this.refresh(true);
     } catch (error) {
+      refreshFailure = { error };
+    }
+    try {
+      if (this.closed) return;
+      const changed: string[] = [];
+      const rearm: string[] = [];
       const reported = new Set<string>();
-      for (const { changed } of refreshes) {
-        for (const reload of reloadInputsForFailedTopologyRefresh(
-          this.reloadFiles.values(),
-          changed,
-          this.lexicalIdentities,
-        )) {
-          const key = this.pathKey(reload);
-          if (reported.has(key)) continue;
-          reported.add(key);
-          this.callbacks.onInputChange({ kind: "config", path: reload });
+      for (const reload of this.reloadFiles.values()) {
+        if (this.closed) return;
+        const movement = this.compilerFileMovement(reload);
+        if (movement.owner) rearm.push(reload);
+        if (this.compilerMovementReports(reload, movement))
+          changed.push(reload);
+      }
+      if (rearm.length !== 0) this.rearmFileWatchers(rearm, true);
+      for (const reload of changed) {
+        if (this.closed) return;
+        reported.add(this.pathKey(reload));
+        this.reportCompilerFileChange(reload);
+      }
+      if (refreshFailure !== undefined) {
+        for (const { changed } of refreshes) {
+          for (const reload of reloadInputsForFailedTopologyRefresh(
+            this.reloadFiles.values(),
+            changed,
+            this.lexicalIdentities,
+          )) {
+            if (this.closed) return;
+            const key = this.pathKey(reload);
+            if (reported.has(key)) continue;
+            reported.add(key);
+            this.callbacks.onInputChange({ kind: "config", path: reload });
+          }
         }
       }
+    } catch (error) {
       this.callbacks.onError(refreshes[0]!.location, error);
+    } finally {
+      if (refreshFailure !== undefined)
+        this.callbacks.onError(refreshes[0]!.location, refreshFailure.error);
     }
   }
 
@@ -2203,10 +2273,11 @@ function listCompilerInputs(
   project: ITtscParsedProjectConfig,
   options: WatchTopologyOptions,
 ): string[] {
+  const env = SidecarEnvironment.merge(process.env, options.env);
   const tsgo = resolveTsgo({
     binary: options.binary,
     cwd: project.root,
-    env: options.env,
+    env,
   });
   const result = spawnNative(
     tsgo.binary,
@@ -2221,7 +2292,7 @@ function listCompilerInputs(
     ],
     {
       cwd: options.compilerArgsCwd ?? project.root,
-      env: { ...process.env, ...options.env },
+      env,
       encoding: "utf8",
     },
   );

package/src/launcher/internal/watch/WatchTopologyWorkerProtocol.ts

@@ -0,0 +1,106 @@
+import type { PluginContentIdentities } from "../../../plugin/internal/source/PluginContentIdentities";
+import type { ITtscProjectInputSnapshot } from "../../../structures/internal/ITtscProjectInputSnapshot";
+import type { WatchInputChange } from "./WatchInputChange";
+import type { WatchTopology } from "./WatchTopology";
+
+/**
+ * Cloned requests and ordered notifications of one watch topology worker.
+ *
+ * @evidence contracts/common.md#principled-implementation Discriminated messages preserve operation arguments and separate callbacks from request completion; bigint reference maps retain the record store's separability evidence through structured cloning.
+ * @evidence contracts/common.md#clear-and-simple-design One internal protocol serves the facade and its worker without transferring callback functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Messages carry actual topology operations and observations rather than predicted decisions.
+ * @evidence contracts/common.md#meaningful-documentation Members identify correlation, callback ordering and the cloneable option boundary.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The types describe structured messages; execution owns native paths and workers.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms These types execute no algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The protocol grants no result reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The types acquire no resources; the facade owns in-flight messages.
+ */
+export namespace WatchTopologyWorkerProtocol {
+  /**
+   * Only the core's selected data options cross the worker boundary.
+   *
+   * @evidence contracts/common.md#principled-implementation Deriving the data type from the core constructor keeps option meaning with its owner.
+   * @evidence contracts/common.md#clear-and-simple-design One alias serves both ends of the worker's startup payload.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The facade explicitly selects these fields without transferring invocation callbacks.
+   * @evidence contracts/common.md#meaningful-documentation Prose identifies the cloneable startup boundary.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This alias executes no native operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms The alias chooses no algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The type grants no reuse.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The type acquires no resource; the facade owns startup cloning.
+   */
+  export type Options = ConstructorParameters<typeof WatchTopology>[0];
+
+  /**
+   * Callback implementations remain on the launcher thread.
+   *
+   * @evidence contracts/common.md#principled-implementation Core callbacks retain their meanings; actual worker error or unexpected exit invokes separate terminal notification because authority was lost, requiring the launcher to retire its session.
+   * @evidence contracts/common.md#clear-and-simple-design One structural intersection adds a dedicated terminal callback beside recoverable subscription events.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Callbacks report actual observations and authority loss without continuing to claim coverage after thread death.
+   * @evidence contracts/common.md#meaningful-documentation Prose identifies launcher-thread callbacks and the receiving owner's required retirement after terminal loss.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation These signatures perform no native operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms Callback signatures choose no algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Callback declarations grant no event reuse; terminal failure belongs to one lifecycle.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Signatures acquire no resources; callback implementations own session retention and cleanup.
+   */
+  export type Callbacks = ConstructorParameters<typeof WatchTopology>[1] & {
+    /** Terminal thread loss requires the launcher to retire its watch session. */
+    onFailure(error: unknown): void;
+  };
+
+  /**
+   * An operation carries only the arguments its core member consumes.
+   *
+   * @evidence contracts/common.md#principled-implementation Discriminated method names pair each actual operation with its required payload.
+   * @evidence contracts/common.md#clear-and-simple-design One union describes the core's five transport operations.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Publications retain complete input snapshots and source proof stores without filtering.
+   * @evidence contracts/common.md#meaningful-documentation Prose identifies argument ownership and discriminated payloads.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The union executes no native operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms The type chooses no algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The payload grants no result reuse.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Transport and core owners retain cloned payloads rather than this type.
+   */
+  export type Operation =
+    | { method: "refresh"; notify: boolean }
+    | {
+        method: "setExtraInputs";
+        inputs: readonly string[];
+        identities?: PluginContentIdentities.Store;
+      }
+    | { method: "setProjectInputs"; inputs: ITtscProjectInputSnapshot }
+    | { method: "whenIdle" }
+    | { method: "close" };
+
+  /**
+   * Each operation receives its own correlated completion or failure.
+   *
+   * @evidence contracts/common.md#principled-implementation A per-facade monotonic id distinguishes concurrent pending operations.
+   * @evidence contracts/common.md#clear-and-simple-design Correlation is one field intersected with the operation union.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts An id identifies the actual request rather than an assumed ordered result.
+   * @evidence contracts/common.md#meaningful-documentation Prose states correlation and terminal outcomes.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The representation performs no native operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms This type runs no algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Request identity grants no reuse.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The facade owns pending correlation entries.
+   */
+  export type Request = { id: number } & Operation;
+
+  /**
+   * Callbacks and answers use one FIFO port, preserving their causal order.
+   *
+   * @evidence contracts/common.md#principled-implementation Event tags distinguish callbacks from correlated success or failure, and one MessagePort orders callback transmission before operation completion.
+   * @evidence contracts/common.md#clear-and-simple-design One union carries observed changes, coverage reports, recoverable errors and request outcomes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Failures retain serialized causes and actual observed input paths; no expected response replaces them.
+   * @evidence contracts/common.md#meaningful-documentation Prose states causal FIFO ordering.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The union describes portable message data without a native operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms The type chooses no algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each message belongs to its actual event or operation.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Message and correlation retention belongs to worker and facade implementations.
+   */
+  export type Reply =
+    | { id: number; ok: true }
+    | { id: number; ok: false; error: unknown }
+    | { event: "input"; change: WatchInputChange }
+    | { event: "topology" }
+    | { event: "error"; location: string; error: unknown }
+    | { event: "roots" | "unavailable"; roots: readonly string[] };
+}