ravensight-playtest 0.5.2 → 0.7.0

package/src/run/drivers/godot.js

@@ -21,6 +21,7 @@
 //      game's own Ravensight SDK tags every event it tracks as synthetic,
 //   4. dial 127.0.0.1, say hello{token}, and poll ping until the game answers.
 import { spawn } from 'node:child_process';
+import { track } from '../liveWork.js';
 import { randomBytes } from 'node:crypto';
 import { createWriteStream } from 'node:fs';
 import fs from 'node:fs/promises';
@@ -29,18 +30,103 @@ import path from 'node:path';
 import { buildObservation, needsVision } from './godot-observation.js';
 import {
   detectGodotBinary,
-  findFreePort,
+  reservePort,
+  importProjectCopy,
   packagedAddonDir,
   prepareProjectCopy,
+  projectNeedsImport,
+  setIniEntry,
 } from './godot-project.js';
+import { screenshotName } from './driver.js';
 import { DriverRpcError, GodotRpcClient } from './godot-rpc.js';
 import { detectFfmpeg } from '../../detect.js';
 import { recordingLimits, recordingViewport, recordingDirectory, recordingMetadata, saveRecording, encodeFrames } from './recording.js';
+import { createTraceWriter, seedFrom, TRACE_FILE } from '../trace.js';
 
 export const DRIVER_NAME = 'godot_driver';
 export const BOOT_TIMEOUT_MS = 60000;
 export const BOOT_POLL_MS = 250;
