ravensight-playtest 0.7.0 → 0.7.5

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

package/src/hosted/buildStatus.js

@@ -0,0 +1,35 @@
+import { printable } from '../ui/index.js';
+
+const base = game => `/api/v1/games/${encodeURIComponent(game)}/playtest/hosted`;
+
+const LABELS = {
+  uploading: 'uploading',
+  awaiting_validation: 'waiting for its archive check',
+  ready: 'ready',
+  graphical_static_validated: 'archive check passed',
+  rejected: 'not accepted',
+  deleting: 'being removed'
+};
+
+// Server text is one fixed sentence; still print it as one plain line.
+const line = text => printable(String(text || '')).replace(/\s+/g, ' ').trim().slice(0, 300);
+
+/** The plain lines that describe one build: its state, why it was refused, and the hold. */
+export function buildStatusLines(build) {
+  const state = build?.state === 'deleting' && build.rejection ? 'not accepted, being removed' : (LABELS[build?.state] || line(build?.state) || 'unknown');
+  const lines = [`${line(build?.buildId)}${build?.entrypoint ? ` (${line(build.entrypoint)})` : ''}: ${state}.`];
+  if (build?.rejection?.message) lines.push(`  Why: ${line(build.rejection.message)}`);
+  else if (build?.state === 'awaiting_validation') lines.push('  Validation is required before a run. Check again in a minute.');
+  if (build?.holdReturn?.message) lines.push(`  ${line(build.holdReturn.message)}`);
+  if (build?.safetyHold) lines.push('  A run of this build was stopped by the safety check, so it cannot be quoted until that hold is cleared.');
+  return lines;
+}
+
+/** The game's private hosted builds, newest first, optionally one of them. */
+export async function readHostedBuilds({ api, gameId, buildId }) {
+  const answer = await api.request('GET', `${base(gameId)}/builds`, { idempotent: true });
+  const builds = (Array.isArray(answer.body?.builds) ? answer.body.builds : [])
+    .filter(build => build && typeof build.buildId === 'string')
+    .sort((a, b) => (Date.parse(b.createdAt) || 0) - (Date.parse(a.createdAt) || 0));
+  return buildId ? builds.filter(build => build.buildId === buildId) : builds;
+}

package/src/hosted/buildUpload.js

@@ -42,6 +42,28 @@ export async function putArchive(archive, transfer, { fetchImpl = globalThis.fet
   } finally { stream.destroy(); }
 }
 
