ravensight-playtest 0.5.2 → 0.6.0

package/src/commands/fix.js

@@ -1,4 +1,6 @@
+import { execFile } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
+import { promisify } from 'node:util';
 import { appendFile, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { optionsFrom, unknownOptionNotes } from '../run/args.js';
@@ -6,18 +8,30 @@ import { getDeps } from '../run/deps.js';
 import { createDriver } from '../run/drivers/index.js';
 import EXIT from '../run/exit.js';
 import { applyFix, fixSystem, MAX_PLAN_IMAGES, planContent, planFix, resolveFixMaxActions, summariseFix } from '../run/fixLoop.js';
-import { createGit, fixBranchName, preflight, startBranch } from '../run/git.js';
+import { abandonBranch, createGit, fixBranchName, preflight, startBranch } from '../run/git.js';
 import { createHeartbeat } from '../run/heartbeat.js';
 import { createModelClient } from '../run/model.js';
 import { jobDir, runDir as runDirFor, RUN_FILES, screenshotsDir } from '../run/paths.js';
 import { runPersona } from '../run/personaLoop.js';
-import { createRepoTools, PROFILE_TOOLS } from '../run/repoTools.js';
-import { assertNoSecrets } from '../run/secretScan.js';
+import { replayTrace } from '../run/replay.js';
+import { loadTrace, replayReport, replaySentence } from './replay.js';
+import { createRepoTools, PROFILE_TOOLS, WRITE_TOOLS } from '../run/repoTools.js';
+import { recordPrOpened } from '../run/labsOutcome.js';
+import { settleFailureLine } from '../run/settle.js';
+import { acceptanceLines, buildAcceptance, fixV2Live, frozenAcceptance, verifyBriefFromAcceptance } from '../run/acceptance.js';
+import { checkResultText, createCheckRunner, detectTestRunner, withRunCheck } from '../run/checks.js';
+import { isGodotProject } from '../run/drivers/godot-project.js';
+import { checksStillFailing, evidenceReport, withEvidenceIntact } from '../run/evidence.js';
+import { openPullRequest, shellQuote } from '../run/openPr.js';
+import { assertNoSecrets, withoutQuotedSecrets } from '../run/secretScan.js';
+import * as pendingRegister from '../run/pendingRegister.js';
 import * as stateFile from '../run/state.js';
 import { createUsageLedger, writeUsageFile } from '../run/usage.js';
-import { createInterruptHandler, deliver, driverOptions, exitCodeFor, explainRegisterRefusal, formatCents, resolveSetup, resolveTarget, skillFor, usableLocalBrief } from './run.js';
+import { createInterruptHandler, deliver, driverOptions, exitCodeFor, explainRegisterRefusal, formatCents, godotRefusal, resolveSetup, resolveTarget, skillFor, usableLocalBrief, startBalanceLine, startBalanceShort } from './run.js';
 import { loadLocalBrief } from '../briefLocal.js';
 
+const execFileAsync = promisify(execFile);
+
 /**
  * `ravensight-playtest fix <target>`: take one finding, change the code on a
  * new branch, replay the finding to see whether the change worked, and hand
@@ -25,10 +39,12 @@ import { loadLocalBrief } from '../briefLocal.js';
  *
  * Three rules shape everything else in this file:
  *
- * 1. **It edits, it never publishes.** All git usage lives in
+ * 1. **It edits, it never publishes on its own.** Git usage lives in
  *    `src/run/git.js`, which has no commit, no push and no way to reach a
  *    forge. The command ends by printing the pull request command; running it
- *    is the developer's decision, made with the diff in front of them.
+ *    is the developer's decision, made with the diff in front of them. The
+ *    one exception is Fix v2's `--open-pr` (`src/run/openPr.js`), which still
+ *    asks at its own prompt after a verified fix and never forces a push.
  * 2. **It buys the answer "no" as cheaply as possible.** The triage call comes
  *    before the first edit, because a finding that is design intent should
  *    cost a refunded unit rather than a branch full of changes nobody wanted.
@@ -65,6 +81,18 @@ export const REPRODUCED_ABOVE = 0.65;
 /** A changeset carries at most this many files. */
 export const MAX_CHANGESET_FILES = 20;
 
+/**
+ * Fix v2: at most this many repair turn sets after the first apply, each
+ * started by a failed check or a verify that still reproduces the finding.
+ */
+export const MAX_REPAIRS = 2;
+
+/** A repair turn set's own action ceiling, inside the same run budget. */
+export const REPAIR_MAX_ACTIONS = 20;
+
+/** The checks run after every apply turn set, in this order. */
+export const GATE_CHECKS = Object.freeze(['godot_import', 'godot_script_check', 'project_tests']);
+
 /**
  * @param {string} target `<jobId>/<label>` or a finding id
  * @param {Object} flags what commander hands over
@@ -96,6 +124,9 @@ export async function fixCommand(target, flags = {}, injected = {}) {
 export function parseTarget(target) {
   const value = String(target || '').trim();
   if (!value) return null;
+  // A finding's id is `<runId>/<label>`, so a run id on the left means the whole
+  // value names the finding, not a label inside a job.
+  if (value.startsWith('pt_run_')) return { jobId: null, label: null, findingId: value };
   const slash = value.lastIndexOf('/');
   if (slash > 0 && slash < value.length - 1) {
     return { jobId: value.slice(0, slash), label: value.slice(slash + 1), findingId: null };
@@ -129,6 +160,24 @@ export function hostedTargetRefusal(driverName, target) {
   return `${target} is not served from this machine, so a verify run there cannot see a change that only exists in this working tree. Serve the build locally and pass --build-url, or pass --no-verify to fix without verifying.`;
 }
 
+/**
+ * What became of a fix's unit when its verify could not boot the game, from the
+ * server's own answers: the unit comes back up to a limit per account.
+ *
+ * @param {{finished: Object|null, run: Object|null, priceCents: number}} input
+ * @returns {string}
+ */
+export function bootRefundLine({ finished, run, priceCents }) {
+  const start = 'The game did not boot for the verify run';
+  if (run && run.changeset && run.changeset.boot_refund_limited) {
+    return `${start}, and this account has used its refunds for that in the last 30 days, so the ${formatCents(priceCents)} is kept.`;
+  }
+  const cents = finished ? Number(finished.refunded_cents) || 0 : 0;
+  if (cents > 0) return `${start}, so the ${formatCents(cents)} comes back.`;
+  if (!finished) return `${start}. The job page says what came back once it settles.`;
+  return `${start}, and nothing came back of the ${formatCents(priceCents)} charged.`;
+}
+
 /**
  * The verdict in the words a developer reads.
  *
@@ -137,6 +186,10 @@ export function hostedTargetRefusal(driverName, target) {
  */
 export function verifyWords(verify) {
   if (!verify) return 'not verified';
+  // A verify run whose game never booted played a black screen: whatever the
+  // replay's report says, it says nothing about the fix.
+  if (verify.failed === 'game_boot_failed') return `not verified, the game did not boot (${verify.detail || 'see godot.log in the verify run directory'})`;
+  if (verify.failed) return `not verified, the verify run failed (${verify.detail || verify.failed})`;
   const score = verify.reproduced;
   if (typeof score !== 'number' || !Number.isFinite(score)) return 'unknown, the verify run reached no verdict';
   if (score < FIXED_BELOW) return `fixed (reproduced ${score})`;
@@ -171,7 +224,7 @@ async function fix(target, flags, injected, deps, log) {
 
   const wantsVerify = options.verify !== false;
   const driverName = options.driver || (context.config && context.config.driver) || 'playwright_web';
-  const buildTarget = resolveTarget(options, context.config, driverName);
+  const buildTarget = resolveTarget(options, context.config, driverName, repoRoot);
 
   // Said before anything is charged, because it is the difference between a
   // verify that means something and one that does not.
@@ -185,6 +238,11 @@ async function fix(target, flags, injected, deps, log) {
       log(refusal);
       return EXIT.ENVIRONMENT;
     }
+    const noGodot = await godotRefusal({ driverName, godotPath: options.godotPath, projectDir: buildTarget, injected });
+    if (noGodot) {
+      log(noGodot);
+      return EXIT.ENVIRONMENT;
+    }
     if (driverName === 'playwright_web') {
       log(`The verify run plays ${buildTarget}, which has to serve this working tree. Rebuild and serve the branch before the verify, or its answer is about the old build.`);
     }
@@ -218,16 +276,29 @@ async function fix(target, flags, injected, deps, log) {
   // repro steps and the persona's words are written in full.
   const finding = enrichFinding(listed, evidence.reportJson);
 
-  const branch = options.branch || fixBranchName(finding.label || finding.finding_id);
+  const pendingScope = { kind: 'fix', gameId, target: finding.finding_id };
+  const pendingRequest = options.idempotencyKey ? null : await pendingRegister.load(repoRoot, pendingScope);
+  const branch = pendingRequest ? pendingRequest.branch : options.branch || fixBranchName(finding.label || finding.finding_id);
   const git = injected.git || createGit({ root: repoRoot });
   // Every refusal now, the one mutation after the price is agreed: a developer
   // who says no to the charge should not be left on a new branch.
-  const checked = await preflight({ git, branch, allowDirty: Boolean(options.allowDirty), create: false });
+  const checked = await preflight({ git, branch, allowDirty: Boolean(options.allowDirty), create: false, reuseBranch: Boolean(pendingRequest) });
+  if (pendingRequest) {
+    log(`The last attempt at this fix got no clear answer, so this run asks about that same request on ${branch}. If it was charged, this answers with that job.`);
+    checked.from = pendingRequest.from;
+  }
   if (!checked.ok) {
     log(checked.reason);
     return EXIT.ENVIRONMENT;
   }
 
+  // --open-pr commits what the fix changed, and a dirty tree makes that a mixture
+  // of two people's work. Refused now, because nothing later can tell them apart.
+  if (options.openPr && checked.dirty) {
+    log('--open-pr publishes a commit, and this working tree has uncommitted changes that would be mixed into it. Commit or stash them, or leave out --open-pr. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+
   // A fix job asks for exactly one persona, the one who filed the finding: the
   // server creates the verify run from it, and both zero and two are a 400.
   const personaSlug = finding.persona || ((pack.personas || [])[0] || {}).slug || null;
@@ -235,7 +306,33 @@ async function fix(target, flags, injected, deps, log) {
     log('That finding names no persona and the content pack has none, so there is nobody to verify the fix with.');
     return EXIT.ENVIRONMENT;
   }
-  const estimate = await api.jobs.estimate(gameId, { modules: [...FIX_MODULES], personas: [personaSlug] });
+  // Fix v2 (Labs beta) only when the server says it is live for this game.
+  // Anything else, including a server that has never heard of Labs, is the standard fix.
+  const labs = !options.noLabs && (await fixV2Live(api, gameId, {
+    onUnfunded: () => log('Fix v2 (Labs beta) needs an account that has added at least $10.00 in top-ups, so this is an ordinary fix.')
+  }));
+  const acceptance = labs ? buildAcceptance(finding, { persona: personaSlug, reproSteps: reproStepsOf(finding) }) : null;
+  if (acceptance) {
+    log('Fix v2 (Labs beta) is on for this game: named checks, up to two repairs, and an evidence report.');
+    for (const line of acceptanceLines(acceptance)) log(line);
+  }
+  // Tests are the developer's code run with the model's edits in place, so
+  // they run only with --allow-tests or a yes at a terminal, asked now,
+  // before anything is charged.
+  let allowTests = Boolean(options.allowTests);
+  if (labs && !allowTests) {
+    const projectDir = await checkProjectDir({ driverName, buildTarget, repoRoot });
+    const runner = projectDir ? await detectTestRunner(projectDir) : null;
+    const askTests = injected.confirmTests || (process.stdin.isTTY && deps.ui && deps.ui.confirm);
+    if (runner && askTests) {
+      allowTests = Boolean(await askTests(`This project ships ${runner === 'gut' ? 'GUT' : 'gdUnit4'} tests. Let the fix run them, with its edits in place, on this machine?`, { yes: false }));
+    }
+  }
+  if (options.openPr && !labs) {
+    log('--open-pr is part of Fix v2 (Labs beta), which is not on for this game, so it is ignored and the pull request command is printed instead.');
+  }
+
+  const estimate = await api.jobs.estimate(gameId, { modules: [...FIX_MODULES], personas: [personaSlug], ...(acceptance ? { acceptance: true } : {}) });
   const priceCents = Number.isFinite(Number(estimate.estimate_cents)) ? Number(estimate.estimate_cents) : Number(estimate.price_cents);
   if (!Number.isFinite(priceCents)) {
     // Sending `confirm_price_cents: undefined` would be refused as
@@ -244,8 +341,15 @@ async function fix(target, flags, injected, deps, log) {
     log('The server quoted no price for this fix, so nothing was charged. Run "ravensight-playtest check" and try again.');
     return EXIT.ENVIRONMENT;
   }
-  const offer = `${formatCents(priceCents)} fix attempt (includes one verify run). Balance: ${formatCents(estimate.balance_cents)}.`;
+  const offer = `${formatCents(priceCents)} fix attempt (includes one verify run). Balance: ${formatCents(estimate.balance_cents)}.`
+    + (labs ? ' The checks and the verify run execute the edited project on this machine with a reduced environment.' : '');
   log(offer);
+  const floorLine = startBalanceLine(estimate);
+  if (floorLine) log(floorLine);
+  if (estimate.ok === false && floorLine) {
+    log(`${startBalanceShort(estimate)} An ordinary fix, with --no-labs, starts on its price alone.`);
+    return EXIT.ENVIRONMENT;
+  }
   if (estimate.ok === false) {
     log(`That is more than the balance covers. Top up at ${estimate.topup_url || 'ravensight.io'} and run this again.`);
     return EXIT.ENVIRONMENT;
@@ -260,42 +364,86 @@ async function fix(target, flags, injected, deps, log) {
     }
   }
 
-  const started = await startBranch({ git, branch });
+  const started = pendingRequest ? await pendingRegister.returnToBranch({ git, branch }) : await startBranch({ git, branch });
   if (!started.ok) {
     log(started.reason);
     return EXIT.ENVIRONMENT;
   }
   log(`branch ${branch}, from ${checked.head.slice(0, 8)}${checked.from ? ` on ${checked.from}` : ''}.`);
 
-  const idempotencyKey = options.idempotencyKey || randomUUID();
+  // Every way out before a job exists has to leave the developer where they were,
+  // unless nobody knows whether a job exists. Then the key and the branch are the way back.
+  const noJob = async () => {
+    await pendingRegister.clear(repoRoot, pendingScope);
+    await abandonBranch({ git, branch, from: checked.from, head: checked.head });
+  };
+  const remember = key => pendingRegister.save(repoRoot, pendingScope, { idempotencyKey: key, branch, from: checked.from, head: checked.head });
+  let idempotencyKey = options.idempotencyKey || (pendingRequest && pendingRequest.idempotencyKey) || randomUUID();
+  const registerBody = {
+    modules: [...FIX_MODULES],
+    personas: [personaSlug],
+    finding_id: finding.finding_id,
+    driver: driverName,
+    cli_version: cliVersion,
+    confirm_price_cents: priceCents,
+    brief_version: brief ? brief.version ?? null : null,
+    build: buildTarget
+      ? { kind: driverName === 'playwright_web' ? 'url' : 'godot_project', ref: buildTarget }
+      : { kind: 'repo', ref: repoRoot },
+    repo: { commit: checked.head, dirty: Boolean(checked.dirty), branch },
+    max_actions: Number.isInteger(options.maxActions) ? options.maxActions : null,
+    pack_versions: { pack: pack.pack_version },
+    ...(acceptance ? { acceptance } : {})
+  };
+  // A failed register, whichever attempt: `undefined` means it was an exception to rethrow.
+  const registerFailed = async error => {
+    if (pendingRegister.outcomeUnknown(error)) {
+      log(pendingRegister.unknownOutcomeMessage('this fix', branch));
+      return EXIT.ENVIRONMENT;
+    }
+    await noJob();
+    const handled = explainRegisterRefusal(error, log);
+    return handled !== null ? handled : undefined;
+  };
   let registered;
   try {
-    registered = await api.jobs.register(gameId, {
-      modules: [...FIX_MODULES],
-      personas: [personaSlug],
-      finding_id: finding.finding_id,
-      driver: driverName,
-      cli_version: cliVersion,
-      confirm_price_cents: priceCents,
-      brief_version: brief ? brief.version ?? null : null,
-      build: buildTarget
-        ? { kind: driverName === 'playwright_web' ? 'url' : 'godot_project', ref: buildTarget }
-        : { kind: 'repo', ref: repoRoot },
-      repo: { commit: checked.head, dirty: Boolean(checked.dirty), branch },
-      max_actions: Number.isInteger(options.maxActions) ? options.maxActions : null,
-      pack_versions: { pack: pack.pack_version }
-    }, { idempotencyKey });
+    await remember(idempotencyKey);
+    registered = await api.jobs.register(gameId, registerBody, { idempotencyKey });
   } catch (error) {
-    const handled = explainRegisterRefusal(error, log);
-    if (handled !== null) return handled;
-    throw error;
+    if (acceptance && error && ['labs_not_enabled', 'funding_required'].includes(error.code)) {
+      // Labs went off, or the funding floor stopped being met, between the status read
+      // and the register. Nothing was charged by a refusal, so register the ordinary
+      // fix instead, on a fresh key because the body differs.
+      log(`The server refused Fix v2 for this game (${error.code}), so this is an ordinary fix.`);
+      delete registerBody.acceptance;
+      idempotencyKey = randomUUID();
+      try {
+        await remember(idempotencyKey);
+        registered = await api.jobs.register(gameId, registerBody, { idempotencyKey });
+      } catch (retryError) {
+        const exit = await registerFailed(retryError);
+        if (exit !== undefined) return exit;
+        throw retryError;
+      }
+    } else {
+      const exit = await registerFailed(error);
+      if (exit !== undefined) return exit;
+      throw error;
+    }
   }
+  await pendingRegister.clear(repoRoot, pendingScope);
 
   const jobId = registered.job_id;
   // Runs are told apart by module and nothing else: the fix run carries
   // `persona: null`, and only the verify run carries the slug.
   const fixRun = (registered.runs || []).find(entry => entry.module === 'fix');
-  const verifyRun = (registered.runs || []).find(entry => entry.module === 'persona_playtest') || null;
+  const verifyRuns = (registered.runs || []).filter(entry => entry.module === 'persona_playtest');
+  const verifyRun = verifyRuns[0] || null;
+  // The contract the server froze. None means the server kept none, and the
+  // fix runs as the standard fix does: no checks, no repairs, no evidence report.
+  const frozen = acceptance ? frozenAcceptance(registered) : null;
+  if (acceptance && !frozen) log('The server did not keep the acceptance contract, so this fix runs without checks or repairs.');
+  const v2 = Boolean(frozen);
 
   await mkdir(jobDir(repoRoot, jobId), { recursive: true });
   const journal = stateFile.newState({
@@ -317,7 +465,8 @@ async function fix(target, flags, injected, deps, log) {
       findingId: finding.finding_id,
       verify: wantsVerify,
       allowDirty: Boolean(options.allowDirty),
-      maxActions: options.maxActions ?? null
+      maxActions: options.maxActions ?? null,
+      ...(v2 ? { labs: 'fix_v2' } : {})
     }
   });
   for (const entry of registered.runs || []) {
@@ -331,7 +480,7 @@ async function fix(target, flags, injected, deps, log) {
 
   if (!fixRun) {
     log('The server registered the job without a fix run, so there is nothing to spend a model turn from.');
-    await skipRun({ api, gameId, jobId, run: verifyRun, reason: 'the job has no fix run', log });
+    for (const entry of v2 ? verifyRuns : [verifyRun]) await skipRun({ api, gameId, jobId, run: entry, reason: 'the job has no fix run', log });
     // Settled rather than abandoned: the job is charged and unplayable, so the
     // refund is owed now and not in half an hour when the sweep notices.
     await settle({ api, gameId, jobId, repoRoot, journal, reason: 'the job has no fix run', log });
@@ -354,6 +503,7 @@ async function fix(target, flags, injected, deps, log) {
     onError: () => {}
   });
   const inFlight = new Map();
+  const abort = new AbortController();
   const interrupt = createInterruptHandler({
     api,
     gameId,
@@ -366,7 +516,9 @@ async function fix(target, flags, injected, deps, log) {
     // this job's verify persona against a half-applied edit would answer a
     // question nobody asked. A fix is abandoned and refunded instead.
     message: 'finishing the turn in flight, then stopping. A fix cannot be resumed, so this one is being given back.',
-    injected
+    injected,
+    // The verify run listens to this: every turn it plays after a Ctrl-C is model spend.
+    onInterrupt: () => abort.abort()
   });
 
   try {
@@ -387,10 +539,11 @@ async function fix(target, flags, injected, deps, log) {
       heartbeat.stop();
       inFlight.delete(fixRun.run_id);
       log(`${finding.label || finding.finding_id} reads as design intent, not a defect (confidence ${verdict.confidence}, from ${verdict.source || 'the brief'}), so nothing was edited.`);
+      for (const entry of v2 ? verifyRuns : [verifyRun]) await skipRun({ api, gameId, jobId, run: entry, reason: 'the finding is design intent', log });
       await completeFixRun({ api, gameId, jobId, runId: fixRun.run_id, body: { state: 'failed', reason: 'intended' }, log });
-      await skipRun({ api, gameId, jobId, run: verifyRun, reason: 'the finding is design intent', log });
-      await settle({ api, gameId, jobId, repoRoot, journal, reason: 'the finding is design intent', log });
-      log('The fix unit was refunded. Mark the finding as intended in the dashboard so no later job spends a turn on it.');
+      const intended = await settle({ api, gameId, jobId, repoRoot, journal, reason: 'the finding is design intent', log });
+      if (Number(intended?.refunded_cents) > 0) log('The fix unit was refunded.');
+      log('Mark the finding as intended in the dashboard so no later job spends a turn on it.');
       return EXIT.OK;
     }
 
@@ -401,7 +554,8 @@ async function fix(target, flags, injected, deps, log) {
       jobId,
       branch,
       baseCommit: checked.head,
-      engine: pack.engine || null
+      engine: pack.engine || null,
+      ...(v2 ? { runCheck: true } : {})
     });
     const codeBrief = pack.code_brief || null;
     // `graph_context` only exists in a bundle asked for with this job's id: it
@@ -432,14 +586,26 @@ async function fix(target, flags, injected, deps, log) {
     if (plan.hypothesis) log(`hypothesis: ${plan.hypothesis}`);
 
     const maxActions = resolveFixMaxActions(options, pack);
-    const applied = await applyFix({
+    // Fix v2: one repository tool surface for the first apply and every
+    // repair, so the per-run write cap counts all of them, plus run_check.
+    const checks = v2
+      ? createCheckRunner({
+        projectDir: await checkProjectDir({ driverName, buildTarget, repoRoot }),
+        godotPath: options.godotPath || null,
+        allowTests,
+        allowToolScripts: Boolean(options.allowToolScripts),
+        changedFiles: async () => projectRelative(await git.diffStat(), repoRoot, await checkProjectDir({ driverName, buildTarget, repoRoot })),
+        ...(injected.checkRunner ? injected.checkRunner : {})
+      })
+      : null;
+    const applyRepo = v2 ? createRepoTools({ root: repoRoot, tools: WRITE_TOOLS }) : undefined;
+    const applyArgs = {
       client,
       jobId,
       runId: fixRun.run_id,
       repoRoot,
       system,
       plan,
-      maxActions,
       codeBrief,
       graphContext,
       ledger,
@@ -454,6 +620,11 @@ async function fix(target, flags, injected, deps, log) {
         appendFile(path.join(directory, 'transcript.jsonl'), `${JSON.stringify({ at: new Date().toISOString(), ...progress })}\n`).catch(() => {});
       },
       shouldStop: () => interrupt.signalled || heartbeat.canceled
+    };
+    let applied = await applyFix({
+      ...applyArgs,
+      maxActions,
+      ...(v2 ? { acceptance: frozen, repo: withRunCheck(applyRepo, checks) } : {})
     });
 
     // A Ctrl-C, or the job cancelled from the dashboard. Either way this run is
@@ -465,16 +636,16 @@ async function fix(target, flags, injected, deps, log) {
       heartbeat.stop();
       inFlight.delete(fixRun.run_id);
       const why = interrupt.signalled ? 'interrupted by the developer' : 'cancelled';
+      for (const entry of v2 ? verifyRuns : [verifyRun]) await skipRun({ api, gameId, jobId, run: entry, reason: `the fix was ${why}`, log });
       await completeFixRun({ api, gameId, jobId, runId: fixRun.run_id, body: { state: 'failed', reason: 'error' }, log });
-      await skipRun({ api, gameId, jobId, run: verifyRun, reason: `the fix was ${why}`, log });
       try {
         await stateFile.patchRun(repoRoot, journal, fixRun.run_id, { state: 'failed', quit_reason: 'error' });
       } catch {
         // The journal is a convenience here; the server's own run state is the
         // record, and it has just been told.
       }
-      await settle({ api, gameId, jobId, repoRoot, journal, reason: `the fix was ${why}`, log });
-      log(`The fix was ${why} and cannot be resumed, so the unit was given back. The branch ${branch} holds whatever was written, and nothing was committed or pushed.`);
+      const stopped = await settle({ api, gameId, jobId, repoRoot, journal, reason: `the fix was ${why}`, log });
+      log(`The fix was ${why} and cannot be resumed${Number(stopped?.refunded_cents) > 0 ? ', so the unit was given back' : ''}. The branch ${branch} holds whatever was written, and nothing was committed or pushed.`);
       return EXIT.CANCELED;
     }
 
@@ -484,10 +655,10 @@ async function fix(target, flags, injected, deps, log) {
       heartbeat.stop();
       inFlight.delete(fixRun.run_id);
       log(`Nothing was changed, so there is nothing to review. The branch ${branch} is empty; delete it or stay on it.`);
+      for (const entry of v2 ? verifyRuns : [verifyRun]) await skipRun({ api, gameId, jobId, run: entry, reason: 'nothing was changed', log });
       await completeFixRun({ api, gameId, jobId, runId: fixRun.run_id, body: { state: 'failed', reason: 'no_change' }, log });
-      await skipRun({ api, gameId, jobId, run: verifyRun, reason: 'nothing was changed', log });
-      await settle({ api, gameId, jobId, repoRoot, journal, reason: 'nothing was changed', log });
-      log('The fix unit was refunded.');
+      const unchanged = await settle({ api, gameId, jobId, repoRoot, journal, reason: 'nothing was changed', log });
+      if (Number(unchanged?.refunded_cents) > 0) log('The fix unit was refunded.');
       return EXIT.OK;
     }
 
@@ -498,7 +669,69 @@ async function fix(target, flags, injected, deps, log) {
 
     // 4. Verify, by replaying the finding against the build.
     let verified = null;
-    if (wantsVerify && verifyRun) {
+    const verifies = [];
+    let repairs = 0;
+    // A script that does not parse or a project that does not import is not a
+    // change anyone can review, so it blocks the upload and the unit comes back
+    // (playtest_fix_check_failed), as it does for a feature. A failing project
+    // test ships, and the report says so first.
+    let checksBlock = false;
+    let usedVerifyRuns = 0;
+    if (v2) {
+      // Fix v2: checks after every apply turn set, verify once they pass, and
+      // at most MAX_REPAIRS repair turn sets started by a failed check or a
+      // verify that still reproduces. The contract never changes.
+      const verifyArgs = {
+        deps, api, client, gameId, jobId, repoRoot, pack, brief, finding, driverName,
+        target: buildTarget, options, journal,
+        maxActions: Math.min(VERIFY_MAX_ACTIONS, maxActions),
+        makeDriver: injected.driverFactory || createDriver,
+        signal: abort.signal,
+        acceptance: frozen,
+        sourceRunId,
+        ...(injected.replayer ? { replayer: injected.replayer } : {}),
+        log
+      };
+      for (;;) {
+        const gate = await runGateChecks(checks, log);
+        checksBlock = gate.importFailed || gate.failed.some(result => result.name === 'godot_script_check');
+        const canRepair = repairs < MAX_REPAIRS && applied.stop !== 'budget' && !interrupt.signalled && !heartbeat.canceled;
+        let repairReason = null;
+        let repairDetail = '';
+        if (gate.failed.length > 0) {
+          repairReason = gate.failed.some(result => result.status === 'check_refused')
+            ? 'the checks were refused because of what the change edited'
+            : `the ${gate.failed.map(result => result.name).join(' and ')} check${gate.failed.length > 1 ? 's' : ''} failed`;
+          repairDetail = gate.failed.map(checkResultText).join('\n\n');
+        } else if (wantsVerify && usedVerifyRuns < verifyRuns.length) {
+          verified = await runVerify({ ...verifyArgs, entry: verifyRuns[usedVerifyRuns] });
+          usedVerifyRuns += 1;
+          verifies.push(verified);
+          const score = verified && !verified.failed ? verified.reproduced : null;
+          // A repair after verify needs a fresh verify run to judge it; the
+          // server registers spares for Fix v2, and without one there is
+          // nothing to re-verify with, so no repair is spent.
+          if (typeof score === 'number' && score > REPRODUCED_ABOVE && usedVerifyRuns < verifyRuns.length) {
+            repairReason = `the verify run still reproduced the finding (${score})`;
+            repairDetail = `verify run ${verified.run_id}: ${verifyWords(verified)}. The acceptance contract is unchanged: ${frozen.actual} should become: ${frozen.expected}`;
+          }
+        }
+        if (!repairReason || !canRepair) break;
+        repairs += 1;
+        log(`repair ${repairs} of ${MAX_REPAIRS}: ${repairReason}.`);
+        applied = await applyFix({
+          ...applyArgs,
+          maxActions: Math.min(REPAIR_MAX_ACTIONS, maxActions),
+          acceptance: frozen,
+          repair: { attempt: repairs, of: MAX_REPAIRS, reason: repairReason, detail: repairDetail },
+          repo: withRunCheck(applyRepo, checks)
+        });
+        if (interrupt.signalled || heartbeat.canceled) break;
+      }
+      for (const spare of verifyRuns.slice(usedVerifyRuns)) {
+        await skipRun({ api, gameId, jobId, run: spare, reason: checksBlock ? 'the fix did not pass its checks' : (wantsVerify ? 'no repair needed it' : 'skipped with --no-verify'), log });
+      }
+    } else if (wantsVerify && verifyRun) {
       verified = await runVerify({
         deps,
         api,
@@ -516,14 +749,61 @@ async function fix(target, flags, injected, deps, log) {
         journal,
         maxActions: Math.min(VERIFY_MAX_ACTIONS, maxActions),
         makeDriver: injected.driverFactory || createDriver,
+        signal: abort.signal,
         log
       });
     } else {
       await skipRun({ api, gameId, jobId, run: verifyRun, reason: wantsVerify ? 'no verify run was registered' : 'skipped with --no-verify', log });
     }
+    if (interrupt.signalled || heartbeat.canceled) {
+      heartbeat.stop();
+      inFlight.delete(fixRun.run_id);
+      await completeFixRun({ api, gameId, jobId, runId: fixRun.run_id, body: { state: 'failed', reason: 'error' }, log });
+      await settle({ api, gameId, jobId, repoRoot, journal, reason: 'the fix was interrupted', log });
+      log(`The fix was interrupted and cannot be resumed, so the unit was given back. The branch ${branch} holds whatever was written.`);
+      return EXIT.CANCELED;
+    }
+
+    // A repair may have touched more files than the first apply did.
+    const finalChanged = v2 ? await git.diffStat() : changed;
+    const finalFiles = v2 ? finalChanged.slice(0, MAX_CHANGESET_FILES) : files;
+
+    if (v2 && checksBlock) {
+      // A fix the project cannot import or parse is not uploaded: there is no
+      // review it deserves. The evidence stays local for the developer.
+      heartbeat.stop();
+      inFlight.delete(fixRun.run_id);
+      const body = evidenceReport({
+        prBody: `# Fix ${finding.label || finding.finding_id}: not uploaded\n\nThis change does not pass its checks.`,
+        summarySource: 'local',
+        acceptance: frozen,
+        finding,
+        sourceRunId,
+        plan,
+        files: finalFiles,
+        checks: checks.results,
+        verifies,
+        repairs,
+        maxRepairs: MAX_REPAIRS,
+        wantsVerify,
+        thresholds: { fixedBelow: FIXED_BELOW, reproducedAbove: REPRODUCED_ABOVE }
+      });
+      await writeFile(path.join(directory, RUN_FILES.reportMd), body, 'utf8').catch(() => {});
+      const stillFailing = checksStillFailing(checks.results);
+      const refusedCheck = checks.results.some(result => stillFailing.includes(result.name) && result.status === 'check_refused');
+      const blockedBy = refusedCheck
+        ? 'The checks were refused for this change'
+        : (stillFailing.includes('godot_import') ? 'The project does not import with this change' : 'This change does not pass its script check');
+      log(`${blockedBy} after ${repairs} repair(s), so the changeset was not uploaded. The evidence is in ${path.join(directory, RUN_FILES.reportMd)} and the branch ${branch} holds the edit.`);
+      // `check_failed` is the server's own word for this, so the ledger and the
+      // dashboard say the fix failed its checks rather than that a run crashed.
+      await completeFixRun({ api, gameId, jobId, runId: fixRun.run_id, body: { state: 'failed', reason: 'check_failed' }, log });
+      await settle({ api, gameId, jobId, repoRoot, journal, reason: 'the fix did not pass its checks', log });
+      return EXIT.FAILED;
+    }
 
     // 5. The pull request text, from the diff that exists.
-    const fallback = localSummary({ finding, plan, files, verify: verified, branch, applied });
+    const fallback = localSummary({ finding, plan, files: finalFiles, verify: verified, branch, applied });
     // Both budget stops mean the apply loop left off early rather than because
     // it was finished, so both carry the caveat. Only the 402 skips the
     // summarise call, because only the 402 means there is nothing left to
@@ -538,24 +818,48 @@ async function fix(target, flags, injected, deps, log) {
         system,
         finding: findingForPrompt(finding),
         plan,
-        files,
+        files: finalFiles,
         verify: verified,
+        thresholds: { fixedBelow: FIXED_BELOW, reproducedAbove: REPRODUCED_ABOVE },
         branch,
         fallback,
         ledger,
         log
       });
 
-    const changeset = {
+    // Fix v2: the pull request body is the evidence report, which keeps what
+    // was measured apart from what a model wrote.
+    const prBody = v2
+      ? withEvidenceIntact(description => evidenceReport({
+        prBody: description,
+        summarySource: summary.source,
+        acceptance: frozen,
+        finding,
+        sourceRunId,
+        plan,
+        files: finalFiles,
+        checks: checks.results,
+        verifies,
+        repairs,
+        maxRepairs: MAX_REPAIRS,
+        wantsVerify,
+        budgetTouched,
+        thresholds: { fixedBelow: FIXED_BELOW, reproducedAbove: REPRODUCED_ABOVE }
+      }), summary.prBody)
+      : summary.prBody;
+
+    const changeset = withoutQuotedSecrets({
       schema_version: '1.0',
       finding_id: finding.finding_id,
       branch,
       base_commit: checked.head,
-      files,
-      verify: verified ? { run_id: verified.run_id, reproduced: verified.reproduced } : null,
+      files: finalFiles,
+      // A verify that never played the fix (its game did not boot, or the run
+      // died) is no verify at all: the changeset says unverified.
+      verify: verified && !verified.failed ? { run_id: verified.run_id, reproduced: verified.reproduced } : null,
       pr_title: summary.prTitle,
-      pr_body: summary.prBody
-    };
+      pr_body: prBody
+    }, log);
 
     await heartbeat.beat();
     heartbeat.stop();
@@ -584,19 +888,34 @@ async function fix(target, flags, injected, deps, log) {
       // whole diagnosis: "pr_title too long" is actionable, "422" is not.
       for (const detail of changesetDetails(error)) log(`  ${detail}`);
     }
-    await settle({ api, gameId, jobId, repoRoot, journal, reason: '', log });
-
-    report({ changeset, directory, reportPath, verified, options, log, injected, deps, budget: budgetTouched });
+    const finished = await settle({ api, gameId, jobId, repoRoot, journal, reason: '', log });
+
+    if (verified && verified.failed === 'game_boot_failed') {
+      // The server refunds a fix whose verify run could not boot
+      // (playtest_fix_unverified_boot) only up to the account's limit, so this says
+      // what its answer says and never assumes.
+      const answer = await api.runs.get(gameId, jobId, fixRun.run_id).catch(() => null);
+      log(bootRefundLine({ finished, run: (answer && (answer.run || answer)) || null, priceCents: registered.price && registered.price.price_cents }));
+    }
+    let opened = null;
+    if (v2 && options.openPr) {
+      opened = await maybeOpenPr({ repoRoot, branch, changed: finalChanged, written: applyRepo.written, changeset, reportPath, verified, injected, deps, log });
+      if (opened.ok) await recordPrOpened({ api, gameId, repoRoot, journal, url: opened.url });
+    }
+    const stillFailing = v2 ? checksStillFailing(checks.results) : [];
+    if (stillFailing.length > 0) log(`checks failed on this change: ${stillFailing.join(', ')}. The verify run did not play it, and the unit is kept because a change was delivered. Read the evidence report before you use it.`);
+    if (!opened || !opened.ok) report({ changeset, directory, reportPath, verified, options, log, injected, deps, budget: budgetTouched });
     // Exit 2 is "the money ran out", which a warning is not: a warning means
     // the run wrapped up early with budget still in hand.
-    return applied.stop === 'budget' ? EXIT.BUDGET : EXIT.OK;
+    if (applied.stop === 'budget') return EXIT.BUDGET;
+    return opened && !opened.ok ? EXIT.ENVIRONMENT : EXIT.OK;
   } catch (error) {
     heartbeat.stop();
     const code = exitCodeFor(error);
     log(`fix failed: ${String(error && error.message)}`);
     log(`The branch ${branch} still holds whatever was written. Nothing was committed or pushed.`);
-    await failFixRun({ api, gameId, jobId, runId: fixRun.run_id, log });
     await skipRun({ api, gameId, jobId, run: verifyRun, reason: 'the fix failed', log });
+    await failFixRun({ api, gameId, jobId, runId: fixRun.run_id, log });
     await settle({ api, gameId, jobId, repoRoot, journal, reason: 'the fix failed', log });
     return code;
   } finally {
@@ -763,17 +1082,34 @@ export async function runVerify({
   journal,
   maxActions,
   makeDriver,
+  acceptance = null,
+  sourceRunId = null,
+  replayer = replayTrace,
+  signal,
   log
 }) {
   const directory = runDirFor(repoRoot, jobId, entry.run_id);
   await mkdir(directory, { recursive: true });
+
+  // FIX V2 REPLAYS THE SOURCE RUN FIRST. It costs no model call, and it can say
+  // one thing for certain: if the game answers identically at every recorded step,
+  // the fix changed nothing on the path that found the problem. It cannot say the
+  // problem is gone, because after a divergence the recorded inputs no longer mean
+  // anything, so a divergence goes to the persona like a run with no trace at all.
+  let divergence = null;
+  if (acceptance && driverName === 'godot_driver') {
+    const replayed = await replaySourceTrace({ api, gameId, jobId, repoRoot, finding, target, godotPath: options.godotPath, directory, sourceRunId, entry, log, replayer });
+    if (replayed.unchanged) return closeVerifyOnUnchanged({ deps, api, gameId, jobId, repoRoot, entry, journal, directory, log, report: replayed.report });
+    divergence = replayed.divergence;
+  }
+
   const persona = (pack.personas || []).find(candidate => candidate.slug === entry.persona) || (pack.personas || [])[0];
   if (!persona) {
     log('The content pack has no persona to verify with, so the fix is reported unverified.');
     return null;
   }
   const headless = driverName === 'godot_driver' ? options.headless === true : options.headed !== true;
-  const driver = await makeDriver(driverName, driverOptions({ headless, driverName, target, directory, entry, jobId }));
+  const driver = await makeDriver(driverName, driverOptions({ headless, driverName, target, directory, entry, jobId, godotPath: options.godotPath, realtime: options.realtime }));
   const ledger = createUsageLedger();
   const heartbeat = createHeartbeat({
     api,
@@ -810,13 +1146,17 @@ export async function runVerify({
       runDirectory: directory,
       skill: skillFor(pack, 'persona_playtest'),
       // The brief fetched above, as `run` does: the pack does not always carry one.
-      brief: verifyBrief(brief || pack.brief || null, finding),
+      // Fix v2 builds the verify brief from the frozen contract alone.
+      brief: withDivergence(acceptance
+        ? verifyBriefFromAcceptance(brief || pack.brief || null, acceptance)
+        : verifyBrief(brief || pack.brief || null, finding), divergence),
       localBrief,
       intentNotes: pack.intent_notes || [],
       schemas: pack.schemas || [],
       maxActions,
       heartbeat,
       ledger,
+      signal,
       log: message => log(`verify: ${message}`)
     });
   } catch (error) {
@@ -825,7 +1165,8 @@ export async function runVerify({
     await stateFile.patchRun(repoRoot, journal, entry.run_id, { state: failed.state, error: String(error && error.message), quit_reason: failed.quitReason });
     await deliver({ deps, api, gameId, jobId, runId: entry.run_id, directory, outcome: failed, options, log, journal, repoRoot });
     log(`the verify run failed (${String(error && error.message)}), so the fix is reported unverified.`);
-    return null;
+    const booted = !(error && (error.code === 'game_boot_failed' || /^game_boot_failed: /.test(String(error.message))));
+    return { run_id: entry.run_id, reproduced: null, source: null, failed: booted ? 'verify_failed' : 'game_boot_failed', detail: String(error && error.message).replace(/^game_boot_failed: /, '').slice(0, 200) };
   }
   heartbeat.stop();
 
@@ -848,10 +1189,100 @@ export async function runVerify({
     log(`the verify verdict could not be read (${String(error && error.message)}).`);
   }
   const verdict = (run && run.verify_verdict) || null;
-  const reproduced = verdict && Number.isFinite(Number(verdict.reproduced)) ? Number(verdict.reproduced) : null;
+  // Strictly a number. `Number(null)` is 0, and the server answers
+  // `{ reproduced: null, source: 'unavailable' }` when nobody could judge, so a
+  // coercion here reads a judge being down as "fixed (reproduced 0)".
+  const reproduced = verdict && typeof verdict.reproduced === 'number' && Number.isFinite(verdict.reproduced) ? verdict.reproduced : null;
   return { run_id: entry.run_id, reproduced, source: (verdict && verdict.source) || null };
 }
 
+/**
+ * Replay the source run's trace against the fix, on this working tree. Never
+ * fails the verify: anything short of a full match, including no trace at all,
+ * answers "not unchanged" and the persona decides. The outcome is recorded on the
+ * job, free, when the server takes it.
+ *
+ * @returns {Promise<{unchanged: boolean, divergence: Object|null}>}
+ */
+export async function replaySourceTrace({ api, gameId, jobId, repoRoot, finding, target, godotPath, directory, sourceRunId, entry, log, replayer = replayTrace }) {
+  const runId = sourceRunId || finding.run_id || null;
+  if (!runId) return { unchanged: false, divergence: null };
+  const trace = await loadTrace({ repoRoot, runId, jobId: finding.job_id || null, api, gameId });
+  if (!trace) return { unchanged: false, divergence: null };
+  let result;
+  try {
+    result = await replayer({ text: trace.text, projectDir: target, godotPath, runDir: path.join(directory, 'trace-replay') });
+  } catch (error) {
+    log(`verify: the source run's trace could not be replayed (${String(error && error.message)}). A persona replays the finding instead.`);
+    return { unchanged: false, divergence: null };
+  }
+  log(`verify: ${replaySentence(result)}`);
+  const sha = await headSha(repoRoot);
+  const report = sha ? replayReport(result, { ref: 'fix-branch', sha }) : null;
+  if (report && entry) {
+    try {
+      await api.runs.recordReplay(gameId, jobId, entry.run_id, report);
+    } catch {
+      // A record is for reading later. The verify does not depend on it.
+    }
+  }
+  // The server decides a verify from this whole report, so a replay that cannot
+  // name its commit cannot close one: a persona replays the finding instead.
+  // The same test as the server's `replayProvesIdentical`: a replay that compared
+  // nothing, or ran no ticks, matched only because it did nothing.
+  const proven = result.matched === true && result.fully_replayed === true && !result.stopped && !result.first_divergence && result.steps_compared > 0 && result.ticks > 0;
+  return { unchanged: Boolean(report) && proven, divergence: result.first_divergence || null, report };
+}
+
+async function headSha(repoRoot) {
+  try {
+    const { stdout } = await execFileAsync('git', ['-C', repoRoot, 'rev-parse', 'HEAD']);
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The trace matched everywhere, so the verify run is finished without a model.
+ * The verdict comes back from the server's own record of this complete, the same
+ * as a persona verify's, and it says the finding is still there.
+ */
+export async function closeVerifyOnUnchanged({ deps, api, gameId, jobId, repoRoot, entry, journal, directory, log, report }) {
+  log('verify: every recorded step answered the same, so this fix changed nothing on the path that found the problem. No model was called.');
+  for (const state of ['launching', 'playing', 'reporting', 'uploading']) {
+    await api.runs.transition(gameId, jobId, entry.run_id, state, { reason: '' });
+  }
+  await deps.finalizeRun(directory, {
+    api,
+    gameId,
+    jobId,
+    runId: entry.run_id,
+    body: { state: 'succeeded', actions_taken: 0, quit_reason: 'goal_reached', trace_replay: report }
+  });
+  await stateFile.patchRun(repoRoot, journal, entry.run_id, { state: 'succeeded', completed: true, uploaded: true });
+  const answer = await api.runs.get(gameId, jobId, entry.run_id);
+  const run = (answer && (answer.run || answer)) || null;
+  const verdict = (run && run.verify_verdict) || null;
+  // The same reading as a persona verify's: `Number(null)` is 0, which would read a
+  // judge that could not answer as "fixed (reproduced 0)".
+  const reproduced = verdict && typeof verdict.reproduced === 'number' && Number.isFinite(verdict.reproduced) ? verdict.reproduced : null;
+  return { run_id: entry.run_id, reproduced, source: (verdict && verdict.source) || 'trace_replay' };
+}
+
+/** Tell the verify persona where the fix first moved the game, as a starting point. */
+export function withDivergence(brief, divergence) {
+  if (!divergence || !brief) return brief;
+  const diff = Object.entries(divergence.game_state_diff || {}).slice(0, 5).map(([key, pair]) => `${key}: ${JSON.stringify(pair.expected)} became ${JSON.stringify(pair.actual)}`);
+  return {
+    ...brief,
+    fields: {
+      ...(brief.fields || {}),
+      verify_trace_note: `Replaying the original run against this fix first differed at tick ${divergence.frame ?? 'unknown'}${diff.length ? ` (${diff.join('; ')})` : ''}. That shows the fix changed behaviour there, not that the problem is gone. Check for yourself.`
+    }
+  };
+}
+
 /**
  * The verify run's brief: what it is being asked to reproduce, then the brief
  * a persona usually plays against. The task comes first because it is the one
@@ -942,11 +1373,13 @@ function report({ changeset, reportPath, verified, options, log, injected, deps,
   log(`verify: ${verifyWords(verified)}`);
   if (budget) log('The fix stopped early because its model budget was spent or nearly spent, so read the diff carefully: it may be half a change.');
   log('Nothing was committed and nothing was pushed. Read the diff, commit it, then:');
-  log(`  gh pr create --title "${String(changeset.pr_title).replace(/"/g, '\\"')}" --body-file ${reportPath}`);
+  log(`  gh pr create --title ${shellQuote(changeset.pr_title)} --body-file ${shellQuote(reportPath)}`);
 }
 
 /**
- * Complete the fix run, tolerating a refusal. The money is settled by
+ * Complete the fix run, tolerating a refusal. Every caller completes or skips
+ * the verify run(s) first: the server reads the verify run's record when the
+ * fix run completes (a verify that could not boot refunds the unit). The money is settled by
  * `finish` either way, and a refused complete must not turn a fix that worked
  * into a crash.
  */
@@ -977,11 +1410,13 @@ async function skipRun({ api, gameId, jobId, run, reason, log }) {
 
 /** `finish` settles the job once and issues at most one refund. */
 async function settle({ api, gameId, jobId, repoRoot, journal, reason, log }) {
+  let finished = null;
   try {
-    const finished = await api.jobs.finish(gameId, jobId, { reason });
+    finished = await api.jobs.finish(gameId, jobId, { reason });
     log(`job ${jobId} ${finished.job ? finished.job.state : 'finished'}: refunded ${formatCents(finished.refunded_cents)}.`);
+    if (finished.refund_limited_note) log(finished.refund_limited_note);
   } catch (error) {
-    log(`the job could not be settled now; the hourly sweep will settle it: ${String(error && error.message)}`);
+    log(settleFailureLine(jobId, error));
   }
   journal.finished = true;
   try {
@@ -990,6 +1425,7 @@ async function settle({ api, gameId, jobId, repoRoot, journal, reason, log }) {
     // The journal is a convenience at this point: the server's ledger is the
     // record of what was charged and what came back.
   }
+  return finished;
 }
 
 /** The finding as the prompt sees it: no ids nobody can act on, no noise. */
@@ -1061,6 +1497,80 @@ export function changesetDetails(error) {
     .filter(Boolean);
 }
 
+/**
+ * The Godot project the checks copy: the verify target for the Godot driver,
+ * else the repository when it is a Godot project, else none.
+ *
+ * @returns {Promise<string|null>}
+ */
+export async function checkProjectDir({ driverName, buildTarget, repoRoot }) {
+  if (driverName === 'godot_driver' && buildTarget) return buildTarget;
+  return (await isGodotProject(repoRoot)) ? repoRoot : null;
+}
+
+/**
+ * Repository relative paths as paths inside the Godot project, dropping any
+ * outside it.
+ */
+export function projectRelative(changed, repoRoot, projectDir) {
+  if (!projectDir) return [];
+  return changed
+    .map(file => path.relative(projectDir, path.join(repoRoot, file.path)))
+    .filter(file => file && !file.startsWith('..') && !path.isAbsolute(file));
+}
+
+/**
+ * Every gate check, in order. `godot_import` failing is the one that blocks an
+ * upload; the others start a repair and, if they still fail, are listed as
+ * remaining risks.
+ *
+ * @returns {Promise<{failed: Array<Object>, importFailed: boolean}>}
+ */
+export async function runGateChecks(checks, log = () => {}) {
+  const failed = [];
+  let importFailed = false;
+  for (const name of GATE_CHECKS) {
+    // A refusal names the edits, not the check, so the rest would only repeat it.
+    if (failed.some(result => result.status === 'check_refused')) break;
+    // After a failed import the tests cannot mean anything, but the script
+    // check still can: the import names the scripts that could not load
+    // because of a broken one, the script check names the broken line.
+    if (importFailed && name === 'project_tests') continue;
+    const result = await checks.run(name);
+    log(`check ${name}: ${result.status} (${result.detail})`);
+    if (result.status === 'failed' || result.status === 'check_refused') {
+      failed.push(result);
+      // A refused check blocks the upload exactly as a failed import does:
+      // nothing proved the change imports.
+      if (name === 'godot_import' || result.status === 'check_refused') importFailed = true;
+    }
+  }
+  return { failed, importFailed };
+}
+
+/**
+ * `--open-pr` after the fix is uploaded: only for a fix the verify scored as
+ * fixed, and only with the developer's own yes.
+ */
+export async function maybeOpenPr({ repoRoot, branch, changed, written = null, changeset, reportPath, verified, injected, deps, log }) {
+  if (!verifyWords(verified).startsWith('fixed')) {
+    log(`--open-pr opens a pull request only for a verified fix, and this one reads ${verifyWords(verified)}. Nothing was pushed.`);
+    return { ok: false, reason: 'not_verified' };
+  }
+  const opener = injected.openPullRequest || openPullRequest;
+  return opener({
+    repoRoot,
+    branch,
+    // What the fix wrote, not whatever else is in the tree by now: a run can leave
+    // files behind that are not the change.
+    paths: changed.map(file => file.path).filter(file => !written || written.includes(file)),
+    title: changeset.pr_title,
+    bodyFile: reportPath,
+    confirm: injected.confirmPr || injected.confirm || (deps.ui && deps.ui.confirm),
+    log
+  });
+}
+
 function isImageName(name) {
   return /\.(png|jpe?g|webp)$/i.test(String(name));
 }