ravensight-playtest 0.7.0 → 0.7.2

package/README.md

@@ -1,9 +1,47 @@
 # ravensight-playtest
 
-Hosted comparisons use a separate command from the local `run`:
+Hosted playtests run your uploaded build on our machines instead of yours. One
+persona plays it twice, once with Standard and once with Jev, and the dashboard
+gets a report for each and a comparison. They use a separate command from the
+local `run`:
 
 ```sh
-ravensight-playtest hosted quote --game GAME --build BUILD --profile PROFILE --persona curious-kid --video --transcript --output hosted-quote.json
+ravensight-playtest hosted run --wait
+ravensight-playtest hosted status ha_...
+ravensight-playtest hosted cancel ha_...
+```
+
+`hosted run` uses the game this directory is linked to (or `--game`), picks the
+newest build that passed its static archive check on a ready profile (or the one
+named by `--build`), asks the server for a quote and prints it: each unit and
+its price, the hosted compute for each mode, the total and what is due now from
+prepaid funds, the expiry, and the statements you accept with it (the refund
+rules for a failed build and for cancellation, no network access for the game,
+the separate validation hold). It asks before it charges. `--yes` answers for
+you, a run with no terminal and no `--yes` is a no, and `--json` needs `--yes`.
+A balance that does not meet the quote's funding requirement stops before the
+question, and nothing is charged.
+
+| Flag | Effect |
+|---|---|
+| `--build <id>` | Use this build instead of the newest ready one. |
+| `--persona <slug>` | The persona for both runs. Default `curious-kid`. |
+| `--video`, `--transcript` | Save video or transcripts of both sessions in their reports. Priced in the quote. |
+| `--wait` | Stay until the run finishes, printing each phase change, then each mode's outcome. |
+| `--game <id>` | Override the linked game. |
+
+The phases are the dashboard's: queued, provisioning, running, capturing,
+analyzing, then report ready, failed or canceled. `hosted status <id>` prints
+the current one (`--wait` to follow it) with each mode's state and findings and
+the dashboard link to the report. With `--wait`, a failed run exits 1 and a
+canceled one exits 10. `hosted cancel <id>` asks first, then requests
+cancellation: work already done follows the accepted policy and unstarted work
+is refunded during settlement.
+
+To review a quote before paying, save it and confirm it later:
+
+```sh
+ravensight-playtest hosted quote --game GAME --build BUILD --profile PROFILE --persona curious-kid --video --output hosted-quote.json
 ravensight-playtest hosted run hosted-quote.json
 ```
 
@@ -11,6 +49,7 @@ The quote names the full Standard then Jev price, prepaid amount, evidence
 options, expiry and refund rules. It charges nothing. `hosted run` confirms
 that saved quote before one admission request. Its durable journal blocks an
 automatic second POST after an uncertain outcome; preserve it for reconciliation.
+Both forms of `hosted run` keep that journal under `.ravensight/hosted-runs/`.
 A charged-blocked acknowledgement does not prove gameplay or a report. This
 command does not top up funds, change local run/report files or ask for model
 proxy permission on the CLI credential.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ravensight-playtest",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Local AI playtests and seeded game simulations with reports in Ravensight.",
   "license": "MIT",
   "homepage": "https://ravensight.io/docs/#playtest",

package/src/auth/scopes.js

