@ggui-ai/ui-gen 0.22.0 → 0.24.0

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

@@ -11,13 +11,24 @@
  * `unverified`, and nothing throws):
  *
  *   - worker exit 0 + parseable verdict → the verdict, verbatim.
- *   - timeout                    → `failed` (runaway component: the
- *     in-process check has no comparable wall-clock bound, the
- *     subprocess finally gives us one).
- *   - spawn-error / overflow / non-zero exit / unparseable stdout
+ *   - timeout                    → `incomplete` (ggui#1299): the check
+ *     did not finish, which is NOT a verdict on the component. The bound
+ *     is wall-clock, and on a contended host an ordinary component
+ *     crosses it; mapping it to `failed` reported crashes that never
+ *     happened. It carries its elapsed ms, and the host load (below)
+ *     says how busy the host was. React's own runaway guards ("Too many
+ *     re-renders", "Maximum update depth exceeded") throw, so they still
+ *     reach `render-no-throw` as `failed`; what now reads `incomplete`
+ *     is a check that ran out of wall-clock time, whatever the cause.
+ *   - overflow                   → `failed` (a pathological logging or
+ *     error loop; output volume does not depend on host load).
+ *   - spawn-error / non-zero exit / unparseable stdout
  *                                → `unverified` (the harness could not
  *     run the check; never blame the component for our plumbing).
  *
+ * Every isolated check records the host's 1-minute load average at its
+ * start and end, and the CPUs available, on `stats.hostLoad`.
+ *
  * Spawn resolution copies the proven `src/tools/render-check.ts`
  * pattern: prefer the built `dist/.../render-check-worker.js`; in
  * dev/test (vitest imports `src/`), fall back to `node --import tsx`
@@ -29,18 +40,78 @@
  */
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { availableParallelism, loadavg } from 'node:os';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { runSandboxed } from '@ggui-ai/sandbox';
 import type { SandboxResult } from '@ggui-ai/sandbox';
+import type { ProbeHostLoad } from '../../../evaluation/types-public.js';
 import type { RenderCheckResult, RunRenderCheckInput } from './render-check.js';
 
 /**
- * Wall-clock bound for one isolated check. The rich probe renders,
- * clicks every declared action, and re-renders streams — slower than
- * the smoke worker's 12s budget; 30s bounds runaway components while
- * staying far under any generation-turn budget.
+ * The subprocess bounds of one isolated check (ggui#1380). They are
+ * INPUTS of the host, not constants: a serving deployment runs the probe
+ * under its own memory and latency budget and sets them per check
+ * instance (`createRuntimeRenderCheck`); the evaluation lane runs on the
+ * defaults below, which are the values the host always used.
+ */
+export interface RenderCheckHostBounds {
+  /**
+   * Wall-clock bound for one isolated check. The rich probe renders,
+   * clicks every declared action, and re-renders streams — slower than
+   * the smoke worker's 12s budget; 30s bounds runaway components while
+   * staying far under any generation-turn budget.
+   */
+  readonly timeoutMs: number;
+  /**
+   * V8 heap cap. The worker realm loads react-dom, happy-dom and
+   * testing-library on top of the component itself; 512 MB leaves
+   * headroom while still bounding pathological allocation.
+   */
+  readonly heapMb: number;
+  /**
+   * Grace between SIGTERM and SIGKILL once the bound is crossed. The
+   * effective value is `min(gracePeriodMs, floor(timeoutMs / 2))` —
+   * `runSandboxed` requires the grace to be strictly below the bound, so
+   * a short bound never trips its RangeError.
+   */
+  readonly gracePeriodMs: number;
+}
+
+export const DEFAULT_RENDER_CHECK_HOST_BOUNDS: RenderCheckHostBounds = {
+  timeoutMs: 30_000,
+  heapMb: 512,
+  gracePeriodMs: 2_000,
+};
+
+/**
+ * Fill the caller's partial bounds from the defaults and clamp the grace
+ * below the bound. Exported so the kill-path pin can run a fixture under
+ * exactly the numbers the host would pass for the same input.
  */
-const CHECK_TIMEOUT_MS = 30_000;
+export function resolveRenderCheckHostBounds(
+  bounds: Partial<RenderCheckHostBounds> = {},
+): RenderCheckHostBounds {
+  const timeoutMs = bounds.timeoutMs ?? DEFAULT_RENDER_CHECK_HOST_BOUNDS.timeoutMs;
+  const heapMb = bounds.heapMb ?? DEFAULT_RENDER_CHECK_HOST_BOUNDS.heapMb;
+  // Refused at construction, like `maxConcurrent`: a 0 / NaN / fractional
+  // bound would otherwise flow into the sandbox's flags as a nonsense number.
+  // `timeoutMs` needs room for a grace of at least 1 ms below it.
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 2) {
+    throw new RangeError(`render-check: timeoutMs must be an integer ≥ 2, got ${timeoutMs}`);
+  }
+  if (!Number.isInteger(heapMb) || heapMb < 1) {
+    throw new RangeError(`render-check: heapMb must be a positive integer, got ${heapMb}`);
+  }
+  const requestedGrace = bounds.gracePeriodMs ?? DEFAULT_RENDER_CHECK_HOST_BOUNDS.gracePeriodMs;
+  const gracePeriodMs = Math.max(1, Math.min(requestedGrace, Math.floor(timeoutMs / 2)));
+  return { timeoutMs, heapMb, gracePeriodMs };
+}
+
+/** Options of {@link runRenderCheckViaWorker}. */
+export interface RenderCheckHostOptions {
+  /** Subprocess bounds; every field omitted falls to {@link DEFAULT_RENDER_CHECK_HOST_BOUNDS}. */
+  readonly bounds?: Partial<RenderCheckHostBounds>;
+}
 
 /**
  * stdout cap. The verdict JSON carries issue lists with diagnostics
@@ -49,16 +120,14 @@ const CHECK_TIMEOUT_MS = 30_000;
  */
 const CHECK_STDOUT_CAP = 2 * 1024 * 1024;
 