+/**
+ * The profile to upload under: the one named, or the only one advertised. With
+ * several and none named, the error lists them so the person can pick one.
+ */
+export function chooseProfile(profiles, requested) {
+  const advertised = profiles.filter(profile => typeof profile?.profileVersion === 'string' && profile.profileVersion);
+  const names = [...new Set(advertised.map(profile => profile.profileVersion))];
+  const list = names.map(name => {
+    const format = advertised.find(profile => profile.profileVersion === name).format;
+    return format ? `${name} (${format})` : name;
+  }).join(', ');
+  if (!names.length) fail('No build profile is advertised for this game right now. Nothing was charged.');
+  if (!requested) {
+    if (names.length === 1) return names[0];
+    fail(`Several build profiles are available. Choose one with --profile: ${list}. Nothing was charged.`);
+  }
+  if (advertised.filter(profile => profile.profileVersion === requested).length !== 1) {
+    fail(`"${requested}" is not an advertised build profile. Choose one with --profile: ${list}. Nothing was charged.`);
+  }
+  return requested;
+}
+
 async function journalOnce(filename, value) {
   await mkdir(path.dirname(filename), { recursive: true, mode: 0o700 });
   let handle;
@@ -58,13 +80,13 @@ async function journalOnce(filename, value) {
 // the only wallet-mutating POST. No model or gameplay API is called here.
 export async function uploadHostedBuild({ filename, gameId, profileVersion, entrypoint, repoRoot, api,
   apiUrl, journalPath, dryRun = false, confirm, onPrepared = () => {}, onProgress = () => {}, fetchImpl, signal } = {}) {
-  if (!gameId || !profileVersion || typeof confirm !== 'function') fail('Choose a game, ready profile and upload confirmation.');
+  if (!gameId || typeof confirm !== 'function') fail('Choose a game and upload confirmation.');
   onProgress({ phase: 'capabilities' });
   const caps = body(await api.request('GET', `${base(gameId)}/capabilities`, { idempotent: true }));
   const profiles = caps?.recorded?.profiles;
   if (!caps?.recorded?.available || !Array.isArray(profiles)) fail('Recorded game uploads are not available for this game.');
+  profileVersion = chooseProfile(profiles, profileVersion);
   const matching = profiles.filter(profile => profile.profileVersion === profileVersion);
-  if (matching.length !== 1) fail('Choose exactly one currently advertised ready profile.');
   const profile = matching[0], limits = profile.capacity ? limitsFromProfile(profile) : buildLimits(caps.limits);
   const offer = profile.reservationOffer;
   if (!offer || offer.amountCents !== 49 || offer.currency !== 'USD' || offer.purpose !== 'validation_hold'

package/src/hosted/recordedRun.js

@@ -1,9 +1,10 @@
 import { createHash } from 'node:crypto';
 import { mkdir, open, access, rename } from 'node:fs/promises';
 import path from 'node:path';
-import { CliError } from '../errors.js';
+import { CliError, ExitCode } from '../errors.js';
 import { ApiError } from '../api/errors.js';
 import { stableStringify } from '../fsutil.js';
+import { printable } from '../ui/index.js';
 
 const MAX_QUOTE_BYTES = 1024 * 1024;
 const CONSENT_KEYS = ['quoteId', 'planHash', 'profileVersion', 'controllers', 'includeVideo', 'includeTranscript',
@@ -140,7 +141,7 @@ export function hostedQuoteLines(offer) {
     ...q.localBreakdown.map(row => `${row.count} ${row.unit} at ${money(row.unitCents)} each: ${money(row.count * row.unitCents)}.`),
     ...q.computeBreakdown.map(row => `${row.controller} hosted compute: ${money(row.priceCents)}.`),
     `Total ${money(q.totalPriceCents)}; already reserved ${money(q.alreadyReservedCents)}; due now ${money(q.dueNowCents)} from prepaid funds. No top-up is performed.`,
-    `Video: ${r.includeVideo ? 'included' : 'off'}; transcript: ${r.includeTranscript ? 'included' : 'off'}.`,
+    `Video: ${r.includeVideo ? 'included' : 'off'}. Hosted runs save no transcript.`,
     `Customer failure: ${q.customerFailure}; cancellation after start: ${q.cancelAfterStart}. Price ${q.priceVersion}; refund policy ${q.policyVersion}.`,
     `Quote expires ${new Date(q.expiresAt).toISOString()}.`];
 }
@@ -157,8 +158,42 @@ export async function runHostedQuote({ filename, api, apiUrl, repoRoot, confirm,
   if (profile.driver !== offer.request.driver || funding?.eligible === false || offer.quote.funding?.eligible === false) fail('The server no longer advertises this profile or sufficient prepaid funding. Nothing was charged.');
   await onPrepared(offer);
   if (typeof confirm !== 'function') fail('The full hosted quote must be confirmed before admission.');
-  if (!await confirm(`Pay ${money(offer.quote.dueNowCents)} now (${money(offer.quote.totalPriceCents)} total) for the quoted Standard then Jev runs and the evidence options shown?`)) return { state: 'declined', walletMutationRequested: false };
+  if (!await confirm(confirmQuestion(offer))) return { state: 'declined', walletMutationRequested: false };
+  return admitHostedOffer({ offer, api, apiUrl, repoRoot, now });
+}
+
+export const confirmQuestion = offer => `Pay ${money(offer.quote.dueNowCents)} now (${money(offer.quote.totalPriceCents)} total) for the quoted Standard then Jev runs and the evidence options shown?`;
+
+// Refusals the server makes before any charge: the quote or consent was not
+// accepted, funding or capacity said no, or the quote is gone. The original
+// intent is kept on disk all the same; only the message differs.
+const DEFINITE_REFUSALS = new Set(['hosted_funding_required', 'quote_not_accepted', 'not_found', 'recorded_unavailable',
+  'recorded_setup_required', 'hosted_global_capacity', 'too_many_active_hosted_runs', 'hosted_daily_capacity',
+  'hosted_build_too_large', 'hosted_build_safety_hold']);
+
+export function hostedRefusalMessage(error) {
+  const code = error?.code;
+  if (code === 'hosted_funding_required') {
+    const f = error.body?.funding;
+    const topUp = Number.isSafeInteger(f?.requiredTopUpCents) && f.requiredTopUpCents > 0 ? ` Add at least ${money(f.requiredTopUpCents)} of prepaid funds, then request a new quote.` : ' Add prepaid funds, then request a new quote.';
+    return `The server refused the run for funding. Nothing was charged.${topUp}`;
+  }
+  if (code === 'quote_not_accepted') return 'The server did not accept this consent for the quote. Nothing was charged; request a new quote.';
+  if (['hosted_global_capacity', 'too_many_active_hosted_runs'].includes(code)) return 'Hosted capacity is busy. Nothing was charged. Wait for an existing run to finish, then retry. Adding funds does not increase capacity.';
+  if (code === 'hosted_daily_capacity') return 'Today\'s hosted run allowance is used up. Nothing was charged. Try again after the daily limit resets.';
+  if (code === 'recorded_setup_required') return `${error.message || 'Complete the playtest brief and choose an available persona.'} Nothing was charged.`;
+  if (code === 'not_found') return 'The quote is no longer available. Nothing was charged; request a new quote.';
+  if (code === 'hosted_build_too_large') return 'This build is too large to play on a hosted machine: hosted playtests play builds up to 300 MiB unpacked. Make the build smaller and upload it again. Nothing was charged.';
+  if (code === 'hosted_build_safety_hold') return 'This build was stopped for safety during a hosted playtest and cannot run again until an admin reviews and clears it in the dashboard. Nothing was charged.';
+  return 'Hosted playtests are not available right now. Nothing was charged.';
+}
+
+// A saved durable intent is never retried. The journal is fsynced before the
+// only wallet-mutating POST and the server receives a stable key for the plan.
+export async function admitHostedOffer({ offer, api, apiUrl, repoRoot, now = Date.now }) {
   validateHostedOffer(offer, apiUrl, now());
+  const identity = digest({ apiUrl: offer.apiUrl, gameId: offer.gameId, planHash: offer.quote.planHash });
+  const journal = path.join(repoRoot, '.ravensight', 'hosted-runs', `${identity}.json`);
   const state = { schema: 'ravensight-hosted-admission-journal/v1', apiUrl: offer.apiUrl, gameId: offer.gameId,
     quoteId: offer.quote.quoteId, planHash: offer.quote.planHash, consent: offer.consent,
     idempotencyKey: `hosted-${offer.quote.planHash}`, phase: 'admission_unknown', createdAt: new Date(now()).toISOString() };
@@ -186,6 +221,103 @@ export async function runHostedQuote({ filename, api, apiUrl, repoRoot, confirm,
     return { state: 'charged_blocked', ...ack, journal, replayAuthorized: false, gameplayProven: false };
   } catch (error) {
     if (error instanceof ApiError && error.status === 401) throw error;
+    if (error instanceof ApiError && DEFINITE_REFUSALS.has(error.code) && error.status >= 400 && error.status < 600) {
+      throw new CliError(hostedRefusalMessage(error), ExitCode.ENVIRONMENT);
+    }
     fail(`The original admission outcome needs reconciliation. Preserve ${journal}; no retry or replacement admission was requested.`);
   }
 }
+
+const ELIGIBLE_BUILD_STATE = 'graphical_static_validated';
+
+/**
+ * The builds a recorded hosted run can use: static-checked, unexpired and on a
+ * profile the server currently advertises as ready. Newest first, the same
+ * filter the dashboard's recorded comparison form applies.
+ */
+export function eligibleHostedBuilds(builds, profiles, now = Date.now()) {
+  const rows = Array.isArray(builds) ? builds : [];
+  return rows.filter(build => build && build.kind === 'recorded_graphical' && build.state === ELIGIBLE_BUILD_STATE
+    && id(build.buildId) && !(Date.parse(build.expiresAt) <= now)
+    && profiles.some(p => p.profileVersion === build.profileVersion && p.format === build.format))
+    .sort((a, b) => (Date.parse(b.createdAt) || 0) - (Date.parse(a.createdAt) || 0));
+}
+
+/**
+ * Quote a recorded Standard then Jev run without a saved quote file: pick the
+ * build (the newest eligible one unless named), ask for a quote, check it, and
+ * hand back the same offer shape `hosted quote` saves. Charges nothing.
+ */
+export async function prepareHostedRun({ api, apiUrl, gameId, buildId, persona, includeVideo = false, includeTranscript = false, standardProvider, now = Date.now }) {
+  if (!id(gameId)) fail('Choose a game. Nothing was charged.');
+  const answer = await api.request('GET', `${base(gameId)}/run-capabilities`, { idempotent: true });
+  const recorded = answer.body?.recorded;
+  if (!recorded?.available || recorded.intakeEnabled !== true || !Array.isArray(recorded.profiles)) {
+    fail('Hosted playtests are not available for this game right now. Nothing was charged.');
+  }
+  const listed = await api.request('GET', `${base(gameId)}/builds`, { idempotent: true });
+  const eligible = eligibleHostedBuilds(listed.body?.builds, recorded.profiles, now());
+  let build;
+  if (buildId) {
+    build = eligible.find(row => row.buildId === buildId);
+    const refused = (Array.isArray(listed.body?.builds) ? listed.body.builds : []).find(row => row?.buildId === buildId && row.rejection?.message);
+    if (!build && refused) fail(`Build ${buildId} was not accepted: ${printable(String(refused.rejection.message)).replace(/\s+/g, ' ').slice(0, 300)} Nothing was charged.`);
+    if (!build) fail(`Build ${buildId} is not ready for a hosted run: it has to pass its static archive check on a ready profile and not have expired. Nothing was charged.`);
+  } else {
+    build = eligible[0];
+    if (!build) fail('No build is ready for a hosted run. Upload one with "build upload" and wait for its static archive check. Nothing was charged.');
+  }
+  const { profile, funding } = await available(api, gameId, build.profileVersion, standardProvider);
+  const request = requestFor({ buildId: build.buildId, profileVersion: build.profileVersion, persona, standardProvider, includeVideo, includeTranscript }, profile);
+  const response = await api.request('POST', `${base(gameId)}/quotes`, { body: request, idempotent: false });
+  if (response.status !== 200) fail('The server did not return a hosted quote. Nothing was charged.');
+  const quote = response.body, consent = hostedConsent(quote, request, now());
+  const value = { apiUrl: origin(apiUrl), gameId, request, quote, consent };
+  const offer = { schema: 'ravensight-hosted-recorded-quote/v1', ...value, integrity: digest(value) };
+  return { offer, build, funding: quote.funding || funding || null };
+}
+
+/** True when the server says the balance does not meet this run's funding requirement. */
+export function fundingShortfall(quote, funding) {
+  const f = quote?.funding || funding;
+  if (f && f.eligible === false) return { requiredTopUpCents: Number.isSafeInteger(f.requiredTopUpCents) ? f.requiredTopUpCents : null };
+  return null;
+}
+
+/** Plain statements a person accepts with the price. Each is something the server enforces or the quote states. */
+export function hostedConsentLines(offer) {
+  const q = offer.quote;
+  return [
+    'One persona plays the same build twice, once with Standard and once with Jev, on isolated hosted machines. These are AI playtests, not human feedback.',
+    'The game runs without network access. Shared capacity, daily limits and the quoted runtime bounds still apply; funding does not guarantee an immediate start.',
+    `If the build fails, hosted compute is ${q.customerFailure === 'refund' ? 'refunded' : 'kept'}. Canceling after a confirmed start ${q.cancelAfterStart === 'refund' ? 'refunds' : 'keeps'} that run's compute charge. Unstarted work is refunded during settlement.`,
+    'The build\'s validation hold is separate and is returned after safe cleanup. It does not reduce this price.',
+    ...(Number.isSafeInteger(q.minimumBalanceCents) ? [`Balance needed to start: ${money(q.minimumBalanceCents)}. Only the total above is charged.`] : [])
+  ];
+}
+
+const admissionPattern = /^ha_[a-f0-9-]{36}$/;
+
+/** Admission, job and runs for one hosted run. A job or runs not readable yet reads as absent. */
+export async function readHostedRun({ api, gameId, admissionId }) {
+  if (!admissionPattern.test(admissionId || '')) fail('Name a hosted run id (ha_...), as "hosted run" printed it.');
+  const admission = (await api.request('GET', `${base(gameId)}/runs/${encodeURIComponent(admissionId)}`, { idempotent: true })).body;
+  if (!admission || admission.admissionId !== admissionId) fail('The server answered for a different hosted run.');
+  let job = null, runs = [];
+  if (admission.jobId) {
+    const jobPath = `/api/v1/games/${encodeURIComponent(gameId)}/playtest/jobs/${encodeURIComponent(admission.jobId)}`;
+    const soft = async promise => { try { return (await promise).body; } catch (error) { if (error instanceof ApiError && error.status === 404) return null; throw error; } };
+    const [jobBody, runsBody] = await Promise.all([
+      soft(api.request('GET', jobPath, { idempotent: true })),
+      soft(api.request('GET', `${jobPath}/runs`, { idempotent: true }))
+    ]);
+    job = jobBody?.job || null;
+    runs = Array.isArray(runsBody?.runs) ? runsBody.runs : [];
+  }
+  return { admission, job, runs };
+}
+
+export async function cancelHostedRun({ api, gameId, admissionId }) {
+  if (!admissionPattern.test(admissionId || '')) fail('Name a hosted run id (ha_...), as "hosted run" printed it.');
+  return (await api.request('POST', `${base(gameId)}/runs/${encodeURIComponent(admissionId)}/cancel`, { body: {}, idempotent: false })).body;
+}

package/src/hosted/status.js

@@ -0,0 +1,108 @@
+// Customer-facing progress for a hosted admission plus its ordinary Playtest job.
+//
+// Mirrors dashboard/src/lib/hostedPlaytestStatus.js in the platform repo
+// (game_tracker), so the CLI and the dashboard use the same phases and the same
+// words. Change both together. The admission owns the provider and payment
+// lifecycle; the job and its runs own gameplay, report capture and aggregation.
+
+const FAILED = new Set(['failed', 'budget_exceeded', 'interrupted', 'stalled', 'refused']);
+const CANCELED = new Set(['canceled']);
+const boundedReason = value => String(value || '').replace(/\s+/g, ' ').trim().slice(0, 240);
+
+export const HOSTED_PHASES = Object.freeze(['queued', 'provisioning', 'running', 'capturing', 'analyzing', 'report-ready', 'failed', 'canceled']);
+export const TERMINAL_PHASES = Object.freeze(['report-ready', 'failed', 'canceled']);
+
+/**
+ * @param {object} admission GET /hosted/runs/:admissionId
+ * @param {object|null} [job] GET /jobs/:jobId `job`, or null when not readable yet
+ * @param {Array<object>} [runs] GET /jobs/:jobId/runs `runs`
+ * @param {number} [now]
+ */
+export function hostedPlaytestStatus(admission, job = null, runs = [], now = Date.now()) {
+  if (!admission) return null;
+  const runRows = Array.isArray(runs) ? runs : [];
+  const jobState = job?.state || '';
+  const admissionState = admission.executionState || admission.state || '';
+  const cancelRequested = admission.cancelRequested === true || job?.cancel_requested === true;
+  const aggregate = runRows.find(row => row.module === 'aggregate_report');
+  const plays = runRows.filter(row => row.module !== 'aggregate_report');
+
+  let phase = 'queued';
+  let label = 'Queued';
+  let detail = 'Waiting for hosted capacity.';
+
+  if (CANCELED.has(jobState) || CANCELED.has(admissionState)) {
+    phase = 'canceled'; label = 'Canceled'; detail = 'The hosted run was canceled.';
+  } else if (FAILED.has(jobState) || FAILED.has(admissionState) || job?.summary_report === 'failed') {
+    phase = 'failed'; label = 'Failed'; detail = 'The hosted run stopped before a report was ready.';
+  } else if (job?.summary_report === 'ready' || admissionState === 'recorded_closed') {
+    phase = 'report-ready'; label = 'Report ready'; detail = 'The hosted run and report are complete.';
+  } else if (['aggregating', 'uploading'].includes(jobState) || ['reporting', 'uploading'].includes(aggregate?.state)) {
+    phase = 'analyzing'; label = 'Analyzing'; detail = 'Combining the completed playtests into the comparison report.';
+  } else if (plays.some(row => ['reporting', 'uploading'].includes(row.state))) {
+    phase = 'capturing'; label = 'Capturing results'; detail = 'Saving the playtest report, evidence and requested media.';
+  } else if (plays.some(row => row.state === 'playing') || jobState === 'running') {
+    phase = 'running'; label = 'Running'; detail = 'The hosted game session is in progress.';
+  } else if (plays.some(row => row.state === 'launching') || jobState === 'registered' || admissionState === 'dispatched') {
+    phase = 'provisioning'; label = 'Provisioning'; detail = 'Preparing isolated hosted compute for this run.';
+  }
+
+  const startedAt = Date.parse(job?.created_at || admission.createdAt || '');
+  const finishedAt = Date.parse(job?.finished_at || '');
+  const elapsedSeconds = Number.isFinite(startedAt)
+    ? Math.max(0, Math.floor(((Number.isFinite(finishedAt) ? finishedAt : Number(now)) - startedAt) / 1000))
+    : null;
+  const failure = phase === 'failed'
+    ? boundedReason(job?.state_reason || admission.failureReason || admission.stopReason)
+    : '';
+
+  return {
+    phase,
+    label,
+    detail,
+    elapsedSeconds,
+    failure,
+    cancelRequested,
+    settled: admission.settled === true,
+    // A terminal job can still be settling provider cleanup and refunds. The
+    // admission is the authoritative signal that a new paid run is safe.
+    terminal: admission.settled === true && TERMINAL_PHASES.includes(phase)
+  };
+}
+
+const MODE_NAMES = Object.freeze({ standard: 'Standard', jev: 'Jev' });
+
+/**
+ * One row per hosted mode (Standard, Jev), from the job's persona runs. A mode
+ * whose run the server has not created yet reads as not started.
+ * @param {Array<object>} runs
+ * @param {Array<string>} [controllers]
+ */
+export function modeOutcomes(runs = [], controllers = ['standard', 'jev']) {
+  const plays = (Array.isArray(runs) ? runs : []).filter(row => row.module !== 'aggregate_report');
+  return controllers.map(controller => {
+    const run = plays.find(row => row.controller === controller) || null;
+    const report = run?.report || null;
+    return {
+      mode: controller,
+      name: MODE_NAMES[controller] || controller,
+      runId: run?.run_id || null,
+      state: run?.state || 'not_started',
+      reason: run?.state_reason ? boundedReason(run.state_reason) : null,
+      reportValid: report ? report.valid === true : false,
+      findings: report && Number.isSafeInteger(report.findings_count) ? report.findings_count : null,
+      wouldContinue: report && typeof report.would_continue === 'boolean' ? report.would_continue : null,
+      recording: run?.recording?.status || null
+    };
+  });
+}
+
+/** "Standard: completed, 4 findings, video saved." */
+export function modeLine(row) {
+  const parts = [row.state.replace(/_/g, ' ')];
+  if (row.findings !== null) parts.push(`${row.findings} finding${row.findings === 1 ? '' : 's'}`);
+  if (row.wouldContinue !== null) parts.push(row.wouldContinue ? 'would keep playing' : 'would stop playing');
+  if (row.recording) parts.push(`video ${row.recording}`);
+  if (row.reason) parts.push(row.reason);
+  return `${row.name}: ${parts.join(', ')}.`;
+}

package/src/run/aggregate.js

@@ -232,11 +232,12 @@ export async function judgeClusters({ client, jobId, runId, clusters, ledger = n
     }
   } catch (error) {
     // A dedup that could not be judged is not worth failing a job over: the
-    // local clustering is the fallback and it is deterministic. A budget
-    // refusal in particular has to reach the caller though, because it
-    // decides the exit code.
-    if (error instanceof ProxyError && (error.isBudget || error.isClosed)) throw error;
-    log(`dedup pass skipped: ${String(error && error.message)}`);
+    // local clustering is the fallback and it is deterministic. That includes
+    // a budget refusal: the aggregate is the job's report and always comes
+    // back, and the exit code is decided by the persona runs, not by this
+    // pass. Only a closed job stops it.
+    if (error instanceof ProxyError && error.isClosed) throw error;
+    log(`dedup pass skipped${error instanceof ProxyError && error.isBudget ? ' (the aggregate run is out of model budget; the local clustering stands)' : ''}: ${String(error && error.message)}`);
   }
   return verdicts;
 }
@@ -393,6 +394,7 @@ export async function buildAggregate({
     persona: run.persona,
     state: run.state,
     report: run.report,
+    markdown: typeof run.markdown === 'string' ? run.markdown : null,
     // A finding the server dropped for want of evidence is marked on disk
     // after delivery (./dropped.js) and kept out of the aggregate, so the
     // job report counts what the dashboard counts.
@@ -456,6 +458,7 @@ export async function buildAggregate({
       dropped_for: 'no evidence'
     })),
     capability_notes: capabilityNotes.length > 0 ? capabilityNotes : ['No capability limits noted for this job.'],
+    persona_voices: inputs.map(run => personaVoice(run)),
     usage: ledger ? aggregateUsage(ledger) : { usd: 0, by_model: {} }
   };
 
@@ -540,11 +543,11 @@ export async function judgeAggregate({ client, jobId, runId, ranked, inputs, bri
     if (ledger) ledger.record({ model: answer.model, usage: answer.usage, ms: Date.now() - askedAt });
     return parseJsonObject(answer.text);
   } catch (error) {
-    // A budget or cancel refusal decides the caller's exit code and has to
-    // reach it. Anything else leaves the locally ranked aggregate standing,
-    // which is still the report a developer can read.
-    if (error instanceof ProxyError && (error.isBudget || error.isClosed)) throw error;
-    log(`aggregate synthesis skipped: ${String(error && error.message)}`);
+    // A cancel refusal reaches the caller. Anything else, a budget refusal
+    // included, leaves the locally ranked aggregate standing, which is still
+    // the report a developer can read: the aggregate always comes back.
+    if (error instanceof ProxyError && error.isClosed) throw error;
+    log(`aggregate synthesis skipped${error instanceof ProxyError && error.isBudget ? ' (the aggregate run is out of model budget; the local ranking stands)' : ''}: ${String(error && error.message)}`);
     return null;
   }
 }
@@ -665,6 +668,14 @@ export function renderAggregateMarkdown(json) {
     lines.push(`| ${run.persona} | ${run.actions_taken} | ${run.quit_reason} | ${sentiment.fun ?? '-'} | ${sentiment.clarity ?? '-'} | ${sentiment.frustration ?? '-'} | ${run.would_continue === null || run.would_continue === undefined ? '-' : run.would_continue ? 'yes' : 'no'} |`);
   }
   lines.push('');
+  lines.push('## How the personas felt');
+  const voices = Array.isArray(json.persona_voices) ? json.persona_voices : [];
+  if (voices.length === 0) lines.push('No persona report was written, so there is nothing in their own words.');
+  for (const voice of voices) {
+    lines.push(`### ${voice.persona}${voice.written_from_log ? ' (written from the run log)' : ''}`);
+    lines.push(voice.text ? voice.text.split('\n').map(line => `> ${line}`).join('\n') : '> This run\'s report has no in-character section.');
+    lines.push('');
+  }
   lines.push('## Top issues (ranked)');
   if (json.issues.length === 0) lines.push('None.');
   for (const issue of json.issues) {
@@ -703,6 +714,54 @@ export function renderAggregateMarkdown(json) {
   return fillPlaceholders(lines.join('\n'), { generatedAt: json.generated_at, game: json.game_id });
 }
 
+/** The most characters of one persona's in-character section the aggregate quotes. */
+export const MAX_VOICE_CHARS = 1200;
+
+/**
+ * One persona's in-character section, from its report.md: the section under
+ * "In-character experience", the one a report written from the run log
+ * carries too, cut to MAX_VOICE_CHARS at a paragraph or sentence where it can.
+ *
+ * @param {{runId: string, persona: string, markdown: string|null}} run
+ * @returns {{run_id: string, persona: string, written_from_log: boolean, text: string|null}}
+ */
+export function personaVoice(run) {
+  const section = inCharacterSection(run && run.markdown);
+  return {
+    run_id: run.runId,
+    persona: run.persona,
+    written_from_log: Boolean(section && section.fromLog),
+    text: section ? clipVoice(section.text) : null
+  };
+}
+
+/**
+ * The body of report.md's in-character section, or null when it has none.
+ *
+ * @param {string|null} markdown
+ * @returns {{text: string, fromLog: boolean}|null}
+ */
+export function inCharacterSection(markdown) {
+  if (typeof markdown !== 'string' || !markdown) return null;
+  const lines = markdown.split('\n');
+  const start = lines.findIndex(line => /^##\s+In-character experience\b/i.test(line.trim()));
+  if (start === -1) return null;
+  const rest = lines.slice(start + 1);
+  const end = rest.findIndex(line => /^#{1,2}\s/.test(line));
+  const text = (end === -1 ? rest : rest.slice(0, end)).join('\n').trim();
+  if (!text) return null;
+  return { text, fromLog: /written from the run log/i.test(lines[start]) };
+}
+
+function clipVoice(text) {
+  if (text.length <= MAX_VOICE_CHARS) return text;
+  const cut = text.slice(0, MAX_VOICE_CHARS);
+  const paragraph = cut.lastIndexOf('\n\n');
+  const sentence = cut.lastIndexOf('. ');
+  const at = paragraph > MAX_VOICE_CHARS / 2 ? paragraph : sentence > MAX_VOICE_CHARS / 2 ? sentence + 1 : cut.length;
+  return `${cut.slice(0, at).trim()} [...]`;
+}
+
 /**
  * Write both aggregate files into the job directory.
  *