@ggui-ai/ui-gen 0.22.0 → 0.24.0

package/src/evaluation/types-public.ts

@@ -20,6 +20,7 @@
 
 export type Priority = "P0" | "P1" | "P2";
 
+import type { GenerationRuntimeProbeOutcome, GenerationRuntimeProbeStatus } from "@ggui-ai/mcp-server-core";
 import type { CanvasClass, DesignMode } from "../design-mode.js";
 
 // ─── Issue shape ───────────────────────────────────────────────────────────
@@ -63,8 +64,10 @@ export interface EvalIssue {
 }
 
 /**
- * Runtime-render probe execution status — three-valued so "the probe
- * never ran" is never conflated with "the probe ran clean".
+ * Runtime-render probe execution status — four-valued so "the probe
+ * never ran" is never conflated with "the probe ran clean". ONE union: the
+ * same values a generation's metadata reports (`GenerationRuntimeProbeStatus`
+ * in `@ggui-ai/mcp-server-core`), declared there and named here.
  *
  *   - `ran`           — probe executed; its findings (possibly none) are
  *                       in the issue stream under `runtime:*` subcategories.
@@ -74,20 +77,96 @@ export interface EvalIssue {
  *                       consumers MUST NOT count it as a pass.
  *   - `not-applicable`— nothing to probe (no compiled code, no contract
  *                       surface, or no runtimeRender check configured).
+ *   - `timed-out`     — probe started but did not finish inside its
+ *                       wall-clock bound (ggui#1299). Carries ZERO
+ *                       evidence about the component: on a contended
+ *                       host an ordinary component crosses the bound.
+ *                       Consumers MUST NOT count it as a pass, and MUST
+ *                       NOT count it as a crash either. `elapsedMs` and
+ *                       `hostLoad` say how long it ran and how busy the
+ *                       host was, so a reader can tell the two cases apart.
  */
-export type RuntimeProbeStatus = "ran" | "infra-skipped" | "not-applicable";
+export type RuntimeProbeStatus = GenerationRuntimeProbeStatus;
+
+/**
+ * The host's 1-minute load average at a probe's start and end, beside the
+ * number of CPUs the process can use (ggui#1299). A load well above
+ * `cores` means the probe competed for CPU; a wall-clock bound crossed
+ * there says more about the host than about the component.
+ */
+export interface ProbeHostLoad {
+  readonly start: number;
+  readonly end: number;
+  readonly cores: number;
+}
+
+/**
+ * The engine's own fields on a probe's meta, beside the outcome a
+ * generation's metadata reports: why a probe did not finish, its render
+ * time, the host's load around it. Present on every arm of
+ * {@link RuntimeProbeMeta}; each is absent when the probe had nothing to
+ * say about it.
+ */
+export interface RuntimeProbeMetaDetail {
+  /** Populated for `infra-skipped` / `not-applicable` / `timed-out` — why the probe didn't finish. */
+  readonly reason?: string;
+  /** `ran` only: the check's own render time, inside `elapsedMs`. */
+  readonly renderMs?: number;
+  /** Host load around the probe, when it ran isolated (absent for an in-process probe). */
+  readonly hostLoad?: ProbeHostLoad;
+  /** Time the check waited for a probe slot before it started, ms; present only when > 0 (ggui#1380 C2b). */
+  readonly queuedMs?: number;
+}
 
 /**
  * Probe execution meta stamped onto an `EvalResult` at the exit-decision
  * points that invoke the probe. Absence of this field means the eval
  * path never reached a probe invocation at all — consumers treat that
  * the same as not-run, never as a pass.
+ *
+ * ONE union with the generation metadata's probe outcome
+ * (`GenerationRuntimeProbeOutcome` in `@ggui-ai/mcp-server-core`, declared
+ * there and carried here with {@link RuntimeProbeMetaDetail} on every arm),
+ * so the round's stamp and the metadata's record cannot say different
+ * things (ggui#1380):
+ *
+ *   - `ran` + `verdict: 'pass'` — the probe executed and no check failed;
+ *   - `ran` + `verdict: 'fail'` — ANY check failed; `failChecks` lists the
+ *     distinct check kinds that did (`RenderCheckKind`, the engine's name
+ *     for the same union), never empty, in the order `RENDER_CHECK_KINDS`
+ *     declares them, parsed from the probe's own
+ *     `runtime:<check>[:<subject>]` issues;
+ *   - `timed-out` / `infra-skipped` / `not-applicable` — no verdict, and the
+ *     type carries none. `elapsedMs` (on every status that reached the
+ *     check) and `hostLoad` say how long it ran and how busy the host was.
+ *
+ * The verdict and the repair trigger are two different questions. The
+ * verdict is `fail` on any failing check. The one repair turn a probe-only
+ * round buys fires on a `render-no-throw` fail the engine recognises
+ * (`isRecoverableRenderCrash`) and on nothing else: a `fail` verdict whose
+ * checks are `prop-sensitivity`, `action-wiring` or any other kind is
+ * recorded here and never fed back.
  */
