ravensight-playtest 0.4.0 → 0.5.0

package/src/run/drivers/recording.js

@@ -0,0 +1,148 @@
+// Local recording only. This module never uploads, reads credentials, or captures
+// a display/audio device. Final files use the existing opt-in upload allowlist.
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { detectFfmpeg } from '../../detect.js';
+import { MAX_VIDEO_BYTES } from '../../upload/allowlist.js';
+
+const execute = promisify(execFile);
+export const RECORDING_LIMITS = Object.freeze({
+  durationMs: 15 * 60 * 1000,
+  videoBytes: MAX_VIDEO_BYTES,
+  frameBytes: 256 * 1024 * 1024,
+  singleFrameBytes: 4 * 1024 * 1024,
+  width: 1280,
+  height: 720,
+  fps: 10,
+  finalizeMs: 60000,
+});
+
+// Test seams may lower limits, never raise production ceilings.
+export function recordingLimits(overrides = {}) {
+  const out = { ...RECORDING_LIMITS };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (!(key in out) || !Number.isSafeInteger(value) || value < 1 || value > out[key]) {
+      throw new Error(`invalid recording limit: ${key}`);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+export function recordingViewport(viewport, limits = RECORDING_LIMITS) {
+  const width = Number(viewport?.width ?? viewport?.w ?? limits.width);
+  const height = Number(viewport?.height ?? viewport?.h ?? limits.height);
+  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 1 || height < 1) {
+    throw new Error('recording viewport must have positive integer dimensions');
+  }
+  const scale = Math.min(1, limits.width / width, limits.height / height);
+  return { width: Math.max(1, Math.floor(width * scale)), height: Math.max(1, Math.floor(height * scale)) };
+}
+
+export async function recordingDirectory(runDir) {
+  await fs.mkdir(runDir, { recursive: true });
+  // Reusing an old playable recording after a failed capture is worse than
+  // reporting no recording. Do not silently replace it either.
+  for (const name of ['session.webm', 'session.mp4', 'recording.json']) {
+    if (await fs.lstat(path.join(runDir, name)).then(() => true, e => { if (e.code === 'ENOENT') return false; throw e; })) {
+      throw new Error(`recording output already exists: ${name}`);
+    }
+  }
+  const directory = await fs.mkdtemp(path.join(runDir, '.recording-'));
+  await fs.chmod(directory, 0o700);
+  return directory;
+}
+
+export function recordingMetadata({ driver, startedAt, endedAt, reason = 'stopped', ...details }) {
+  return {
+    schemaVersion: 1, driver, status: 'failed', audio: false,
+    startedAt: new Date(startedAt).toISOString(), endedAt: new Date(endedAt).toISOString(),
+    durationMs: Math.max(0, endedAt - startedAt), durationSource: 'capture-clock',
+    relativePath: null, mimeType: null, bytes: 0, reason, stopReason: reason, ...details,
+  };
+}
+
+export async function saveRecording(runDir, metadata) {
+  const pending = path.join(runDir, '.recording.json.tmp');
+  await fs.writeFile(pending, `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  await fs.rename(pending, path.join(runDir, 'recording.json'));
+  return metadata;
+}
+
+export async function videoInfo(file, { limits = RECORDING_LIMITS } = {}) {
+  const stat = await fs.lstat(file);
+  if (!stat.isFile() || stat.size < 16 || stat.size > limits.videoBytes) throw new Error('invalid_video_size');
+  const handle = await fs.open(file, 'r');
+  const head = Buffer.alloc(16);
+  try { await handle.read(head, 0, head.length, 0); } finally { await handle.close(); }
+  const webm = head.subarray(0, 4).equals(Buffer.from([0x1a, 0x45, 0xdf, 0xa3]));
+  const mp4 = head.toString('ascii', 4, 8) === 'ftyp';
+  if (!webm && !mp4) throw new Error('invalid_video_container');
+  return { bytes: stat.size, mimeType: webm ? 'video/webm' : 'video/mp4' };
+}
+
+// ffprobe is optional for Playwright, whose successful close finalizes WebM.
+// When installed, verify the actual media timeline and absence of audio. A
+// present tool rejecting the media is a failure, never a fallback success.
+export async function probeVideo(file, { limits = RECORDING_LIMITS, run = execute } = {}) {
+  const info = await videoInfo(file, { limits });
+  const binary = process.env.RAVENSIGHT_FFPROBE || (process.env.RAVENSIGHT_FFMPEG
+    ? path.join(path.dirname(process.env.RAVENSIGHT_FFMPEG), process.platform === 'win32' ? 'ffprobe.exe' : 'ffprobe') : 'ffprobe');
+  let stdout;
+  try {
+    ({ stdout } = await run(binary, ['-v', 'error', '-show_entries', 'stream=codec_type,width,height:format=duration', '-of', 'json', file],
+      { timeout: 10000, killSignal: 'SIGKILL', maxBuffer: 64 * 1024, windowsHide: true }));
+  } catch (error) {
+    if (error.code === 'ENOENT') return info;
+    throw new Error('invalid_video_media');
+  }
+  try {
+    const media = JSON.parse(stdout);
+    const video = media.streams.filter(stream => stream.codec_type === 'video');
+    const durationMs = Math.round(Number(media.format.duration) * 1000);
+    if (video.length !== 1 || media.streams.some(stream => stream.codec_type === 'audio')
+      || !Number.isSafeInteger(durationMs) || durationMs <= 0 || durationMs > limits.durationMs
+      || video[0].width > limits.width || video[0].height > limits.height) throw new Error();
+    return { ...info, durationMs, durationSource: 'media', width: video[0].width, height: video[0].height };
+  } catch { throw new Error('invalid_video_media'); }
+}
+
+/** Encode only numbered PNGs we wrote, with their actual capture timestamps. */
+export async function encodeFrames({ directory, frames, endedAt, limits = RECORDING_LIMITS, encoder, run = execute, inspect = probeVideo }) {
+  if (!frames.length) throw new Error('no_frames');
+  const detected = encoder ?? await detectFfmpeg();
+  if (!detected.path) throw new Error('encoder_unavailable');
+  const first = frames[0].at;
+  const durationMs = Math.min(limits.durationMs, Math.max(1000 / limits.fps, endedAt - first));
+  const lines = ['ffconcat version 1.0'];
+  for (let i = 0; i < frames.length; i++) {
+    const frame = frames[i];
+    if (!/^\d{6}\.png$/.test(frame.name) || !Number.isFinite(frame.at) || (i && frame.at < frames[i - 1].at)) {
+      throw new Error('invalid_frame_timeline');
+    }
+    const end = Math.min(first + durationMs, frames[i + 1]?.at ?? first + durationMs);
+    lines.push(`file '${frame.name}'`, `duration ${Math.max(0.001, (end - frame.at) / 1000).toFixed(6)}`);
+  }
+  lines.push(`file '${frames.at(-1).name}'`);
+  const list = path.join(directory, 'frames.ffconcat');
+  await fs.writeFile(list, `${lines.join('\n')}\n`, { mode: 0o600, flag: 'wx' });
+  const output = path.join(directory, 'encoded.mp4');
+  try {
+    await run(detected.path, [
+      '-nostdin', '-hide_banner', '-loglevel', 'error', '-n',
+      '-protocol_whitelist', 'file', '-f', 'concat', '-safe', '1', '-i', list,
+      '-an', '-vf', `scale=${limits.width}:${limits.height}:force_original_aspect_ratio=decrease,pad=ceil(iw/2)*2:ceil(ih/2)*2,setsar=1`,
+      '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '23', '-pix_fmt', 'yuv420p',
+      '-r', '30', '-t', (durationMs / 1000).toFixed(3), '-fs', String(limits.videoBytes - 4096),
+      '-movflags', '+faststart', output,
+    ], { cwd: directory, timeout: limits.finalizeMs, killSignal: 'SIGKILL', maxBuffer: 64 * 1024, windowsHide: true });
+    const info = await inspect(output, { limits });
+    return { file: output, durationMs, ...info, truncated: info.durationMs != null && info.durationMs + 150 < durationMs };
+  } catch (error) {
+    await fs.rm(output, { force: true });
+    // Never include process output, a game path, or inherited environment in a report.
+    throw new Error(error.killed ? 'encoding_timeout' : 'encoding_failed');
+  }
+}

package/src/run/drivers/web.js

@@ -1,4 +1,5 @@
-import { mkdir, rename, stat, readdir } from 'node:fs/promises';
+import { mkdir, rename, stat, readdir, rm, chmod } from 'node:fs/promises';
+import { recordingLimits, recordingViewport, recordingDirectory, recordingMetadata, saveRecording, probeVideo } from './recording.js';
 import path from 'node:path';
 import {
   DriverError,
@@ -1121,7 +1122,7 @@ export const CHECK_PLAYTEST_IDENTITY = Object.freeze({ token: 'check', runId: nu
  *   the one the platform implies
  * @returns {Object} a driver
  */
-export function createWebDriver({ importer, headless = true, playtest = null, platform = process.platform, modifier = null } = {}) {
+export function createWebDriver({ importer, headless = true, playtest = null, platform = process.platform, modifier = null, recording = {}, now = () => Date.now(), inspectVideo = probeVideo } = {}) {
   const editModifier = modifier === 'Meta' || modifier === 'Control' ? modifier : platformModifier(platform);
   let browser = null;
   let context = null;
@@ -1129,6 +1130,16 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
   let target = null;
   let runDirectory = null;
   let videoRequested = false;
+  const limits = recordingLimits(recording);
+  let captureDirectory = null;
+  let captureStartedAt = null;
+  let stopPromise = null;
+  let captureTimer = null;
+  let captureDeadline = null;
+  let runSignal = null;
+  let onAbort = null;
+  let inspecting = false;
+  let terminalReason = null;
   let step = 0;
   let shots = 0;
   let lastHash = null;
@@ -1344,6 +1355,77 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
     return observationHash(after);
   }
 
+  function stop({ reason = 'stopped' } = {}) {
+    if (stopPromise) return stopPromise;
+    terminalReason ??= reason;
+    stopPromise = Promise.resolve().then(finalize);
+    return stopPromise;
+  }
+
+  async function finalize() {
+    clearInterval(captureTimer);
+    clearTimeout(captureDeadline);
+    runSignal?.removeEventListener('abort', onAbort);
+    const endedAt = now();
+    let videoPath = null;
+    let promotedPath = null;
+    let finalized = true;
+    // Only the explicitly selected page's handle may become session.webm.
+    const video = videoRequested && page && typeof page.video === 'function' ? page.video() : null;
+    try { if (context) await withTimeout(context.close(), 15000); } catch { finalized = false; }
+    let metadata = null;
+    if (videoRequested && captureStartedAt != null) {
+      metadata = recordingMetadata({ driver: 'playwright_web', startedAt: captureStartedAt, endedAt,
+        reason: terminalReason, timeOrigin: 'page-creation-request' });
+      if (video) {
+        try {
+          let source;
+          if (typeof video.saveAs === 'function') {
+            source = path.join(captureDirectory, 'selected-final.webm');
+            await withTimeout(video.saveAs(source), 15000);
+          } else source = await withTimeout(video.path(), 15000);
+          // No arbitrary run-directory scan or old-file fallback on a crash.
+          if (path.dirname(path.resolve(source)) !== path.resolve(captureDirectory)) throw new Error('foreign_video_path');
+          const info = await inspectVideo(source, { limits });
+          if (info.mimeType !== 'video/webm') throw new Error('invalid_video_container');
+          const destination = path.join(runDirectory, 'session.webm');
+          await rename(source, destination);
+          promotedPath = destination;
+          await chmod(destination, 0o600);
+          videoPath = destination;
+          metadata = { ...metadata, ...info, relativePath: 'session.webm',
+            status: finalized && ['stopped', 'completed'].includes(terminalReason) ? 'complete' : 'partial' };
+        } catch (error) {
+          if (promotedPath) await rm(promotedPath, { force: true });
+          videoPath = null;
+          metadata.reason = 'video_finalization_failed';
+          metadata.failure = ['invalid_video_size', 'invalid_video_container', 'invalid_video_media', 'foreign_video_path'].includes(error.message) ? error.message : 'recorder_unavailable';
+        }
+      } else metadata.reason = 'video_unavailable';
+    }
+    try { if (browser) await withTimeout(browser.close(), 15000); } catch { /* already closed or unavailable */ }
+    if (captureDirectory) await rm(captureDirectory, { recursive: true, force: true });
+    if (metadata) await saveRecording(runDirectory, metadata);
+    page = null;
+    context = null;
+    browser = null;
+    return { videoPath, ...(metadata ? { recording: metadata } : {}) };
+  }
+
+  async function inspectCapture() {
+    if (inspecting || stopPromise || !captureDirectory) return;
+    inspecting = true;
+    try {
+      let bytes = 0;
+      for (const name of await readdir(captureDirectory)) {
+        bytes += (await stat(path.join(captureDirectory, name))).size;
+      }
+      // Leave room for WebM's final index; oversize output is never published.
+      if (bytes >= Math.max(1, limits.videoBytes - 8 * 1024 * 1024)) await stop({ reason: 'size_limit' });
+    } catch { await stop({ reason: 'capture_failed' }); }
+    finally { inspecting = false; }
+  }
+
   return {
     name: 'playwright_web',
     supportsRefs: true,
@@ -1357,20 +1439,26 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
      * @param {boolean} [opts.recordVideo]
      * @param {{width: number, height: number}} [opts.viewport]
      */
-    async launch({ target: url, runDir, recordVideo = false, viewport = DEFAULT_VIEWPORT }) {
+    async launch({ target: url, runDir, recordVideo = false, viewport = DEFAULT_VIEWPORT, signal }) {
       if (!url) throw new DriverError('playwright_web needs a target URL', { fatal: true });
+      if (signal?.aborted) throw new DriverError('run canceled before browser launch');
       target = url;
       viewportSize = viewport || DEFAULT_VIEWPORT;
       runDirectory = runDir;
       videoRequested = Boolean(recordVideo);
+      if (videoRequested) {
+        viewport = recordingViewport(viewport, limits);
+        viewportSize = viewport;
+        captureDirectory = await recordingDirectory(runDir);
+      }
 
+      try {
       const playwright = await loadPlaywright(importer);
       await mkdir(runDir, { recursive: true });
-
-      browser = await playwright.chromium.launch({ headless });
+      browser = await playwright.chromium.launch({ headless, ...(videoRequested ? { args: ['--mute-audio'] } : {}) });
       context = await browser.newContext({
         viewport,
-        ...(videoRequested ? { recordVideo: { dir: runDir, size: viewport } } : {})
+        ...(videoRequested ? { recordVideo: { dir: captureDirectory, size: viewport }, permissions: [] } : {})
       });
       // The playtest identity goes in as an init script, not as
       // `extraHTTPHeaders`: a context header rides on every request the page
@@ -1387,7 +1475,34 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
       // One token per document: set again by every new document, kept by
       // pushState and hash route changes, which do not run init scripts.
       if (typeof context.addInitScript === 'function') await context.addInitScript(markDocument);
+      if (videoRequested && typeof context.route === 'function') {
+        const origin = new URL(url).origin;
+        await context.route('**/*', route => {
+          const request = route.request();
+          if (request.isNavigationRequest() && !request.frame().parentFrame() && new URL(request.url()).origin !== origin) {
+            return route.abort('blockedbyclient');
+          }
+          return route.continue();
+        });
+      }
+      captureStartedAt = videoRequested ? now() : null;
       page = await context.newPage();
+      if (videoRequested) {
+        // Context video may briefly allocate a popup file; close it immediately
+        // and discard all non-selected files during finalization.
+        page.on('popup', popup => { void popup.close().catch(() => {}); });
+        page.on('crash', () => { void stop({ reason: 'game_crashed' }).catch(() => {}); });
+        page.on('close', () => { if (!stopPromise) void stop({ reason: 'page_closed' }).catch(() => {}); });
+        captureTimer = setInterval(() => { void inspectCapture(); }, 250);
+        captureTimer.unref?.();
+        captureDeadline = setTimeout(() => { void stop({ reason: 'duration_limit' }).catch(() => {}); }, limits.durationMs);
+        captureDeadline.unref?.();
+      }
+      runSignal = signal;
+      onAbort = () => { void stop({ reason: 'canceled' }).catch(() => {}); };
+      signal?.addEventListener('abort', onAbort, { once: true });
+      if (signal?.aborted) { await stop({ reason: 'canceled' }); throw new DriverError('run canceled during browser launch'); }
+
       page.on('console', message => {
         if (message.type() !== 'error') return;
         let location = null;
@@ -1426,6 +1541,11 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
       if (response && response.status() >= 400) {
         throw new DriverError(`${url} answered ${response.status()}`, { fatal: true });
       }
+      } catch (error) {
+        await stop({ reason: 'launch_failed' }).catch(() => {});
+        if (captureDirectory) await rm(captureDirectory, { recursive: true, force: true }).catch(() => {});
+        throw error;
+      }
     },
 
     /** @returns {Promise<import('./driver.js').Observation>} */
@@ -1598,33 +1718,8 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
       return attachNetworkFailures(consoleBuffer.splice(0, consoleBuffer.length), networkFailures);
     },
 
-    /** @returns {Promise<{videoPath: string|null}>} */
-    async stop() {
-      let videoPath = null;
-      const video = videoRequested && page && typeof page.video === 'function' ? page.video() : null;
-      try {
-        if (context) await context.close();
-      } catch {
-        // A context that is already gone is not an error worth failing the
-        // run over; the report is already written by the time we get here.
-      }
-      if (video) {
-        try {
-          videoPath = await renameVideo(await video.path(), runDirectory);
-        } catch {
-          videoPath = await findVideo(runDirectory);
-        }
-      }
-      try {
-        if (browser) await browser.close();
-      } catch {
-        // Same: a closed browser is the desired end state either way.
-      }
-      page = null;
-      context = null;
-      browser = null;
-      return { videoPath };
-    }
+    /** Idempotent: cancellation, crashes and finally share one finalization. */
+    stop
   };
 }
 
@@ -1694,37 +1789,4 @@ export function attachNetworkFailures(entries, failures) {
   });
 }
 
-/**
- * Playwright names its recording with a random id. The upload allowlist and
- * the server's 90 day lifecycle rule are written against `session.webm`, so
- * the file is renamed rather than uploaded under whatever name it got.
- *
- * @param {string} source
- * @param {string} runDir
- * @returns {Promise<string>}
- */
-async function renameVideo(source, runDir) {
-  const target = path.join(runDir, 'session.webm');
-  if (!source || path.resolve(source) === path.resolve(target)) return target;
-  await rename(source, target);
-  return target;
-}
-
-/**
- * @param {string} runDir
- * @returns {Promise<string|null>}
- */
-async function findVideo(runDir) {
-  try {
-    const entries = await readdir(runDir);
-    const webm = entries.find(entry => entry.endsWith('.webm'));
-    if (!webm) return null;
-    const source = path.join(runDir, webm);
-    await stat(source);
-    return await renameVideo(source, runDir);
-  } catch {
-    return null;
-  }
-}
-
 export default createWebDriver;

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/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;
+}