ravensight-playtest 0.4.0 → 0.5.1

package/src/commands/run.js

@@ -1,8 +1,10 @@
+import { recordingForCompletion, recordingCompletionBody } from '../upload/recording.js';
 import { randomUUID } from 'node:crypto';
 import { mkdir, readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { buildAggregate, writeAggregate } from '../run/aggregate.js';
 import { optionsFrom, unknownOptionNotes } from '../run/args.js';
+import { controllerPlan, quoteMatchesPlan, runsMatchPlan } from '../run/controllers.js';
 import { getDeps } from '../run/deps.js';
 import { createDriver } from '../run/drivers/index.js';
 import EXIT from '../run/exit.js';
@@ -94,10 +96,13 @@ async function run(flags, injected, deps, log) {
   if (setup.code !== undefined) return setup.code;
   const { context, gameId, repoRoot, apiUrl, cliVersion, api } = setup;
 
-  if (options.controller && !['standard', 'jev'].includes(options.controller)) { log('Choose --controller standard or --controller jev.'); return EXIT.ENVIRONMENT; }
+  let controllers;
+  try { controllers = controllerPlan(options); } catch (error) { log(error.message); return EXIT.ENVIRONMENT; }
+  options.controllers = controllers;
   const keyModifier = resolveKeyModifier(options.keyModifier);
   if (keyModifier.error) { log(keyModifier.error); return EXIT.ENVIRONMENT; }
   const driverName = options.driver || (context.config && context.config.driver) || 'playwright_web';
+  if (controllers?.length > 1 && !['playwright_web', 'godot_driver'].includes(driverName)) { log('Comparisons currently require a web or Godot build. Nothing was charged.'); return EXIT.ENVIRONMENT; }
   const target = resolveTarget(options, context.config, driverName);
   if (!target) {
     log('Point the run at a build: --build-url for a web build, --godot-project for Godot, or --driver-config for a native or text bridge.');
@@ -147,7 +152,7 @@ async function run(flags, injected, deps, log) {
   }
   const modules = [...RUN_MODULES];
   const pack = await deps.packs.get({ api, gameId, modules });
-  if (options.controller === 'jev' && !pack.routing?.action_controllers?.includes('jev')) { log('This server does not currently support the requested action controller. No job was registered.'); return EXIT.ENVIRONMENT; }
+  if (controllers && (!pack.routing?.controller_plans || controllers.some(controller => !pack.routing?.action_controllers?.includes(controller)))) { log('This server does not currently support the requested controller plan. No job was registered or charged.'); return EXIT.ENVIRONMENT; }
   const personaSlugs = resolvePersonas(options, context.config, pack);
   const unknownSlugs = unknownPersonas(personaSlugs, pack.personas || []);
   if (unknownSlugs.length > 0) {
@@ -161,7 +166,7 @@ async function run(flags, injected, deps, log) {
   // fetch, nothing charged. `pack.routing` is the clientRouting subset, and an
   // older cached pack without `max_personas` skips the check rather than
   // refusing on a field that does not exist yet.
-  const personaRefusal = personaCountRefusal(personaSlugs.length, pack.routing && pack.routing.max_personas);
+  const personaRefusal = personaCountRefusal(personaSlugs.length * (controllers?.length || 1), pack.routing && pack.routing.max_personas);
   if (personaRefusal) {
     log(personaRefusal);
     return EXIT.ENVIRONMENT;
@@ -192,7 +197,7 @@ async function run(flags, injected, deps, log) {
   const runLength = options.runLength === 'long' ? 'long' : 'standard';
   let estimate;
   try {
-    estimate = await api.jobs.estimate(gameId, { modules, personas: personaSlugs, runLength });
+    estimate = await api.jobs.estimate(gameId, { modules, personas: personaSlugs, runLength, ...(controllers ? { controllers, driver: driverName } : {}) });
   } catch (error) {
     if (error && error.code === 'invalid_estimate') {
       log(`The server refused to price this job: ${String(error.message || 'invalid estimate')}${runLength === 'long' ? ' This server may not price long runs yet; run without --long.' : ''} Nothing was registered or charged.`);
@@ -200,6 +205,9 @@ async function run(flags, injected, deps, log) {
     }
     throw error;
   }
+  if (!quoteMatchesPlan(estimate, controllers, personaSlugs)) { log('The server did not quote every requested controller run. Nothing was registered or charged.'); return EXIT.ENVIRONMENT; }
+  if (controllers) log(`Controllers: ${controllers.join(' + ')}. ${personas.length * controllers.length} independent playthrough(s); each run is included in the total quote.`);
+  if (controllers?.length > 1) log('Each controller gets a fresh game process or browser session. Server-side game progress and randomness may differ; comparison is evidence, not proof of identical starting state.');
   // A long run is its own unit on the server. An older server that ignores
   // run_length prices a standard run, and confirming that would buy a run
   // the CLI then plays as long.
@@ -245,6 +253,7 @@ async function run(flags, injected, deps, log) {
     registered = await api.jobs.register(gameId, {
       modules,
       personas: personaSlugs,
+      ...(controllers ? { controllers } : {}),
       driver: driverName,
       cli_version: cliVersion,
       confirm_price_cents: estimate.estimate_cents,
@@ -280,6 +289,8 @@ async function run(flags, injected, deps, log) {
       runLength,
       ...(runLength === 'long' ? { longRunFactor: options.longRunFactor } : {}),
       controller: options.controller || 'standard',
+      ...(controllers ? { controllers } : {}),
+      recordVideo: Boolean(options.recordVideo || options.uploadVideo),
       concurrency: options.concurrency ?? DEFAULT_CONCURRENCY,
       uploadVideo: Boolean(options.uploadVideo),
       uploadTranscript: Boolean(options.uploadTranscript)
@@ -291,6 +302,10 @@ async function run(flags, injected, deps, log) {
     }
   }
   await stateFile.save(repoRoot, journal);
+  if (!runsMatchPlan(registered.runs || [], controllers, personaSlugs)) {
+    log(`The registered controller plan does not match the quote. Job ${jobId} is saved for reconciliation; no playthrough or model call was started.`);
+    return EXIT.FAILED;
+  }
   log(`job ${jobId}${registered.replayed ? ' (replayed)' : ''}: ${formatCents(registered.price && registered.price.price_cents)} charged. ${directory}`);
 
   return playJob({
@@ -451,7 +466,7 @@ export async function playJob({
 
   const results = [];
   const queue = personaRuns.filter(entry => !stateFile.isRunDone(journal.runs[entry.run_id]));
-  const concurrency = WEBDRIVER_NAMES.includes(driverName) ? 1 : Math.max(1, Math.min(Number(options.concurrency) || DEFAULT_CONCURRENCY, queue.length || 1));
+  const concurrency = (options.controllers?.length > 1 || WEBDRIVER_NAMES.includes(driverName)) ? 1 : Math.max(1, Math.min(Number(options.concurrency) || DEFAULT_CONCURRENCY, queue.length || 1));
 
   /**
    * Runs the process is in the middle of. A Ctrl-C has to move these to
@@ -462,7 +477,8 @@ export async function playJob({
    * back out of, which is exactly what it is for.
    */
   const inFlight = new Map();
-  const interrupt = createInterruptHandler({ api, gameId, jobId, repoRoot, journal, inFlight, log, injected });
+  const abort = new AbortController();
+  const interrupt = createInterruptHandler({ api, gameId, jobId, repoRoot, journal, inFlight, log, injected, onInterrupt: () => abort.abort() });
 
   try {
     await Promise.all(Array.from({ length: concurrency }, async () => {
@@ -483,7 +499,7 @@ export async function playJob({
           pack,
           driverName,
           target,
-          options,
+          options: { ...options, signal: abort.signal },
           journal,
           inFlight,
           makeDriver,
@@ -633,7 +649,8 @@ export async function playPersonaRun({
   try {
     if (inFlight) inFlight.set(runId, { state: 'launching' });
     outcome = await runPersona({
-      controller: options.controller || 'standard',
+      controller: entry.controller || options.controller || 'standard',
+      signal: options.signal,
       client,
       api,
       gameId,
@@ -654,7 +671,7 @@ export async function playPersonaRun({
       maxActions,
       heartbeat,
       ledger,
-      recordVideo: Boolean(options.uploadVideo),
+      recordVideo: Boolean(options.recordVideo || options.uploadVideo),
       // Written the moment the warning arrives, not after the run: a run that
       // then fails still says in state.json that it was warned.
       onBudgetWarning: async () => {
@@ -668,6 +685,10 @@ export async function playPersonaRun({
     });
   } catch (error) {
     heartbeat.stop();
+    if (options.signal?.aborted) {
+      await stateFile.patchRun(repoRoot, journal, runId, { state: 'interrupted', completed: false, actions_taken: error.outcome?.actionsTaken || 0 });
+      return { runId, persona: persona.slug, state: 'interrupted', error };
+    }
     if (inFlight) inFlight.delete(runId);
     const failed = error.outcome || { state: 'failed', quitReason: 'error', actionsTaken: 0, report: null, reportLint: [], reachedState: 'playing' };
     await stateFile.patchRun(repoRoot, journal, runId, {
@@ -726,6 +747,10 @@ export async function playPersonaRun({
     return { runId, persona: persona.slug, state: failed.state, quitReason: failed.quitReason, error };
   }
   heartbeat.stop();
+  if (options.signal?.aborted) {
+    await stateFile.patchRun(repoRoot, journal, runId, { state: 'interrupted', completed: false, actions_taken: outcome.actionsTaken, report_written: Boolean(outcome.report) });
+    return { runId, persona: persona.slug, state: 'interrupted' };
+  }
   if (inFlight) inFlight.delete(runId);
 
   await stateFile.patchRun(repoRoot, journal, runId, {
@@ -804,6 +829,9 @@ export async function deliver({ deps, api, gameId, jobId, runId, directory, outc
   // The run card's duration. The server lane accepts `duration`; an older
   // server ignores a key it does not know.
   if (outcome.duration) body.duration = durationBody(outcome.duration);
+  // Keep the same bounded opt-in status in the older-server partial-report fallback.
+  const recording = options.uploadVideo === true ? recordingForCompletion(outcome.recording) : null;
+  Object.assign(body, await recordingCompletionBody(directory, recording ? { recording } : {}, options.uploadVideo === true));
   if (outcome.report) body.report = outcome.report;
   // `report_md` is what the server lints for its four required sections. Not
   // sending it means `report_lint` is silently empty on every run, which reads
@@ -842,11 +870,11 @@ export async function deliver({ deps, api, gameId, jobId, runId, directory, outc
         body
       });
     } catch (error) {
-      // A server older than partial reports refuses one as `invalid_report`.
-      // The uploads are already done by then, so the run is completed
-      // without it rather than left open: the notes stay on disk in
-      // report.json either way.
-      if (!(body.report && body.report.partial && error && error.status === 422 && error.code === 'invalid_report')) throw error;
+      // A server older than partial reports refuses one as `invalid_report`,
+      // and any server refuses one with a secret shaped value in it. The
+      // uploads are already done by then, so the run is completed without it
+      // rather than left open: the notes stay on disk in report.json either way.
+      if (!(body.report && body.report.partial && error && error.status === 422 && ['invalid_report', 'secrets_detected'].includes(error.code))) throw error;
       log(`run ${runId}: the server refused the partial report (${String(error.message)}), so the run is completed without it. The notes are in ${directory}.`);
       if (delivery) delivery.reportRefused = true;
       const { report: ignored, report_md: alsoIgnored, ...withoutReport } = body;
@@ -1009,7 +1037,10 @@ async function aggregatePhase({
 
   // The aggregate reads reports off disk, so a resumed job whose earlier runs
   // were played by a previous process is covered too.
-  const reports = await loadRunReports(repoRoot, jobId, personaRuns, journal);
+  // A failed run's report explains the failure and its unit is refunded. It is
+  // not a result to summarise, and the server refuses a summary of only those.
+  const reports = (await loadRunReports(repoRoot, jobId, personaRuns, journal))
+    .map(run => (run.state === 'failed' ? { ...run, report: null } : run));
   let aggregate;
   try {
     aggregate = await buildAggregate({
@@ -1135,7 +1166,7 @@ async function publishAggregate({ deps, api, gameId, jobId, repoRoot, directory,
  *
  * @returns {{signalled: boolean, settle: () => Promise<void>, release: () => void}}
  */
-export function createInterruptHandler({ api, gameId, jobId, repoRoot, journal, inFlight, log, message = null, injected = {} }) {
+export function createInterruptHandler({ api, gameId, jobId, repoRoot, journal, inFlight, log, message = null, injected = {}, onInterrupt = () => {} }) {
   const signals = injected.signals || ['SIGINT', 'SIGTERM'];
   const target = injected.process || process;
   const state = { signalled: false, signal: null };
@@ -1144,6 +1175,7 @@ export function createInterruptHandler({ api, gameId, jobId, repoRoot, journal,
     if (state.signalled) return;
     state.signalled = true;
     state.signal = signal;
+    onInterrupt(signal);
     log(`\n${signal}: ${message || `finishing the turn in flight, then stopping. Nothing is lost; "ravensight-playtest resume ${jobId}" carries on.`}`);
     // Hand the signal back to the default behaviour, so a second press kills
     // the process rather than being swallowed by a handler that is now done.
@@ -1285,15 +1317,15 @@ export async function loadRunReports(repoRoot, jobId, personaRuns, journal = nul
     // summary must not count findings the dashboard does not have.
     const recorded = journal && journal.runs ? journal.runs[entry.run_id] : null;
     if (recorded && recorded.report_refused === true) {
-      out.push({ runId: entry.run_id, persona: entry.persona, state: 'failed', report: null, reportRefused: true });
+      out.push({ runId: entry.run_id, persona: entry.persona, ...(entry.controller ? { controller: entry.controller } : {}), state: 'failed', report: null, reportRefused: true });
       continue;
     }
     const file = path.join(runDirFor(repoRoot, jobId, entry.run_id), RUN_FILES.reportJson);
     try {
       const report = JSON.parse(await readFile(file, 'utf8'));
-      out.push({ runId: entry.run_id, persona: entry.persona, state: report && report.partial === true ? 'budget_exceeded' : 'succeeded', report });
+      out.push({ runId: entry.run_id, persona: entry.persona, ...(entry.controller ? { controller: entry.controller } : {}), state: recorded?.state || entry.state || (report && report.partial === true ? 'budget_exceeded' : 'succeeded'), report });
     } catch {
-      out.push({ runId: entry.run_id, persona: entry.persona, state: 'failed', report: null });
+      out.push({ runId: entry.run_id, persona: entry.persona, ...(entry.controller ? { controller: entry.controller } : {}), state: 'failed', report: null });
     }
   }
   return out;

package/src/run/actionSelector.js

@@ -1,5 +1,5 @@
 import { ProxyError, STEPS } from './model.js';
-export const CONTROLLERS = ['standard', 'jev'];
+export { CONTROLLERS } from './controllers.js';
 export const JEV_CONTROLLER_PROMPT = '\nRavensight Playtester action-selection mode: describe the currently visible screen briefly in text, including each proposed target and its screenshot coordinates, then propose one to three ALTERNATIVE next actions as tool calls. Only one will be executed after a separate selector chooses. These are alternatives, never a sequential plan. Use only observed controls. For a canvas game without accessible DOM controls, include a target label describing the visible control AND screenshot x/y coordinates; the driver uses those coordinates. Never invent selectors such as textbox or button names. When the brief identifies a field as a public player label, use Ravensight Playtester. Credentials or private access codes require human review. When the game is loading or transitioning, propose a bounded wait tool call. Do not place secrets in proposals. After their tool results, observe the resulting state before proposing again.';
 export function describeAction(tool) {
   const input = tool.input || {};
@@ -14,7 +14,7 @@ export function describeAction(tool) {
   };
   return String(descriptions[tool.name] || `${tool.name}: ${JSON.stringify(input)}`).slice(0, 300);
 }
-export async function selectAction({ api, jobId, runId, persona, observation, toolUses, recentActions = [], intentNotes = [] }) {
+export async function selectAction({ api, jobId, runId, persona, observation, toolUses, controller = 'jev', recentActions = [], intentNotes = [] }) {
   const proposals = toolUses.slice(0, 8);
   // Observation does not input anything into the game. Keep it in the existing
   // bounded driver loop; Jev selects game inputs, not whether a frame may load.
@@ -22,6 +22,7 @@ export async function selectAction({ api, jobId, runId, persona, observation, to
     return { status: 'selected', toolId: proposals[0].id, source: 'observation' };
   }
   const body = {
+    controller,
     objective: ('Play the game according to the supplied persona, exploring visible controls and gathering evidence. Developer scope: ' + intentNotes.map(note => note.text || '').join(' ')).slice(0, 1000),
     // The observer already applies the full persona. The selector needs its identity,
     // current visible state and proposed inputs, not a second personality prompt.

package/src/run/aggregate.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { compareControllers, comparisonMarkdown } from './comparison.js';
 import { fillPlaceholders } from './placeholders.js';
 import { writeFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -458,7 +459,9 @@ export async function buildAggregate({
     usage: ledger ? aggregateUsage(ledger) : { usd: 0, by_model: {} }
   };
 
-  return { json, markdown: renderAggregateMarkdown(json) };
+  const comparison = compareControllers(runs);
+  if (comparison) json.controller_comparison = comparison;
+  return { json, markdown: renderAggregateMarkdown(json) + comparisonMarkdown(comparison) };
 }
 
 /**

package/src/run/args.js

@@ -16,6 +16,7 @@ const VALUED = new Map([
   ['--driver', 'driver'],
   ['--driver-config', 'driverConfig'],
   ['--controller', 'controller'],
+  ['--compare-with', 'compareWith'],
   ['--build-url', 'buildUrl'],
   ['--build-dir', 'buildDir'],
   ['--godot-project', 'godotProject'],
@@ -29,6 +30,7 @@ const VALUED = new Map([
 /** Options that are just present or absent. */
 const BOOLEAN = new Map([
   ['--upload-video', 'uploadVideo'],
+  ['--record-video', 'recordVideo'],
   ['--upload-transcript', 'uploadTranscript'],
   ['--dry-upload', 'dryUpload'],
   ['--offline-upload', 'offlineUpload'],

package/src/run/comparison.js

@@ -0,0 +1,32 @@
+// Deterministic comparison of the reports already paid for. No new model call.
+export function compareControllers(runs) {
+  const planned = runs.filter(run => run.controller);
+  const controllers = [...new Set(planned.map(run => run.controller))];
+  if (controllers.length < 2) return null;
+  const rows = planned.map(run => ({
+    run_id: run.runId, persona: run.persona, controller: run.controller,
+    state: run.state, report_available: Boolean(run.report),
+    partial: !run.report || run.report.partial === true || run.state !== 'succeeded',
+    actions_taken: run.report?.actions_taken ?? null,
+  }));
+  const groups = new Map();
+  for (const run of planned) for (const finding of run.report?.findings || []) {
+    if (finding.dropped || !Array.isArray(finding.evidence) || !finding.evidence.length) continue;
+    const key = JSON.stringify([run.persona, finding.category || '', String(finding.title || '').trim().toLowerCase().replace(/\s+/g, ' ')]);
+    if (!groups.has(key)) groups.set(key, { title: finding.title, persona: run.persona, category: finding.category, occurrences: [] });
+    groups.get(key).occurrences.push({ run_id: run.runId, controller: run.controller, evidence: finding.evidence });
+  }
+  const findings = [...groups.values()].map(group => ({ ...group,
+    match: new Set(group.occurrences.map(row => row.controller)).size > 1 ? 'reported_by_multiple_controllers' : 'reported_by_one_controller' }));
+  return { schema_version: '1.0', controllers, status: rows.some(row => row.partial) ? 'inconclusive' : 'reports_complete',
+    limits: ['Controllers use separate game sessions. Server saves and random state are not proven identical.', 'Matches use the same persona, category and exact normalized title. Agreement does not verify a bug; absence does not prove a pass.'], runs: rows, findings };
+}
+export function comparisonMarkdown(comparison) {
+  if (!comparison) return '';
+  const safe = value => String(value ?? '').replace(/[\r\n|]/g, ' ');
+  return '\n\n## Controller comparison\n\n' + comparison.limits.join(' ') + '\n\n' +
+    (comparison.status === 'inconclusive' ? 'At least one playthrough is missing or partial. This comparison is inconclusive.\n\n' : '') +
+    '| Controller | Persona | Run | Report |\n| --- | --- | --- | --- |\n' +
+    comparison.runs.map(row => `| ${safe(row.controller)} | ${safe(row.persona)} | ${safe(row.run_id)} | ${row.partial ? 'Incomplete' : 'Complete'} |`).join('\n') +
+    '\n\n' + comparison.findings.map(group => `- ${safe(group.title)}: ${[...new Set(group.occurrences.map(row => row.controller))].join(', ')} (${group.occurrences.map(row => safe(row.run_id)).join(', ')}).`).join('\n');
+}

package/src/run/controllers.js

@@ -0,0 +1,17 @@
+export const CONTROLLERS = ['standard', 'jev', 'rune'];
+export function controllerPlan(options = {}) {
+  if (options.compareWith && options.controller) throw new Error('Use --controller for one playthrough or --compare-with for a comparison.');
+  if (!options.compareWith && !options.controller) return null;
+  const plan = options.compareWith ? ['standard', ...String(options.compareWith).split(',')] : [options.controller];
+  if (plan.length > 3 || plan.some(x => !CONTROLLERS.includes(x)) || new Set(plan).size !== plan.length) throw new Error('Choose standard, jev or rune once each. --compare-with jev runs standard and Jev separately.');
+  return plan;
+}
+export function quoteMatchesPlan(quote, plan, personas) {
+  return !plan || (Array.isArray(quote.controllers) && JSON.stringify(quote.controllers) === JSON.stringify(plan) && quote.persona_run_count === plan.length * personas.length);
+}
+export function runsMatchPlan(runs, plan, personas) {
+  if (!plan) return true;
+  const actual = runs.filter(run => run.module === 'persona_playtest').map(run => `${run.persona}/${run.controller}`).sort();
+  const expected = personas.flatMap(persona => plan.map(controller => `${persona}/${controller}`)).sort();
+  return JSON.stringify(actual) === JSON.stringify(expected);
+}

package/src/run/drivers/driver.js

@@ -18,7 +18,7 @@ import { createHash } from 'node:crypto';
  * observe()                -> Observation
  * act(action)              -> ActResult
  * screenshot(name, opts)   -> { path, relativePath }
- * stop()                   -> { videoPath?: string|null, framesDir?: string }
+ * stop({ reason })         -> { videoPath?: string|null, recording?: Object }
  * ```
  *
  * Optional, used when present:
@@ -37,10 +37,10 @@ import { createHash } from 'node:crypto';
  *   description in ../tools.js says so, because the model is the one
  *   choosing.
  * - **`stop()` may return no video.** `playwright_web` hands back a
- *   `session.webm` from Playwright's own recorder. `godot_driver` returns
- *   `videoPath: null` and leaves a `frames/` sequence, which the CLI
- *   stitches only when ffmpeg is present. That is what keeps ffmpeg
- *   optional, and it means "no video" is a normal outcome, not a failure.
+ *   `session.webm` from Playwright's own recorder. `godot_driver` encodes
+ *   timestamped viewport frames to `session.mp4` with optional local ffmpeg.
+ *   `recording.status` distinguishes complete, partial, unsupported and failed
+ *   capture; absence of an encoder or rendered viewport never masquerades as video.
  *
  * `Observation.scene`, `.scenes` and `.scripts` are how a finding from a
  * running Godot game can cite a `res://` path; the web driver leaves them

package/src/run/drivers/godot.js

@@ -9,8 +9,8 @@
 //
 // Both of the differences ./driver.js names fall on this driver's side: a
 // string `click` target is a scene tree node path, not an accessibility ref,
-// and `stop()` answers `videoPath: null` with a `frames/` sequence beside it,
-// because stitching is ffmpeg's job and ffmpeg stays optional.
+// and recording uses the selected viewport, with optional local ffmpeg encoding.
+// Without an encoder or a rendered viewport it reports unsupported, never a video.
 //
 // What happens at launch, in order:
 //   1. find the developer's own Godot binary (spec 17 detection order),
@@ -34,6 +34,8 @@ import {
   prepareProjectCopy,
 } from './godot-project.js';
 import { DriverRpcError, GodotRpcClient } from './godot-rpc.js';
+import { detectFfmpeg } from '../../detect.js';
+import { recordingLimits, recordingViewport, recordingDirectory, recordingMetadata, saveRecording, encodeFrames } from './recording.js';
 
 export const DRIVER_NAME = 'godot_driver';
 export const BOOT_TIMEOUT_MS = 60000;
@@ -124,6 +126,9 @@ export class GodotDriver {
     prepare = prepareProjectCopy,
     choosePort = findFreePort,
     now = () => Date.now(),
+    recording = {},
+    detectEncoder = detectFfmpeg,
+    encode = encodeFrames,
   } = {}) {
     this.name = DRIVER_NAME;
     this.projectDir = projectDir;
@@ -148,6 +153,11 @@ export class GodotDriver {
     this._prepare = prepare;
     this._choosePort = choosePort;
     this._now = now;
+    this._recordingLimits = recordingLimits(recording);
+    this._detectEncoder = detectEncoder;
+    this._encode = encode;
+    this._frames = [];
+    this._frameBytes = 0;
 
     this.rpc = null;
     this.child = null;
@@ -178,8 +188,13 @@ export class GodotDriver {
     return !this._stopped && this.exitCode !== null && this.exitCode !== 0;
   }
 
-  async launch({ recordVideo = false, viewport } = {}) {
+  async launch({ recordVideo = false, viewport, signal } = {}) {
+    if (signal?.aborted) throw new Error('run canceled before game launch');
     if (viewport) this.viewport = viewport;
+    if (recordVideo) {
+      const size = recordingViewport(this.viewport, this._recordingLimits);
+      this.viewport = { w: size.width, h: size.height };
+    }
     if (!this.projectDir) throw new Error('godot driver needs a projectDir');
     this.godot = this.godotPath
       ? await this._detect({ explicitPath: this.godotPath, env: this.env, projectDir: this.projectDir })
@@ -198,6 +213,7 @@ export class GodotDriver {
       this.logPath = this.runDir ? path.join(this.runDir, 'godot.log') : null;
 
       const args = ['--path', this.projectCopy];
+      if (recordVideo) args.push('--audio-driver', 'Dummy');
       if (this.headless) args.push('--headless');
       else args.push('--resolution', `${this.viewport.w}x${this.viewport.h}`);
       args.push('--', '--ravensight-driver', `--ravensight-driver-port=${this.port}`);
@@ -226,6 +242,10 @@ export class GodotDriver {
       }
 
       if (recordVideo) await this._startFrameCapture();
+      this._signal = signal;
+      this._onAbort = () => { void this.stop({ reason: 'canceled' }).catch(() => {}); };
+      signal?.addEventListener('abort', this._onAbort, { once: true });
+      if (signal?.aborted) { await this.stop({ reason: 'canceled' }); throw new Error('run canceled during game launch'); }
       return {};
     } catch (error) {
       // Everything past this point has already spawned a game and copied a
@@ -289,6 +309,10 @@ export class GodotDriver {
       this.exitCode = code;
       this.exitSignal = signal;
       if (log) log.end();
+      if (!this._stopped && this._recordingStartedAt != null) {
+        this._endCapture(code === 0 ? 'game_exited' : 'game_crashed');
+        void this._finalizeRecording().catch(() => {});
+      }
     });
     this.child.on('error', (error) => {
       this._consoleQueue.push({ kind: 'driver', text: `failed to launch Godot: ${error.message}` });
@@ -501,43 +525,114 @@ export class GodotDriver {
     this.chapters.push({ title, at: this._startedAt === null ? 0 : this._now() - this._startedAt });
   }
 
-  /**
-   * Video on a local Godot run is a sequence of stills, not a container: the
-   * frames land in the run dir and whoever wants a webm stitches them with
-   * ffmpeg, which stays optional for the CLI.
-   */
-  async _startFrameCapture({ fps = 4 } = {}) {
-    if (this.headless || !this.runDir) return;
-    this._framesDir = path.join(this.runDir, 'frames');
-    await fs.mkdir(this._framesDir, { recursive: true });
-    this._videoTimer = setInterval(() => {
-      void this._captureFrame();
-    }, Math.round(1000 / fps));
-    if (typeof this._videoTimer.unref === 'function') this._videoTimer.unref();
+  // Capture only this project's viewport. No screen/audio device is opened.
+  async _startFrameCapture() {
+    this._recordingStartedAt = this._now();
+    if (this.runDir) this._framesDir = await recordingDirectory(this.runDir);
+    if (this.headless || !this.runDir) {
+      this._recordingUnsupported = this.headless ? 'headless_no_viewport' : 'run_directory_required';
+      return;
+    }
+    this._encoder = await this._detectEncoder();
+    if (!this._encoder?.path) {
+      this._recordingUnsupported = 'encoder_unavailable';
+      this._consoleQueue.push({ kind: 'driver', text: 'Video unavailable: install optional ffmpeg or set RAVENSIGHT_FFMPEG. No video was recorded.' });
+      return;
+    }
+    this._recordingStartedAt = this._now();
+    await this._captureFrame();
+    if (this._captureEndedAt != null) return;
+    this._videoTimer = setInterval(() => { void this._captureFrame(); }, Math.round(1000 / this._recordingLimits.fps));
+    this._videoTimer.unref?.();
+    this._videoDeadline = setTimeout(() => this._endCapture('duration_limit'), this._recordingLimits.durationMs);
+    this._videoDeadline.unref?.();
+  }
+
+  _endCapture(reason) {
+    if (this._captureEndedAt != null) return;
+    this._captureEndedAt = Math.min(this._now(), this._recordingStartedAt + this._recordingLimits.durationMs);
+    this._captureReason = reason;
+    clearInterval(this._videoTimer);
+    clearTimeout(this._videoDeadline);
+    this._videoTimer = null;
   }
 
   async _captureFrame() {
-    if (this._capturing || this._stopped) return;
-    this._capturing = true;
-    try {
-      const shot = await this._rawScreenshot();
-      if (!shot) return;
-      this._frameIndex += 1;
-      const file = path.join(this._framesDir, `${String(this._frameIndex).padStart(6, '0')}.png`);
-      await fs.writeFile(file, Buffer.from(shot.data, 'base64'));
-    } catch {
-      // A dropped frame is never worth interrupting a run for.
-    } finally {
-      this._capturing = false;
+    if (this._capturePromise || this._stopped || this._captureEndedAt != null) return;
+    if (this._now() - this._recordingStartedAt >= this._recordingLimits.durationMs) {
+      this._endCapture('duration_limit'); return;
     }
+    const at = this._now();
+    this._capturePromise = (async () => {
+      try {
+        const shot = await this._rawScreenshot();
+        if (!shot) return;
+        const max = this._recordingLimits.singleFrameBytes;
+        if (typeof shot.data !== 'string' || shot.data.length > Math.ceil(max / 3) * 4) {
+          this._endCapture('frame_size_limit'); return;
+        }
+        const bytes = Buffer.from(shot.data, 'base64');
+        if (bytes.length > max || this._frameBytes + bytes.length > this._recordingLimits.frameBytes) {
+          this._endCapture('frame_bytes_limit'); return;
+        }
+        const name = `${String(this._frameIndex + 1).padStart(6, '0')}.png`;
+        await fs.writeFile(path.join(this._framesDir, name), bytes, { flag: 'wx', mode: 0o600 });
+        this._frames.push({ name, at });
+        this._frameIndex += 1;
+        this._frameBytes += bytes.length;
+      } catch {
+        // A disconnected/crashed game can still leave a useful partial recording.
+        this._endCapture('capture_failed');
+      }
+    })();
+    try { await this._capturePromise; } finally { this._capturePromise = null; }
   }
 
-  async stop({ removeTemp = !this.keepTemp } = {}) {
+  _finalizeRecording() {
+    if (this._finalizePromise) return this._finalizePromise;
+    this._finalizePromise = (async () => {
+      if (this._recordingStartedAt == null) return {};
+      await this._capturePromise;
+      const endedAt = this._captureEndedAt ?? this._now();
+      let metadata = recordingMetadata({ driver: this.name, startedAt: this._recordingStartedAt, endedAt,
+        reason: this._recordingUnsupported ?? this._captureReason ?? 'stopped',
+        status: this._recordingUnsupported ? 'unsupported' : 'failed', frameCount: this._frameIndex,
+        captureFpsLimit: this._recordingLimits.fps, timeOrigin: 'first-viewport-frame',
+      });
+      let videoPath = null;
+      if (!this._recordingUnsupported && this._framesDir) {
+        try {
+          const encoded = await this._encode({ directory: this._framesDir, frames: this._frames, endedAt,
+            encoder: this._encoder, limits: this._recordingLimits });
+          videoPath = path.join(this.runDir, 'session.mp4');
+          await fs.rename(encoded.file, videoPath);
+          metadata = { ...metadata, status: ['stopped', 'completed', 'game_exited'].includes(metadata.reason) ? 'complete' : 'partial',
+            relativePath: 'session.mp4', mimeType: encoded.mimeType, bytes: encoded.bytes,
+            durationMs: encoded.durationMs, durationSource: encoded.durationSource ?? 'frame-timestamps',
+            firstFrameOffsetMs: this._frames[0].at - this._recordingStartedAt };
+          if (encoded.truncated) { metadata.status = 'partial'; metadata.reason = 'size_limit'; }
+        } catch (error) {
+          metadata.reason = ['no_frames', 'encoder_unavailable', 'encoding_timeout', 'encoding_failed'].includes(error.message) ? error.message : 'encoding_failed';
+        }
+      }
+      // Captured game frames are local temporary data, never upload artifacts.
+      if (this._framesDir) await fs.rm(this._framesDir, { recursive: true, force: true });
+      if (this.runDir) await saveRecording(this.runDir, metadata);
+      return { videoPath, recording: metadata };
+    })();
+    return this._finalizePromise;
+  }
+
+  stop(options = {}) {
+    if (!this._stopPromise) this._stopPromise = Promise.resolve().then(() => this._stop(options));
+    return this._stopPromise;
+  }
+
+  async _stop({ removeTemp = !this.keepTemp, reason = 'stopped' } = {}) {
     this._stopped = true;
-    if (this._videoTimer) {
-      clearInterval(this._videoTimer);
-      this._videoTimer = null;
-    }
+    this._signal?.removeEventListener('abort', this._onAbort);
+    if (this._recordingStartedAt != null) this._endCapture(reason);
+    await this._capturePromise;
     if (this.rpc && !this.rpc.closed) {
       await this.rpc.call('quit', { code: 0 }, { timeoutMs: 2000 }).catch(() => {});
     }
@@ -549,12 +644,9 @@ export class GodotDriver {
       this.projectCopy = null;
     }
     return {
-      videoPath: null,
-      framesDir: this._framesDir,
-      frameCount: this._frameIndex,
-      chapters: this.chapters,
-      logPath: this.logPath,
-      exitCode: this.exitCode,
+      videoPath: null, ...await this._finalizeRecording(),
+      frameCount: this._frameIndex, chapters: this.chapters,
+      logPath: this.logPath, exitCode: this.exitCode,
     };
   }