-export interface RuntimeProbeMeta {
-  readonly status: RuntimeProbeStatus;
-  /** Populated for `infra-skipped` / `not-applicable` — why the probe didn't run. */
-  readonly reason?: string;
-}
+export type RuntimeProbeMeta = GenerationRuntimeProbeOutcome & RuntimeProbeMetaDetail;
+
+/**
+ * The one repair turn a probe-only round buys (ggui#1380). A serving
+ * deployment that wires the runtime probe and configures no evaluator runs
+ * the probe once after the coding turns; a render crash the engine
+ * recognises buys exactly one repair turn, then one re-probe. This records
+ * what came of it:
+ *   - `compiled: false` — the repair turn's code did not pass self-check, so
+ *     no re-probe ran (there is no `after`) and the pre-repair card is the
+ *     one served;
+ *   - `compiled: true` — the re-probe ran and `after` is its whole meta:
+ *     its status, its verdict when it ran, and the checks that still fail.
+ *     Whether the crash class the turn was bought for is still there is
+ *     `after.verdict === 'fail' && after.failChecks.includes('render-no-throw')`.
+ * The two arms are exclusive by type.
+ */
+export type RuntimeProbeRepair =
+  | { readonly attempted: true; readonly compiled: false; readonly trigger?: never }
+  | { readonly attempted: true; readonly compiled: true; readonly trigger: RuntimeProbeMeta };
 
 /**
  * Per-criterion execution status — three-valued so "the criterion
@@ -202,6 +281,13 @@ export interface EvalResult {
    * probe runner; absent on eval paths that never invoke the probe.
    */
   runtimeProbe?: RuntimeProbeMeta;
