@telorun/kernel 0.61.0 → 0.63.0

package/dist/transports/transport-registry.js

@@ -59,10 +59,12 @@ export function defaultTransports(registryUrl) {
 }
 const defaultRegistryCache = new Map();
 /** A `TransportRegistry` seeded with {@link defaultTransports}, memoized per
- *  `registryUrl`. The default transports are stateless config (a fresh
- *  `OciClient` with its own token cache is created per OCI operation), so one
- *  shared instance per registry URL is safe — and avoids re-instantiating the
- *  whole set on hot paths like `cachePathForCanonical`. */
+ *  `registryUrl`. The default transports hold no per-call state, so one shared
+ *  instance per registry URL is safe — and avoids re-instantiating the whole set
+ *  on hot paths like `cachePathForCanonical`. It is also what gives
+ *  `OciTransport`'s per-instance read-client pool a process-wide lifetime here,
+ *  so the bearer-token cache survives across operations without the pool having
+ *  to be global. */
 export function defaultTransportRegistry(registryUrl) {
     const key = registryUrl ?? "";
     let cached = defaultRegistryCache.get(key);

package/dist/transports/transport-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport-registry.js","sourceRoot":"","sources":["../../src/transports/transport-registry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAQ5D;;;;2EAI2E;AAC3E,MAAM,OAAO,iBAAiB;IAC5B,YAA6B,UAAuB;QAAvB,eAAU,GAAV,UAAU,CAAa;IAAG,CAAC;IAExD,kEAAkE;IAClE,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IACtD,CAAC;IAED;0EACsE;IACtE,OAAO;QACL,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED;iEAC6D;IAC7D,WAAW,CAAC,GAAW;QACrB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IACpD,CAAC;IAED;wEACoE;IACpE,YAAY,CAAC,GAAW;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED;gEAC4D;IAC5D,UAAU,CAAC,GAAW,EAAE,UAAkB;QACxC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACvD,CAAC;IAED;kFAC8E;IAC9E,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IAED;yDACqD;IACrD,OAAO,CACL,WAAmB,EACnB,MAAqB,EACrB,IAAqB;QAErB,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;IAEO,OAAO,CAAC,GAAW;QACzB,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,GAAG,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF;AAED;;oFAEoF;AACpF,MAAM,UAAU,iBAAiB,CAAC,WAAoB;IACpD,OAAO,CAAC,IAAI,YAAY,EAAE,EAAE,IAAI,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAA6B,CAAC;AAElE;;;;2DAI2D;AAC3D,MAAM,UAAU,wBAAwB,CAAC,WAAoB;IAC3D,MAAM,GAAG,GAAG,WAAW,IAAI,EAAE,CAAC;IAC9B,IAAI,MAAM,GAAG,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,IAAI,iBAAiB,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC;QAC/D,oBAAoB,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"transport-registry.js","sourceRoot":"","sources":["../../src/transports/transport-registry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAQ5D;;;;2EAI2E;AAC3E,MAAM,OAAO,iBAAiB;IAC5B,YAA6B,UAAuB;QAAvB,eAAU,GAAV,UAAU,CAAa;IAAG,CAAC;IAExD,kEAAkE;IAClE,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IACtD,CAAC;IAED;0EACsE;IACtE,OAAO;QACL,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED;iEAC6D;IAC7D,WAAW,CAAC,GAAW;QACrB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IACpD,CAAC;IAED;wEACoE;IACpE,YAAY,CAAC,GAAW;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED;gEAC4D;IAC5D,UAAU,CAAC,GAAW,EAAE,UAAkB;QACxC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACvD,CAAC;IAED;kFAC8E;IAC9E,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IAED;yDACqD;IACrD,OAAO,CACL,WAAmB,EACnB,MAAqB,EACrB,IAAqB;QAErB,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;IAEO,OAAO,CAAC,GAAW;QACzB,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,GAAG,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF;AAED;;oFAEoF;AACpF,MAAM,UAAU,iBAAiB,CAAC,WAAoB;IACpD,OAAO,CAAC,IAAI,YAAY,EAAE,EAAE,IAAI,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAA6B,CAAC;AAElE;;;;;;oBAMoB;AACpB,MAAM,UAAU,wBAAwB,CAAC,WAAoB;IAC3D,MAAM,GAAG,GAAG,WAAW,IAAI,EAAE,CAAC;IAC9B,IAAI,MAAM,GAAG,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,IAAI,iBAAiB,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC;QAC/D,oBAAoB,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.61.0",
+  "version": "0.63.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
     "telo",
@@ -61,9 +61,9 @@
   "dependencies": {
     "@marcbachmann/cel-js": "^7.6.1",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.49.0",
+    "@telorun/analyzer": "0.50.0",
     "@telorun/glob": "0.2.0",
-    "@telorun/templating": "0.11.0",
+    "@telorun/templating": "0.11.1",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "packageurl-js": "^2.0.1",
@@ -75,10 +75,10 @@
     "@types/tar-stream": "^3.1.3",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.61.0"
+    "@telorun/sdk": "0.63.0"
   },
   "optionalDependencies": {
-    "esbuild": "^0.28.1"
+    "esbuild": "^0.25.12"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/bundle/module-artifact.ts

@@ -26,6 +26,17 @@ export interface MaterializedLayer {
   files: string[];
 }
 
+/** A materialized controller layer plus whether reaching it cost a transfer.
+ *
+ *  `transferred` is out of band rather than a field on `MaterializedLayer`
+ *  because it describes THIS call, not the layer: the value is memoized and
+ *  shared, so a flag on it would be meaningless to every other caller. Only the
+ *  controller path reports progress, so only it asks. */
+export interface ResolvedControllerLayer {
+  layer: MaterializedLayer;
+  transferred: boolean;
+}
+
 /**
  * Map Node's platform vocabulary onto the canonical OCI/GOOS names selectors are
  * published with. Node says `win32`/`x64`; OCI descriptors say
@@ -123,8 +134,11 @@ export class ModuleArtifact {
   private readonly transports: TransportRegistry;
   private readonly log: Logger;
   /** In-flight / completed materializations, keyed by blob digest. Rejections
-   *  are dropped so a transient fetch failure retries on the next ask. */
-  private readonly inFlight = new Map<string, Promise<MaterializedLayer>>();
+   *  are dropped so a transient fetch failure retries on the next ask. Each
+   *  records whether the work it wraps transferred the layer or read it off
+   *  disk — the memoized entry is shared, so a joining caller reads the flag
+   *  but never claims it. */
+  private readonly inFlight = new Map<string, Promise<ResolvedControllerLayer>>();
 
   constructor(opts: {
     pinnedRef: string;
@@ -165,14 +179,23 @@ export class ModuleArtifact {
    * Returns `undefined` when the artifact ships no layer for this selector, which
    * is how a loader learns to fall through to the next candidate.
    */
-  async materializeController(selector: ArtifactSelector): Promise<MaterializedLayer | undefined> {
+  async materializeController(
+    selector: ArtifactSelector,
+  ): Promise<ResolvedControllerLayer | undefined> {
     const key = selectorKey(selector);
     const layer = this.layers.find(
       (l) => l.role === "controller" && l.selector !== undefined && selectorKey(l.selector) === key,
     );
     if (!layer) return undefined;
-    await this.materializeCommon();
-    return this.materialize(layer);
+    const common = await this.materializeCommonTracked();
+    const controller = await this.materializeTracked(layer);
+    // Either half is a transfer the caller waited on: the common layer's bytes
+    // come down on this call too, so they are as much of a wait as the
+    // controller layer's.
+    return {
+      layer: controller.layer,
+      transferred: controller.transferred || (common?.transferred ?? false),
+    };
   }
 
   /**
@@ -197,8 +220,15 @@ export class ModuleArtifact {
 
   /** Materialize the `common` layer, if the module ships one. */
   async materializeCommon(): Promise<MaterializedLayer | undefined> {
+    return (await this.materializeCommonTracked())?.layer;
+  }
+
+  /** As `materializeCommon`, reporting whether this call transferred it — the
+   *  controller path rides the common layer along and has to count its bytes as
+   *  part of the wait. One lookup, so "common comes too" is encoded once. */
+  private async materializeCommonTracked(): Promise<ResolvedControllerLayer | undefined> {
     const layer = singletonLayer(this.layers, "common");
-    return layer ? this.materialize(layer) : undefined;
+    return layer ? this.materializeTracked(layer) : undefined;
   }
 
   /**
@@ -226,9 +256,21 @@ export class ModuleArtifact {
       .join(", ");
   }
 
-  private materialize(layer: ArtifactLayer): Promise<MaterializedLayer> {
+  private async materialize(layer: ArtifactLayer): Promise<MaterializedLayer> {
+    return (await this.materializeTracked(layer)).layer;
+  }
+
+  /**
+   * As `materialize`, but also reporting whether THIS call transferred the layer.
+   *
+   * A caller that joins work already in flight reports `false`: several
+   * controller candidates of one module share a layer, and attributing the
+   * transfer to all of them would print one progress line per candidate for a
+   * single download. The call that started the work owns the report.
+   */
+  private materializeTracked(layer: ArtifactLayer): Promise<ResolvedControllerLayer> {
     const pending = this.inFlight.get(layer.blob);
-    if (pending) return pending;
+    if (pending) return pending.then((r) => ({ layer: r.layer, transferred: false }));
     const work = this.materializeUncached(layer).catch((err) => {
       // Drop the rejection so a transient fetch failure is retried rather than
       // cached for the lifetime of the module.
@@ -247,10 +289,10 @@ export class ModuleArtifact {
     return path.join(this.dir, `.telo-layer-${layer.role}-${short}`);
   }
 
-  private async materializeUncached(layer: ArtifactLayer): Promise<MaterializedLayer> {
+  private async materializeUncached(layer: ArtifactLayer): Promise<ResolvedControllerLayer> {
     const marker = this.markerPath(layer);
     if (existsSync(marker)) {
-      return { dir: this.dir, files: await readMarker(marker) };
+      return { layer: { dir: this.dir, files: await readMarker(marker) }, transferred: false };
     }
 
     return withDirectoryLock(
@@ -260,7 +302,7 @@ export class ModuleArtifact {
         // Re-check inside the lock: a peer may have extracted this layer between
         // the fast-path miss and our acquisition.
         if (existsSync(marker)) {
-          return { dir: this.dir, files: await readMarker(marker) };
+          return { layer: { dir: this.dir, files: await readMarker(marker) }, transferred: false };
         }
 
         const files = await this.transports.fetchLayer(this.pinnedRef, layer.blob);
@@ -283,7 +325,7 @@ export class ModuleArtifact {
           "telo.layer.role": layer.role,
           "telo.layer.files": written.length,
         });
-        return { dir: this.dir, files: written };
+        return { layer: { dir: this.dir, files: written }, transferred: true };
       },
       this.log,
     );

package/src/controller-loader.ts

@@ -8,10 +8,13 @@ import { ControllerPolicy, DEFAULT_POLICY, POLICY_WILDCARD } from "./runtime-reg
 export type { ControllerPolicy } from "./runtime-registry.js";
 
 /**
- * Which branch the per-scheme loader actually took. Cache/local hits resolve
- * in milliseconds; `npm-install` and `cargo-build` are the only branches that
- * do real (network or compile) work. The CLI uses this to decide whether a
- * "downloading…" line was honest or should be erased.
+ * Which branch the per-scheme loader actually took. Cache/local hits resolve in
+ * milliseconds; `npm-install`, `cargo-build` and `bundle` are the branches that
+ * do real (network or compile) work — `bundle` is reported only when the resolve
+ * fetched the module's controller layer, never when it found it already
+ * extracted. The CLI uses this to decide whether a "downloading…" line was
+ * honest or should be erased, so a source that names work no one waited for
+ * turns every warm start into noise.
  */
 export type ControllerResolveSource =
   | "local"
@@ -73,6 +76,10 @@ export interface ControllerLoaderOptions {
    *  single `resolveCacheRoot`. Overrides the entry-anchored default so a
    *  relocated `TELO_CACHE_DIR` is honoured. */
   installRoot?: string;
+  /** The `.telo` cache root for this load. The bundle loader caches a dev build
+   *  of a local module's controller source under it; absent simply disables that
+   *  path, leaving a prebuilt `path=` to load. */
+  cacheRoot?: string;
   /** Where the sub-loaders' diagnostics go — install-lock waits, bundle skips.
    *  Threaded from `ctx.log` so §13.1 holds (no direct `process.stderr`), and so
    *  the bundle-skip diagnostics that replaced `TELO_BUNDLE_DEBUG` actually reach
@@ -111,7 +118,7 @@ export class ControllerLoader {
     });
     if (options.log) this.npmLoader.setLogger(options.log);
     this.napiLoader = new NapiControllerLoader();
-    this.bundleLoader = new BundleControllerLoader();
+    this.bundleLoader = new BundleControllerLoader(options.cacheRoot);
   }
 
   async load(

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

@@ -10,6 +10,7 @@ import { hostPlatformTarget, type ModuleArtifact } from "../bundle/module-artifa
 import type { ControllerResolveSource } from "../controller-loader.js";
 import { ControllerEnvMissingError } from "./napi-loader.js";
 import { REALM_COLLAPSE_NAMES } from "./realm.js";
+import { buildControllerFromSource, canBuildFromSource } from "./source-bundle-builder.js";
 
 /** A base URI whose files are already on disk: a `file://` URL or a bare
  *  absolute path. Everything else (`oci://`, `http(s)://`, `memory://`) names a
@@ -130,7 +131,16 @@ function findPackageRoot(entryFile: string, name: string): string | null {
  *    (or `[pkg:telo …, pkg:npm …]`) falls through to a candidate this — or
  *    another runtime's — kernel can load.
  *  - `path` — the file in the bundle; `#export` — the named export.
+ *  - `local_path` — the TypeScript source `path=` was built from. Present only
+ *    while the module is a working copy; a published artifact ships no `src/`.
+ *    When the module arrives with **no artifact handle** and the source resolves
+ *    on disk, the loader builds it (see `source-bundle-builder.ts`) rather than
+ *    importing `path=`, so editing a controller and re-running picks the edit up
+ *    with no build step. The guard is the absence of an artifact, not the shape
+ *    of the base URI: a published module served from the on-disk manifest cache
+ *    has a local base too, and its payload is the layer regardless.
  *
+
  * Two separate concerns for `js` bundles importing `@telorun/sdk`:
  *  - *Resolution* — the bare specifier must point at a real file. The bundle has
  *    no node_modules, so `ensureRealmSymlinks()` symlinks the realm-collapse
@@ -146,6 +156,11 @@ function findPackageRoot(entryFile: string, name: string): string | null {
  * through); a bundle that loads but is malformed is a hard `ERR_CONTROLLER_INVALID`.
  */
 export class BundleControllerLoader {
+  /** Where a dev build from `local_path` is cached (`<cache-root>/controller-src`).
+   *  Absent for callers that resolved no cache root, which simply disables the
+   *  source path — a prebuilt `path=` still loads. */
+  constructor(private readonly cacheRoot?: string) {}
+
   async load(
     purl: string,
     baseUri: string,
@@ -215,22 +230,76 @@ export class BundleControllerLoader {
       );
     }
 
+    const fragment = parsed.subpath;
+
+    // Dev path: a module that is a working copy — no artifact behind it — with a
+    // `local_path` source on disk is built from that source, because the source
+    // is what is authoritative there. An artifact means the payload IS the layer,
+    // so this never fires for a published module, including one served from the
+    // on-disk manifest cache (whose base is local but whose payload is a layer).
+    //
+    // esbuild is probed HERE rather than inside the build. It is an optional
+    // dependency so that an install skipping optionals still runs published
+    // artifacts — and a working copy that has run its build script has the same
+    // prebuilt file on disk. Deciding it lazily would turn "no bundler" into a
+    // hard failure standing next to a perfectly good bundle, and the candidate
+    // list could not rescue it: the fallback belongs to this same PURL, not to a
+    // sibling candidate.
+    const cacheRoot = this.cacheRoot;
+    const sourceFile = artifact ? undefined : this.localSourceFile(parsed, baseUri);
+    const buildFromSource =
+      sourceFile !== undefined &&
+      cacheRoot !== undefined &&
+      (await pathExists(sourceFile)) &&
+      (await canBuildFromSource());
+    if (buildFromSource) {
+      // The same file the prebuilt branch would import, kept as the fallback for
+      // an environment that stops being able to build between resolve and first
+      // instantiation.
+      const prebuilt = path.resolve(this.moduleDir(baseUri), relPath);
+      return {
+        source: "local",
+        // Deferred like every other branch: the build is paid on the kind's
+        // first instantiation, so a manifest pays only for the kinds it uses.
+        // A build FAILURE is user code and propagates unchanged; only a missing
+        // *environment* falls back, and only to a file that is actually there.
+        importInstance: async () => {
+          let built: string;
+          try {
+            built = await buildControllerFromSource(sourceFile!, cacheRoot!);
+          } catch (err) {
+            if (!(err instanceof ControllerEnvMissingError)) throw err;
+            if (!(await pathExists(prebuilt))) throw err;
+            await ensureRealmSymlinks(path.dirname(prebuilt));
+            return importControllerModule(prebuilt, purl, fragment);
+          }
+          await ensureRealmSymlinks(path.dirname(built));
+          return importControllerModule(built, purl, fragment);
+        },
+      };
+    }
+
     // A published module's payload lives in its artifact, so materialize the one
     // layer carrying this candidate and resolve `path=` inside it. Nothing is
     // fetched here: the artifact handle owns the pinned ref and the verified
     // layer index, so an `oci://` module ref never reaches this loader as a path.
     let bundleDir: string;
+    // What this resolve actually cost. A module already on disk is `local`; an
+    // artifact layer found extracted is `cache`; only a layer this call pulled
+    // down reports `bundle`, the branch that made the user wait.
+    let source: ControllerResolveSource = "local";
     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 layer = await artifact.materializeController(selector);
-      if (!layer) {
+      const resolved = await artifact.materializeController(selector);
+      if (!resolved) {
         throw new ControllerEnvMissingError(
           `pkg:telo controller "${purl}": the module artifact ships no layer for ` +
             `${describeSelector(selector)} (has: ${artifact.describeLayers()})`,
         );
       }
-      bundleDir = layer.dir;
+      bundleDir = resolved.layer.dir;
+      source = resolved.transferred ? "bundle" : "cache";
     } else {
       // No artifact: a module already on disk (local development, or a manifest
       // served from the on-disk cache). Its files sit next to the manifest.
@@ -256,31 +325,52 @@ export class BundleControllerLoader {
     // importing the bundle, so authors write normal imports.
     await ensureRealmSymlinks(path.dirname(absFile));
 
-    const fragment = parsed.subpath;
     return {
-      source: "bundle",
-      importInstance: async () => {
-        // A broken bundle (syntax / failed import) is a real user-code failure —
-        // let it propagate rather than masking it as env-missing.
-        const mod = (await import(pathToFileURL(absFile).href)) as Record<string, ControllerInstance>;
-        // Distinguish "no such export" from "export isn't a controller" so the
-        // error points at the actual problem (mirrors the napi loader's project()).
-        if (fragment && !(fragment in mod)) {
-          throw new RuntimeError(
-            "ERR_CONTROLLER_INVALID",
-            `Bundled controller "${purl}": module "${absFile}" has no export named "${fragment}"`,
-          );
-        }
-        const instance = fragment ? mod[fragment] : (mod as unknown as ControllerInstance);
-        if (!instance || (!instance.create && !instance.register)) {
-          throw new RuntimeError(
-            "ERR_CONTROLLER_INVALID",
-            `Bundled controller "${purl}" exports neither create() nor register()` +
-              (fragment ? ` at fragment "#${fragment}"` : ""),
-          );
-        }
-        return instance;
-      },
+      source,
+      importInstance: () => importControllerModule(absFile, purl, fragment),
     };
   }
+
+  /** The `local_path` source this candidate names, resolved against the declaring
+   *  module's directory — or `undefined` when the candidate declares none, or the
+   *  module is not on disk to resolve it against. */
+  private localSourceFile(parsed: PackageURL, baseUri: string): string | undefined {
+    const localPath = parsed.qualifiers?.local_path;
+    if (!localPath || !isLocalBase(baseUri)) return undefined;
+    return path.resolve(this.moduleDir(baseUri), localPath);
+  }
+
+  /** Directory of the declaring module's manifest. Only meaningful for a local
+   *  base; callers gate on {@link isLocalBase} first. */
+  private moduleDir(baseUri: string): string {
+    return path.dirname(baseUri.startsWith("file://") ? fileURLToPath(baseUri) : baseUri);
+  }
+}
+
+/** Import a built bundle and project out the controller the fragment names. A
+ *  broken bundle (syntax error, failed import) is a real user-code failure and
+ *  propagates; it is never masked as env-missing. */
+async function importControllerModule(
+  absFile: string,
+  purl: string,
+  fragment: string | undefined,
+): Promise<ControllerInstance> {
+  const mod = (await import(pathToFileURL(absFile).href)) as Record<string, ControllerInstance>;
+  // Distinguish "no such export" from "export isn't a controller" so the error
+  // points at the actual problem (mirrors the napi loader's project()).
+  if (fragment && !(fragment in mod)) {
+    throw new RuntimeError(
+      "ERR_CONTROLLER_INVALID",
+      `Bundled controller "${purl}": module "${absFile}" has no export named "${fragment}"`,
+    );
+  }
+  const instance = fragment ? mod[fragment] : (mod as unknown as ControllerInstance);
+  if (!instance || (!instance.create && !instance.register)) {
+    throw new RuntimeError(
+      "ERR_CONTROLLER_INVALID",
+      `Bundled controller "${purl}" exports neither create() nor register()` +
+        (fragment ? ` at fragment "#${fragment}"` : ""),
+    );
+  }
+  return instance;
 }

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

@@ -149,7 +149,7 @@ export class NpmControllerLoader {
    * same spec share one `npm install <spec>` invocation rather than each
    * acquiring the fs-lock and reinstalling.
    */
-  private readonly inFlight = new Map<string, Promise<void>>();
+  private readonly inFlight = new Map<string, Promise<boolean>>();
 
   /**
    * Promise that resolves when the install root has been materialized
@@ -264,15 +264,20 @@ export class NpmControllerLoader {
       dependencies[name] = `file:${resolvedPkgRoot}`;
     }
 
-    const packageJson = {
-      name: "telo-runtime-install",
-      private: true,
-      version: "0.0.0",
-      dependencies,
-    };
     const packageJsonPath = path.join(installRoot, "package.json");
     const stateFile = path.join(installRoot, ".telo-state.json");
-    const newHash = sha256(JSON.stringify(packageJson));
+    // Keyed on the realm deps alone — the only part this function owns. The
+    // controller aliases below join the file but never the identity: they are
+    // added one `--save` at a time, so hashing them would make every controller
+    // install invalidate the root and trigger another root install.
+    const newHash = sha256(
+      JSON.stringify({
+        name: "telo-runtime-install",
+        private: true,
+        version: "0.0.0",
+        dependencies,
+      }),
+    );
 
     await fs.mkdir(installRoot, { recursive: true });
 
@@ -301,7 +306,25 @@ export class NpmControllerLoader {
         return;
       }
 
-      await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
+      // Rewrite the root's package.json REALM DEPS ONLY, keeping every
+      // controller alias a previous `installPackage --save` recorded. Writing a
+      // fresh file instead drops them, and the install below then prunes their
+      // `node_modules` folders — so a realm change (a different kernel checkout,
+      // e.g. a globally installed CLI and a repo one addressing the same app)
+      // evicted every controller and reinstalled the lot, on every switch.
+      const existingDeps = (await readPackageDeps(installRoot)) ?? {};
+      const merged: Record<string, string> = {
+        ...(await liveControllerDeps(existingDeps, installRoot)),
+        ...dependencies,
+      };
+      await fs.writeFile(
+        packageJsonPath,
+        JSON.stringify(
+          { name: "telo-runtime-install", private: true, version: "0.0.0", dependencies: merged },
+          null,
+          2,
+        ) + "\n",
+      );
       await runPackageManager(installRoot, [
         "install",
         "--no-audit",
@@ -414,8 +437,11 @@ export class NpmControllerLoader {
       }
     }
 
+    // Resolves to whether the package manager actually ran: the re-check below
+    // routinely wins the race, and reporting an install that never happened
+    // makes the CLI print a "downloading…" line nobody waited for.
     const work = (async () => {
-      await withDirectoryLock(installRoot, "controller install", async () => {
+      return withDirectoryLock(installRoot, "controller install", async () => {
         // Re-check inside the lock: a peer process may have installed the
         // spec between the fast-path miss and our acquisition.
         if (kind === "registry") {
@@ -424,7 +450,7 @@ export class NpmControllerLoader {
             installedVersion !== null &&
             (requestedVersion === null || requestedVersion === installedVersion)
           ) {
-            return;
+            return false;
           }
         } else {
           // Normalize the on-disk record to absolute form before comparing —
@@ -436,7 +462,7 @@ export class NpmControllerLoader {
             (await pathExists(targetPath))
           ) {
             this.rootDeps[alias] = lockedSpec;
-            return;
+            return false;
           }
         }
 
@@ -458,16 +484,21 @@ export class NpmControllerLoader {
         const written = await readDepSpec(installRoot, alias);
         if (written !== undefined) this.rootDeps[alias] = written;
         else this.rootDeps[alias] = spec;
+        return true;
       }, this.log);
     })();
 
     this.inFlight.set(cacheKey, work);
+    let installed: boolean;
     try {
-      await work;
+      installed = await work;
     } finally {
       this.inFlight.delete(cacheKey);
     }
     this.installedSpecs.add(cacheKey);
+    // A peer that won the lock had already put the package there, so nothing
+    // was installed — that is a cache hit, whatever the fast path thought.
+    if (!installed) return "cache";
     // First-touch local installs report `local` (silenced in CLI progress);
     // fresh registry installs report `npm-install` (the only branch a
     // user-facing "downloading…" line should ever surface for).
@@ -693,6 +724,37 @@ function normalizeFileSpec(spec: string, installRoot: string): string {
  * Returns null when the file is missing or unreadable; callers decide whether
  * to seed from a synthesized map instead.
  */
+/**
+ * The subset of a root's recorded dependencies still worth carrying into a
+ * rewrite: the package manager has to resolve every entry, so one dead record
+ * fails the whole install.
+ *
+ * Dropped: a `file:` spec whose target no longer exists (the app was run from a
+ * checkout that has since moved, or the app directory was copied without it),
+ * and an alias with no folder in `node_modules`. Both are free to drop —
+ * `installPackage` reinstalls a controller the moment something asks for it —
+ * and keeping them is not: a dangling `file:` dep makes the root install fail
+ * with an ENOENT that names nothing in the manifest, and since the state file is
+ * only written after a successful install, every later run repeats it. This is
+ * also what stops aliases accumulating forever now that the rewrite preserves
+ * them: a version an app has moved off drops out on the next root install.
+ */
+async function liveControllerDeps(
+  deps: Record<string, string>,
+  installRoot: string,
+): Promise<Record<string, string>> {
+  const live: Record<string, string> = {};
+  for (const [name, spec] of Object.entries(deps)) {
+    if (spec.startsWith("file:")) {
+      const target = normalizeFileSpec(spec, installRoot).slice("file:".length);
+      if (!(await pathExists(target))) continue;
+    }
+    if (!(await pathExists(path.join(installRoot, "node_modules", name)))) continue;
+    live[name] = spec;
+  }
+  return live;
+}
+
 async function readPackageDeps(installRoot: string): Promise<Record<string, string> | null> {
   try {
     const text = await fs.readFile(path.join(installRoot, "package.json"), "utf8");