@ggui-ai/ui-gen 0.21.0 → 0.22.0

package/src/generator-build.ts

@@ -0,0 +1,158 @@
+/**
+ * The generator's BUILD identity (ggui#1280): values that change when the
+ * triad's templates change and never with the request, so generations group
+ * by the build that produced them.
+ *
+ * - `promptTemplateSha256` / `boilerplateTemplateSha256` are sha256 over the
+ *   production system prompt and the boilerplate rendered on the design-mode
+ *   pin's FIXED fixtures (`PIN_FIXTURES`), in the live env, so an env-gated
+ *   block (the pitfalls) counts as it really is. The design-mode pin renders
+ *   the same functions and asserts these values equal its recorded constants
+ *   under the default env: the runtime key and the pin cannot drift.
+ * - These are BUILD keys, not instance fingerprints. A hash of the prompt one
+ *   generation actually sent embeds the request and differs every time, so it
+ *   could never group two generations by build.
+ * - `version` is the package's own version, read once from the nearest
+ *   `package.json` named `@ggui-ai/ui-gen` above this module. It is absent
+ *   when none is found (e.g. a consumer bundled this package into one file),
+ *   never guessed.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { GeneratorBuild } from '@ggui-ai/mcp-server-core';
+import { generateBoilerplate } from './boilerplate/generate.js';
+import type { DesignMode } from './design-mode.js';
+import { buildSystemPrompt } from './harness/runtime.js';
+import { PIN_FIXTURES } from './pin-fixtures.js';
+
+/** The separator the rendered fixtures are joined with before hashing. */
+export const TEMPLATE_FIXTURE_BOUNDARY = '\n<<<pin-fixture-boundary>>>\n';
+
+/** sha256 hex of a rendered template. */
+export function templateSha256(text: string): string {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+/**
+ * The production system prompt for every pin fixture, joined. The constrained
+ * arm uses the positional default-path signature (no `designMode` argument),
+ * which is what the pin has always recorded.
+ */
+export function renderPromptTemplates(designMode: DesignMode): string {
+  return PIN_FIXTURES.map((f) => {
+    switch (designMode) {
+      case 'constrained':
+        return buildSystemPrompt(f.userRequest, f.shellType, f.screen);
+      case 'free':
+        return buildSystemPrompt(f.userRequest, f.shellType, f.screen, undefined, undefined, undefined, 'free');
+    }
+  }).join(TEMPLATE_FIXTURE_BOUNDARY);
+}
+
+/** The boilerplate for every pin fixture, joined — same signature split as the prompt. */
+export function renderBoilerplateTemplates(designMode: DesignMode): string {
+  return PIN_FIXTURES.map((f) => {
+    switch (designMode) {
+      case 'constrained':
+        return generateBoilerplate(f.userRequest, f.contract, f.shellType, f.screen);
+      case 'free':
+        return generateBoilerplate(f.userRequest, f.contract, f.shellType, f.screen, undefined, undefined, 'free');
+    }
+  }).join(TEMPLATE_FIXTURE_BOUNDARY);
+}
+
+/**
+ * ui-gen's precise {@link GeneratorBuild}: the core port's generic shape with
+ * ui-gen's own keys — `mode` is the design mode, and `digests` names the two
+ * template digests (the keys a blueprint's build stamp copies).
+ */
+export interface UiGenBuild extends GeneratorBuild {
+  /** This package's version; absent when its `package.json` cannot be found at runtime. */
+  readonly version?: string;
+  readonly mode: DesignMode;
+  readonly digests: {
+    readonly promptTemplateSha256: string;
+    readonly boilerplateTemplateSha256: string;
+  };
+}
+
+const PACKAGE_NAME = '@ggui-ai/ui-gen';
+/** How far up from this module the package root can sit (`src/`, `dist/`, a nested entry). */
+const MAX_PACKAGE_DEPTH = 6;
+
+/**
+ * A `package.json` the walk meets may not be ours, and in a consumer's bundle
+ * it may not even parse. A candidate that does not parse is skipped (as if
+ * absent), so reading this package's version can never fail a generation —
+ * the version is then absent, never guessed. Only a JSON `SyntaxError` is
+ * handled here; any other error is a real fault and propagates.
+ */
+function parsePackageJson(text: string): unknown {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return parsed;
+  } catch (err) {
+    if (err instanceof SyntaxError) return undefined;
+    throw err;
+  }
+}
+
+/**
+ * Walk up from `startDir` (this module's own directory by default) to the
+ * nearest `package.json` named `@ggui-ai/ui-gen` and return its version;
+ * `undefined` when none is found within reach.
+ */
+export function findPackageVersion(startDir: string = dirname(fileURLToPath(import.meta.url))): string | undefined {
+  let dir = startDir;
+  for (let i = 0; i < MAX_PACKAGE_DEPTH; i++) {
+    const candidate = join(dir, 'package.json');
+    const pkg = existsSync(candidate) ? parsePackageJson(readFileSync(candidate, 'utf8')) : undefined;
+    if (pkg !== undefined) {
+      if (
+        typeof pkg === 'object' &&
+        pkg !== null &&
+        'name' in pkg &&
+        pkg.name === PACKAGE_NAME &&
+        'version' in pkg &&
+        typeof pkg.version === 'string'
+      ) {
+        return pkg.version;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
+let versionRead = false;
+let packageVersion: string | undefined;
+const identities = new Map<string, UiGenBuild>();
+
+/**
+ * The build identity for `designMode`, computed once per process per design
+ * mode and pitfalls env gate (the only env the templates read), so a changed
+ * gate is never answered from a stale memo.
+ */
+export function generatorBuild(designMode: DesignMode): UiGenBuild {
+  const key = `${designMode}|${process.env.GGUI_PITFALLS ?? ''}|${process.env.GGUI_NEW_PITFALLS ?? ''}`;
+  const known = identities.get(key);
+  if (known !== undefined) return known;
+  if (!versionRead) {
+    packageVersion = findPackageVersion();
+    versionRead = true;
+  }
+  const identity: UiGenBuild = {
+    ...(packageVersion !== undefined ? { version: packageVersion } : {}),
+    mode: designMode,
+    digests: {
+      promptTemplateSha256: templateSha256(renderPromptTemplates(designMode)),
+      boilerplateTemplateSha256: templateSha256(renderBoilerplateTemplates(designMode)),
+    },
+  };
+  identities.set(key, identity);
+  return identity;
+}

package/src/harness/claude-code-login-query.ts

@@ -43,7 +43,7 @@ import { z } from "zod";
 import type { LLMToolDef } from "../llm.js";
 import {
   claudeCodeLoginQueryOptions,
-  stripProviderKeyEnv,
+  loginChildEnv,
 } from "../adapters/claude/claude-code-login.js";
 import { MCP_SERVER_NAME } from "../adapters/claude/tool-bridge.js";
 import { toolArgsToJsonObject } from "../adapters/tool-bridge.js";
@@ -186,8 +186,9 @@ export async function* imageUserMessage(
  * SDK's typed `thinking` option (the probe spelled it `thinkingConfig`,
  * untyped, and saw a thinking block anyway — whether the typed spelling
  * is honoured is Exp 009's to measure; it reports thinking tokens as
- * their own column either way); every provider key name is stripped from the
- * env the binary inherits; Layer 1's pins keep it tool-less (the CLI's
+ * their own column either way); the binary inherits an allowlisted env
+ * (`loginChildEnv`: no provider key, nothing else the parent merely holds,
+ * ggui#1278); Layer 1's pins keep it tool-less (the CLI's
  * own tools), config-less (`~/.claude` never loads) and non-bare (the
  * login store IS read). Tools, when offered, come as ggui's in-process
  * MCP server with NO allow-list and the denying intercept.
@@ -206,7 +207,7 @@ export function buildLoginQueryOptions(params: {
     systemPrompt: params.systemPrompt,
     maxTurns: 1,
     thinking: { type: "disabled" },
-    env: stripProviderKeyEnv(params.env ?? process.env),
+    env: loginChildEnv(params.env ?? process.env),
     ...claudeCodeLoginQueryOptions(),
     ...(params.tools !== undefined
       ? {

package/src/harness/coding/assemble-result.ts

@@ -122,7 +122,14 @@ export async function assembleGenerationResult(
     generationTimeMs: totalMs,
     turnsUsed: telemetry.turnsUsed,
     passesUsed: 1,
-    evalResult: telemetry.evalResult,
+    // ggui#1261 — the contract-feedback round's record rides the result the
+    // generation ends with (whose probe stamp is the post-round verdict).
+    evalResult:
+      telemetry.evalResult !== undefined && telemetry.contractFeedback !== undefined
+        ? { ...telemetry.evalResult, contractFeedback: telemetry.contractFeedback }
+        : telemetry.evalResult,
+    // ggui#404 — present only when the same-exchange guard ended the run.
+    ...(telemetry.sameExchangeBreak !== undefined ? { sameExchangeBreak: telemetry.sameExchangeBreak } : {}),
     needsBackgroundImprovement,
     selfCheckPassed: telemetry.selfCheckPassed,
     timing,

package/src/harness/coding/generate-task-runner.ts

@@ -12,7 +12,7 @@
 
 import type { Classification } from "../../classifier/index.js";
 import type { JsonValue } from "@ggui-ai/protocol";
-import type { EvalResult } from "../../evaluation/types-public.js";
+import type { ContractFeedbackRecord, EvalResult } from "../../evaluation/types-public.js";
 import type { Harness, Task, TaskContext } from "../types-public.js";
 import type { SingleComponentParams } from "../runtime.js";
 import type { TaskRunner } from "../index.js";
@@ -20,8 +20,11 @@ import type { CodingSession } from "./init-session.js";
 import {
   runCodingTurn,
   type A1Phase,
+  type CodingTurnResult,
 } from "./run-coding-turn.js";
 import { runEvalRound } from "./run-eval-round.js";
+import type { TokenUsage } from "./run-eval-round.js";
+import type { SameExchangeBreak } from "../result-types.js";
 
 type PreWarmedEvalContext =
   import("../../evaluation/llm-evaluator.js").PreWarmedEvalContext;
@@ -64,15 +67,27 @@ export interface GenerateTelemetry {
   /** Total output tokens billed across coding + eval. */
   totalOut: number;
   /**
-   * Prompt-cache tokens accumulated across coding turns, when the
-   * provider reports them. Optional: stays `undefined` for providers
-   * that don't expose cache accounting (never defaulted to 0 here, so
-   * the boundary can distinguish "no cache reads" from "unreported").
+   * Prompt-cache tokens accumulated across coding turns AND eval rounds
+   * (ggui#1281), when the provider reports them. Optional: stays
+   * `undefined` for providers that don't expose cache accounting (never
+   * defaulted to 0 here, so the boundary can distinguish "no cache reads"
+   * from "unreported").
    */
   cacheReadTokens?: number;
   cacheCreationTokens?: number;
   /** Latest evalResult — undefined when eval was disabled or never ran. */
   evalResult: EvalResult | undefined;
+  /**
+   * ggui#1261 — the contract-feedback round, once one fired: kept across the
+   * rounds after it (each rebuilds `evalResult`) so the assembled result can
+   * carry the round's before beside the source the generation ends with.
+   */
+  contractFeedback: ContractFeedbackRecord | undefined;
+  /**
+   * The same-exchange guard's record (ggui#404), set by the turn it ended —
+   * undefined unless that guard is what stopped the loop.
+   */
+  sameExchangeBreak: SameExchangeBreak | undefined;
   /** Latest compiled code — empty string until the first self-check pass. */
   compiledCode: string;
   /**
@@ -111,6 +126,8 @@ export function createTelemetry(): GenerateTelemetry {
     totalIn: 0,
     totalOut: 0,
     evalResult: undefined,
+    contractFeedback: undefined,
+    sameExchangeBreak: undefined,
     compiledCode: "",
     pairedSource: "",
     selfCheckPassed: false,
@@ -120,6 +137,56 @@ export function createTelemetry(): GenerateTelemetry {
   };
 }
 
+/**
+ * Fold one call's (or one eval round's) tokens into the run's totals — the ONE
+ * rule for coding turns and eval rounds alike (ggui#1281: the eval path used to
+ * add input/output only, so `tokens.total` dropped every eval call's cached
+ * prefix). A cache counter is seeded on its first report and stays `undefined`
+ * while nothing has reported one: unreported, never zero.
+ */
+export function absorbTokens(telemetry: GenerateTelemetry, usage: TokenUsage): void {
+  telemetry.totalIn += usage.input;
+  telemetry.totalOut += usage.output;
+  if (usage.cacheRead !== undefined) {
+    telemetry.cacheReadTokens = (telemetry.cacheReadTokens ?? 0) + usage.cacheRead;
+  }
+  if (usage.cacheCreation !== undefined) {
+    telemetry.cacheCreationTokens = (telemetry.cacheCreationTokens ?? 0) + usage.cacheCreation;
+  }
+}
+
+/**
+ * Fold one coding turn's measurements into the run's telemetry — tokens (via
+ * {@link absorbTokens}), timings, the phase/outcome counters, and the
+ * same-exchange guard's record when that guard ended the turn (ggui#404). One
+ * function so every per-turn fact the result is assembled from lands in one
+ * place.
+ */
+export function absorbTurn(telemetry: GenerateTelemetry, turn: CodingTurnResult): void {
+  absorbTokens(telemetry, {
+    input: turn.tokens.input,
+    output: turn.tokens.output,
+    ...(turn.cacheReadTokens !== undefined ? { cacheRead: turn.cacheReadTokens } : {}),
+    ...(turn.cacheCreationTokens !== undefined ? { cacheCreation: turn.cacheCreationTokens } : {}),
+  });
+  telemetry.cumulativeLlmMs += turn.llmMs;
+  telemetry.cumulativeToolMs += turn.toolMs;
+  if (turn.phase) {
+    if (turn.phase === "scaffold") telemetry.counters.phases.scaffold++;
+    else if (turn.phase === "fill") telemetry.counters.phases.fill++;
+    else if (turn.phase === "impl") telemetry.counters.phases.impl++;
+    else if (turn.phase === "eval-fix") telemetry.counters.phases.evalFix++;
+    else telemetry.counters.phases.patch++;
+  }
+  if (turn.outcome) {
+    if (turn.outcome === "PASS") telemetry.counters.outcomes.pass++;
+    else if (turn.outcome === "PATCH_INVALID") telemetry.counters.outcomes.patchInvalid++;
+    else if (turn.outcome === "DIFF_FAIL") telemetry.counters.outcomes.diffFail++;
+    else telemetry.counters.outcomes.selfCheckFail++;
+  }
+  if (turn.sameExchangeBreak !== undefined) telemetry.sameExchangeBreak = turn.sameExchangeBreak;
+}
+
 export interface CreateGenerateRunnerInput {
   readonly session: CodingSession;
   readonly params: SingleComponentParams;
@@ -203,38 +270,10 @@ export function createGenerateTaskRunner(input: CreateGenerateRunnerInput): Task
         },
       );
 
-      telemetry.totalIn += turn.tokens.input;
-      telemetry.totalOut += turn.tokens.output;
-      // Accumulate prompt-cache counters only when the provider reported
-      // them this turn. Seeding from `undefined` on first report keeps the
-      // "unreported" providers' totals absent rather than 0.
-      if (turn.cacheReadTokens !== undefined) {
-        telemetry.cacheReadTokens =
-          (telemetry.cacheReadTokens ?? 0) + turn.cacheReadTokens;
-      }
-      if (turn.cacheCreationTokens !== undefined) {
-        telemetry.cacheCreationTokens =
-          (telemetry.cacheCreationTokens ?? 0) + turn.cacheCreationTokens;
-      }
-      telemetry.cumulativeLlmMs += turn.llmMs;
-      telemetry.cumulativeToolMs += turn.toolMs;
+      absorbTurn(telemetry, turn);
       iconNamesCache = turn.iconNamesCache;
       preWarmedContext = turn.preWarmedContext;
 
-      if (turn.phase) {
-        if (turn.phase === "scaffold") telemetry.counters.phases.scaffold++;
-        else if (turn.phase === "fill") telemetry.counters.phases.fill++;
-        else if (turn.phase === "impl") telemetry.counters.phases.impl++;
-        else if (turn.phase === "eval-fix") telemetry.counters.phases.evalFix++;
-        else telemetry.counters.phases.patch++;
-      }
-      if (turn.outcome) {
-        if (turn.outcome === "PASS") telemetry.counters.outcomes.pass++;
-        else if (turn.outcome === "PATCH_INVALID") telemetry.counters.outcomes.patchInvalid++;
-        else if (turn.outcome === "DIFF_FAIL") telemetry.counters.outcomes.diffFail++;
-        else telemetry.counters.outcomes.selfCheckFail++;
-      }
-
       if (turn.control === "break") break;
       if (turn.control === "continue") {
         lastResultText = turn.lastResultText;
@@ -334,9 +373,9 @@ export function createGenerateTaskRunner(input: CreateGenerateRunnerInput): Task
         prevFailFingerprints = round.prevFailFingerprints;
         preWarmedContext = round.preWarmedContext;
         if (round.evalResult) telemetry.evalResult = round.evalResult;
+        if (round.contractFeedback) telemetry.contractFeedback = round.contractFeedback;
         evalDone = round.evalDone;
-        telemetry.totalIn += round.evalTokens.input;
-        telemetry.totalOut += round.evalTokens.output;
+        absorbTokens(telemetry, round.evalTokens);
 
         if (round.control === "break") break;
         // round.control === "feedback" — set next coding turn input.

package/src/harness/coding/run-coding-turn.ts

@@ -21,6 +21,7 @@ import { executeTool } from "../../coding-agent/tools.js";
 import type { CostTracker } from "../../evaluation/cost-tracker.js";
 import type { LLMAgent } from "../llm-router.js";
 import type { Harness } from "../types-public.js";
+import type { SameExchangeBreak } from "../result-types.js";
 import {
   APPLY_CHANGES_HASHLINE_TOOL,
   APPLY_CHANGES_HASHLINE_TOOL_FLAT,
@@ -244,6 +245,12 @@ export interface CodingTurnResult {
   readonly isEvalFeedback: boolean;
   readonly iconNamesCache: string | null;
   readonly preWarmedContext: PreWarmedEvalContext | null | undefined;
+  /**
+   * Set only on the `break` the same-exchange guard returns (ggui#404) — the
+   * one way a caller can tell this guard ended the run, since `break` is a
+   * control value many exits share. No key on any other turn.
+   */
+  readonly sameExchangeBreak?: SameExchangeBreak;
 }
 
 /**
@@ -637,6 +644,7 @@ ${closingInstruction}`;
         isEvalFeedback: false,
         iconNamesCache,
         preWarmedContext,
+        sameExchangeBreak: { tool: call.name, repeats: iconRepeats },
       };
     }
     return {
@@ -964,6 +972,7 @@ ${closingInstruction}`;
       isEvalFeedback: false,
       iconNamesCache,
       preWarmedContext,
+      sameExchangeBreak: { tool: call.name, repeats: sameExchangeRepeats },
     };
   }
 

package/src/harness/coding/run-eval-round.ts

@@ -22,7 +22,7 @@ import { listContractGadgets } from "@ggui-ai/protocol";
 import type { Classification } from "../../classifier/index.js";
 import type { AgentWorkspace } from "../../coding-agent/workspace.js";
 import type { CostTracker } from "../../evaluation/cost-tracker.js";
-import type { EvalIssue, EvalResult, RuntimeProbeMeta, VisualEvalSummary, VisualCoverage } from "../../evaluation/types-public.js";
+import type { ContractFeedbackRecord, EvalIssue, EvalResult, RuntimeProbeMeta, VisualEvalSummary, VisualCoverage } from "../../evaluation/types-public.js";
 import { notApplicableCoverage } from "../../evaluation/types-public.js";
 import { mapProviderForEvaluator, visionJudgeProvider } from "../enforced-coding.js";
 import { runCheck } from "../index.js";
@@ -40,6 +40,7 @@ import type {
 type PreWarmedEvalContext =
   import("../../evaluation/llm-evaluator.js").PreWarmedEvalContext;
 type LlmEvalMod = typeof import("../../evaluation/llm-evaluator.js");
+type LLMEvalTokenUsage = import("../../evaluation/llm-evaluator.js").LLMEvalTokenUsage;
 type VisualEvalMod = typeof import("../../evaluation/visual-evaluator.js");
 
 /**
@@ -100,6 +101,20 @@ export interface EvalRoundInput {
  */
 export type EvalRoundControl = "break" | "feedback";
 
+/**
+ * One call's (or one round's) token accounting. `input` is the NON-cached
+ * input; the cache counts are present only when the provider reported them —
+ * absent means unreported, never zero. The runner folds every coding turn and
+ * every eval round through the same rule (`absorbTokens`), so the published
+ * `tokens.total` holds one convention across both (ggui#1281, #1186).
+ */
+export interface TokenUsage {
+  readonly input: number;
+  readonly output: number;
+  readonly cacheRead?: number;
+  readonly cacheCreation?: number;
+}
+
 export interface EvalRoundResult {
   readonly control: EvalRoundControl;
   /** True only on the low-risk bypass + clean-pass paths. */
@@ -115,7 +130,7 @@ export interface EvalRoundResult {
   readonly prevFailFingerprints: Set<string>;
   readonly preWarmedContext: PreWarmedEvalContext | null | undefined;
   /** Tokens added during this round — caller adds to its own totals. */
-  readonly evalTokens: { input: number; output: number };
+  readonly evalTokens: TokenUsage;
   /** Wall-clock of the parallel LLM + visual eval block (zero on the
    *  low-risk bypass path, which exits before `Promise.all`). Caller
    *  accumulates into its `cumulativeEvalLlmMs`. */
@@ -124,6 +139,13 @@ export interface EvalRoundResult {
   readonly lastResultText: string;
   readonly isEvalFeedback: boolean;
   readonly lastDiffFailed: boolean;
+  /**
+   * ggui#1261 — set ONLY on the round that granted a contract-feedback round:
+   * what bought it and the source it was fed back on. The caller keeps it past
+   * this round (the next round rebuilds `evalResult`) and stamps it on the
+   * result the generation ends with.
+   */
+  readonly contractFeedback?: ContractFeedbackRecord;
 }
 
 /** Cap feedback to N issues per eval-fix turn so the LLM stays surgical. */
@@ -368,6 +390,42 @@ function formatRuntimeProbeFeedback(issue: EvalIssue): string {
   );
 }
 
+/**
+ * Exit-probe checks whose FAIL buys ONE feedback round although it is not a
+ * crash: a contract defect the probe diagnoses deterministically, with a fix
+ * text the model can act on in a turn. Without the round the loop recorded the
+ * finding and shipped it — its own evaluator named the defect and the model
+ * never heard. Named, and grown only with evidence: `prop-sensitivity` (a
+ * declared prop ignored, a literal baked in its place — "You" for
+ * `currentUser`) is the class measured failing across models (ggui#1261).
+ */
+const FEEDBACK_PROBE_CHECKS: readonly string[] = ["prop-sensitivity"];
+
+/** Rounds past the cap the contract-feedback round may use: one, as the fit round (ggui#1195). */
+const CONTRACT_FEEDBACK_BONUS = 1;
+
+/** `runtime:<check>` or `runtime:<check>:<subject>` for a named feedback check, FAIL only. */
+function isFeedbackProbeFail(issue: EvalIssue): boolean {
+  const sub = issue.subcategory;
+  if (issue.result !== "fail" || typeof sub !== "string") return false;
+  return FEEDBACK_PROBE_CHECKS.some((check) => sub === `runtime:${check}` || sub.startsWith(`runtime:${check}:`));
+}
+
+/**
+ * The exit probe's feedback-worthy FAILs this generation has not been told
+ * about yet. A finding whose fingerprint already rode a feedback round and
+ * recurred is left out — one attempt per finding, then it ships as recorded.
+ */
+/** The round's record: the findings that bought it, and the source they were found on. */
+function contractFeedbackRecord(fails: readonly EvalIssue[], sourceBefore: string): ContractFeedbackRecord {
+  return { firedOn: fails.flatMap((i) => (i.subcategory !== undefined ? [i.subcategory] : [])), sourceBefore };
+}
+
+function contractFeedbackFails(exitProbe: ProbeAtExitResult, alreadyFedBack: ReadonlySet<string>): EvalIssue[] {
+  if (!exitProbe.fired) return [];
+  return exitProbe.probeIssues.filter((i) => isFeedbackProbeFail(i) && !alreadyFedBack.has(fingerprintFail(i)));
+}
+
 /**
  * Run one eval round. Mutates `ctx.costTracker` (records LLM eval tokens)
  * and `ctx.workspace` is read-only from this function's POV. Returns
@@ -404,7 +462,7 @@ export async function runEvalRound(
   const currentSource = workspace.read() ?? "";
 
   let evalResult: EvalResult | undefined;
-  let evalTokens = { input: 0, output: 0 };
+  let evalTokens: TokenUsage = { input: 0, output: 0 };
   let evalLlmMs = 0;
 
   try {
@@ -528,7 +586,7 @@ export async function runEvalRound(
     }
 
     // ── Tier 1+2: LLM evaluation + Visual eval in parallel ──
-    let llmResult: (EvalResult & { inputTokens: number; outputTokens: number }) | null = null;
+    let llmResult: (EvalResult & LLMEvalTokenUsage) | null = null;
     let visualIssues: EvalIssue[] | null = null;
 
     // The visual leg's page and frame — ONE value each, read by the judge and
@@ -629,6 +687,8 @@ export async function runEvalRound(
       evalTokens = {
         input: llmResult.inputTokens,
         output: llmResult.outputTokens,
+        ...(llmResult.cacheReadTokens !== undefined ? { cacheRead: llmResult.cacheReadTokens } : {}),
+        ...(llmResult.cacheCreationTokens !== undefined ? { cacheCreation: llmResult.cacheCreationTokens } : {}),
       };
     }
 
@@ -748,6 +808,40 @@ export async function runEvalRound(
           lastDiffFailed: false,
         };
       }
+      // ggui#1261 — a contract defect the probe diagnosed (a named check,
+      // FAIL) that this generation has not been told about: ONE feedback
+      // round with the probe's own diagnosis and fix. The next round re-runs
+      // the probe at its exit, so the result this generation ends with
+      // carries the post-fix stamp, never this one.
+      const contractFails = contractFeedbackFails(exitProbe, prevFailFingerprints);
+      if (contractFails.length > 0 && evalRoundsUsed < maxEvalRounds + CONTRACT_FEEDBACK_BONUS) {
+        const lines = contractFails.slice(0, MAX_FEEDBACK_ISSUES).map(formatRuntimeProbeFeedback);
+        evalResult = {
+          ...evalResult,
+          issues: [...allIssues, ...exitProbe.probeIssues],
+          pass: allPass,
+          runtimeProbe: exitProbe.meta,
+        };
+        console.log(
+          `[simple] eval round ${evalRoundsUsed}: tier-1/2 clean BUT contract probe fail — granting +1 turn ` +
+            `(ggui#1261; ${contractFails.map((i) => i.subcategory).join(", ")})`,
+        );
+        return {
+          control: "feedback",
+          evalDone: false,
+          evalResult,
+          evalRoundsUsed,
+          prevModeSubcats: updatedPrevModeSubcats,
+          prevFailFingerprints: new Set([...currFailFingerprints, ...contractFails.map(fingerprintFail)]),
+          preWarmedContext,
+          evalTokens,
+          evalLlmMs,
+          lastResultText: lines.join("\n\n"),
+          isEvalFeedback: true,
+          lastDiffFailed: false,
+          contractFeedback: contractFeedbackRecord(contractFails, currentSource),
+        };
+      }
       // Probe didn't trip a recoverable fail — fold its issues (if any)
       // into the merged result and ALWAYS stamp its execution meta, so a
       // did-not-run probe is visible downstream even on this clean exit.
@@ -811,7 +905,8 @@ export async function runEvalRound(
       // the runtimeProbe stamp lands (Exp 48 found this exit surfacing
       // as "SKIP — no runtimeProbe stamp" in the bench: honest, but a
       // probe here is cheap and the shipped code deserves the signal).
-      // No feedback is granted — stuck means the LLM stopped converging.
+      // The RECURRING fails get no more feedback — stuck means the model
+      // saw them and stopped converging on them.
       const stuckExitProbe = await runProbeAtExit({
         harness,
         sourceCode: currentSource,
@@ -824,6 +919,36 @@ export async function runEvalRound(
         issues: [...evalResult.issues, ...stuckExitProbe.probeIssues],
         runtimeProbe: stuckExitProbe.meta,
       };
+      // ggui#1261 — a contract defect the exit probe diagnosed here was never
+      // DELIVERED: the stuck set is non-runtime by construction (runtime-only
+      // sets are exempt above), and the stuck premise is "the model saw these
+      // and did not resolve them". So it gets the same one round as at the
+      // clean-PASS and cap exits — the probe's diagnosis only, never the
+      // recurring fail; one attempt per finding; bounded at the cap + 1 (Exp
+      // 011, candidate r5: the one FAIL that shipped without a round).
+      const stuckContractFails = contractFeedbackFails(stuckExitProbe, prevFailFingerprints);
+      if (stuckContractFails.length > 0 && evalRoundsUsed < maxEvalRounds + CONTRACT_FEEDBACK_BONUS) {
+        const lines = stuckContractFails.slice(0, MAX_FEEDBACK_ISSUES).map(formatRuntimeProbeFeedback);
+        console.log(
+          `[simple] eval round ${evalRoundsUsed}: stuck BUT contract probe fail never delivered — granting +1 turn ` +
+            `(ggui#1261; ${stuckContractFails.map((i) => i.subcategory).join(", ")})`,
+        );
+        return {
+          control: "feedback",
+          evalDone: false,
+          evalResult,
+          evalRoundsUsed,
+          prevModeSubcats: updatedPrevModeSubcats,
+          prevFailFingerprints: new Set([...currFailFingerprints, ...stuckContractFails.map(fingerprintFail)]),
+          preWarmedContext,
+          evalTokens,
+          evalLlmMs,
+          lastResultText: lines.join("\n\n"),
+          isEvalFeedback: true,
+          lastDiffFailed: false,
+          contractFeedback: contractFeedbackRecord(stuckContractFails, currentSource),
+        };
+      }
       return {
         control: "break",
         evalDone: false,
@@ -909,6 +1034,36 @@ export async function runEvalRound(
           lastDiffFailed: false,
         };
       }
+      // ggui#1261 — a named contract FAIL from the exit probe active at the
+      // cap: the same one round as at the clean exit, bounded at the cap + 1.
+      const capContractFails = allowRuntimeExtension ? [] : contractFeedbackFails(exitProbe, prevFailFingerprints);
+      if (capContractFails.length > 0 && evalRoundsUsed < maxEvalRounds + CONTRACT_FEEDBACK_BONUS) {
+        const contractLines = capContractFails.slice(0, MAX_FEEDBACK_ISSUES).map(formatRuntimeProbeFeedback);
+        evalResult = {
+          ...evalResult,
+          issues: [...evalResult.issues, ...exitProbe.probeIssues],
+          runtimeProbe: exitProbe.meta,
+        };
+        console.log(
+          `[simple] eval round ${evalRoundsUsed}: contract probe fail active at cap — granting +1 retry ` +
+            `(ggui#1261; ${capContractFails.map((i) => i.subcategory).join(", ")})`,
+        );
+        return {
+          control: "feedback",
+          evalDone: false,
+          evalResult,
+          evalRoundsUsed,
+          prevModeSubcats: updatedPrevModeSubcats,
+          prevFailFingerprints: new Set([...currFailFingerprints, ...capContractFails.map(fingerprintFail)]),
+          preWarmedContext,
+          evalTokens,
+          evalLlmMs,
+          lastResultText: contractLines.join("\n\n"),
+          isEvalFeedback: true,
+          lastDiffFailed: false,
+          contractFeedback: contractFeedbackRecord(capContractFails, currentSource),
+        };
+      }
       if (!allowRuntimeExtension) {
         // Fold probe issues (if any) into evalResult for telemetry and
         // ALWAYS stamp the probe's execution meta, even though we're not