-const FRAMES_PER_SECOND = 60;
+
+/**
+ * The longest one key action may hold its keys, in milliseconds. The addon's
+ * own ceiling for a held input action is 10 s; a persona turn holding the
+ * game for longer than this is not playing it, it is waiting.
+ */
+export const MAX_HOLD_MS = 5000;
+
+/** The longest wait action, matching the browser driver's. */
+export const MAX_WAIT_MS = 10000;
+
+/** The most keys one action may hold down together (a diagonal is two). */
+export const MAX_HELD_KEYS = 3;
+
+/** In the path of every user:// a lockstep run creates, so stop removes only those. */
+const USER_DIR_MARKER = 'ravensight-lockstep';
+
+/** The longest one lockstep step may run, matching the addon's own ceiling. */
+export const MAX_STEP_TICKS = 3600;
+
+/** How much longer a step's answer may take per tick, on top of the call timeout. */
+const STEP_MS_PER_TICK = 34;
+
+/** Frames the game is given after ping before its boot is judged. */
+export const BOOT_SETTLE_FRAMES = 10;
+
+/** The error code, and the run's stateReason prefix, for a game that never booted. */
+export const BOOT_FAILED = 'game_boot_failed';
+
+/**
+ * Lines in Godot's own output that mean the game's scripts or main scene did
+ * not load. Seen before the first observation, the persona would be playing a
+ * black screen, so the launch fails instead.
+ */
+const BOOT_FATAL_LINE = [
+  /Parse Error:/i,
+  /Failed to load script ".*" with error/i,
+  /Failed loading resource: res:\/\/.*\.(?:tscn|scn)/i,
+  /(?:Can't|Couldn't|Failed to) (?:load|open) (?:the )?main scene/i,
+];
+
+/** The tick rate Godot assumes when a project does not state its own. */
+export const DEFAULT_TICKS_PER_SECOND = 60;
+
+/**
+ * The tick rate a lockstep run uses: the power of two nearest the project's own.
+ *
+ * Not the project's own rate, and this is measured rather than tidy. Godot decides
+ * how many physics steps a frame gets by adding 1/fps to a float and flooring it
+ * times the tick rate. At 60 that float is inexact, so now and then a frame gets
+ * none and the next gets two, at a moment that depends on how many frames passed
+ * while parked, which is the wall clock's choice: a hold came out a tick long or
+ * short, at random, in about half of windowed replays. 1/64 is exact, so every
+ * frame is one tick. The game runs a few percent off its usual physics rate; its
+ * delta says so, and `game_seconds` is still real game time.
+ *
+ * @param {string} projectDir
+ * @returns {Promise<number>}
+ */
+export async function projectTicksPerSecond(projectDir) {
+  const text = await fs.readFile(path.join(projectDir, 'project.godot'), 'utf8').catch(() => '');
+  const match = text.match(/^\s*common\/physics_ticks_per_second\s*=\s*(\d+)/m);
+  const declared = match ? Number(match[1]) : DEFAULT_TICKS_PER_SECOND;
+  const ticks = declared >= 1 && declared <= 1000 ? declared : DEFAULT_TICKS_PER_SECOND;
+  return 2 ** Math.round(Math.log2(ticks));
+}
+
+/**
+ * How long, on the wall clock, a hold of `holdMs` of game time takes at the
+ * game's time scale. Counted on the clock rather than in frames: live on a
+ * 120 Hz display, 120 frames was one game second, so a hold counted at 60
+ * frames a second came out half as long as asked.
+ *
+ * @param {number} holdMs
+ * @param {number} scale the game's time scale while the hold runs
+ * @returns {number}
+ */
+export function holdWallMs(holdMs, scale = 1) {
+  const ms = Math.min(Math.max(Number(holdMs) || 0, 0), MAX_HOLD_MS);
+  return Number(scale) > 0 ? Math.round(ms / Number(scale)) : ms;
+}
 
 /**
  * The only environment variables forwarded to Godot.
@@ -102,6 +188,29 @@ export const ENV_ALLOWLIST = [
 const ERROR_LINE = /^(?:USER )?(?:SCRIPT )?ERROR:|^SCRIPT ERROR/;
 const SOURCE_LINE = /^\s+at:\s*(.+)$/;
 
+/**
+ * The events as a replay should send them. A click named by node path goes in the
+ * trace as where it landed: a generated name such as @CanvasLayer@10 carries a
+ * process-wide counter, so the same path can be gone on the next run, or on a commit
+ * that only added a node somewhere else. A button that really moved misses, and the
+ * state says so.
+ *
+ * @param {Array<Object>} events
+ * @param {Array<Array<number>>} [clicks] - where the driver says each click landed
+ * @returns {Array<Object>}
+ */
+export function traceableEvents(events, clicks = []) {
+  let index = 0;
+  return events.map((event) => {
+    if (event.type !== 'click') return event;
+    const at = clicks[index];
+    index += 1;
+    if (!at) return event;
+    const { node_path: ignored, ...rest } = event;
+    return { ...rest, x: at[0], y: at[1] };
+  });
+}
+
 export class GodotDriver {
   constructor({
     projectDir,
@@ -119,18 +228,35 @@ export class GodotDriver {
     treeDepth = 6,
     settleFrames = 2,
     keepTemp = false,
+    // The game's clock is frozen between actions (time_scale 0) and runs only
+    // while an action executes, so a persona is never punished for thinking.
+    // Off for a game that has to keep running in real time.
+    pauseBetweenActions = true,
+    // Deterministic play: a stopped clock from before the first scene, a seed,
+    // fixed ticks, and every input recorded to trace.jsonl. Run paths turn it on
+    // (drivers: `driverOptions`); it needs the clock parked between actions.
+    lockstep = false,
+    seed,
+    recordTrace = true,
+    traceHeader = {},
+    importTimeoutMs = 180000,
+    needsImport = projectNeedsImport,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    importProject = importProjectCopy,
     env = process.env,
     extraEnv = {},
     spawnFn = spawn,
     detect = detectGodotBinary,
     prepare = prepareProjectCopy,
-    choosePort = findFreePort,
+    choosePort = reservePort,
     now = () => Date.now(),
     recording = {},
     detectEncoder = detectFfmpeg,
     encode = encodeFrames,
   } = {}) {
     this.name = DRIVER_NAME;
+    // The key action holds its keys for hold_ms (and with_keys together).
+    this.supportsHold = true;
     this.projectDir = projectDir;
     this.runDir = runDir;
     this.godotPath = godotPath;
@@ -146,6 +272,26 @@ export class GodotDriver {
     this.treeDepth = treeDepth;
     this.settleFrames = settleFrames;
     this.keepTemp = keepTemp;
+    this.pauseBetweenActions = pauseBetweenActions;
+    this.lockstep = Boolean(lockstep);
+    this.seed = Number.isInteger(seed) ? seed : seedFrom(playtest?.runId ?? 'ravensight');
+    this.recordTrace = recordTrace;
+    this.traceHeader = traceHeader;
+    this.ticksPerSecond = DEFAULT_TICKS_PER_SECOND;
+    this.tick = 0;
+    this.lastDigest = null;
+    this.bootDigest = null;
+    this.deaths = null;
+    this.errorCount = 0;
+    this.reasserted = 0;
+    this.trace = null;
+    this.traceSecrets = [];
+    this.importTimeoutMs = importTimeoutMs;
+    this._needsImport = needsImport;
+    this._sleep = sleep;
+    this._importProject = importProject;
+    this._resumeScale = 1;
+    this._paused = false;
     this.env = env;
     this.extraEnv = extraEnv;
     this._spawn = spawnFn;
@@ -206,13 +352,28 @@ export class GodotDriver {
     });
     this.tempRoot = prepared.tempRoot;
     this.projectCopy = prepared.projectCopy;
+    // A second Ctrl-C runs no finally: this is what still removes the copy and the game.
+    this._untrack = track({
+      kill: () => this.child?.kill('SIGKILL'),
+      root: () => (this.keepTemp ? [] : [this.tempRoot, this.userDataDir?.includes(USER_DIR_MARKER) ? this.userDataDir : null])
+    });
     try {
       this.port = this.port ?? (await this._choosePort());
 
       if (this.runDir) await fs.mkdir(this.runDir, { recursive: true });
       this.logPath = this.runDir ? path.join(this.runDir, 'godot.log') : null;
 
+      // A fresh clone or worktree has no .godot/ import cache, so no class_name
+      // resolves and every script that names one fails to parse. One headless
+      // import of the copy (never the developer's own directory) builds it.
+      await this._importIfNeeded();
+
       const args = ['--path', this.projectCopy];
+      if (this.lockstep) {
+        this.ticksPerSecond = await projectTicksPerSecond(this.projectDir);
+        args.push('--fixed-fps', String(this.ticksPerSecond));
+        await this._isolateUserData();
+      }
       if (recordVideo) args.push('--audio-driver', 'Dummy');
       if (this.headless) args.push('--headless');
       else args.push('--resolution', `${this.viewport.w}x${this.viewport.h}`);
@@ -230,6 +391,10 @@ export class GodotDriver {
       await this.rpc.call('hello', { token: this.driverToken });
       this.ping = await this.rpc.call('ping');
       this.headless = Boolean(this.ping.headless);
+      if (Number(this.ping.time_scale) > 0) this._resumeScale = Number(this.ping.time_scale);
+      await this._checkBoot();
+      if (this.lockstep) await this._startLockstep();
+      else if (this.pauseBetweenActions) await this._freeze();
       this._startedAt = this._now();
       if (this.headless) {
         this._consoleQueue.push({
@@ -257,25 +422,278 @@ export class GodotDriver {
     }
   }
 
+  async _importIfNeeded() {
+    let decision;
+    try {
+      decision = await this._needsImport(this.projectDir);
+    } catch {
+      decision = { needed: false };
+    }
+    if (!decision?.needed) return;
+    const result = await this._importProject({
+      godotPath: this.godot.path,
+      projectCopy: this.projectCopy,
+      env: this.launchEnv({ driver: false }),
+      timeoutMs: this.importTimeoutMs,
+      logPath: this.logPath,
+      spawnFn: this._spawn,
+    }).catch((error) => ({ ok: false, error: error.message }));
+    this.imported = { reason: decision.reason ?? null, ...result };
+    if (!result?.ok) {
+      this._consoleQueue.push({
+        kind: 'driver',
+        type: 'driver',
+        text: `the project import before launch did not finish (${result?.error ?? `exit ${result?.exitCode}`}); launching anyway`,
+      });
+    }
+  }
+
+  /**
+   * Fail the launch, rather than hand a persona a black screen, when the game
+   * never got past loading its scripts or its main scene.
+   */
+  async _checkBoot() {
+    await this.rpc.call('wait_frames', { n: BOOT_SETTLE_FRAMES }).catch(() => {});
+    // Godot's stdout arrives on its own stream; give the lines written while
+    // the game booted a moment to land before judging them.
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    const fatal = this._logTail.filter((line) => BOOT_FATAL_LINE.some((pattern) => pattern.test(line)));
+    let reason = null;
+    if (fatal.length > 0) {
+      reason = `the game's scripts did not load (${fatal.length} error line(s)): ${fatal.slice(0, 3).map((line) => line.trim()).join(' | ')}`;
+    } else {
+      const state = await this.rpc.call('get_state', { max_depth: 1, visible_only: true }).catch(() => null);
+      if (state && !state.current_scene && !state.current_scene_file) reason = 'no scene is loaded, so there is nothing to play';
+    }
+    if (!reason) return;
+    const error = new Error(`${BOOT_FAILED}: ${reason}. See ${this.logPath ?? 'the Godot output'}.`);
+    error.code = BOOT_FAILED;
+    error.fatal = true;
+    throw error;
+  }
+
+  /**
+   * A save file or a settings file left by the last run would make this one
+   * start somewhere else, so a lockstep run gets an empty user:// of its own. The
+   * name goes in the temp copy's project.godot, and the directory is removed at
+   * stop, only when its path carries this marker.
+   */
+  async _isolateUserData() {
+    const file = path.join(this.projectCopy, 'project.godot');
+    const name = `${USER_DIR_MARKER}/${randomBytes(8).toString('hex')}`;
+    let text = await fs.readFile(file, 'utf8');
+    text = setIniEntry(text, 'application', 'config/use_custom_user_dir', 'true');
+    text = setIniEntry(text, 'application', 'config/custom_user_dir_name', `"${name}"`);
+    // A window that never takes focus can never lose it, and losing it is what makes
+    // Godot drop every held key at a moment the desktop chooses.
+    text = setIniEntry(text, 'display', 'window/size/no_focus', 'true');
+    await fs.writeFile(file, text);
+  }
+
+  /**
+   * The addon stopped the clock and took the seed in its own _ready, before the
+   * main scene. This checks that happened and writes the trace's first two
+   * lines, the second being the state the game booted to.
+   */
+  async _startLockstep() {
+    if (!this.ping?.lockstep) {
+      const error = new Error('This project did not start in lockstep, so the run could not be recorded for replay. The driver addon may be older than this CLI.');
+      error.fatal = true;
+      throw error;
+    }
+    if (Number(this.ping.seed) !== this.seed) throw new Error(`The game started on seed ${this.ping.seed}, not the ${this.seed} it was given.`);
+    const { digest, tick } = await this.rpc.call('digest');
+    this.userDataDir = typeof this.ping.user_dir === 'string' ? this.ping.user_dir : null;
+    this.bootDigest = digest;
+    this.lastDigest = digest;
+    this.tick = tick;
+    this._readDeaths(digest);
+    if (this.recordTrace && this.runDir) {
+      this.trace = createTraceWriter(path.join(this.runDir, TRACE_FILE));
+      await this.trace.start({
+        engine: 'godot',
+        godot_version: this.ping.godot_version ?? null,
+        driver_version: this.ping.driver_version ?? null,
+        seed: this.seed,
+        ticks_per_second: this.ticksPerSecond,
+        headless: this.headless,
+        viewport: this.viewport,
+        ...(this.traceHeader ?? {}),
+      }, digest);
+    }
+  }
+
+  /** The newest `deaths` any _ravensight_state() hook reports, null if none does. */
+  _readDeaths(digest) {
+    const states = digest?.game_state;
+    if (!states || typeof states !== 'object') return;
+    for (const state of Object.values(states)) {
+      const value = state?.deaths;
+      if (typeof value === 'number' && Number.isFinite(value)) this.deaths = value;
+    }
+  }
+
+  /**
+   * One lockstep request: apply these inputs, run exactly `ticks` ticks, stop,
+   * answer. The only way the game's clock moves in this mode, so the trace and
+   * the game cannot disagree about what happened.
+   *
+   * @param {Array<Object>} events
+   * @param {number} ticks
+   * @param {{action?: string, args?: Object, digest?: boolean, redacted?: boolean}} [record]
+   * @returns {Promise<{tick: number, digest?: Object}>}
+   */
+  async step(events, ticks, { action = 'step', args = {}, digest = true, redacted = false } = {}) {
+    const whole = Math.min(Math.max(Math.round(Number(ticks) || 1), 1), MAX_STEP_TICKS);
+    const answer = await this.rpc.call(
+      'step',
+      { events, ticks: whole, digest },
+      // A windowed game may be held to the display's rate.
+      { timeoutMs: this.callTimeoutMs + whole * STEP_MS_PER_TICK },
+    );
+    const frame = this.tick;
+    this.tick = answer.tick;
+    if (Number.isInteger(answer.reasserted)) this.reasserted = answer.reasserted;
+    if (answer.digest) {
+      this.lastDigest = answer.digest;
+      this._readDeaths(answer.digest);
+    }
+    await this.trace?.step({
+      frame,
+      action,
+      args,
+      ...(redacted ? { redacted: true } : { events: traceableEvents(events, answer.clicks) }),
+      ticks: whole,
+      state: answer.digest ?? null,
+    });
+    return answer;
+  }
+
+  _ticksFor(ms) {
+    return Math.max(1, Math.round((ms / 1000) * this.ticksPerSecond));
+  }
+
+  async _performLockstep(action) {
+    const settle = Math.max(0, this.settleFrames);
+    switch (action.kind) {
+      case 'key': {
+        const keys = [action.key, ...(Array.isArray(action.keys) ? action.keys : [])]
+          .filter((key) => typeof key === 'string' && key !== '')
+          .slice(0, MAX_HELD_KEYS);
+        const holdMs = holdWallMs(action.holdMs, this._resumeScale);
+        const args = { key: action.key, keys: action.keys, hold_ms: action.holdMs };
+        await this.step(
+          keys.map((key) => ({ type: 'key', keycode: key, pressed: true })),
+          holdMs > 0 ? this._ticksFor(holdMs) : 1,
+          { action: 'key', args, digest: false },
+        );
+        await this.step(
+          [...keys].reverse().map((key) => ({ type: 'key', keycode: key, pressed: false })),
+          Math.max(settle, 1),
+          { action: 'key_release', args },
+        );
+        return;
+      }
+      case 'type': {
+        const text = String(action.text ?? '');
+        const redacted = this.traceSecrets.some((secret) => secret && text.includes(secret));
+        const args = redacted ? { redacted: true } : { text, submit: Boolean(action.submit) };
+        for (const char of text) {
+          const unicode = char.codePointAt(0);
+          await this.step(
+            [{ type: 'key', keycode: char, pressed: true, unicode }, { type: 'key', keycode: char, pressed: false, unicode }],
+            1,
+            { action: 'type', args, digest: false, redacted },
+          );
+        }
+        if (action.submit) {
+          await this.step(
+            [{ type: 'key', keycode: 'Enter', pressed: true }, { type: 'key', keycode: 'Enter', pressed: false }],
+            1,
+            { action: 'type_submit', args, digest: false },
+          );
+        }
+        await this.step([], Math.max(settle, 2), { action: 'settle', args: {} });
+        return;
+      }
+      case 'click': {
+        const target = action.target;
+        const where = typeof target === 'string'
+          ? { node_path: target }
+          : { x: target?.x ?? 0, y: target?.y ?? 0 };
+        const event = { type: 'click', ...where, ...(action.button ? { button: action.button } : {}), ...(action.double ? { double: true } : {}) };
+        await this.step([event], 2 + settle, { action: 'click', args: where });
+        return;
+      }
+      case 'press_action': {
+        const ms = Math.min(Math.max(Number(action.duration_ms ?? 50), 0), MAX_HOLD_MS);
+        const args = { action: action.action, duration_ms: ms };
+        await this.step([{ type: 'action', action: action.action, pressed: true }], this._ticksFor(ms), { action: 'press_action', args, digest: false });
+        await this.step([{ type: 'action', action: action.action, pressed: false }], Math.max(settle, 1), { action: 'press_action_release', args });
+        return;
+      }
+      case 'wait': {
+        const ms = Math.min(Math.max(Number(action.ms) || 0, 0), MAX_WAIT_MS);
+        await this.step([], ms > 0 ? this._ticksFor(ms) : 1, { action: 'wait', args: { ms } });
+        return;
+      }
+      default:
+        throw new Error(`godot driver cannot perform action kind "${action.kind}"`);
+    }
+  }
+
+  /**
+   * What this run measured, for a validation: game seconds rather than wall
+   * seconds, because a persona's thinking time is not time the player spent.
+   * `deaths` is null when the game exposes no count, never zero.
+   */
+  playMetrics() {
+    return {
+      ticks: this.tick,
+      game_seconds: this.ticksPerSecond > 0 ? this.tick / this.ticksPerSecond : null,
+      deaths: this.deaths,
+      errors: this.errorCount,
+      replayable: Boolean(this.trace) && !this.trace.truncated,
+      inputs_reasserted: this.reasserted,
+    };
+  }
+
+  /** Park the game: its clock stops, rendering and input handling go on. */
+  async _freeze() {
+    const answer = await this.rpc.call('set_time_scale', { scale: 0 });
+    const previous = Number(answer?.previous);
+    // The scale the game was running at is the one to resume with, so a game
+    // that sets its own time scale keeps it.
+    if (Number.isFinite(previous) && previous > 0) this._resumeScale = previous;
+    this._paused = true;
+  }
+
+  async _resume() {
+    await this.rpc.call('set_time_scale', { scale: this._resumeScale });
+    this._paused = false;
+  }
+
   /**
    * The environment Godot is launched with. RAVENSIGHT_DRIVER* activate and
    * authenticate the driver; the RAVENSIGHT_PLAYTEST_* set is read by the
    * customer's own Ravensight.gd in _ready(), which is what makes every event
    * the game tracks during this run carry synthetic / persona / pt_run tags.
    */
-  launchEnv() {
+  launchEnv({ driver = true } = {}) {
     const { token, runId, jobId, persona } = this.playtest ?? {};
-    const allowed = new Set(ENV_ALLOWLIST.map((name) => name.toLowerCase()));
-    const out = {};
-    for (const [key, value] of Object.entries(this.env ?? {})) {
-      if (allowed.has(key.toLowerCase())) out[key] = value;
-    }
+    const out = allowlistedEnv(this.env);
     Object.assign(out, this.extraEnv ?? {});
+    if (!driver) return out;
     Object.assign(out, {
       RAVENSIGHT_DRIVER: '1',
       RAVENSIGHT_DRIVER_PORT: String(this.port),
       RAVENSIGHT_DRIVER_TOKEN: this.driverToken,
     });
+    if (this.lockstep) {
+      out.RAVENSIGHT_DRIVER_LOCKSTEP = '1';
+      out.RAVENSIGHT_DRIVER_SEED = String(this.seed);
+      out.RAVENSIGHT_DRIVER_TICKS = String(this.ticksPerSecond);
+    }
     if (token) out.RAVENSIGHT_PLAYTEST_TOKEN = token;
     if (runId) out.RAVENSIGHT_PLAYTEST_RUN_ID = runId;
     if (jobId) out.RAVENSIGHT_PLAYTEST_JOB_ID = jobId;
@@ -290,9 +708,15 @@ export class GodotDriver {
     } catch (error) {
       const tail = this._logTail.slice(-15).join('\n');
       const exited = this.exitCode === null ? '' : ` Godot exited with code ${this.exitCode}.`;
-      throw new Error(
-        `${error.message}.${exited}${tail ? `\nLast Godot output:\n${tail}` : ''}`,
+      // The game never reached a state anything could play, which is what a boot
+      // failure is: the same word, so a fix whose verify met this is told apart from
+      // one whose persona ran and failed, and its unit comes back the same way.
+      const failure = new Error(
+        `${BOOT_FAILED}: ${error.message}.${exited}${tail ? `\nLast Godot output:\n${tail}` : ''}`,
       );
+      failure.code = BOOT_FAILED;
+      failure.fatal = true;
+      throw failure;
     }
   }
 
@@ -339,6 +763,7 @@ export class GodotDriver {
         continue;
       }
       if (ERROR_LINE.test(line.trim())) {
+        this.errorCount += 1;
         this._consoleQueue.push({ kind: 'error', text: line.trim() });
       }
     }
@@ -364,13 +789,17 @@ export class GodotDriver {
       state,
       gameState,
       step: this._step,
-      elapsedMs: this._startedAt === null ? 0 : this._now() - this._startedAt,
+      elapsedMs: this.lockstep
+        ? Math.round((this.tick / this.ticksPerSecond) * 1000)
+        : (this._startedAt === null ? 0 : this._now() - this._startedAt),
     });
     const wantVision = vision ?? needsVision(observation);
     if (wantVision && !this.headless) {
       const shot = await this._rawScreenshot();
       if (shot) {
-        observation = { ...observation, screenshot_b64: shot.data };
+        // screenshotBase64 is the name the persona's tools read; the old
+        // screenshot_b64 is kept for anything that reads the observation raw.
+        observation = { ...observation, screenshot_b64: shot.data, screenshotBase64: shot.data, screenshotMediaType: 'image/png' };
       }
     }
     // changed detection compares outline hashes only, never this observation's
@@ -389,21 +818,41 @@ export class GodotDriver {
     if (action.kind === 'type' && (action.replace || action.target)) {
       return { ok: false, error: 'replace (empty a field, then type) and a typing target are only available on playwright_web; this driver can only type more text into what has focus', changed: false };
     }
-    try {
-      await this._perform(action);
-    } catch (error) {
-      if (error instanceof DriverRpcError) {
-        return { ok: false, error: error.rpcMessage, code: error.code, data: error.data, changed: false };
+    if (this.lockstep && action.kind !== 'quit' && action.kind !== 'set_time_scale') {
+      try {
+        await this._performLockstep(action);
+      } catch (error) {
+        if (error instanceof DriverRpcError) {
+          return { ok: false, error: error.rpcMessage, code: error.code, data: error.data, changed: false };
+        }
+        throw error;
       }
-      throw error;
+      const { hash } = await this._snapshot();
+      const changed = this._lastHash !== null && hash !== this._lastHash;
+      this._lastHash = hash;
+      return { ok: true, changed };
     }
-    if (action.kind === 'quit') return { ok: true, changed: false };
-    // Input reaches the game a frame after it is parsed, and a handler that
-    // changes a label runs a frame after that, so a snapshot taken the instant
-    // an action returns reports the screen as it was one action ago. Settling
-    // first is what makes "changed" mean what the persona loop thinks it means.
-    if (this.settleFrames > 0) {
-      await this.rpc.call('wait_frames', { n: this.settleFrames }).catch(() => {});
+    const pausing = this.pauseBetweenActions && this._paused && action.kind !== 'quit' && action.kind !== 'set_time_scale';
+    try {
+      if (pausing) await this._resume();
+      try {
+        await this._perform(action);
+      } catch (error) {
+        if (error instanceof DriverRpcError) {
+          return { ok: false, error: error.rpcMessage, code: error.code, data: error.data, changed: false };
+        }
+        throw error;
+      }
+      if (action.kind === 'quit') return { ok: true, changed: false };
+      // Input reaches the game a frame after it is parsed, and a handler that
+      // changes a label runs a frame after that, so a snapshot taken the instant
+      // an action returns reports the screen as it was one action ago. Settling
+      // first is what makes "changed" mean what the persona loop thinks it means.
+      if (this.settleFrames > 0) {
+        await this.rpc.call('wait_frames', { n: this.settleFrames }).catch(() => {});
+      }
+    } finally {
+      if (pausing && this.rpc && !this.rpc.closed) await this._freeze().catch(() => {});
     }
     const { hash } = await this._snapshot();
     const changed = this._lastHash !== null && hash !== this._lastHash;
@@ -413,11 +862,30 @@ export class GodotDriver {
 
   async _perform(action) {
     switch (action.kind) {
-      case 'key':
-        await this.rpc.call('key', { keycode: action.key, pressed: true });
-        await this.rpc.call('wait_frames', { n: 1 });
-        await this.rpc.call('key', { keycode: action.key, pressed: false });
+      case 'key': {
+        // Every key goes down, the game runs for the hold, then every key that
+        // went down comes back up, in reverse order, even when a later press
+        // was refused: a key left held would steer the rest of the run.
+        const keys = [action.key, ...(Array.isArray(action.keys) ? action.keys : [])]
+          .filter((key) => typeof key === 'string' && key !== '')
+          .slice(0, MAX_HELD_KEYS);
+        const holdMs = holdWallMs(action.holdMs, this._resumeScale);
+        const down = [];
+        try {
+          for (const key of keys) {
+            await this.rpc.call('key', { keycode: key, pressed: true });
+            down.push(key);
+          }
+          // A tap is one frame, as it always was; a hold is game time.
+          if (holdMs > 0) await this._sleep(holdMs);
+          else await this.rpc.call('wait_frames', { n: 1 });
+        } finally {
+          for (const key of down.reverse()) {
+            await this.rpc.call('key', { keycode: key, pressed: false }).catch(() => {});
+          }
+        }
         return;
+      }
       case 'type':
         for (const char of String(action.text ?? '')) {
           await this.rpc.call('key', { keycode: char, pressed: true, unicode: char.codePointAt(0) });
@@ -452,8 +920,10 @@ export class GodotDriver {
         );
         return;
       case 'wait': {
-        const frames = Math.max(1, Math.round(((action.ms ?? 0) / 1000) * FRAMES_PER_SECOND));
-        await this.rpc.call('wait_frames', { n: frames }, { timeoutMs: this.callTimeoutMs + (action.ms ?? 0) });
+        // On the clock, like a hold: a frame count is display rate dependent.
+        const ms = Math.min(Math.max(Number(action.ms) || 0, 0), MAX_WAIT_MS);
+        if (ms > 0) await this._sleep(ms);
+        else await this.rpc.call('wait_frames', { n: 1 });
         return;
       }
       case 'set_time_scale':
@@ -506,9 +976,12 @@ export class GodotDriver {
     this._shotIndex += 1;
     const dir = path.join(this.runDir ?? '.', 'screenshots');
     await fs.mkdir(dir, { recursive: true });
-    const file = path.join(dir, `${String(this._shotIndex).padStart(2, '0')}-${slug(name)}.png`);
+    // relativePath is what a report cites as evidence; without it every
+    // Godot screenshot reached the report as screenshots/undefined.
+    const relativePath = path.join('screenshots', screenshotName(this._shotIndex, name));
+    const file = path.join(this.runDir ?? '.', relativePath);
     await fs.writeFile(file, Buffer.from(shot.data, 'base64'));
-    return { path: file, width: shot.width, height: shot.height };
+    return { path: file, relativePath, width: shot.width, height: shot.height };
   }
 
   /** Console errors since the previous call, from Godot stdout and driver events. */
@@ -516,7 +989,9 @@ export class GodotDriver {
     const fromEvents = (this.rpc?.drainEvents() ?? [])
       .filter((event) => event.type === 'error')
       .map((event) => ({ kind: 'error', text: event.message, source: event.source, frame: event.frame }));
-    const out = [...this._consoleQueue, ...fromEvents];
+    // The persona loop labels a console note by its `type`, as the browser
+    // drivers report it; without one every note read "undefined: ...".
+    const out = [...this._consoleQueue, ...fromEvents].map((entry) => ({ type: entry.kind, ...entry }));
     this._consoleQueue = [];
     return out;
   }
@@ -631,6 +1106,7 @@ export class GodotDriver {
   async _stop({ removeTemp = !this.keepTemp, reason = 'stopped' } = {}) {
     this._stopped = true;
     this._signal?.removeEventListener('abort', this._onAbort);
+    await this.trace?.end({ tick: this.tick, reason, deaths: this.deaths, errors: this.errorCount }).catch(() => {});
     if (this._recordingStartedAt != null) this._endCapture(reason);
     await this._capturePromise;
     if (this.rpc && !this.rpc.closed) {
@@ -638,11 +1114,17 @@ export class GodotDriver {
     }
     await this._waitForExit(this.exitTimeoutMs);
     this.rpc?.close();
+    if (this.userDataDir?.includes(USER_DIR_MARKER)) {
+      await fs.rm(this.userDataDir, { recursive: true, force: true }).catch(() => {});
+      this.userDataDir = null;
+    }
     if (removeTemp && this.tempRoot) {
       await fs.rm(this.tempRoot, { recursive: true, force: true }).catch(() => {});
       this.tempRoot = null;
       this.projectCopy = null;
     }
+    this._untrack?.();
+    this._untrack = null;
     return {
       videoPath: null, ...await this._finalizeRecording(),
       frameCount: this._frameIndex, chapters: this.chapters,
@@ -669,16 +1151,21 @@ export class GodotDriver {
   }
 }
 
-export function createGodotDriver(options) {
-  return new GodotDriver(options);
+/**
+ * The environment for any Godot process: `ENV_ALLOWLIST` and nothing else.
+ *
+ * @param {Object} [env]
+ * @returns {Object}
+ */
+export function allowlistedEnv(env = process.env) {
+  const allowed = new Set(ENV_ALLOWLIST.map((name) => name.toLowerCase()));
+  const out = {};
+  for (const [key, value] of Object.entries(env ?? {})) {
+    if (allowed.has(key.toLowerCase())) out[key] = value;
+  }
+  return out;
 }
 
-function slug(name) {
-  return (
-    String(name ?? 'shot')
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-+|-+$/g, '')
-      .slice(0, 40) || 'shot'
-  );
+export function createGodotDriver(options) {
+  return new GodotDriver(options);
 }