ravensight-playtest 0.5.2 → 0.6.0

package/src/commands/feature.js

@@ -0,0 +1,845 @@
+import { execFile } from 'node:child_process';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import { prepareAssets } from '../assets/index.js';
+import { capabilityLive } from '../run/acceptance.js';
+import { checkResultText, createCheckRunner, withRunCheck } from '../run/checks.js';
+import { getDeps } from '../run/deps.js';
+import { DIMENSION_3D, dimensionGate, isThreeDRoot, mainSceneRoot } from '../run/dimension.js';
+import { GodotDriver } from '../run/drivers/godot.js';
+import { inputControls, isGodotProject } from '../run/drivers/godot-project.js';
+import EXIT from '../run/exit.js';
+import {
+  applyFeature, eventsInChange, featureEvidence, featurePlanContent, featureSystem, localFeatureSummary,
+  MAX_FEATURE_ACTIONS, maxWritesForSize, planFeature, scenarioBrief, summariseFeature
+} from '../run/featureLoop.js';
+import { abandonBranch, createGit, preflight, startBranch } from '../run/git.js';
+import { createHeartbeat } from '../run/heartbeat.js';
+import { createModelClient } from '../run/model.js';
+import { openPullRequest, shellQuote } from '../run/openPr.js';
+import { jobDir, runDir as runDirFor, RUN_FILES } from '../run/paths.js';
+import { checkoutRef, cleanCommit, replayTrace } from '../run/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 { withEvidenceIntact } from '../run/evidence.js';
+import { assertNoSecrets, withoutQuotedSecrets } from '../run/secretScan.js';
+import * as pendingRegister from '../run/pendingRegister.js';
+import * as stateFile from '../run/state.js';
+import { seedFrom } from '../run/trace.js';
+import { createUsageLedger, writeUsageFile } from '../run/usage.js';
+import { unknownPersonaMessage, unknownPersonas } from '../runDefaults.js';
+import { loadLocalBrief } from '../briefLocal.js';
+import { changesetDetails, projectRelative, runGateChecks } from './fix.js';
+import { createInterruptHandler, explainRegisterRefusal, exitCodeFor, formatCents, godotRefusal, playJob, resolvePersonas, resolveSetup, startBalanceLine, startBalanceShort } from './run.js';
+import { replayReport, replaySentence } from './replay.js';
+import { bootProblem } from './validate.js';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * `ravensight-playtest feature`: Build a feature (Labs beta).
+ *
+ * Given a brief, it asks the server for a specification, one AI unit, and stops:
+ * a person reads, edits and approves that in the dashboard before any code is
+ * bought. Given an approved specification's id, it buys the job and builds it on
+ * a new branch, on this machine:
+ *
+ *   plan -> apply (write tools and named checks, 40 files) -> the checks ->
+ *   a persona plays each of the spec's test scenarios -> summarize
+ *
+ * with at most two repairs, started by a failed check or a failed scenario. The
+ * specification the server froze at register is the only definition of done.
+ *
+ * Whether it was verified is the server's answer from its own run rows; this
+ * command prints it and never words it more strongly. It never pushes, except
+ * `--open-pr` after a verified feature and a yes at a prompt.
+ */
+
+const CAPABILITY = 'feature';
+export const FEATURE_MODULES = Object.freeze(['feature']);
+export const PACK_MODULES = Object.freeze(['feature', 'persona_playtest']);
+export const CHANGESET_FILE = 'changeset.json';
+export const MAX_REPAIRS = 2;
+export const REPAIR_MAX_ACTIONS = 30;
+const SPEC_ID = /^[a-f0-9]{24}$/i;
+const ALPHA_3D_LINE = '3D Alpha: a proof of concept on one template. It is priced as any feature is, a real model on 3D is unmeasured, and a persona plays with keys and input actions, never mouse look.';
+const LABS_OFF = 'Build a feature is part of Ravensight Labs (beta), and it is not on for this game. Turn Labs on from the Labs page in the dashboard. Nothing was charged.';
+
+/**
+ * @param {string} target a brief, or an approved specification's id
+ * @param {Object} flags
+ * @param {Object} [injected] test seam
+ * @returns {Promise<number>} an exit code
+ */
+export async function featureCommand(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 {
+    const value = String(target || '').trim();
+    if (!value) {
+      log('Say what to build, in quotes, or name an approved specification\'s id.');
+      return EXIT.ENVIRONMENT;
+    }
+    const options = {
+      apiUrl: flags.apiUrl, repo: flags.repoRoot, game: flags.game, yes: flags.yes, headless: flags.headless === true,
+      godotPath: flags.godotPath, personas: flags.personas, uploadTrace: true, skipAggregate: true, concurrency: 1, verbose: flags.verbose
+    };
+    const setup = await resolveSetup(deps, options, log);
+    if (setup.code !== undefined) return setup.code;
+
+    let labs = null;
+    try { labs = await setup.api.labs.get(setup.gameId); } catch { labs = null; }
+    if (!capabilityLive(labs, CAPABILITY)) {
+      log(LABS_OFF);
+      return EXIT.ENVIRONMENT;
+    }
+    return SPEC_ID.test(value)
+      ? await build(value, flags, options, setup, injected, deps, log)
+      : await writeSpec(value, flags, setup, 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;
+  }
+}
+
+/** Ask for a specification and stop. A person approves it in the dashboard. */
+async function writeSpec(brief, flags, setup, injected, deps, log) {
+  const { api, gameId, repoRoot, context } = setup;
+  // Free, before the unit: a specification is written for the kind of game this is.
+  const projectDir = path.resolve(repoRoot || '.', flags.godotProject || context?.config?.godot_project || '.');
+  const { refusal, dimension } = await dimensionGate({ projectDir, alpha3d: Boolean(flags.alpha3d), name: 'Build a feature' });
+  if (refusal) {
+    log(`${refusal} Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+  if (dimension === DIMENSION_3D) log(ALPHA_3D_LINE);
+  const offer = 'Writing a specification is one AI unit. A brief bigger than a large feature is declined and costs nothing.';
+  log(offer);
+  const confirm = injected.confirm || (deps.ui && deps.ui.confirm);
+  if (!flags.yes && confirm && !await confirm('Write the specification?', { yes: flags.yes })) {
+    log('Nothing was charged.');
+    return EXIT.CANCELED;
+  }
+  let spec;
+  try {
+    ({ spec } = await api.labs.featureSpecs.create(gameId, brief, dimension === DIMENSION_3D ? { dimension } : {}));
+  } catch (error) {
+    if (error && /^feature_(too_large|out_of_scope|not_2d)$/.test(String(error.code))) {
+      log(`Declined: ${error.message} Nothing was charged.`);
+      return EXIT.ENVIRONMENT;
+    }
+    throw error;
+  }
+  log(`Specification ${spec.spec_id}: ${spec.title} (${spec.size}).`);
+  for (const line of specLines(spec.spec)) log(line);
+  log('Read it, edit it and approve it on the Labs page in the dashboard. Then build it with:');
+  log(`  npx ravensight-playtest feature ${spec.spec_id}${dimension === DIMENSION_3D ? ' --alpha-3d' : ''}`);
+  if (flags.json) (deps.ui && deps.ui.json ? deps.ui.json : value => console.log(JSON.stringify(value)))(spec);
+  return EXIT.OK;
+}
+
+function specLines(spec) {
+  return [
+    `  requirements: ${spec.requirements.length}, acceptance criteria: ${spec.acceptance_criteria.length}, proposed files: ${spec.proposed_files.length}`,
+    `  test scenarios: ${spec.test_scenarios.map(scenario => scenario.title).join('; ')}`,
+    ...(spec.placeholders.length ? [`  placeholders: ${spec.placeholders.join('; ')}`] : [])
+  ];
+}
+
+/**
+ * Why a project is not one Build a feature can work on at launch: it has to be a
+ * 2D Godot project. Reads the main scene's root node, which is what decides what
+ * a player sees. A project with no readable main scene is let through, because
+ * the boot check that follows answers that one properly.
+ *
+ * @param {string} projectDir
+ * @returns {Promise<string|null>} the refusal, or null
+ */
+export async function notTwoD(projectDir) {
+  if (!await isGodotProject(projectDir)) return 'There is no Godot project here, and Build a feature works on Godot projects.';
+  const root = await mainSceneRoot(projectDir);
+  return isThreeDRoot(root)
+    ? `The main scene's root is a ${root}. Build a feature works on 2D Godot projects for now.`
+    : null;
+}
+
+export function featureBranchName(title, suffix = () => randomBytes(3).toString('hex')) {
+  const slug = String(title || 'feature').toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'feature';
+  return `ravensight/feature-${slug}-${suffix()}`;
+}
+
+/**
+ * The whole job: everything up to the charge refuses for free. Exported for
+ * `create`, whose every milestone is one of these against its own scaffold, with
+ * `flags.prototype` naming the plan and the whole budget confirmed up front.
+ */
+export async function buildFeature(specId, flags, options, setup, injected, deps, log) {
+  return build(specId, flags, options, setup, injected, deps, log);
+}
+
+async function build(specId, flags, options, setup, injected, deps, log) {
+  const { context, api, gameId, apiUrl, repoRoot, cliVersion } = setup;
+
+  let loaded;
+  try {
+    loaded = await api.labs.featureSpecs.get(gameId, specId);
+  } catch (error) {
+    if (error && error.status === 404) {
+      log(`There is no specification ${specId} for this game. Nothing was charged.`);
+      return EXIT.ENVIRONMENT;
+    }
+    throw error;
+  }
+  const specRow = loaded.spec;
+  if (specRow.status !== 'approved') {
+    log(`${specRow.title} has not been approved. Read it and approve it on the Labs page in the dashboard first. Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+
+  const projectDir = path.resolve(repoRoot, flags.godotProject || context.config?.godot_project || '.');
+  const subdir = path.relative(repoRoot, projectDir);
+  if (subdir.startsWith('..')) {
+    log('The Godot project has to be inside this repository. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+  if (!await isGodotProject(projectDir)) {
+    log('There is no project.godot here. Pass --godot-project with the project\'s directory. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+  const { refusal, dimension } = await dimensionGate({ projectDir, alpha3d: Boolean(flags.alpha3d), name: 'Build a feature' });
+  if (refusal) {
+    log(`${refusal} Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+  // A specification was written for 2D or for 3D, and the two read differently.
+  if ((specRow.dimension || '2d') !== dimension) {
+    log(`This specification was written for a ${(specRow.dimension || '2d').toUpperCase()} game and this project is ${dimension.toUpperCase()}. Write one for this project. Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+  if (dimension === DIMENSION_3D) log(ALPHA_3D_LINE);
+
+  const noGodot = await godotRefusal({ driverName: 'godot_driver', godotPath: flags.godotPath, projectDir, injected: { detectGodot: injected.detectGodot, driverFactory: injected.driverFactory || injected.checkRunner || injected.playJob } });
+  if (noGodot) {
+    log(noGodot);
+    return EXIT.ENVIRONMENT;
+  }
+
+  // Free, before a price: a folder that was named has to be usable.
+  const assets = await prepareAssets({ repoRoot, projectDir, folder: flags.assetsDir || context.config?.assets_dir, dimension });
+  if (!assets.ok) {
+    log(`${assets.reason} Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+
+  // The base has to be a clean commit, because the branch and the diff are the
+  // deliverable, and a tree with other work in it would blur what this job did.
+  const baseCommit = await (injected.cleanCommit || cleanCommit)(repoRoot);
+  if (!baseCommit) {
+    log('This working tree has uncommitted changes. Commit or stash them first, so the branch holds only this feature. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+  const pendingScope = { kind: 'feature', gameId, target: `${specId}:${flags.prototype || ''}` };
+  const pendingRequest = await pendingRegister.load(repoRoot, pendingScope);
+  const branch = pendingRequest ? pendingRequest.branch : flags.branch || featureBranchName(specRow.spec.title);
+  const git = injected.git || createGit({ root: repoRoot });
+  const checked = await preflight({ git, branch, allowDirty: false, create: false, reuseBranch: Boolean(pendingRequest) });
+  if (!checked.ok) {
+    log(`${checked.reason} Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+  if (pendingRequest) {
+    log(`The last attempt at this feature 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;
+  }
+
+  const pack = await deps.packs.get({ api, gameId, modules: PACK_MODULES });
+  const skill = (pack.skills || []).find(entry => entry.module === 'feature');
+  if (!skill || !(pack.skills || []).some(entry => entry.module === 'persona_playtest')) {
+    log('The content pack does not have this module. Update the server and CLI together. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+  const brief = await deps.brief.get({ api, gameId });
+  if (!brief || brief.status !== 'complete') {
+    log('The scenarios are played by personas, which need a complete expectations brief. Run "ravensight-playtest brief" first. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+  const scenarioCount = specRow.spec.test_scenarios.length;
+  const personaSlugs = resolvePersonas({ personas: flags.personas }, context.config, pack).slice(0, scenarioCount);
+  const unknown = unknownPersonas(personaSlugs, pack.personas || []);
+  if (unknown.length > 0) {
+    log(`${unknownPersonaMessage(unknown, pack.personas || [])} Nothing was registered or charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+  const personas = personaSlugs.map(slug => (pack.personas || []).find(persona => persona.slug === slug));
+
+  // Free, before a price: a project that does not start today is not one a job
+  // can be judged on. Extracted to a temp directory, so this checkout is untouched.
+  log('Checking that the project imports and starts. This costs nothing.');
+  const makeProbe = injected.makeDriver || (driverOptions => new GodotDriver(driverOptions));
+  let baseCheckout = null;
+  try {
+    baseCheckout = await (injected.checkoutRef || checkoutRef)({ repoRoot, ref: baseCommit, projectSubdir: subdir, godotPath: flags.godotPath });
+    const problem = await bootProblem(baseCheckout, { godotPath: flags.godotPath, makeDriver: makeProbe, headless: true });
+    if (problem) {
+      log(`This commit does not start: ${problem}`);
+      log('Nothing was charged.');
+      return EXIT.FAILED;
+    }
+  } catch (error) {
+    log(`${String(error && error.message)} Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  } finally {
+    await baseCheckout?.cleanup();
+  }
+
+  // A stop that came while the free checks ran: nothing has been charged, so it stays that way.
+  if (flags.shouldStop && flags.shouldStop()) {
+    log('Stopped before anything was charged.');
+    return EXIT.CANCELED;
+  }
+  const featureRef = { spec_id: specId, ...(flags.prototype ? { prototype: flags.prototype } : {}) };
+  const estimate = await api.jobs.estimate(gameId, { modules: [...FEATURE_MODULES], personas: personaSlugs, feature: featureRef });
+  const priceCents = Number(estimate.estimate_cents);
+  if (!Number.isFinite(priceCents) || priceCents <= 0 || !Array.isArray(estimate.breakdown)) {
+    log('This server did not quote this job. Update the server and CLI together. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+  const lines = estimate.breakdown.map(line => `${line.count} x ${line.unit} at ${formatCents(line.unit_cents)}`).join(', ');
+  log(`${specRow.spec.title} (${specRow.size}): ${formatCents(priceCents)} for the whole plan (${lines}). Balance: ${formatCents(estimate.balance_cents)}.`);
+  log(`It writes at most ${maxWritesForSize(specRow.size)} files. The whole plan comes back if nothing changes or the change fails its checks, up to three times in any 30 days per account once a job has used model time; past that the feature's own price is kept, and scenario runs that did not play still come back. It is kept once a change is delivered, verified or not. The checks and the scenarios run the edited project on this machine with a reduced environment.`);
+  const floorLine = startBalanceLine(estimate);
+  if (floorLine) log(floorLine);
+  if (estimate.ok === false && floorLine) {
+    log(startBalanceShort(estimate));
+    return EXIT.ENVIRONMENT;
+  }
+  if (estimate.ok === false) {
+    log(`That is more than the balance covers, and the whole plan has to be covered. Top up at ${estimate.topup_url || 'ravensight.io'} and run this again. Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+  const confirm = injected.confirm || (deps.ui && deps.ui.confirm);
+  if (!flags.yes && confirm && !await confirm(`Build this for ${formatCents(priceCents)}?`, { yes: flags.yes })) {
+    log('Nothing was charged and nothing was changed.');
+    return EXIT.CANCELED;
+  }
+
+  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)}.`);
+
+  const idempotencyKey = pendingRequest ? pendingRequest.idempotencyKey : randomUUID();
+  let registered;
+  try {
+    await pendingRegister.save(repoRoot, pendingScope, { idempotencyKey, branch, from: checked.from, head: checked.head });
+    registered = await api.jobs.register(gameId, {
+      modules: [...FEATURE_MODULES],
+      personas: personaSlugs,
+      feature: featureRef,
+      driver: 'godot_driver',
+      cli_version: cliVersion,
+      confirm_price_cents: priceCents,
+      brief_version: brief.version ?? null,
+      build: { kind: 'godot_project', ref: subdir || '.' },
+      repo: { commit: checked.head, dirty: false, branch },
+      pack_versions: { pack: pack.pack_version }
+    }, { idempotencyKey });
+  } catch (error) {
+    // Nobody knows whether a job exists, so the key and the branch are the way back to it.
+    if (pendingRegister.outcomeUnknown(error)) {
+      log(pendingRegister.unknownOutcomeMessage('this feature', branch));
+      return EXIT.ENVIRONMENT;
+    }
+    // Every other way out before a job exists has to leave the developer where they were.
+    await pendingRegister.clear(repoRoot, pendingScope);
+    await abandonBranch({ git, branch, from: checked.from, head: checked.head });
+    if (error && (['labs_not_enabled', 'funding_required', 'feature_spec_not_approved'].includes(error.code) || String(error.code).startsWith('prototype_'))) {
+      log(`${String(error.message)}${error.body?.topup_url ? ` Top up at ${error.body.topup_url}.` : ''}`);
+      return EXIT.ENVIRONMENT;
+    }
+    const handled = explainRegisterRefusal(error, log);
+    if (handled !== null) return handled;
+    throw error;
+  }
+
+  await pendingRegister.clear(repoRoot, pendingScope);
+
+  const jobId = registered.job_id;
+  const frozen = registered.feature;
+  const featureRun = (registered.runs || []).find(entry => entry.module === 'feature');
+  const personaRuns = (registered.runs || []).filter(entry => entry.module === 'persona_playtest');
+  const scenarioRuns = personaRuns.filter(entry => Number.isInteger(entry.feature_scenario));
+  const spareRuns = personaRuns.filter(entry => !Number.isInteger(entry.feature_scenario));
+
+  await mkdir(jobDir(repoRoot, jobId), { recursive: true });
+  const journal = stateFile.newState({
+    jobId, gameId, idempotencyKey, cliVersion,
+    packVersion: pack.pack_version,
+    briefVersion: brief.version ?? null,
+    modules: [...FEATURE_MODULES],
+    driver: 'godot_driver',
+    target: subdir || '.',
+    priceCents: registered.price && registered.price.price_cents,
+    options: { branch, baseCommit: checked.head, specId, labs: 'feature', uploadTrace: true, dimension }
+  });
+  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);
+  log(`job ${jobId}: ${formatCents(registered.price && registered.price.price_cents)} charged. ${jobDir(repoRoot, jobId)}`);
+
+  const skipAll = async (runs, reason) => {
+    for (const entry of runs) {
+      try {
+        await api.runs.transition(gameId, jobId, entry.run_id, 'skipped', { reason });
+      } catch (error) {
+        log(`run ${entry.run_id} could not be marked skipped (${String(error && error.message)}).`);
+      }
+    }
+  };
+  const settle = async reason => {
+    let finished = null;
+    try {
+      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(settleFailureLine(jobId, error));
+    }
+    journal.finished = true;
+    await stateFile.save(repoRoot, journal).catch(() => {});
+    return finished;
+  };
+  // WHAT CAME BACK, FROM THE SERVER'S ANSWER. A job that would be refunded may not be:
+  // the account's limit can keep the unit. So this reads the figure and the reason
+  // and never assumes either. A settle that failed already said so, and claims nothing.
+  const settleAndSay = async reason => {
+    const finished = await settle(reason);
+    if (!finished) return;
+    const cents = Number(finished.refunded_cents) || 0;
+    log(cents > 0
+      ? `${formatCents(cents)} of the ${formatCents(registered.price && registered.price.price_cents)} charged came back.`
+      : `Nothing came back of the ${formatCents(registered.price && registered.price.price_cents)} charged.`);
+    if (finished.refund_limited_note) log(finished.refund_limited_note);
+    const closed = await api.jobs.feature(gameId, jobId).catch(() => null);
+    if (closed && closed.refund_limited_note) log(closed.refund_limited_note);
+  };
+  const complete = async body => {
+    try {
+      await api.runs.complete(gameId, jobId, featureRun.run_id, body);
+    } catch (error) {
+      log(`the feature run could not be completed (${String(error && error.message)}); the hourly sweep will settle it.`);
+    }
+  };
+
+  if (!frozen || !frozen.spec || !featureRun) {
+    log('The server registered this job without its frozen specification, so nothing can be judged. The job is being given back. Update the server and CLI together.');
+    await skipAll(registered.runs || [], 'the job has no frozen specification');
+    await settle('the job has no frozen specification');
+    return EXIT.FAILED;
+  }
+  const spec = frozen.spec;
+
+  const directory = runDirFor(repoRoot, jobId, featureRun.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: featureRun.run_id,
+    onCancel: () => log('the job was cancelled; stopping.'),
+    onUsage: usage => ledger.recordServerUsage(usage),
+    onError: () => {}
+  });
+  const inFlight = new Map();
+  let interrupt = createInterruptHandler({
+    api, gameId, jobId, repoRoot, journal, inFlight, log,
+    message: 'finishing the turn in flight, then stopping. A feature job cannot be resumed, so what did not happen is being given back.',
+    injected
+  });
+  const stopped = () => interrupt.signalled || heartbeat.canceled || Boolean(flags.shouldStop && flags.shouldStop());
+  const abandon = async why => {
+    heartbeat.stop();
+    inFlight.delete(featureRun.run_id);
+    await skipAll(personaRuns.filter(entry => !journal.runs[entry.run_id]?.completed), why);
+    await complete({ state: 'failed', reason: 'error' });
+    await settleAndSay(why);
+    log(`The branch ${branch} holds whatever was written. Nothing was committed or pushed.`);
+  };
+
+  try {
+    await api.runs.transition(gameId, jobId, featureRun.run_id, 'launching', { reason: '' });
+    await api.runs.transition(gameId, jobId, featureRun.run_id, 'playing', { reason: '' });
+    heartbeat.start();
+    inFlight.set(featureRun.run_id, { state: 'playing' });
+
+    // From the size frozen on the job: the server refuses a changeset above it, so
+    // a write past it has to be refused here, where the model can read why.
+    const maxWrites = maxWritesForSize(frozen.size);
+    const system = featureSystem({ skill: skill.content, jobId, branch, baseCommit: checked.head, maxWrites, dimension });
+    const codeBrief = pack.code_brief || null;
+    const { plan } = await planFeature({
+      client, jobId, runId: featureRun.run_id, system,
+      repo: assets.guardRepo(createRepoTools({ root: repoRoot, tools: PROFILE_TOOLS })),
+      content: featurePlanContent({ spec, codeBrief, assetLines: assets.planLines }),
+      ledger, log
+    });
+    if (plan.hypothesis) log(`plan: ${plan.hypothesis}`);
+
+    const maxActions = Math.min(Number.isInteger(flags.maxActions) && flags.maxActions > 0 ? flags.maxActions : MAX_FEATURE_ACTIONS, MAX_FEATURE_ACTIONS);
+    const checks = createCheckRunner({
+      projectDir,
+      godotPath: flags.godotPath || null,
+      allowTests: Boolean(flags.allowTests),
+      allowToolScripts: Boolean(flags.allowToolScripts),
+      changedFiles: async () => projectRelative(await git.diffStat(), repoRoot, projectDir),
+      ...(injected.checkRunner ? injected.checkRunner : {})
+    });
+    const applyRepo = assets.guardRepo(createRepoTools({ root: repoRoot, tools: WRITE_TOOLS, maxWrites }));
+    const assetChecks = assets.bindChecks({
+      checks,
+      changedFiles: async () => projectRelative(await git.diffStat(), repoRoot, projectDir),
+      godotPath: flags.godotPath || null,
+      allowTests: Boolean(flags.allowTests),
+      allowToolScripts: Boolean(flags.allowToolScripts),
+      ...(injected.checkRunner ? injected.checkRunner : {})
+    });
+    const applyArgs = {
+      client, jobId, runId: featureRun.run_id, repoRoot, system, plan, codeBrief, ledger, log, spec,
+      assetInstructions: assets.instructions,
+      dimension,
+      onProgress: progress => {
+        if (flags.verbose) log(`  ${progress.tool} ${progress.target || ''} (${progress.resultChars} chars${progress.isError ? ', error' : ''}${progress.repeat ? ', repeat' : ''})`);
+        appendFile(path.join(directory, 'transcript.jsonl'), `${JSON.stringify({ at: new Date().toISOString(), ...progress })}\n`).catch(() => {});
+      },
+      shouldStop: stopped
+    };
+
+    let applied = await applyFeature({ ...applyArgs, maxActions, repo: assetChecks.withChecks(withRunCheck(applyRepo, checks)) });
+    if (stopped() || applied.stop === 'interrupted') {
+      await abandon('the feature job was interrupted');
+      return EXIT.CANCELED;
+    }
+
+    // NOTHING CHANGED: there is nothing to review, so the whole unit comes back.
+    const changed = await git.diffStat();
+    if (changed.length === 0) {
+      heartbeat.stop();
+      inFlight.delete(featureRun.run_id);
+      log(`Nothing was changed, so there is nothing to review. The branch ${branch} is empty; delete it or stay on it.`);
+      await skipAll(personaRuns, 'nothing was changed');
+      await complete({ state: 'failed', reason: 'no_change' });
+      await settleAndSay('nothing was changed');
+      return EXIT.OK;
+    }
+
+    // Checks after every apply turn set. A failed check starts a repair; passing
+    // checks start the scenarios; a failed scenario starts a repair while a spare
+    // run is left to judge it on. At most MAX_REPAIRS of either, and nothing here
+    // can change what the spec says.
+    let repairs = 0;
+    let checksBlock = false;
+    const pendingScenarios = new Map(scenarioRuns.map(entry => [entry.feature_scenario, entry]));
+    const spares = [...spareRuns];
+    const staleNotes = [];
+    const staleScenarios = new Set();
+    let played = false;
+    let report = null;
+    const runGoAhead = () => repairs < MAX_REPAIRS && applied.stop !== 'budget' && !stopped();
+
+    for (;;) {
+      const gate = await assetChecks.gate(await runGateChecks(checks, log), log);
+      // 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. A failing project test
+      // is a repair while one is left, and after that a risk the report names:
+      // the scenarios still get played.
+      checksBlock = gate.importFailed || gate.assetsBlock || gate.failed.some(result => result.name === 'godot_script_check');
+      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');
+      }
+      if (!(repairReason && runGoAhead()) && !checksBlock) {
+        // Scenarios that passed before this repair: their trace replays free
+        // against the new code. A full match means the answer still stands;
+        // anything else and it cannot be claimed for this code.
+        if (played) {
+          const stale = await rejudgePassed({ report, api, gameId, jobId, repoRoot, projectDir, godotPath: flags.godotPath, replayer: injected.replayer || replayTrace, log });
+          for (const item of stale) {
+            staleScenarios.add(item.index);
+            staleNotes.push(`Scenario "${item.title}" passed before a later repair, and its recorded inputs no longer replay the same on the final code, so it does not count as passed.`);
+          }
+        }
+        const toPlay = [];
+        if (!played) {
+          toPlay.push(...scenarioRuns.map(entry => ({ entry, index: entry.feature_scenario, spare: false })));
+        } else {
+          for (const answer of report.scenarios.filter(item => !item.passed && item.played)) {
+            const entry = spares.shift();
+            if (!entry) break;
+            toPlay.push({ entry, index: answer.index, spare: true });
+          }
+        }
+        if (toPlay.length > 0) {
+          // playJob owns the signal while it plays; ours comes back after it.
+          interrupt.release();
+          const result = await playScenarios({
+            toPlay, deps, api, apiUrl, gameId, jobId, repoRoot, pack, personas, projectDir, options, journal, spec, brief,
+            commit: checked.head, config: context.config, injected, log
+          });
+          interrupt = createInterruptHandler({
+            api, gameId, jobId, repoRoot, journal, inFlight, log,
+            message: 'finishing the turn in flight, then stopping. A feature job cannot be resumed, so what did not happen is being given back.',
+            injected
+          });
+          for (const { index } of toPlay) { pendingScenarios.delete(index); staleScenarios.delete(index); }
+          played = true;
+          if (result === EXIT.CANCELED) {
+            await abandon('the feature job was interrupted');
+            return EXIT.CANCELED;
+          }
+        }
+        report = await api.jobs.feature(gameId, jobId);
+        const failed = report.scenarios.filter(item => item.played && !item.passed);
+        repairReason = null;
+        if (failed.length > 0 && spares.length > 0) {
+          repairReason = `${failed.length} test scenario${failed.length > 1 ? 's' : ''} did not pass`;
+          repairDetail = await scenarioFailureText({ failed, repoRoot, jobId });
+        }
+      }
+      if (!repairReason || !runGoAhead()) break;
+      repairs += 1;
+      log(`repair ${repairs} of ${MAX_REPAIRS}: ${repairReason}.`);
+      applied = await applyFeature({
+        ...applyArgs,
+        maxActions: Math.min(REPAIR_MAX_ACTIONS, maxActions),
+        repair: { attempt: repairs, of: MAX_REPAIRS, reason: repairReason, detail: repairDetail },
+        repo: assetChecks.withChecks(withRunCheck(applyRepo, checks))
+      });
+      if (stopped()) break;
+    }
+
+    if (stopped()) {
+      await abandon('the feature job was interrupted during a repair');
+      return EXIT.CANCELED;
+    }
+    await skipAll(spares, 'no repair needed it');
+    for (const entry of pendingScenarios.values()) await skipAll([entry], checksBlock ? 'the change did not pass its checks' : 'not played');
+
+    const finalChanged = await git.diffStat();
+    const files = finalChanged.slice(0, maxWrites);
+    const placeholders = assets.placeholders(plan, spec);
+    const assetReport = await assets.report({ runDir: directory, changed: projectRelative(finalChanged, repoRoot, projectDir), placeholders, log });
+    const events = await eventsInChange({ spec, files, repoRoot });
+    const budgetTouched = applied.stop === 'budget' || applied.stop === 'budget_warning';
+
+    if (checksBlock) {
+      heartbeat.stop();
+      inFlight.delete(featureRun.run_id);
+      const body = featureEvidence({
+        prBody: `# ${spec.title}: not uploaded\n\nThis change does not pass its checks.`,
+        summarySource: 'local', spec, report: null, files, checks: checks.results, repairs, maxRepairs: MAX_REPAIRS, placeholders, events, staleNotes, budgetTouched, assetLines: assetReport.reportLines
+      });
+      await writeFile(path.join(directory, RUN_FILES.reportMd), body, 'utf8').catch(() => {});
+      log(`This change does not pass its checks 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.`);
+      await complete({ state: 'failed', reason: 'check_failed' });
+      await settleAndSay('the change did not pass its checks');
+      return EXIT.FAILED;
+    }
+
+    report = await api.jobs.feature(gameId, jobId).catch(() => report);
+    const fallback = localFeatureSummary({ spec, plan, files, branch });
+    const summary = applied.stop === 'budget'
+      ? { ...fallback, source: 'local' }
+      : await summariseFeature({ client, jobId, runId: featureRun.run_id, system, spec, plan, files, branch, fallback, ledger, log });
+    const finalReport = withStale(report, staleScenarios);
+    const prBody = withEvidenceIntact(description => featureEvidence({
+      prBody: description, summarySource: summary.source, spec, report: finalReport, files, checks: checks.results,
+      repairs, maxRepairs: MAX_REPAIRS, placeholders, events, staleNotes, budgetTouched, assetLines: assetReport.reportLines
+    }), summary.prBody);
+    const changeset = withoutQuotedSecrets({
+      schema_version: '1.0',
+      spec_id: specId,
+      branch,
+      base_commit: checked.head,
+      files,
+      checks: checks.results.slice(-60).map(result => ({ name: result.name, status: result.status })),
+      repairs,
+      placeholders,
+      ...(staleScenarios.size ? { stale_scenarios: [...staleScenarios] } : {}),
+      pr_title: summary.prTitle,
+      pr_body: prBody
+    }, log);
+    const reportPath = await writeChangeset(directory, changeset);
+
+    await heartbeat.beat();
+    heartbeat.stop();
+    inFlight.delete(featureRun.run_id);
+    await writeUsageFile(directory, ledger);
+    await api.runs.transition(gameId, jobId, featureRun.run_id, 'reporting', { reason: '' });
+    await api.runs.transition(gameId, jobId, featureRun.run_id, 'uploading', { reason: '' });
+    let accepted = true;
+    try {
+      await deps.finalizeRun(directory, {
+        api, gameId, jobId, runId: featureRun.run_id,
+        allowedPaths: [CHANGESET_FILE, RUN_FILES.reportMd, RUN_FILES.usageJson],
+        body: { state: 'succeeded', changeset }
+      });
+      await stateFile.patchRun(repoRoot, journal, featureRun.run_id, { state: 'succeeded', uploaded: true, completed: true, report_written: true });
+    } catch (error) {
+      accepted = false;
+      log(`The changeset could not be uploaded (${String(error && error.message)}). It is in ${directory} and "ravensight-playtest upload ${jobId}" can retry it.`);
+      for (const detail of changesetDetails(error)) log(`  ${detail}`);
+    }
+    await settle('');
+
+    const closed = await api.jobs.feature(gameId, jobId).catch(() => finalReport);
+    log(`branch ${branch}`);
+    for (const file of files) log(`  ${file.path} +${file.additions} -${file.deletions}`);
+    if (finalChanged.length > files.length) log(`${finalChanged.length} files changed and a ${frozen.size} feature's changeset carries at most ${maxWrites}. The branch has all of them.`);
+    if (closed) log(closed.verification_note);
+    if (closed && closed.refund_limited_note) log(closed.refund_limited_note);
+    for (const item of placeholders) log(`placeholder: ${item}`);
+    if (budgetTouched) log('The job stopped early because its model budget was spent or nearly spent, so read the diff carefully: it may be half a feature.');
+
+    let opened = null;
+    if (flags.openPr) {
+      if (!accepted || !closed || closed.verification.status !== 'verified') {
+        log(`--open-pr opens a pull request only for a verified feature, and this one reads ${closed ? closed.verification.status.replace('_', ' ') : 'unknown'}. Nothing was pushed.`);
+        opened = { ok: false };
+      } else {
+        const opener = injected.openPullRequest || openPullRequest;
+        opened = await opener({
+          repoRoot, branch, paths: finalChanged.map(file => file.path).filter(file => applyRepo.written.includes(file)), title: changeset.pr_title, bodyFile: reportPath,
+          confirm: injected.confirmPr || injected.confirm || (deps.ui && deps.ui.confirm), log
+        });
+        if (opened.ok) await recordPrOpened({ api, gameId, repoRoot, journal, url: opened.url });
+      }
+    }
+    if ((!opened || !opened.ok) && !flags.prototype) {
+      log('Nothing was committed and nothing was pushed. Read the diff, commit it, then:');
+      log(`  gh pr create --title ${shellQuote(changeset.pr_title)} --body-file ${shellQuote(reportPath)}`);
+    }
+    if (flags.json) (deps.ui && deps.ui.json ? deps.ui.json : value => console.log(JSON.stringify(value)))({ job_id: jobId, ...closed });
+    if (applied.stop === 'budget') return EXIT.BUDGET;
+    return opened && !opened.ok ? EXIT.ENVIRONMENT : EXIT.OK;
+  } catch (error) {
+    heartbeat.stop();
+    const code = exitCodeFor(error);
+    log(`the feature job failed: ${String(error && error.message)}`);
+    await abandon('the feature job failed');
+    return code;
+  } finally {
+    interrupt.release();
+  }
+}
+
+/** One persona run per scenario, against this working tree, on the seams validate uses. */
+async function playScenarios({ toPlay, deps, api, apiUrl, gameId, jobId, repoRoot, pack, personas, projectDir, options, journal, spec, brief, commit, config, injected, log }) {
+  const controls = await inputControls(projectDir);
+  const runs = toPlay.map(({ entry, index, spare }) => ({
+    ...entry,
+    target: projectDir,
+    brief: scenarioBrief(brief, spec.test_scenarios[index], spec, controls),
+    // The same seed for a scenario however many times it is played, so a re-play
+    // after a repair differs only by what the repair changed.
+    seed: seedFrom(`${jobId}:${index}`),
+    trace_header: { commit, side: 'head', pair: index },
+    ...(spare ? { report_scenario: index } : {})
+  }));
+  for (const { index } of toPlay) log(`scenario: ${spec.test_scenarios[index].title}`);
+  let localBrief = {};
+  try {
+    localBrief = await loadLocalBrief({ repoRoot });
+  } catch (error) {
+    log(`${String(error && error.message)} The scenarios go ahead without expected_noise and test_account.`);
+  }
+  return (injected.playJob || playJob)({
+    deps, api, apiUrl, gameId, jobId, repoRoot, runs, pack, personas,
+    driverName: 'godot_driver', target: projectDir, options, journal, config, brief, localBrief, injected, log, finish: false
+  });
+}
+
+/**
+ * Re-judge scenarios that passed before a repair, for free, by replaying their
+ * traces on the code as it now stands. Answers those that can no longer be
+ * claimed. Never fails the job: no trace or a replay that breaks reads as stale.
+ *
+ * @returns {Promise<Array<{index: number, title: string}>>}
+ */
+export async function rejudgePassed({ report, api, gameId, jobId, repoRoot, projectDir, godotPath, replayer = replayTrace, log = () => {} }) {
+  const stale = [];
+  const sha = await headSha(repoRoot);
+  for (const answer of (report ? report.scenarios : []).filter(item => item.passed && item.run_id)) {
+    const directory = runDirFor(repoRoot, jobId, answer.run_id);
+    let result = null;
+    try {
+      const text = await readFile(path.join(directory, 'trace.jsonl'), 'utf8');
+      result = await replayer({ text, projectDir, godotPath, runDir: path.join(directory, 'trace-replay') });
+      log(`scenario "${answer.title}": ${replaySentence(result)}`);
+      if (sha) await api.runs.recordReplay(gameId, jobId, answer.run_id, replayReport(result, { ref: 'feature-branch', sha })).catch(() => {});
+    } catch (error) {
+      log(`scenario "${answer.title}": its trace could not be replayed (${String(error && error.message)}).`);
+    }
+    if (!result || result.matched !== true || result.fully_replayed !== true) stale.push({ index: answer.index, title: answer.title });
+  }
+  return stale;
+}
+
+async function headSha(repoRoot) {
+  try {
+    const { stdout } = await execFileAsync('git', ['-C', repoRoot, 'rev-parse', 'HEAD']);
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+/** The repair's failure text: which scenarios, why, and what the persona filed. */
+export async function scenarioFailureText({ failed, repoRoot, jobId }) {
+  const parts = [];
+  for (const answer of failed) {
+    const lines = [`Scenario "${answer.title}" did not pass: ${answer.reason}. Expected: ${answer.expected}`];
+    try {
+      const body = JSON.parse(await readFile(path.join(runDirFor(repoRoot, jobId, answer.run_id), RUN_FILES.reportJson), 'utf8'));
+      for (const finding of (body.findings || []).slice(0, 5)) lines.push(`- ${finding.severity}: ${finding.title}. ${String(finding.description || '').slice(0, 400)}`);
+    } catch {
+      // No report on disk: the reason above is what there is.
+    }
+    parts.push(lines.join('\n'));
+  }
+  return parts.join('\n\n');
+}
+
+/** The report with scenarios this command could not stand behind marked as such. */
+function withStale(report, stale) {
+  if (!report || stale.size === 0) return report;
+  const scenarios = report.scenarios.map(item => (stale.has(item.index) ? { ...item, passed: false, reason: 'passed before a later repair, and its trace no longer replays the same' } : item));
+  const passed = scenarios.filter(item => item.passed).length;
+  const status = passed === scenarios.length ? 'verified' : (passed > 0 ? 'partly_verified' : 'not_verified');
+  return { ...report, scenarios, verification: { status, passed, total: scenarios.length } };
+}
+
+/** `changeset.json` and `report.md`, scanned first, as a fix's are. */
+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;
+}
+
+export default featureCommand;