ravensight-playtest 0.1.0 → 0.2.3

package/src/commands/fix.js

@@ -0,0 +1,1059 @@
+import { randomUUID } from 'node:crypto';
+import { appendFile, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { optionsFrom } from '../run/args.js';
+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 { 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 * as stateFile from '../run/state.js';
+import { createUsageLedger, writeUsageFile } from '../run/usage.js';
+import { createInterruptHandler, deliver, exitCodeFor, explainRegisterRefusal, formatCents, resolveSetup, resolveTarget, skillFor } from './run.js';
+
+/**
+ * `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
+ * the developer a pull request to open.
+ *
+ * Three rules shape everything else in this file:
+ *
+ * 1. **It edits, it never publishes.** All 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.
+ * 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.
+ *    A fix that changes nothing is refunded the same way.
+ * 3. **A verify run that cannot see the change is worse than none.** The
+ *    verify plays the build the developer points at, so a build served from
+ *    somewhere else would answer about yesterday's code. That is refused
+ *    rather than reported, because a false "fixed" is the one answer this
+ *    command must never give.
+ */
+
+/** The job a fix registers. The verify run comes back with it. */
+export const FIX_MODULES = Object.freeze(['fix']);
+
+/**
+ * What the content pack is asked for: the fix skill and the persona skill,
+ * because the verify run is an ordinary persona run.
+ */
+export const PACK_MODULES = Object.freeze(['fix', 'persona_playtest']);
+
+/** The changeset lands beside `report.md` in the fix run directory. */
+export const CHANGESET_FILE = 'changeset.json';
+
+/** At or above this confidence, `design_intent` stops the fix before it edits. */
+export const DESIGN_INTENT_CONFIDENCE = 0.7;
+
+/** The verify run's own action ceiling: it reproduces one finding, nothing more. */
+export const VERIFY_MAX_ACTIONS = 20;
+
+/** How the judged `reproduced` score reads in words. */
+export const FIXED_BELOW = 0.35;
+export const REPRODUCED_ABOVE = 0.65;
+
+/** A changeset carries at most this many files. */
+export const MAX_CHANGESET_FILES = 20;
+
+/**
+ * @param {string} target `<jobId>/<label>` or a finding id
+ * @param {Object} flags what commander hands over
+ * @param {Object} [injected] test seam
+ * @returns {Promise<number>} process exit code
+ */
+export async function fixCommand(target, flags = {}, injected = {}) {
+  const deps = injected.deps || (await getDeps());
+  const log = injected.log || (deps.ui && deps.ui.info ? message => deps.ui.info(message) : message => console.log(message));
+  try {
+    return await fix(target, flags, injected, deps, log);
+  } catch (error) {
+    const code = exitCodeFor(error);
+    if (code === EXIT.FAILED) throw error;
+    log(String(error && error.message ? error.message : error));
+    return code;
+  }
+}
+
+/**
+ * `<jobId>/<label>` or a bare finding id.
+ *
+ * The last slash wins, because a job id has no slash in it and a label never
+ * does either, while an id from somewhere else might.
+ *
+ * @param {string} target
+ * @returns {{jobId: string|null, label: string|null, findingId: string|null}|null}
+ */
+export function parseTarget(target) {
+  const value = String(target || '').trim();
+  if (!value) return null;
+  const slash = value.lastIndexOf('/');
+  if (slash > 0 && slash < value.length - 1) {
+    return { jobId: value.slice(0, slash), label: value.slice(slash + 1), findingId: null };
+  }
+  if (slash !== -1) return null;
+  return { jobId: null, label: null, findingId: value };
+}
+
+/**
+ * The verify run plays a URL, and a URL this machine does not serve cannot
+ * show an edit that only exists in this working tree. A hosted build would
+ * answer about the last upload instead, and answer it confidently.
+ *
+ * @param {string} driverName
+ * @param {string|null} target
+ * @returns {string|null} the refusal, or null
+ */
+export function hostedTargetRefusal(driverName, target) {
+  if (driverName !== 'playwright_web' || !target) return null;
+  let host;
+  try {
+    host = new URL(String(target)).hostname.toLowerCase();
+  } catch {
+    return `${target} is not a URL the verify run can play. Pass --build-url with a local address, or --no-verify.`;
+  }
+  // Node keeps the brackets on an IPv6 hostname, so `http://[::1]:8080/`
+  // answers `[::1]` and never the bare form.
+  const local = host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]'
+    || host === '0.0.0.0' || host.endsWith('.localhost');
+  if (local) return null;
+  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.`;
+}
+
+/**
+ * The verdict in the words a developer reads.
+ *
+ * @param {{reproduced: number|null}|null} verify
+ * @returns {string}
+ */
+export function verifyWords(verify) {
+  if (!verify) return 'not verified';
+  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})`;
+  if (score > REPRODUCED_ABOVE) return `still reproduced (${score})`;
+  return `unknown (reproduced ${score})`;
+}
+
+/**
+ * @param {string} target
+ * @param {Object} flags
+ * @param {Object} injected
+ * @param {Object} deps
+ * @param {(message: string) => void} log
+ * @returns {Promise<number>}
+ */
+async function fix(target, flags, injected, deps, log) {
+  const { options, unknown } = optionsFrom(flags);
+  if (unknown.length > 0) {
+    log(`I do not know these options: ${unknown.join(', ')}. Run "ravensight-playtest fix --help".`);
+    return EXIT.ENVIRONMENT;
+  }
+  const parsed = parseTarget(target);
+  if (!parsed) {
+    log('Name the finding to fix: either <jobId>/<label>, like pt_job_1/F002, or a finding id.');
+    return EXIT.ENVIRONMENT;
+  }
+
+  const setup = await resolveSetup(deps, options, log);
+  if (setup.code !== undefined) return setup.code;
+  const { context, api, gameId, apiUrl, repoRoot, cliVersion } = setup;
+
+  const wantsVerify = options.verify !== false;
+  const driverName = options.driver || (context.config && context.config.driver) || 'playwright_web';
+  const buildTarget = resolveTarget(options, context.config, driverName);
+
+  // Said before anything is charged, because it is the difference between a
+  // verify that means something and one that does not.
+  if (wantsVerify) {
+    if (!buildTarget) {
+      log('The verify run needs a build to play: pass --build-url for a web build or --godot-project for a Godot project, or pass --no-verify.');
+      return EXIT.ENVIRONMENT;
+    }
+    const refusal = hostedTargetRefusal(driverName, buildTarget);
+    if (refusal) {
+      log(refusal);
+      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.`);
+    }
+  }
+
+  const pack = await deps.packs.get({ api, gameId, modules: PACK_MODULES });
+  const fixSkill = (pack.skills || []).find(entry => entry.module === 'fix');
+  if (!fixSkill) {
+    log('The content pack has no fix skill. Run "ravensight-playtest check" and try again.');
+    return EXIT.ENVIRONMENT;
+  }
+  // A fix job registers a persona run, so the persona skill has to be there
+  // too. Finding that out now beats finding it out after the charge.
+  if (wantsVerify && !(pack.skills || []).some(entry => entry.module === 'persona_playtest')) {
+    log('The content pack has no persona-playtest skill, so the verify run could not be played. Run "ravensight-playtest check" and try again.');
+    return EXIT.ENVIRONMENT;
+  }
+  const brief = await deps.brief.get({ api, gameId }).catch(() => null);
+
+  const listed = await resolveFinding(api, gameId, parsed);
+  if (!listed) {
+    log(parsed.findingId
+      ? `No finding ${parsed.findingId} is visible to this token. Run "ravensight-playtest open" to see the findings this game has.`
+      : `Job ${parsed.jobId} has no finding labelled ${parsed.label}.`);
+    return EXIT.ENVIRONMENT;
+  }
+  const sourceJobId = listed.job_id || parsed.jobId || null;
+  const sourceRunId = listed.run_id || null;
+  const evidence = await gatherEvidence({ api, gameId, repoRoot, sourceJobId, sourceRunId, injected, log });
+  // The findings list is a summary; the run's own report.json is where the
+  // 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 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 });
+  if (!checked.ok) {
+    log(checked.reason);
+    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;
+  if (!personaSlug) {
+    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] });
+  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
+    // `price_changed`, which reads as a race rather than as the truth: this
+    // server did not quote a price at all.
+    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)}.`;
+  log(offer);
+  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;
+  }
+  if (estimate.wall_warning) log(estimate.wall_warning);
+  const confirm = injected.confirm || (deps.ui && deps.ui.confirm);
+  if (!options.yes && confirm) {
+    const go = await confirm(offer, { yes: options.yes });
+    if (!go) {
+      log('Nothing was charged and nothing was changed.');
+      return EXIT.CANCELED;
+    }
+  }
+
+  const started = 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();
+  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 });
+  } catch (error) {
+    const handled = explainRegisterRefusal(error, log);
+    if (handled !== null) return handled;
+    throw error;
+  }
+
+  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;
+
+  await mkdir(jobDir(repoRoot, jobId), { recursive: true });
+  const journal = stateFile.newState({
+    jobId,
+    gameId,
+    idempotencyKey,
+    cliVersion,
+    packVersion: pack.pack_version,
+    briefVersion: brief ? brief.version ?? null : null,
+    modules: [...FIX_MODULES],
+    // The driver and the target belong to the verify run, which is the only
+    // run in this job that plays anything.
+    driver: driverName,
+    target: buildTarget,
+    priceCents: registered.price && registered.price.price_cents,
+    options: {
+      branch,
+      baseCommit: checked.head,
+      findingId: finding.finding_id,
+      verify: wantsVerify,
+      allowDirty: Boolean(options.allowDirty),
+      maxActions: options.maxActions ?? null
+    }
+  });
+  for (const entry of registered.runs || []) {
+    journal.runs[entry.run_id] = stateFile.newRunEntry({ runId: entry.run_id, module: entry.module, persona: entry.persona });
+  }
+  await stateFile.save(repoRoot, journal);
+  // The journal and the job id are written before anything can go wrong with
+  // the runs, because the charge has already happened: a developer who cannot
+  // name the job they paid for cannot ask anybody about it either.
+  log(`job ${jobId}: ${formatCents(registered.price && registered.price.price_cents)} charged. ${jobDir(repoRoot, jobId)}`);
+
+  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 });
+    // 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 });
+    return EXIT.FAILED;
+  }
+
+  const directory = runDirFor(repoRoot, jobId, fixRun.run_id);
+  await mkdir(directory, { recursive: true });
+
+  const createClient = injected.createClient || createModelClient;
+  const client = createClient({ apiUrl, token: injected.modelToken || api.token });
+  const ledger = createUsageLedger();
+  const heartbeat = createHeartbeat({
+    api,
+    gameId,
+    jobId,
+    runId: fixRun.run_id,
+    onCancel: () => log('the job was cancelled; stopping.'),
+    onUsage: usage => ledger.recordServerUsage(usage),
+    onError: () => {}
+  });
+  const inFlight = new Map();
+  const interrupt = createInterruptHandler({
+    api,
+    gameId,
+    jobId,
+    repoRoot,
+    journal,
+    inFlight,
+    log,
+    // Not "resume carries on": `resume` replays persona runs, and replaying
+    // 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
+  });
+
+  try {
+    await api.runs.transition(gameId, jobId, fixRun.run_id, 'launching', { reason: '' });
+    await api.runs.transition(gameId, jobId, fixRun.run_id, 'playing', { reason: '' });
+    heartbeat.start();
+    inFlight.set(fixRun.run_id, { state: 'playing' });
+
+    // 1. Is this a bug at all? The cheapest possible "no".
+    const verdict = await api.jobs.fixTriage(gameId, jobId, { finding_id: finding.finding_id });
+    if (verdict && verdict.verdict === null) {
+      // The triage service is off, so nothing was judged. Proceeding is right
+      // (the finding was filed by a persona that was told the design intent),
+      // but the developer should know the check did not happen.
+      log(`Triage could not judge this finding (${verdict.source || 'unavailable'}), so the fix proceeds without it. Read the diff against your own design intent.`);
+    }
+    if (isDesignIntent(verdict)) {
+      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.`);
+      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.');
+      return EXIT.OK;
+    }
+
+    // 2. Plan, then apply.
+    const images = await saveEvidenceImages(directory, evidence.images);
+    const system = fixSystem({
+      skill: fixSkill.content,
+      jobId,
+      branch,
+      baseCommit: checked.head,
+      engine: pack.engine || null
+    });
+    const codeBrief = pack.code_brief || null;
+    // `graph_context` only exists in a bundle asked for with this job's id: it
+    // is assembled from the job's own findings, so the pre-register fetch (which
+    // bought the skills and the price) has it as null. A refetch that fails is
+    // not fatal, it just means planning without the level graph.
+    const graphContext = await jobGraphContext({ deps, api, gameId, jobId, log });
+    const planRepo = createRepoTools({ root: repoRoot, tools: PROFILE_TOOLS });
+    const { plan } = await planFix({
+      client,
+      jobId,
+      runId: fixRun.run_id,
+      system,
+      repo: planRepo,
+      content: planContent({
+        finding: findingForPrompt(finding),
+        reproSteps: reproStepsOf(finding),
+        personaQuote: finding.persona_quote || null,
+        images,
+        intentNotes: intentNotesFor(pack, brief),
+        reportMarkdown: evidence.reportMarkdown,
+        codeBrief,
+        graphContext
+      }),
+      ledger,
+      log
+    });
+    if (plan.hypothesis) log(`hypothesis: ${plan.hypothesis}`);
+
+    const maxActions = resolveFixMaxActions(options, pack);
+    const applied = await applyFix({
+      client,
+      jobId,
+      runId: fixRun.run_id,
+      repoRoot,
+      system,
+      plan,
+      maxActions,
+      codeBrief,
+      graphContext,
+      ledger,
+      log,
+      onProgress: progress => {
+        if (options.verbose) {
+          log(`  ${progress.tool} ${progress.target || ''} (${progress.resultChars} chars${progress.isError ? ', error' : ''}${progress.repeat ? ', repeat' : ''})`);
+        }
+        // A local transcript of the apply loop: which tools, on what, how much
+        // came back. Never uploaded; it is how a fix that wrote nothing gets
+        // explained afterwards, which the first production attempt could not be.
+        appendFile(path.join(directory, 'transcript.jsonl'), `${JSON.stringify({ at: new Date().toISOString(), ...progress })}\n`).catch(() => {});
+      },
+      shouldStop: () => interrupt.signalled || heartbeat.canceled
+    });
+
+    // A Ctrl-C, or the job cancelled from the dashboard. Either way this run is
+    // over, and it is abandoned rather than left `interrupted`: `resume` only
+    // knows how to replay persona runs, so a fix run parked in a resumable
+    // state is a promise nothing can keep. The edits stay on the branch, which
+    // is where the developer can read them, and the unit goes back.
+    if (interrupt.signalled || heartbeat.canceled || applied.stop === 'interrupted') {
+      heartbeat.stop();
+      inFlight.delete(fixRun.run_id);
+      const why = interrupt.signalled ? 'interrupted by the developer' : 'cancelled';
+      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.`);
+      return EXIT.CANCELED;
+    }
+
+    // 3. Did anything change? If not, say so and give the money back.
+    const changed = await git.diffStat();
+    if (changed.length === 0) {
+      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.`);
+      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.');
+      return EXIT.OK;
+    }
+
+    const files = changed.slice(0, MAX_CHANGESET_FILES);
+    if (changed.length > files.length) {
+      log(`${changed.length} files changed and a changeset carries at most ${MAX_CHANGESET_FILES}, so the changeset lists the first ${MAX_CHANGESET_FILES}. The branch has all of them.`);
+    }
+
+    // 4. Verify, by replaying the finding against the build.
+    let verified = null;
+    if (wantsVerify && verifyRun) {
+      verified = await runVerify({
+        deps,
+        api,
+        client,
+        gameId,
+        jobId,
+        repoRoot,
+        entry: verifyRun,
+        pack,
+        finding,
+        driverName,
+        target: buildTarget,
+        options,
+        journal,
+        maxActions: Math.min(VERIFY_MAX_ACTIONS, maxActions),
+        makeDriver: injected.driverFactory || createDriver,
+        log
+      });
+    } else {
+      await skipRun({ api, gameId, jobId, run: verifyRun, reason: wantsVerify ? 'no verify run was registered' : 'skipped with --no-verify', log });
+    }
+
+    // 5. The pull request text, from the diff that exists.
+    const fallback = localSummary({ finding, plan, files, 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
+    // spend on it.
+    const budgetTouched = applied.stop === 'budget' || applied.stop === 'budget_warning';
+    const summary = applied.stop === 'budget'
+      ? { ...fallback, source: 'local' }
+      : await summariseFix({
+        client,
+        jobId,
+        runId: fixRun.run_id,
+        system,
+        finding: findingForPrompt(finding),
+        plan,
+        files,
+        verify: verified,
+        branch,
+        fallback,
+        ledger,
+        log
+      });
+
+    const changeset = {
+      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,
+      pr_title: summary.prTitle,
+      pr_body: summary.prBody
+    };
+
+    await heartbeat.beat();
+    heartbeat.stop();
+    inFlight.delete(fixRun.run_id);
+    const reportPath = await writeChangeset(directory, changeset);
+    await writeUsageFile(directory, ledger);
+
+    await api.runs.transition(gameId, jobId, fixRun.run_id, 'reporting', { reason: '' });
+    await api.runs.transition(gameId, jobId, fixRun.run_id, 'uploading', { reason: '' });
+    try {
+      await deps.finalizeRun(directory, {
+        api,
+        gameId,
+        jobId,
+        runId: fixRun.run_id,
+        // Exactly the three files this run produced. Screenshots copied from
+        // the run that found the bug are evidence for the model, not something
+        // to upload a second time.
+        allowedPaths: [CHANGESET_FILE, RUN_FILES.reportMd, RUN_FILES.usageJson],
+        body: { state: 'succeeded', changeset }
+      });
+      await stateFile.patchRun(repoRoot, journal, fixRun.run_id, { state: 'succeeded', uploaded: true, completed: true, report_written: true });
+    } catch (error) {
+      log(`The changeset could not be uploaded (${String(error && error.message)}). It is in ${directory} and "ravensight-playtest upload ${jobId}" can retry it.`);
+      // 422 `invalid_changeset` carries per-field pointers, and they are the
+      // 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 });
+    // 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;
+  } 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 settle({ api, gameId, jobId, repoRoot, journal, reason: 'the fix failed', log });
+    return code;
+  } finally {
+    interrupt.release();
+  }
+}
+
+/**
+ * The finding, by label inside one job or by id across the game.
+ *
+ * @param {Object} api
+ * @param {string} gameId
+ * @param {{jobId: string|null, label: string|null, findingId: string|null}} target
+ * @returns {Promise<Object|null>}
+ */
+export async function resolveFinding(api, gameId, target) {
+  const answer = await api.jobs.findings(gameId, target.jobId ? { job: target.jobId } : {});
+  const list = (answer && answer.findings) || [];
+  if (target.findingId) return list.find(entry => entry.finding_id === target.findingId) || null;
+  const wanted = String(target.label).toLowerCase();
+  return list.find(entry => String(entry.label || '').toLowerCase() === wanted) || null;
+}
+
+/**
+ * Fill in what the findings list left out from the run's own report.
+ *
+ * `GET /findings` answers a list for a dashboard, so it may carry a title and
+ * a severity and nothing else. The report the persona wrote is where the repro
+ * steps, the quote and the cited evidence live, and those are most of what the
+ * plan step has to work from. The listed record still wins on every field it
+ * does have: it is the one the server considers current.
+ *
+ * @param {Object} listed
+ * @param {Object|null} reportJson
+ * @returns {Object}
+ */
+export function enrichFinding(listed, reportJson) {
+  const findings = (reportJson && Array.isArray(reportJson.findings) ? reportJson.findings : []);
+  const match = findings.find(entry => entry
+    && (entry.finding_id === listed.finding_id
+      || (entry.label && listed.label && String(entry.label).toLowerCase() === String(listed.label).toLowerCase())));
+  if (!match) return listed;
+  const merged = { ...match };
+  for (const [key, value] of Object.entries(listed)) {
+    if (value !== null && value !== undefined && !(Array.isArray(value) && value.length === 0)) merged[key] = value;
+  }
+  return merged;
+}
+
+/**
+ * @param {Object|null} verdict
+ * @returns {boolean}
+ */
+export function isDesignIntent(verdict) {
+  if (!verdict || verdict.verdict !== 'design_intent') return false;
+  const confidence = Number(verdict.confidence);
+  return Number.isFinite(confidence) && confidence >= DESIGN_INTENT_CONFIDENCE;
+}
+
+/**
+ * The report and the screenshots behind the finding.
+ *
+ * Screenshots come from the local run directory when this machine is the one
+ * that played the job, which is the usual case and costs nothing. Otherwise
+ * they come from the presigned artifact URLs, which is what makes `fix` usable
+ * from a different machine than the run. Either way at most two are taken,
+ * because that is the plan step's image ceiling.
+ *
+ * @returns {Promise<{reportMarkdown: string|null, reportJson: Object|null, images: Array}>}
+ */
+export async function gatherEvidence({ api, gameId, repoRoot, sourceJobId, sourceRunId, injected = {}, log = () => {} }) {
+  const out = { reportMarkdown: null, reportJson: null, images: [] };
+  if (!sourceJobId || !sourceRunId) return out;
+
+  try {
+    out.reportMarkdown = String(await api.runs.report(gameId, sourceJobId, sourceRunId, 'md'));
+  } catch {
+    log('The run report for that finding could not be read, so the fix works from the finding alone.');
+  }
+  try {
+    const body = await api.runs.report(gameId, sourceJobId, sourceRunId, 'json');
+    out.reportJson = typeof body === 'string' ? JSON.parse(body) : body;
+  } catch {
+    // The markdown is the part the plan step reads; the JSON is a bonus.
+  }
+
+  const local = screenshotsDir(runDirFor(repoRoot, sourceJobId, sourceRunId));
+  try {
+    const names = (await readdir(local)).filter(isImageName).sort().slice(0, MAX_PLAN_IMAGES);
+    for (const name of names) {
+      out.images.push({ name, mediaType: mediaTypeFor(name), base64: (await readFile(path.join(local, name))).toString('base64') });
+    }
+  } catch {
+    // No local run directory: this machine did not play that job.
+  }
+  if (out.images.length > 0) return out;
+
+  const fetchImpl = injected.fetch || globalThis.fetch;
+  if (!fetchImpl) return out;
+  try {
+    const answer = await api.jobs.artifacts(gameId, sourceJobId);
+    const wanted = (answer && answer.artifacts ? answer.artifacts : [])
+      // The server answers every artifact of the job, so the run has to be
+      // matched, and the content type is what says an artifact is an image: a
+      // report is not, whatever its path looks like.
+      .filter(entry => entry && entry.url && entry.run_id === sourceRunId)
+      .filter(entry => String(entry.content_type || '').startsWith('image/') || isImageName(String(entry.path || '')))
+      .slice(0, MAX_PLAN_IMAGES);
+    for (const entry of wanted) {
+      const response = await fetchImpl(entry.url);
+      if (!response || !response.ok) continue;
+      const body = Buffer.from(await response.arrayBuffer());
+      out.images.push({ name: path.basename(String(entry.path)), mediaType: mediaTypeFor(String(entry.path)), base64: body.toString('base64') });
+    }
+  } catch {
+    log('The screenshots behind that finding could not be fetched, so the fix works from the text alone.');
+  }
+  return out;
+}
+
+/**
+ * Put the evidence images in the fix run directory, so what the model was
+ * shown is on disk next to what it produced.
+ *
+ * @param {string} directory the fix run directory
+ * @param {Array<Object>} images
+ * @returns {Promise<Array<Object>>} the images, unchanged
+ */
+export async function saveEvidenceImages(directory, images) {
+  if (images.length === 0) return images;
+  const target = screenshotsDir(directory);
+  await mkdir(target, { recursive: true });
+  for (const image of images) {
+    await writeFile(path.join(target, image.name), Buffer.from(image.base64, 'base64'));
+  }
+  return images;
+}
+
+/**
+ * Replay the finding on the build, as an ordinary persona run whose brief
+ * starts with the one thing it is being asked to do.
+ *
+ * Unlike `run`, this emits no synthetic telemetry: a verify run is one
+ * question asked of a build that only exists on this machine, and putting its
+ * session into the game's event stream would count a private replay as
+ * playtest traffic.
+ *
+ * @returns {Promise<{run_id: string, reproduced: number|null, source: string|null}|null>}
+ */
+export async function runVerify({
+  deps,
+  api,
+  client,
+  gameId,
+  jobId,
+  repoRoot,
+  entry,
+  pack,
+  finding,
+  driverName,
+  target,
+  options,
+  journal,
+  maxActions,
+  makeDriver,
+  log
+}) {
+  const directory = runDirFor(repoRoot, jobId, entry.run_id);
+  await mkdir(directory, { recursive: true });
+  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, { headless });
+  const ledger = createUsageLedger();
+  const heartbeat = createHeartbeat({
+    api,
+    gameId,
+    jobId,
+    runId: entry.run_id,
+    onUsage: usage => ledger.recordServerUsage(usage),
+    onError: () => {}
+  });
+  heartbeat.start();
+
+  let outcome;
+  try {
+    outcome = await runPersona({
+      client,
+      api,
+      gameId,
+      jobId,
+      runId: entry.run_id,
+      persona,
+      module: 'persona_playtest',
+      driver,
+      driverName,
+      target,
+      runDirectory: directory,
+      skill: skillFor(pack, 'persona_playtest'),
+      brief: verifyBrief(pack.brief || null, finding),
+      intentNotes: pack.intent_notes || [],
+      schemas: pack.schemas || [],
+      maxActions,
+      heartbeat,
+      ledger,
+      log: message => log(`verify: ${message}`)
+    });
+  } catch (error) {
+    heartbeat.stop();
+    const failed = error.outcome || { state: 'failed', quitReason: 'error', actionsTaken: 0, report: null, reportLint: [], reachedState: 'playing' };
+    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;
+  }
+  heartbeat.stop();
+
+  await stateFile.patchRun(repoRoot, journal, entry.run_id, {
+    state: outcome.state,
+    actions_taken: outcome.actionsTaken,
+    quit_reason: outcome.quitReason,
+    report_written: Boolean(outcome.report),
+    budget_warned: outcome.budgetWarned
+  });
+  await deliver({ deps, api, gameId, jobId, runId: entry.run_id, directory, outcome, options, log, journal, repoRoot });
+
+  // The verdict is the server's: it reads the verify run's own report against
+  // the finding, which is judgement the CLI has no business making locally.
+  let run = null;
+  try {
+    const answer = await api.runs.get(gameId, jobId, entry.run_id);
+    run = (answer && (answer.run || answer)) || null;
+  } catch (error) {
+    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;
+  return { run_id: entry.run_id, reproduced, source: (verdict && verdict.source) || null };
+}
+
+/**
+ * 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
+ * thing this run exists for.
+ *
+ * @param {Object|null} base
+ * @param {Object} finding
+ * @returns {Object}
+ */
+export function verifyBrief(base, finding) {
+  const fields = (base && base.fields) || {};
+  return {
+    ...(base || {}),
+    fields: {
+      verify_task: `Reproduce ${finding.label || finding.finding_id}: ${finding.title || 'the finding'}`,
+      verify_repro_steps: reproStepsOf(finding),
+      verify_instruction: 'Try these steps first and say plainly whether the problem still happens. Then play as you normally would.',
+      ...fields
+    }
+  };
+}
+
+/**
+ * What the pull request says when the model could not say it: no budget left,
+ * or an answer with no JSON in it. It is deliberately plain, and it says which
+ * parts are unknown rather than guessing at them.
+ *
+ * @returns {{prTitle: string, prBody: string}}
+ */
+export function localSummary({ finding, plan, files, verify, branch, applied = {} }) {
+  const label = finding.label || finding.finding_id;
+  const body = [
+    `# Fix ${label}: ${finding.title || 'a playtest finding'}`,
+    '',
+    '## What was wrong',
+    finding.title ? `${finding.title}${finding.severity ? ` (${finding.severity})` : ''}` : 'See the finding in the dashboard.',
+    plan.hypothesis ? `\n${plan.hypothesis}` : '',
+    '',
+    '## What changed',
+    ...files.map(file => `- \`${file.path}\`: +${file.additions} -${file.deletions}`),
+    '',
+    '## Verify',
+    verifyWords(verify),
+    '',
+    '## What the reviewer should check',
+    'This summary was written locally rather than by the model, so read the diff before trusting the description above.',
+    applied.stop === 'budget' || applied.stop === 'budget_warning'
+      ? 'The fix stopped early because its model budget was spent or nearly spent, so it may be incomplete.'
+      : '',
+    '',
+    `Branch: ${branch}`,
+    ''
+  ].filter(line => line !== '').join('\n');
+  return { prTitle: `Fix ${label}: ${(finding.title || 'a playtest finding').slice(0, 100)}`, prBody: body };
+}
+
+/**
+ * Write `changeset.json` and `report.md`, scanning both first.
+ *
+ * The scan is not a formality: the pull request body is written by a model
+ * that has just been reading source files, and a key quoted into it would be
+ * uploaded and then pasted into a pull request.
+ *
+ * @param {string} directory
+ * @param {Object} changeset
+ * @returns {Promise<string>} the path to report.md
+ */
+export async function writeChangeset(directory, changeset) {
+  const json = `${JSON.stringify(changeset, null, 2)}\n`;
+  const markdown = `${String(changeset.pr_body || '').trimEnd()}\n`;
+  assertNoSecrets(CHANGESET_FILE, json);
+  assertNoSecrets(RUN_FILES.reportMd, markdown);
+  await writeFile(path.join(directory, CHANGESET_FILE), json, 'utf8');
+  const reportPath = path.join(directory, RUN_FILES.reportMd);
+  await writeFile(reportPath, markdown, 'utf8');
+  return reportPath;
+}
+
+/** What the developer reads at the end, or the changeset when `--json`. */
+function report({ changeset, reportPath, verified, options, log, injected, deps, budget }) {
+  if (options.json) {
+    const emit = injected.emitJson || (deps.ui && deps.ui.json ? value => deps.ui.json(value) : value => console.log(JSON.stringify(value, null, 2)));
+    emit(changeset);
+    return;
+  }
+  log(`branch ${changeset.branch}`);
+  for (const file of changeset.files) log(`  ${file.path} +${file.additions} -${file.deletions}`);
+  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}`);
+}
+
+/**
+ * Complete the fix run, tolerating a refusal. The money is settled by
+ * `finish` either way, and a refused complete must not turn a fix that worked
+ * into a crash.
+ */
+async function completeFixRun({ api, gameId, jobId, runId, body, log }) {
+  try {
+    await api.runs.complete(gameId, jobId, runId, body);
+  } catch (error) {
+    log(`the fix run could not be completed (${String(error && error.message)}); the hourly sweep will settle it.`);
+  }
+}
+
+async function failFixRun({ api, gameId, jobId, runId, log }) {
+  await completeFixRun({ api, gameId, jobId, runId, body: { state: 'failed', reason: 'error' }, log });
+}
+
+/**
+ * A run this job paid for and never played. Saying so is what gets it
+ * refunded now rather than by the stall sweep half an hour later.
+ */
+async function skipRun({ api, gameId, jobId, run, reason, log }) {
+  if (!run) return;
+  try {
+    await api.runs.transition(gameId, jobId, run.run_id, 'skipped', { reason });
+  } catch (error) {
+    log(`the verify run could not be marked skipped (${String(error && error.message)}).`);
+  }
+}
+
+/** `finish` settles the job once and issues at most one refund. */
+async function settle({ api, gameId, jobId, repoRoot, journal, reason, log }) {
+  try {
+    const finished = await api.jobs.finish(gameId, jobId, { reason });
+    log(`job ${jobId} ${finished.job ? finished.job.state : 'finished'}: refunded ${formatCents(finished.refunded_cents)}.`);
+  } catch (error) {
+    log(`the job could not be settled now; the hourly sweep will settle it: ${String(error && error.message)}`);
+  }
+  journal.finished = true;
+  try {
+    await stateFile.save(repoRoot, journal);
+  } catch {
+    // The journal is a convenience at this point: the server's ledger is the
+    // record of what was charged and what came back.
+  }
+}
+
+/** The finding as the prompt sees it: no ids nobody can act on, no noise. */
+export function findingForPrompt(finding) {
+  return {
+    finding_id: finding.finding_id,
+    label: finding.label || null,
+    title: finding.title || null,
+    severity: finding.severity || null,
+    kind: finding.kind || null,
+    description: finding.description || null,
+    expected: finding.expected || null,
+    actual: finding.actual || null,
+    evidence: finding.evidence || null
+  };
+}
+
+/**
+ * @param {Object} finding
+ * @returns {Array<string>}
+ */
+export function reproStepsOf(finding) {
+  const steps = finding.repro_steps ?? finding.repro ?? null;
+  if (Array.isArray(steps)) return steps.map(step => (typeof step === 'string' ? step : String(step && step.text ? step.text : JSON.stringify(step)))).filter(Boolean);
+  if (typeof steps === 'string' && steps.trim()) return steps.split('\n').map(line => line.trim()).filter(Boolean);
+  return [];
+}
+
+/**
+ * Design intent comes from the pack and from the brief, and both are binding:
+ * a fix that "fixes" something the developer meant is worse than no fix.
+ *
+ * @param {Object} pack
+ * @param {Object|null} brief
+ * @returns {Array<string>}
+ */
+export function intentNotesFor(pack, brief) {
+  const fromBrief = ((brief && brief.fields && brief.fields.design_intent_notes) || []).map(note => (typeof note === 'string' ? note : note && note.text)).filter(Boolean);
+  const fromPack = (pack.intent_notes || []).map(note => (typeof note === 'string' ? note : note && note.text)).filter(Boolean);
+  return [...fromBrief, ...fromPack];
+}
+
+/**
+ * The level graph for this job, or null.
+ *
+ * @returns {Promise<Object|null>}
+ */
+export async function jobGraphContext({ deps, api, gameId, jobId, log = () => {} }) {
+  try {
+    const bundle = await deps.packs.get({ api, gameId, modules: PACK_MODULES, jobId });
+    return (bundle && bundle.graph_context) || null;
+  } catch (error) {
+    log(`The level graph for this job could not be read (${String(error && error.message)}), so the plan is made without it.`);
+    return null;
+  }
+}
+
+/**
+ * The server's per-field reasons for refusing a changeset, as lines.
+ *
+ * @param {any} error
+ * @returns {Array<string>}
+ */
+export function changesetDetails(error) {
+  if (!error || error.code !== 'invalid_changeset') return [];
+  const details = (error.body && error.body.details) || error.details || [];
+  return (Array.isArray(details) ? details : [])
+    .map(detail => [detail.instancePath, detail.code, detail.message].filter(Boolean).join(': '))
+    .filter(Boolean);
+}
+
+function isImageName(name) {
+  return /\.(png|jpe?g|webp)$/i.test(String(name));
+}
+
+function mediaTypeFor(name) {
+  if (/\.jpe?g$/i.test(name)) return 'image/jpeg';
+  if (/\.webp$/i.test(name)) return 'image/webp';
+  return 'image/png';
+}
+
+export default fixCommand;