ravensight-playtest 0.5.1 → 0.5.2

package/README.md

@@ -1,5 +1,53 @@
 # ravensight-playtest
 
+Hosted comparisons use a separate command from the local `run`:
+
+```sh
+ravensight-playtest hosted quote --game GAME --build BUILD --profile PROFILE --persona curious-kid --video --transcript --output hosted-quote.json
+ravensight-playtest hosted run hosted-quote.json
+```
+
+The quote names the full Standard then Jev price, prepaid amount, evidence
+options, expiry and refund rules. It charges nothing. `hosted run` confirms
+that saved quote before one admission request. Its durable journal blocks an
+automatic second POST after an uncertain outcome; preserve it for reconciliation.
+A charged-blocked acknowledgement does not prove gameplay or a report. This
+command does not top up funds, change local run/report files or ask for model
+proxy permission on the CLI credential.
+
+On a server that advertises it as ready, `hosted quote --standard-provider openai`
+selects OpenAI for Standard. Explicit `anthropic` works the same way. The returned
+provider and policy hash must match and remain in the saved consent; `hosted run`
+has no provider override. Omitting the flag keeps the original default request
+and consent wire. No choice falls back to another provider, and a CLI declaration
+does not establish deployed provider or hosted engine readiness. Existing `run`
+continues to use its local runner and original API contract.
+
+The hosted build command source adds a local check before a paid upload:
+
+```sh
+ravensight-playtest build preflight ./game.zip --format web --entrypoint index.html
+ravensight-playtest build upload ./game.zip --game GAME --profile READY_PROFILE --entrypoint index.html --dry-run
+```
+
+`preflight` seeks through bounded ZIP metadata; it does not load a multi-GB
+archive into memory. A saved server profile can be supplied with `--capacity`
+for its declared limits. Upload selects a currently advertised ready profile,
+checks metadata and a streamed checksum, then asks for the separate $0.49
+validation hold before requesting it. The server’s isolated validator remains
+authoritative. A passing local check does not establish engine, GPU or license
+compatibility.
+
+The current upload protocol is one streamed presigned PUT. Multipart upload
+and byte-range resume are not advertised. The original upload journal is kept
+after an uncertain response, and repeating that upload cannot silently request
+a second reservation. A different journal does not cancel or refund an earlier
+upload. Reports and existing run-upload journals are left intact. Larger limits
+and native executable formats are usable only when the server advertises a
+ready profile and the corresponding upload and runtime support exists. This
+source addition does not claim an accepted AAA engine run or a published CLI
+release.
+
 AI personas play your game, then file a report you can read, mark up and argue
 with. The personas run on your machine, against your build; Ravensight stores
 the reports and renders them.

package/package.json

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

package/src/api/client.js

@@ -51,7 +51,7 @@ export function createClient(options = {}) {
    * @param {string} method
    * @param {string} path
    * @param {{query?: Object, body?: unknown, headers?: Object, idempotent?: boolean,
-   *   raw?: boolean, anonymous?: boolean}} [opts]
+   *   raw?: boolean, anonymous?: boolean, onResponseRaw?: Function}} [opts]
    * @returns {Promise<{status: number, headers: Headers, body: unknown}>}
    */
   async function request(method, path, opts = {}) {
@@ -86,6 +86,7 @@ export function createClient(options = {}) {
       bodyText,
       idempotent: Boolean(opts.idempotent),
       raw: Boolean(opts.raw),
+      onResponseRaw: opts.onResponseRaw,
       ...transport
     });
   }

package/src/api/http.js

@@ -43,18 +43,26 @@ export function buildUrl(apiUrl, path, query) {
 }
 
 /**
- * Read a response body without ever throwing. A 502 from a load balancer is
+ * Read a response body without throwing for body or JSON decoding errors. A 502 from a load balancer is
  * HTML, a 204 is empty, and a JSON parse failure on the error path would
  * replace a useful status code with a useless SyntaxError.
  * @param {Response} response
  * @returns {Promise<{json: unknown, text: string}>}
  */
