ravensight-playtest 0.7.0 → 0.7.2

package/src/hosted/recordedRun.js

@@ -1,7 +1,7 @@
 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';
 
@@ -140,7 +140,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 +157,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 +220,101 @@ 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);
+    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.
  *

package/src/run/budgetReserve.js

@@ -0,0 +1,102 @@
+import { OUTPUT_WEIGHT } from './usage.js';
+
+/**
+ * Keeping enough of a run's model budget back to write its report.
+ *
+ * The proxy reserves each call's pessimistic projection before sending it:
+ * the whole request body at the full input rate (characters / 3.5) plus the
+ * output ceiling at the output rate. A call whose projection does not fit
+ * what is left of the run's budget is refused with 402 before anything is
+ * sent. The server's own warning comes at 80 percent of the budget, counting
+ * the call being made, and in the October 26 runs it never came: one act
+ * turn's projection jumped the run from under 80 percent to a refusal, and the
+ * report that followed did not fit either.
+ *
+ * So before every act turn the loop asks this module whether, after that
+ * turn, the report call would still be admitted. Both projections are sized
+ * from the requests themselves (the act turn about to be sent and the report
+ * prompt as it would be built now), in input-token units, and priced at what
+ * one unit has actually cost this run (the server's spend over the ledger's
+ * weighted tokens, ./usage.js). No price is held here.
+ */
+
+/** Characters per input token, the proxy's own projection rule. */
+export const CHARS_PER_INPUT_TOKEN = 3.5;
+
+/**
+ * Headroom on the report's projection: the prompt grows by the notes and
+ * observations of the turn still to be played, and a persona that escalates
+ * may write it on a dearer tier than the one the unit price was learned on.
+ */
+export const REPORT_RESERVE_MARGIN = 1.3;
+
+/** Headroom on what the next act turn will really cost, over the dearest recent one. */
+export const ACT_COST_MARGIN = 1.5;
+
+/** A flat share of the run's budget never planned against. */
+export const FLAT_MARGIN_RATIO = 0.03;
+
+/**
+ * The proxy's projection of a request, in input-token units.
+ *
+ * @param {number} bodyChars the request's JSON length
+ * @param {number} maxTokens its output ceiling
+ * @returns {number}
+ */
+export function projectionUnits(bodyChars, maxTokens) {
+  return Math.max(0, Number(bodyChars) || 0) / CHARS_PER_INPUT_TOKEN + Math.max(0, Number(maxTokens) || 0) * OUTPUT_WEIGHT;
+}
+
+/**
+ * Whether play has to stop now so the report still fits.
+ *
+ * @param {Object} args
+ * @param {number|null} args.usdMax the run's model budget, from register
+ * @param {{usd: number, usdPerUnit: number}|null} args.spend the ledger's estimate
+ * @param {number} args.actChars the next act request's JSON length
+ * @param {number} args.actMaxTokens
+ * @param {number} args.actCostUnits what an act turn has really cost, at most, lately
+ * @param {number} args.reportChars the report request's JSON length if it were sent now
+ * @param {number} args.reportMaxTokens
+ * @returns {{stop: boolean, known: boolean, figures: Object}}
+ */
+export function reserveDecision({ usdMax, spend, actChars, actMaxTokens, actCostUnits, reportChars, reportMaxTokens }) {
+  const max = Number(usdMax);
+  if (!Number.isFinite(max) || max <= 0 || !spend || !Number.isFinite(spend.usdPerUnit) || spend.usdPerUnit <= 0) {
+    return { stop: false, known: false, figures: {} };
+  }
+  const price = spend.usdPerUnit;
+  const actProjected = price * projectionUnits(actChars, actMaxTokens);
+  const actCost = price * Math.max(0, Number(actCostUnits) || 0) * ACT_COST_MARGIN;
+  const reportProjected = price * projectionUnits(reportChars, reportMaxTokens) * REPORT_RESERVE_MARGIN;
+  const flat = max * FLAT_MARGIN_RATIO;
+  // The act turn itself has to be admitted, and after it the report has to be.
+  const actFits = spend.usd + actProjected <= max;
+  const reportFitsAfter = spend.usd + actCost + reportProjected + flat <= max;
+  const round = value => Math.round(value * 1e6) / 1e6;
+  return {
+    stop: !actFits || !reportFitsAfter,
+    known: true,
+    figures: {
+      usd_max: round(max),
+      usd_spent: round(spend.usd),
+      act_projected_usd: round(actProjected),
+      act_cost_usd: round(actCost),
+      report_reserve_usd: round(reportProjected),
+      margin_usd: round(flat)
+    }
+  };
+}
+
+/**
+ * A registered run's model budget in USD: `limits.model_usd`, or the older
+ * `budget_usd` beside it. Null when the server sent neither, which leaves the
+ * reserve off and the server's own warning in charge.
+ *
+ * @param {Object} entry a run from the register answer
+ * @returns {number|null}
+ */
+export function runModelBudgetUsd(entry) {
+  const value = Number(entry && ((entry.limits && entry.limits.model_usd) ?? entry.budget_usd));
+  return Number.isFinite(value) && value > 0 ? value : null;
+}