-/**
- * V8 heap cap. The worker realm loads react-dom, happy-dom and
- * testing-library on top of the component itself; 512 MB leaves
- * headroom while still bounding pathological allocation.
- */
-const CHECK_NODE_HEAP_MB = 512;
-
 const WORKER_BASENAME = 'render-check-worker';
 
-function resolveWorkerSpawn(): { command: string; args: string[] } {
+/**
+ * How the host spawns the worker from THIS location: the built dist sibling
+ * when one exists, else the source `.ts` through tsx. Exported so the entry
+ * guard can be pinned with the same spawn the host makes (no build needed).
+ */
+export function resolveWorkerSpawn(): { command: string; args: string[] } {
   const jsCandidates = [
     // Sibling — when import.meta.url is already .../harness/check/runtime-render/.
     new URL(`./${WORKER_BASENAME}.js`, import.meta.url),
@@ -113,18 +182,22 @@ function unverified(reason: string, t0: number): RenderCheckResult {
 }
 
 /**
- * Map one sandbox result onto a `RenderCheckResult`. Exported for the
- * unit pins — the spawn itself is exercised by the integration test.
+ * Map one sandbox result onto a `RenderCheckResult`. `boundMs` is the
+ * wall-clock bound the run was given, reported on a timeout. Exported for
+ * the unit pins — the spawn itself is exercised by the integration test.
  */
 export function mapSandboxResultToCheckResult(
   result: SandboxResult,
   t0: number,
+  boundMs: number = DEFAULT_RENDER_CHECK_HOST_BOUNDS.timeoutMs,
 ): RenderCheckResult {
   if (result.outcome === 'timeout') {
-    return failed(
-      `render check timed out after ${CHECK_TIMEOUT_MS}ms in the isolated worker (likely infinite loop or runaway effect in the component).`,
-      t0,
-    );
+    return {
+      ok: false,
+      issues: [],
+      incomplete: { kind: 'timeout', elapsedMs: result.durationMs, boundMs },
+      stats: { actionsChecked: 0, streamsChecked: 0, renderMs: Date.now() - t0 },
+    };
   }
   if (result.outcome === 'overflow-stdout' || result.outcome === 'overflow-stderr') {
     return failed(
@@ -172,11 +245,15 @@ export function mapSandboxResultToCheckResult(
 
 /**
  * Run the render check in an isolated subprocess. See module doc.
+ * `options.bounds` sets the subprocess bounds for this run; omitted
+ * fields are the evaluation lane's defaults.
  */
 export async function runRenderCheckViaWorker(
   input: RunRenderCheckInput,
+  options: RenderCheckHostOptions = {},
 ): Promise<RenderCheckResult> {
   const t0 = Date.now();
+  const bounds = resolveRenderCheckHostBounds(options.bounds);
   let spawn: { command: string; args: string[] };
   try {
     spawn = resolveWorkerSpawn();
@@ -184,12 +261,14 @@ export async function runRenderCheckViaWorker(
     return unverified(err instanceof Error ? err.message : String(err), t0);
   }
 
+  const loadAtStart = loadavg()[0] ?? 0;
   const result = await runSandboxed({
     command: spawn.command,
     args: spawn.args,
-    timeoutMs: CHECK_TIMEOUT_MS,
+    timeoutMs: bounds.timeoutMs,
+    gracePeriodMs: bounds.gracePeriodMs,
     maxStdoutBytes: CHECK_STDOUT_CAP,
-    nodeHeapMb: CHECK_NODE_HEAP_MB,
+    nodeHeapMb: bounds.heapMb,
     stdin: JSON.stringify(input),
     // NODE_ENV steers React's production vs development build — keep
     // parity with the caller; everything else stays on the sandbox's
@@ -197,5 +276,11 @@ export async function runRenderCheckViaWorker(
     env: { NODE_ENV: process.env.NODE_ENV ?? 'production' },
   });
 
-  return mapSandboxResultToCheckResult(result, t0);
+  const hostLoad: ProbeHostLoad = {
+    start: loadAtStart,
+    end: loadavg()[0] ?? 0,
+    cores: availableParallelism(),
+  };
+  const mapped = mapSandboxResultToCheckResult(result, t0, bounds.timeoutMs);
+  return { ...mapped, stats: { ...mapped.stats, hostLoad } };
 }

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

@@ -28,7 +28,20 @@
  * (the render SMOKE worker): reached by spawn path, never by import
  * specifier; registered as a tsup entry so `dist/harness/check/
  * runtime-render/render-check-worker.js` ships.
+ *
+ * Shutdown (ggui#1380): the compile runs on esbuild's service, a child
+ * process esbuild keeps alive for the life of this worker. After the
+ * verdict is written the worker calls `esbuild.stop()` so that child is
+ * gone before the worker is; a worker stopped at its wall-clock bound is
+ * killed by the host, and the service's stdin closing with it is what
+ * ends the service in that case. `workerMain` is exported for the
+ * process-shape pins; `main()` runs only when this file is the process
+ * entry, so importing it never reads stdin.
  */
+import { realpathSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as esbuild from 'esbuild';
 import { runRenderCheckInProcess } from './render-check.js';
 import type { RunRenderCheckInput } from './render-check.js';
 
@@ -44,37 +57,78 @@ function emit(value: unknown): void {
   process.stdout.write(`${JSON.stringify(value)}\n`);
 }
 
-async function main(): Promise<void> {
-  const raw = await readAllStdin();
-  let input: RunRenderCheckInput;
+/**
+ * Parse one input document, run the check, write the verdict. Whatever
+ * happens after parsing, esbuild's service is stopped before this
+ * returns (or rejects). If the service was never started, `stop()` is a
+ * no-op.
+ */
+export async function workerMain(raw: string): Promise<void> {
   try {
-    input = JSON.parse(raw) as RunRenderCheckInput;
-  } catch (err) {
-    process.stderr.write(
-      `render-check worker: malformed input JSON — ${
-        err instanceof Error ? err.message : String(err)
-      }\n`,
-    );
-    process.exitCode = 1;
-    return;
-  }
-  if (typeof input.sourceCode !== 'string' || input.sourceCode.length === 0) {
-    process.stderr.write(
-      'render-check worker: input.sourceCode must be a non-empty string\n',
-    );
-    process.exitCode = 1;
-    return;
+    let input: RunRenderCheckInput;
+    try {
+      input = JSON.parse(raw) as RunRenderCheckInput;
+    } catch (err) {
+      process.stderr.write(
+        `render-check worker: malformed input JSON — ${
+          err instanceof Error ? err.message : String(err)
+        }\n`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+    if (typeof input.sourceCode !== 'string' || input.sourceCode.length === 0) {
+      process.stderr.write(
+        'render-check worker: input.sourceCode must be a non-empty string\n',
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    // The in-process check never throws for component failures (they are
+    // reported as issues); an escape here is a harness defect — let it
+    // crash the worker so the host maps it to `unverified` with the
+    // stderr tail as the reason.
+    const result = await runRenderCheckInProcess(input);
+    emit(result);
+    // The check's async-infra grace period (React scheduler drain) holds
+    // handlers for ~100ms; exit through the event loop naturally so that
+    // drain completes inside the worker instead of leaking crashes.
+  } finally {
+    // Post-verdict work must never turn a written verdict into a failure:
+    // a rejecting `stop()` would otherwise become an unhandled rejection,
+    // exit code 1, and the host discarding the verdict on stdout.
+    try {
+      await esbuild.stop();
+    } catch (err) {
+      process.stderr.write(
+        `render-check worker: esbuild.stop() failed — ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+    }
   }
+}
 
-  // The in-process check never throws for component failures (they are
-  // reported as issues); an escape here is a harness defect — let it
-  // crash the worker so the host maps it to `unverified` with the
-  // stderr tail as the reason.
-  const result = await runRenderCheckInProcess(input);
-  emit(result);
-  // The check's async-infra grace period (React scheduler drain) holds
-  // handlers for ~100ms; exit through the event loop naturally so that
-  // drain completes inside the worker instead of leaking crashes.
+async function main(): Promise<void> {
+  await workerMain(await readAllStdin());
+}
+
+/** True when this file is the process entry (`node <this file>`), not an import. */
+function isProcessEntry(): boolean {
+  const entry = process.argv[1];
+  if (entry === undefined) return false;
+  // Resolve BOTH sides through the filesystem: `import.meta.url` is this
+  // file's realpath while argv[1] is whatever the spawner passed — a
+  // symlinked spawn path must still read as the entry, or the worker would
+  // exit with no verdict and the host would read a silent `unverified`.
+  let entryReal: string;
+  try {
+    entryReal = realpathSync(resolvePath(entry));
+  } catch {
+    return false;
+  }
+  return entryReal === realpathSync(fileURLToPath(import.meta.url));
 }
 
-void main();
+if (isProcessEntry()) {
+  void main();
+}