ravensight-playtest 0.6.0 → 0.7.2

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/lists.js

@@ -0,0 +1,206 @@
+import { createContext } from '../api/index.js';
+import { ApiError } from '../api/errors.js';
+import { resolveGameId } from '../config.js';
+import { withAuthHandling } from '../auth/session.js';
+import { CliError, ExitCode } from '../errors.js';
+import { ui } from '../ui/index.js';
+
+/**
+ * What `punch` and `tape` share: the game, the client, the refusals in plain
+ * words, and how an item is printed.
+ *
+ * The punch list holds what has to be finished before handover, closed one at
+ * a time. Blue tape holds small first-impression annoyances, captured fast and
+ * promoted to the punch list when they matter. Both live on the server under
+ * the game's Labs lists, so the dashboard and this CLI read the same items.
+ */
+
+export const LIST_NAMES = Object.freeze({ punch: 'punch list', tape: 'blue tape list' });
+export const STATUSES = Object.freeze(['open', 'done', 'dropped', 'all']);
+export const ITEM_ID = /^li_[A-Za-z0-9_-]+$/;
+export const LIMIT = 500;
+
+/**
+ * Run `fn` with the client and the game this repo is linked to (or `--game`).
+ * @param {Object} flags
+ * @param {Object} deps test seam: context
+ * @param {(setup: {api: Object, gameId: string}) => Promise<number>} fn
+ * @returns {Promise<number>}
+ */
+export async function withList(flags, deps, fn) {
+  const context = deps.context || await createContext({ apiUrl: flags.apiUrl, repoRoot: flags.repoRoot, requireAuth: true });
+  return withAuthHandling(context, async () => {
+    const gameId = resolveGameId(flags, context.config);
+    return fn({ api: context.api, gameId });
+  });
+}
+
+/**
+ * A refusal from the lists routes as a sentence a person can act on. Anything
+ * this does not recognise is handed back unchanged for `report` to print.
+ *
+ * @param {unknown} error
+ * @param {{list: string, itemId?: string|null}} where
+ * @returns {unknown}
+ */
+export function listError(error, { list, itemId = null }) {
+  if (!(error instanceof ApiError) && !(error && typeof error.status === 'number' && typeof error.code === 'string')) return error;
+  const name = LIST_NAMES[list] || 'list';
+  if (error.code === 'labs_not_enabled') {
+    return new CliError(
+      `The ${name} is part of Ravensight Labs (beta). Labs is not on for this game.`,
+      ExitCode.ENVIRONMENT,
+      { hint: 'Turn Labs on from the Labs page in the dashboard. Nothing was changed.' }
+    );
+  }
+  if (error.code === 'item_closed') {
+    return new CliError(`${itemId || 'That item'} is closed. Reopen it first, then promote it.`, ExitCode.FAILURE);
+  }
+  if (error.code === 'quota_exceeded') {
+    return new CliError('This account has no AI units left. Add funds, then try again. Nothing was charged.', ExitCode.FAILURE);
+  }
+  if (error.code === 'labs_list_attempts') {
+    return new CliError('Too many drafts came back empty this hour. Try again later. Nothing was charged.', ExitCode.FAILURE);
+  }
+  if (error.code === 'ai_unavailable') {
+    return new CliError('The AI service is not available right now. Try again later. Nothing was charged.', ExitCode.FAILURE);
+  }
+  if (error.code === 'list_full') {
+    return new CliError(
+      `The ${name} already has ${LIMIT} open items. Close or drop some, then add this one.`,
+      ExitCode.FAILURE
+    );
+  }
+  if (error.status === 404) {
+    if (itemId) {
+      return new CliError(
+        `No item ${itemId} is on this game's ${name}.`,
+        ExitCode.FAILURE,
+        { hint: `Run "ravensight-playtest ${list} list --status all" to see the item ids.` }
+      );
+    }
+    return new CliError(
+      `This game has no ${name} that this token can see.`,
+      ExitCode.FAILURE,
+      { hint: 'Run "ravensight-playtest check" to confirm the game is linked. An older server has no lists yet.' }
+    );
+  }
+  return error;
+}
+
+/**
+ * Call the server and turn its refusals into sentences.
+ * @template T
+ * @param {() => Promise<T>} call
+ * @param {{list: string, itemId?: string|null}} where
+ * @returns {Promise<T>}
+ */
+export async function guarded(call, where) {
+  try {
+    return await call();
+  } catch (error) {
+    throw listError(error, where);
+  }
+}
+
+/**
+ * Refuse an id that cannot be an item before asking the server about it.
+ * @param {string} itemId
+ */
+export function requireItemId(itemId) {
+  const value = String(itemId || '').trim();
+  if (!ITEM_ID.test(value)) {
+    throw new CliError(`"${value}" is not an item id. Item ids start with li_.`, ExitCode.FAILURE, {
+      hint: 'Run "ravensight-playtest punch list" or "ravensight-playtest tape list" to see them.'
+    });
+  }
+  return value;
+}
+
+/**
+ * Refuse empty text here rather than spend a round trip on it.
+ * @param {string} text
+ */
+export function requireText(text) {
+  const value = String(text || '').trim();
+  if (!value) throw new CliError('Say what the item is, in quotes.', ExitCode.FAILURE);
+  return value;
+}
+
+/** @param {string|undefined} status */
+export function requireStatus(status) {
+  if (status === undefined || status === null) return 'open';
+  if (!STATUSES.includes(status)) {
+    throw new CliError(`--status takes ${STATUSES.join(', ')}.`, ExitCode.FAILURE);
+  }
+  return status;
+}
+
+/** Where an item came from, in a few words. */
+export function sourceWords(source) {
+  if (!source || !source.kind || source.kind === 'manual') return 'manual';
+  const kind = String(source.kind).replace(/_/g, ' ');
+  return source.ref ? `${kind} ${source.ref}` : kind;
+}
+
+/** The plain-language hints under an item. A hint, never a block. */
+export function printHints(item) {
+  const issues = item && item.plain_check && Array.isArray(item.plain_check.issues) ? item.plain_check.issues : [];
+  for (const issue of issues) {
+    if (issue && issue.message) ui.info(`  hint: ${issue.message}`);
+  }
+  return issues.length;
+}
+
+/**
+ * Print a list answer as a table, or say it is empty.
+ * @param {Object} answer `{ items, counts }`
+ * @param {string} list
+ * @param {string} status
+ */
+export function printList(answer, list, status) {
+  const items = answer && Array.isArray(answer.items) ? answer.items : [];
+  const name = LIST_NAMES[list];
+  if (items.length === 0) {
+    ui.info(status === 'all' ? `The ${name} is empty.` : `The ${name} has no ${status} items.`);
+  } else {
+    ui.table(items.map(item => ({
+      item_id: item.item_id,
+      status: item.status,
+      text: item.text,
+      source: sourceWords(item.source) + (item.promoted_to ? `, now ${item.promoted_to}` : '') + (item.fix_job_id ? `, fix ${item.fix_job_id}` : '')
+    })), [
+      { key: 'item_id', label: 'ITEM' },
+      { key: 'status', label: 'STATUS' },
+      { key: 'text', label: 'TEXT' },
+      { key: 'source', label: 'SOURCE' }
+    ]);
+  }
+  const counts = answer && answer.counts;
+  if (counts) {
+    ui.blank();
+    ui.info(`${counts.open ?? 0} open, ${counts.done ?? 0} done, ${counts.dropped ?? 0} dropped.`);
+  }
+}
+
+/**
+ * Find one item by id, for `fix li_...`. The punch list first, because that is
+ * where a finding to fix usually sits, then blue tape on a 404.
+ *
+ * @param {Object} api
+ * @param {string} gameId
+ * @param {string} itemId
+ * @returns {Promise<{item: Object, list: string}|null>}
+ */
+export async function findListItem(api, gameId, itemId) {
+  for (const list of ['punch', 'tape']) {
+    try {
+      const answer = await api.labs.lists.get(gameId, list, itemId);
+      if (answer && answer.item) return { item: answer.item, list };
+    } catch (error) {
+      if (error && error.status === 404) continue;
+      throw listError(error, { list, itemId });
+    }
+  }
+  return null;
+}

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/punch.js

