@telorun/kernel 0.58.0 → 0.60.0

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

@@ -1,3 +1,4 @@
+import { describeSelector, selectorFromQualifiers, selectorMatches } from "@telorun/analyzer";
 import { ControllerInstance, RuntimeError } from "@telorun/sdk";
 import { existsSync, readFileSync } from "fs";
 import * as fs from "fs/promises";
@@ -5,10 +6,18 @@ import { createRequire } from "module";
 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 { ControllerEnvMissingError } from "./napi-loader.js";
 import { REALM_COLLAPSE_NAMES } from "./realm.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
+ *  module whose payload only exists inside an artifact. */
+function isLocalBase(baseUri: string): boolean {
+  return baseUri.startsWith("file://") || path.isAbsolute(baseUri);
+}
+
 async function pathExists(filePath: string): Promise<boolean> {
   try {
     await fs.access(filePath);
@@ -140,20 +149,23 @@ export class BundleControllerLoader {
   async load(
     purl: string,
     baseUri: string,
+    artifact?: ModuleArtifact,
   ): Promise<{ instance: ControllerInstance; source: ControllerResolveSource }> {
-    const { source, importInstance } = await this.resolve(purl, baseUri);
+    const { source, importInstance } = await this.resolve(purl, baseUri, artifact);
     return { instance: await importInstance(), source };
   }
 
   /**
-   * Resolve without importing: parse + validate the PURL, confirm the bundle
-   * file exists and its format is hostable, and ensure the realm symlinks — all
-   * cheap, fail-fast checks — but defer the bundle `import()` (the eval cost)
-   * into the returned `importInstance` thunk. Used by lazy controller loading.
+   * Resolve without importing: parse + validate the PURL, reject a candidate this
+   * host cannot run, materialize the layer that carries it, confirm the file
+   * exists, and ensure the realm symlinks — all fail-fast checks — but defer the
+   * bundle `import()` (the eval cost) into the returned `importInstance` thunk.
+   * Used by lazy controller loading.
    */
   async resolve(
     purl: string,
     baseUri: string,
+    artifact?: ModuleArtifact,
   ): Promise<{ source: ControllerResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     let parsed: PackageURL;
     try {
@@ -190,16 +202,50 @@ export class BundleControllerLoader {
       );
     }
 
-    // Bundles are local files next to the manifest. A remote (http) baseUri
-    // can't host one, so defer to the next candidate.
-    if (baseUri.startsWith("http://") || baseUri.startsWith("https://")) {
+    // Platform gate, BEFORE any materialization. A candidate list names one
+    // binary per platform, so checking the host first is what keeps a fallthrough
+    // from downloading every platform's layer on the way to the right one.
+    const selector = selectorFromQualifiers(format, parsed.qualifiers, `controller "${purl}"`);
+    const host = hostPlatformTarget();
+    if (!selectorMatches(selector, host)) {
       throw new ControllerEnvMissingError(
-        `pkg:telo controller "${purl}" requires a local manifest; baseUri is remote (${baseUri})`,
+        `pkg:telo controller "${purl}" targets ${describeSelector(selector)}, which does not ` +
+          `match this host (${host.os ?? "unknown os"}/${host.arch ?? "unknown arch"}` +
+          `${host.libc ? `/${host.libc}` : ""})`,
       );
     }
 
-    const basePath = baseUri.startsWith("file://") ? fileURLToPath(baseUri) : baseUri;
-    const absFile = path.resolve(path.dirname(basePath), relPath);
+    // 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;
+    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) {
+        throw new ControllerEnvMissingError(
+          `pkg:telo controller "${purl}": the module artifact ships no layer for ` +
+            `${describeSelector(selector)} (has: ${artifact.describeLayers()})`,
+        );
+      }
+      bundleDir = layer.dir;
+    } 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.
+      if (!isLocalBase(baseUri)) {
+        throw new ControllerEnvMissingError(
+          `pkg:telo controller "${purl}" cannot be located: the declaring module resolved from ` +
+            `"${baseUri}", which is neither a local path nor an artifact with a layer index. ` +
+            `A bundled controller ships in its module's artifact — republish the module, or ` +
+            `import it from a local path during development.`,
+        );
+      }
+      bundleDir = path.dirname(baseUri.startsWith("file://") ? fileURLToPath(baseUri) : baseUri);
+    }
+
+    const absFile = path.resolve(bundleDir, relPath);
     if (!(await pathExists(absFile))) {
       throw new ControllerEnvMissingError(
         `pkg:telo controller bundle not found at "${absFile}" (from "${purl}")`,

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

@@ -10,6 +10,7 @@ import { fileURLToPath, pathToFileURL } from "url";
 import { promisify } from "util";
 import { hostEnv } from "../host-env.js";
 import { tryBuildControllerBundle } from "./bundle-builder.js";
+import { withDirectoryLock } from "../directory-lock.js";
 import { ControllerEnvMissingError } from "./napi-loader.js";
 import { REALM_COLLAPSE_NAMES } from "./realm.js";
 
@@ -43,39 +44,6 @@ const PEER_INSTALL_FLAGS: ReadonlyArray<string> =
       ? ["--no-strict-peer-dependencies"]
       : [];
 
-/**
- * A held lock is refreshed (its mtime bumped) every {@link LOCK_HEARTBEAT_MS}
- * by the holder. Staleness is judged purely by mtime age — a lock older than
- * this means the holder stopped heartbeating (crashed, was killed, or its
- * container vanished), so it is safe to reclaim. This deliberately does NOT
- * probe the recorded PID for liveness: PID identity is meaningless across
- * container restarts and PID namespaces (deterministic PID reuse makes an
- * unrelated process look like the dead holder on the same hostname), which is
- * exactly what deadlocked container boots. The `{pid, host}` in the lock body
- * is diagnostics for humans, never a reclaim signal. Must be comfortably
- * larger than the heartbeat interval so a briefly-descheduled holder (GC
- * pause, busy event loop) is not reclaimed out from under itself.
- */
-const LOCK_STALE_MS = 30_000;
-
-/** How often the holder refreshes the lock mtime while `fn` runs. Well under
- *  {@link LOCK_STALE_MS} so several heartbeats are missed before a live holder
- *  is ever judged stale. */
-const LOCK_HEARTBEAT_MS = 5_000;
-
-/**
- * Total wall-clock cap for waiting on the install lock — enough for a slow
- * first install on a peer process to finish, short enough that a genuinely
- * deadlocked CI job fails loudly rather than hanging for hours. The retry
- * interval trades wakeup latency vs. wasted polls; 500ms is well below the
- * lock holder's typical hold time.
- */
-const LOCK_WAIT_MAX_MS = 5 * 60_000;
-const LOCK_RETRY_MS = 500;
-
-/** After this long waiting on a lock, emit one stderr line so a slow wait is
- *  visible instead of looking like a silent hang. */
-const LOCK_WAIT_NOTICE_MS = 2_000;
 
 /**
  * Tells the dispatcher (and any UI consumer downstream) which branch the
@@ -325,7 +293,7 @@ export class NpmControllerLoader {
       return installRoot;
     }
 
-    await withInstallLock(installRoot, async () => {
+    await withDirectoryLock(installRoot, "controller install", async () => {
       // Re-check inside the lock: a peer may have completed the install
       // between the fast-path miss and our acquisition.
       const existingHash = await readJsonField(stateFile, "rootHash");
@@ -447,7 +415,7 @@ export class NpmControllerLoader {
     }
 
     const work = (async () => {
-      await withInstallLock(installRoot, async () => {
+      await 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") {
@@ -557,176 +525,6 @@ async function resolveKernelPackageRoot(name: string): Promise<string | null> {
   }
 }
 
-/**
- * Serialize same-process callers for one install root, in memory, ahead of the
- * filesystem lock.
- *
- * Package installs dedupe per alias, so N distinct controllers are N distinct
- * `withInstallLock` calls against the SAME root. Without this queue they all
- * contend through the filesystem: one wins and the rest poll `fs.open` every
- * {@link LOCK_RETRY_MS} for the whole install, each crossing
- * {@link LOCK_WAIT_NOTICE_MS} and printing the wait notice — a notice whose
- * whole point is "another Telo *process* holds this", which is misleading when
- * the holder is us. (`telo install` fanning 52 controllers out through one
- * `Promise.allSettled` printed 51 of them.)
- *
- * Queuing here means exactly one caller per process reaches the fs lock, so the
- * notice regains its cross-process meaning and the losers do no I/O at all. The
- * fs lock is untouched and still provides the cross-process guarantee.
- */
-const localInstallQueues = new Map<string, Promise<unknown>>();
-
-function withLocalInstallQueue<T>(installRoot: string, fn: () => Promise<T>): Promise<T> {
-  const prev = localInstallQueues.get(installRoot) ?? Promise.resolve();
-  // Run on both settle paths: one failed install must not wedge the queue.
-  const run = prev.then(fn, fn);
-  // The stored tail never rejects — a failure neither poisons followers nor
-  // surfaces as an unhandled rejection on the chain copy.
-  const tail = run.then(
-    () => {},
-    () => {},
-  );
-  localInstallQueues.set(installRoot, tail);
-  // Drop the entry once nothing further is queued, so a long-lived process that
-  // touches many entry dirs doesn't retain a promise per root forever.
-  void tail.then(() => {
-    if (localInstallQueues.get(installRoot) === tail) localInstallQueues.delete(installRoot);
-  });
-  return run;
-}
-
-/**
- * Acquire the install lock for `installRoot` and run `fn` under it: first the
- * in-process queue above, then the cross-process filesystem lock.
- */
-async function withInstallLock<T>(
-  installRoot: string,
-  fn: () => Promise<T>,
-  log: Logger = NOOP_LOGGER,
-): Promise<T> {
-  return withLocalInstallQueue(installRoot, () => withFileInstallLock(installRoot, fn, log));
-}
-
-/**
- * Acquire a process-portable lock on `<root>/.lock` and execute fn while
- * holding it. `fs.open(path, 'wx')` is atomic on POSIX and Windows, so
- * concurrent processes serialize naturally.
- *
- * Liveness is a heartbeat: the holder bumps the lock's mtime every
- * {@link LOCK_HEARTBEAT_MS} while `fn` runs, and a waiter reclaims a lock whose
- * mtime is older than {@link LOCK_STALE_MS} (holder crashed/killed/vanished).
- * mtime age is the *only* reclaim signal — the recorded `{pid, host}` is
- * diagnostics, never probed for liveness, because PID identity is unreliable
- * across container restarts and PID namespaces (the failure that deadlocked
- * container boots). Reclaim is via atomic rename to a unique tombstone so two
- * waiters that both see the lock stale can't both win.
- *
- * The lock guards the install-root manifest write, the package-manager
- * invocation, and any state-file writes. It does NOT serialize *reads* of
- * already-installed controllers — those run lock-free against a stable tree.
- */
-async function withFileInstallLock<T>(
-  installRoot: string,
-  fn: () => Promise<T>,
-  log: Logger = NOOP_LOGGER,
-): Promise<T> {
-  const lockPath = path.join(installRoot, ".lock");
-
-  await fs.mkdir(installRoot, { recursive: true });
-
-  const lockBody = JSON.stringify({ pid: process.pid, host: os.hostname(), startedAt: Date.now() });
-  let handle: import("fs/promises").FileHandle | null = null;
-  const waitedSince = Date.now();
-  let noticed = false;
-  while (true) {
-    try {
-      handle = await fs.open(lockPath, "wx");
-      await handle.writeFile(lockBody);
-      break;
-    } catch (err: any) {
-      if (err?.code !== "EEXIST") throw err;
-      // Lock exists. Reclaim it only if its heartbeat has gone silent.
-      if (await reclaimIfStale(lockPath)) continue;
-      const waited = Date.now() - waitedSince;
-      if (waited > LOCK_WAIT_MAX_MS) {
-        throw new Error(
-          `[telo] timed out waiting for install lock at ${lockPath} ` +
-            `(held >${LOCK_WAIT_MAX_MS / 60_000} min with a live heartbeat). ` +
-            `Inspect the lock file or remove it manually if no other Telo process is running.`,
-        );
-      }
-      if (!noticed && waited > LOCK_WAIT_NOTICE_MS) {
-        noticed = true;
-        log.info("waiting for controller install lock", { "telo.install.lock_path": lockPath });
-      }
-      await sleep(LOCK_RETRY_MS);
-    }
-  }
-
-  // Keep the lock fresh while `fn` runs so a slow-but-live install is never
-  // reclaimed. `unref` so the heartbeat can't by itself keep the process alive.
-  const heartbeat = setInterval(() => {
-    const now = new Date();
-    fs.utimes(lockPath, now, now).catch(() => {});
-  }, LOCK_HEARTBEAT_MS);
-  heartbeat.unref?.();
-
-  try {
-    return await fn();
-  } finally {
-    clearInterval(heartbeat);
-    // The fd close races nothing important: if it fails, the FD is reaped on
-    // process exit. The unlink is the dangerous one — a non-ENOENT failure
-    // (permissions, read-only mount) means every subsequent kernel waits
-    // LOCK_STALE_MS before reclaiming. Surface it so the cause is visible
-    // rather than hiding behind a silent hang.
-    await handle!.close().catch(() => {});
-    try {
-      await fs.rm(lockPath, { force: true });
-    } catch (err: any) {
-      if (err?.code !== "ENOENT") {
-        log.warn(
-          "failed to release install lock",
-          { "telo.install.lock_path": lockPath },
-          { error: err },
-        );
-      }
-    }
-  }
-}
-
-/**
- * If the lock at `lockPath` is stale (mtime older than {@link LOCK_STALE_MS}, so
- * its holder stopped heartbeating), atomically claim and remove it and return
- * true; otherwise return false. The claim is a `rename` to a unique tombstone:
- * `rename` is atomic and fails for all but one racer, so two processes that
- * both observe the same stale lock cannot both reclaim it — the loser's rename
- * throws ENOENT (the file is already gone) and it simply retries the open.
- */
-async function reclaimIfStale(lockPath: string): Promise<boolean> {
-  let stat: import("fs").Stats;
-  try {
-    stat = await fs.stat(lockPath);
-  } catch (err: any) {
-    // Race: lock vanished while we inspected it. Retry the open immediately.
-    if (err?.code === "ENOENT") return true;
-    throw err;
-  }
-  if (Date.now() - stat.mtimeMs < LOCK_STALE_MS) return false;
-
-  // Stale — the holder's heartbeat is silent. Claim via atomic rename; only one
-  // racer wins, the rest get ENOENT and fall back to retrying the open.
-  const tombstone = `${lockPath}.stale.${process.pid}.${stat.mtimeMs}`;
-  try {
-    await fs.rename(lockPath, tombstone);
-  } catch (err: any) {
-    if (err?.code === "ENOENT") return true; // another waiter reclaimed it first
-    throw err;
-  }
-  await fs.rm(tombstone, { force: true });
-  return true;
-}
-
 async function runPackageManager(cwd: string, args: string[]): Promise<void> {
   try {
     await execFileAsync(PACKAGE_MANAGER, args, { cwd, maxBuffer: 32 * 1024 * 1024, env: hostEnv() });
@@ -1135,10 +933,6 @@ export const __testing__ = {
   resolveExportTargetValue,
   tryResolveFile,
   computeInstallRoot,
-  withInstallLock,
-  reclaimIfStale,
-  LOCK_STALE_MS,
-  LOCK_HEARTBEAT_MS,
   EXPORTS_MAX_DEPTH,
   DEFAULT_RESOLVER_CONDITIONS,
   REALM_COLLAPSE_NAMES,

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

@@ -14,6 +14,7 @@ import {
   inheritedCapability,
   type DefResolver,
 } from "@telorun/analyzer";
+import type { ModuleArtifact } from "../../bundle/module-artifact.js";
 import { ControllerLoader } from "../../controller-loader.js";
 import { formatAjvErrors, validateResourceDefinition } from "../../manifest-schemas.js";
 import { createTemplateController } from "./resource-template-controller.js";
@@ -162,10 +163,18 @@ class ResourceDefinition implements ResourceInstance {
     // `controllers:` candidate fails fast at boot), but defer the expensive
     // import/eval and the controller's `register()` to the kind's first
     // instantiation. Definitions whose kind is never instantiated never import.
+    // 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
+    // ref and the verified layer index, so the loader picks a candidate and asks
+    // it for that selector's directory rather than fetching anything itself.
+    const artifact = (ctx as unknown as ModuleArtifactHost).getModuleArtifact?.(
+      this.resource.metadata.source,
+    );
     const resolved = await loader.resolve(
       this.resource.controllers,
       this.resource.metadata.source,
       ctx.getControllerPolicy(),
+      artifact,
     );
     ctx.registerDefinition(this.resource);
 
@@ -198,6 +207,16 @@ class ResourceDefinition implements ResourceInstance {
   }
 }
 
+/**
+ * Kernel-internal hook for reaching a module's artifact handle. Off the SDK
+ * surface deliberately: it hands back a kernel class, and only controller
+ * resolution needs it — module authors reach a module's files through
+ * `ctx.resolveModuleFile`, which returns a plain URI.
+ */
+interface ModuleArtifactHost {
+  getModuleArtifact?(source: string | undefined): ModuleArtifact | undefined;
+}
+
 /**
  * Kernel-internal hook the concrete `ResourceContextImpl` exposes for lazy
  * controller loading — deliberately off the public SDK `ResourceContext`

package/src/directory-lock.ts

@@ -0,0 +1,225 @@
+import { NOOP_LOGGER, type Logger } from "@telorun/sdk";
+import * as fs from "fs/promises";
+import * as os from "os";
+import * as path from "path";
+
+/**
+ * The cross-process lock guarding mutation of a shared cache directory.
+ *
+ * Two consumers hold it for the same reason — several Telo processes (and, in
+ * one process, several concurrent resolutions) may decide to populate the same
+ * directory at the same moment: `NpmControllerLoader` around its install root,
+ * and `ModuleArtifact` around a module's extracted layers. One implementation
+ * rather than two, because the reclaim rule below is subtle enough that two
+ * copies would drift.
+ */
+
+/**
+ * A held lock is refreshed (its mtime bumped) every {@link LOCK_HEARTBEAT_MS}
+ * by the holder. Staleness is judged purely by mtime age — a lock older than
+ * this means the holder stopped heartbeating (crashed, was killed, or its
+ * container vanished), so it is safe to reclaim. This deliberately does NOT
+ * probe the recorded PID for liveness: PID identity is meaningless across
+ * container restarts and PID namespaces (deterministic PID reuse makes an
+ * unrelated process look like the dead holder on the same hostname), which is
+ * exactly what deadlocked container boots. The `{pid, host}` in the lock body
+ * is diagnostics for humans, never a reclaim signal. Must be comfortably
+ * larger than the heartbeat interval so a briefly-descheduled holder (GC
+ * pause, busy event loop) is not reclaimed out from under itself.
+ */
+const LOCK_STALE_MS = 30_000;
+
+/** How often the holder refreshes the lock mtime while `fn` runs. Well under
+ *  {@link LOCK_STALE_MS} so several heartbeats are missed before a live holder
+ *  is ever judged stale. */
+const LOCK_HEARTBEAT_MS = 5_000;
+
+/**
+ * Total wall-clock cap for waiting on the lock — enough for a slow first
+ * populate on a peer process to finish, short enough that a genuinely
+ * deadlocked CI job fails loudly rather than hanging for hours. The retry
+ * interval trades wakeup latency vs. wasted polls; 500ms is well below the
+ * lock holder's typical hold time.
+ */
+const LOCK_WAIT_MAX_MS = 5 * 60_000;
+const LOCK_RETRY_MS = 500;
+
+/** After this long waiting on a lock, emit one line so a slow wait is visible
+ *  instead of looking like a silent hang. */
+const LOCK_WAIT_NOTICE_MS = 2_000;
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * In-process serialization ahead of the filesystem lock.
+ *
+ * Without it, N concurrent callers for the same directory all reach the fs lock,
+ * N-1 sit in the retry loop, and each crossing {@link LOCK_WAIT_NOTICE_MS}
+ * prints the wait notice — a notice whose whole point is "another *process* is
+ * populating this", printed when the holder is us. (`telo install` fanning 52
+ * controllers out through one `Promise.allSettled` printed 51 of them.)
+ *
+ * Queuing here means exactly one caller per process reaches the fs lock, so the
+ * notice regains its cross-process meaning and the losers do no I/O at all. The
+ * fs lock is untouched and still provides the cross-process guarantee.
+ */
+const localQueues = new Map<string, Promise<unknown>>();
+
+function withLocalQueue<T>(dir: string, fn: () => Promise<T>): Promise<T> {
+  const prev = localQueues.get(dir) ?? Promise.resolve();
+  // Run on both settle paths: one failure must not wedge the queue.
+  const run = prev.then(fn, fn);
+  // The stored tail never rejects — a failure neither poisons followers nor
+  // surfaces as an unhandled rejection on the chain copy.
+  const tail = run.then(
+    () => {},
+    () => {},
+  );
+  localQueues.set(dir, tail);
+  // Drop the entry once nothing further is queued, so a long-lived process that
+  // touches many directories doesn't retain a promise per directory forever.
+  void tail.then(() => {
+    if (localQueues.get(dir) === tail) localQueues.delete(dir);
+  });
+  return run;
+}
+
+/**
+ * Acquire the lock for `dir` and run `fn` under it: first the in-process queue
+ * above, then the cross-process filesystem lock. `label` names the operation in
+ * the wait notice and timeout error (e.g. "controller install", "module layer").
+ */
+export async function withDirectoryLock<T>(
+  dir: string,
+  label: string,
+  fn: () => Promise<T>,
+  log: Logger = NOOP_LOGGER,
+): Promise<T> {
+  return withLocalQueue(dir, () => withFileLock(dir, label, fn, log));
+}
+
+/**
+ * Acquire a process-portable lock on `<dir>/.lock` and execute fn while
+ * holding it. `fs.open(path, 'wx')` is atomic on POSIX and Windows, so
+ * concurrent processes serialize naturally.
+ *
+ * Liveness is a heartbeat: the holder bumps the lock's mtime every
+ * {@link LOCK_HEARTBEAT_MS} while `fn` runs, and a waiter reclaims a lock whose
+ * mtime is older than {@link LOCK_STALE_MS} (holder crashed/killed/vanished).
+ * mtime age is the *only* reclaim signal — the recorded `{pid, host}` is
+ * diagnostics, never probed for liveness, because PID identity is unreliable
+ * across container restarts and PID namespaces (the failure that deadlocked
+ * container boots). Reclaim is via atomic rename to a unique tombstone so two
+ * waiters that both see the lock stale can't both win.
+ *
+ * The lock guards *writes* into the directory. It does NOT serialize reads of
+ * already-populated content — those run lock-free against a stable tree.
+ */
+async function withFileLock<T>(
+  dir: string,
+  label: string,
+  fn: () => Promise<T>,
+  log: Logger,
+): Promise<T> {
+  const lockPath = path.join(dir, ".lock");
+
+  await fs.mkdir(dir, { recursive: true });
+
+  const lockBody = JSON.stringify({ pid: process.pid, host: os.hostname(), startedAt: Date.now() });
+  let handle: import("fs/promises").FileHandle | null = null;
+  const waitedSince = Date.now();
+  let noticed = false;
+  while (true) {
+    try {
+      handle = await fs.open(lockPath, "wx");
+      await handle.writeFile(lockBody);
+      break;
+    } catch (err: any) {
+      if (err?.code !== "EEXIST") throw err;
+      // Lock exists. Reclaim it only if its heartbeat has gone silent.
+      if (await reclaimIfStale(lockPath)) continue;
+      const waited = Date.now() - waitedSince;
+      if (waited > LOCK_WAIT_MAX_MS) {
+        throw new Error(
+          `[telo] timed out waiting for ${label} lock at ${lockPath} ` +
+            `(held >${LOCK_WAIT_MAX_MS / 60_000} min with a live heartbeat). ` +
+            `Inspect the lock file or remove it manually if no other Telo process is running.`,
+        );
+      }
+      if (!noticed && waited > LOCK_WAIT_NOTICE_MS) {
+        noticed = true;
+        log.info(`waiting for ${label} lock`, { "telo.lock.path": lockPath });
+      }
+      await sleep(LOCK_RETRY_MS);
+    }
+  }
+
+  // Keep the lock fresh while `fn` runs so a slow-but-live operation is never
+  // reclaimed. `unref` so the heartbeat can't by itself keep the process alive.
+  const heartbeat = setInterval(() => {
+    const now = new Date();
+    fs.utimes(lockPath, now, now).catch(() => {});
+  }, LOCK_HEARTBEAT_MS);
+  heartbeat.unref?.();
+
+  try {
+    return await fn();
+  } finally {
+    clearInterval(heartbeat);
+    // The fd close races nothing important: if it fails, the FD is reaped on
+    // process exit. The unlink is the dangerous one — a non-ENOENT failure
+    // (permissions, read-only mount) means every subsequent kernel waits
+    // LOCK_STALE_MS before reclaiming. Surface it so the cause is visible
+    // rather than hiding behind a silent hang.
+    await handle!.close().catch(() => {});
+    try {
+      await fs.rm(lockPath, { force: true });
+    } catch (err: any) {
+      if (err?.code !== "ENOENT") {
+        log.warn(`failed to release ${label} lock`, { "telo.lock.path": lockPath }, { error: err });
+      }
+    }
+  }
+}
+
+/**
+ * If the lock at `lockPath` is stale (mtime older than {@link LOCK_STALE_MS}, so
+ * its holder stopped heartbeating), atomically claim and remove it and return
+ * true; otherwise return false. The claim is a `rename` to a unique tombstone:
+ * `rename` is atomic and fails for all but one racer, so two processes that
+ * both observe the same stale lock cannot both reclaim it — the loser's rename
+ * throws ENOENT (the file is already gone) and it simply retries the open.
+ */
+async function reclaimIfStale(lockPath: string): Promise<boolean> {
+  let stat: import("fs").Stats;
+  try {
+    stat = await fs.stat(lockPath);
+  } catch (err: any) {
+    // Race: lock vanished while we inspected it. Retry the open immediately.
+    if (err?.code === "ENOENT") return true;
+    throw err;
+  }
+  if (Date.now() - stat.mtimeMs < LOCK_STALE_MS) return false;
+
+  // Stale — the holder's heartbeat is silent. Claim via atomic rename; only one
+  // racer wins, the rest get ENOENT and fall back to retrying the open.
+  const tombstone = `${lockPath}.stale.${process.pid}.${stat.mtimeMs}`;
+  try {
+    await fs.rename(lockPath, tombstone);
+  } catch (err: any) {
+    if (err?.code === "ENOENT") return true; // another waiter reclaimed it first
+    throw err;
+  }
+  await fs.rm(tombstone, { force: true });
+  return true;
+}
+
+/**
+ * Internals exposed for the lock's own tests (acquire/release, stale reclaim,
+ * heartbeat, in-process queuing). Not part of the kernel's public API.
+ */
+export const __testing__ = {
+  reclaimIfStale,
+  LOCK_STALE_MS,
+  LOCK_HEARTBEAT_MS,
+};

package/src/evaluation-context.ts

@@ -818,13 +818,23 @@ export class EvaluationContext implements IEvaluationContext {
           child.preInitHook = (resource, childGetInstance, childIsPending) => {
             parentHook(
               resource,
-              (name, alias) =>
-                alias && alias !== "Self"
-                  ? parent.resolveImportedInstance(alias, name)
-                  : childGetInstance(name) ?? parent.resourceInstances.get(name)?.instance,
-              // A scoped ref resolves against the scope's own resources or an already-inited
-              // outer one; only a scope-local dependency can still be pending. The outer is
-              // live by the time a scope opens, so the child's own predicate suffices.
+              (name, alias) => {
+                if (alias && alias !== "Self") return parent.resolveImportedInstance(alias, name);
+                const scoped = childGetInstance(name);
+                if (scoped) return scoped;
+                // A name the scope DECLARES resolves to the scope's instance and to
+                // nothing else. Falling through to the enclosing module while the
+                // scoped one is merely not initialized yet would inject the resource
+                // it shadows — an init-order-dependent wrong answer, and a silent
+                // one: the ref binds an instance that is never started, so the
+                // failure surfaces later as a timeout somewhere else entirely.
+                // Returning nothing leaves it pending, which is what makes the init
+                // loop come back to it.
+                if (child.hasManifest(name)) return undefined;
+                return parent.resourceInstances.get(name)?.instance;
+              },
+              // Only a scope-local dependency can still be pending — an outer resource
+              // is live by the time a scope opens — so the child's own predicate suffices.
               childIsPending,
             );
           };