-async function readBody(response) {
+async function readBody(response, onResponseRaw) {
   let text = '';
-  try {
-    text = await response.text();
-  } catch {
-    return { json: null, text: '' };
+  if (onResponseRaw) {
+    let bytes = Buffer.alloc(0), bodyComplete = false;
+    try { bytes = Buffer.from(await response.arrayBuffer()); bodyComplete = true; }
+    catch { /* Preserve a read-failure observation, never invent complete bytes. */ }
+    // Opt-in capture runs on every HTTP status BEFORE JSON parsing or an
+    // ApiError. Capture failures propagate and cannot trigger a request retry.
+    await onResponseRaw({ status: response.status, contentType: response.headers.get('content-type'), bytes, bodyComplete });
+    if (!bodyComplete) return { json: null, text: '' };
+    text = new TextDecoder().decode(bytes);
+  } else {
+    try { text = await response.text(); }
+    catch { return { json: null, text: '' }; }
   }
   if (!text) return { json: null, text: '' };
   try {
@@ -102,6 +110,7 @@ function errorFrom(response, parsed, { method, path }) {
  * @param {string} [options.bodyText]
  * @param {boolean} [options.idempotent]
  * @param {boolean} [options.raw] - resolve the body as text, not JSON
+ * @param {Function} [options.onResponseRaw] - await exact response-byte capture before parsing, including non-2xx
  * @param {number} [options.retries]
  * @param {number} [options.timeoutMs]
  * @param {typeof fetch} [options.fetchImpl]
@@ -119,6 +128,7 @@ export async function requestWithRetry(options) {
     bodyText,
     idempotent = false,
     raw = false,
+    onResponseRaw,
     retries = DEFAULT_RETRIES,
     timeoutMs = DEFAULT_TIMEOUT_MS,
     fetchImpl = globalThis.fetch,
@@ -162,7 +172,7 @@ export async function requestWithRetry(options) {
     }
 
     if (response) {
-      const parsed = await readBody(response);
+      const parsed = await readBody(response, onResponseRaw);
       if (response.ok || response.status === 304) {
         return {
           status: response.status,

package/src/cli.js

@@ -143,6 +143,50 @@ function withoutFirst(values, value) {
 export function buildProgram() {
   const program = new Command();
   const slot = { code: ExitCode.OK };
+  const hosted = common(program.command('hosted').description('quote and admit a server-hosted Standard/Jev comparison'));
+  hosted.command('quote')
+    .description('save a full hosted quote without charging or admitting a run')
+    .requiredOption('--build <id>', 'an existing validated hosted build')
+    .requiredOption('--profile <version>', 'one currently advertised ready hosted profile')
+    .requiredOption('--persona <slug>', 'one available persona for both separate playthroughs')
+    .requiredOption('--output <file>', 'save the original quote and immutable consent here')
+    .option('--game <id>', 'game id, overriding this repo’s configuration')
+    .addOption(new Option('--standard-provider <name>', 'explicit Standard provider; unavailable choices are refused').choices(['anthropic', 'openai']))
+    .option('--video', 'include hosted gameplay video in this quote')
+    .option('--transcript', 'include the hosted transcript in this quote')
+    .action(capture(slot, async (options, command) => {
+      const { hostedQuote } = await import('./commands/hosted.js');
+      return hostedQuote(flagsFrom(command.optsWithGlobals(), { build: options.build, profile: options.profile,
+        persona: options.persona, output: options.output, game: options.game, standardProvider: options.standardProvider,
+        video: options.video, transcript: options.transcript }));
+    }));
+  hosted.command('run <quote-file>')
+    .description('confirm the full saved quote and request one hosted admission; never retry an unknown outcome')
+    .action(capture(slot, async (filename, _options, command) => {
+      const { hostedRun } = await import('./commands/hosted.js');
+      return hostedRun(filename, flagsFrom(command.optsWithGlobals()));
+    }));
+  const build = common(program.command('build').description('check or upload a self-contained hosted game archive'));
+  build.command('preflight <archive>')
+    .description('check bounded ZIP metadata locally before any paid upload')
+    .requiredOption('--entrypoint <path>', 'entry file inside the ZIP')
+    .option('--format <name>', 'web or godot-project without a selected capacity profile', 'web')
+    .option('--capacity <file>', 'saved profile JSON for a local capacity check; does not establish server readiness')
+    .action(capture(slot, async (archive, options, command) => {
+      const { buildPreflight } = await import('./commands/build.js');
+      return buildPreflight(archive, flagsFrom(command.optsWithGlobals(), { entrypoint: options.entrypoint, format: options.format, capacity: options.capacity }));
+    }));
+  build.command('upload <archive>')
+    .description('preflight and stream one private build upload after validation-hold consent')
+    .requiredOption('--profile <version>', 'one currently advertised ready server profile')
+    .requiredOption('--entrypoint <path>', 'entry file inside the ZIP')
+    .option('--game <id>', 'game id, overriding this repo’s configuration')
+    .option('--journal <file>', 'preserve this original upload intent at the specified path')
+    .option('--dry-run', 'inspect and hash the archive without requesting a reservation')
+    .action(capture(slot, async (archive, options, command) => {
+      const { buildUpload } = await import('./commands/build.js');
+      return buildUpload(archive, flagsFrom(command.optsWithGlobals(), { entrypoint: options.entrypoint, profile: options.profile, game: options.game, journal: options.journal, dryRun: options.dryRun }));
+    }));
   program.exitCodeSlot = slot;
   program
     .name('ravensight-playtest')

package/src/commands/build.js

@@ -0,0 +1,81 @@
+import { readFile, stat } from 'node:fs/promises';
+import { createContext } from '../api/index.js';
+import { resolveGameId } from '../config.js';
+import { withAuthHandling } from '../auth/session.js';
+import { preflightBuildArchive, limitsFromProfile } from '../hosted/archivePreflight.js';
+import { uploadHostedBuild } from '../hosted/buildUpload.js';
+import { CliError, ExitCode } from '../errors.js';
+import { ui } from '../ui/index.js';
+
+// TTY animation stays live while I/O awaits. Piped logs receive at most one
+// byte update per second, plus phase boundaries and the final byte count.
+export function buildUploadProgress({ json = false, now = Date.now } = {}) {
+  let spin, phase, last = 0, finished = false;
+  const labels = { capabilities: 'Checking available build profiles', preflight: 'Checking ZIP metadata',
+    hash: 'Hashing archive', reservation: 'Requesting the confirmed validation hold',
+    upload: 'Streaming archive bytes', completion: 'Submitting the original upload for validation' };
+  return {
+    update(event) {
+      if (json || ui.isQuiet()) return;
+      const at = now(), changed = phase !== event.phase;
+      const complete = event.totalBytes !== undefined && event.completedBytes === event.totalBytes;
+      if (!changed && at - last < 1000 && (!complete || finished)) return;
+      const label = labels[event.phase] + (event.totalBytes === undefined ? ''
+        : `: ${ui.bytes(event.completedBytes)} / ${ui.bytes(event.totalBytes)}`);
+      if (changed) { spin?.stop(); spin = ui.spinner(label); phase = event.phase; }
+      else spin.update(label);
+      last = at; finished = complete;
+    },
+    stop() { spin?.stop(); spin = null; phase = null; finished = false; }
+  };
+}
+
+export async function buildPreflight(filename, flags = {}) {
+  let profile;
+  if (flags.capacity) {
+    const info = await stat(flags.capacity);
+    if (!info.isFile() || info.size > 65536) throw new CliError('Choose a capacity profile JSON file no larger than 64 KiB.');
+    profile = JSON.parse(await readFile(flags.capacity, 'utf8'));
+  }
+  const result = await preflightBuildArchive(filename, { format: profile?.format || flags.format,
+    entrypoint: flags.entrypoint, limits: profile ? limitsFromProfile(profile) : undefined,
+    requirements: profile?.capacity?.requirements });
+  if (flags.json) ui.json(result);
+  else {
+    ui.ok(`ZIP metadata passed: ${result.entries} entries; ${ui.bytes(result.archiveBytes)} uploaded, ${ui.bytes(result.expandedBytes)} expanded.`);
+    ui.info('No wallet charge or upload was requested. Server validation and runtime compatibility checks are still required.');
+  }
+  return ExitCode.OK;
+}
+
+export async function buildUpload(filename, flags = {}, deps = {}) {
+  const context = deps.context || await createContext({ apiUrl: flags.apiUrl, repoRoot: flags.repoRoot, requireAuth: true });
+  return withAuthHandling(context, async () => {
+    const progress = buildUploadProgress({ json: Boolean(flags.json) });
+    try {
+      const result = await uploadHostedBuild({ filename, gameId: resolveGameId(flags, context.config), profileVersion: flags.profile,
+        entrypoint: flags.entrypoint, repoRoot: context.repoRoot, api: context.api, apiUrl: context.api.apiUrl,
+        journalPath: flags.journal, dryRun: Boolean(flags.dryRun), fetchImpl: deps.fetch,
+        confirm: deps.confirm || (question => ui.confirm(question, { yes: Boolean(flags.yes) })),
+        onProgress: event => progress.update(event),
+        onPrepared: prepared => {
+          progress.stop();
+          if (flags.json) return;
+          ui.info(`ZIP metadata checked: ${prepared.entries} entries; ${ui.bytes(prepared.archiveBytes)} archive, ${ui.bytes(prepared.expandedBytes)} expanded.`);
+          const limit = prepared.limits;
+          ui.info(`Selected limits: archive ${ui.bytes(limit.archiveBytes)}, expanded ${ui.bytes(limit.expandedBytes)}, file ${ui.bytes(limit.fileBytes)}, ${limit.files} entries, depth ${limit.depth}, ratio ${limit.ratio}:1.`);
+          const required = prepared.capacity?.requirements;
+          if (required) ui.info(`Server profile: ${required.os}/${required.architecture}, ${required.cpuVcpus} CPU, ${ui.bytes(required.memoryBytes)} RAM. Runtime and license readiness must come from the server.`);
+          if (Number.isSafeInteger(prepared.funding?.minimumFundingCents)) ui.info(`Server prepaid funding minimum: $${(prepared.funding.minimumFundingCents / 100).toFixed(2)}; the separate gameplay price is quoted after validation.`);
+          ui.info('Static validation hold: $0.49 from prepaid funds, returned after safe cleanup. A gameplay quote is separate. No top-up is performed.');
+          ui.info('Passing this local check does not establish GPU, licensing or game runtime compatibility.');
+        }
+      });
+      progress.stop();
+      if (flags.json) ui.json(result);
+      else if (result.state === 'awaiting_validation') ui.ok(`Uploaded ${result.buildId}; awaiting server validation. Journal: ${result.journal}`);
+      else ui.info(result.state === 'declined' ? 'Upload declined; no reservation requested.' : 'Preflight finished; no reservation requested.');
+      return result.state === 'declined' ? ExitCode.CANCELED : ExitCode.OK;
+    } finally { progress.stop(); }
+  });
+}

package/src/commands/hosted.js

@@ -0,0 +1,39 @@
+import { createContext } from '../api/index.js';
+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';
+
+export async function hostedQuote(flags = {}, deps = {}) {
+  const context = deps.context || await createContext({ apiUrl: flags.apiUrl, repoRoot: flags.repoRoot, requireAuth: true });
+  return withAuthHandling(context, async () => {
+    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 });
+    if (flags.json) ui.json(result);
+    else {
+      hostedQuoteLines(result).forEach(line => ui.info(line));
+      ui.ok(`Saved ${result.quoteFile}. No admission or charge was requested.`);
+    }
+    return ExitCode.OK;
+  });
+}
+
+export async function hostedRun(filename, flags = {}, deps = {}) {
+  if (flags.json && !flags.yes && !deps.confirm) throw new CliError('Inspect the saved quote, then use --yes with --json. No admission was requested.');
+  const context = deps.context || await createContext({ apiUrl: flags.apiUrl, repoRoot: flags.repoRoot, requireAuth: true });
+  return withAuthHandling(context, async () => {
+    const result = await runHostedQuote({ filename, api: context.api, apiUrl: context.api.apiUrl, repoRoot: context.repoRoot,
+      confirm: deps.confirm || (question => ui.confirm(question, { yes: Boolean(flags.yes) })),
+      onPrepared: offer => { if (!flags.json) hostedQuoteLines(offer).forEach(line => ui.info(line)); } });
+    if (flags.json) ui.json(result);
+    else if (result.state === 'declined') ui.info('Hosted quote declined. No admission was requested.');
+    else {
+      ui.ok(`Admission ${result.admissionId}; job ${result.jobId}. Saved ${result.journal}.`);
+      ui.info('The server acknowledged charged_blocked. This does not prove a worker started or produced gameplay or reports.');
+    }
+    return result.state === 'declined' ? ExitCode.CANCELED : ExitCode.OK;
+  });
+}

package/src/hosted/archivePreflight.js

@@ -0,0 +1,240 @@
+import { constants } from 'node:fs';
+import { open, lstat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { Readable } from 'node:stream';
+import { createInflateRaw } from 'node:zlib';
+import { CliError } from '../errors.js';
+
+export const LEGACY_BUILD_LIMITS = Object.freeze({ archiveBytes: 64 * 1024 ** 2,
+  expandedBytes: 512 * 1024 ** 2, fileBytes: 64 * 1024 ** 2, files: 1000, depth: 16, ratio: 100,
+  archiveFormats: Object.freeze(['zip']), zip64: false });
+// These parser bounds cap metadata/memory even when an operator declares a
+// much larger byte budget. They do not advertise server or engine capacity.
+const MAX_DIRECTORY_BYTES = 64 * 1024 ** 2;
+const MAX_ENTRIES = 1_000_000;
+const MAX_PATH_BYTES = 1024;
+const reject = reason => { throw new CliError(`Build preflight failed: ${reason}. No upload reservation was requested.`); };
+const integer = value => Number.isSafeInteger(value) && value > 0;
+const same = (a, b) => ['dev', 'ino', 'size', 'mtimeNs', 'ctimeNs'].every(key => a[key] === b[key]);
+
+export function buildLimits(value = LEGACY_BUILD_LIMITS) {
+  const keys = ['archiveBytes', 'expandedBytes', 'fileBytes', 'files', 'depth', 'ratio'];
+  if (!value || keys.some(key => !integer(value[key]))) reject('the selected build limits are incomplete');
+  if (value.files > MAX_ENTRIES || value.depth > 128 || value.ratio > 10000) reject('the selected limits exceed this client’s bounded metadata parser');
+  if (value.archiveFormats !== undefined && (!Array.isArray(value.archiveFormats) || value.archiveFormats.length !== 1 || value.archiveFormats[0] !== 'zip')
+    || value.zip64 !== undefined && typeof value.zip64 !== 'boolean') reject('the selected archive policy is unsupported');
+  return { ...Object.fromEntries(keys.map(key => [key, value[key]])), archiveFormats: ['zip'], zip64: value.zip64 === true };
+}
+
+export function limitsFromProfile(profile) {
+  if (profile?.capacity?.version !== 1) reject('the selected profile does not declare a supported capacity schema');
+  return buildLimits(profile.capacity.uploadLimits);
+}
+
+function safePath(value, depth, directory = false) {
+  if (!value || Buffer.byteLength(value) > MAX_PATH_BYTES || /[\\\x00-\x1f\x7f:]/.test(value) || value.startsWith('/')) reject('an archive path is unsafe');
+  const name = directory && value.endsWith('/') ? value.slice(0, -1) : value;
+  const parts = name.split('/');
+  if (parts.length > depth || parts.some(part => !part || part === '.' || part === '..' || part.length > 255
+    || /[. ]$/.test(part) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))
+    || !/^[A-Za-z0-9_./ +@()=-]+$/.test(name)) reject('an archive path is not portable or exceeds the selected depth');
+  return name;
+}
+
+function number64(bytes, offset) {
+  const value = bytes.readBigUInt64LE(offset);
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) reject('a ZIP64 offset or size cannot be represented safely');
+  return Number(value);
+}
+
+// A descriptor owns one open file throughout preflight, hash and upload. The
+// pathname is never reopened for transfer after consent. No file-size buffer.
+export async function openBuildArchive(filename, { signal, onRead } = {}) {
+  const before = await lstat(filename, { bigint: true });
+  if (!before.isFile() || before.isSymbolicLink()) reject('choose a regular ZIP file');
+  const handle = await open(filename, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+  try {
+    const stat = await handle.stat({ bigint: true });
+    if (!same(before, stat) || stat.size > BigInt(Number.MAX_SAFE_INTEGER)) reject('the archive changed while opening');
+    let closed = false;
+    const check = async () => {
+      if (closed || signal?.aborted) reject('the archive operation was stopped');
+      if (!same(stat, await handle.stat({ bigint: true }))) reject('the archive changed; run preflight again');
+    };
+    const read = async (offset, length) => {
+      if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 || length < 0
+        || length > 65557 || offset + length > Number(stat.size)) reject('an archive record extends outside the file');
+      await check();
+      const bytes = Buffer.alloc(length); let done = 0;
+      while (done < length) {
+        const result = await handle.read(bytes, done, length - done, offset + done);
+        if (!result.bytesRead) reject('the archive is truncated');
+        done += result.bytesRead;
+      }
+      onRead?.(length); return bytes;
+    };
+    return { size: Number(stat.size), read, check,
+      async sha256({ onProgress } = {}) {
+        const hash = createHash('sha256');
+        for (let at = 0; at < Number(stat.size); at += 65536) {
+          const chunk = await read(at, Math.min(65536, Number(stat.size) - at));
+          hash.update(chunk); onProgress?.(at + chunk.length, Number(stat.size));
+        }
+        await check(); return hash.digest('hex');
+      },
+      async *chunks({ start = 0, end = Number(stat.size), onProgress } = {}) {
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start || end > Number(stat.size)) reject('the upload range is invalid');
+        for (let at = start; at < end; at += 65536) {
+          const chunk = await read(at, Math.min(65536, end - at));
+          yield chunk; onProgress?.(at + chunk.length - start, end - start);
+        }
+        await check();
+      },
+      async close() { if (!closed) { closed = true; await handle.close(); } }
+    };
+  } catch (error) { await handle.close(); throw error; }
+}
+
+async function directory(archive, limits) {
+  if (archive.size < 22 || archive.size > limits.archiveBytes) reject('the ZIP exceeds the selected upload size or is truncated');
+  const tailStart = Math.max(0, archive.size - 65557), tail = await archive.read(tailStart, archive.size - tailStart);
+  let eocd = -1;
+  for (let at = tail.length - 22; at >= 0; at--) {
+    if (tail.readUInt32LE(at) === 0x06054b50 && at + 22 + tail.readUInt16LE(at + 20) === tail.length) { eocd = at; break; }
+  }
+  if (eocd < 0) reject('the ZIP directory is missing');
+  const record = tail.subarray(eocd), end = tailStart + eocd;
+  if (record.readUInt16LE(4) || record.readUInt16LE(6) || record.readUInt16LE(8) !== record.readUInt16LE(10)) reject('split ZIP archives are unsupported');
+  let count = record.readUInt16LE(10), size = record.readUInt32LE(12), offset = record.readUInt32LE(16), boundary = end;
+  const locator = end >= 20 ? await archive.read(end - 20, 20) : null;
+  const zip64 = locator?.readUInt32LE(0) === 0x07064b50;
+  if (zip64 && !limits.zip64) reject('the selected profile does not accept ZIP64');
+  if (zip64) {
+    if (locator.readUInt32LE(4) || locator.readUInt32LE(16) !== 1) reject('split ZIP64 archives are unsupported');
+    boundary = number64(locator, 8);
+    const expanded = await archive.read(boundary, 56);
+    if (expanded.readUInt32LE(0) !== 0x06064b50 || number64(expanded, 4) < 44
+      || number64(expanded, 4) > 1024 || boundary + 12 + number64(expanded, 4) !== end - 20
+      || expanded.readUInt32LE(16) || expanded.readUInt32LE(20) || number64(expanded, 24) !== number64(expanded, 32)) reject('the ZIP64 directory is invalid');
+    const values = [number64(expanded, 32), number64(expanded, 40), number64(expanded, 48)];
+    if ([count, size, offset].some((value, i) => value !== (i ? 0xffffffff : 0xffff) && value !== values[i])) reject('ZIP and ZIP64 directories disagree');
+    [count, size, offset] = values;
+  } else if (count === 0xffff || size === 0xffffffff || offset === 0xffffffff) reject('the ZIP64 locator is missing');
+  if (!count || count > limits.files || count > MAX_ENTRIES) reject('the ZIP entry count exceeds the selected limit');
+  if (size > MAX_DIRECTORY_BYTES || size < count * 46 || offset + size !== boundary) reject('the ZIP directory exceeds the bounded metadata budget or is inconsistent');
+  return { count, size, offset, zip64 };
+}
+
+function sizes(header, extra) {
+  let expanded = header.readUInt32LE(24), compressed = header.readUInt32LE(20), offset = header.readUInt32LE(42), disk = header.readUInt16LE(34);
+  let zip64;
+  for (let at = 0; at < extra.length;) {
+    if (at + 4 > extra.length) reject('a ZIP extra field is truncated');
+    const kind = extra.readUInt16LE(at), size = extra.readUInt16LE(at + 2); at += 4;
+    if (at + size > extra.length) reject('a ZIP extra field is truncated');
+    if (kind === 1) { if (zip64) reject('duplicate ZIP64 extra fields'); zip64 = extra.subarray(at, at + size); }
+    at += size;
+  }
+  let at = 0;
+  const next = () => { if (!zip64 || at + 8 > zip64.length) reject('a ZIP64 file size is missing'); const value = number64(zip64, at); at += 8; return value; };
+  if (expanded === 0xffffffff) expanded = next();
+  if (compressed === 0xffffffff) compressed = next();
+  if (offset === 0xffffffff) offset = next();
+  if (disk === 0xffff) { if (!zip64 || at + 4 > zip64.length) reject('a ZIP64 disk field is missing'); disk = zip64.readUInt32LE(at); }
+  if (disk) reject('split ZIP archives are unsupported');
+  return { expanded, compressed, offset };
+}
+
+async function prefix(archive, file, length) {
+  if (length > 1024 ** 2 || length > file.expanded) reject('the native executable header is outside the bounded metadata window');
+  const source = Readable.from(archive.chunks({ start: file.dataOffset, end: file.dataEnd }), { objectMode: false, highWaterMark: 65536 });
+  const output = file.method === 8 ? source.pipe(createInflateRaw({ chunkSize: 16384 })) : source;
+  const parts = []; let total = 0;
+  const timer = setTimeout(() => { source.destroy(Error('header timeout')); output.destroy(Error('header timeout')); }, 5000);
+  source.on('error', error => output.destroy(error));
+  try {
+    for await (const chunk of output) {
+      const take = chunk.subarray(0, length - total); parts.push(take); total += take.length;
+      if (total === length) return Buffer.concat(parts, total);
+    }
+    reject('the native executable header is truncated');
+  } catch { reject('the native executable header could not be inspected within its bound'); }
+  finally { clearTimeout(timer); source.destroy(); output.destroy(); }
+}
+
+async function nativeHeader(archive, file, format, requirements) {
+  const os = format === 'linux-executable' ? 'linux' : 'windows';
+  if (requirements?.os !== os || !['arm64', 'x86_64'].includes(requirements.architecture)) reject('the native format does not match the selected profile requirements');
+  const header = await prefix(archive, file, 64); let architecture, binaryFormat;
+  if (os === 'linux') {
+    if (header.subarray(0, 4).toString('hex') !== '7f454c46' || header[4] !== 2 || header[5] !== 1 || header[6] !== 1
+      || ![2, 3].includes(header.readUInt16LE(16))) reject('the Linux entrypoint must be a little-endian ELF64 executable');
+    architecture = { 62: 'x86_64', 183: 'arm64' }[header.readUInt16LE(18)]; binaryFormat = 'ELF64';
+  } else {
+    if (header.subarray(0, 2).toString() !== 'MZ') reject('the Windows entrypoint must be a PE executable');
+    const at = header.readUInt32LE(60);
+    if (at < 64 || at > 1024 ** 2 - 26) reject('the PE header offset exceeds the bounded metadata window');
+    const pe = await prefix(archive, file, at + 26);
+    if (pe.readUInt32LE(at) !== 0x00004550 || pe.readUInt16LE(at + 24) !== 0x20b) reject('the Windows entrypoint must be a PE32+ executable');
+    architecture = { 0x8664: 'x86_64', 0xaa64: 'arm64' }[pe.readUInt16LE(at + 4)]; binaryFormat = 'PE32+';
+  }
+  if (architecture !== requirements.architecture) reject('the executable architecture does not match the selected profile');
+  return { os, architecture, binaryFormat, runtimeCompatibilityProven: false };
+}
+
+export async function inspectBuildArchive(archive, { limits: supplied, format, entrypoint, requirements } = {}) {
+  const limits = buildLimits(supplied);
+  if (!['web', 'godot-project', 'linux-executable', 'windows-executable'].includes(format)) reject('the selected runtime format is unsupported');
+  if (typeof entrypoint !== 'string' || entrypoint.length > 240 || !/^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(entrypoint)) reject('the entrypoint does not match the current server path policy');
+  const wanted = safePath(entrypoint, limits.depth);
+  if (format === 'web' && !wanted.endsWith('.html') || format === 'godot-project' && wanted.split('/').at(-1) !== 'project.godot'
+    || format === 'windows-executable' && !wanted.toLowerCase().endsWith('.exe')) reject('the entrypoint does not match the selected format');
+  const dir = await directory(archive, limits), paths = new Map(), explicit = new Set(), ranges = [];
+  let cursor = dir.offset, expandedBytes = 0, files = 0, found = false, pathBytes = 0, nativeFile;
+  for (let index = 0; index < dir.count; index++) {
+    const h = await archive.read(cursor, 46);
+    if (h.readUInt32LE(0) !== 0x02014b50) reject('a ZIP directory entry is invalid');
+    const flags = h.readUInt16LE(8), method = h.readUInt16LE(10), nameBytes = h.readUInt16LE(28), extraBytes = h.readUInt16LE(30), commentBytes = h.readUInt16LE(32);
+    if (flags & 0x41 || ![0, 8].includes(method)) reject('encrypted or unsupported ZIP compression');
+    if (!nameBytes || nameBytes > MAX_PATH_BYTES || cursor + 46 + nameBytes + extraBytes + commentBytes > dir.offset + dir.size) reject('a ZIP directory entry is oversized');
+    const nameBuffer = await archive.read(cursor + 46, nameBytes), nameText = nameBuffer.toString('utf8');
+    const isDirectory = nameText.endsWith('/'), name = safePath(nameText, limits.depth, isDirectory), folded = name.toLowerCase();
+    if (explicit.has(folded)) reject('duplicate ZIP paths'); explicit.add(folded);
+    const parts = name.split('/');
+    for (let n = 1; n <= parts.length; n++) {
+      const prefix = parts.slice(0, n).join('/'), key = prefix.toLowerCase(), kind = n < parts.length || isDirectory ? 'directory' : 'file', prior = paths.get(key);
+      if (prior && (prior.name !== prefix || prior.kind !== kind)) reject('colliding ZIP paths');
+      if (!prior) { pathBytes += Buffer.byteLength(prefix); if (pathBytes > MAX_DIRECTORY_BYTES) reject('the ZIP path index exceeds the bounded metadata budget'); }
+      paths.set(key, { name: prefix, kind });
+    }
+    const mode = h.readUInt32LE(38) >>> 16, type = mode & 0xf000;
+    if (type && type !== (isDirectory ? 0x4000 : 0x8000) || mode & 0x0e00 || !isDirectory && h.readUInt32LE(38) & 0x10) reject('links, devices or privileged ZIP entries are unsupported');
+    const extra = await archive.read(cursor + 46 + nameBytes, extraBytes), size = sizes(h, extra);
+    if (size.expanded > limits.fileBytes || BigInt(size.expanded) > BigInt(Math.max(1, size.compressed)) * BigInt(limits.ratio)) reject('a file exceeds the selected size or compression-ratio limit');
+    if (isDirectory && (size.expanded || size.compressed)) reject('a ZIP directory contains file data');
+    expandedBytes += size.expanded;
+    if (!Number.isSafeInteger(expandedBytes) || expandedBytes > limits.expandedBytes) reject('the expanded build exceeds the selected limit');
+    const local = await archive.read(size.offset, 30);
+    if (local.readUInt32LE(0) !== 0x04034b50 || local.readUInt16LE(6) !== flags || local.readUInt16LE(8) !== method
+      || local.readUInt16LE(26) !== nameBytes) reject('local and central ZIP headers disagree');
+    if (!(await archive.read(size.offset + 30, nameBytes)).equals(nameBuffer)) reject('local and central ZIP filenames disagree');
+    const dataEnd = size.offset + 30 + nameBytes + local.readUInt16LE(28) + size.compressed;
+    if (!Number.isSafeInteger(dataEnd) || dataEnd > dir.offset) reject('file data overlaps the ZIP directory');
+    ranges.push([size.offset, dataEnd]);
+    if (!isDirectory) { files++; if (name === wanted) { if (!size.expanded) reject('the entrypoint is empty'); found = true;
+      nativeFile = { ...size, method, dataOffset: size.offset + 30 + nameBytes + local.readUInt16LE(28), dataEnd }; } }
+    cursor += 46 + nameBytes + extraBytes + commentBytes;
+  }
+  if (cursor !== dir.offset + dir.size || !found) reject('the declared entrypoint is absent or the directory is inconsistent');
+  ranges.sort((a, b) => a[0] - b[0]);
+  for (let i = 1; i < ranges.length; i++) if (ranges[i][0] < ranges[i - 1][1]) reject('ZIP file data overlaps');
+  await archive.check();
+  const nativeBinaryMetadata = format.endsWith('-executable') ? await nativeHeader(archive, nativeFile, format, requirements) : null;
+  return { archiveBytes: archive.size, expandedBytes, entries: dir.count, files, format, entrypoint: wanted,
+    zip64: dir.zip64, metadataVerified: true, nativeBinaryMetadata, contentsVerified: false, serverValidationRequired: true, runtimeCompatibilityProven: false };
+}
+
+export async function preflightBuildArchive(filename, options) {
+  const archive = await openBuildArchive(filename, options);
+  try { return await inspectBuildArchive(archive, options); } finally { await archive.close(); }
+}

package/src/hosted/buildUpload.js

@@ -0,0 +1,118 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open } from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { CliError } from '../errors.js';
+import { ApiError } from '../api/errors.js';
+import { writeJson } from '../fsutil.js';
+import { openBuildArchive, inspectBuildArchive, buildLimits, limitsFromProfile } from './archivePreflight.js';
+
+const fail = message => { throw new CliError(message); };
+const base = game => `/api/v1/games/${encodeURIComponent(game)}/playtest/hosted`;
+const body = answer => answer.body;
+const money = cents => `$${(cents / 100).toFixed(2)}`;
+
+export function singlePut(upload, { size, sha256, uploadExpiresAt }, now = Date.now()) {
+  const url = new URL(upload?.url), headers = upload?.headers;
+  if (upload.method !== 'PUT' || url.protocol !== 'https:' || url.username || url.password || url.hash
+    || !/^[a-z0-9.-]+\.s3\.[a-z0-9-]+\.amazonaws\.com$/.test(url.hostname)) fail('The server did not return a supported private S3 upload destination. Preserve the original upload journal.');
+  const expected = { 'content-type': 'application/zip', 'if-none-match': '*', 'x-amz-checksum-sha256': Buffer.from(sha256, 'hex').toString('base64'), 'x-amz-server-side-encryption': 'AES256' };
+  if (!headers || Object.keys(headers).sort().join(',') !== Object.keys(expected).sort().join(',')
+    || Object.entries(expected).some(([key, value]) => headers[key] !== value)) fail('The upload headers do not match the inspected archive. Preserve the original upload journal.');
+  const signed = url.searchParams.get('X-Amz-Date'), seconds = Number(url.searchParams.get('X-Amz-Expires'));
+  if (!/^\d{8}T\d{6}Z$/.test(signed || '') || !Number.isInteger(seconds) || seconds < 1 || seconds > 604800) fail('The upload URL has an invalid expiry.');
+  const at = Date.parse(`${signed.slice(0, 4)}-${signed.slice(4, 6)}-${signed.slice(6, 8)}T${signed.slice(9, 11)}:${signed.slice(11, 13)}:${signed.slice(13, 15)}Z`);
+  const until = Math.min(at + seconds * 1000, Date.parse(uploadExpiresAt));
+  if (!Number.isFinite(until) || until <= now || !Number.isSafeInteger(size) || size < 1) fail('The original upload URL has expired. Do not create a replacement reservation automatically.');
+  return { url: url.href, headers: { ...expected, 'content-length': String(size) }, expiresAt: until };
+}
+
+export async function putArchive(archive, transfer, { fetchImpl = globalThis.fetch, signal, onProgress } = {}) {
+  await archive.check();
+  const remaining = transfer.expiresAt - Date.now();
+  if (remaining <= 0) fail('The original upload URL has expired.');
+  const deadline = AbortSignal.timeout(Math.min(remaining, 2147483647));
+  const combined = signal ? AbortSignal.any([signal, deadline]) : deadline;
+  const stream = Readable.from(archive.chunks({ onProgress }), { objectMode: false, highWaterMark: 65536 });
+  try {
+    const response = await fetchImpl(transfer.url, { method: 'PUT', headers: transfer.headers, body: stream,
+      duplex: 'half', redirect: 'error', signal: combined });
+    if (!response.ok) fail(`The original archive upload returned HTTP ${response.status}. Preserve the journal; no replacement reservation was requested.`);
+    await archive.check();
+  } finally { stream.destroy(); }
+}
+
+async function journalOnce(filename, value) {
+  await mkdir(path.dirname(filename), { recursive: true, mode: 0o700 });
+  let handle;
+  try { handle = await open(filename, 'wx', 0o600); }
+  catch (error) {
+    if (error.code === 'EEXIST') fail(`An original build upload already has this journal: ${filename}. Reconcile it before starting another paid upload.`);
+    throw error;
+  }
+  try { await handle.writeFile(JSON.stringify(value, null, 2) + '\n'); await handle.sync(); }
+  finally { await handle.close(); }
+}
+
+// All metadata checks and a streamed checksum precede the confirmation and
+// 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.');
+  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.');
+  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'
+    || offer.refund !== 'after_cleanup' || !/^[a-f0-9]{64}$/.test(offer.version || '')) fail('The server did not provide the supported validation-hold offer.');
+  if (caps.funding?.eligible === false) fail('The server reports insufficient prepaid funding. No reservation or top-up was requested.');
+  const archive = await openBuildArchive(filename, { signal });
+  try {
+    onProgress({ phase: 'preflight' });
+    const measurement = await inspectBuildArchive(archive, { limits, format: profile.format, entrypoint, requirements: profile.capacity?.requirements });
+    onProgress({ phase: 'hash', completedBytes: 0, totalBytes: archive.size });
+    const sha256 = await archive.sha256({ onProgress: (completedBytes, totalBytes) => onProgress({ phase: 'hash', completedBytes, totalBytes }) });
+    const prepared = { ...measurement, sha256, profileVersion, limits, capacity: profile.capacity || null,
+      validationHoldCents: offer.amountCents, funding: caps.funding || null, gameplayQuoteRequired: true };
+    await onPrepared(prepared);
+    if (dryRun) return { state: 'preflight_only', ...prepared, walletMutationRequested: false };
+    if (!await confirm(`Reserve ${money(offer.amountCents)} from prepaid funds for this build’s static validation? It is returned after safe cleanup and is separate from the gameplay quote.`)) {
+      return { state: 'declined', walletMutationRequested: false };
+    }
+    await archive.check();
+    const input = { sha256, bytes: archive.size, entrypoint, args: [], reservation: { amountCents: offer.amountCents, version: offer.version },
+      validation: { kind: 'recorded_graphical', format: profile.format, profileVersion, selfContained: true } };
+    const identity = createHash('sha256').update(JSON.stringify({ apiUrl, gameId, sha256, profileVersion, entrypoint })).digest('hex');
+    const journal = journalPath || path.join(repoRoot, '.ravensight', 'hosted-uploads', identity + '.json');
+    const state = { version: 1, apiUrl, gameId, profileVersion, archive: path.resolve(filename), measurement, sha256,
+      idempotencyKey: randomUUID(), input, phase: 'reservation_unknown', createdAt: new Date().toISOString() };
+    await journalOnce(journal, state); // durable intent BEFORE the paid POST
+    try {
+      onProgress({ phase: 'reservation' });
+      const answer = body(await api.request('POST', `${base(gameId)}/builds`, { body: input, headers: { 'Idempotency-Key': state.idempotencyKey }, idempotent: false }));
+      if (!/^pt_build_[a-f0-9-]{1,100}$/.test(answer?.build?.buildId || '')) fail('The upload reservation response needs reconciliation.');
+      state.buildId = answer.build.buildId; state.phase = 'reserved'; await writeJson(journal, state, { mode: 0o600 });
+      const transfer = singlePut(answer.upload, { size: archive.size, sha256, uploadExpiresAt: answer.uploadExpiresAt });
+      state.phase = 'upload_unknown'; await writeJson(journal, state, { mode: 0o600 });
+      onProgress({ phase: 'upload', completedBytes: 0, totalBytes: archive.size });
+      await putArchive(archive, transfer, { fetchImpl, signal,
+        onProgress: (completedBytes, totalBytes) => onProgress({ phase: 'upload', completedBytes, totalBytes }) });
+      state.phase = 'uploaded'; await writeJson(journal, state, { mode: 0o600 });
+      onProgress({ phase: 'completion' });
+      const completed = body(await api.request('POST', `${base(gameId)}/builds/${encodeURIComponent(state.buildId)}/complete`, { idempotent: true }));
+      state.phase = 'awaiting_validation'; state.serverBuild = completed; await writeJson(journal, state, { mode: 0o600 });
+      return { state: state.phase, buildId: state.buildId, journal, walletMutationRequested: true, validationHoldCents: offer.amountCents,
+        multipartSupported: false, uploadResumeSupported: false, gameplayStarted: false };
+    } catch (error) {
+      if (error instanceof ApiError && [401, 403].includes(error.status)) {
+        error.message += ` Original upload journal: ${journal}; no replacement reservation was requested.`;
+        throw error;
+      }
+      throw new CliError(`The original build upload needs review. Preserve ${journal}; its phase is ${state.phase}. No new reservation, multipart restart or gameplay request was issued.`, 1, { cause: error });
+    }
+  } finally { await archive.close(); }
+}

package/src/hosted/recordedRun.js

@@ -0,0 +1,191 @@
+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 { ApiError } from '../api/errors.js';
+import { stableStringify } from '../fsutil.js';
+
+const MAX_QUOTE_BYTES = 1024 * 1024;
+const CONSENT_KEYS = ['quoteId', 'planHash', 'profileVersion', 'controllers', 'includeVideo', 'includeTranscript',
+  'totalPriceCents', 'dueNowCents', 'priceVersion', 'policyVersion'];
+const PROVIDERS = ['anthropic', 'openai'];
+const base = game => `/api/v1/games/${encodeURIComponent(game)}/playtest/hosted`;
+const digest = value => createHash('sha256').update(stableStringify(value)).digest('hex');
+const fail = message => { throw new CliError(message); };
+const id = value => typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,128}$/.test(value);
+const hex = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const cents = value => Number.isSafeInteger(value) && value >= 0;
+const money = value => `$${(value / 100).toFixed(2)}`;
+const same = (a, b) => stableStringify(a) === stableStringify(b);
+
+function origin(value) {
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) fail('Choose a supported API URL.');
+  return url.href.replace(/\/+$/, '');
+}
+
+async function exclusiveJson(filename, value) {
+  await mkdir(path.dirname(filename), { recursive: true, mode: 0o700 });
+  let handle;
+  try { handle = await open(filename, 'wx', 0o600); }
+  catch (error) {
+    if (error.code === 'EEXIST') fail(`An original hosted record already exists at ${filename}. Preserve it and reconcile it; no replacement request was sent.`);
+    throw error;
+  }
+  try { await handle.writeFile(JSON.stringify(value, null, 2) + '\n'); await handle.sync(); }
+  finally { await handle.close(); }
+}
+
+export async function readHostedQuote(filename) {
+  const handle = await open(filename, 'r');
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size < 1 || stat.size > MAX_QUOTE_BYTES) fail('Choose a saved hosted quote file no larger than 1 MiB.');
+    const buffer = Buffer.alloc(stat.size + 1);
+    let bytes = 0;
+    while (bytes < buffer.length) {
+      const row = await handle.read(buffer, bytes, buffer.length - bytes, bytes);
+      if (!row.bytesRead) break;
+      bytes += row.bytesRead;
+    }
+    if (bytes !== stat.size) fail('The saved quote changed while it was read. Nothing was charged.');
+    try { return JSON.parse(buffer.subarray(0, bytes).toString('utf8')); }
+    catch { fail('The saved hosted quote is not valid JSON. Nothing was charged.'); }
+  } finally { await handle.close(); }
+}
+
+function requestFor({ buildId, profileVersion, persona, standardProvider, includeVideo = false, includeTranscript = false }, profile) {
+  if (!id(buildId) || !id(profileVersion) || typeof persona !== 'string' || persona.length > 48
+    || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(persona)) fail('Choose a validated build, ready profile and one persona.');
+  if (standardProvider !== undefined && !PROVIDERS.includes(standardProvider)) fail('Choose anthropic or openai for Standard.');
+  if (typeof includeVideo !== 'boolean' || typeof includeTranscript !== 'boolean') fail('Choose explicit video and transcript options.');
+  return { kind: 'recorded_graphical', buildId, personas: [persona], controllers: ['standard', 'jev'],
+    driver: profile.driver, runLength: 'standard', profileVersion, includeVideo, includeTranscript,
+    ...(standardProvider === undefined ? {} : { standardProvider }) };
+}
+
+async function available(api, gameId, profileVersion, standardProvider) {
+  const answer = await api.request('GET', `${base(gameId)}/run-capabilities`, { idempotent: true });
+  const caps = answer.body, recorded = caps?.recorded;
+  if (!recorded?.available || recorded.intakeEnabled !== true || !Array.isArray(recorded.profiles)
+    || !Array.isArray(recorded.controllers) || !['standard', 'jev'].every(value => recorded.controllers.includes(value))) {
+    fail('This server does not currently advertise ready recorded Standard/Jev runs. Nothing was charged.');
+  }
+  const matches = recorded.profiles.filter(value => value.profileVersion === profileVersion);
+  if (matches.length !== 1 || !['playwright_web', 'godot_driver'].includes(matches[0].driver)) fail('Choose exactly one currently advertised ready hosted profile. Nothing was charged.');
+  if (standardProvider !== undefined && (!PROVIDERS.includes(standardProvider)
+    || !Array.isArray(recorded.standardProviders) || !recorded.standardProviders.includes(standardProvider))) {
+    fail(`This server does not advertise ready Standard ${standardProvider}. No provider fallback or charge was requested.`);
+  }
+  return { profile: matches[0], funding: caps.funding };
+}
+
+function sum(rows, value) {
+  const total = rows.reduce((n, row) => n + value(row), 0n);
+  if (total > BigInt(Number.MAX_SAFE_INTEGER)) fail('The server quote has an unsupported price. Nothing was charged.');
+  return Number(total);
+}
+
+export function hostedConsent(quote, request, now = Date.now()) {
+  if (!quote || quote.kind !== 'recorded_graphical' || !/^hq_[a-f0-9-]{36}$/.test(quote.quoteId || '') || !hex(quote.planHash)
+    || quote.buildId !== request.buildId || quote.profileVersion !== request.profileVersion || quote.driver !== request.driver
+    || !same(quote.controllers, ['standard', 'jev']) || quote.includeVideo !== request.includeVideo || quote.includeTranscript !== request.includeTranscript
+    || quote.currency !== 'USD' || !Number.isSafeInteger(quote.expiresAt) || quote.expiresAt <= now
+    || !['localPriceCents', 'computePriceCents', 'totalPriceCents', 'dueNowCents', 'alreadyReservedCents'].every(key => cents(quote[key]))
+    || quote.totalPriceCents < 1 || BigInt(quote.localPriceCents) + BigInt(quote.computePriceCents) !== BigInt(quote.totalPriceCents)
+    || BigInt(quote.dueNowCents) + BigInt(quote.alreadyReservedCents) !== BigInt(quote.totalPriceCents)
+    || !id(quote.priceVersion) || !id(quote.policyVersion) || !['refund', 'retain'].includes(quote.customerFailure)
+    || !['refund', 'retain'].includes(quote.cancelAfterStart)) fail('The server quote changed or expired. Nothing was charged; request a fresh quote.');
+  if (!Array.isArray(quote.localBreakdown) || !quote.localBreakdown.length || !quote.localBreakdown.every(row => id(row.unit) && cents(row.unitCents) && Number.isSafeInteger(row.count) && row.count > 0)
+    || sum(quote.localBreakdown, row => BigInt(row.count) * BigInt(row.unitCents)) !== quote.localPriceCents
+    || !Array.isArray(quote.computeBreakdown) || quote.computeBreakdown.length !== 2
+    || !quote.computeBreakdown.every((row, index) => row.controller === request.controllers[index] && row.profileVersion === request.profileVersion && cents(row.priceCents))
+    || sum(quote.computeBreakdown, row => BigInt(row.priceCents)) !== quote.computePriceCents) fail('The server did not quote every Standard/Jev price. Nothing was charged.');
+  const explicit = request.standardProvider !== undefined;
+  if (explicit ? quote.standardProvider !== request.standardProvider || !hex(quote.standardProviderPolicyHash)
+    : Object.hasOwn(quote, 'standardProvider') || Object.hasOwn(quote, 'standardProviderPolicyHash')) {
+    fail('The quoted Standard provider policy does not match the requested choice. Nothing was charged.');
+  }
+  return Object.fromEntries([...CONSENT_KEYS, ...(explicit ? ['standardProvider', 'standardProviderPolicyHash'] : [])].map(key => [key, quote[key]]));
+}
+
+export function validateHostedOffer(offer, apiUrl, now = Date.now()) {
+  if (offer?.schema !== 'ravensight-hosted-recorded-quote/v1' || !offer.request || !offer.quote || !id(offer.gameId) || offer.apiUrl !== origin(apiUrl)
+    || offer.integrity !== digest({ apiUrl: offer.apiUrl, gameId: offer.gameId, request: offer.request, quote: offer.quote, consent: offer.consent })) fail('The saved quote does not match this API or its original contents. Nothing was charged.');
+  const request = requestFor({ ...offer.request, persona: offer.request.personas?.[0] }, { driver: offer.request.driver });
+  if (!same(request, offer.request) || !same(hostedConsent(offer.quote, request, now), offer.consent)) fail('The saved quote request or consent changed. Nothing was charged.');
+  return offer;
+}
+
+export async function quoteHostedRun({ api, apiUrl, gameId, output, now = Date.now, ...options }) {
+  if (!id(gameId) || !output) fail('Choose a game and an output file for the original quote.');
+  try { await access(output); fail('That saved quote already exists. Choose a new output path; the original was preserved.'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const { profile } = await available(api, gameId, options.profileVersion, options.standardProvider);
+  const request = requestFor(options, 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. No admission was requested.');
+  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) };
+  await exclusiveJson(path.resolve(output), offer);
+  return { state: 'quoted', quoteFile: path.resolve(output), ...offer, walletMutationRequested: false };
+}
+
+export function hostedQuoteLines(offer) {
+  const { quote: q, request: r } = offer;
+  return [`Game ${offer.gameId}; build ${r.buildId}; persona ${r.personas[0]}; profile ${r.profileVersion}.`,
+    `Two separate playthroughs: Standard (${r.standardProvider || 'server default Anthropic'}) then Jev.`,
+    ...(r.standardProvider ? [`Standard provider policy: ${q.standardProviderPolicyHash}.`] : []),
+    ...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'}.`,
+    `Customer failure: ${q.customerFailure}; cancellation after start: ${q.cancelAfterStart}. Price ${q.priceVersion}; refund policy ${q.policyVersion}.`,
+    `Quote expires ${new Date(q.expiresAt).toISOString()}.`];
+}
+
+// A saved durable intent is never retried, even with the same quote or a new
+// capability response. The server also receives a stable key for this plan.
+export async function runHostedQuote({ filename, api, apiUrl, repoRoot, confirm, onPrepared = () => {}, now = Date.now }) {
+  const offer = validateHostedOffer(await readHostedQuote(filename), 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`);
+  try { await access(journal); fail(`This hosted quote already has an admission intent at ${journal}. Reconcile the original outcome; no POST was repeated.`); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const { profile, funding } = await available(api, offer.gameId, offer.request.profileVersion, offer.request.standardProvider);
+  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 };
+  validateHostedOffer(offer, apiUrl, now());
+  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() };
+  await exclusiveJson(journal, state); // fsync BEFORE the only wallet-mutating POST
+  try {
+    let responseCaptured = false;
+    const answer = await api.request('POST', `${base(offer.gameId)}/runs`, { body: offer.consent,
+      headers: { 'Idempotency-Key': state.idempotencyKey }, idempotent: false, raw: true,
+      onResponseRaw: async ({ status, contentType, bytes, bodyComplete }) => {
+        await exclusiveJson(journal + '.response.json', { status, contentType, bodyComplete,
+          bodyBase64: bytes.toString('base64'), bodyBytes: bytes.length,
+          bodySha256: createHash('sha256').update(bytes).digest('hex') });
+        responseCaptured = true;
+      } });
+    if (!responseCaptured) fail('The admission response was not captured. Preserve the original intent.');
+    if (answer.status !== 202 || answer.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/json'
+      || typeof answer.body !== 'string' || Buffer.byteLength(answer.body) > MAX_QUOTE_BYTES) fail('The admission acknowledgement needs reconciliation.');
+    const ack = JSON.parse(answer.body);
+    if (!same(Object.keys(ack).sort(), ['admissionId', 'dispatchAllowed', 'jobId', 'state', 'totalPriceCents'])
+      || ack.state !== 'charged_blocked' || ack.dispatchAllowed !== false || ack.totalPriceCents !== offer.quote.totalPriceCents
+      || !/^ha_[a-f0-9-]{36}$/.test(ack.admissionId || '') || !/^pt_job_[a-f0-9]{20}$/.test(ack.jobId || '')) fail('The admission acknowledgement needs reconciliation.');
+    state.phase = 'charged_blocked'; state.admission = ack;
+    await exclusiveJson(journal + '.acknowledged.json', state);
+    await rename(journal + '.acknowledged.json', journal);
+    return { state: 'charged_blocked', ...ack, journal, replayAuthorized: false, gameplayProven: false };
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 401) throw error;
+    fail(`The original admission outcome needs reconciliation. Preserve ${journal}; no retry or replacement admission was requested.`);
+  }
+}