@@ -0,0 +1,116 @@
+import { ui } from '../ui/index.js';
+import { ExitCode } from '../errors.js';
+import { guarded, printHints, printList, requireItemId, requireStatus, requireText, sourceWords, withList } from './lists.js';
+
+/**
+ * `ravensight-playtest punch`: the punch list (Labs beta).
+ *
+ * What has to be finished before handover, closed one item at a time. Reading,
+ * adding and closing are free. `draft` asks for proposals from the game's
+ * findings and specs, which is one AI unit, and saves nothing unless
+ * `--accept` is passed. Nothing here closes an item on its own: `fix li_...`
+ * records the fix job on the item and leaves closing it to a person.
+ */
+
+const LIST = 'punch';
+
+/** `punch list [--status open|done|dropped|all]` */
+export async function punchList(flags = {}, deps = {}) {
+  const status = requireStatus(flags.status);
+  return withList(flags, deps, async ({ api, gameId }) => {
+    const answer = await guarded(() => api.labs.lists.list(gameId, LIST, { status }), { list: LIST });
+    if (flags.json) {
+      ui.json(answer);
+      return ExitCode.OK;
+    }
+    printList(answer, LIST, status);
+    return ExitCode.OK;
+  });
+}
+
+/** `punch add "<text>"` */
+export async function punchAdd(text, flags = {}, deps = {}) {
+  const value = requireText(text);
+  return withList(flags, deps, async ({ api, gameId }) => {
+    const answer = await guarded(() => api.labs.lists.add(gameId, LIST, { text: value }), { list: LIST });
+    if (flags.json) {
+      ui.json(answer);
+      return ExitCode.OK;
+    }
+    printAdded(answer);
+    return ExitCode.OK;
+  });
+}
+
+/** `punch done <li_id>` and `punch drop <li_id>` */
+export async function punchClose(itemId, status, flags = {}, deps = {}) {
+  const id = requireItemId(itemId);
+  return withList(flags, deps, async ({ api, gameId }) => {
+    const answer = await guarded(() => api.labs.lists.update(gameId, LIST, id, { status }), { list: LIST, itemId: id });
+    if (flags.json) {
+      ui.json(answer);
+      return ExitCode.OK;
+    }
+    const text = answer && answer.item && answer.item.text ? `: ${answer.item.text}` : '';
+    ui.ok(`${status === 'done' ? 'Done' : 'Dropped'} ${id}${text}`);
+    return ExitCode.OK;
+  });
+}
+
+/** `punch draft [--accept]` */
+export async function punchDraft(flags = {}, deps = {}) {
+  return withList(flags, deps, async ({ api, gameId }) => {
+    if (!flags.json) {
+      ui.info('Drafting a punch list is one AI unit. It is not charged when there is nothing to propose.');
+      ui.info(flags.accept ? 'Every proposal will be added to the punch list.' : 'Nothing is saved. Pass --accept to add the proposals.');
+    }
+    const confirm = deps.confirm || ui.confirm;
+    if (!flags.yes && !(await confirm('Draft the punch list?', { yes: flags.yes }))) {
+      ui.info('Nothing was charged. Pass --yes to draft without a terminal.');
+      return ExitCode.CANCELED;
+    }
+    const answer = await guarded(() => api.labs.lists.draft(gameId), { list: LIST });
+    const proposals = answer && Array.isArray(answer.proposals) ? answer.proposals : [];
+    const added = [];
+    if (flags.accept) {
+      try {
+        for (const proposal of proposals) {
+          const body = proposal.source ? { text: proposal.text, source: proposal.source } : { text: proposal.text };
+          added.push(await guarded(() => api.labs.lists.add(gameId, LIST, body), { list: LIST }));
+        }
+      } catch (error) {
+        // Say what was saved before the refusal, so nobody adds it twice.
+        if (!flags.json) for (const saved of added) printAdded(saved);
+        throw error;
+      }
+    }
+    if (flags.json) {
+      ui.json({ ...answer, ...(flags.accept ? { added } : {}) });
+      return ExitCode.OK;
+    }
+    if (proposals.length === 0) {
+      ui.info('No proposals, so nothing was charged.');
+      return ExitCode.OK;
+    }
+    const units = Number(answer.units) || 0;
+    ui.info(`${proposals.length} proposal${proposals.length === 1 ? '' : 's'}, ${units} AI unit${units === 1 ? '' : 's'} charged:`);
+    if (flags.accept) {
+      for (const saved of added) printAdded(saved);
+      return ExitCode.OK;
+    }
+    proposals.forEach((proposal, index) => {
+      ui.info(`  ${index + 1}. ${proposal.text} (${sourceWords(proposal.source)})`);
+    });
+    ui.blank();
+    ui.info('Nothing was saved. Add the ones you want with "ravensight-playtest punch add".');
+    return ExitCode.OK;
+  });
+}
+
+/** One added item, with its plain-language hints under it. */
+export function printAdded(answer) {
+  const item = answer && answer.item ? answer.item : {};
+  if (answer && answer.existing) ui.info(`Already on the list: ${item.item_id}, ${item.text}`);
+  else ui.ok(`Added ${item.item_id}: ${item.text}`);
+  if (printHints(item) > 0) ui.info('  These hints follow the rules of Simplified Technical English. They never block an item.');
+}

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 });
     }