+  /**
+   * The probe-only round's repair record (ggui#1380) — present only when a
+   * recoverable render crash bought the one repair turn. See
+   * {@link RuntimeProbeRepair}. `runtimeProbe` beside it is the re-probe's
+   * verdict when the repair compiled, else the pre-repair probe's.
+   */
+  runtimeProbeRepair?: RuntimeProbeRepair;
   /**
    * The contract-feedback round, when one fired this generation (ggui#1261):
    * which exit-probe findings bought it and the source as it stood when the

package/src/harness/check/runtime-render/adapter.ts

@@ -6,62 +6,205 @@
 
 import type { EvalIssue } from "../../../evaluation/types-public.js";
 import type { RuntimeRenderCheck } from "../../types-public.js";
-import { runRenderCheck, type RenderCheckIssue } from "./render-check.js";
+import {
+  RENDER_CHECK_KINDS,
+  runRenderCheck,
+  type RenderCheckIssue,
+  type RenderCheckKind,
+  type RunRenderCheckOptions,
+} from "./render-check.js";
+import { resolveRenderCheckHostBounds } from "./render-check-host.js";
 import { prepareMockupProps } from "./prepare-mockup.js";
 
-export const DEFAULT_RUNTIME_RENDER_CHECK: RuntimeRenderCheck = {
-  id: "runtime-render",
-  run: async input => {
-    const { sourceCode, compiledCode, contract, fixtureProps } = input;
+/**
+ * How one runtime-render check instance runs its isolated worker
+ * (ggui#1380). A serving deployment sets the probe's wall-clock bound,
+ * worker heap and concurrency here; every field omitted is the evaluation
+ * lane's behaviour — the host's default bounds and no concurrency cap.
+ */
+export interface RuntimeRenderProbeConfig {
+  /** Wall-clock bound of one isolated check, ms. Default: the host's (30 000). */
+  readonly timeoutMs?: number;
+  /** V8 heap cap of the worker, MB. Default: the host's (512). */
+  readonly heapMb?: number;
+  /**
+   * Live workers this instance may have at once. The (K+1)th check waits
+   * in FIFO order and spawns only when a slot frees; a check that throws
+   * releases its slot. Default: unbounded. Must be a positive integer.
+   */
+  readonly maxConcurrent?: number;
+}
 
