ravensight-playtest 0.5.2 → 0.7.0

package/src/commands/create.js

@@ -0,0 +1,734 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { prepareAssets } from '../assets/index.js';
+import { countsLine, DEFAULT_ASSETS_DIR } from '../assets/inventory.js';
+import { saveConfig, defaultConfig } from '../config.js';
+import { dashboardUrl } from '../dashboard.js';
+import {
+  checkoutMain, commitAll, currentBranch, hasCommit, initRepository, landOnMain, writeKeyFile, writeScaffold
+} from '../create/scaffold.js';
+import { getDeps } from '../run/deps.js';
+import EXIT from '../run/exit.js';
+import { GodotDriver } from '../run/drivers/godot.js';
+import { inputControls } from '../run/drivers/godot-project.js';
+import { scenarioBrief } from '../run/featureLoop.js';
+import { createHeartbeat } from '../run/heartbeat.js';
+import { parseJsonObject } from '../run/json.js';
+import { stopRunningChecks } from '../run/checks.js';
+import { claimSignal, dieOf } from '../run/liveWork.js';
+import { callStepWithRetry, configureSpendHold, createModelClient, STEPS } from '../run/model.js';
+import { jobDir, runDir as runDirFor } from '../run/paths.js';
+import { briefAsksFor3d, CREATE_REFUSES_3D } from '../run/dimension.js';
+import * as stateFile from '../run/state.js';
+import { parseTrace, seedFrom, TRACE_FILE } from '../run/trace.js';
+import { unknownPersonaMessage, unknownPersonas } from '../runDefaults.js';
+import { loadLocalBrief } from '../briefLocal.js';
+import { buildFeature } from './feature.js';
+import { exitCodeFor, explainRegisterRefusal, formatCents, playJob, resolvePersonas, resolveSetup, startBalanceLine, startBalanceShort } from './run.js';
+
+/**
+ * `ravensight-playtest create`: Create a game (Labs, Experimental), on this machine.
+ *
+ * From a brief, it confirms the whole declared budget, makes a new game through the
+ * org's own create-game route, buys the prototype job, asks the model for a design
+ * and stops: a person reads and approves that in the dashboard. Given the plan's job
+ * id, it writes the scaffold, proves in real Godot that it boots, and then builds one
+ * milestone at a time, each an ordinary feature job with its own charge and
+ * settlement, moving on only when the last one validated, and stopping at the count
+ * that was declared. A persona then plays the finished game for the playable check.
+ *
+ * WHAT IT NEVER DOES. It never pushes. It generates no art or audio and names no tool
+ * for it. A model never decides whether a milestone validated or a game is playable:
+ * those come from the server's own run rows and from the game's own state.
+ *
+ * STOPPING. Ctrl-C closes the plan: what finished stays paid for, what never started
+ * comes back, and a milestone not yet bought was never charged. A process that dies
+ * without that leaves the plan open: run the same command again to carry on, and the
+ * plan closes by itself when its window ends. A milestone that does not validate
+ * stops here too, leaving the plan open so a retry can use another declared slot.
+ */
+
+export const JOURNAL_FILE = 'create.json';
+export const CAPABILITY = 'prototype';
+const JOB_ID = /^pt_job_[A-Za-z0-9_-]+$/;
+const PACK_MODULES = Object.freeze(['prototype', 'persona_playtest']);
+export const DESIGN_REPAIRS = 1;
+const DESIGN_MAX_TOKENS = 32000;
+const EXPERIMENTAL = 'Create a game is Experimental: it may not produce a game you want, so read the design before you approve it, and read the code before you ship it.';
+
+const DECLINE_TOOL = {
+  name: 'decline_game',
+  description: 'Decline a brief this cannot honestly deliver: it needs 3D, it is too large for any number of bounded milestones, or it is not a game or recreates an existing one. Declining costs the studio nothing.',
+  input_schema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['reason', 'explanation'],
+    properties: {
+      reason: { enum: ['too_large', 'out_of_scope', 'not_2d'] },
+      explanation: { type: 'string', maxLength: 600 }
+    }
+  }
+};
+
+// One string and not the schema itself: real models flattened and stringified a
+// nested tool input, on most designs, and came back worse when told so.
+const DESIGN_TOOL = {
+  name: 'write_game_design',
+  description: 'Write the game design a person will approve.',
+  input_schema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['design_json'],
+    properties: {
+      design_json: { type: 'string', description: 'The whole design as one JSON object that matches design_schema.' }
+    }
+  }
+};
+
+function slugOf(text, fallback = 'new-game') {
+  return String(text || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || fallback;
+}
+
+function journalPath(dir) {
+  return path.join(dir, '.ravensight', JOURNAL_FILE);
+}
+
+async function readJournal(dir) {
+  try {
+    return JSON.parse(await readFile(journalPath(dir), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function writeJournal(dir, journal) {
+  await mkdir(path.dirname(journalPath(dir)), { recursive: true });
+  await writeFile(journalPath(dir), `${JSON.stringify(journal, null, 2)}\n`, { mode: 0o600 });
+}
+
+/** The limit on getting the first charge back, in the server's figures. Nothing from an older server. */
+export function refundLimitLines(limit) {
+  if (!limit) return [];
+  return [`Once the model has been used, this account can get the first charge back ${limit.limit} times in any ${limit.window_days} days, and it has ${limit.left} left. Past that, a brief that is declined, a design you reject and a plan that stops before its scaffold boots all keep it.`];
+}
+
+/** What rejecting a design does to this account's money, right now. */
+export function rejectLine(limit) {
+  if (limit && limit.left <= 0) return 'Read it and approve or reject it in the dashboard. This account has used its refunds, so rejecting it keeps the first charge.';
+  return `Read it and approve or reject it in the dashboard. Rejecting it gives the whole charge back${limit ? `, which uses one of your ${limit.left} refund${limit.left === 1 ? '' : 's'}` : ''}.`;
+}
+
+/** Lines stating a declared plan. Every figure is the server's. */
+export function planLines(quote) {
+  const units = quote.breakdown.map(line => `${line.count} x ${line.unit} at ${formatCents(line.unit_cents)}`).join(', ');
+  return [
+    `Create a game (${quote.label}): up to ${quote.milestones} milestone${quote.milestones === 1 ? '' : 's'}, each at most ${quote.size}.`,
+    `The whole plan is at most ${formatCents(quote.estimate_cents)} (${units}).`,
+    `${formatCents(quote.charged_at_register_cents)} is charged now for the design, the scaffold and the persona run that checks the game is playable. Each milestone is at most ${formatCents(quote.milestone_cents)}, charged when it starts.`,
+    'The run stops at the declared count. Each charge is refunded by its own rules when nothing was delivered, and a milestone that never starts is never charged.',
+    ...(startBalanceLine(quote) ? [startBalanceLine(quote)] : []),
+    ...refundLimitLines(quote.refund_limit)
+  ];
+}
+
+/**
+ * @param {string} target a brief, or a plan's job id
+ * @param {Object} flags
+ * @param {Object} [injected] test seam
+ * @returns {Promise<number>} an exit code
+ */
+export async function createCommand(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));
+  const signals = createStopFlag(injected);
+  configureSpendHold({ log, shouldStop: () => signals.stopped });
+  try {
+    const value = String(target || '').trim();
+    if (!value) {
+      log('Say what game to make, in quotes, or name a plan\'s job id.');
+      return EXIT.ENVIRONMENT;
+    }
+    if (JOB_ID.test(value)) return await carryOn(value, flags, injected, deps, log, signals);
+    if (flags.template === 'godot-3d' || briefAsksFor3d(value)) {
+      log(CREATE_REFUSES_3D);
+      return EXIT.ENVIRONMENT;
+    }
+    return await start(value, flags, injected, deps, log, signals);
+  } catch (error) {
+    const code = exitCodeFor(error);
+    if (code === EXIT.FAILED) throw error;
+    log(String(error && error.message ? error.message : error));
+    return code;
+  } finally {
+    signals.release();
+    configureSpendHold({ shouldStop: () => false });
+  }
+}
+
+/** This command's own view of Ctrl-C. Handlers further in have theirs too. */
+function createStopFlag(injected) {
+  const target = injected.process || process;
+  const names = injected.signals || ['SIGINT', 'SIGTERM'];
+  const state = { stopped: false };
+  // A flag alone would swallow every Ctrl-C after the first, and nothing could end a
+  // scaffold that hangs. A second one means now.
+  const onSignal = (signal) => {
+    if (state.stopped && target === process) dieOf(signal);
+    state.stopped = true;
+    stopRunningChecks();
+    if (target === process) claimSignal();
+  };
+  for (const name of names) target.on(name, onSignal);
+  return {
+    get stopped() { return state.stopped; },
+    release() { for (const name of names) target.removeListener(name, onSignal); }
+  };
+}
+
+/** The first half: price, game, job, design. A person approves what comes back. */
+async function start(brief, flags, injected, deps, log, signals) {
+  const milestones = Number.isInteger(flags.milestones) ? flags.milestones : 3;
+  const size = flags.size || 'medium';
+  const title = flags.name || brief.split(/[.!?\n]/)[0].slice(0, 60);
+  const dir = path.resolve(flags.dir || slugOf(title));
+  const existing = await readdir(dir).catch(() => null);
+  if (existing && existing.length > 0) {
+    log(`${dir} is not empty, and a scaffold only goes in an empty directory. Pass --dir with a new one. Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+  if (flags.assetsDir && path.relative(dir, path.resolve(dir, flags.assetsDir)).split(path.sep)[0] === '..') {
+    log(`The assets folder has to be inside the project, and ${flags.assetsDir} is not. Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+
+  const context = await deps.createContext({ apiUrl: flags.apiUrl, repoRoot: path.dirname(dir), requireAuth: true }).catch(error => {
+    log(`You are not signed in. Run "ravensight-playtest login" first. (${String(error && error.message)})`);
+    return null;
+  });
+  if (!context) return EXIT.AUTH;
+  const { api, apiUrl } = context;
+
+  let quote;
+  try {
+    quote = await api.labs.prototypes.estimate({ milestones, size });
+  } catch (error) {
+    if (error && error.status === 404) {
+      log('This server does not offer Create a game. Nothing was charged.');
+      return EXIT.ENVIRONMENT;
+    }
+    if (error && error.status === 400) {
+      log(`${String(error.message)} Nothing was charged.`);
+      return EXIT.ENVIRONMENT;
+    }
+    throw error;
+  }
+  if (!quote.capability_live) {
+    log('Create a game is part of Ravensight Labs (Experimental), and it is not available yet. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+  if (!quote.can_manage) {
+    log('Only an owner or admin can start Create a game. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+  log(EXPERIMENTAL);
+  for (const line of planLines(quote)) log(line);
+  if (!quote.funded) {
+    log(`Create a game needs an account that has added at least $10.00 in top-ups. Add funds at ${quote.topup_url} and run this again. Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+  if (quote.ok === false && startBalanceLine(quote)) {
+    log(`${startBalanceShort(quote)} Declaring fewer milestones needs less.`);
+    return EXIT.ENVIRONMENT;
+  }
+  if (quote.ok === false) {
+    log(`The balance is ${formatCents(quote.balance_cents)}, and it has to cover the whole plan. Add funds at ${quote.topup_url}, or declare fewer milestones, 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(`Start this plan, charging ${formatCents(quote.charged_at_register_cents)} now?`, { yes: flags.yes })) {
+    log('Nothing was charged and nothing was created.');
+    return EXIT.CANCELED;
+  }
+
+  const gameId = `${slugOf(title).slice(0, 48)}-${randomBytes(3).toString('hex')}`;
+  const made = await api.labs.prototypes.createGame({ gameId, name: title.slice(0, 80) });
+  await initRepository(dir);
+  await writeKeyFile({ dir, ingestKey: made.ingestKey, apiUrl });
+  // A named folder is kept with the project, so every milestone finds it the way a feature does.
+  await saveConfig(defaultConfig(gameId, { driver: 'godot_driver', godot_project: '.', build: { kind: 'godot_project', ref: '.' }, ...(flags.assetsDir ? { assets_dir: flags.assetsDir } : {}) }), { repoRoot: dir });
+  log(`game ${gameId} made, with its key in ${path.join(dir, 'ravensight_key.cfg')}, which git ignores.`);
+
+  const pack = await deps.packs.get({ api, gameId, modules: [...PACK_MODULES] });
+  const skill = (pack.skills || []).find(entry => entry.module === 'prototype');
+  if (!skill) {
+    log('The content pack does not have this module. Update the server and CLI together. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+  const personaSlugs = resolvePersonas({ personas: flags.personas }, null, pack).slice(0, 1);
+  const unknown = unknownPersonas(personaSlugs, pack.personas || []);
+  if (unknown.length > 0) {
+    log(`${unknownPersonaMessage(unknown, pack.personas || [])} Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+
+  const journal = {
+    job_id: null, game_id: gameId, title, brief, milestones, size,
+    plan_cents: quote.estimate_cents, job_cents: quote.charged_at_register_cents,
+    persona: personaSlugs[0], idempotency_key: randomUUID(), api_url: apiUrl
+  };
+  await writeJournal(dir, journal);
+
+  let registered;
+  try {
+    registered = await registerPlan(api, journal, deps);
+  } catch (error) {
+    if (error && ['labs_not_enabled', 'funding_required', 'forbidden'].includes(error.code)) {
+      log(String(error.message));
+      return EXIT.ENVIRONMENT;
+    }
+    const handled = explainRegisterRefusal(error, log);
+    if (handled !== null) return handled;
+    throw error;
+  }
+  journal.job_id = registered.job_id;
+  await writeJournal(dir, journal);
+  await mkdir(jobDir(dir, registered.job_id), { recursive: true });
+  log(`job ${registered.job_id}: ${formatCents(registered.price.price_cents)} charged.`);
+
+  const unit = (registered.runs || []).find(entry => entry.module === 'prototype');
+  const createClient = injected.createClient || createModelClient;
+  const client = createClient({ apiUrl, token: injected.modelToken || api.token });
+  const outcome = await writeDesign({ api, gameId, jobId: registered.job_id, runId: unit.run_id, brief, journal, pack, skill, client, log, signals });
+
+  if (outcome.stop) {
+    await closeUnit(api, gameId, registered.job_id, unit.run_id, outcome.stop, log);
+    const closed = await stopPlan(api, gameId, registered.job_id, log);
+    log(moneyLine(closed));
+    return outcome.stop === 'declined' ? EXIT.ENVIRONMENT : (signals.stopped ? EXIT.CANCELED : EXIT.FAILED);
+  }
+
+  const design = outcome.plan.design.spec;
+  log(`The design: ${design.title}. ${design.pitch}`);
+  log(`Core loop: ${design.core_loop.summary}`);
+  outcome.plan.milestones.forEach(row => log(`  ${row.index + 1}. ${row.title} (${row.size})${row.declared ? '' : ', past the declared count'}`));
+  log(rejectLine(outcome.plan.refund_limit));
+  log(`  ${dashboardUrl(apiUrl)}/labs/prototypes/${registered.job_id}?game=${encodeURIComponent(gameId)}`);
+  log(`Your own art and audio go in ${path.join(dir, flags.assetsDir || DEFAULT_ASSETS_DIR)}. Put them there before you carry on, and each milestone can use them. Anything missing stays a placeholder.`);
+  log('Then carry on with:');
+  log(`  cd ${dir} && npx ravensight-playtest create ${registered.job_id}`);
+  if (flags.json) (deps.ui && deps.ui.json ? deps.ui.json : answer => console.log(JSON.stringify(answer)))({ job_id: registered.job_id, game_id: gameId, dir, status: outcome.plan.status });
+  return EXIT.OK;
+}
+
+/** The register body, the same every time, so a replay hands back the same job and fresh run tokens. */
+function registerPlan(api, journal, deps) {
+  return api.jobs.register(journal.game_id, {
+    modules: [CAPABILITY],
+    personas: [journal.persona],
+    driver: 'godot_driver',
+    cli_version: deps.cliVersion || api.cliVersion || '0.0.0',
+    confirm_price_cents: journal.job_cents,
+    build: { kind: 'godot_project', ref: '.' },
+    repo: { commit: '', dirty: false, branch: 'main' },
+    pack_versions: {},
+    prototype: { brief: journal.brief, milestones: journal.milestones, size: journal.size, confirm_plan_cents: journal.plan_cents }
+  }, { idempotencyKey: journal.idempotency_key });
+}
+
+/**
+ * The model's design, held to the server's schema, with one repair if it is refused.
+ *
+ * @returns {Promise<{plan?: Object, stop?: string}>} the stored plan, or the reason
+ *   the unit's run closes
+ */
+async function writeDesign({ api, gameId, jobId, runId, brief, journal, pack, skill, client, log, signals }) {
+  const heartbeat = createHeartbeat({ api, gameId, jobId, runId, onCancel: () => {}, onUsage: () => {}, onError: () => {} });
+  try {
+    await api.runs.transition(gameId, jobId, runId, 'launching', { reason: '' });
+    await api.runs.transition(gameId, jobId, runId, 'playing', { reason: '' });
+    heartbeat.start();
+    const shape = (await api.labs.prototypes.get(gameId, jobId)).prototype.design_schema;
+    const tools = [DESIGN_TOOL, DECLINE_TOOL];
+    const system = [{ type: 'text', text: skill.content, cache_control: { type: 'ephemeral' } }];
+    const messages = [{ role: 'user', content: [{ type: 'text', text: designPrompt({ brief, journal, shape }) }] }];
+    log('Writing the design.');
+    for (let attempt = 0; attempt <= DESIGN_REPAIRS; attempt += 1) {
+      if (signals.stopped) return { stop: 'design_failed' };
+      let answer;
+      try {
+        answer = await callStepWithRetry({ client, jobId, runId, step: STEPS.prototypeDesign, system, messages, tools, maxTokens: DESIGN_MAX_TOKENS });
+      } catch (error) {
+        log(`The design could not be written: ${String(error && error.message)}`);
+        return { stop: 'design_failed' };
+      }
+      const call = (answer.toolUses || [])[0];
+      if (call && call.name === DECLINE_TOOL.name && call.input) {
+        log(`Declined: ${String(call.input.explanation || call.input.reason).slice(0, 600)}`);
+        return { stop: 'declined' };
+      }
+      const design = designFrom(call && call.name === DESIGN_TOOL.name ? call.input : parseJsonObject(answer.text || ''), shape);
+      if (!design) {
+        log('The answer held no design.');
+        messages.push({ role: 'assistant', content: answer.text || '(no design)' }, { role: 'user', content: 'Call write_game_design or decline_game.' });
+        continue;
+      }
+      try {
+        const { prototype } = await api.labs.prototypes.submitDesign(gameId, jobId, design);
+        return { plan: prototype };
+      } catch (error) {
+        if (!(error && error.code === 'invalid_game_design')) throw error;
+        const details = ((error.body && error.body.details) || []).slice(0, 12).map(detail => `${detail.instancePath}: ${detail.message}`).join('\n');
+        log(`The design was refused by its schema${attempt < DESIGN_REPAIRS ? ', so the model gets one more try' : ''}:\n${details}`);
+        // The model has no memory of a design unless it is sent back, and from nothing it writes a different shape.
+        messages.push(
+          { role: 'assistant', content: JSON.stringify(design) },
+          { role: 'user', content: `That design was refused:\n${details}\nCall write_game_design again with this same whole design, changing only what the refusal names.` }
+        );
+      }
+    }
+    return { stop: 'design_failed' };
+  } finally {
+    heartbeat.stop();
+  }
+}
+
+/**
+ * The design inside a model's answer. A real model can answer `{ design: {...} }` for
+ * all the schema says otherwise, and the design is no less the design. The schema
+ * version is a constant the model has no way to know better, so it is ours to set.
+ */
+export function designFrom(answer, shape) {
+  const unwrapped = answer && typeof answer.design_json === 'string' ? parseJsonObject(answer.design_json) : answer;
+  const keys = unwrapped && typeof unwrapped === 'object' ? Object.keys(unwrapped) : [];
+  const design = keys.length === 1 && keys[0] === 'design' && unwrapped.design && typeof unwrapped.design === 'object' ? unwrapped.design : unwrapped;
+  const version = shape && shape.properties && shape.properties.schema_version && shape.properties.schema_version.const;
+  return design && typeof design === 'object' && version ? { ...design, schema_version: version } : design;
+}
+
+function designPrompt({ brief, journal, shape }) {
+  return [
+    `<brief>\n${brief}\n</brief>`,
+    `<declared_milestones>${journal.milestones}</declared_milestones>`,
+    `<size>${journal.size}</size>`,
+    '<template>',
+    'A Godot 4 2D project with: scenes/main.tscn (a Node2D root with a placeholder player, a HUD label and a settings overlay), scripts/main.gd, scripts/player.gd, scripts/state_hook.gd (the node a playtest reads), and these autoloads: GameState (score, level, deaths, complete_core_loop(), add_score(), record_death()), Telemetry (track(name, data, kind)), GameConfig and Ravensight. Input actions: move_left, move_right, move_up, move_down, action, pause. Pause opens settings, so a game must not take it over.',
+    '</template>',
+    `<design_schema>\n${JSON.stringify(shape)}\n</design_schema>`
+  ].join('\n');
+}
+
+async function closeUnit(api, gameId, jobId, runId, reason, log) {
+  try {
+    await api.runs.complete(gameId, jobId, runId, { state: 'failed', reason });
+  } catch (error) {
+    log(`the run could not be closed (${String(error && error.message)}); the plan's sweep will settle it.`);
+  }
+}
+
+async function stopPlan(api, gameId, jobId, log) {
+  try {
+    const { prototype } = await api.labs.prototypes.stop(gameId, jobId);
+    return prototype;
+  } catch (error) {
+    log(`the plan could not be closed now (${String(error && error.message)}). Run this command again with --stop, or it closes itself when its window ends.`);
+    return null;
+  }
+}
+
+/** What a plan cost, all of it the server's figures. */
+export function moneyLine(plan) {
+  if (!plan) return 'The server could not say what this plan cost. It is on the job page.';
+  const money = plan.money;
+  const limited = plan.refund_limited_note ? ` ${plan.refund_limited_note}` : '';
+  return `Declared ${formatCents(money.declared_cents)}. Charged ${formatCents(money.charged_cents)}, refunded ${formatCents(money.refunded_cents)}${money.refund_reason ? ` (${money.refund_reason})` : ''}. ${formatCents(money.never_charged_cents)} was never charged.${limited}`;
+}
+
+/** The second half. Everything is read back from the server, so it can resume anywhere. */
+async function carryOn(jobId, flags, injected, deps, log, signals) {
+  const dir = path.resolve(flags.repoRoot || process.cwd());
+  const journal = await readJournal(dir);
+  if (!journal || journal.job_id !== jobId) {
+    log(`This directory is not that plan's project, because ${journalPath(dir)} does not name it. Run this from the project, or pass --repo. Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+  const options = {
+    apiUrl: flags.apiUrl, repo: dir, game: journal.game_id, yes: true, headless: flags.headless === true,
+    godotPath: flags.godotPath, personas: flags.personas || [journal.persona], uploadTrace: true, skipAggregate: true, concurrency: 1, verbose: flags.verbose
+  };
+  const setup = await resolveSetup(deps, options, log);
+  if (setup.code !== undefined) return setup.code;
+  const { api, gameId, apiUrl } = setup;
+
+  let plan;
+  try {
+    ({ prototype: plan } = await api.labs.prototypes.get(gameId, jobId));
+  } catch (error) {
+    if (error && error.status === 404) {
+      log(`There is no plan ${jobId} for this game. Nothing was charged.`);
+      return EXIT.ENVIRONMENT;
+    }
+    throw error;
+  }
+
+  if (flags.stop) {
+    const closed = await stopPlan(api, gameId, jobId, log);
+    if (!closed) return EXIT.FAILED;
+    log(`The plan is closed. ${moneyLine(closed)}`);
+    return EXIT.OK;
+  }
+  if (plan.closed) {
+    log(`This plan has closed (${plan.state}). ${moneyLine(plan)}`);
+    return EXIT.OK;
+  }
+  if (plan.status === 'designing') {
+    log('This plan has no design, so there is nothing to carry on from. Close it with --stop to get the charge back, within this account\'s refund limit.');
+    return EXIT.ENVIRONMENT;
+  }
+  if (plan.status === 'rejected') {
+    log(`This design was rejected. ${moneyLine(plan)}`);
+    return EXIT.OK;
+  }
+  if (plan.status !== 'approved') {
+    log('A person has not approved this design yet. Read it and approve or reject it in the dashboard. Nothing more has been charged.');
+    log(`  ${dashboardUrl(apiUrl)}/labs/prototypes/${jobId}?game=${encodeURIComponent(gameId)}`);
+    return EXIT.ENVIRONMENT;
+  }
+
+  // Free, before anything is written or bought: a folder that was named has to be usable.
+  const assets = await prepareAssets({ repoRoot: dir, projectDir: dir, folder: flags.assetsDir || setup.context?.config?.assets_dir });
+  if (!assets.ok) {
+    log(`${assets.reason} Nothing more was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+  if (assets.inventory.counts.files > 0) log(`Your art and audio in ${assets.inventory.folder}: ${countsLine(assets.inventory.counts)}.`);
+
+  // A replay of the register, for the run tokens: the same key answers the same job.
+  const registered = await registerPlan(api, journal, deps);
+  const unit = registered.runs.find(entry => entry.module === 'prototype');
+  const gate = registered.runs.find(entry => entry.prototype_gate);
+  const design = plan.design.spec;
+
+  if (!plan.scaffolded_at) {
+    const scaffolded = await scaffold({ api, gameId, jobId, unit, dir, journal, design, flags, injected, log });
+    if (!scaffolded) {
+      const closed = await stopPlan(api, gameId, jobId, log);
+      log(moneyLine(closed));
+      return EXIT.FAILED;
+    }
+  } else {
+    log('The scaffold is already in place.');
+    if (await hasCommit(dir) && await currentBranch(dir) !== 'main') {
+      await commitAll(dir, 'Work left from an interrupted run, not validated');
+      await checkoutMain(dir);
+    }
+  }
+  if (signals.stopped) return closeForStop({ api, gameId, jobId, log });
+
+  // The loop. Each milestone is one feature job, and the next starts only when the
+  // last one validated by the server's own answer.
+  let refreshed = (await api.labs.prototypes.get(gameId, jobId)).prototype;
+  const declared = refreshed.milestones.filter(row => row.declared);
+  for (const row of declared) {
+    if (row.status === 'validated') {
+      log(`Milestone ${row.index + 1}, ${row.title}: already validated.`);
+      continue;
+    }
+    log(`Milestone ${row.index + 1} of ${declared.length}: ${row.title}.`);
+    const branch = `ravensight/milestone-${row.index + 1}-${slugOf(row.title).slice(0, 30)}-${randomBytes(2).toString('hex')}`;
+    const code = await (injected.buildFeature || buildFeature)(row.spec_id, {
+      ...flags, yes: true, game: gameId, repoRoot: dir, personas: options.personas, branch, godotProject: '.', json: false,
+      prototype: { job_id: jobId, milestone: row.index },
+      shouldStop: () => signals.stopped
+    }, { ...options, yes: true }, setup, injected, deps, log);
+
+    refreshed = (await api.labs.prototypes.get(gameId, jobId)).prototype;
+    const after = refreshed.milestones[row.index];
+    const onBranch = await currentBranch(dir) === branch;
+    if (after.status === 'validated') {
+      if (onBranch) {
+        await commitAll(dir, `Milestone ${row.index + 1}: ${row.title}`);
+        await landOnMain(dir, branch);
+      }
+      log(`Milestone ${row.index + 1} validated, and it is on main.`);
+    } else {
+      if (onBranch) {
+        await commitAll(dir, `Milestone ${row.index + 1} attempt, not validated: ${row.title}`);
+        await checkoutMain(dir);
+      }
+      if (signals.stopped) return closeForStop({ api, gameId, jobId, log });
+      const latest = after.attempts.at(-1);
+      log(`Milestone ${row.index + 1} did not validate${latest ? ` (${latest.outcome}, ${latest.verification.status.replace('_', ' ')})` : ''}, so the next one was not bought.${onBranch ? ` The attempt is on ${branch}.` : ''}`);
+      log(`Run "create ${jobId}" to try it again, which uses another declared milestone if this one kept its charge, or "create ${jobId} --stop" to close the plan. ${moneyLine(refreshed)}`);
+      return EXIT.FAILED;
+    }
+    if (signals.stopped) return closeForStop({ api, gameId, jobId, log });
+  }
+
+  const past = refreshed.milestones.filter(row => !row.declared);
+  if (past.length > 0) log(`Stopped at the declared count of ${declared.length}. ${past.length} more in the design ${past.length === 1 ? 'was' : 'were'} not bought: ${past.map(row => row.title).join(', ')}.`);
+  else log(`All ${declared.length} declared milestone${declared.length === 1 ? '' : 's'} validated.`);
+
+  // A persona plays the finished game. The server judges the run on its own; the
+  // number that says the core loop was completed is the game's own.
+  const played = await playableCheck({ api, apiUrl, gameId, jobId, gate, dir, design, options, journal, setup, flags, injected, deps, log });
+  if (played === EXIT.CANCELED || signals.stopped) return closeForStop({ api, gameId, jobId, log });
+
+  let finished = null;
+  try {
+    finished = await api.jobs.finish(gameId, jobId, { reason: '' });
+  } catch (error) {
+    log(`The plan could not be settled now; the sweep will settle it: ${String(error && error.message)}`);
+  }
+  const closed = (await api.labs.prototypes.get(gameId, jobId)).prototype;
+  const playable = closed.playable;
+  if (playable && playable.passed) log(`Playable: a persona completed the core loop ${playable.core_loops_completed} time${playable.core_loops_completed === 1 ? '' : 's'}, with no blocker or major finding. A persona is a model playing the game, not a player. Play it yourself before you ship it.`);
+  else log(`Not playable yet: ${playable ? playable.reason : 'the check did not finish'}.`);
+  log(moneyLine(closed));
+  log('Nothing was pushed. Every placeholder is yours to replace with your own art and audio.');
+  if (flags.json) (deps.ui && deps.ui.json ? deps.ui.json : answer => console.log(JSON.stringify(answer)))({ job_id: jobId, game_id: gameId, playable, money: closed.money, settled: Boolean(finished) });
+  return playable && playable.passed ? EXIT.OK : EXIT.FAILED;
+}
+
+async function closeForStop({ api, gameId, jobId, log }) {
+  const closed = await stopPlan(api, gameId, jobId, log);
+  log(`Stopped. What finished stays yours, and what never started comes back. ${moneyLine(closed)}`);
+  return EXIT.CANCELED;
+}
+
+/**
+ * Write the template in, prove it in real Godot, and report names and counts.
+ *
+ * @returns {Promise<boolean>} whether the scaffold was accepted
+ */
+async function scaffold({ api, gameId, jobId, unit, dir, journal, design, flags, injected, log }) {
+  const fail = async message => {
+    log(`The scaffold did not boot: ${message}. The plan closes, and the charge comes back within this account's refund limit.`);
+    await closeUnit(api, gameId, jobId, unit.run_id, 'scaffold_failed', log);
+    return false;
+  };
+  const moveUnit = async state => api.runs.transition(gameId, jobId, unit.run_id, state, { reason: '' });
+  // The run waited on a person, so the sweep may have read it as interrupted.
+  const current = (await api.runs.list(gameId, jobId)).runs.find(run => run.run_id === unit.run_id);
+  if (current && current.state === 'interrupted') await moveUnit('playing');
+  else if (current && current.state === 'queued') { await moveUnit('launching'); await moveUnit('playing'); }
+
+  let written;
+  try {
+    written = await writeScaffold({ dir, name: flags.name || design.title || journal.title, design, declared: journal.milestones });
+  } catch (error) {
+    return fail(String(error && error.message));
+  }
+  log(`Scaffold written from ${written.manifest.name} ${written.manifest.version}, with the Ravensight SDK ${written.manifest.sdk.version} from its public release. Checking that it imports and starts in Godot.`);
+
+  const makeDriver = injected.makeDriver || (driverOptions => new GodotDriver(driverOptions));
+  const driver = makeDriver({ projectDir: dir, godotPath: flags.godotPath, headless: true, lockstep: true, seed: 1, recordTrace: false });
+  let engine = '';
+  let hooked = false;
+  try {
+    await driver.launch({});
+    const states = (driver.lastDigest && driver.lastDigest.game_state) || {};
+    hooked = Object.values(states).some(state => state && Object.prototype.hasOwnProperty.call(state, 'core_loops_completed'));
+    engine = String((driver.ping && driver.ping.godot_version) || '').slice(0, 80);
+  } catch (error) {
+    return fail(String(error && error.message).slice(0, 400));
+  } finally {
+    await driver.stop({ reason: 'preflight' }).catch(() => {});
+  }
+  if (!hooked) return fail('the game started, and its state node did not answer');
+  // Starting it imported any art and audio, and those settings are the project's. A
+  // milestone only starts from a clean tree.
+  const imported = await commitAll(dir, 'Import settings for the art and audio in this project');
+
+  await moveUnit('reporting');
+  await moveUnit('uploading');
+  await api.runs.complete(gameId, jobId, unit.run_id, {
+    state: 'succeeded',
+    scaffold: {
+      schema_version: '1.0',
+      template: written.manifest.name,
+      template_version: written.manifest.version,
+      sdk_version: written.manifest.sdk.version,
+      files: written.files,
+      commit: imported || written.commit,
+      boot: { imported: true, started: true, state_hook: true, engine }
+    }
+  });
+  log(`The scaffold boots. It is on main at ${(imported || written.commit).slice(0, 8)}.`);
+  return true;
+}
+
+/**
+ * The newest `core_loops_completed` the game's own hook reported during a run, read
+ * from the run's trace. Zero when the trace has none: this can only ever say a game
+ * did less than a persona claimed.
+ *
+ * @param {string} text the trace
+ * @returns {number}
+ */
+export function coreLoopsInTrace(text) {
+  let trace;
+  try {
+    trace = parseTrace(text);
+  } catch {
+    return 0;
+  }
+  let most = 0;
+  for (const step of trace.steps) {
+    const states = step.digest && step.digest.game_state ? step.digest.game_state : (step.state && step.state.game_state);
+    if (!states) continue;
+    for (const state of Object.values(states)) {
+      const value = state && state.core_loops_completed;
+      if (Number.isInteger(value) && value > most) most = value;
+    }
+  }
+  return most;
+}
+
+async function playableCheck({ api, apiUrl, gameId, jobId, gate, dir, design, options, journal, setup, flags, injected, deps, log }) {
+  const current = (await api.runs.list(gameId, jobId)).runs.find(run => run.run_id === gate.run_id);
+  if (current && ['succeeded', 'failed', 'skipped', 'canceled', 'budget_exceeded'].includes(current.state)) {
+    log('The playable check has already run.');
+    return EXIT.OK;
+  }
+  log(`A persona plays the finished game: ${design.core_loop.done_when}`);
+  const pack = await deps.packs.get({ api, gameId, modules: ['persona_playtest'] });
+  const personas = options.personas.map(slug => (pack.personas || []).find(persona => persona.slug === slug)).filter(Boolean);
+  const brief = await deps.brief.get({ api, gameId });
+  const task = { title: 'Complete the core loop', steps: design.core_loop.player_steps, expected: design.core_loop.done_when };
+  let localBrief = {};
+  try { localBrief = await loadLocalBrief({ repoRoot: dir }); } catch { localBrief = {}; }
+  const entry = {
+    ...gate,
+    target: dir,
+    brief: scenarioBrief(brief, task, { title: design.title, summary: design.pitch }, await inputControls(dir)),
+    seed: seedFrom(`${jobId}:playable`),
+    trace_header: { side: 'head', pair: 0 }
+  };
+  const state = stateFile.newState({
+    jobId, gameId, idempotencyKey: journal.idempotency_key, cliVersion: setup.cliVersion, packVersion: pack.pack_version,
+    briefVersion: brief ? brief.version ?? null : null, modules: [CAPABILITY], driver: 'godot_driver', target: '.', priceCents: journal.job_cents,
+    options: { labs: CAPABILITY, uploadTrace: true }
+  });
+  state.runs[gate.run_id] = stateFile.newRunEntry({ runId: gate.run_id, module: gate.module, persona: gate.persona });
+  await mkdir(jobDir(dir, jobId), { recursive: true });
+  await stateFile.save(dir, state);
+
+  const code = await (injected.playJob || playJob)({
+    deps, api, apiUrl, gameId, jobId, repoRoot: dir, runs: [entry], pack, personas,
+    driverName: 'godot_driver', target: dir, options, journal: state, config: setup.context.config, brief, localBrief, injected, log, finish: false
+  });
+  if (code === EXIT.CANCELED) return code;
+
+  const text = await readFile(path.join(runDirFor(dir, jobId, gate.run_id), TRACE_FILE), 'utf8').catch(() => '');
+  const loops = coreLoopsInTrace(text);
+  try {
+    await api.labs.prototypes.playable(gameId, jobId, { run_id: gate.run_id, core_loops_completed: loops });
+  } catch (error) {
+    log(`The playable check could not be recorded: ${String(error && error.message)}`);
+  }
+  return code;
+}
+
+export default createCommand;