@telorun/kernel 0.59.0 → 0.61.0

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

@@ -26,6 +26,12 @@ import {
 } from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
 import { evalPathCovers } from "@telorun/analyzer";
+import {
+  classifyInitFailures,
+  renderInitFailureText,
+  summarizeInitFailures,
+  type FailedResource,
+} from "./init-failure-diagnostics.js";
 import {
   acceptReportedStatus,
   buildPublishedProps,
@@ -93,6 +99,16 @@ function collectResourceRefs(resource: ResourceManifest): ResourceRef[] {
   return [...found.values()];
 }
 
+/**
+ * Project resource refs onto the names they depend on IN THIS CONTEXT. A local
+ * ref is its own name; a cross-module `Alias.name` ref depends on the local
+ * `Telo.Import` resource named by the alias, since that is the resource whose
+ * failure would strand it. Used to attribute an init failure to its cause.
+ */
+function localDependencyNames(refs: ResourceRef[]): string[] {
+  return refs.map((r) => (r.alias && r.alias !== "Self" ? r.alias : r.name));
+}
+
 /**
  * Build a resource's resolved properties for the debug stream — its config "after
  * templating", with `${{ }}` / `!cel` reduced to concrete values. The manifest is
@@ -343,6 +359,12 @@ export class EvaluationContext implements IEvaluationContext {
   /** Resources queued for initialization on this context node. */
   private pendingResources: ResourceManifest[] = [];
 
+  /** Per-resource dependency names, captured at create() time — BEFORE Phase-5
+   *  injection swaps refs for live instances, so the walk sees plain objects and
+   *  cannot wander into a controller's (possibly cyclic) object graph. Read only
+   *  when init fails, to attribute each failure to its cause. */
+  private readonly resourceDependencies = new Map<string, string[]>();
+
   /**
    * Optional hook called between create() and init() for each resource.
    * Set by the kernel to inject live instances into reference fields.
@@ -616,7 +638,10 @@ export class EvaluationContext implements IEvaluationContext {
    */
   async initializeResources(): Promise<void> {
     const MAX_PASSES = 10;
-    const errors = new Map<string, { message: string; code?: string; details?: string }>();
+    const errors = new Map<
+      string,
+      { message: string; code?: string; details?: string; children?: RuntimeDiagnostic[] }
+    >();
 
     let pass = 1;
     do {
@@ -641,6 +666,8 @@ export class EvaluationContext implements IEvaluationContext {
             errors.delete(name);
             progress = true;
             const createdRes = created.resource;
+            const refs = collectResourceRefs(createdRes);
+            this.resourceDependencies.set(name, localDependencyNames(refs));
             const payload: Record<string, unknown> = {
               resource: {
                 kind: createdRes.kind,
@@ -649,7 +676,7 @@ export class EvaluationContext implements IEvaluationContext {
                 id: this.resourceId(createdRes.kind, createdRes.metadata.name),
               },
               ...(this.owner ? { owner: this.owner } : {}),
-              dependencies: this.qualifyDeps(collectResourceRefs(createdRes)),
+              dependencies: this.qualifyDeps(refs),
             };
             // `properties` (the resolved config) is a second full config walk plus
             // a secret scrub. Build it lazily: the EventBus short-circuits when
@@ -682,6 +709,7 @@ export class EvaluationContext implements IEvaluationContext {
                   ? this.resolveImportedInstance(alias, n)
                   : this.resourceInstances.get(n)?.instance,
               (n) => this.hasManifest(n) && !this.resourceInstances.has(n),
+              this,
             );
           }
           if (instance.init) await instance.init(ctx);
@@ -694,6 +722,9 @@ export class EvaluationContext implements IEvaluationContext {
           await this.publishSnapshot(name);
           this.resourceInstances.set(name, { resource, instance });
           this.createdInstances.delete(name);
+          // Read only on failure, and this one succeeded — drop it rather than
+          // holding a dep-name array per resource for the context's lifetime.
+          this.resourceDependencies.delete(name);
           errors.delete(name);
           progress = true;
           await this.emit(`${resource.kind}.${resource.metadata.name}.Initialized`, {
@@ -715,38 +746,33 @@ export class EvaluationContext implements IEvaluationContext {
     } while (pass <= MAX_PASSES);
 
     if (this.pendingResources.length > 0 || this.createdInstances.size > 0) {
-      const diagnostics: RuntimeDiagnostic[] = [
-        ...this.pendingResources.map((r) => {
-          const info = errors.get(r.metadata.name) ?? { message: "Unknown error" };
-          return {
-            resource: r.metadata.name,
-            kind: r.kind,
-            message: info.message,
-            details: info.details,
-            code: info.code,
-          };
-        }),
-        ...[...this.createdInstances].map(([name, { resource }]) => {
-          const info = errors.get(name) ?? { message: "Unknown error" };
-          return {
-            resource: name,
-            kind: resource.kind,
-            message: info.message,
-            details: info.details,
-            code: info.code,
-          };
-        }),
+      const toFailure = (name: string, kind: string, deps: string[]): FailedResource => {
+        const info = errors.get(name) ?? { message: "Unknown error" };
+        return {
+          resource: name,
+          kind,
+          message: info.message,
+          details: info.details,
+          code: info.code,
+          children: info.children,
+          deps,
+        };
+      };
+      const failures: FailedResource[] = [
+        // A resource that never got created was never injected either, so its
+        // manifest still carries plain `{kind, name}` refs — walk it here rather
+        // than relying on the create-time capture it never reached.
+        ...this.pendingResources.map((r) =>
+          toFailure(r.metadata.name, r.kind, localDependencyNames(collectResourceRefs(r))),
+        ),
+        ...[...this.createdInstances].map(([name, { resource }]) =>
+          toFailure(name, resource.kind, this.resourceDependencies.get(name) ?? []),
+        ),
       ];
-      const textDetails = diagnostics
-        .map((d) => {
-          const head = `  ${d.kind ? `${d.kind} ` : ""}${d.resource}: ${d.message}${d.code ? ` [${d.code}]` : ""}`;
-          const extra = d.details ? "\n" + d.details.split("\n").map((l) => `    ${l}`).join("\n") : "";
-          return head + extra;
-        })
-        .join("\n");
+      const diagnostics = classifyInitFailures(failures);
       throw new RuntimeError(
         "ERR_RESOURCE_INITIALIZATION_FAILED",
-        `Unable to process resources:\n${textDetails}`,
+        `${summarizeInitFailures(diagnostics)}:\n${renderInitFailureText(diagnostics)}`,
         diagnostics,
       );
     }
@@ -815,7 +841,7 @@ export class EvaluationContext implements IEvaluationContext {
         // Propagate injection hook: extend getInstance to also resolve parent singleton instances.
         if (parent.preInitHook) {
           const parentHook = parent.preInitHook;
-          child.preInitHook = (resource, childGetInstance, childIsPending) => {
+          child.preInitHook = (resource, childGetInstance, childIsPending, owner) => {
             parentHook(
               resource,
               (name, alias) => {
@@ -836,6 +862,9 @@ export class EvaluationContext implements IEvaluationContext {
               // 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,
+              // Forwarded, not replaced by `child`: a `with:` nested inside a scoped
+              // resource must still resolve kinds against the scope it opened in.
+              owner,
             );
           };
         }
@@ -1761,11 +1790,31 @@ function formatErrorForDiagnostic(err: unknown): {
   message: string;
   code?: string;
   details?: string;
+  children?: RuntimeDiagnostic[];
 } {
   if (!(err instanceof Error)) {
     return { message: String(err) };
   }
 
+  // A nested context's aggregate (an import initializing its library's
+  // resources) already carries a classified diagnostic list. Keep it structured
+  // instead of letting the cause-chain walk flatten it into this entry's
+  // message: the child's root causes stay distinguishable from the child's own
+  // cascade, and the error count sees the real leaves rather than one import.
+  // The headline is re-derived from the diagnostics, never recovered by parsing
+  // the message the child already rendered from them.
+  if (
+    err instanceof RuntimeError &&
+    err.code === "ERR_RESOURCE_INITIALIZATION_FAILED" &&
+    err.diagnostics?.length
+  ) {
+    return {
+      message: summarizeInitFailures(err.diagnostics),
+      code: err.code,
+      children: err.diagnostics,
+    };
+  }
+
   const detailLines: string[] = [];
   const seen = new Set<unknown>();
   let current: unknown = err;

package/src/index.ts

@@ -23,11 +23,19 @@ export {
 export { makeTarGz, readTarGz, type BundleEntry } from "./bundle/tar.js";
 export {
   computeFilesIntegrity,
-  injectFilesIntegrity,
+  injectLayerIndex,
   type PayloadFile,
 } from "./bundle/files-integrity.js";
+export {
+  ModuleArtifact,
+  moduleArtifactFor,
+  moduleDirectoryFor,
+  hostPlatformTarget,
+  type MaterializedLayer,
+} from "./bundle/module-artifact.js";
+export { readOwnerManifest, type OwnerManifest } from "./bundle/module-manifest.js";
 export type {
-  FetchedArtifact,
+  PayloadLayer,
   PublishBundle,
   PublishResult,
   PublishOptions,
@@ -39,6 +47,7 @@ export { ModuleContext } from "./module-context.js";
 export { ManifestRegistry as Registry } from "./registry.js";
 export { ResourceURI } from "./resource-uri.js";
 export type { RuntimeDiagnostic } from "@telorun/sdk";
+export { describeBlockedGroup, groupBlockedResources } from "./init-failure-diagnostics.js";
 
 // Structured logging — the runtime half of kernel/specs/logging.md. The record
 // model, severity scale, and `Logger` surface live in `@telorun/sdk`; these are

package/src/init-failure-diagnostics.ts

@@ -0,0 +1,169 @@
+import type { RuntimeDiagnostic } from "@telorun/sdk";
+
+/**
+ * Codes that mean "this resource never got its turn": the multi-pass init loop
+ * deferred it because a dependency had not initialized, so it never produced a
+ * failure of its own. This is the ONLY signal that an entry may be collapsed —
+ * see {@link classifyInitFailures}.
+ */
+const DEPENDENCY_PENDING_CODES = new Set([
+  "ERR_LOCAL_REF_PENDING",
+  "ERR_CROSS_MODULE_REF_PENDING",
+]);
+
+/** One resource that did not reach the `Initialized` state, with the outbound
+ *  edges (names of resources in the SAME context) captured for it. */
+export interface FailedResource {
+  resource: string;
+  kind?: string;
+  message: string;
+  details?: string;
+  code?: string;
+  children?: RuntimeDiagnostic[];
+  deps: string[];
+}
+
+/**
+ * Split a failed-resource set into the ones that failed on their own (root
+ * causes) and the ones that only failed because something else in the set did.
+ *
+ * A dependency chain of any length produces one real error and N shadows of it,
+ * and the shadows outnumber the cause — reporting them flat buries the only
+ * line a reader can act on.
+ *
+ * **What makes an entry derived is its CODE, never its edges.** Only a
+ * {@link DEPENDENCY_PENDING_CODES} deferral says "this resource never ran, so
+ * it has nothing of its own to report". A reference edge into the failure set
+ * proves an edge exists, not that this entry's failure came from it: a resource
+ * can reference a failed dependency AND fail its own schema validation, and
+ * collapsing it there would swallow a real, independent error the author has to
+ * fix — the second half of a two-error session they would only discover on the
+ * next run. (Nor is the edge trustworthy on its own terms: `collectResourceRefs`
+ * walks `with:`-scoped inline declarations, whose names resolve scope-locally,
+ * so a scoped `!ref Db` can collide with a failed module-level `Db`.)
+ *
+ * Edges are used for ATTRIBUTION only — they name which failure a deferred
+ * entry is waiting on. `blockedBy` is the ROOT of the chain, not the immediate
+ * blocker, since that is the name a reader has to go fix; the walk stops at the
+ * first entry that is not itself derived. A deferral with no visible edge (a
+ * `${{ resources.X }}` read the ref walk cannot see) is still derived, just
+ * unattributed.
+ *
+ * Classification never hides everything: if no entry survives as a root (every
+ * failure is a deferral), the whole set is reported unclassified.
+ *
+ * Returns diagnostics ordered root causes first, then the derived entries.
+ */
+export function classifyInitFailures(failures: FailedResource[]): RuntimeDiagnostic[] {
+  const failed = new Set(failures.map((f) => f.resource));
+
+  const derived = new Set(
+    failures.filter((f) => f.code && DEPENDENCY_PENDING_CODES.has(f.code)).map((f) => f.resource),
+  );
+  // Attribution edges are collected for EVERY entry, derived or not: a chain
+  // walk has to pass through an entry to reach the root beyond it.
+  const edgeBlocker = new Map<string, string>();
+  for (const f of failures) {
+    const dep = f.deps.find((n) => n !== f.resource && failed.has(n));
+    if (dep !== undefined) edgeBlocker.set(f.resource, dep);
+  }
+
+  const rootCauseOf = (name: string): string | undefined => {
+    const seen = new Set<string>([name]);
+    let current = edgeBlocker.get(name);
+    while (current !== undefined && !seen.has(current)) {
+      if (!derived.has(current)) return current;
+      seen.add(current);
+      current = edgeBlocker.get(current);
+    }
+    return undefined;
+  };
+
+  const toDiagnostic = (f: FailedResource, isDerived: boolean): RuntimeDiagnostic => {
+    const blockedBy = isDerived ? rootCauseOf(f.resource) : undefined;
+    return {
+      resource: f.resource,
+      kind: f.kind,
+      message: f.message,
+      details: f.details,
+      code: f.code,
+      ...(f.children?.length ? { children: f.children } : {}),
+      ...(isDerived ? { derived: true, ...(blockedBy ? { blockedBy } : {}) } : {}),
+    };
+  };
+
+  const roots = failures.filter((f) => !derived.has(f.resource));
+  if (roots.length === 0) return failures.map((f) => toDiagnostic(f, false));
+
+  return [
+    ...roots.map((f) => toDiagnostic(f, false)),
+    ...failures.filter((f) => derived.has(f.resource)).map((f) => toDiagnostic(f, true)),
+  ];
+}
+
+/** Group the derived entries by the root cause they hang off, so a renderer can
+ *  collapse each chain to a single line instead of repeating one failure N
+ *  times. Entries whose blocker could not be named group under `undefined`. */
+export function groupBlockedResources(
+  diagnostics: RuntimeDiagnostic[],
+): Map<string | undefined, string[]> {
+  const groups = new Map<string | undefined, string[]>();
+  for (const d of diagnostics) {
+    if (!d.derived) continue;
+    const key = d.blockedBy;
+    const names = groups.get(key) ?? [];
+    names.push(d.resource ?? "(unnamed)");
+    groups.set(key, names);
+  }
+  return groups;
+}
+
+/** One collapsed line per blocked chain, e.g.
+ *  `9 resources blocked by GrantDb: GrantStore, GoogleTokens, ...`. */
+export function describeBlockedGroup(blockedBy: string | undefined, names: string[]): string {
+  const subject = `${names.length} resource${names.length !== 1 ? "s" : ""}`;
+  const blocker = blockedBy ?? "an uninitialized dependency";
+  return `${subject} blocked by ${blocker}: ${names.join(", ")}`;
+}
+
+/** The headline for a classified failure set. Shared by the aggregate error's
+ *  own message and by the entry an importing context builds for it, so the two
+ *  are never recovered by re-parsing each other's rendered text. */
+export function summarizeInitFailures(diagnostics: RuntimeDiagnostic[]): string {
+  const total = diagnostics.length;
+  const roots = diagnostics.filter((d) => !d.derived).length;
+  const blocked = total - roots;
+  return (
+    `${total} resource${total !== 1 ? "s" : ""} failed to initialize` +
+    (blocked > 0 ? ` (${roots} root cause${roots !== 1 ? "s" : ""}, rest blocked)` : "")
+  );
+}
+
+/** Render a classified failure set as the text body of the aggregate error
+ *  message — root causes in full, each blocked chain collapsed to one line.
+ *  Nested children recurse through this same function so a child list is
+ *  traversed exactly once, groups included. */
+export function renderInitFailureText(diagnostics: RuntimeDiagnostic[]): string {
+  const lines: string[] = [];
+  for (const d of diagnostics) {
+    if (!d.derived) {
+      lines.push(
+        `  ${d.kind ? `${d.kind} ` : ""}${d.resource}: ${d.message}${d.code ? ` [${d.code}]` : ""}`,
+      );
+      if (d.details) lines.push(...d.details.split("\n").map((l) => `    ${l}`));
+    }
+    // A derived entry contributes no line of its own, but a nested context's
+    // root causes are not shadows of THIS context's failure — they still report.
+    if (d.children?.length) {
+      lines.push(
+        ...renderInitFailureText(d.children)
+          .split("\n")
+          .map((l) => `  ${l}`),
+      );
+    }
+  }
+  for (const [blockedBy, names] of groupBlockedResources(diagnostics)) {
+    lines.push(`  ${describeBlockedGroup(blockedBy, names)}`);
+  }
+  return lines.join("\n");
+}