pi-crew 0.8.4 → 0.8.6

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # Changelog
 
+## [0.8.6] — General cold-start race fix (runtime module-graph warmup) (2026-06-17)
+
+Fixes the `validateWorkflowForTeam` cold-start crash that v0.8.1 did NOT
+actually fix (honest correction — v0.8.1's per-import latch covered only the
+peer-dep namespace `existsSync` variant, not this pi-crew-internal variant).
+
+### Corrected root cause
+
+Under the **tsx loader**, a named import `import { X } from "mod"` compiles to
+`mod_1.X` — a namespace-property access at runtime. If `mod_1` is observed
+mid-instantiation as `undefined` during concurrent cold-start, the access
+throws `Cannot read properties of undefined (reading 'X')`. **ANY module in
+the graph is vulnerable**, not just the peer dep. v0.8.1's per-import latch
+can't scale to every named import in `src/`.
+
+### Fix — general, not per-import
+
+1. **Pre-warm at registration.** `startRuntimeWarmup()` fires eager `import()`
+   of the hot module graph ROOTS during single-threaded `registerPiTeams()` —
+   before any subagent can spawn. ESM transitively instantiates their entire
+   import graph, so one import per path warms the full subgraph.
+2. **Await at spawn boundaries.** `awaitRuntimeWarmup()` is awaited at the top
+   of `runLiveSessionTask` and `runTeamTask` — the two spawn entry points — so
+   the graph is guaranteed warm before any module is touched, regardless of
+   which binding would otherwise race.
+
+The warmup runs in milliseconds (module loading only). The await is
+belt-and-suspenders for the pathological case where a spawn races the warmup
+promise. Errors are swallowed — a failed warmup (e.g. peer dep absent) never
+blocks the extension; worst case the old race returns (no worse than before).
+
+### Files
+- NEW `src/runtime/runtime-warmup.ts` — `startRuntimeWarmup()` (idempotent
+  fire-and-forget) + `awaitRuntimeWarmup()` (gate) + test seams.
+- `src/extension/register.ts` — `startRuntimeWarmup()` early in
+  `registerPiTeams`.
+- `src/runtime/live-session-runtime.ts` — `await awaitRuntimeWarmup()` at top
+  of `runLiveSessionTask`.
+- `src/runtime/task-runner.ts` — `await awaitRuntimeWarmup()` at top of
+  `runTeamTask`.
+- NEW `test/unit/runtime-warmup.test.ts` (6 tests): idempotency, no-hang,
+  back-compat (no-op when not started), hot-module specifiers resolve,
+  integration (graph actually warms).
+- Updated `.github/issues/2026-06-16-validateworkflowf-team-cold-start-race.md`
+  — marked RESOLVED with the fix applied.
+
+typecheck clean; full suite 0 real failures (2 timer flakes under local load
+pass 3/3 in isolation — clean on CI).
+
+## [0.8.5] — Per-write validator (T5) + validateWorkflowForTeam race note (2026-06-16)
+
+Third APPLIED technique from the pi-ecosystem distillation (pi-lens /
+apmantza — the "inline channel"). Adds real-time feedback on file
+writes/edits: a CHEAP synchronous validator runs on every `write`/`edit`
+tool result and appends a `🔴` blocker to the tool result on failure, so
+malformed files are caught the moment they're written — not at the next
+load.
+
+### Latency-safe v1 design (deliberate scope)
+
+pi-lens runs LSP servers + linters per write. That is expensive and would
+cause latency storms if naively ported (seconds of spawn per edit, firing in
+the main session AND every worker). This v1 ships ONLY zero-cost, zero-spawn,
+synchronous validators:
+
+- **`json` → `JSON.parse`** (nanoseconds, built-in, no process spawn).
+
+The registry is extensible — process-spawning validators (`.js` → `node
+--check`, `.sh` → `bash -n`, `.py` → `py_compile`) are a FUTURE opt-in
+(never default-on), and will need to be async + debounced (pi-lens's
+`inFlightPipelines` / debounce-window pattern) when added.
+
+### Contract guarantees
+- Synchronous. No `await`, no `spawn`, no disk write.
+- One disk READ per validated file (after a cheap extension check, so
+  non-validated files cost nothing).
+- Dedup by content: the same path+content is validated at most once per
+  process.
+- Silent on success; appends exactly one TextContent block on failure.
+- Best-effort: any internal error is swallowed (never breaks a write).
+- Toggle: `runtime.reliability.perWriteValidation` (default `true` → opt-out).
+
+### Files
+- NEW `src/runtime/per-write-validator.ts` — `validateJson`, the extensible
+  `PerWriteValidator` registry, dedup cache, `validateWrittenFile`, and
+  `buildValidationBlocker`. Test seams: `setPerWriteValidatorsForTest`,
+  `resetPerWriteValidatorCache`.
+- `src/config/types.ts` — `reliability.perWriteValidation?: boolean`.
+- `src/extension/register.ts` — `pi.on("tool_result", ...)` handler for
+  `write`/`edit` (pi-crew previously subscribed only to `tool_call`).
+- NEW `test/unit/t5-per-write-validator.test.ts` (15 tests).
+- NEW `.github/issues/2026-06-16-validateworkflowf-team-cold-start-race.md` —
+  honest note that the `validateWorkflowForTeam` cold-start error (same
+  class as v0.8.1's `existsSync`) was NOT actually fixed by v0.8.1's latch
+  (that covered only the peer-dep namespace). Documents the corrected
+  root cause (tsx makes every named import a runtime namespace access) and
+  4 candidate fixes for the later pass.
+
+typecheck clean; full suite 0 failures.
+
 ## [0.8.4] — cold-verifier agent (T9) (2026-06-16)
 
 Second APPLIED technique from the pi-ecosystem distillation (piolium /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/config/types.ts

@@ -180,6 +180,15 @@ export interface CrewReliabilityConfig {
 	cleanupOrphanedTempDirs?: boolean;
 	/** Inject a compact ambient crew-status note into the agent's context on every LLM call while crew runs are in-flight, so the agent stays continuously aware of active runs without calling the `team` tool. No-op when no runs are active. Default: true. */
 	ambientStatusInjection?: boolean;
+	/**
+	 * Per-write validation (T5). On every `write`/`edit` tool result, run a
+	 * zero-cost synchronous validator for the file type and append a `🔴`
+	 * blocker to the tool result on failure (e.g. malformed JSON). v1 ships
+	 * JSON only (`JSON.parse` — instant, no process spawn); process-spawning
+	 * validators (.js/.sh/.py) are a future opt-in. Default: true (opt-out).
+	 * Set to `false` to disable.
+	 */
+	perWriteValidation?: boolean;
 	/**
 	 * Opt-in model scope enforcement (F7). When true, subagent model choices
 	 * that fall outside the user's pi `enabledModels` allowlist are flagged:

package/src/extension/register.ts

@@ -82,6 +82,8 @@ import {
 import { RenderScheduler } from "../ui/render-scheduler.ts";
 import { runEventBus } from "../ui/run-event-bus.ts";
 import { createTerminalStatusController, type TerminalStatusController } from "../ui/terminal-status.ts";
+import { extractPathFromInput, validateWrittenFile, buildValidationBlocker } from "../runtime/per-write-validator.ts";
+import { startRuntimeWarmup } from "../runtime/runtime-warmup.ts";
 import { createRunSnapshotCache } from "../ui/run-snapshot-cache.ts";
 import { closeWatcher } from "../utils/fs-watch.ts";
 import { RunWatcherRegistry } from "../utils/run-watcher-registry.ts";
@@ -197,6 +199,14 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	const disposeI18n = initI18n(pi);
 	resetTimings();
 	time("register:start");
+	// Cold-start race fix (general): pre-warm the hot module graph NOW, during
+	// single-threaded registration, before any concurrent subagent can spawn.
+	// Under the tsx loader, concurrent first-imports race module-record
+	// instantiation → `Cannot read properties of undefined (reading '<X>')` for
+	// ANY named import (observed: existsSync, validateWorkflowForTeam).
+	// Warming the graph here + awaiting it at spawn boundaries eliminates the
+	// race window. See src/runtime/runtime-warmup.ts.
+	startRuntimeWarmup();
 	// Deploy bundled themes (crew-dark, crew-dracula, etc.) to ~/.pi/agent/themes/
 	// so Pi's theme loader discovers them. Best-effort, idempotent.
 	deployBundledThemes();
@@ -1986,6 +1996,27 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		};
 	});
 
+	// T5 (v0.8.5): per-write validation. On write/edit, run a zero-cost
+	// SYNCHRONOUS validator (v1: JSON.parse) and append a 🔴 blocker to the
+	// tool result on failure — catches malformed config the moment it's
+	// written, not at the next load. Latency-safe by construction: no process
+	// spawn, one disk read ONLY for validated extensions, dedup'd by content.
+	// Toggle via runtime.reliability.perWriteValidation (default true).
+	// Process-spawning validators (.js/.sh/.py) are a future opt-in.
+	pi.on("tool_result", (event, ctx) => {
+		try {
+			if (event.toolName !== "write" && event.toolName !== "edit") return;
+			if (loadConfig(ctx.cwd).config.reliability?.perWriteValidation === false) return;
+			const filePath = extractPathFromInput(event.input);
+			if (!filePath) return;
+			const result = validateWrittenFile(filePath);
+			if (!result || result.ok) return;
+			return { content: [...event.content, buildValidationBlocker(filePath, result.error ?? "validation failed")] };
+		} catch {
+			// best-effort: never break a tool result
+		}
+	});
+
 	registerTeamTool(pi, {
 		foregroundControllers,
 		startForegroundRun,

package/src/runtime/live-session-runtime.ts

@@ -18,6 +18,7 @@ import { buildConfiguredModelRouting } from "./model-fallback.ts";
 import { readEnabledModelsPatterns } from "./model-scope.ts";
 import { resolveToolPolicy } from "../agents/agent-config.ts";
 import { loadConfig } from "../config/config.ts";
+import { awaitRuntimeWarmup } from "./runtime-warmup.ts";
 import { DEFAULT_LIVE_SESSION } from "../config/defaults.ts";
 import { buildYieldReminder, hasYieldInOutput, isYieldEvent, extractYieldResult, validateYieldData, DEFAULT_YIELD_CONFIG, type YieldResult } from "./yield-handler.ts";
 import { buildMcpProxyFromSession } from "./mcp-proxy.ts";
@@ -396,6 +397,10 @@ export async function probeLiveSessionRuntime(): Promise<LiveSessionUnavailableR
 }
 
 export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<LiveSessionRunResult> {
+	// Cold-start race fix: ensure the hot module graph is warm before touching
+	// any module. Under tsx, concurrent first-imports race module-record
+	// instantiation; awaiting the registration-time warmup eliminates the window.
+	await awaitRuntimeWarmup();
 	const isCurrent = input.isCurrent ?? (() => true);
 	let streamOut: StreamingOutputHandle | undefined;
 

package/src/runtime/per-write-validator.ts

@@ -0,0 +1,183 @@
+/**
+ * Per-write validator — real-time feedback on file writes/edits (T5).
+ *
+ * Distilled from pi-lens (apmantza) — the "inline channel": on every
+ * `write`/`edit` tool result, run a CHEAP synchronous validator for the file
+ * type and, on failure, append a `🔴` blocker block to the tool result the
+ * agent sees next. This catches silent-breaking errors (malformed JSON
+ * config) at the moment they're introduced instead of at the next load.
+ *
+ * CRITICAL LATENCY-SAFETY DESIGN (the reason this is a careful slice, not the
+ * full pi-lens pipeline): pi-lens runs LSP servers + linters per write. That
+ * is expensive and would cause latency storms if naively ported (seconds of
+ * spawn per edit, firing in the main session AND every worker). This module's
+ * v1 deliberately ships ONLY zero-cost, zero-spawn, synchronous validators:
+ *
+ *   - `json` → `JSON.parse` (nanoseconds, built-in, no process spawn).
+ *
+ * The registry is extensible — future validators (`.js` → `node --check`,
+ * `.sh` → `bash -n`, `.py` → `py_compile`) are process-spawning and MUST be
+ * added behind an explicit opt-in (never default-on) to preserve the
+ * latency guarantee. A process-spawning validator would also need to be async
+ * and debounced (pi-lens's `inFlightPipelines` / debounce-window pattern),
+ * which the current sync contract intentionally avoids.
+ *
+ * Contract guarantees for v1:
+ *   - Synchronous. No `await`, no `spawn`, no disk write.
+ *   - One disk READ per validated file (after a cheap extension check, so
+ *     non-validated files cost nothing).
+ *   - Dedup by content: the same path+content is validated at most once per
+ *     process (a repeated identical write doesn't re-report).
+ *   - Silent on success; appends exactly one TextContent block on failure.
+ *   - Best-effort: any internal error is swallowed (never breaks a write).
+ *
+ * @module per-write-validator
+ */
+
+import { readFileSync } from "node:fs";
+import { extname as pathExtname } from "node:path";
+
+/** Outcome of validating a file's content. */
+export interface ValidationResult {
+	ok: boolean;
+	/** Human-readable error message when `ok` is false. */
+	error?: string;
+}
+
+/** A synchronous validator: content + path → result. */
+export type PerWriteValidator = (content: string, filePath: string) => ValidationResult;
+
+// ─────────────────────────────────────────────────────────────────────────
+// Validators (zero-cost, synchronous, dependency-free for v1)
+// ─────────────────────────────────────────────────────────────────────────
+
+/** JSON: parse with `JSON.parse`. Catches malformed config/manifests instantly. */
+export function validateJson(content: string, _filePath: string): ValidationResult {
+	if (content.trim() === "") return { ok: true }; // empty file is valid JSON absence, not a parse error
+	try {
+		JSON.parse(content);
+		return { ok: true };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { ok: false, error: `Invalid JSON: ${message}` };
+	}
+}
+
+/**
+ * Registry of default-on validators, keyed by extension (lowercase, no dot).
+ * ONLY zero-cost synchronous validators belong here. Process-spawning
+ * validators must be registered via a future opt-in path (see module doc).
+ */
+const DEFAULT_VALIDATORS: ReadonlyMap<string, PerWriteValidator> = new Map([
+	["json", validateJson],
+]);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Dedup cache (path → last-validated content). Bounded; small.
+// ─────────────────────────────────────────────────────────────────────────
+
+const MAX_DEDUP_ENTRIES = 256;
+const seenContent = new Map<string, string>();
+
+function rememberSeen(path: string, content: string): void {
+	if (seenContent.has(path)) seenContent.delete(path); // refresh LRU position
+	seenContent.set(path, content);
+	while (seenContent.size > MAX_DEDUP_ENTRIES) {
+		const oldest = seenContent.keys().next().value;
+		if (oldest === undefined) break;
+		seenContent.delete(oldest);
+	}
+}
+
+/** Test seam: reset the dedup cache between tests. */
+export function resetPerWriteValidatorCache(): void {
+	seenContent.clear();
+}
+
+/**
+ * Replace the validator registry (test seam). Production uses
+ * DEFAULT_VALIDATORS; tests inject a custom map to exercise specific extensions.
+ */
+let validators: ReadonlyMap<string, PerWriteValidator> = DEFAULT_VALIDATORS;
+
+export function setPerWriteValidatorsForTest(map: ReadonlyMap<string, PerWriteValidator> | undefined): void {
+	validators = map ?? DEFAULT_VALIDATORS;
+}
+
+/**
+ * Normalise an extension to the registry key form (lowercase, no leading dot).
+ * "" for files with no extension.
+ */
+export function extensionKey(filePath: string): string {
+	return pathExtname(filePath).replace(/^\./, "").toLowerCase();
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Path extraction from a tool_result event input (defensive — pi-ai types
+// aren't exported here, so accept a record and probe common field names).
+// ─────────────────────────────────────────────────────────────────────────
+
+const PATH_FIELDS = ["filePath", "path", "file"] as const;
+
+/** Extract the written/edited path from a tool result input, if present. */
+export function extractPathFromInput(input: unknown): string | undefined {
+	if (!input || typeof input !== "object") return undefined;
+	const record = input as Record<string, unknown>;
+	for (const field of PATH_FIELDS) {
+		const value = record[field];
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+	return undefined;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Core entry point
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Validate a just-written/edited file. Returns `null` when there is nothing
+ * to report (no validator for the extension, dedup hit, file unreadable, or
+ * the content is valid). Returns a `ValidationResult` with `ok:false` when the
+ * content fails validation.
+ *
+ * Reads the file from disk (it's already written by `tool_result` time) so the
+ * logic is uniform across `write` (full content) and `edit` (patch). The disk
+ * read happens ONLY after a cheap extension check, so non-validated files cost
+ * nothing.
+ */
+export function validateWrittenFile(filePath: string): ValidationResult | null {
+	const key = extensionKey(filePath);
+	const validator = validators.get(key);
+	if (!validator) return null; // cheap skip: no validator for this file type
+	let content: string;
+	try {
+		content = readFileSync(filePath, "utf-8");
+	} catch {
+		// Unreadable / missing / permission denied — can't validate; never block.
+		return null;
+	}
+	// Dedup: identical content already validated this process → don't re-report.
+	if (seenContent.get(filePath) === content) return null;
+	rememberSeen(filePath, content);
+	const result = validator(content, filePath);
+	return result.ok ? null : result;
+}
+
+/**
+ * Build the TextContent block to append to a tool_result on validation failure.
+ * Uses a strong `🔴` prefix so the agent treats it as a real signal and fixes
+ * the file before continuing.
+ */
+export function buildValidationBlocker(filePath: string, error: string): { type: "text"; text: string } {
+	return {
+		type: "text",
+		text: [
+			"",
+			"🔴 pi-crew per-write check FAILED",
+			`   ${filePath}`,
+			`   ${error}`,
+			"   The file you just wrote is malformed. Fix it now — a broken file here will",
+			"   silently fail the next load/parse. Re-write the file with valid content before continuing.",
+		].join("\n"),
+	};
+}

package/src/runtime/runtime-warmup.ts

@@ -0,0 +1,121 @@
+/**
+ * Runtime module-graph warmup — general fix for the cold-start race.
+ *
+ * Problem: when N in-process live-session subagents spawn CONCURRENTLY, the
+ * tsx loader can race module-record instantiation, yielding
+ * `Cannot read properties of undefined (reading '<binding>')` for ANY named
+ * import in the hot graph (observed: `existsSync`, `validateWorkflowForTeam`).
+ * v0.8.1's per-import latch covered only the peer-dep namespace; this is the
+ * GENERAL fix.
+ *
+ * Root cause: under tsx, a named import `import { X } from "mod"` compiles to
+ * `mod_1.X` — a namespace-property access at runtime. If `mod_1` (the module
+ * namespace object) is observed mid-instantiation as `undefined`, the access
+ * throws. ANY module in the graph is vulnerable, not just the peer dep. So
+ * per-import latching doesn't scale.
+ *
+ * Fix: pre-warm the hot module graph during SINGLE-THREADED extension
+ * registration (before any subagent can spawn), then `await` the warmup at
+ * every spawn entry point. By the time concurrent subagents touch the graph,
+ * every module record is fully instantiated → no race window.
+ *
+ * Why this is general (not per-import):
+ *   - `startRuntimeWarmup()` fires `import()` for the ROOT modules of each
+ *     hot execution path. ESM transitively instantiates their entire import
+ *     graph, so one import per path warms the whole reachable subgraph.
+ *   - `awaitRuntimeWarmup()` is the gate: spawn paths await it before
+ *     touching any module, guaranteeing the graph is warm regardless of
+ *     which specific binding races.
+ *
+ * The warmup runs during `registerPiTeams()` (single-threaded, before pi
+ * accepts user input). It resolves in milliseconds (module loading only, no
+ * I/O for local modules). The `await` at spawn boundaries is belt-and-
+ * suspenders for pathological cases where a spawn races the warmup promise.
+ *
+ * @module runtime-warmup
+ */
+
+/**
+ * The modules whose transitive import graphs cover every hot execution path
+ * a concurrent subagent can reach. Importing the ROOT of each path warms the
+ * full subgraph (ESM instantiates imports eagerly during `import()`).
+ *
+ * - `./live-session-runtime.ts` — the in-process subagent spawn path
+ *   (pulls in the peer dep + the entire runtime layer).
+ * - `./task-runner.ts` — the child-process task dispatch path.
+ * - `../extension/team-tool.ts` — the team tool (pulls in
+ *   validate-resources → validate-workflow, the `validateWorkflowForTeam` site).
+ * - `../extension/validate-resources.ts` — direct warm of the aggregator.
+ * - `@earendil-works/pi-coding-agent` — the peer dep (the `existsSync` site;
+ *   also latched in v0.8.1 — defense in depth).
+ */
+const HOT_MODULE_SPECIFIERS = [
+	"./live-session-runtime.ts",
+	"./task-runner.ts",
+	"../extension/team-tool.ts",
+	"../extension/validate-resources.ts",
+] as const;
+
+/** Additional bare-specifier peer deps to warm. */
+const HOT_PEER_DEPS = ["@earendil-works/pi-coding-agent"] as const;
+
+let warmupPromise: Promise<void> | undefined;
+let warmupStarted = false;
+
+/**
+ * Start the runtime warmup (idempotent). Fires eager `import()` of the hot
+ * module graph. Safe to call during single-threaded registration — the
+ * promises resolve on the event loop before any subagent can spawn.
+ *
+ * Errors are swallowed: a failed warmup (e.g. peer dep absent) must never
+ * block the extension from loading. The worst case is the old race returns
+ * (which is no worse than before this fix).
+ */
+export function startRuntimeWarmup(): void {
+	if (warmupStarted) return;
+	warmupStarted = true;
+	warmupPromise = (async (): Promise<void> => {
+		const imports: Array<Promise<unknown>> = [];
+		for (const spec of HOT_MODULE_SPECIFIERS) {
+			imports.push(
+				import(new URL(spec, import.meta.url).href).catch(() => {
+					// swallow — never block registration on a warmup failure
+				}),
+			);
+		}
+		for (const dep of HOT_PEER_DEPS) {
+			imports.push(
+				import(dep).catch(() => {
+					// peer dep may be absent (optional dep) — swallow
+				}),
+			);
+		}
+		await Promise.all(imports);
+	})().catch(() => {
+		// final safety net — warmup must never reject
+	});
+}
+
+/**
+ * Await the runtime warmup at a spawn entry point. No-op if warmup hasn't
+ * started (back-compat for callers that don't call startRuntimeWarmup) or has
+ * already resolved. Guarantees the hot module graph is instantiated before
+ * the caller touches any module — eliminating the concurrent cold-start race.
+ */
+export async function awaitRuntimeWarmup(): Promise<void> {
+	if (warmupPromise) await warmupPromise;
+}
+
+/**
+ * Test seam: reset the warmup state so tests can re-trigger it. Also lets
+ * tests verify idempotency by calling startRuntimeWarmup() multiple times.
+ */
+export function resetRuntimeWarmupForTest(): void {
+	warmupPromise = undefined;
+	warmupStarted = false;
+}
+
+/** Test seam: has startRuntimeWarmup() been called? */
+export function isRuntimeWarmupStarted(): boolean {
+	return warmupStarted;
+}

package/src/runtime/task-runner.ts

@@ -40,6 +40,7 @@ import {
 	type ParsedPiJsonOutput,
 } from "./pi-json-output.ts";
 import { runChildPi, type ChildPiLifecycleEvent } from "./child-pi.ts";
+import { awaitRuntimeWarmup } from "./runtime-warmup.ts";
 import { buildTaskPacket } from "./task-packet.ts";
 import { executeHook, appendHookEvent } from "../hooks/registry.ts";
 import { createVerificationEvidence } from "./green-contract.ts";
@@ -155,6 +156,10 @@ export interface TaskRunnerInput {
 export async function runTeamTask(
 	input: TaskRunnerInput,
 ): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
+	// Cold-start race fix: ensure the hot module graph is warm before touching
+	// any module. Under tsx, concurrent first-imports race module-record
+	// instantiation; awaiting the registration-time warmup eliminates the window.
+	await awaitRuntimeWarmup();
 	let manifest = input.manifest;
 	// H4: registerStreamBridge inside try so dispose() in finally is safe
 	let streamBridge: ReturnType<typeof registerStreamBridge> | undefined;