@@ -0,0 +1,36 @@
+/**
+ * The scopes a CLI token carries, checked before anything is charged.
+ *
+ * A token's scopes are fixed when it is approved. A persona run needs
+ * `playtest:model` to play and `playtest:upload` to hand in its report, and
+ * the server only checks each one when the run reaches it: in October a token
+ * without `playtest:upload` registered a paid job, played it, and was refused
+ * at the upload, so the job came back with no report. `whoami` answers with
+ * the token's scopes, so `run` asks first and refuses locally.
+ */
+
+/** What a persona run (`run`, and `fix`'s verify replay) needs. */
+export const RUN_SCOPES = Object.freeze(['playtest:write', 'playtest:model', 'playtest:upload']);
+
+/**
+ * The required scopes a token lacks, or null when its scopes are not known
+ * (an older server's `whoami` does not list them).
+ *
+ * @param {unknown} scopes the `scopes` field of a whoami answer
+ * @param {ReadonlyArray<string>} [required]
+ * @returns {Array<string>|null}
+ */
+export function missingScopes(scopes, required = RUN_SCOPES) {
+  if (!Array.isArray(scopes)) return null;
+  return required.filter(scope => !scopes.includes(scope));
+}
+
+/**
+ * The refusal for a token that lacks what a run needs.
+ *
+ * @param {Array<string>} missing
+ * @returns {string}
+ */
+export function missingScopeMessage(missing) {
+  return `This login cannot run a playtest: its token does not have ${missing.join(', ')}. Log in again with "ravensight-playtest login" and approve the full set of playtest permissions. Nothing was registered or charged.`;
+}

package/src/cli.js

@@ -153,7 +153,7 @@ function withoutFirst(values, value) {
 export function buildProgram() {
   const program = new Command();
   const slot = { code: ExitCode.OK };
-  const hosted = common(program.command('hosted').description('quote and admit a server-hosted Standard/Jev comparison'));
+  const hosted = common(program.command('hosted').description('run a server-hosted Standard and Jev playtest: quote, run, status and cancel'));
   hosted.command('quote')
     .description('save a full hosted quote without charging or admitting a run')
     .requiredOption('--build <id>', 'an existing validated hosted build')
@@ -163,18 +163,43 @@ export function buildProgram() {
     .option('--game <id>', 'game id, overriding this repo’s configuration')
     .addOption(new Option('--standard-provider <name>', 'explicit Standard provider; unavailable choices are refused').choices(['anthropic', 'openai']))
     .option('--video', 'include hosted gameplay video in this quote')
-    .option('--transcript', 'include the hosted transcript in this quote')
     .action(capture(slot, async (options, command) => {
       const { hostedQuote } = await import('./commands/hosted.js');
       return hostedQuote(flagsFrom(command.optsWithGlobals(), { build: options.build, profile: options.profile,
         persona: options.persona, output: options.output, game: options.game, standardProvider: options.standardProvider,
-        video: options.video, transcript: options.transcript }));
+        video: options.video }));
     }));