package/src/run/drivers/web.js

@@ -1,6 +1,7 @@
 import { mkdir, rename, stat, readdir, rm, chmod } from 'node:fs/promises';
 import { recordingLimits, recordingViewport, recordingDirectory, recordingMetadata, saveRecording, probeVideo } from './recording.js';
 import path from 'node:path';
+import { gameRefusal, runnerGone } from '../gameRefusal.js';
 import {
   DriverError,
   STALE_REF_MESSAGE,
@@ -31,6 +32,18 @@ import {
 /** Default recording and viewport size. Kept at 720p to match the upload guidance. */
 export const DEFAULT_VIEWPORT = Object.freeze({ width: 1280, height: 720 });
 
+/**
+ * The frame a canvas observation sends the model: JPEG at this quality, at the
+ * viewport's own size. The model is billed for an image by its pixels, so the
+ * format changes nothing there and the coordinates a persona reads off it stay
+ * the page's own. What it changes is the proxy's reservation, which prices the
+ * request body's characters as text: a 1280x720 PNG of a busy canvas is
+ * 300 to 900 KB of base64, a projection of up to half a standard run's model
+ * budget for one act turn, where the same frame as JPEG at 70 is 60 to 150 KB.
+ * Screenshots saved as evidence stay PNG.
+ */
+export const OBSERVATION_FRAME = Object.freeze({ type: 'jpeg', quality: 70, mediaType: 'image/jpeg' });
+
 /** A `wait` action is clamped to this, so one turn cannot burn the wall clock. */
 export const MAX_WAIT_MS = 10000;
 
@@ -1349,7 +1362,7 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
     const snap = await snapshotText();
     const after = { text: hashText(snap, shownText(snap)) };
     if (String(snap.text).trim().length < THIN_OBSERVATION_CHARS) {
-      const frame = await current.screenshot({ type: 'png', timeout: ACTION_TIMEOUT_MS });
+      const frame = await current.screenshot({ type: OBSERVATION_FRAME.type, quality: OBSERVATION_FRAME.quality, timeout: ACTION_TIMEOUT_MS });
       after.screenshotBase64 = frame.toString('base64');
     }
     return observationHash(after);
@@ -1579,9 +1592,9 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
       // is the only way to play them. Spend an image only then.
       if (String(text).trim().length < THIN_OBSERVATION_CHARS) {
         try {
-          const buffer = await current.screenshot({ type: 'png', timeout: ACTION_TIMEOUT_MS });
+          const buffer = await current.screenshot({ type: OBSERVATION_FRAME.type, quality: OBSERVATION_FRAME.quality, timeout: ACTION_TIMEOUT_MS });
           observation.screenshotBase64 = buffer.toString('base64');
-          observation.screenshotMediaType = 'image/png';
+          observation.screenshotMediaType = OBSERVATION_FRAME.mediaType;
         } catch {
           // No image and thin text is still an observation; the persona will
           // read it as a blank screen, which is what it is.
@@ -1679,6 +1692,16 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
         if (/Timeout \d+ms exceeded/i.test(text) && intercepted) {
           return { ok: false, changed: false, error: `timed out: ${intercepted.slice(0, 160)} intercepts pointer events over the target`, driverError: false };
         }
+        // A target the page shows as disabled, hidden or not editable is the
+        // game refusing the action, which is what a player sees: evidence,
+        // never a driver error. The resolved element is named so the report
+        // step can cite it.
+        const refusal = /Timeout \d+ms exceeded/i.test(text) ? gameRefusal(text) : null;
+        if (refusal) {
+          return { ok: false, changed: false, error: `the game did not accept this action: the target is ${refusal.state} (${refusal.element})`, driverError: false };
+        }
+        // The browser or page closed under the runner: the runner's failure.
+        if (runnerGone(text)) return { ok: false, changed: false, error: text, driverError: true };
         // A timeout with the page unchanged while resolving a click or typing
         // target means the target was never found or never actionable: the
         // driver's failure, not the game's. Never for navigate: a game that

package/src/run/failureReason.js

@@ -0,0 +1,77 @@
+import { homedir } from 'node:os';
+import { redactSecrets } from './secretScan.js';
+
+/** The server stores a run's reason as `stateReason` and the dashboard shows it. */
+export const MAX_REASON_CHARS = 400;
+
+/**
+ * Token shapes the upload scan does not cover, because they are not refused
+ * there: any `gt_` or `sk-` token and a bearer header value. A reason is
+ * diagnostics, so these are replaced rather than refused.
+ */
+const EXTRA_PATTERNS = [
+  { type: 'bearer_token', regex: /\bbearer\s+[A-Za-z0-9._~+/=-]{4,2048}/gi },
+  { type: 'ravensight_token', regex: /\bgt_[A-Za-z0-9_-]{4,256}/g },
+  { type: 'api_key', regex: /\bsk-[A-Za-z0-9_-]{4,256}/g }
+];
+
+/** A home directory in a path: macOS, Linux and Windows. */
+const HOME_PATHS = [
+  /\/Users\/[^/\s'"`]+/g,
+  /\/home\/[^/\s'"`]+/g,
+  /\b[A-Za-z]:[\\/]+Users[\\/]+[^\\/\s'"`]+/gi
+];
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * The text with token-like strings and absolute home paths taken out, safe to
+ * send to the server as a run's reason.
+ *
+ * @param {string} text
+ * @param {{home?: string}} [options]
+ * @returns {string}
+ */
+export function redactReason(text, { home = homedir() } = {}) {
+  let out = redactSecrets(text);
+  for (const { type, regex } of EXTRA_PATTERNS) out = out.replace(regex, `[redacted ${type}]`);
+  if (home && home.length > 1) out = out.replace(new RegExp(escapeRegExp(home), 'g'), '~');
+  for (const pattern of HOME_PATHS) out = out.replace(pattern, '~');
+  return out;
+}
+
+/**
+ * The reason a failed run is reported with: the detail it already has, or else
+ * the caught error's message, redacted and cut to 400 characters. Never empty.
+ *
+ * @param {unknown} error
+ * @param {{detail?: string, fallback?: string, home?: string}} [options]
+ * @returns {string}
+ */
+export function failureReason(error, { detail = '', fallback = 'the run stopped on an error', home } = {}) {
+  const message = error && typeof error === 'object' && 'message' in error ? error.message : error;
+  const raw = String(detail || '').trim() || (message == null ? '' : String(message).trim());
+  const text = redactReason(raw, home === undefined ? {} : { home }).trim().slice(0, MAX_REASON_CHARS);
+  return text || fallback;
+}
+
+/**
+ * The reason a run whose game or browser could not start is reported with:
+ * what failed, the redacted message, and what to do about it. The message is
+ * cut first, so the instruction always survives the 400 character limit.
+ *
+ * @param {string} driverName
+ * @param {unknown} error
+ * @param {{detail?: string, browserFix?: string, home?: string}} [options]
+ * @returns {string}
+ */
+export function driverStartReason(driverName, error, { detail = '', browserFix = 'npx playwright install chromium', home } = {}) {
+  const browser = driverName === 'playwright_web';
+  const what = browser ? 'the browser could not start' : driverName === 'godot_driver' ? 'Godot could not start' : `the ${driverName} driver could not start`;
+  const todo = browser ? `run ${browserFix}` : 'run "ravensight-playtest check" to see what is missing';
+  const room = MAX_REASON_CHARS - what.length - todo.length - 4;
+  const message = failureReason(error, { detail, fallback: 'no error message', ...(home === undefined ? {} : { home }) }).slice(0, Math.max(0, room)).trim();
+  return `${what}: ${message}; ${todo}`;
+}