@ggui-ai/ui-gen 0.21.0 → 0.23.0

package/dist/workflows.d.ts

@@ -2,7 +2,7 @@ import { C as Classification } from './axes-CzLEMDeB.js';
 import { Workflow } from './harness/types-public.js';
 import '@ggui-ai/protocol';
 import './styling-profile-CxfvV48g.js';
-import './types-public-CzYqZclY.js';
+import './types-public-Ow-tNtFE.js';
 import './design-mode-DLufhrNp.js';
 import './types-BOvHNG7K.js';
 import './llm.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "UI generation harness for ggui — the LLM system prompt, multi-turn coding loop, and evaluation engine that turn a DataContract into a React component. Implements the UiGenerator contract from @ggui-ai/mcp-server-core; consumed by @ggui-ai/mcp-server.",
   "license": "Apache-2.0",
   "keywords": [
@@ -189,9 +189,9 @@
     "puppeteer-core": "^24.40.0 || ^25.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@ggui-ai/protocol": "0.21.0",
-    "@ggui-ai/mcp-server-core": "0.21.0",
-    "@ggui-ai/project-config": "0.21.0"
+    "@ggui-ai/mcp-server-core": "0.23.0",
+    "@ggui-ai/protocol": "0.23.0",
+    "@ggui-ai/project-config": "0.23.0"
   },
   "peerDependenciesMeta": {
     "@google/adk": {
@@ -233,11 +233,11 @@
     "openai": "^7.9.0",
     "typescript": "^5.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.21.0",
-    "@ggui-ai/gadgets": "0.21.0",
-    "@ggui-ai/sandbox": "0.21.0",
-    "@ggui-ai/ui-visual-tester": "0.21.0",
-    "@ggui-ai/wire": "0.21.0"
+    "@ggui-ai/design": "0.23.0",
+    "@ggui-ai/gadgets": "0.23.0",
+    "@ggui-ai/sandbox": "0.23.0",
+    "@ggui-ai/wire": "0.23.0",
+    "@ggui-ai/ui-visual-tester": "0.23.0"
   },
   "devDependencies": {
     "@google/adk": "^2.0.0",
@@ -252,9 +252,9 @@
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.6",
-    "@ggui-ai/mcp-server-core": "0.21.0",
-    "@ggui-ai/project-config": "0.21.0",
-    "@ggui-ai/protocol": "0.21.0"
+    "@ggui-ai/mcp-server-core": "0.23.0",
+    "@ggui-ai/project-config": "0.23.0",
+    "@ggui-ai/protocol": "0.23.0"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/adapters/claude/claude-code-login.ts

@@ -9,9 +9,12 @@
  *   1. {@link CLAUDE_CODE_LOGIN_CREDENTIAL} — the sentinel a `ProviderKeyRef`
  *      carries in place of a key, the same shape `bedrock-iam` already uses
  *      for "authenticate with ambient credentials, not a key I hold".
- *   2. {@link stripProviderKeyEnv} — no provider key may reach the spawned
- *      process: the binary prefers an env key over its login, so a stale
- *      `ANTHROPIC_API_KEY` would silently take the run off the login path.
+ *   2. {@link loginChildEnv} — the spawned process sees an ALLOWLIST of the
+ *      parent's env, never the parent's env minus a few names: no provider
+ *      key (the binary prefers an env key over its login, so a stale
+ *      `ANTHROPIC_API_KEY` would silently take the run off the login path),
+ *      no other secret the parent merely holds, and no switch that would
+ *      change what the binary does (ggui#1278).
  *   3. {@link claudeCodeLoginQueryOptions} — the SDK options that keep the
  *      run bounded: no built-in tool (`tools: []`), no `~/.claude` settings,
  *      hooks or MCP servers leaking in (`settingSources: []`). Not
@@ -40,14 +43,66 @@ export const PROVIDER_KEY_ENV_NAMES = [
   "ANTHROPIC_BASE_URL",
 ] as const;
 
-/** A copy of `env` without any provider key or endpoint override. */
-export function stripProviderKeyEnv(
+/**
+ * The only env names the login child inherits (ggui#1278), plus every
+ * `LC_*` locale name. The spawned binary sees a property of this code, not
+ * whatever the parent happened to load: a parent that sourced a whole
+ * `.env` holds every provider's key, and a denylist would pass all of them
+ * on, together with switches such as `CLAUDE_CODE_USE_BEDROCK` that would
+ * silently re-route the run.
+ *
+ * - Process basics: `PATH` (the binary runs helpers, e.g. the macOS
+ *   keychain tool), `HOME`/`USER`/`LOGNAME` (where and whose the login
+ *   store is), `SHELL`, temp dirs, `TERM`, `TZ`, locale.
+ * - Where the login lives: `CLAUDE_CONFIG_DIR`, the XDG base dirs.
+ * - `CLAUDE_CODE_OAUTH_TOKEN`: the login ITSELF when a headless host
+ *   supplies it by env (`claude setup-token`). It is the one credential
+ *   this path may use; every provider key stays out
+ *   ({@link PROVIDER_KEY_ENV_NAMES} is never on this list).
+ * - Network reach: proxy variables in both spellings, and the extra-CA
+ *   and certificate paths a corporate network needs.
+ */
+export const LOGIN_CHILD_ENV_NAMES = [
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "TERM",
+  "TZ",
+  "LANG",
+  "CLAUDE_CONFIG_DIR",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "XDG_CONFIG_HOME",
+  "XDG_DATA_HOME",
+  "XDG_CACHE_HOME",
+  "XDG_STATE_HOME",
+  "XDG_RUNTIME_DIR",
+  "HTTPS_PROXY",
+  "https_proxy",
+  "HTTP_PROXY",
+  "http_proxy",
+  "NO_PROXY",
+  "no_proxy",
+  "ALL_PROXY",
+  "all_proxy",
+  "NODE_EXTRA_CA_CERTS",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+] as const;
+
+const LOGIN_CHILD_ENV: ReadonlySet<string> = new Set(LOGIN_CHILD_ENV_NAMES);
+
+/** The env the login child is spawned with: the allowlisted names present in `env`, nothing else. */
+export function loginChildEnv(
   env: Readonly<Record<string, string | undefined>>
 ): Record<string, string> {
   const out: Record<string, string> = {};
-  const drop: ReadonlySet<string> = new Set(PROVIDER_KEY_ENV_NAMES);
   for (const [k, v] of Object.entries(env)) {
-    if (v !== undefined && !drop.has(k)) out[k] = v;
+    if (v !== undefined && (LOGIN_CHILD_ENV.has(k) || k.startsWith("LC_"))) out[k] = v;
   }
   return out;
 }

package/src/adapters/claude/sdk.ts

@@ -13,7 +13,7 @@ import type { ClaudeSdkConfig, GenerateParams } from '../base';
 import type { AdapterResult, ProviderName, AdapterMode } from '../types';
 import { createArtifacts, processMessage } from './message-parser';
 import { createToolMcpServer } from './tool-bridge';
-import { claudeCodeLoginQueryOptions, stripProviderKeyEnv } from './claude-code-login';
+import { claudeCodeLoginQueryOptions, loginChildEnv } from './claude-code-login';
 
 export class ClaudeSdkAdapter extends GeneratorAdapter {
   readonly provider: ProviderName = 'claude';
@@ -41,11 +41,12 @@ export class ClaudeSdkAdapter extends GeneratorAdapter {
     const { query } = await import('@anthropic-ai/claude-agent-sdk');
 
     // Build environment from config or process.env
-    // ggui#1185 — on the login path no provider key may reach the binary:
-    // it prefers an env key over its login, so a stale one would take the
-    // run off this path without a word.
+    // ggui#1185/#1278 — on the login path the binary sees an allowlisted
+    // env: no provider key (it prefers an env key over its login, so a stale
+    // one would take the run off this path without a word), and nothing
+    // else the parent merely holds.
     const login = cfg.claudeCodeLogin === true;
-    const env = login ? stripProviderKeyEnv(buildEnv(cfg.env)) : buildEnv(cfg.env);
+    const env = login ? loginChildEnv(buildEnv(cfg.env)) : buildEnv(cfg.env);
 
     const artifacts = createArtifacts();
     const onProgress = cfg.onProgress;

package/src/advanced/generator.ts

@@ -349,6 +349,18 @@ async function runFastStage(
     ...(input.contract ? { contract: input.contract } : {}),
   };
   const result = await runRenderCheck(checkInput);
+  if (result.incomplete !== undefined) {
+    // ggui#1299: the check ran out of wall-clock time, so there is no
+    // evidence either way — the same posture as an unverified check
+    // (non-failing, the unverified score). The slow stage still gates.
+    return {
+      stage: 'fast',
+      ok: true,
+      score: UNVERIFIED_FAST_SCORE,
+      diagnostics: [],
+      durationMs: Date.now() - start,
+    };
+  }
   const diagnostics: StageDiagnostic[] = buildFastStageComplaints(
     result.issues as readonly RenderCheckIssue[],
   );
@@ -405,11 +417,14 @@ async function runSlowStage(
  * job is just to land above or below it. Per-issue gradations matter
  * less than getting the pass/fail boundary right.
  */
+/** Fast-stage score when nothing failed but something went unverified. */
+const UNVERIFIED_FAST_SCORE = 0.85;
+
 function scoreFromRenderCheck(issues: readonly RenderCheckIssue[]): number {
   const failed = issues.filter((i) => i.outcome === 'failed').length;
   const unverified = issues.filter((i) => i.outcome === 'unverified').length;
   if (failed === 0 && unverified === 0) return 1.0;
-  if (failed === 0) return 0.85;
+  if (failed === 0) return UNVERIFIED_FAST_SCORE;
   if (failed === 1) return 0.4;
   if (failed === 2) return 0.3;
   return 0.2;

package/src/blueprint-validator.ts

@@ -23,7 +23,7 @@
 
 import type { DataContract, JsonObject } from '@ggui-ai/protocol';
 import { DEFAULT_RUNTIME_RENDER_CHECK } from './harness/check/runtime-render/index.js';
-import type { EvalIssue } from './evaluation/types-public.js';
+import type { EvalIssue, RuntimeProbeStatus } from './evaluation/types-public.js';
 
 /**
  * Caller-supplied blueprint payload. `contract` is `unknown` at the
@@ -74,6 +74,23 @@ export interface ValidateBlueprintInput {
  * the absence cleanly (selfCheck skips prop-coverage warnings; runtime
  * probe skip-warns).
  */
+/**
+ * The warning code for a probe that did not produce evidence. Exhaustive over
+ * the did-not-run statuses, so a new status is a compile error here instead of
+ * silently reading as whichever arm a ternary falls through to (ggui#1299:
+ * `timed-out` would otherwise have been labelled `probe-not-applicable`).
+ */
+function probeDidNotRunCode(status: Exclude<RuntimeProbeStatus, 'ran'>): string {
+  switch (status) {
+    case 'infra-skipped':
+      return 'runtime:probe-infra-failure';
+    case 'not-applicable':
+      return 'runtime:probe-not-applicable';
+    case 'timed-out':
+      return 'runtime:probe-timeout';
+  }
+}
+
 function asContract(x: RawContract): DataContract | undefined {
   if (typeof x !== 'object' || x === null) return undefined;
   return x as DataContract;
@@ -247,17 +264,15 @@ async function runtimeTier(input: RuntimeTierInput): Promise<RuntimeResult> {
       fixtureProps: asJsonObject(input.fixtureProps),
     });
     if (outcome.status !== 'ran') {
-      // Probe did not execute — infra failure or nothing to probe.
+      // Probe produced no evidence — infra failure, nothing to probe, or it
+      // ran out of wall-clock time before finishing.
       // Surface as a warning rather than a hard error so a flaky probe
       // doesn't permanently block legitimate blueprints — Claude can
       // retry, and host-level logs record the diagnostic for ops review.
       warnings.push({
         _kind: 'warning',
         tier: 'runtime',
-        code:
-          outcome.status === 'infra-skipped'
-            ? 'runtime:probe-infra-failure'
-            : 'runtime:probe-not-applicable',
+        code: probeDidNotRunCode(outcome.status),
         message: `Runtime probe did not run (${outcome.status}): ${outcome.reason ?? 'no reason recorded'}`,
       });
       return { errors, warnings };

package/src/boilerplate/hard-sections.ts

@@ -250,6 +250,7 @@ export const FRAME_SIZING = `## Sizing — the frame owns the height and the wid
 The host sizes the iframe; the component never sizes itself to the viewport. NEVER write \`100vh\` / \`100dvh\` / \`100svh\` (or an \`h-screen\` / \`min-h-screen\` class) as a height on any element:
 - An inline card takes its natural height. A content-sized frame is measured FROM the content, so a \`100vh\` root can never shrink and grows the frame on every re-measure.
 - Under fullscreen the frame already stretches your root to its full height. Centre inside it with flex (\`display: flex; flex-direction: column; justify-content: center\`), never with a viewport height.
+- Under fullscreen the frame also keeps a 16 px inset between your content and the panel's edge — leave it. A \`surface="hero"\` band that OPENS the card runs edge to edge on its own. Any other band that is MEANT to run edge to edge (a full-width strip of rows, a closing action bar) takes \`bleed\` (\`<Box surface="sunken" bleed>…</Box>\`); only such a band should, and \`bleed\` is ignored outside fullscreen.
 - To fill a parent that has a height use \`height: 100%\` or \`flex: 1\`; a viewport unit is only ever a \`max-height\` cap on a scroll region.
 
 The width works the same way, and the mistake is the mirror image: **your outermost element FILLS the frame; a width cap belongs INSIDE it, on the column that holds text.**

package/src/boilerplate/templates/layouts/chat-mobile.tsx.tmpl

@@ -1,3 +1,7 @@
-    <Card padding="sm" shadow="sm">
-      {/* implement your UI here */}
-    </Card>
+    <Box padding="md">
+      {/* implement your UI here — an inline card: the chat bubble around it
+          provides the chrome, so add no shadow or outer radius of your own.
+          Compact and natural height; stack vertically. This root fills the
+          bubble — wrap PROSE in <Container maxWidth="sm"> to cap the reading
+          measure (inert at bubble width, composed on a wider frame). */}
+    </Box>

package/src/boilerplate/templates/layouts/chat-universal.tsx.tmpl

@@ -1,3 +1,7 @@
-    <Card padding="sm" shadow="sm">
-      {/* implement your UI here */}
-    </Card>
+    <Box padding="md">
+      {/* implement your UI here — an inline card: the chat bubble around it
+          provides the chrome, so add no shadow or outer radius of your own.
+          Compact and natural height; stack vertically. This root fills the
+          bubble — wrap PROSE in <Container maxWidth="sm"> to cap the reading
+          measure (inert at bubble width, composed on a wider frame). */}
+    </Box>

package/src/coding-agent/tools.ts

@@ -416,7 +416,12 @@ export async function executeTool(
         changes: normalizedChanges,
       });
       if (!patchResult.ok) {
-        return { result: `FAILED: ${patchResult.error}`, error: true };
+        // ggui#1261: the engine refused the patch (overlap, line bounds, missing range) before
+        // anything applied. Say so in the log, and call it what it is — PATCH_INVALID, like every
+        // other structural refusal in this tool — so the turn is never counted as a self-check
+        // failure that did not run.
+        console.log(`[coding-agent] apply_changes: REJECTED | ${patchResult.error}`);
+        return { result: `PATCH_INVALID: ${patchResult.error}`, error: true };
       }
       const candidate = patchResult.sourceAfter ?? currentFile;
 

package/src/contract-context.ts

@@ -59,7 +59,7 @@ const SHELL_HINTS: Record<string, string> = {
 - Padding: use var(--ggui-spacing-2) for inner elements, var(--ggui-spacing-4) for sections. Tight.
 - Scrolling: parent scrolls (chat feed) — component should NOT have internal scroll
 - Layout: single column, compact. No sidebar. Stack everything vertically.
-- Width: width: 100% (fills parent bubble). Do NOT set max-width.`,
+- Width: the root is width: 100% (fills the bubble) — never cap the ROOT. A prose column inside it carries the reading cap (<Container maxWidth="sm">), which is inert at bubble width.`,
 
   fullscreen: `**Fullscreen Shell — Takes over entire viewport**
 - Container: the whole viewport, edge to edge — the frame stretches your root to its full height (you never set a viewport height yourself)

package/src/create-ui-generator.ts

@@ -56,6 +56,7 @@ import {
 } from '@ggui-ai/mcp-server-core';
 import { createGeneratorTools } from './adapters/index.js';
 import { dispatchGeneration } from './adapters/generation-dispatch.js';
+import { generatorBuild } from './generator-build.js';
 import { hasProfile } from './boilerplate/styling-profile.js';
 import { effortDials } from './effort.js';
 import type { ProviderName } from './adapters/types.js';
@@ -68,6 +69,7 @@ import {
 } from './contract-context.js';
 import type { RenderingContext } from './contract-context.js';
 import type { DesignMode } from './design-mode.js';
+import { DEFAULT_DESIGN_MODE } from './design-mode.js';
 import { resolveRoute, applyRouteToEnv } from './adapters/provider-router.js';
 import type { QualityConfig } from './evaluation/types-public.js';
 import type { EvaluationConfig } from './evaluation/types.js';
@@ -339,6 +341,7 @@ export function createUiGenerator(
         // Ignored by the constrained prompt (its shell/screen
         // descriptors stay byte-identical).
         const canvas = rendering ? canvasForRenderingContext(rendering) : undefined;
+        const shellType = harnessShellForRendering(rendering);
         const promptWithVariance = injectVariance(
           promptWithRendering,
           input.variance,
@@ -405,6 +408,8 @@ export function createUiGenerator(
           ...(onRetry !== undefined ? { onRetry } : {}),
           ...(designMode !== undefined ? { designMode } : {}),
           ...(canvas !== undefined ? { canvas } : {}),
+          // ggui#1279 — the shell the declared rendering composes for (chat only; see harnessShellForRendering).
+          ...(shellType !== undefined ? { shellType } : {}),
           ...(input.profile !== undefined ? { profile: input.profile } : {}),
           // Fixture props reach the in-loop probe + visual round only (never the prompt, never identity).
           ...(input.fixtureProps !== undefined ? { fixtureProps: input.fixtureProps } : {}),
@@ -421,6 +426,8 @@ export function createUiGenerator(
           latencyMs: Date.now() - startedAt,
           cacheHit: false,
           attempts: result.turnsUsed,
+          // ggui#1280 — the build that made this generation (template keys, never per-request).
+          build: generatorBuild(designMode ?? DEFAULT_DESIGN_MODE),
           // Prompt-cache counters are provider-specific (Claude reports
           // them; others omit). Pass through truthfully — absent on the
           // adapter result stays absent here, never defaulted to 0.
@@ -461,6 +468,8 @@ export function createUiGenerator(
             outputTokens: 0,
             latencyMs: Date.now() - startedAt,
             cacheHit: false,
+            // ggui#1280 — a failed generation still names the build that failed.
+            build: generatorBuild(designMode ?? DEFAULT_DESIGN_MODE),
           },
         };
       } finally {
@@ -523,6 +532,27 @@ function mapLlmProviderToDispatchProvider(provider: LlmProvider): ProviderName {
   }
 }
 
+/**
+ * ggui#1279 — the harness shell a declared rendering composes for. The canvas
+ * (`canvasForRenderingContext`) already follows the rendering; the WHAT leg's
+ * layout and the HOW leg's shell descriptor did not, so a declared chat card
+ * was scaffolded to "fill the frame" while the user prompt and the fit verdict
+ * treated it as an inline card. Only a declared CHAT shell changes anything.
+ * `fullscreen` IS the harness default, and `partial` has no layout of its own
+ * yet, so both pass no shell and those generations stay byte-identical — named
+ * here rather than guessed.
+ */
+function harnessShellForRendering(rendering: RenderingContext | undefined): 'chat' | undefined {
+  if (rendering === undefined) return undefined;
+  switch (rendering.shell) {
+    case 'chat':
+      return 'chat';
+    case 'fullscreen':
+    case 'partial':
+      return undefined;
+  }
+}
+
 function mapRendering(
   rendering: UiGenerateInput['rendering'],
 ): RenderingContext | undefined {

package/src/evaluation/axis-checks/checks/state-payload.ts

@@ -79,16 +79,41 @@ function runStateCoversPayload(input: AxisCheckInput): EvalIssue[] {
   return issues;
 }
 
+/**
+ * Whether a `useState` initializer reads `props.<name>`: directly, or through a local bound from
+ * it (`const initial = normalize(props.initialProfile)` then `useState(initial.name)`, or a
+ * destructure `const { name } = props.initialProfile ?? {}` then `useState(name)`). The property
+ * this check guards is "form state is seeded from the prop", not a spelling: ggui#1261's Exp 011
+ * cell re-seeded correctly through a normalized local, was refused, and spent a turn restoring
+ * the literal form.
+ */
+function seedsFromProp(src: string, name: string): boolean {
+  const propRef = `props\\??\\.${name}\\b`;
+  const initializerReads = (ref: string): boolean =>
+    new RegExp(`useState(?:<[^>]*>)?\\s*\\([\\s\\S]{0,400}?${ref}`).test(src);
+  if (initializerReads(propRef)) return true;
+  const locals = new Set<string>();
+  for (const m of src.matchAll(new RegExp(`(?:const|let|var)\\s+(\\w+)\\s*(?::[^=]{1,80})?=\\s*[^;]{0,300}?${propRef}`, "g"))) {
+    const id = m[1];
+    if (id !== undefined) locals.add(id);
+  }
+  for (const m of src.matchAll(new RegExp(`(?:const|let|var)\\s*\\{([^}]{1,400})\\}\\s*=\\s*[^;]{0,300}?${propRef}`, "g"))) {
+    for (const part of (m[1] ?? "").split(",")) {
+      const id = part.split(":").pop()?.split("=")[0]?.trim();
+      if (id !== undefined && /^\w+$/.test(id)) locals.add(id);
+    }
+  }
+  for (const id of locals) if (initializerReads(`\\b${id}\\b`)) return true;
+  return false;
+}
+
 function runInitialValuesSeeded(input: AxisCheckInput): EvalIssue[] {
   if (input.compiledCode === null) return [];
   const src = input.sourceCode;
   const initialProps = getInitialValuePropNames(input.contract);
   const issues: EvalIssue[] = [];
   for (const name of initialProps) {
-    const re = new RegExp(
-      `useState(?:<[^>]*>)?\\s*\\([\\s\\S]{0,400}?props\\.${name}\\b`,
-    );
-    if (re.test(src)) continue;
+    if (seedsFromProp(src, name)) continue;
     issues.push(
       mkIssue(
         "state.payload.initial_values_seeded",

package/src/evaluation/index.ts

@@ -22,6 +22,7 @@ export type {
   EvalOutcome,
   EvalCategory,
   EvalResult,
+  ContractFeedbackRecord,
   VisualEvalSummary,
   CanvasJudgeRecord,
   CanvasVisualSummary,

package/src/evaluation/llm-evaluator.ts

@@ -25,7 +25,7 @@ import type {
 } from './types-public.js';
 import { LLM_EVAL_STATIC_CRITERIA } from './types-public.js';
 import { createAgent } from '../harness/llm-router';
-import type { AgentConfig, LLMToolDef, LLMAgent } from '../harness/llm-router';
+import type { AgentConfig, LLMToolDef, LLMAgent, LLMToolCallResponse } from '../harness/llm-router';
 import type { JsonObject } from '@ggui-ai/protocol';
 import { getCriterionById } from './types-public.js';
 import { DEFAULT_DESIGN_MODE, type DesignMode } from '../design-mode.js';
@@ -596,10 +596,36 @@ interface CriterionResult {
   coverage: CriterionRunStatus;
   /** Populated for `skipped` — why the criterion produced no verdict. */
   skipReason?: string;
-  tokens: { in: number; out: number };
+  /** This call's token accounting. The cache counts are present only when the
+   *  provider reported them — absent means unreported, never zero (ggui#1281). */
+  tokens: { in: number; out: number; cacheRead?: number; cacheCreation?: number };
   durationMs: number;
 }
 
+/** A call's token accounting, carrying the prompt-cache counts only when the
+ *  provider reported them (the router's rule: absent is "unreported"). */
+function callTokens(response: LLMToolCallResponse): CriterionResult['tokens'] {
+  return {
+    in: response.inputTokens,
+    out: response.outputTokens,
+    ...(response.cacheReadTokens !== undefined ? { cacheRead: response.cacheReadTokens } : {}),
+    ...(response.cacheCreationTokens !== undefined ? { cacheCreation: response.cacheCreationTokens } : {}),
+  };
+}
+
+/**
+ * The evaluation's summed token accounting. `inputTokens` is the NON-cached
+ * input (the router's convention); the cache counts are the sums of what the
+ * calls reported, and stay absent when no call reported one — so a caller can
+ * tell "no cache reads" from "the provider does not say" (ggui#1281).
+ */
+export interface LLMEvalTokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheCreationTokens?: number;
+}
+
 /**
  * All valid categories for LLM evaluation — derived from the ONE static
  * list in types-public so the coverage stamp here and the harness's
@@ -642,7 +668,7 @@ async function evalCriterion(
         pass: true,
         coverage: 'skipped',
         skipReason: 'no tool call returned',
-        tokens: { in: response.inputTokens, out: response.outputTokens },
+        tokens: callTokens(response),
         durationMs,
       };
     }
@@ -700,7 +726,7 @@ async function evalCriterion(
       issues,
       pass,
       coverage: 'ran',
-      tokens: { in: response.inputTokens, out: response.outputTokens },
+      tokens: callTokens(response),
       durationMs,
     };
   } catch (e) {
@@ -833,7 +859,7 @@ export async function runLLMEvaluation(
   context: LLMEvalContext,
   config: LLMEvalConfig,
   preWarmedContext?: PreWarmedEvalContext | null,
-): Promise<EvalResult & { inputTokens: number; outputTokens: number }> {
+): Promise<EvalResult & LLMEvalTokenUsage> {
   const providerName = config.provider;
   const model = config.model || getDefaultEvalModel(providerName);
   const routerProvider =
@@ -887,7 +913,10 @@ export async function runLLMEvaluation(
   const passCategories: string[] = [];
   let totalIn = 0;
   let totalOut = 0;
-  let cachedTokensEstimate = 0;
+  // Measured, not estimated: summed from what the calls reported; absent
+  // while no call has reported one (ggui#1281).
+  let cacheRead: number | undefined;
+  let cacheCreation: number | undefined;
 
   for (const r of results) {
     allIssues.push(...r.issues);
@@ -896,12 +925,8 @@ export async function runLLMEvaluation(
     }
     totalIn += r.tokens.in;
     totalOut += r.tokens.out;
-  }
-
-  // Estimate cached tokens (mother prompt sent N times, cached N-1 times)
-  const firstResult = results[0];
-  if (firstResult && firstResult.tokens.in > 0) {
-    cachedTokensEstimate = firstResult.tokens.in * (totalCriteriaCount - 1);
+    if (r.tokens.cacheRead !== undefined) cacheRead = (cacheRead ?? 0) + r.tokens.cacheRead;
+    if (r.tokens.cacheCreation !== undefined) cacheCreation = (cacheCreation ?? 0) + r.tokens.cacheCreation;
   }
 
   const wallMs = Date.now() - evalStart;
@@ -928,7 +953,7 @@ export async function runLLMEvaluation(
   }
   console.log(
     `[eval] total: ${(wallMs / 1000).toFixed(1)}s wall (${totalCriteriaCount} parallel) | ` +
-    `in=${totalIn} out=${totalOut} cached~=${cachedTokensEstimate} | ` +
+    `in=${totalIn} out=${totalOut} cacheRead=${cacheRead ?? 'unreported'} cacheWrite=${cacheCreation ?? 'unreported'} | ` +
     `issues=${allIssues.length} pass=${passCategories.length}` +
     (skippedCount > 0 ? ` skipped=${skippedCount}` : ''),
   );
@@ -939,5 +964,7 @@ export async function runLLMEvaluation(
     criteriaCoverage,
     inputTokens: totalIn,
     outputTokens: totalOut,
+    ...(cacheRead !== undefined ? { cacheReadTokens: cacheRead } : {}),
+    ...(cacheCreation !== undefined ? { cacheCreationTokens: cacheCreation } : {}),
   };
 }

package/src/evaluation/types-public.ts

@@ -74,8 +74,28 @@ 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 = "ran" | "infra-skipped" | "not-applicable" | "timed-out";
+
+/**
+ * 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;
+}
 
 /**
  * Probe execution meta stamped onto an `EvalResult` at the exit-decision
@@ -85,8 +105,12 @@ export type RuntimeProbeStatus = "ran" | "infra-skipped" | "not-applicable";
  */
 export interface RuntimeProbeMeta {
   readonly status: RuntimeProbeStatus;
-  /** Populated for `infra-skipped` / `not-applicable` — why the probe didn't run. */
+  /** Populated for `infra-skipped` / `not-applicable` / `timed-out` — why the probe didn't finish. */
   readonly reason?: string;
+  /** `timed-out` only: how long the probe ran before it was stopped. */
+  readonly elapsedMs?: number;
+  /** Host load around the probe, when it ran isolated (absent for an in-process probe). */
+  readonly hostLoad?: ProbeHostLoad;
 }
 
 /**
@@ -175,6 +199,14 @@ export function notApplicableCoverage(reason: string): CriterionCoverage[] {
   }));
 }
 
+/** One contract-feedback round (ggui#1261): what bought it, and the source it was fed back on. */
+export interface ContractFeedbackRecord {
+  /** The exit-probe issue subcategories that bought the round, e.g. `runtime:prop-sensitivity:currentUser`. */
+  readonly firedOn: readonly string[];
+  /** The component source as it stood when the model was told — the round's BEFORE. */
+  readonly sourceBefore: string;
+}
+
 export interface EvalResult {
   issues: EvalIssue[];
   pass: string[];
@@ -194,6 +226,14 @@ export interface EvalResult {
    * probe runner; absent on eval paths that never invoke the probe.
    */
   runtimeProbe?: RuntimeProbeMeta;
+  /**
+   * 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
+   * model was told. `runtimeProbe` and the `runtime:*` issues on this result
+   * are the probe's verdict AFTER that round; `sourceBefore` beside the final
+   * source is the round's before/after. Absent when no such round fired.
+   */
+  contractFeedback?: ContractFeedbackRecord;
   /**
    * Per-canvas visual verdicts. Stamped by the harness ONLY when the
    * visual leg ran with `visualEvaluation.canvases` set (arm-neutral —