-    // Nothing to render / no contract surface to verify — the probe has
-    // no subject, which is different from the probe failing to run.
-    if (compiledCode === null) {
-      return { status: "not-applicable", issues: [], reason: "no compiled code" };
+/**
+ * K-slot FIFO limiter. `undefined` slots = no limiter (the task runs at
+ * once). A slot is released in `finally`, so a rejected task never holds
+ * one.
+ */
+function createSlotLimiter(
+  maxConcurrent: number | undefined
+): <T>(task: (waitedMs: number) => Promise<T>) => Promise<T> {
+  if (maxConcurrent === undefined) return (task) => task(0);
+  if (!Number.isInteger(maxConcurrent) || maxConcurrent < 1) {
+    throw new RangeError(
+      `createRuntimeRenderCheck: maxConcurrent must be a positive integer, got ${maxConcurrent}`
+    );
+  }
+  let active = 0;
+  const waiting: Array<() => void> = [];
+  /** Resolves with the time the caller actually WAITED for a slot: 0 when one was free. */
+  const acquire = (): Promise<number> => {
+    if (active < maxConcurrent) {
+      active += 1;
+      return Promise.resolve(0);
     }
-    if (!contract) {
-      return { status: "not-applicable", issues: [], reason: "no contract surface" };
+    const enqueuedAt = Date.now();
+    return new Promise<number>((resolve) => {
+      waiting.push(() => {
+        active += 1;
+        resolve(Date.now() - enqueuedAt);
+      });
+    });
+  };
+  const release = (): void => {
+    active -= 1;
+    const next = waiting.shift();
+    if (next !== undefined) next();
+  };
+  return async (task) => {
+    const waitedMs = await acquire();
+    try {
+      return await task(waitedMs);
+    } finally {
+      release();
     }
+  };
+}
 
-    const mockup = prepareMockupProps({ contract, fixtureProps });
+/** `{ queuedMs }` when the check actually waited for a slot, `{}` when one was free. */
+function queuedField(queuedMs: number): { readonly queuedMs?: number } {
+  return queuedMs > 0 ? { queuedMs } : {};
+}
 
-    let result;
-    try {
-      result = await runRenderCheck({
-        sourceCode,
-        mockupProps: mockup.props,
-        contract,
-      });
-    } catch (e) {
-      // Triad audit (2026-04-27): every error that escapes `runRenderCheck`
-      // is an INFRA problem — happy-dom import failure, ESM/CJS interop
-      // (`Dynamic require of "events"`), bundler name collision (`Window2
-      // is not a constructor`), missing `@testing-library/react`, etc.
-      // Component-level failures are caught and emitted as `RenderCheckIssue`
-      // entries from inside `runRenderCheck`; they don't propagate out.
-      //
-      // An infra failure must never become an eval issue (the coding
-      // agent can't fix the environment — pre-2026-04-27 that phantom
-      // issue dragged every score-below-80 cell's eval-fix loop), but it
-      // must also never be silent to scoring: ggui#403 found the bench
-      // reporting `probe_pass 3/3` on cells where this branch fired on
-      // every invocation. The `infra-skipped` status is the No-Silent-
-      // Block channel — consumers surface it as did-not-run, never pass.
-      const message = e instanceof Error ? e.message : String(e);
-      console.warn(
-        `[runtime-render] probe skipped — infra failure: ${message}`,
-      );
-      return { status: "infra-skipped", issues: [], reason: message };
-    }
+/** The `runRenderCheck` options a config maps to — `undefined` when no bound is set. */
+function toRenderCheckOptions(config: RuntimeRenderProbeConfig): RunRenderCheckOptions | undefined {
+  if (config.timeoutMs === undefined && config.heapMb === undefined) return undefined;
+  return {
+    bounds: {
+      ...(config.timeoutMs !== undefined ? { timeoutMs: config.timeoutMs } : {}),
+      ...(config.heapMb !== undefined ? { heapMb: config.heapMb } : {}),
+    },
+  };
+}
+
+/**
+ * Build a runtime-render check instance. One FIFO limiter per instance;
+ * the bounds reach `runRenderCheck` on every run. `createRuntimeRenderCheck()`
+ * with no config is {@link DEFAULT_RUNTIME_RENDER_CHECK}'s behaviour.
+ */
+export function createRuntimeRenderCheck(
+  config: RuntimeRenderProbeConfig = {}
+): RuntimeRenderCheck {
+  const limit = createSlotLimiter(config.maxConcurrent);
+  const options = toRenderCheckOptions(config);
+  // A bad bound is refused here, at construction, never at the first probe.
+  if (options !== undefined) resolveRenderCheckHostBounds(options.bounds);
+  return {
+    id: "runtime-render",
+    run: async (input) => {
+      const { sourceCode, compiledCode, contract, fixtureProps } = input;
 
-    return {
-      status: "ran",
-      issues: result.issues
-        .map(toEvalIssue)
-        .filter((x): x is EvalIssue => x !== null),
-    };
-  },
-};
+      // Nothing to render / no contract surface to verify — the probe has
+      // no subject, which is different from the probe failing to run.
+      if (compiledCode === null) {
+        return { status: "not-applicable", issues: [], reason: "no compiled code" };
+      }
+      if (!contract) {
+        return { status: "not-applicable", issues: [], reason: "no contract surface" };
+      }
+
+      const mockup = prepareMockupProps({ contract, fixtureProps });
+
+      // ggui#1380 — the adapter's own clock around the check: every status
+      // that reached the check (`ran`, `timed-out`, `infra-skipped`) reports
+      // how long it took, so a reader of the probe meta can tell a 2 s probe
+      // from a 30 s one on the same status. The two not-applicable returns
+      // above carry nothing: nothing ran.
+      // The clock starts when the slot is acquired, so `elapsedMs` is the
+      // check's own wall-clock; the time the check actually WAITED for a slot
+      // is `queuedMs` (present only when it queued) — a latency reader needs
+      // the two apart exactly when a serving deployment queues more probes
+      // than it has slots. A check that found a slot free carries no key.
+      let queuedMs = 0;
+      let t0 = Date.now();
+      let result;
+      try {
+        result = await limit((waitedMs) => {
+          queuedMs = waitedMs;
+          t0 = Date.now();
+          return runRenderCheck(
+            {
+              sourceCode,
+              mockupProps: mockup.props,
+              contract,
+            },
+            options
+          );
+        });
+      } catch (e) {
+        // Triad audit (2026-04-27): every error that escapes `runRenderCheck`
+        // is an INFRA problem — happy-dom import failure, ESM/CJS interop
+        // (`Dynamic require of "events"`), bundler name collision (`Window2
+        // is not a constructor`), missing `@testing-library/react`, etc.
+        // Component-level failures are caught and emitted as `RenderCheckIssue`
+        // entries from inside `runRenderCheck`; they don't propagate out.
+        //
+        // An infra failure must never become an eval issue (the coding
+        // agent can't fix the environment — pre-2026-04-27 that phantom
+        // issue dragged every score-below-80 cell's eval-fix loop), but it
+        // must also never be silent to scoring: ggui#403 found the bench
+        // reporting `probe_pass 3/3` on cells where this branch fired on
+        // every invocation. The `infra-skipped` status is the No-Silent-
+        // Block channel — consumers surface it as did-not-run, never pass.
+        const message = e instanceof Error ? e.message : String(e);
+        console.warn(`[runtime-render] probe skipped — infra failure: ${message}`);
+        return { status: "infra-skipped", issues: [], reason: message, elapsedMs: Date.now() - t0, ...queuedField(queuedMs) };
+      }
+
+      const hostLoad = result.stats.hostLoad;
+      const load = hostLoad !== undefined ? { hostLoad } : {};
+
+      // ggui#1299: a check that ran out of wall-clock time is not a verdict on
+      // the component. It becomes the `timed-out` status (did-not-run, never a
+      // pass, never a crash), never an eval issue — so the coding agent is never
+      // told to fix a crash that did not happen.
+      if (result.incomplete !== undefined) {
+        const { elapsedMs, boundMs } = result.incomplete;
+        const loadNote =
+          hostLoad !== undefined
+            ? `; host load ${hostLoad.start.toFixed(1)} → ${hostLoad.end.toFixed(1)} on ${hostLoad.cores} CPUs`
+            : "";
+        const reason = `render check did not finish within ${boundMs} ms (stopped at ${elapsedMs} ms)${loadNote}`;
+        console.warn(`[runtime-render] probe timed out — ${reason}`);
+        // One clock for every status that reached the worker: the adapter's
+        // wall-clock around the check. The worker's own reading survives in
+        // `reason` ("stopped at N ms").
+        return { status: "timed-out", issues: [], reason, elapsedMs: Date.now() - t0, ...queuedField(queuedMs), ...load };
+      }
+
+      return {
+        status: "ran",
+        issues: result.issues.map(toEvalIssue).filter((x): x is EvalIssue => x !== null),
+        elapsedMs: Date.now() - t0,
+        ...queuedField(queuedMs),
+        renderMs: result.stats.renderMs,
+        ...load,
+      };
+    },
+  };
+}
+
+/** The evaluation lane's instance: the host's default bounds, no concurrency cap. */
+export const DEFAULT_RUNTIME_RENDER_CHECK: RuntimeRenderCheck = createRuntimeRenderCheck();
 
 /**
  * Map a runtime-render crash reason to a class-specific fix string.
@@ -158,11 +301,7 @@ export function classifyRenderCrashFix(reason: string): string {
       "(b) check it's an array before iterating (`Array.isArray(x) && ...`)."
     );
   }
-  if (
-    r.includes("cannot read") ||
-    r.includes("undefined is not") ||
-    r.includes("null is not")
-  ) {
+  if (r.includes("cannot read") || r.includes("undefined is not") || r.includes("null is not")) {
     return (
       "Null/undefined access. Add optional chaining (`obj?.field`) and " +
       "default values for optional props/state before reading nested fields. " +
@@ -176,7 +315,32 @@ export function classifyRenderCrashFix(reason: string): string {
   );
 }
 
-function toEvalIssue(issue: RenderCheckIssue): EvalIssue | null {
+/** The prefix every probe issue's subcategory carries: `runtime:<check>[:<subject>]`. */
+const RUNTIME_SUBCATEGORY_PREFIX = "runtime:";
+
+/**
+ * The check a probe issue's subcategory names (ggui#1380) — the inverse of
+ * the `runtime:<check>[:<subject>]` form {@link toEvalIssue} writes, so a
+ * round can list WHICH checks failed from the issues alone. `undefined` for
+ * anything that is not a probe subcategory naming a member of
+ * {@link RENDER_CHECK_KINDS} (an axis check's subcategory, a did-not-run
+ * code such as `runtime:probe-timeout`, a bare check name).
+ */
+export function parseRuntimeSubcategory(subcategory: string): RenderCheckKind | undefined {
+  if (!subcategory.startsWith(RUNTIME_SUBCATEGORY_PREFIX)) return undefined;
+  const rest = subcategory.slice(RUNTIME_SUBCATEGORY_PREFIX.length);
+  const separator = rest.indexOf(":");
+  const check = separator === -1 ? rest : rest.slice(0, separator);
+  return RENDER_CHECK_KINDS.find((kind) => kind === check);
+}
+
+/**
+ * One probe finding → the eval issue the loop feeds back and the metadata
+ * counts. Exported for the pin that every switch case below is a member of
+ * {@link RENDER_CHECK_KINDS} and round-trips through
+ * {@link parseRuntimeSubcategory}.
+ */
+export function toEvalIssue(issue: RenderCheckIssue): EvalIssue | null {
   // verified → no issue (silent pass)
   if (issue.outcome === "verified" || issue.outcome === "skipped") return null;
 
@@ -209,7 +373,7 @@ function toEvalIssue(issue: RenderCheckIssue): EvalIssue | null {
     diagParts.push(
       "primed" in diag.inputPriming
         ? `input priming: ${diag.inputPriming.primed} control(s) filled before the click`
-        : `input priming failed: ${diag.inputPriming.error}`,
+        : `input priming failed: ${diag.inputPriming.error}`
     );
   }
   const diagSuffix = diagParts.length ? ` [observed: ${diagParts.join("; ")}]` : "";
@@ -245,9 +409,10 @@ function toEvalIssue(issue: RenderCheckIssue): EvalIssue | null {
       };
 
     case "action-wiring": {
-      const fix = issue.outcome === "unverified"
-        ? `Source shows the action callback flowing into a non-native or custom-component prop. If wiring is intentional (e.g., Dropdown.onChange, drag-drop), this warn is informational — manual/browser verification is required to confirm. Otherwise wire to a native onClick={() => ${subject}(payload)} on <button> or design-system <Button>.`
-        : `Wire ${subject}() to a native event prop. Common fix: <Button onClick={() => ${subject}(payload)}>Label</Button>. Source-AST analysis didn't find this wiring in your JSX.`;
+      const fix =
+        issue.outcome === "unverified"
+          ? `Source shows the action callback flowing into a non-native or custom-component prop. If wiring is intentional (e.g., Dropdown.onChange, drag-drop), this warn is informational — manual/browser verification is required to confirm. Otherwise wire to a native onClick={() => ${subject}(payload)} on <button> or design-system <Button>.`
+          : `Wire ${subject}() to a native event prop. Common fix: <Button onClick={() => ${subject}(payload)}>Label</Button>. Source-AST analysis didn't find this wiring in your JSX.`;
       return {
         tier: 0,
         result,

package/src/harness/check/runtime-render/index.ts

@@ -10,15 +10,26 @@
 //   - declared stream events update the DOM when emitted    (warn)
 
 import { installProductionActShim } from "./production-act-shim.js";
+import type { RenderCheckHostBounds } from "./render-check-host.js";
 
-export { runRenderCheck, type RenderCheckResult, type RenderCheckIssue } from "./render-check.js";
+export {
+  RENDER_CHECK_KINDS,
+  runRenderCheck,
+  type RenderCheckKind,
+  type RenderCheckResult,
+  type RenderCheckIssue,
+} from "./render-check.js";
 export { createProbe, createProbeWireConfig, type Probe } from "./probe.js";
 export { prepareMockupProps, type MockupPropsResult } from "./prepare-mockup.js";
 export {
   DEFAULT_RUNTIME_RENDER_CHECK,
   classifyRenderCrashFix,
+  createRuntimeRenderCheck,
   isRecoverableRenderCrash,
+  parseRuntimeSubcategory,
+  type RuntimeRenderProbeConfig,
 } from "./adapter.js";
+export type { RenderCheckHostBounds, RenderCheckHostOptions } from "./render-check-host.js";
 
 /**
  * Pre-warm the runtime-render probe's runtime dependencies so the first
@@ -41,7 +52,11 @@ export {
  *
  * Returns the wall-clock spent loading.
  */
-export async function warmupRuntimeRenderProbe(): Promise<{ ms: number; loaded: number; missing: number }> {
+export async function warmupRuntimeRenderProbe(): Promise<{
+  ms: number;
+  loaded: number;
+  missing: number;
+}> {
   const start = Date.now();
   let loaded = 0;
   let missing = 0;
@@ -67,3 +82,61 @@ export async function warmupRuntimeRenderProbe(): Promise<{ ms: number; loaded:
   ]);
   return { ms: Date.now() - start, loaded, missing };
 }
+
+/**
+ * The component the boot warm renders: a constant element, an empty
+ * contract — nothing to click, nothing to cover, one compile and one
+ * render in the worker.
+ */
+const WARMUP_COMPONENT = "export default function Warmup() { return <div>warm</div>; }";
+
+/**
+ * Warm the PROCESS that runs every probe (ggui#1380): spawn one real check
+ * worker on a trivial component through the same host every probe uses.
+ * Afterwards the node binary, the worker's module tree and esbuild's
+ * service have all run once on this machine (OS page cache warm), and the
+ * result says whether that process can run a check at all — which
+ * `warmupRuntimeRenderProbe` (an import in THIS process) cannot tell.
+ *
+ * `bounds` are the subprocess bounds for the one run; a serving deployment
+ * passes the same bounds it will probe with. Never throws: a worker that
+ * cannot run is `{ ok: false, reason }`, so a boot sequence can log it and
+ * decide, instead of dying in a fire-and-forget.
+ */
+export async function warmupRuntimeRenderWorker(
+  bounds?: Partial<RenderCheckHostBounds>
+): Promise<{ ok: true; ms: number } | { ok: false; ms: number; reason: string }> {
+  const start = Date.now();
+  try {
+    // Lazy: the host pulls `@ggui-ai/sandbox` (spawn machinery); keep it off
+    // the import graph of everything that only needs the in-process check.
+    const { runRenderCheckViaWorker } = await import("./render-check-host.js");
+    const result = await runRenderCheckViaWorker(
+      { sourceCode: WARMUP_COMPONENT, mockupProps: {}, contract: {} },
+      bounds !== undefined ? { bounds } : {}
+    );
+    const ms = Date.now() - start;
+    if (result.incomplete !== undefined) {
+      return {
+        ok: false,
+        ms,
+        reason: `the warm-up check did not finish within ${result.incomplete.boundMs} ms (stopped at ${result.incomplete.elapsedMs} ms)`,
+      };
+    }
+    const blocking = result.issues.find(
+      (i) => i.outcome === "failed" || i.outcome === "unverified"
+    );
+    if (blocking !== undefined) {
+      return { ok: false, ms, reason: `${blocking.check} ${blocking.outcome}: ${blocking.reason}` };
+    }
+    return { ok: true, ms };
+  } catch (err) {
+    // The host itself never throws for a worker fault; what reaches here is
+    // the spawn layer refusing to run at all (an invalid bound, no binary).
+    return {
+      ok: false,
+      ms: Date.now() - start,
+      reason: err instanceof Error ? err.message : String(err),
+    };
+  }
+}