@telorun/kernel 0.78.0 → 0.80.0

package/src/controller-loader.ts

@@ -39,10 +39,44 @@ export interface ResolvedController {
   purl: string;
   source: ControllerResolveSource;
   importInstance: () => Promise<ControllerInstance>;
+  /**
+   * How long the caller has waited for this controller, measured from the
+   * first {@link ControllerWorkKind} branch it entered — or, when it entered
+   * none, from the `importInstance()` call. Resolution is what installs,
+   * compiles and fetches, so timing only the import reports a 40-second
+   * install as a few milliseconds.
+   */
+  waitedMs: () => number;
 }
 
+/**
+ * A branch that makes the caller wait: a registry install, a compile, or a
+ * layer transfer. Reported by the sub-loader that is about to enter it, which
+ * is the only place that knows — a resolve's `source` is a verdict available
+ * only afterwards, and a warm start enters no branch at all, so nothing is
+ * announced for it. Reported for work in the resolve *and* the import phase:
+ * a dev-mode `pkg:telo` build and a `cargo build` are both paid inside
+ * `importInstance`.
+ */
+export type ControllerWorkKind = "npm-install" | "cargo-build" | "source-build" | "layer-fetch";
+
+/**
+ * Sub-loader hook, invoked immediately before entering a {@link
+ * ControllerWorkKind} branch. Awaited, so a consumer that renders progress has
+ * its line on screen before the wait starts rather than after it.
+ */
+export type ControllerWorkReporter = (work: ControllerWorkKind) => void | Promise<void>;
+
 export type ControllerLoaderEvent =
-  | { name: "ControllerLoading"; payload: { purl: string } }
+  /**
+   * A resolved controller is about to be imported. `source` names the branch
+   * the resolve took, so a consumer can tell a warm start (`cache` / `local`)
+   * from work someone waited for (`npm-install`, `cargo-build`, `bundle`)
+   * *before* rendering anything. The event is emitted after resolution
+   * precisely so this is known: resolution is what fetches, installs and
+   * builds, and an event emitted ahead of it could only speculate.
+   */
+  | { name: "ControllerLoading"; payload: { purl: string; source: ControllerResolveSource } }
   | {
       name: "ControllerLoaded";
       payload: { purl: string; source: ControllerResolveSource; durationMs: number };
@@ -55,7 +89,15 @@ export type ControllerLoaderEvent =
    * which is non-recoverable. Consumers that opened a UI element on the
    * matching `ControllerLoading` should close it out here.
    */
-  | { name: "ControllerLoadSkipped"; payload: { purl: string; reason: string } };
+  | { name: "ControllerLoadSkipped"; payload: { purl: string; reason: string } }
+  /**
+   * Real work has started for `purl` — an install, a compile or a transfer is
+   * about to run. This is the *only* in-progress signal, and it fires solely
+   * on the branch that does the work, so a warm start emits nothing rather
+   * than something a consumer has to take back. Closed by the matching
+   * `ControllerLoaded` / `ControllerLoadFailed`.
+   */
+  | { name: "ControllerWorkStarted"; payload: { purl: string; work: ControllerWorkKind } };
 
 /**
  * The dispatcher awaits each emission, so the callback may be async without
@@ -104,9 +146,13 @@ export interface ControllerLoaderOptions {
  * next candidate. User-code failures (`RuntimeError("ERR_CONTROLLER_BUILD_FAILED" | "ERR_CONTROLLER_INVALID")`)
  * fail hard regardless of remaining candidates.
  *
- * Lifecycle events are emitted per *attempt*, so a fallback chain produces one
- * `ControllerLoading` per candidate tried plus a final `ControllerLoaded` (or
- * `ControllerLoadFailed`) for the one that won.
+ * Lifecycle events follow resolution: a candidate this environment cannot host
+ * produces a `ControllerLoadSkipped` and nothing else, and only the candidate
+ * that resolved gets a `ControllerLoading` (carrying its resolve `source`)
+ * followed by `ControllerLoaded` / `ControllerLoadFailed`. In between, the
+ * sub-loader announces each branch that makes the caller wait as
+ * `ControllerWorkStarted` — the only in-progress signal, and the only one that
+ * cannot be emitted for a warm start.
  */
 export class ControllerLoader {
   private readonly emit: ControllerLoaderEmit | undefined;
@@ -121,7 +167,7 @@ export class ControllerLoader {
       installRoot: options.installRoot,
     });
     if (options.log) this.npmLoader.setLogger(options.log);
-    this.napiLoader = new NapiControllerLoader();
+    this.napiLoader = new NapiControllerLoader(options.cacheRoot);
     this.bundleLoader = new BundleControllerLoader(options.cacheRoot, options.log);
   }
 
