ravensight-playtest 0.5.0 → 0.5.2

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.`);
+  }
+}

package/src/run/drivers/stdio.js

@@ -18,7 +18,7 @@ export async function readBridgeConfig(file) {
 }
 
 export function createStdioDriver({ spawn: spawnImpl = spawn, timeoutMs = 30000 } = {}) {
-  let child, buffer = '', nextId = 0, runDirectory, step = 0, shots = 0, lastHash;
+  let child, childState, buffer = '', nextId = 0, runDirectory, step = 0, shots = 0, lastHash;
   const pending = new Map();
   const fail = message => {
     for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(new DriverError(message, { fatal: true })); }
@@ -52,6 +52,9 @@ export function createStdioDriver({ spawn: spawnImpl = spawn, timeoutMs = 30000
       const config = await readBridgeConfig(target);
       runDirectory = runDir;
       child = spawnImpl(config.command, config.args || [], { cwd: config.cwd || path.dirname(path.resolve(target)), shell: false, stdio: ['pipe', 'pipe', 'pipe'] });
+      const state = { process: child, closed: false, stopping: null };
+      state.close = new Promise(resolve => child.once('close', () => { state.closed = true; resolve(); }));
+      childState = state;
       child.stdout.setEncoding('utf8');
       child.stdout.on('data', chunk => {
         buffer += chunk;
@@ -92,20 +95,33 @@ export function createStdioDriver({ spawn: spawnImpl = spawn, timeoutMs = 30000
     async screenshot(reason) {
       const image = await request('screenshot');
       if (typeof image?.pngBase64 !== 'string' || !image.pngBase64.startsWith('iVBORw0KGgo')) throw new DriverError('This bridge did not return a PNG screenshot.');
-      const relativePath = path.join('screenshots', screenshotName(++shots, reason));
+      const relativePath = path.posix.join('screenshots', screenshotName(++shots, reason));
       const file = path.join(runDirectory, relativePath);
       await fs.writeFile(file, Buffer.from(image.pngBase64, 'base64'));
       return { path: file, relativePath };
     },
     async consoleErrors() { return []; },
     async stop() {
-      if (child && child.exitCode === null && !child.killed) {
-        child.kill('SIGTERM');
-        const process = child;
-        const timer = setTimeout(() => { if (process.exitCode === null) process.kill('SIGKILL'); }, 1000);
-        timer.unref();
-      }
       fail('Game bridge stopped.');
+      const state = childState;
+      if (state && !state.stopping) {
+        state.stopping = (async () => {
+          if (state.closed) return;
+          const process = state.process;
+          let deadline;
+          const force = setTimeout(() => { if (!state.closed) process.kill('SIGKILL'); }, 1000);
+          try {
+            const timedOut = new Promise((resolve, reject) => {
+              deadline = setTimeout(() => reject(new DriverError('Game bridge did not close after stopping.', { fatal: true })), 5000);
+            });
+            if (process.exitCode === null && process.signalCode === null && !process.killed) process.kill('SIGTERM');
+            // Windows can retain the bridge's cwd until its pipes close, even
+            // after exit. Concurrent/repeated stops share the same close wait.
+            await Promise.race([state.close, timedOut]);
+          } finally { clearTimeout(force); clearTimeout(deadline); }
+        })();
+      }
+      if (state) await state.stopping;
       return { videoPath: null };
     }
   };

package/src/run/drivers/web.js

@@ -1706,7 +1706,9 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
     async screenshot(name) {
       const current = requirePage();
       shots += 1;
-      const relativePath = path.join('screenshots', screenshotName(shots, name));
+      // Forward slashes on every platform: this is the evidence ref the server
+      // matches against upload paths.
+      const relativePath = path.posix.join('screenshots', screenshotName(shots, name));
       const absolute = path.join(runDirectory, relativePath);
       await mkdir(path.dirname(absolute), { recursive: true });
       await current.screenshot({ path: absolute, type: 'png', timeout: ACTION_TIMEOUT_MS });

package/src/run/drivers/webdriver.js

@@ -61,7 +61,7 @@ export function createWebDriverAdapter({name='desktop_driver',fetch:fetchImpl=gl
    }catch(error){return {ok:false,changed:false,error:error instanceof DriverError?error.message:'Device input failed.'};}
    finally {if(session)await request('DELETE',route('/actions')).catch(()=>{});}
   },
-  async screenshot(reason){const relativePath=path.join('screenshots',screenshotName(++shots,reason));const file=path.join(runDirectory,relativePath);await fs.writeFile(file,Buffer.from(await frame(),'base64'));return {path:file,relativePath,reason};},
+  async screenshot(reason){const relativePath=path.posix.join('screenshots',screenshotName(++shots,reason));const file=path.join(runDirectory,relativePath);await fs.writeFile(file,Buffer.from(await frame(),'base64'));return {path:file,relativePath,reason};},
   async consoleErrors(){return [];},
   async stop(){if(session){const current=route('');session=null;await request('DELETE',current);}return {videoPath:null};}
  };return driver;