-  hosted.command('run <quote-file>')
-    .description('confirm the full saved quote and request one hosted admission; never retry an unknown outcome')
-    .action(capture(slot, async (filename, _options, command) => {
-      const { hostedRun } = await import('./commands/hosted.js');
-      return hostedRun(filename, flagsFrom(command.optsWithGlobals()));
+  common(hosted.command('run [quote-file]'))
+    .description('quote the newest ready build (or --build), confirm the price, and start one hosted Standard and Jev run; with a saved quote file, confirm that quote instead. Never retries an unknown outcome')
+    .option('--build <id>', 'a build that passed its static archive check (default: the newest one)')
+    .option('--persona <slug>', 'the persona that plays both runs (default: curious-kid)')
+    .option('--game <id>', 'game id, overriding this repo’s configuration')
+    .option('--video', 'save video of both game sessions in their reports')
+    .option('--wait', 'stay until the report is ready, printing each phase change')
+    .action(capture(slot, async (filename, options, command) => {
+      const { hostedRun, hostedRunDirect } = await import('./commands/hosted.js');
+      if (filename) {
+        const extra = ['build', 'persona', 'game', 'video', 'wait'].filter(name => options[name] !== undefined);
+        if (extra.length) throw new CliError(`A saved quote already fixes its build, persona and options. Drop --${extra.join(', --')}, or run "hosted run" without a quote file.`);
+        return hostedRun(filename, flagsFrom(command.optsWithGlobals()));
+      }
+      return hostedRunDirect(flagsFrom(command.optsWithGlobals(), { build: options.build, persona: options.persona, game: options.game,
+        video: options.video, wait: options.wait }));
+    }));
+  common(hosted.command('status <run-id>'))
+    .description('show the phase of one hosted run (queued, provisioning, running, capturing, analyzing, report ready, failed or canceled), each mode and the report link')
+    .option('--game <id>', 'game id, overriding this repo’s configuration')
+    .option('--wait', 'stay until the run finishes, printing each phase change')
+    .action(capture(slot, async (runId, options, command) => {
+      const { hostedStatus } = await import('./commands/hosted.js');
+      return hostedStatus(runId, flagsFrom(command.optsWithGlobals(), { game: options.game, wait: options.wait }));
+    }));
+  common(hosted.command('cancel <run-id>'))
+    .description('request cancellation of one hosted run; unstarted work is refunded during settlement')
+    .option('--game <id>', 'game id, overriding this repo’s configuration')
+    .action(capture(slot, async (runId, options, command) => {
+      const { hostedCancel } = await import('./commands/hosted.js');
+      return hostedCancel(runId, flagsFrom(command.optsWithGlobals(), { game: options.game }));
     }));
   const build = common(program.command('build').description('check or upload a self-contained hosted game archive'));
   build.command('preflight <archive>')

package/src/commands/check.js

@@ -3,6 +3,7 @@ import { ApiError } from '../api/errors.js';
 import { resolveApiUrl, paths } from '../paths.js';
 import { resolveToken, looksLikeIngestKey, looksLikeMcpToken } from '../auth/session.js';
 import { backendName } from '../auth/keychain.js';
+import { missingScopes } from '../auth/scopes.js';
 import { loadConfig } from '../config.js';
 import { packs } from '../packs/index.js';
 import { detectFfmpeg, freeBytes, recommendConcurrency } from '../detect.js';
@@ -421,7 +422,10 @@ export async function runChecks(flags = {}, deps = {}) {
       facts.login.valid = true;
       facts.login.games = games.map(game => ({ gameId: game.gameId, name: game.name || null }));
       const who = whoami.user.email || whoami.user.name || whoami.user.id;
-      rows.push(row(
+      const missing = missingScopes(whoami.scopes);
+      if (missing && missing.length > 0) {
+        rows.push(row('login', 'fail', `${who}, valid, but the token does not have ${missing.join(', ')}, so a playtest run would be refused`, 'ravensight-playtest login'));
+      } else rows.push(row(
         'login',
         games.length > 0 ? 'pass' : 'warn',
         games.length > 0

package/src/commands/fakeCore.js

@@ -363,7 +363,11 @@ export function fakeCore({
     runs: {
       async heartbeat(gameId, jobId, runId, options) {
         record('heartbeat', { runId, options });
-        return { run: { usage: { total_usd: 0.11 } }, cancel_requested: false };
+        // calls: 0, so the fake spend never prices a unit: $0.11 over a few
+        // ten-token scripted turns would make the report reserve
+        // (../run/budgetReserve.js) stop play after one turn in tests about
+        // other things. The reserve has its own tests.
+        return { run: { usage: { total_usd: 0.11, calls: 0 } }, cancel_requested: false };
       },
       async transition(gameId, jobId, runId, state, options) {
         record('transition', { runId, state, options });

package/src/commands/fix.js

@@ -13,6 +13,7 @@ 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 { runModelBudgetUsd } from '../run/budgetReserve.js';
 import { replayTrace } from '../run/replay.js';
 import { loadTrace, replayReport, replaySentence } from './replay.js';
 import { createRepoTools, PROFILE_TOOLS, WRITE_TOOLS } from '../run/repoTools.js';
@@ -1202,6 +1203,7 @@ export async function runVerify({
     outcome = await runPersona({
       client,
       api,
+      modelBudgetUsd: runModelBudgetUsd(entry),
       gameId,
       jobId,
       runId: entry.run_id,

package/src/commands/hosted.js

@@ -3,7 +3,11 @@ import { resolveGameId } from '../config.js';
 import { withAuthHandling } from '../auth/session.js';
 import { CliError, ExitCode } from '../errors.js';
 import { ui } from '../ui/index.js';
-import { quoteHostedRun, runHostedQuote, hostedQuoteLines } from '../hosted/recordedRun.js';
+import { quoteHostedRun, runHostedQuote, hostedQuoteLines, prepareHostedRun, admitHostedOffer, confirmQuestion,
+  hostedConsentLines, fundingShortfall, readHostedRun, cancelHostedRun } from '../hosted/recordedRun.js';
+import { hostedPlaytestStatus, modeOutcomes, modeLine, TERMINAL_PHASES } from '../hosted/status.js';
+import { jobLink } from '../dashboard.js';
+import { DEFAULT_PERSONAS } from '../runDefaults.js';
 
 export async function hostedQuote(flags = {}, deps = {}) {
   const context = deps.context || await createContext({ apiUrl: flags.apiUrl, repoRoot: flags.repoRoot, requireAuth: true });
@@ -11,7 +15,7 @@ export async function hostedQuote(flags = {}, deps = {}) {
     const result = await quoteHostedRun({ api: context.api, apiUrl: context.api.apiUrl,
       gameId: resolveGameId(flags, context.config), buildId: flags.build, profileVersion: flags.profile,
       persona: flags.persona, standardProvider: flags.standardProvider, includeVideo: Boolean(flags.video),
-      includeTranscript: Boolean(flags.transcript), output: flags.output });
+      output: flags.output });
     if (flags.json) ui.json(result);
     else {
       hostedQuoteLines(result).forEach(line => ui.info(line));
@@ -37,3 +41,140 @@ export async function hostedRun(filename, flags = {}, deps = {}) {
     return result.state === 'declined' ? ExitCode.CANCELED : ExitCode.OK;
   });
 }
+
+const POLL_MS = 15000;
+const dollars = cents => `$${(cents / 100).toFixed(2)}`;
+const sleepFor = ms => new Promise(resolve => { const timer = setTimeout(resolve, ms); if (timer.unref) timer.unref(); });
+
+/** One status object for --json and for the printed lines. */
+function statusView(gameId, apiUrl, { admission, job, runs }, now = Date.now()) {
+  const status = hostedPlaytestStatus(admission, job, runs, now);
+  return {
+    admissionId: admission.admissionId,
+    jobId: admission.jobId || null,
+    gameId,
+    buildId: admission.buildId || null,
+    phase: status.phase,
+    label: status.label,
+    detail: status.detail,
+    terminal: status.terminal,
+    settled: status.settled,
+    cancelRequested: status.cancelRequested,
+    failure: status.failure || null,
+    elapsedSeconds: status.elapsedSeconds,
+    totalPriceCents: Number.isSafeInteger(admission.totalPriceCents) ? admission.totalPriceCents : null,
+    modes: modeOutcomes(runs, Array.isArray(admission.controllers) ? admission.controllers : ['standard', 'jev']),
+    summaryReport: job?.summary_report ?? null,
+    reportUrl: admission.jobId ? jobLink(gameId, admission.jobId, apiUrl) : null
+  };
+}
+
+function printOutcome(view) {
+  ui.info(`${view.label}. ${view.detail}`);
+  if (view.failure) ui.info(`Reason: ${view.failure}`);
+  if (view.cancelRequested && view.phase !== 'canceled') ui.info('Cancellation was requested.');
+  if (TERMINAL_PHASES.includes(view.phase) || view.modes.some(row => row.state !== 'not_started')) view.modes.forEach(row => ui.info(modeLine(row)));
+  if (TERMINAL_PHASES.includes(view.phase) && !view.settled) ui.info('Refunds and cleanup are still settling.');
+  if (view.reportUrl) ui.info(`Report: ${view.reportUrl}`);
+}
+
+const exitFor = view => view.phase === 'canceled' ? ExitCode.CANCELED : view.phase === 'failed' ? ExitCode.FAILURE : ExitCode.OK;
+
+/** Poll until the phase is terminal, printing each phase change once. */
+async function waitForRun({ api, gameId, admissionId, apiUrl, sleep, now, onPhase }) {
+  let last = null;
+  for (;;) {
+    const view = statusView(gameId, apiUrl, await readHostedRun({ api, gameId, admissionId }), now());
+    if (view.phase !== last) { last = view.phase; onPhase(view); }
+    if (TERMINAL_PHASES.includes(view.phase)) return view;
+    await sleep();
+  }
+}
+
+const phaseLine = flags => row => { if (!flags.json) ui.info(`${row.label}: ${row.detail}`); };
+
+/**
+ * `hosted run` with no saved quote: the newest eligible build (or --build), a
+ * fresh quote, the price and consent printed from it, one confirmation, one
+ * admission. The admission keeps the saved-quote path's journal and never retries.
+ */
+export async function hostedRunDirect(flags = {}, deps = {}) {
+  if (flags.json && !flags.yes && !deps.confirm) throw new CliError('A hosted run charges prepaid funds. Use --yes with --json. Nothing was charged.');
+  const context = deps.context || await createContext({ apiUrl: flags.apiUrl, repoRoot: flags.repoRoot, requireAuth: true });
+  const now = deps.now || Date.now, sleep = deps.sleep || (() => sleepFor(POLL_MS));
+  return withAuthHandling(context, async () => {
+    const api = context.api, apiUrl = api.apiUrl, gameId = resolveGameId(flags, context.config);
+    const { offer, build, funding } = await prepareHostedRun({ api, apiUrl, gameId, buildId: flags.build,
+      persona: flags.persona || DEFAULT_PERSONAS[0], includeVideo: Boolean(flags.video), now });
+    if (!flags.json) {
+      ui.info(`Build ${build.buildId}${build.entrypoint ? ` (${build.entrypoint})` : ''}${flags.build ? '' : ', the newest ready build'}.`);
+      hostedQuoteLines(offer).forEach(line => ui.info(line));
+      hostedConsentLines(offer).forEach(line => ui.info(line));
+    }
+    const short = fundingShortfall(offer.quote, funding);
+    if (short) {
+      const topUp = short.requiredTopUpCents ? ` Add at least ${dollars(short.requiredTopUpCents)} of prepaid funds, then run this again.` : ' Add prepaid funds, then run this again.';
+      throw new CliError(`The balance does not meet this hosted run's funding requirement. Nothing was charged.${topUp}`, ExitCode.ENVIRONMENT);
+    }
+    const confirm = deps.confirm || (question => ui.confirm(question, { yes: Boolean(flags.yes) }));
+    if (!await confirm(confirmQuestion(offer))) {
+      if (flags.json) ui.json({ state: 'declined', gameId, buildId: build.buildId, walletMutationRequested: false });
+      else ui.info('Declined. Nothing was charged.');
+      return ExitCode.CANCELED;
+    }
+    const admitted = await admitHostedOffer({ offer, api, apiUrl, repoRoot: context.repoRoot, now });
+    const reportUrl = jobLink(gameId, admitted.jobId, apiUrl);
+    const result = { state: admitted.state, admissionId: admitted.admissionId, jobId: admitted.jobId, gameId, buildId: build.buildId,
+      persona: offer.request.personas[0], totalPriceCents: admitted.totalPriceCents, dueNowCents: offer.quote.dueNowCents,
+      journal: admitted.journal, reportUrl };
+    if (!flags.json) {
+      ui.ok(`Paid ${dollars(offer.quote.dueNowCents)}. Hosted run ${admitted.admissionId}, job ${admitted.jobId}.`);
+      ui.info(`Check on it with: ravensight-playtest hosted status ${admitted.admissionId}`);
+    }
+    if (!flags.wait) {
+      if (flags.json) ui.json(result);
+      else ui.info(`Report: ${reportUrl}`);
+      return ExitCode.OK;
+    }
+    const view = await waitForRun({ api, gameId, admissionId: admitted.admissionId, apiUrl, sleep, now, onPhase: phaseLine(flags) });
+    if (flags.json) ui.json({ ...result, status: view });
+    else printOutcome(view);
+    return exitFor(view);
+  });
+}
+
+export async function hostedStatus(admissionId, flags = {}, deps = {}) {
+  const context = deps.context || await createContext({ apiUrl: flags.apiUrl, repoRoot: flags.repoRoot, requireAuth: true });
+  const now = deps.now || Date.now, sleep = deps.sleep || (() => sleepFor(POLL_MS));
+  return withAuthHandling(context, async () => {
+    const api = context.api, apiUrl = api.apiUrl, gameId = resolveGameId(flags, context.config);
+    const view = flags.wait
+      ? await waitForRun({ api, gameId, admissionId, apiUrl, sleep, now, onPhase: phaseLine(flags) })
+      : statusView(gameId, apiUrl, await readHostedRun({ api, gameId, admissionId }), now());
+    if (flags.json) ui.json(view); else printOutcome(view);
+    return flags.wait ? exitFor(view) : ExitCode.OK;
+  });
+}
+
+export async function hostedCancel(admissionId, flags = {}, deps = {}) {
+  if (flags.json && !flags.yes && !deps.confirm) throw new CliError('Use --yes with --json to cancel a hosted run. Nothing was canceled.');
+  const context = deps.context || await createContext({ apiUrl: flags.apiUrl, repoRoot: flags.repoRoot, requireAuth: true });
+  const now = deps.now || Date.now;
+  return withAuthHandling(context, async () => {
+    const api = context.api, apiUrl = api.apiUrl, gameId = resolveGameId(flags, context.config);
+    const confirm = deps.confirm || (question => ui.confirm(question, { yes: Boolean(flags.yes) }));
+    if (!await confirm(`Cancel hosted run ${admissionId}? Work already completed follows the accepted policy; unstarted work is refunded during settlement.`)) {
+      if (flags.json) ui.json({ state: 'kept', admissionId });
+      else ui.info('Nothing was canceled.');
+      return ExitCode.CANCELED;
+    }
+    await cancelHostedRun({ api, gameId, admissionId });
+    const view = statusView(gameId, apiUrl, await readHostedRun({ api, gameId, admissionId }), now());
+    if (flags.json) ui.json(view);
+    else {
+      ui.ok(view.phase === 'canceled' ? `Hosted run ${admissionId} is canceled.` : `Cancellation requested for hosted run ${admissionId}.`);
+      printOutcome(view);
+    }
+    return ExitCode.OK;
+  });
+}

package/src/commands/profile.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { mkdir } from 'node:fs/promises';
 import { optionsFrom, unknownOptionNotes } from '../run/args.js';
 import { settleFailureLine } from '../run/settle.js';
+import { failureReason } from '../run/failureReason.js';
 import { getDeps } from '../run/deps.js';
 import EXIT from '../run/exit.js';
 import { createHeartbeat } from '../run/heartbeat.js';
@@ -234,7 +235,7 @@ async function safeFail({ api, gameId, jobId, runId, error, log }) {
   try {
     await api.runs.complete(gameId, jobId, runId, {
       state: 'failed',
-      reason: String(error && error.message).slice(0, 400),
+      reason: failureReason(error, { fallback: 'the profile stopped on an error' }),
       quit_reason: 'error'
     });
   } catch (completeError) {

package/src/commands/run.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { buildAggregate, writeAggregate } from '../run/aggregate.js';
 import { reportPrOutcomes } from '../run/labsOutcome.js';
 import { finishJob } from '../run/settle.js';
+import { driverStartReason, failureReason } from '../run/failureReason.js';
 import { optionsFrom, unknownOptionNotes } from '../run/args.js';
 import { controllerPlan, quoteMatchesPlan, runsMatchPlan } from '../run/controllers.js';
 import { getDeps } from '../run/deps.js';
@@ -19,8 +20,10 @@ import { configureSpendHold, createModelClient, ModelUnavailableError, ProxyErro
 import { jobDir, runDir as runDirFor, JOB_FILES, RUN_FILES } from '../run/paths.js';
 import { readBridgeConfig } from "../run/drivers/stdio.js";
 import { WEBDRIVER_NAMES, readDriverConfig } from '../run/drivers/webdriver.js';
-import { automationChecks } from './check.js';
+import { BROWSER_FIX, automationChecks } from './check.js';
 import { runPersona } from '../run/personaLoop.js';
+import { runModelBudgetUsd } from '../run/budgetReserve.js';
+import { missingScopeMessage, missingScopes } from '../auth/scopes.js';
 import { tracesWanted } from '../run/acceptance.js';
 import { cleanCommit } from '../run/replay.js';
 import { loadLocalBrief, localBriefProblems } from '../briefLocal.js';
@@ -102,6 +105,11 @@ async function run(flags, injected, deps, log) {
   const setup = await resolveSetup(deps, options, log);
   if (setup.code !== undefined) return setup.code;
   const { context, gameId, repoRoot, apiUrl, cliVersion, api } = setup;
+  const scopeRefusal = await tokenScopeRefusal(api);
+  if (scopeRefusal !== null) {
+    log(scopeRefusal.message);
+    return scopeRefusal.code;
+  }
 
   let controllers;
   try { controllers = controllerPlan(options); } catch (error) { log(error.message); return EXIT.ENVIRONMENT; }
@@ -678,7 +686,25 @@ export async function playPersonaRun({
   const headless = driverName === 'godot_driver' ? options.headless === true : options.headed !== true;
   // A validate run plays its own side's checkout and its pair's seed.
   const runTarget = entry.target || target;
-  const driver = await makeDriver(driverName, driverOptions({ headless, driverName, target: runTarget, directory, entry, jobId, keyModifier: options.keyModifier, godotPath: options.godotPath, realtime: options.realtime }));
+  let driver;
+  try {
+    driver = await makeDriver(driverName, driverOptions({ headless, driverName, target: runTarget, directory, entry, jobId, keyModifier: options.keyModifier, godotPath: options.godotPath, realtime: options.realtime }));
+  } catch (error) {
+    // A driver that cannot even be built (the browser package missing, say) is
+    // what a new machine hits first. The run is completed as failed now, with
+    // what to do, rather than left queued for the server's sweep.
+    if (inFlight) inFlight.delete(runId);
+    const reason = driverStartReason(driverName, error, { browserFix: BROWSER_FIX });
+    log(`run ${runId} (${persona.slug}) failed: ${reason}`);
+    await stateFile.patchRun(repoRoot, journal, runId, { state: 'failed', error: reason, quit_reason: 'error', report_written: false }).catch(() => {});
+    try {
+      await api.runs.complete(gameId, jobId, runId, { state: 'failed', reason, actions_taken: 0, quit_reason: 'error' });
+      await stateFile.patchRun(repoRoot, journal, runId, { completed: true }).catch(() => {});
+    } catch (completeError) {
+      log(`run ${runId} (${persona.slug}): could not be completed as failed (${String(completeError && completeError.message)}). "ravensight-playtest resume" can retry it.`);
+    }
+    return { runId, persona: persona.slug, state: 'failed', quitReason: 'error', error };
+  }
   // The ledger is created here rather than inside the loop so the heartbeat
   // can feed it the server's own figure for what this run has spent. Prices
   // are server side only, so that answer is the only real one.
@@ -719,6 +745,7 @@ export async function playPersonaRun({
       signal: options.signal,
       client,
       api,
+      modelBudgetUsd: runModelBudgetUsd(entry),
       gameId,
       jobId,
       runId,
@@ -757,7 +784,18 @@ export async function playPersonaRun({
       return { runId, persona: persona.slug, state: 'interrupted', error };
     }
     if (inFlight) inFlight.delete(runId);
-    const failed = error.outcome || { state: 'failed', quitReason: 'error', actionsTaken: 0, report: null, reportLint: [], reachedState: 'playing' };
+    const crashed = error.outcome || { state: 'failed', quitReason: 'error', actionsTaken: 0, report: null, reportLint: [], reachedState: 'playing' };
+    // The server stores this as the run's reason and the dashboard shows it. A
+    // crash outside the persona loop's own handler carries no detail, so the
+    // caught error's message stands in, redacted and cut to 400 characters.
+    // A run the server holds at `launching` never got its game or browser up,
+    // so the reason also says what to do about it.
+    const failed = {
+      ...crashed,
+      quitDetail: crashed.reachedState === 'launching'
+        ? driverStartReason(driverName, error, { detail: crashed.quitDetail, browserFix: BROWSER_FIX })
+        : failureReason(error, { detail: crashed.quitDetail })
+    };
     await stateFile.patchRun(repoRoot, journal, runId, {
       state: failed.state,
       error: String(error && error.message),
@@ -894,6 +932,22 @@ export function durationBody(duration) {
   return { wall_seconds: value('wall_seconds'), model_seconds: value('model_seconds') };
 }
 
+/**
+ * The reason `complete` sends. The server stores it as the run's
+ * `stateReason` and the dashboard shows it as why the run ended, so a run that
+ * succeeded sends none: in 0.7.1 a succeeded run sent its quit detail, which
+ * was the persona's whole closing message, report text included. Any other
+ * state sends its detail, redacted and cut like every other reason.
+ *
+ * @param {Object} outcome
+ * @returns {string}
+ */
+export function completionReason(outcome) {
+  if (!outcome || outcome.state === 'succeeded') return '';
+  const detail = String(outcome.quitDetail || '').trim();
+  return detail ? failureReason(null, { detail }) : '';
+}
+
 /**
  * Upload the run directory and complete the run, through cli-core's
  * `finalizeRun` so the 422 `upload_unverified` repair pass lives in one place.
@@ -913,7 +967,7 @@ export function durationBody(duration) {
 export async function deliver({ deps, api, gameId, jobId, runId, directory, outcome, options, log, journal, repoRoot, delivery = null, extraBody = null }) {
   const body = {
     state: outcome.state,
-    reason: outcome.quitDetail || '',
+    reason: completionReason(outcome),
     actions_taken: outcome.actionsTaken,
     quit_reason: outcome.quitReason,
     ...(extraBody || {})
@@ -1352,6 +1406,30 @@ export async function godotRefusal({ driverName, godotPath, projectDir, injected
  *
  * @returns {Promise<Object>}
  */
+/**
+ * A token that cannot finish a run is refused before anything is priced,
+ * registered or charged (../auth/scopes.js). Null when the token has what a
+ * run needs, or when its scopes cannot be read: an older server that lists
+ * none, or a network failure, leaves the server's own checks in charge.
+ *
+ * @param {Object} api
+ * @returns {Promise<{code: number, message: string}|null>}
+ */
+export async function tokenScopeRefusal(api) {
+  if (!api || !api.cli || typeof api.cli.whoami !== 'function') return null;
+  let whoami;
+  try {
+    whoami = await api.cli.whoami();
+  } catch (error) {
+    if (error && (error.status === 401 || error.status === 403)) {
+      return { code: EXIT.AUTH, message: `The server refused this login (${String(error.message || error.status)}). Log in again with "ravensight-playtest login". Nothing was registered or charged.` };
+    }
+    return null;
+  }
+  const missing = missingScopes(whoami && whoami.scopes);
+  return missing && missing.length > 0 ? { code: EXIT.AUTH, message: missingScopeMessage(missing) } : null;
+}
+
 export async function resolveSetup(deps, options, log) {
   let context;
   try {
@@ -1462,7 +1540,10 @@ export async function loadRunReports(repoRoot, jobId, personaRuns, journal = nul
     const file = path.join(runDirFor(repoRoot, jobId, entry.run_id), RUN_FILES.reportJson);
     try {
       const report = withoutRunnerEvidence(JSON.parse(await readFile(file, 'utf8')), await readRunnerEvidence(path.dirname(file)));
-      out.push({ runId: entry.run_id, persona: entry.persona, ...(entry.controller ? { controller: entry.controller } : {}), state: recorded?.state || entry.state || (report && report.partial === true ? 'budget_exceeded' : 'succeeded'), report });
+      // report.md, for the aggregate's "How the personas felt": each persona's
+      // in-character section in its own words.
+      const markdown = await readFile(path.join(path.dirname(file), RUN_FILES.reportMd), 'utf8').catch(() => null);
+      out.push({ runId: entry.run_id, persona: entry.persona, ...(entry.controller ? { controller: entry.controller } : {}), state: recorded?.state || entry.state || (report && report.partial === true ? 'budget_exceeded' : 'succeeded'), report, markdown });
     } catch {
       out.push({ runId: entry.run_id, persona: entry.persona, ...(entry.controller ? { controller: entry.controller } : {}), state: 'failed', report: null });
     }