@@ -132,56 +178,28 @@ export class ControllerLoader {
     artifact?: ModuleArtifact,
     libraries: SiblingLibraryMap = NO_SIBLING_LIBRARIES,
   ): Promise<ControllerInstance> {
-    if (!purlCandidates || purlCandidates.length === 0) {
-      throw new RuntimeError("ERR_CONTROLLER_NOT_FOUND", "Missing controller PURL candidates");
-    }
-    const effectivePolicy = policy ?? DEFAULT_POLICY;
-    const ordered = orderCandidates(purlCandidates, effectivePolicy);
-    if (ordered.length === 0) {
-      throw new RuntimeError(
-        "ERR_CONTROLLER_NOT_FOUND",
-        `No controllers match runtime selection [${effectivePolicy.load.join(", ")}]; declared: ${purlCandidates.join(", ")}`,
-      );
-    }
-
-    const errors: string[] = [];
-    for (const purl of ordered) {
-      await this.emit?.({ name: "ControllerLoading", payload: { purl } });
-      const startedAt = Date.now();
-      try {
-        const { instance, source } = await this.dispatchOne(purl, baseUri, artifact, libraries);
-        await this.emit?.({
-          name: "ControllerLoaded",
-          payload: { purl, source, durationMs: Date.now() - startedAt },
-        });
-        return instance;
-      } catch (err) {
-        if (err instanceof ControllerEnvMissingError) {
-          errors.push(`${purl}: ${err.message}`);
-          // Env-missing isn't a hard failure — the dispatcher will try the
-          // next candidate. We still emit a terminal event for *this* attempt
-          // so consumers (notably the CLI progress renderer) can close out
-          // the UI state opened by the matching ControllerLoading. Without
-          // this, every fallback attempt would leak a pending `⬇` line.
-          await this.emit?.({
-            name: "ControllerLoadSkipped",
-            payload: { purl, reason: err.message },
-          });
-          continue;
-        }
-        await this.emit?.({
-          name: "ControllerLoadFailed",
-          payload: { purl, error: err instanceof Error ? err.message : String(err) },
-        });
-        throw err;
-      }
-    }
-    const aggregated = `No controller resolved. Tried ${ordered.length} candidate(s):\n${errors.join("\n")}`;
+    // Resolution — which is what installs, compiles and fetches — reports its
+    // own work and its own candidate fallthrough, so this is the import half
+    // and the announcement of what resolution decided.
+    const resolved = await this.resolve(purlCandidates, baseUri, policy, artifact, libraries);
     await this.emit?.({
-      name: "ControllerLoadFailed",
-      payload: { purl: ordered[ordered.length - 1], error: aggregated },
+      name: "ControllerLoading",
+      payload: { purl: resolved.purl, source: resolved.source },
     });
-    throw new RuntimeError("ERR_CONTROLLER_NOT_FOUND", aggregated);
+    try {
+      const instance = await resolved.importInstance();
+      await this.emit?.({
+        name: "ControllerLoaded",
+        payload: { purl: resolved.purl, source: resolved.source, durationMs: resolved.waitedMs() },
+      });
+      return instance;
+    } catch (err) {
+      await this.emit?.({
+        name: "ControllerLoadFailed",
+        payload: { purl: resolved.purl, error: err instanceof Error ? err.message : String(err) },
+      });
+      throw err;
+    }
   }
 
   /**
@@ -194,10 +212,12 @@ export class ControllerLoader {
    * registers fine and errors only when a resource of it is declared (matching
    * the Rust kernel's deferral).
    *
-   * Silent by design — no lifecycle events here; the caller emits
-   * ControllerLoading/Loaded around `importInstance` so the events fire when the
-   * load actually happens. A total resolution failure throws, mirroring
-   * {@link load}'s aggregated error.
+   * Emits `ControllerWorkStarted` whenever a sub-loader enters a branch that
+   * makes the caller wait, and `ControllerLoadSkipped` per candidate this
+   * environment cannot host. It does NOT announce the load itself: the caller
+   * emits ControllerLoading/Loaded around `importInstance`, so those fire when
+   * the load actually happens, with the resolved `source` already in hand. A
+   * total resolution failure throws, mirroring {@link load}'s aggregated error.
    */
   async resolve(
     purlCandidates: string[],
@@ -219,41 +239,54 @@ export class ControllerLoader {
     }
     const errors: string[] = [];
     for (const purl of ordered) {
+      // First work only: an install followed by a compile is one wait, and the
+      // clock the caller reads has to start where that wait did. The reporter
+      // outlives resolution because the import phase does work too.
+      let workStartedAt: number | undefined;
+      const report: ControllerWorkReporter = async (work) => {
+        workStartedAt ??= Date.now();
+        await this.emit?.({ name: "ControllerWorkStarted", payload: { purl, work } });
+      };
       try {
         const { source, importInstance } = await this.dispatchResolveOne(
           purl,
           baseUri,
           artifact,
           libraries,
+          report,
         );
-        return { purl, source, importInstance };
+        let importStartedAt: number | undefined;
+        return {
+          purl,
+          source,
+          importInstance: () => {
+            importStartedAt ??= Date.now();
+            return importInstance();
+          },
+          waitedMs: () => Date.now() - (workStartedAt ?? importStartedAt ?? Date.now()),
+        };
       } catch (err) {
         if (err instanceof ControllerEnvMissingError) {
           errors.push(`${purl}: ${err.message}`);
+          await this.emit?.({
+            name: "ControllerLoadSkipped",
+            payload: { purl, reason: err.message },
+          });
           continue;
         }
+        await this.emit?.({
+          name: "ControllerLoadFailed",
+          payload: { purl, error: err instanceof Error ? err.message : String(err) },
+        });
         throw err;
       }
     }
-    throw new RuntimeError(
-      "ERR_CONTROLLER_NOT_FOUND",
-      `No controller resolved. Tried ${ordered.length} candidate(s):\n${errors.join("\n")}`,
-    );
-  }
-
-  private async dispatchOne(
-    purl: string,
-    baseUri: string,
-    artifact: ModuleArtifact | undefined,
-    libraries: SiblingLibraryMap,
-  ): Promise<{ instance: ControllerInstance; source: ControllerResolveSource }> {
-    const { source, importInstance } = await this.dispatchResolveOne(
-      purl,
-      baseUri,
-      artifact,
-      libraries,
-    );
-    return { instance: await importInstance(), source };
+    const aggregated = `No controller resolved. Tried ${ordered.length} candidate(s):\n${errors.join("\n")}`;
+    await this.emit?.({
+      name: "ControllerLoadFailed",
+      payload: { purl: ordered[ordered.length - 1], error: aggregated },
+    });
+    throw new RuntimeError("ERR_CONTROLLER_NOT_FOUND", aggregated);
   }
 
   private async dispatchResolveOne(
@@ -261,15 +294,16 @@ export class ControllerLoader {
     baseUri: string,
     artifact: ModuleArtifact | undefined,
     libraries: SiblingLibraryMap,
+    report: ControllerWorkReporter,
   ): Promise<{ source: ControllerResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     if (purl.startsWith("pkg:npm")) {
-      return this.npmLoader.resolve(purl, baseUri);
+      return this.npmLoader.resolve(purl, baseUri, report);
     }
     if (purl.startsWith("pkg:cargo")) {
-      return this.napiLoader.resolve(purl, baseUri);
+      return this.napiLoader.resolve(purl, baseUri, report);
     }
     if (purl.startsWith("pkg:telo")) {
-      return this.bundleLoader.resolve(purl, baseUri, artifact, libraries);
+      return this.bundleLoader.resolve(purl, baseUri, artifact, libraries, report);
     }
     throw new ControllerEnvMissingError(`Unsupported PURL scheme: ${purl}`);
   }

package/src/controller-loaders/bundle-loader.ts

@@ -7,7 +7,7 @@ import { PackageURL } from "packageurl-js";
 import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { hostPlatformTarget, type ModuleArtifact } from "../bundle/module-artifact.js";
-import type { ControllerResolveSource } from "../controller-loader.js";
+import type { ControllerResolveSource, ControllerWorkReporter } from "../controller-loader.js";
 import { ControllerEnvMissingError } from "./napi-loader.js";
 import { REALM_COLLAPSE_NAMES } from "./realm.js";
 import {
@@ -485,6 +485,7 @@ export class BundleControllerLoader {
     baseUri: string,
     artifact?: ModuleArtifact,
     libraries: SiblingLibraryMap = NO_SIBLING_LIBRARIES,
+    report?: ControllerWorkReporter,
   ): Promise<{ source: ControllerResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     let parsed: PackageURL;
     try {
@@ -578,10 +579,17 @@ export class BundleControllerLoader {
         importInstance: async () => {
           let built: string;
           try {
+            // A dev build is a compile the caller waits on, and it is paid here
+            // rather than at resolve — which is why the work signal is not tied
+            // to the resolve phase. The reporter goes INTO the builder rather
+            // than wrapping the call: only the builder knows whether its
+            // content-addressed cache answered, and reporting a cache hit would
+            // put a line on screen for work nobody waited for.
             built = await buildControllerFromSource(
               sourceFile!,
               cacheRoot!,
               buildExternals(libraries, format),
+              report,
             );
           } catch (err) {
             if (!(err instanceof ControllerEnvMissingError)) throw err;
@@ -607,7 +615,7 @@ export class BundleControllerLoader {
     if (artifact) {
       // By its own selector, not by re-matching the host: this candidate IS one
       // selector, and it is exactly the key of the layer that carries it.
-      const resolved = await artifact.materializeController(selector);
+      const resolved = await artifact.materializeController(selector, report);
       if (!resolved) {
         throw new ControllerEnvMissingError(
           `pkg:telo controller "${purl}": the module artifact ships no layer for ` +

package/src/controller-loaders/napi-loader.ts

@@ -8,6 +8,8 @@ import { fileURLToPath } from "url";
 import { promisify } from "util";
 
 import { hostEnv } from "../host-env.js";
+// Type-only, so the cycle with the dispatcher that imports this loader is erased.
+import type { ControllerWorkReporter } from "../controller-loader.js";
 
 const execFileAsync = promisify(execFile);
 const requireFromHere = createRequire(import.meta.url);
@@ -104,6 +106,34 @@ export interface NapiLoadResult {
 }
 
 export class NapiControllerLoader {
+  /**
+   * The `.telo` cache root this kernel resolved, or `undefined` when it resolved
+   * none (a memory-rooted entry), in which case cargo's own default is used.
+   *
+   * The build is anchored here for the same reason the Rust kernel's is: one
+   * shared dependency build per workspace instead of one per crate, and — the
+   * load-bearing half — a directory KEYED BY SDK BACKEND. This loader builds a
+   * controller crate with `telorun-sdk/napi` while `telo-rs` builds the very same
+   * crate with `native`, and a plain `cargo build --workspace` builds it with
+   * neither. All three sharing one target directory means each alternation
+   * rebuilds the crate and its dependency tree; before this they were kept apart
+   * only by the accident that this loader took cargo's default.
+   */
+  private readonly cacheRoot?: string;
+
+  constructor(cacheRoot?: string) {
+    this.cacheRoot = cacheRoot;
+  }
+
+  /** `CARGO_TARGET_DIR` for this loader's builds, or `undefined` to leave cargo's
+   *  own resolution alone. Applied to `cargo metadata` as well as `cargo build`,
+   *  since `target_directory` is where the dylib is then looked for — setting it
+   *  on only one of the two would build in one place and search in another. */
+  private targetDirEnv(): Record<string, string | undefined> {
+    const env = hostEnv();
+    if (!this.cacheRoot) return env;
+    return { ...env, CARGO_TARGET_DIR: path.join(this.cacheRoot, "cargo", "napi", "target") };
+  }
   /**
    * Resolve a `pkg:cargo/...` PURL to a controller module instance by building
    * the crate and loading the resulting native addon.
@@ -140,6 +170,7 @@ export class NapiControllerLoader {
   async resolve(
     purl: string,
     baseUri: string,
+    report?: ControllerWorkReporter,
   ): Promise<{ source: NapiResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     const [, , name, , qualifiers, entry] = PackageURL.parseString(purl);
     const localPath = (qualifiers as any)?.get("local_path");
@@ -199,6 +230,9 @@ export class NapiControllerLoader {
           const { rawModule } = await existingInFlight;
           return project(rawModule, entry, cratePath);
         }
+        // Nothing above this line compiles — the cache and the in-flight gate
+        // both return without cargo running.
+        await report?.("cargo-build");
         const buildPromise = build(cratePath, crateName, cacheKey);
         _napiInFlight.set(cacheKey, buildPromise);
         let rawModule: any;
@@ -228,7 +262,11 @@ export class NapiControllerLoader {
     // Read before building: the metadata answers both "where did the dylib
     // land" and "does this crate use the SDK", and the second decides the build
     // flags.
-    const { targetDir, libName, usesSdk } = await resolveCrateMetadata(cratePath, fallbackName);
+    const { targetDir, libName, usesSdk } = await resolveCrateMetadata(
+      cratePath,
+      fallbackName,
+      this.targetDirEnv(),
+    );
 
     try {
       // The backend is selected as a *dependency* feature of the SDK. A crate
@@ -247,7 +285,7 @@ export class NapiControllerLoader {
       await execFileAsync("cargo", ["build", "--release", ...featureArgs], {
         cwd: cratePath,
         maxBuffer: 32 * 1024 * 1024,
-        env: hostEnv(),
+        env: this.targetDirEnv(),
       });
     } catch (err: any) {
       const stderr = err?.stderr ? `\n${err.stderr}` : "";
@@ -325,6 +363,7 @@ const SDK_CRATE_NAME = "telorun-sdk";
 async function resolveCrateMetadata(
   cratePath: string,
   fallbackName: string,
+  env: Record<string, string | undefined>,
 ): Promise<{ targetDir: string; libName: string; usesSdk: boolean }> {
   const result = await execFileAsync("cargo", [
     "metadata",
@@ -333,7 +372,7 @@ async function resolveCrateMetadata(
     "--manifest-path",
     path.join(cratePath, "Cargo.toml"),
     "--no-deps",
-  ], { maxBuffer: 32 * 1024 * 1024, env: hostEnv() });
+  ], { maxBuffer: 32 * 1024 * 1024, env });
   const metadata = JSON.parse(result.stdout);
   const cratePackage = metadata.packages?.find(
     (p: any) => p.manifest_path === path.join(cratePath, "Cargo.toml"),

package/src/controller-loaders/npm-loader.ts

@@ -1,4 +1,5 @@
 import { ControllerInstance, NOOP_LOGGER, type Logger } from "@telorun/sdk";
+import type { ControllerWorkReporter } from "../controller-loader.js";
 import { execFile } from "child_process";
 import * as crypto from "crypto";
 import * as fs from "fs/promises";
@@ -44,6 +45,21 @@ const PEER_INSTALL_FLAGS: ReadonlyArray<string> =
       ? ["--no-strict-peer-dependencies"]
       : [];
 
+/**
+ * Quiet the installer WITHOUT quieting its failures. `--silent` does both: on
+ * npm 11 a failed install writes nothing at all — not the `ERESOLVE`/`ETARGET`
+ * code, not the offending spec — so the wrapper below could only report that
+ * some install failed, with no cause, for every failure class. `--loglevel`
+ * error keeps the diagnosis and drops the progress chatter, which is the half
+ * that was actually worth suppressing.
+ */
+const QUIET_INSTALL_FLAGS: ReadonlyArray<string> =
+  PACKAGE_MANAGER === "npm"
+    ? ["--loglevel=error", "--no-progress"]
+    : PACKAGE_MANAGER === "pnpm"
+      ? ["--loglevel=error"]
+      : [];
+
 
 /**
  * Tells the dispatcher (and any UI consumer downstream) which branch the
@@ -188,6 +204,7 @@ export class NpmControllerLoader {
   async resolve(
     purl: string,
     baseUri: string,
+    report?: ControllerWorkReporter,
   ): Promise<{ source: NpmResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     const parsed = PackageURL.fromString(purl);
     if (!parsed.name) {
@@ -199,7 +216,7 @@ export class NpmControllerLoader {
     // versions can coexist in one flat node_modules (see installAlias).
     const alias = installAlias(packageName, version);
 
-    const installRoot = await this.ensureInstallRoot();
+    const installRoot = await this.ensureInstallRoot(report);
     const resolved = await resolveInstallSpec(parsed, packageName, baseUri);
     const source = await this.installPackage(
       installRoot,
@@ -207,6 +224,7 @@ export class NpmControllerLoader {
       resolved.spec,
       resolved.kind,
       version,
+      report,
     );
     const subpath = parsed.subpath ?? null;
     return {
@@ -221,9 +239,9 @@ export class NpmControllerLoader {
    * `npm install` once, and return the absolute root path. Memoized for the
    * lifetime of this loader instance.
    */
-  private ensureInstallRoot(): Promise<string> {
+  private ensureInstallRoot(report?: ControllerWorkReporter): Promise<string> {
     if (this.rootReady) return this.rootReady;
-    this.rootReady = this.materializeInstallRoot().catch((err) => {
+    this.rootReady = this.materializeInstallRoot(report).catch((err) => {
       // Reset on failure so a follow-up call retries rather than caches the rejection.
       this.rootReady = undefined;
       throw err;
@@ -231,7 +249,7 @@ export class NpmControllerLoader {
     return this.rootReady;
   }
 
-  private async materializeInstallRoot(): Promise<string> {
+  private async materializeInstallRoot(report?: ControllerWorkReporter): Promise<string> {
     if (!this.entryUrl) {
       // Throw the env-missing variant so a mixed candidate list (e.g.
       // `pkg:npm/... + pkg:cargo/...`) still falls back to the next
@@ -325,11 +343,14 @@ export class NpmControllerLoader {
           2,
         ) + "\n",
       );
+      // Announced here rather than at the top of the resolve: everything above
+      // this line is a fast path that reuses the existing tree.
+      await report?.("npm-install");
       await runPackageManager(installRoot, [
         "install",
         "--no-audit",
         "--no-fund",
-        "--silent",
+        ...QUIET_INSTALL_FLAGS,
         ...PEER_INSTALL_FLAGS,
       ]);
       await fs.writeFile(stateFile, JSON.stringify({ rootHash: newHash }, null, 2) + "\n");
@@ -383,6 +404,7 @@ export class NpmControllerLoader {
     spec: string,
     kind: SpecKind,
     requestedVersion: string | null,
+    report?: ControllerWorkReporter,
   ): Promise<NpmResolveSource> {
     const cacheKey = alias;
     if (this.installedSpecs.has(cacheKey)) return "cache";
@@ -466,11 +488,24 @@ export class NpmControllerLoader {
           }
         }
 
+        // Past every re-check: the package manager is about to run for real,
+        // which is the wait a caller wants reported.
+        await report?.("npm-install");
+        // The installer re-resolves the ROOT's whole dependency set, not just
+        // the alias being added, so one dead record left by another app fails
+        // an install that has nothing to do with it — and the root is shared
+        // workspace-wide, so that blast radius is every app. Prune here rather
+        // than only on a realm change (`materializeInstallRoot`), which a root
+        // that goes stale afterwards never reaches. Placed past every re-check
+        // so it costs 2 stats per recorded dep only on the branch that was
+        // already going to spawn the package manager, never on a cache hit.
+        const pruned = await pruneDeadControllerDeps(installRoot);
+        if (pruned) this.rootDeps = pruned;
         await runPackageManager(installRoot, [
           "install",
           "--no-audit",
           "--no-fund",
-          "--silent",
+          ...QUIET_INSTALL_FLAGS,
           ...PEER_INSTALL_FLAGS,
           "--save",
           // `<alias>@<source-spec>` installs the package under the alias folder
@@ -640,9 +675,15 @@ async function runPackageManager(cwd: string, args: string[]): Promise<void> {
           `TELO_PKG_MANAGER to a different binary name.`,
       );
     }
-    const stderr = err?.stderr ? `\n${err.stderr}` : "";
+    // Both streams: npm writes its diagnosis to stderr, pnpm and bun put parts
+    // of theirs on stdout. Reporting one of them is how a real cause becomes a
+    // failure with no message.
+    const output = [err?.stderr, err?.stdout]
+      .map((s) => (typeof s === "string" ? s.trim() : ""))
+      .filter(Boolean)
+      .join("\n");
     throw new Error(
-      `[telo] '${PACKAGE_MANAGER} ${args.join(" ")}' failed in ${cwd}:${stderr}`,
+      `[telo] '${PACKAGE_MANAGER} ${args.join(" ")}' failed in ${cwd}:${output ? `\n${output}` : ""}`,
     );
   }
 }
@@ -825,6 +866,43 @@ async function liveControllerDeps(
   return live;
 }
 
+/**
+ * Rewrite the install root's `package.json` with its dead controller records
+ * dropped, returning the surviving map — or null when nothing had to change,
+ * so the common case writes no file.
+ *
+ * Realm-collapse names are never candidates: they are wired in by
+ * `materializeInstallRoot` from the kernel's own resolved paths and are the one
+ * thing whose absence must be reported rather than repaired away.
+ *
+ * Must be called under the install root's lock — it is a read-modify-write of a
+ * file every kernel sharing the root writes to.
+ */
+async function pruneDeadControllerDeps(
+  installRoot: string,
+): Promise<Record<string, string> | null> {
+  const deps = await readPackageDeps(installRoot);
+  if (!deps) return null;
+  const realm = new Set<string>(REALM_COLLAPSE_NAMES);
+  const controllers: Record<string, string> = {};
+  const preserved: Record<string, string> = {};
+  for (const [name, spec] of Object.entries(deps)) {
+    if (realm.has(name)) preserved[name] = spec;
+    else controllers[name] = spec;
+  }
+  const live = await liveControllerDeps(controllers, installRoot);
+  if (Object.keys(live).length === Object.keys(controllers).length) return null;
+
+  const packageJsonPath = path.join(installRoot, "package.json");
+  const pkg = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+  const merged = { ...live, ...preserved };
+  await fs.writeFile(
+    packageJsonPath,
+    JSON.stringify({ ...pkg, dependencies: merged }, null, 2) + "\n",
+  );
+  return merged;
+}
+
 async function readPackageDeps(installRoot: string): Promise<Record<string, string> | null> {
   try {
     const text = await fs.readFile(path.join(installRoot, "package.json"), "utf8");

package/src/controller-loaders/source-bundle-builder.ts

@@ -4,6 +4,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+// Type-only, so this builder stays free of a runtime edge to the dispatcher.
+import type { ControllerWorkReporter } from "../controller-loader.js";
 
 import { readOwnerManifest } from "../bundle/module-manifest.js";
 import { ControllerEnvMissingError } from "./napi-loader.js";
@@ -295,6 +297,7 @@ export async function buildControllerFromSource(
   entryFile: string,
   cacheRoot: string,
   libraries: readonly SiblingLibrary[] = [],
+  report?: ControllerWorkReporter,
 ): Promise<string> {
   const cacheDir = path.join(cacheRoot, CACHE_DIR);
   const externals = externalSpecifiers(libraries);
@@ -309,6 +312,9 @@ export async function buildControllerFromSource(
 
   const inFlight = buildsInFlight.get(entryFile);
   if (inFlight) return inFlight;
+  // Below the content-addressed cache and the in-flight gate: from here esbuild
+  // really runs, which is the only branch worth reporting as a wait.
+  await report?.("source-build");
   const work = build(entryFile, cacheDir, libraries).finally(() =>
     buildsInFlight.delete(entryFile),
   );

package/src/controllers/resource-definition/resource-definition-controller.ts

@@ -161,6 +161,11 @@ class ResourceDefinition implements ResourceInstance {
       installRoot: ctx.getInstallRoot(),
       cacheRoot: host.getCacheRoot?.(),
       log: ctx.log,
+      // What resolution reports on its own: the work branches it enters, and
+      // the candidates it skipped. Routed through `ctx.emit` so they carry the
+      // same `<kind>.` namespace as the load events emitted below — a consumer
+      // pairs a wait with its outcome by that namespace.
+      emit: (event) => ctx.emit(event.name, event.payload as Record<string, unknown>),
     });
     // The artifact of the module that DECLARED this kind — a bundled controller
     // ships in its own module's payload, not the consumer's. It owns the pinned
@@ -199,8 +204,7 @@ class ResourceDefinition implements ResourceInstance {
             }
             throw err;
           });
-        await ctx.emit("ControllerLoading", { purl: resolved.purl });
-        const startedAt = Date.now();
+        await ctx.emit("ControllerLoading", { purl: resolved.purl, source: resolved.source });
         const instance = await resolved.importInstance().catch(async (err) => {
           await ctx.emit("ControllerLoadFailed", {
             purl: resolved.purl,
@@ -212,7 +216,7 @@ class ResourceDefinition implements ResourceInstance {
         await ctx.emit("ControllerLoaded", {
           purl: resolved.purl,
           source: resolved.source,
-          durationMs: Date.now() - startedAt,
+          durationMs: resolved.waitedMs(),
         });
       },
     );