ravensight-playtest 0.3.2 → 0.5.0

package/src/run/personaLoop.js

@@ -211,7 +211,7 @@ export async function runPersona(args) {
     // game", and a launch that hangs or dies should leave the server holding
     // that rather than still holding `queued`.
     await advance('launching');
-    await driver.launch({ target, runDir: runDirectory, recordVideo, viewport });
+    await driver.launch({ target, runDir: runDirectory, recordVideo, viewport, signal: args.signal });
     await advance('playing');
 
     const play = await playLoop({
@@ -231,8 +231,9 @@ export async function runPersona(args) {
     outcome = { ...outcome, ...play };
 
     const endedAt = new Date().toISOString();
-    await driverStop(driver, outcome, log);
+    await driverStop(driver, outcome, log, play.canceled ? 'canceled' : 'completed');
 
+    if (args.signal?.aborted || heartbeat?.canceled) play.canceled = true;
     if (play.canceled) {
       outcome.state = 'canceled';
       outcome.quitReason = play.quitReason || 'error';
@@ -258,6 +259,7 @@ export async function runPersona(args) {
     }
 
     await advance('reporting');
+    if (args.signal?.aborted || heartbeat?.canceled) throw new Error('The playthrough was interrupted before reporting.');
     onProgress({ phase: 'reporting', persona: persona.slug });
 
     const written = await reportPhase({
@@ -293,7 +295,7 @@ export async function runPersona(args) {
     outcome.quitDetail = written.report.quit_detail || '';
     return finish(outcome, ledger, runDirectory, transcript, heartbeat);
   } catch (error) {
-    await driverStop(driver, outcome, log);
+    await driverStop(driver, outcome, log, args.signal?.aborted ? 'canceled' : 'failed');
     if (error instanceof ProxyError && error.isBudget) {
       outcome.state = 'budget_exceeded';
       outcome.quitReason = 'cost_cap';
@@ -327,6 +329,7 @@ export async function runPersona(args) {
 async function playLoop({
   api,
   controller = 'standard',
+  signal: argsSignal,
   client,
   jobId,
   runId,
@@ -355,11 +358,11 @@ async function playLoop({
   const identity = runIdentity({ persona, runId });
   const secrets = secretsOf(localBrief);
   const noisePatterns = (localBrief && Array.isArray(localBrief.expected_noise)) ? localBrief.expected_noise : [];
-  if (controller === 'jev') system.push({ type: 'text', text: JEV_CONTROLLER_PROMPT });
+  if (['jev', 'rune'].includes(controller)) system.push({ type: 'text', text: JEV_CONTROLLER_PROMPT });
   const availableTools = driver.supportedActions
     ? [...PLAY_TOOLS, ...(driver.supportedActions.includes('swipe') ? [SWIPE_TOOL] : [])].filter(tool => !ACTION_TOOLS.includes(tool.name) || driver.supportedActions.includes(tool.name))
     : PLAY_TOOLS;
-  const playTools = controller === 'jev' ? availableTools.map(tool => ({
+  const playTools = ['jev', 'rune'].includes(controller) ? availableTools.map(tool => ({
     ...tool,
     input_schema: {
       ...tool.input_schema,
@@ -426,7 +429,7 @@ async function playLoop({
   });
 
   while (turns < maxTurns && actions < maxActions) {
-    if (heartbeat && heartbeat.canceled) {
+    if (argsSignal?.aborted || (heartbeat && heartbeat.canceled)) {
       canceled = true;
       quitReason = 'error';
       quitDetail = 'the job was cancelled';
@@ -485,6 +488,7 @@ async function playLoop({
       if (typeof onBudgetWarning === 'function') await onBudgetWarning();
     }
 
+    if (argsSignal?.aborted || heartbeat?.canceled) { canceled = true; quitReason = 'error'; quitDetail = 'the job was cancelled'; break; }
     if (answer.toolUses.length === 0) {
       // No tool call is how a persona stops: there is no quit tool in the
       // step's allowlist, and adding one would be refused by the proxy.
@@ -495,14 +499,15 @@ async function playLoop({
     }
 
     let selection = null;
-    if (controller === 'jev') {
+    if (['jev', 'rune'].includes(controller)) {
       try {
-        selection = await selectAction({ api, jobId, runId, persona, observation: `${visualObservation ? '' : latestObservation}\nScreen interpretation: ${answer.toolUses.map(tool => tool.input?.visible_state || '').filter(Boolean).join('\n') || answer.text}`, toolUses: answer.toolUses, recentActions, intentNotes });
+        selection = await selectAction({ api, jobId, runId, persona, controller, observation: `${visualObservation ? '' : latestObservation}\nScreen interpretation: ${answer.toolUses.map(tool => tool.input?.visible_state || '').filter(Boolean).join('\n') || answer.text}`, toolUses: answer.toolUses, recentActions, intentNotes });
       } catch (error) {
         if (error instanceof ProxyError && error.isBudget) { budgetExceeded = true; quitReason = 'cost_cap'; quitDetail = error.message; break; }
         if (error instanceof ProxyError && error.isClosed) { canceled = true; quitDetail = error.message; break; }
         throw error;
       }
+      if (argsSignal?.aborted || heartbeat?.canceled) { canceled = true; quitReason = 'error'; quitDetail = 'the job was cancelled'; break; }
       transcript.write({ kind: 'action_selection', source: selection.source || 'jev', status: selection.status, confidence: selection.confidence, selected_tool_id: selection.toolId, reason: selection.reason });
       if (selection.status !== 'selected') { quitReason = 'persona_quit'; quitDetail = 'Ravensight Playtester stopped for review: ' + selection.reason; break; }
       if (selection.budget === 'warn' && !budgetWarned) {
@@ -518,6 +523,7 @@ async function playLoop({
     // its actions changes the screen, a later ref may name something else.
     let screenChangedThisTurn = false;
     for (const toolUse of answer.toolUses) {
+      if (argsSignal?.aborted || heartbeat?.canceled) { canceled = true; quitReason = 'error'; quitDetail = 'the job was cancelled'; break; }
       if (selection && toolUse.id !== selection.toolId) { results.push({ type: 'tool_result', tool_use_id: toolUse.id, content: 'Alternative not selected. No action executed.' }); continue; }
       const notesBefore = notes.length;
       const executed = await executeTool({
@@ -1437,9 +1443,10 @@ async function safeScreenshot(driver, name, screenshots, transcript, observation
   }
 }
 
-async function driverStop(driver, outcome, log) {
+async function driverStop(driver, outcome, log, reason) {
   try {
-    const stopped = await driver.stop();
+    const stopped = await driver.stop({ reason });
+    if (stopped?.recording) outcome.recording = stopped.recording;
     if (stopped && stopped.videoPath) outcome.videoPath = stopped.videoPath;
     // The Godot driver captures frames rather than video, and stitching them
     // needs ffmpeg, which is optional. No video is a normal outcome: say

package/src/run/resume.js

@@ -1,6 +1,7 @@
 import { optionsFrom } from './args.js';
 import { getDeps } from './deps.js';
 import EXIT from './exit.js';
+import { runsMatchPlan } from './controllers.js';
 import { runDir as runDirFor } from './paths.js';
 import { buildPartialReport, readTranscript, shouldFinalize } from './regenerate.js';
 import { reconcileDroppedFindings } from './dropped.js';
@@ -57,6 +58,13 @@ export async function resumeJob({ api, gameId, jobId, job, runs, state, repoRoot
     log(`There is no journal for ${jobId} in this repository, so there is nothing to resume from. "ravensight-playtest upload ${jobId}" can still drain any pending uploads.`);
     return EXIT.ENVIRONMENT;
   }
+  const controllers = job.controllers?.length ? job.controllers : null;
+  if (journal.job_id !== jobId || journal.game_id !== gameId ||
+      JSON.stringify(journal.options?.controllers || null) !== JSON.stringify(controllers) ||
+      !runsMatchPlan(runs || [], controllers, [...new Set((runs || []).filter(row => row.module === 'persona_playtest').map(row => row.persona))])) {
+    log('The saved job/controller identity does not match the server. Nothing was replayed or charged; reconcile the saved job first.');
+    return EXIT.ENVIRONMENT;
+  }
   if (!journal.idempotency_key) {
     log('That journal has no idempotency key, so the per-run tokens cannot be minted again safely. Start a new job instead.');
     return EXIT.ENVIRONMENT;
@@ -142,7 +150,9 @@ export async function resumeJob({ api, gameId, jobId, job, runs, state, repoRoot
   // nothing is charged. The tokens that come back are new ones.
   const replayed = await api.jobs.register(gameId, {
     modules,
+    resume_job_id: jobId,
     personas: slugs,
+    ...(journal.options?.controllers ? { controllers: journal.options.controllers } : {}),
     driver: driverName,
     cli_version: deps.cliVersion || api.cliVersion,
     confirm_price_cents: Number.isInteger(journal.price_cents) ? journal.price_cents : 0,
@@ -154,11 +164,10 @@ export async function resumeJob({ api, gameId, jobId, job, runs, state, repoRoot
     pack_versions: { pack: pack.pack_version }
   }, { idempotencyKey: journal.idempotency_key });
 
-  if (!replayed.replayed) {
-    // A register that was NOT a replay means the key did not match a stored
-    // job, which means money just moved. Say so rather than letting it look
-    // like a free resume.
-    log('That idempotency key did not match a stored job, so a new job was registered and charged.');
+  const identity = rows => JSON.stringify(rows.map(row => [row.run_id, row.module, row.persona || null, row.controller || null]).sort((a, b) => a[0].localeCompare(b[0])));
+  if (replayed.replayed !== true || replayed.job_id !== jobId || identity(replayed.runs || []) !== identity(runs || [])) {
+    log('The server did not replay the exact saved job and controller runs. No playthrough was started. Reconcile this response before retrying.');
+    return EXIT.FAILED;
   }
 
   log(`resuming ${jobId}: ${outstanding.length} run(s) to play again of ${(runs || []).length}.`);
@@ -166,6 +175,8 @@ export async function resumeJob({ api, gameId, jobId, job, runs, state, repoRoot
   const resumeOptions = {
     ...options,
     controller: journal.options?.controller || options.controller || 'standard',
+    controllers,
+    recordVideo: options.recordVideo ?? journal.options?.recordVideo,
     maxActions: (journal.options && journal.options.maxActions) ?? options.maxActions,
     // The journal's answer, never the flag: a job is long or standard for good.
     runLength: journal.options?.runLength === 'long' ? 'long' : 'standard',

package/src/simulation/index.js

@@ -0,0 +1,176 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { boundedString, bridgeOptions, observation, openBridge } from './protocol.js';
+const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const MAX_TRACE_BYTES = 4 * 1024 * 1024;
+const MAX_ACTIONS = 1000000;
+const compareText = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+export function validateConfig(input) {
+  if (!input || input.version !== 1 || !boundedString(input.seed, 128)) throw new Error('Simulation config needs version 1 and a seed of 1 to 128 characters.');
+  for (const [key, max] of [['runs', 10000], ['max_steps', 10000], ['workers', 16]]) if (!Number.isInteger(input[key]) || input[key] < 1 || input[key] > max) throw new Error(`Invalid simulation ${key}.`);
+  if (!Array.isArray(input.strategies) || !input.strategies.length || input.strategies.length > 16) throw new Error('Choose 1 to 16 simulation strategies.');
+  const strategies = input.strategies.map(strategy => {
+    if (!strategy || typeof strategy.name !== 'string' || !/^[a-z][a-z0-9_-]{0,63}$/.test(strategy.name) || !['random', 'scripted', 'scored'].includes(strategy.policy)) throw new Error('Invalid simulation strategy.');
+    if (strategy.policy === 'scripted' && (!Array.isArray(strategy.actions) || !strategy.actions.length || strategy.actions.length > 10000 || strategy.actions.some(id => !boundedString(id, 128)))) throw new Error('Scripted strategy needs 1 to 10000 action IDs.');
+    return { name: strategy.name, policy: strategy.policy, ...(strategy.policy === 'scripted' ? { actions: [...strategy.actions] } : {}) };
+  });
+  if (new Set(strategies.map(s => s.name)).size !== strategies.length) throw new Error('Strategy names must be unique.');
+  const config = { version: 1, seed: input.seed, runs: input.runs, max_steps: input.max_steps, workers: input.workers, strategies };
+  if (Buffer.byteLength(JSON.stringify(config)) > 2 * 1024 * 1024) throw new Error('Simulation configuration exceeds 2 MiB.');
+  return config;
+}
+export function configHash(config) { return hash({ version: 1, seed: config.seed, runs: config.runs, max_steps: config.max_steps, workers: config.workers, strategies: config.strategies.map(({ name, policy }) => ({ name, policy })) }); }
+export function deriveSeed(seed, index) { return hash([seed, index]); }
+function choose(state, strategy, index, seed) {
+  if (strategy.policy === 'scripted') {
+    const id = strategy.actions[index];
+    if (!id) throw new Error('Scripted strategy exhausted before terminal state.');
+    if (!state.actions.some(action => action.id === id)) throw new Error('Scripted strategy selected an illegal action.');
+    return id;
+  }
+  if (strategy.policy === 'scored') {
+    const choices = state.actions.filter(action => Number.isFinite(action.scores?.[strategy.name]));
+    if (!choices.length) throw new Error('Game supplied no scores for this strategy.');
+    return choices.sort((a, b) => b.scores[strategy.name] - a.scores[strategy.name] || compareText(a.id, b.id))[0].id;
+  }
+  const choices = [...state.actions].sort((a, b) => compareText(a.id, b.id));
+  return choices[parseInt(hash([seed, index]).slice(0, 12), 16) % choices.length].id;
+}
+function stateRecord(state) { return { done: state.done, state_hash: state.state_hash, ...(state.outcome === undefined ? {} : { outcome: state.outcome }), ...(state.metrics === undefined ? {} : { metrics: state.metrics }) }; }
+async function writeJson(file, value) { await fs.writeFile(file, JSON.stringify(value) + '\n', { flag: 'wx', mode: 0o600 }); }
+export async function probeBridge({ bridge, seed = 'preflight', strategy = 'random', max_steps = 1, signal }) {
+  if (!boundedString(seed, 128) || !boundedString(strategy, 80) || !Number.isInteger(max_steps) || max_steps < 1 || max_steps > 10000) throw new Error('Invalid simulation probe.');
+  const client = openBridge(bridge, { signal });
+  try { return await client.request('simulation.start', { version: 1, seed, strategy, max_steps }); }
+  finally { await client.stop(); }
+}
+export async function runBatch({ config: rawConfig, bridge: rawBridge, outputDir, playtest, signal, onProgress }) {
+  const config = validateConfig(rawConfig); const bridge = bridgeOptions(rawBridge);
+  if (typeof outputDir !== 'string' || !outputDir) throw new Error('Simulation output directory is required.');
+  outputDir = path.resolve(outputDir); await fs.mkdir(outputDir, { recursive: true });
+  const resultsPath = path.join(outputDir, 'results.jsonl'); const file = await fs.open(resultsPath, 'wx', 0o600);
+  const started = Date.now(); const controller = new AbortController(); let stopReason = null;
+  const cancel = () => { stopReason ||= 'cancelled'; controller.abort(); };
+  signal?.addEventListener('abort', cancel, { once: true }); if (signal?.aborted) cancel();
+  const timer = setTimeout(() => { stopReason ||= 'batch_deadline'; controller.abort(); }, bridge.batchTimeoutMs);
+  let next = 0, reservedSteps = 0, writeChain = Promise.resolve(), commitTail = Promise.resolve();
+  const traces = [];
+  const summary = { version: 1, seed: config.seed, config_hash: configHash(config), requested_runs: config.runs, completed_runs: 0, failed_runs: 0, truncated_runs: 0, total_steps: 0, strategies: config.strategies.map(s => ({ name: s.name, runs: 0, completed: 0, failed: 0, truncated: 0, outcomes: {}, metrics: {} })), trace_count: 0, duration_ms: 0 };
+  async function execute(index, priorCommit) {
+    const strategy = config.strategies[index % config.strategies.length]; const seed = deriveSeed(config.seed, index);
+    const row = { version: 1, run_index: index, seed, strategy: strategy.name, status: 'failed', steps: 0 };
+    const trace = index < 10 ? { version: 1, run_index: index, seed, strategy: strategy.name, max_steps: config.max_steps, local_config_hash: hash(config), states: [], actions: [] } : null;
+    let traceBytes = 1024, client, pendingAction, phase = 'start';
+    const record = state => {
+      if (!trace) return;
+      const item = stateRecord(state); traceBytes += Buffer.byteLength(JSON.stringify(item)) + 1;
+      if (traceBytes > MAX_TRACE_BYTES) { trace.truncated = true; return; }
+      trace.states.push(item);
+    };
+    try {
+      if (controller.signal.aborted) throw new Error('Simulation stopped before run started.');
+      client = openBridge(bridge, { signal: controller.signal, playtest });
+      let state = await client.request('simulation.start', { version: 1, seed, strategy: strategy.name, max_steps: config.max_steps }); record(state);
+      while (!state.done && row.steps < config.max_steps) {
+        if (reservedSteps >= MAX_ACTIONS) { stopReason ||= 'action_budget'; controller.abort(); throw new Error('Batch action budget exhausted.'); }
+        phase = 'policy';
+        const action = choose(state, strategy, row.steps, seed); reservedSteps++;
+        pendingAction = action; phase = 'step';
+        state = await client.request('simulation.step', { action }); pendingAction = undefined; row.steps++; summary.total_steps++;
+        if (trace && !trace.truncated) { trace.actions.push(action); traceBytes += Buffer.byteLength(JSON.stringify(action)) + 1; }
+        record(state);
+      }
+      row.status = state.done ? 'completed' : 'truncated';
+      if (state.done) { row.outcome = state.outcome || 'unspecified'; row.metrics = state.metrics || {}; }
+    } catch (error) { row.error = error.message.slice(0, 200); if (trace) { trace.failure_phase = phase; if (pendingAction) trace.failed_action = pendingAction; } }
+    finally { if (client) await client.stop(); }
+    // Commit in run-index order, retaining at most one result per worker. This
+    // makes floating-point aggregate order independent of process scheduling.
+    await priorCommit;
+    const aggregate = summary.strategies[index % config.strategies.length]; aggregate.runs++;
+    summary[`${row.status}_runs`]++; aggregate[row.status]++;
+    if (row.status === 'completed') {
+      // Bound aggregate cardinality even if a malicious adapter invents a new
+      // metric/outcome name in every run. Raw per-run values remain on disk.
+      const outcome = Object.hasOwn(aggregate.outcomes, row.outcome) || Object.keys(aggregate.outcomes).length < 127 ? row.outcome : 'other';
+      aggregate.outcomes[outcome] = (Object.hasOwn(aggregate.outcomes, outcome) ? aggregate.outcomes[outcome] : 0) + 1;
+      for (const [key, value] of Object.entries(row.metrics)) {
+        if (!Object.hasOwn(aggregate.metrics, key) && Object.keys(aggregate.metrics).length >= 32) continue;
+        if (!Object.hasOwn(aggregate.metrics, key)) aggregate.metrics[key] = { count: 0, min: value, max: value, mean: 0 };
+        const metric = aggregate.metrics[key];
+        metric.count++; metric.min = Math.min(metric.min, value); metric.max = Math.max(metric.max, value);
+        // Weighted arithmetic avoids overflow from subtracting opposite extremes.
+        metric.mean = Math.max(metric.min, Math.min(metric.max, metric.mean * ((metric.count - 1) / metric.count) + value / metric.count));
+      }
+    }
+    if (trace) { if (trace.truncated) trace.actions = trace.actions.slice(0, Math.max(0, trace.states.length - 1)); trace.status = row.status; trace.error = row.error; const target = path.join(outputDir, `trace-${String(index).padStart(5, '0')}.json`); await writeJson(target, trace); traces.push(target); }
+    writeChain = writeChain.then(() => file.write(JSON.stringify(row) + '\n')); await writeChain;
+    if (onProgress) await onProgress({ finished_runs: summary.completed_runs + summary.failed_runs + summary.truncated_runs, requested_runs: config.runs, completed_runs: summary.completed_runs, failed_runs: summary.failed_runs, truncated_runs: summary.truncated_runs, total_steps: summary.total_steps });
+  }
+  try {
+    const workers = Array.from({ length: Math.min(config.workers, config.runs) }, async () => {
+      try {
+        while (next < config.runs) {
+          const index = next++; const prior = commitTail; let release;
+          commitTail = new Promise(resolve => { release = resolve; });
+          try { await execute(index, prior); } finally { release(); }
+        }
+      }
+      catch (error) { controller.abort(); throw error; }
+    });
+    const outcomes = await Promise.allSettled(workers);
+    const failure = outcomes.find(item => item.status === 'rejected');
+    if (failure) throw failure.reason;
+  }
+  finally { clearTimeout(timer); signal?.removeEventListener('abort', cancel); controller.abort(); try { await writeChain; } finally { await file.close(); } }
+  summary.trace_count = traces.length; summary.duration_ms = Math.min(bridge.batchTimeoutMs, Date.now() - started);
+  traces.sort();
+  const report = { results_path: resultsPath, stop_reason: stopReason, determinism_note: 'Replay verifies recorded observations. Reproducibility requires the game to honor its seed; this runner cannot prove determinism.' };
+  await writeJson(path.join(outputDir, 'summary.json'), summary);
+  return { summary, traces, report };
+}
+export async function replayTrace({ trace, bridge, signal, outputDir }) {
+  if (typeof trace === 'string') { if ((await fs.stat(trace)).size > MAX_TRACE_BYTES + 1024) throw new Error('Trace exceeds replay limit.'); trace = JSON.parse(await fs.readFile(trace, 'utf8')); }
+  const failedStart = trace?.status === 'failed' && trace?.failure_phase === 'start' && trace?.states?.length === 0;
+  if (!trace || trace.version !== 1 || !boundedString(trace.seed, 128) || !boundedString(trace.strategy, 80) || !Number.isInteger(trace.max_steps) || trace.max_steps < 1 || trace.max_steps > 10000 || !Array.isArray(trace.actions) || trace.actions.length > 10000 || trace.actions.some(action => !boundedString(action, 128)) || !Array.isArray(trace.states) || (!failedStart && trace.states.length !== trace.actions.length + 1) || (failedStart && trace.actions.length) || (trace.failed_action !== undefined && !boundedString(trace.failed_action, 128))) throw new Error('Trace is invalid for replay.');
+  if (Buffer.byteLength(JSON.stringify(trace)) > MAX_TRACE_BYTES + 1024) throw new Error('Trace exceeds replay limit.');
+  for (const state of trace.states) observation({ ...state, actions: state.done ? [] : [{ id: 'replay-validation' }] });
+  const options = bridgeOptions(bridge);
+  const deadline = AbortSignal.timeout(options.batchTimeoutMs);
+  const replaySignal = signal ? AbortSignal.any([signal, deadline]) : deadline;
+  const client = openBridge(options, { signal: replaySignal });
+  let result = { matched: true, matched_prefix: false, fully_replayed: false, failure_reproduced: null, first_divergence: null };
+  const start = () => client.request('simulation.start', { version: 1, seed: trace.seed, strategy: trace.strategy, max_steps: trace.max_steps });
+  async function reproduce(request, step) {
+    try {
+      const actual = await request(); result.matched = false; result.failure_reproduced = false;
+      result.first_divergence = { step, reason: 'Recorded protocol failure did not recur.', actual: stateRecord(actual) };
+    } catch (error) {
+      result.failure_reproduced = error.message === trace.error;
+      result.matched = result.failure_reproduced;
+      if (!result.matched) result.first_divergence = { step, expected_error: trace.error, actual_error: error.message };
+    }
+  }
+  try {
+    if (failedStart) await reproduce(start, 0);
+    else {
+      for (let i = 0; i < trace.states.length; i++) {
+        let state;
+        try { state = i === 0 ? await start() : await client.request('simulation.step', { action: trace.actions[i - 1] }); }
+        catch (error) { result.matched = false; result.first_divergence = { step: i, actual_error: error.message }; break; }
+        const expected = trace.states[i]; const actual = stateRecord(state);
+        const canonical = value => JSON.stringify([value.state_hash, value.done, value.outcome ?? null, Object.entries(value.metrics || {}).sort(([a], [b]) => compareText(a, b))]);
+        if (canonical(expected) !== canonical(actual)) { result.matched = false; result.first_divergence = { step: i, expected, actual }; break; }
+        if (i < trace.actions.length && !state.actions.some(action => action.id === trace.actions[i])) { result.matched = false; result.first_divergence = { step: i, reason: 'Recorded action is no longer legal.' }; break; }
+      }
+      if (result.matched) {
+        result.matched_prefix = true;
+        result.fully_replayed = !trace.truncated && trace.status !== 'failed';
+        if (trace.status === 'failed' && trace.failed_action && !trace.truncated) await reproduce(() => client.request('simulation.step', { action: trace.failed_action }), trace.states.length);
+      }
+    }
+  } finally { await client.stop(); }
+  if (outputDir) { await fs.mkdir(outputDir, { recursive: true }); const file = path.resolve(outputDir, 'replay.json'); await writeJson(file, result); result.report_path = file; }
+  return result;
+}

package/src/simulation/protocol.js

@@ -0,0 +1,90 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+const forbidden = new Set(['__proto__', 'constructor', 'prototype']);
+export const MAX_RESPONSE = 256 * 1024;
+export function boundedString(value, max) { return typeof value === 'string' && value.length > 0 && value.length <= max && !forbidden.has(value); }
+export function observation(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || typeof value.done !== 'boolean' || !boundedString(value.state_hash, 128) || !Array.isArray(value.actions) || value.actions.length > 256) throw new Error('Invalid simulation observation.');
+  const numbers = (map, limit, maxAbsolute = Infinity) => {
+    if (!map || typeof map !== 'object' || Array.isArray(map) || Object.keys(map).length > limit || Object.entries(map).some(([key, n]) => !boundedString(key, 80) || typeof n !== 'number' || (!Number.isFinite(n) || Math.abs(n) > maxAbsolute))) throw new Error('Invalid simulation numeric map.');
+    return { ...map };
+  };
+  const actions = value.actions.map(action => {
+    if (!action || !boundedString(action.id, 128)) throw new Error('Invalid simulation action.');
+    return { id: action.id, ...(action.scores === undefined ? {} : { scores: numbers(action.scores, 16) }) };
+  });
+  if (new Set(actions.map(action => action.id)).size !== actions.length) throw new Error('Duplicate simulation action.');
+  if (!value.done && !actions.length) throw new Error('Nonterminal simulation needs legal actions.');
+  if (value.outcome !== undefined && !boundedString(value.outcome, 80)) throw new Error('Invalid simulation outcome.');
+  return { done: value.done, state_hash: value.state_hash, actions, ...(value.metrics === undefined ? {} : { metrics: numbers(value.metrics, 32, 1e15) }), ...(value.outcome === undefined ? {} : { outcome: value.outcome }) };
+}
+export function bridgeOptions(bridge) {
+  // Native Windows has no POSIX process-group kill. Do not buy a batch whose
+  // adapter descendants we cannot reliably stop; WSL uses the Linux path.
+  if (process.platform === 'win32') throw new Error('Simulation Runner is not supported on native Windows. Run it in WSL, Linux or macOS so cancellation can stop the adapter process group.');
+  if (!bridge || !path.isAbsolute(bridge.command || '') || (bridge.args !== undefined && (!Array.isArray(bridge.args) || bridge.args.length > 256 || bridge.args.some(arg => typeof arg !== 'string' || arg.length > 8192))) || (bridge.cwd !== undefined && !path.isAbsolute(bridge.cwd))) throw new Error('Bridge needs an absolute command, string arguments and optional absolute cwd.');
+  const timeoutMs = bridge.timeoutMs ?? 30000; const batchTimeoutMs = bridge.batchTimeoutMs ?? 900000;
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || !Number.isInteger(batchTimeoutMs) || batchTimeoutMs < 1 || batchTimeoutMs > 900000) throw new Error('Invalid simulation deadline.');
+  if (bridge.env !== undefined && (!bridge.env || typeof bridge.env !== 'object' || Array.isArray(bridge.env) || Object.entries(bridge.env).some(([k, v]) => !boundedString(k, 128) || typeof v !== 'string' || v.length > 8192))) throw new Error('Invalid bridge environment.');
+  return { ...bridge, timeoutMs, batchTimeoutMs };
+}
+export function childEnvironment(extra = {}, playtest = {}) {
+  // Local adapters are trusted code, not a security sandbox. Avoid accidentally
+  // forwarding account/provider credentials or inherited synthetic identities.
+  const env = {};
+  for (const [key, value] of Object.entries({ ...process.env, ...extra })) {
+    if (/TOKEN|SECRET|PASSWORD|CREDENTIAL|API.?KEY|PRIVATE.?KEY|AUTH|^AWS_|^AZURE_|^GOOGLE_|^ANTHROPIC_|^OPENAI_|^NODE_OPTIONS$|^RAVENSIGHT_.*(?:RUN|JOB)/i.test(key)) continue;
+    env[key] = value;
+  }
+  env.RAVENSIGHT_PLAYTEST_TOKEN = typeof playtest.token === 'string' && playtest.token ? playtest.token : 'invalid-simulation-preflight-token';
+  env.RAVENSIGHT_PLAYTEST_RUN_ID = String(playtest.runId || 'local-simulation');
+  env.RAVENSIGHT_PLAYTEST_JOB_ID = String(playtest.jobId || 'local-simulation');
+  return env;
+}
+export function openBridge(raw, { signal, playtest } = {}) {
+  const bridge = bridgeOptions(raw);
+  const child = spawn(bridge.command, bridge.args || [], { cwd: bridge.cwd, shell: false, detached: process.platform !== 'win32', env: childEnvironment(bridge.env, playtest), stdio: ['pipe', 'pipe', 'pipe'] });
+  let buffer = Buffer.alloc(0), id = 0, pending, failure, closing;
+  const kill = sig => { try { if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, sig); else child.kill(sig); } catch {} };
+  const fail = message => { failure ||= new Error(message); if (pending) { clearTimeout(pending.timer); pending.reject(failure); pending = null; } };
+  const stop = () => {
+    if (closing) return closing;
+    fail('Simulation bridge stopped.'); signal?.removeEventListener('abort', abort);
+    kill('SIGTERM');
+    // Always escalate against the process group, including when child.killed is
+    // true or the leader exited while a descendant still owns its pipes.
+    closing = new Promise(resolve => setTimeout(() => { kill('SIGKILL'); child.stdin.destroy(); child.stdout.destroy(); child.stderr.destroy(); resolve(); }, 100));
+    return closing;
+  };
+  const abort = () => { fail('Simulation cancelled.'); void stop(); };
+  signal?.addEventListener('abort', abort, { once: true });
+  if (signal?.aborted) abort();
+  child.stderr.resume();
+  child.on('error', () => { fail('Simulation bridge could not start.'); void stop(); });
+  child.on('exit', () => { fail('Simulation bridge exited.'); });
+  child.stdin.on('error', () => { fail('Simulation bridge input failed.'); void stop(); });
+  child.stdout.on('data', chunk => {
+    buffer = Buffer.concat([buffer, chunk]);
+    if (buffer.length > MAX_RESPONSE) { fail('Simulation response exceeds 256 KB.'); void stop(); return; }
+    let end;
+    while ((end = buffer.indexOf(10)) >= 0) {
+      const line = buffer.subarray(0, end); buffer = buffer.subarray(end + 1);
+      try {
+        const message = JSON.parse(line.toString('utf8'), (key, value) => { if (forbidden.has(key)) throw new Error(); return value; });
+        if (!pending || message.jsonrpc !== '2.0' || message.id !== pending.id || message.error || !Object.hasOwn(message, 'result')) throw new Error();
+        const result = observation(message.result); const entry = pending; pending = null; clearTimeout(entry.timer); entry.resolve(result);
+      } catch { fail('Invalid simulation protocol response.'); void stop(); return; }
+    }
+  });
+  return {
+    request(method, params) {
+      if (failure) return Promise.reject(failure);
+      if (pending) return Promise.reject(new Error('Simulation request already pending.'));
+      return new Promise((resolve, reject) => {
+        const requestId = ++id;
+        pending = { id: requestId, resolve, reject, timer: setTimeout(() => { fail('Simulation response timed out.'); void stop(); }, bridge.timeoutMs) };
+        child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: requestId, method, params }) + '\n');
+      });
+    }, stop
+  };
+}

package/src/upload/index.js

@@ -1,3 +1,4 @@
+import { recordingCompletionBody } from './recording.js';
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join, sep } from 'node:path';
 import { ApiError, isRetryable } from '../api/errors.js';
@@ -459,10 +460,11 @@ export async function finalizeRun(runDir, options) {
   const { api, gameId, jobId, runId, body = {} } = options;
   if (!runId) throw new TypeError('finalizeRun needs a runId');
 
+  const completionBody = await recordingCompletionBody(runDir, body, options.includeVideo);
   await uploadRunDir(runDir, options);
 
   try {
-    return await api.runs.complete(gameId, jobId, runId, body);
+    return await api.runs.complete(gameId, jobId, runId, completionBody);
   } catch (error) {
     if (!(error instanceof ApiError) || error.status !== 422 || error.code !== 'upload_unverified') {
       throw error;
@@ -470,6 +472,6 @@ export async function finalizeRun(runDir, options) {
     const paths = unverifiedPaths(error);
     if (paths.length === 0) throw error;
     await uploadRunDir(runDir, { ...options, only: paths, force: true });
-    return api.runs.complete(gameId, jobId, runId, body);
+    return api.runs.complete(gameId, jobId, runId, completionBody);
   }
 }

package/src/upload/recording.js

@@ -0,0 +1,56 @@
+import { open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join } from 'node:path';
+
+// Deliberately independent of the full local driver receipt. Never send paths,
+// timestamps, targets, driver errors or recording.json as an artifact.
+const STATUSES = ['complete', 'partial', 'unsupported', 'failed'];
+const STOP_REASONS = [
+  'stopped', 'completed', 'canceled', 'failed', 'game_exited', 'game_crashed',
+  'page_closed', 'duration_limit', 'size_limit', 'frame_size_limit',
+  'frame_bytes_limit', 'capture_failed', 'launch_failed', 'headless_no_viewport',
+  'run_directory_required', 'encoder_unavailable', 'no_frames',
+  'encoding_timeout', 'encoding_failed', 'video_finalization_failed',
+  'video_unavailable', 'unknown'
+];
+const MAX_METADATA_BYTES = 8192;
+const MAX_DURATION_MS = 900000;
+
+export function recordingForCompletion(metadata) {
+  if (!metadata || typeof metadata !== 'object' || !STATUSES.includes(metadata.status)) return null;
+  return {
+    status: metadata.status,
+    duration_ms: typeof metadata.durationMs === 'number' && Number.isFinite(metadata.durationMs)
+      && metadata.durationMs >= 0 && metadata.durationMs <= MAX_DURATION_MS ? metadata.durationMs : null,
+    stop_reason: STOP_REASONS.includes(metadata.reason) ? metadata.reason : 'unknown'
+  };
+}
+
+async function readRecording(runDir) {
+  let file;
+  try {
+    file = await open(join(runDir, 'recording.json'), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const info = await file.stat();
+    if (!info.isFile() || info.size > MAX_METADATA_BYTES) return null;
+    // One bounded read also protects against a file growing after stat().
+    const buffer = Buffer.alloc(MAX_METADATA_BYTES + 1);
+    const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+    if (bytesRead > MAX_METADATA_BYTES) return null;
+    return recordingForCompletion(JSON.parse(buffer.subarray(0, bytesRead).toString('utf8')));
+  } catch {
+    // Missing or malformed local status must not lose the run's existing report.
+    return null;
+  } finally {
+    await file?.close().catch(() => {});
+  }
+}
+
+export async function recordingCompletionBody(runDir, body, includeVideo) {
+  const { recording: supplied, include_video: ignored, ...result } = body;
+  if (includeVideo !== true) return result;
+  const recording = supplied ? recordingForCompletion({
+    status: supplied.status, durationMs: supplied.duration_ms, reason: supplied.stop_reason
+  }) : await readRecording(runDir);
+  if (recording) Object.assign(result, { include_video: true, recording });
+  return result;
+}