ravensight-playtest 0.7.0 → 0.7.5

package/src/run/drivers/web.js

@@ -1,6 +1,7 @@
 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 { gameRefusal, runnerGone } from '../gameRefusal.js';
 import {
   DriverError,
   STALE_REF_MESSAGE,
@@ -31,6 +32,18 @@ import {
 /** Default recording and viewport size. Kept at 720p to match the upload guidance. */
 export const DEFAULT_VIEWPORT = Object.freeze({ width: 1280, height: 720 });
 
+/**
+ * The frame a canvas observation sends the model: JPEG at this quality, at the
+ * viewport's own size. The model is billed for an image by its pixels, so the
+ * format changes nothing there and the coordinates a persona reads off it stay
+ * the page's own. What it changes is the proxy's reservation, which prices the
+ * request body's characters as text: a 1280x720 PNG of a busy canvas is
+ * 300 to 900 KB of base64, a projection of up to half a standard run's model
+ * budget for one act turn, where the same frame as JPEG at 70 is 60 to 150 KB.
+ * Screenshots saved as evidence stay PNG.
+ */
+export const OBSERVATION_FRAME = Object.freeze({ type: 'jpeg', quality: 70, mediaType: 'image/jpeg' });
+
 /** A `wait` action is clamped to this, so one turn cannot burn the wall clock. */
 export const MAX_WAIT_MS = 10000;
 
@@ -853,21 +866,24 @@ async function loadPlaywright(importer) {
 }
 
 /**
- * Whether the model is allowed to navigate here. The persona may only move
- * around inside the build it was pointed at, plus the rest of loopback when
- * the build ITSELF is on loopback (a local web export is commonly served on
- * one port with an asset or API server on another).
+ * Whether the page may be at this address: the build's own origin, and
+ * nothing else. It decides the `navigate` tool and every top-level
+ * navigation the page itself starts (a clicked link, a form, a script, a
+ * server redirect), recording or not.
  *
  * Game text is untrusted input: a level name or a leaderboard entry can
- * carry "go to https://.../ and paste your token". Confining `navigate` to
+ * carry "go to https://.../ and paste your token". Confining the page to
  * the target's own origin means the worst such an instruction can achieve
  * is a page of the developer's own game.
  *
- * The loopback allowance is conditional for a reason. A hosted build has no
- * business steering the browser at the developer's own machine: `localhost`
- * there is whatever else they happen to be running, dev servers and admin
- * panels included, and reaching it is a genuine escalation rather than a
- * convenience.
+ * The one allowance is a loopback alias: when the build is on loopback,
+ * `localhost`, `127.0.0.1` and `[::1]` on the SAME scheme and port are the
+ * same server, so a page that links to itself by another loopback name is
+ * still the build. Another port is another server (a dev server, an admin
+ * panel, a mirror of the live site) and is off the build. Subresources are
+ * not decided here: a page may still load assets or call an API on another
+ * port. A hosted build never gets the loopback alias: `localhost` there is
+ * whatever else the developer happens to be running.
  *
  * @param {string} candidate
  * @param {string} target
@@ -884,7 +900,35 @@ export function isNavigationAllowed(candidate, target) {
   }
   if (url.protocol !== 'http:' && url.protocol !== 'https:') return false;
   if (url.origin === base.origin) return true;
-  return isLoopback(base.hostname) && isLoopback(url.hostname);
+  return isLoopback(base.hostname) && isLoopback(url.hostname)
+    && url.protocol === base.protocol && effectivePort(url) === effectivePort(base);
+}
+
+/**
+ * @param {URL} url
+ * @returns {string}
+ */
+function effectivePort(url) {
+  return url.port || (url.protocol === 'https:' ? '443' : '80');
+}
+
+/** The most off-site attempts one run keeps for its notes. */
+export const MAX_OFF_SITE_ATTEMPTS = 50;
+
+/**
+ * The host an off-site navigation asked for, for the persona's refusal text.
+ * Never the full address: a query string can carry anything.
+ *
+ * @param {string} candidate
+ * @returns {string}
+ */
+export function offSiteHost(candidate) {
+  try {
+    const url = new URL(candidate);
+    return url.host || url.protocol.replace(/:$/, '');
+  } catch {
+    return 'an address that is not a web page';
+  }
 }
 
 const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '[::1]', '::1'];
@@ -1158,6 +1202,68 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
   const consoleBuffer = [];
   /** Recent failed requests, newest last, bounded: what a console line is matched against. */
   const networkFailures = [];
+  // Containment. The build's addresses (the target, and where its first
+  // load landed), every attempt to leave them since the last drain, and
+  // the last address on the build, for a recovery.
+  let buildTargets = [];
+  let guardArmed = false;
+  const offSite = [];
+  let offSiteCount = 0;
+  let lastBuildUrl = null;
+  let recovery = null;
+
+  /** @param {string} candidate */
+  function onBuild(candidate) {
+    return buildTargets.some(base => isNavigationAllowed(candidate, base));
+  }
+
+  /**
+   * @param {string} url
+   * @param {string} via
+   */
+  function recordOffSite(url, via) {
+    offSiteCount += 1;
+    offSite.push({ host: offSiteHost(url), url: networkUrl(url), via, claimed: false });
+    while (offSite.length > MAX_OFF_SITE_ATTEMPTS) offSite.shift();
+  }
+
+  /**
+   * A top-level document landed off the build anyway: a server redirect,
+   * which a route never sees after its first hop. Go back, and if that does
+   * not land on the build, load the last address that did.
+   * @param {any} current
+   */
+  async function recoverToBuild(current) {
+    try {
+      await current.goBack({ waitUntil: 'domcontentloaded', timeout: 10000 });
+    } catch {
+      // Nothing to go back to, or the page would not: load the build instead.
+    }
+    try {
+      if (!onBuild(current.url()) && lastBuildUrl) await current.goto(lastBuildUrl, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    } catch {
+      // The next observation shows where the page is; act refuses from there.
+    }
+  }
+
+  /** Any recovery in flight, settled. */
+  async function settled() {
+    while (recovery) {
+      const pending = recovery;
+      await pending;
+      if (recovery === pending) recovery = null;
+    }
+  }
+
+  /** @param {any} request */
+  function isTopLevel(request) {
+    try {
+      return !request.frame().parentFrame();
+    } catch {
+      // A new window's first request is issued before its frame exists.
+      return null;
+    }
+  }
 
   /** @returns {any} */
   function requirePage() {
@@ -1349,7 +1455,7 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
     const snap = await snapshotText();
     const after = { text: hashText(snap, shownText(snap)) };
     if (String(snap.text).trim().length < THIN_OBSERVATION_CHARS) {
-      const frame = await current.screenshot({ type: 'png', timeout: ACTION_TIMEOUT_MS });
+      const frame = await current.screenshot({ type: OBSERVATION_FRAME.type, quality: OBSERVATION_FRAME.quality, timeout: ACTION_TIMEOUT_MS });
       after.screenshotBase64 = frame.toString('base64');
     }
     return observationHash(after);
@@ -1426,6 +1532,136 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
     finally { inspecting = false; }
   }
 
+  /**
+   * @param {any} current
+   * @param {import('./driver.js').Action} action
+   * @returns {Promise<import('./driver.js').ActResult>}
+   */
+  async function actOnPage(current, action) {
+    const before = lastHash;
+    const urlBefore = pageUrl(current);
+    const tokenBefore = await documentToken(current);
+    let typed = null;
+    try {
+      switch (action.kind) {
+        case 'key':
+          if (action.holdMs > 0 || (Array.isArray(action.keys) && action.keys.length > 0)) {
+            // Held keys go down together and come up in reverse, even when
+            // one is refused, so nothing stays held for the rest of the run.
+            const keys = [action.key, ...(action.keys || [])].map(key => normalizeChord(key, editModifier));
+            const down = [];
+            try {
+              for (const key of keys) {
+                await current.keyboard.down(key);
+                down.push(key);
+              }
+              await current.waitForTimeout(Math.min(Math.max(Number(action.holdMs) || 0, 0), MAX_WAIT_MS));
+            } finally {
+              for (const key of down.reverse()) await current.keyboard.up(key).catch(() => {});
+            }
+            break;
+          }
+          await current.keyboard.press(normalizeChord(action.key, editModifier), { timeout: ACTION_TIMEOUT_MS });
+          break;
+        case 'type':
+          typed = await typeText(current, action);
+          if (action.submit) await current.keyboard.press('Enter');
+          break;
+        case 'click': {
+          if (!action.ref && action.target && typeof action.target === 'object') {
+            await current.mouse.click(Number(action.target.x), Number(action.target.y));
+            break;
+          }
+          const resolved = await targetFor(current, action);
+          if (resolved && resolved.point) await current.mouse.click(resolved.point.x, resolved.point.y);
+          else await resolved.click({ timeout: ACTION_TIMEOUT_MS });
+          break;
+        }
+        case 'navigate': {
+          const url = String(action.url);
+          if (!onBuild(url)) {
+            // A refusal by the runner, not a failure of the game or the
+            // driver: ./tools.js answers it with plain text and the persona
+            // plays on (an off-site address in a brief is common).
+            recordOffSite(url, 'navigate');
+            offSite[offSite.length - 1].claimed = true;
+            return { ok: false, changed: false, refused: 'off_site', host: offSiteHost(url), error: `navigation to ${url} is outside this build's origin (${new URL(target).origin}) and was refused` };
+          }
+          await current.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+          break;
+        }
+        case 'wait':
+          await current.waitForTimeout(Math.min(Math.max(Number(action.ms) || 0, 0), MAX_WAIT_MS));
+          break;
+        default:
+          return { ok: false, changed: false, error: `the playwright_web driver cannot do "${action.kind}"` };
+      }
+    } catch (error) {
+      // Playwright colours its call log; the colour codes are noise here.
+      const text = String(error && error.message ? error.message : error).replace(/\u001b\[[0-9;]*m/g, '');
+      // Two elements under one name: Playwright's strict mode. Answered
+      // with the candidates and their refs, so the next try can work.
+      if (/strict mode violation/i.test(text)) {
+        const count = Number((text.match(/resolved to (\d+) elements/) || [])[1]) || null;
+        const candidates = action.target && typeof action.target === 'string' ? candidatesFor(lastNodes, action.target) : [];
+        return { ok: false, changed: false, error: ambiguityMessage(action.target || action.ref || '', candidates, count), driverError: true };
+      }
+      if (error && error.driverSide) return { ok: false, changed: false, error: text, driverError: true };
+      // A click the page kept intercepting is the game's: something sat on
+      // top of the target and never went away. Named, never a driver error.
+      const interceptor = text.match(/^\s*-?\s*(.+?)\s+(?:from .+? subtree\s+)?intercepts pointer events/m);
+      const intercepted = interceptor ? interceptor[1] : null;
+      if (/Timeout \d+ms exceeded/i.test(text) && intercepted) {
+        return { ok: false, changed: false, error: `timed out: ${intercepted.slice(0, 160)} intercepts pointer events over the target`, driverError: false };
+      }
+      // A target the page shows as disabled, hidden or not editable is the
+      // game refusing the action, which is what a player sees: evidence,
+      // never a driver error. The resolved element is named so the report
+      // step can cite it.
+      const refusal = /Timeout \d+ms exceeded/i.test(text) ? gameRefusal(text) : null;
+      if (refusal) {
+        return { ok: false, changed: false, error: `the game did not accept this action: the target is ${refusal.state} (${refusal.element})`, driverError: false };
+      }
+      // The browser or page closed under the runner: the runner's failure.
+      if (runnerGone(text)) return { ok: false, changed: false, error: text, driverError: true };
+      // A timeout with the page unchanged while resolving a click or typing
+      // target means the target was never found or never actionable: the
+      // driver's failure, not the game's. Never for navigate: a game that
+      // never loads is a real blocker.
+      if (/Timeout \d+ms exceeded/i.test(text) && (action.kind === 'click' || action.kind === 'type')) {
+        let unchanged = false;
+        try {
+          unchanged = (await currentHash(current)) === before;
+        } catch {
+          unchanged = false;
+        }
+        return { ok: false, changed: false, error: text, driverError: unchanged };
+      }
+      return { ok: false, changed: false, error: text };
+    }
+
+    const measure = async () => {
+      const facts = { urlBefore, urlAfter: pageUrl(current), tokenBefore, tokenAfter: await documentToken(current), hashBefore: before, valueBefore: typed ? typed.before : null, valueAfter: typed ? typed.after : null };
+      // The same basis observe() hashes, so the two are comparable.
+      // Without it a long screen is always "changed".
+      facts.hashAfter = await currentHash(current);
+      return computeChanged(facts);
+    };
+    let changed = false;
+    try {
+      changed = await measure();
+      // A click or a submit can start a navigation that has not landed yet:
+      // look once more after a short pause before calling it a no-op.
+      if (!changed && SETTLE_MS > 0 && (action.kind === 'click' || action.kind === 'key' || (action.kind === 'type' && action.submit))) {
+        await new Promise(resolve => setTimeout(resolve, SETTLE_MS));
+        changed = await measure();
+      }
+    } catch {
+      changed = true;
+    }
+    return { ok: true, changed };
+  }
+
   return {
     name: 'playwright_web',
     supportsRefs: true,
@@ -1477,22 +1713,62 @@ 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 => {
+      // The page never leaves the build, recording or not. A top-level
+      // navigation off it (a clicked link, a form, a script) is answered with
+      // an empty 204, which a browser treats as "stay where you are": the
+      // game keeps its state and nothing is fetched from the other site. An
+      // abort would put an error page in its place instead. Only addresses
+      // off the build are routed at all; subresources pass as before, and
+      // an embedded frame may still load what it loads.
+      buildTargets = [url];
+      if (typeof context.route === 'function') {
+        await context.route(candidate => !onBuild(String(candidate && candidate.href ? candidate.href : candidate)), route => {
           const request = route.request();
-          if (request.isNavigationRequest() && !request.frame().parentFrame() && new URL(request.url()).origin !== origin) {
-            return route.abort('blockedbyclient');
-          }
-          return route.continue();
+          if (!guardArmed || !request.isNavigationRequest()) return route.continue();
+          const topLevel = isTopLevel(request);
+          if (topLevel === false) return route.continue();
+          // A new window's first request (no frame yet) is answered the same
+          // way: the window never gets a document, so Playwright never even
+          // surfaces it as a page.
+          recordOffSite(request.url(), topLevel === null ? 'new window' : 'navigation');
+          return route.fulfill({ status: 204, body: '' });
         });
       }
       captureStartedAt = videoRequested ? now() : null;
       page = await context.newPage();
+      // A new window that did get a document (one on the build, or a blank
+      // one a script means to point somewhere) is never played either: it is
+      // closed at once and noted. (Context video may also briefly allocate a
+      // file for it; finalization discards every non-selected file.)
+      page.on('popup', popup => {
+        let opened = null;
+        try {
+          opened = popup.url();
+        } catch {
+          opened = null;
+        }
+        recordOffSite(opened && opened !== 'about:blank' ? opened : 'about:blank', 'new window');
+        if (!opened || opened === 'about:blank') offSite[offSite.length - 1].host = 'a new window';
+        void popup.close().catch(() => {});
+      });
+      // The backstop: a top-level document that landed off the build anyway
+      // (a server redirect after its first hop) is undone before anything
+      // observes it. Error pages are the build's own failures, not a visit.
+      page.on('framenavigated', frame => {
+        try {
+          if (!guardArmed || typeof page.mainFrame !== 'function' || frame !== page.mainFrame()) return;
+          const landed = frame.url();
+          if (onBuild(landed)) { lastBuildUrl = landed; return; }
+          if (!/^https?:/i.test(landed)) return;
+          recordOffSite(landed, 'redirect');
+          const current = page;
+          const previous = recovery;
+          recovery = Promise.resolve(previous).then(() => recoverToBuild(current));
+        } catch {
+          // A frame that cannot be read is not a navigation worth undoing.
+        }
+      });
       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);
@@ -1543,6 +1819,17 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
       if (response && response.status() >= 400) {
         throw new DriverError(`${url} answered ${response.status()}`, { fatal: true });
       }
+      // Where the first load landed is the build too (a hosted address that
+      // redirects to its canonical one, http to https). From here on, leaving
+      // is refused.
+      try {
+        const landed = page.url();
+        if (/^https?:/i.test(landed) && !onBuild(landed)) buildTargets.push(landed);
+        lastBuildUrl = /^https?:/i.test(landed) ? landed : url;
+      } catch {
+        lastBuildUrl = url;
+      }
+      guardArmed = true;
       } catch (error) {
         await stop({ reason: 'launch_failed' }).catch(() => {});
         if (captureDirectory) await rm(captureDirectory, { recursive: true, force: true }).catch(() => {});
@@ -1553,6 +1840,7 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
     /** @returns {Promise<import('./driver.js').Observation>} */
     async observe() {
       const current = requirePage();
+      await settled();
       const started = Date.now();
       step += 1;
       const snap = await snapshotText();
@@ -1579,9 +1867,9 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
       // is the only way to play them. Spend an image only then.
       if (String(text).trim().length < THIN_OBSERVATION_CHARS) {
         try {
-          const buffer = await current.screenshot({ type: 'png', timeout: ACTION_TIMEOUT_MS });
+          const buffer = await current.screenshot({ type: OBSERVATION_FRAME.type, quality: OBSERVATION_FRAME.quality, timeout: ACTION_TIMEOUT_MS });
           observation.screenshotBase64 = buffer.toString('base64');
-          observation.screenshotMediaType = 'image/png';
+          observation.screenshotMediaType = OBSERVATION_FRAME.mediaType;
         } catch {
           // No image and thin text is still an observation; the persona will
           // read it as a blank screen, which is what it is.
@@ -1608,115 +1896,43 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
      */
     async act(action) {
       const current = requirePage();
-      const before = lastHash;
-      const urlBefore = pageUrl(current);
-      const tokenBefore = await documentToken(current);
-      let typed = null;
-      try {
-        switch (action.kind) {
-          case 'key':
-            if (action.holdMs > 0 || (Array.isArray(action.keys) && action.keys.length > 0)) {
-              // Held keys go down together and come up in reverse, even when
-              // one is refused, so nothing stays held for the rest of the run.
-              const keys = [action.key, ...(action.keys || [])].map(key => normalizeChord(key, editModifier));
-              const down = [];
-              try {
-                for (const key of keys) {
-                  await current.keyboard.down(key);
-                  down.push(key);
-                }
-                await current.waitForTimeout(Math.min(Math.max(Number(action.holdMs) || 0, 0), MAX_WAIT_MS));
-              } finally {
-                for (const key of down.reverse()) await current.keyboard.up(key).catch(() => {});
-              }
-              break;
-            }
-            await current.keyboard.press(normalizeChord(action.key, editModifier), { timeout: ACTION_TIMEOUT_MS });
-            break;
-          case 'type':
-            typed = await typeText(current, action);
-            if (action.submit) await current.keyboard.press('Enter');
-            break;
-          case 'click': {
-            if (!action.ref && action.target && typeof action.target === 'object') {
-              await current.mouse.click(Number(action.target.x), Number(action.target.y));
-              break;
-            }
-            const resolved = await targetFor(current, action);
-            if (resolved && resolved.point) await current.mouse.click(resolved.point.x, resolved.point.y);
-            else await resolved.click({ timeout: ACTION_TIMEOUT_MS });
-            break;
-          }
-          case 'navigate': {
-            const url = String(action.url);
-            if (!isNavigationAllowed(url, target)) {
-              return { ok: false, changed: false, error: `navigation to ${url} is outside this build's origin (${new URL(target).origin}) and was refused` };
-            }
-            await current.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
-            break;
-          }
-          case 'wait':
-            await current.waitForTimeout(Math.min(Math.max(Number(action.ms) || 0, 0), MAX_WAIT_MS));
-            break;
-          default:
-            return { ok: false, changed: false, error: `the playwright_web driver cannot do "${action.kind}"` };
-        }
-      } catch (error) {
-        // Playwright colours its call log; the colour codes are noise here.
-        const text = String(error && error.message ? error.message : error).replace(/\u001b\[[0-9;]*m/g, '');
-        // Two elements under one name: Playwright's strict mode. Answered
-        // with the candidates and their refs, so the next try can work.
-        if (/strict mode violation/i.test(text)) {
-          const count = Number((text.match(/resolved to (\d+) elements/) || [])[1]) || null;
-          const candidates = action.target && typeof action.target === 'string' ? candidatesFor(lastNodes, action.target) : [];
-          return { ok: false, changed: false, error: ambiguityMessage(action.target || action.ref || '', candidates, count), driverError: true };
-        }
-        if (error && error.driverSide) return { ok: false, changed: false, error: text, driverError: true };
-        // A click the page kept intercepting is the game's: something sat on
-        // top of the target and never went away. Named, never a driver error.
-        const interceptor = text.match(/^\s*-?\s*(.+?)\s+(?:from .+? subtree\s+)?intercepts pointer events/m);
-        const intercepted = interceptor ? interceptor[1] : null;
-        if (/Timeout \d+ms exceeded/i.test(text) && intercepted) {
-          return { ok: false, changed: false, error: `timed out: ${intercepted.slice(0, 160)} intercepts pointer events over the target`, driverError: false };
-        }
-        // A timeout with the page unchanged while resolving a click or typing
-        // target means the target was never found or never actionable: the
-        // driver's failure, not the game's. Never for navigate: a game that
-        // never loads is a real blocker.
-        if (/Timeout \d+ms exceeded/i.test(text) && (action.kind === 'click' || action.kind === 'type')) {
-          let unchanged = false;
-          try {
-            unchanged = (await currentHash(current)) === before;
-          } catch {
-            unchanged = false;
-          }
-          return { ok: false, changed: false, error: text, driverError: unchanged };
-        }
-        return { ok: false, changed: false, error: text };
+      await settled();
+      const attemptsBefore = offSiteCount;
+      const outcome = await actOnPage(current, action);
+      if (outcome.refused) return outcome;
+      // A click, a key, a submit or a script that tried to leave the build:
+      // the page stayed (or was brought back), and the persona is told the
+      // same as for a refused `navigate`. A step that changed nothing.
+      await settled();
+      if (offSiteCount > attemptsBefore) {
+        const fresh = offSite.filter(attempt => !attempt.claimed).slice(-(offSiteCount - attemptsBefore));
+        for (const attempt of fresh) attempt.claimed = true;
+        const host = fresh.length > 0 ? fresh[fresh.length - 1].host : 'another site';
+        return { ok: false, changed: false, refused: 'off_site', host, error: `the page tried to leave the build for ${host}; the runner kept it on the build` };
       }
+      return outcome;
+    },
 
-      const measure = async () => {
-        const facts = { urlBefore, urlAfter: pageUrl(current), tokenBefore, tokenAfter: await documentToken(current), hashBefore: before, valueBefore: typed ? typed.before : null, valueAfter: typed ? typed.after : null };
-        // The same basis observe() hashes, so the two are comparable.
-        // Without it a long screen is always "changed".
-        facts.hashAfter = await currentHash(current);
-        return computeChanged(facts);
-      };
-      let changed = false;
+    /**
+     * Every attempt to leave the build since the last call, claimed by an
+     * action or not (a timer redirect between actions has no action), for the
+     * run's notes. Hosts and addresses without their query strings only.
+     * @returns {Array<{host: string, url: string, via: string}>}
+     */
+    offSiteAttempts() {
+      return offSite.splice(0, offSite.length).map(({ host, url: address, via }) => ({ host, url: address, via }));
+    },
+
+    /** How many pages the browser has open: one, whatever the game opened. */
+    openPages() {
       try {
-        changed = await measure();
-        // A click or a submit can start a navigation that has not landed yet:
-        // look once more after a short pause before calling it a no-op.
-        if (!changed && SETTLE_MS > 0 && (action.kind === 'click' || action.kind === 'key' || (action.kind === 'type' && action.submit))) {
-          await new Promise(resolve => setTimeout(resolve, SETTLE_MS));
-          changed = await measure();
-        }
+        return context && typeof context.pages === 'function' ? context.pages().length : (page ? 1 : 0);
       } catch {
-        changed = true;
+        return page ? 1 : 0;
       }
-      return { ok: true, changed };
     },
 
+
     /**
      * @param {string} name
      * @returns {Promise<{path: string, relativePath: string}>}

package/src/run/failureReason.js

@@ -0,0 +1,77 @@
+import { homedir } from 'node:os';
+import { redactSecrets } from './secretScan.js';
+
+/** The server stores a run's reason as `stateReason` and the dashboard shows it. */
+export const MAX_REASON_CHARS = 400;
+
+/**
+ * Token shapes the upload scan does not cover, because they are not refused
+ * there: any `gt_` or `sk-` token and a bearer header value. A reason is
+ * diagnostics, so these are replaced rather than refused.
+ */
+const EXTRA_PATTERNS = [
+  { type: 'bearer_token', regex: /\bbearer\s+[A-Za-z0-9._~+/=-]{4,2048}/gi },
+  { type: 'ravensight_token', regex: /\bgt_[A-Za-z0-9_-]{4,256}/g },
+  { type: 'api_key', regex: /\bsk-[A-Za-z0-9_-]{4,256}/g }
+];
+
+/** A home directory in a path: macOS, Linux and Windows. */
+const HOME_PATHS = [
+  /\/Users\/[^/\s'"`]+/g,
+  /\/home\/[^/\s'"`]+/g,
+  /\b[A-Za-z]:[\\/]+Users[\\/]+[^\\/\s'"`]+/gi
+];
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * The text with token-like strings and absolute home paths taken out, safe to
+ * send to the server as a run's reason.
+ *
+ * @param {string} text
+ * @param {{home?: string}} [options]
+ * @returns {string}
+ */
+export function redactReason(text, { home = homedir() } = {}) {
+  let out = redactSecrets(text);
+  for (const { type, regex } of EXTRA_PATTERNS) out = out.replace(regex, `[redacted ${type}]`);
+  if (home && home.length > 1) out = out.replace(new RegExp(escapeRegExp(home), 'g'), '~');
+  for (const pattern of HOME_PATHS) out = out.replace(pattern, '~');
+  return out;
+}
+
+/**
+ * The reason a failed run is reported with: the detail it already has, or else
+ * the caught error's message, redacted and cut to 400 characters. Never empty.
+ *
+ * @param {unknown} error
+ * @param {{detail?: string, fallback?: string, home?: string}} [options]
+ * @returns {string}
+ */
+export function failureReason(error, { detail = '', fallback = 'the run stopped on an error', home } = {}) {
+  const message = error && typeof error === 'object' && 'message' in error ? error.message : error;
+  const raw = String(detail || '').trim() || (message == null ? '' : String(message).trim());
+  const text = redactReason(raw, home === undefined ? {} : { home }).trim().slice(0, MAX_REASON_CHARS);
+  return text || fallback;
+}
+
+/**
+ * The reason a run whose game or browser could not start is reported with:
+ * what failed, the redacted message, and what to do about it. The message is
+ * cut first, so the instruction always survives the 400 character limit.
+ *
+ * @param {string} driverName
+ * @param {unknown} error
+ * @param {{detail?: string, browserFix?: string, home?: string}} [options]
+ * @returns {string}
+ */
+export function driverStartReason(driverName, error, { detail = '', browserFix = 'npx playwright install chromium', home } = {}) {
+  const browser = driverName === 'playwright_web';
+  const what = browser ? 'the browser could not start' : driverName === 'godot_driver' ? 'Godot could not start' : `the ${driverName} driver could not start`;
+  const todo = browser ? `run ${browserFix}` : 'run "ravensight-playtest check" to see what is missing';
+  const room = MAX_REASON_CHARS - what.length - todo.length - 4;
+  const message = failureReason(error, { detail, fallback: 'no error message', ...(home === undefined ? {} : { home }) }).slice(0, Math.max(0, room)).trim();
+  return `${what}: ${message}; ${todo}`;
+}