@looop-games/cli 0.1.35 → 0.1.37

package/CHANGELOG.md

@@ -14,6 +14,25 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.37] - 2026-09-06
+
+- Windows: stopping a development or smoke stack terminates its worker descendants, releasing their ports and temporary folders.
+
+- Windows: selective test runs recognize short and long names for the same project folder, and replay export accepts destinations inside the game folder.
+
+- Test submissions with `looop test --since <base>`: ordinary checks plus explicitly triggered extended tests in `looop.tests.json`; `--list` explains selection and `--all` runs an explicit audit. Smoke stacks disable reload watchers, and module serving avoids repeated filesystem lookups within each dependency walk.
+
+## [0.1.36] - 2026-09-04
+
+### Added
+
+- **`looop dev` keeps the sessions you play.** As you play, the room hands the dev server each slice of the recording and it lands under your game's `.looop/replays/`. Watch one back by adding `?replay=<id>` to the game's URL — the id is printed to the console when the session starts. Nothing leaves your machine, and nothing is kept when the room is not a dev room.
+- **`?replay=last`** — the newest recording, resolved by the dev server, so watching the session you just played does not start with copying an id.
+- **Old recordings are swept, so a game folder stops growing forever.** When `looop dev` starts it keeps the newest **20 recordings** and up to **200 MB** per game, whichever runs out first — roughly an hour of play for a busy game — and removes the oldest past that, saying on the way up how many went. To protect one, hit **keep** on its row in the toolbox's Sessions panel; a kept recording is never swept. (It still counts toward the caps: keeping means "don't delete this", not "don't charge me for it".)
+- **`looop replay export` — a session you played, as a table you can query.** A recording holds what you PRESSED, not what happened: no position, no speed, no score is in it anywhere. So this replays the session through your own game, reads the world at every tick, and writes it down as Parquet — one row per tick per entity, one column per declared field, plus a second table of every input you sent. Running the game costs a few seconds once; every question you ask afterwards is free, in SQL, with DuckDB or pandas or anything else that reads Parquet. Measured on a real 27-second session: 279,367 rows x 443 columns in 10 seconds, 3.9 MB on disk, and a query answered in 0.02 s. Numbers come back bit-for-bit as the simulation held them. `npx looop replay export --help` for the schema, or `shared/docs/replay-export.md`.
+- **`looop replay export` tells you when the table will not be the session you played — before it spends the time building it.** A recording holds what you pressed, not what happened, so the numbers come from running your current code on old inputs. The export now compares the recording against what you are running and says up front if the engine version or the shape of your game has moved since. While it replays it also reports how many keyframes put playback back onto the recorded state, and the divergence warning no longer claims that everything after a divergence is worthless — a drift is bounded to the stretch before the next keyframe, and saying otherwise had people binning tables that were mostly fine.
+- The dev server answers the toolbox's Sessions panel — listing this game's recordings, deleting one, and pinning one. Only ever on the dev server, and deleting or pinning a recording works only from a page this dev server itself served. `looop dev` listens on every network interface so your phone can play, which means everything else on that wifi can reach it too — on a cafe or coworking network that is not a set of machines you control, and nothing there can now remove one of your sessions.
+
 ## [0.1.35] - 2026-09-02
 
 ### Added

package/bin/looop.mjs

@@ -8,6 +8,7 @@ import { lane } from '../lib/lane.mjs';
 import { login, whoami } from '../lib/login.mjs';
 import { publish } from '../lib/publish.mjs';
 import { create } from '../lib/create.mjs';
+import { parseTestArgs } from '../lib/test-policy.mjs';
 import { testCmd } from '../lib/test-cmd.mjs';
 import { lintCmd } from '../lib/lint.mjs';
 import { update } from '../lib/update.mjs';
@@ -30,12 +31,15 @@ Usage:
   looop dev [--port <n>]     Run the full dev stack (game + multiplayer + services)
   looop assets [<id>]       Browse and drive your models, sounds and assets on their own
   looop lane <name>          Open an isolated copy of the game to experiment in, safely
-  looop test                 Run the game's tests (*.test.mjs) and smokes (*.smoke.mjs)
+  looop test [aspect]        Run targeted checks (no aspect: conservative full run)
+  looop test --since <base>  Submission: ordinary + triggered extended checks
+  looop test --all           Explicit full audit; add --list to preview selection
   looop lint [--fix]         Check the game against the Looop rules (runs inside 'looop test')
   looop changelog [<v>]      What changed in the engine (default: everything newer than your pin)
   looop update [--rc <v>]    Move this game to the latest engine release (--rc <v> takes a specific pre-release)
   looop model bake <glb>     Re-bake a 3D model's server-side hit data now (normally automatic)
   looop publish [--slug <s>]  Publish this game to play.looop.games (--slug for an A/B copy)
+  looop replay export [<id>]  Turn a recorded session into a table you can query (Parquet)
   looop feedback             Send reports + replies under notes/feedback/; pull outcomes back in
   looop login                Authenticate this machine as your Looop player account
   looop logout               Forget the stored token
@@ -89,9 +93,7 @@ try {
       await create({ name: rest.find((a) => !a.startsWith('--')) });
       break;
     case 'test': {
-      // Positional args scope the run: `looop test charge` runs only files whose
-      // path contains "charge". Flags are left for future options (e.g. --changed).
-      const { ok } = await testCmd({ patterns: rest.filter((a) => !a.startsWith('--')) });
+      const { ok } = await testCmd(parseTestArgs(rest));
       process.exit(ok ? 0 : 1);
     }
     case 'lint': {
@@ -124,6 +126,23 @@ try {
       await bakeModel(glb);
       break;
     }
+    case 'replay': {
+      // `replay` is the accessor for a recorded session; `export` is its first
+      // verb. Watching one back needs no command at all — it is `?replay=<id>`
+      // on the game's URL, or the toolbox's Sessions panel.
+      const { REPLAY_HELP, replayExport, parseReplayArgs } = await import('../lib/replay-cmd.mjs');
+      // Parsed in the lib so the argv split is under test — a flag's value must
+      // never slide into the session slot, and --help must be answered before
+      // anything is read as an id.
+      const { verb, id, out, help } = parseReplayArgs(rest);
+      if (help) {
+        console.log(REPLAY_HELP);
+        break;
+      }
+      if (verb !== 'export') throw new Error(`Unknown replay command: ${verb} — try: looop replay export`);
+      await replayExport({ stream: id, out });
+      break;
+    }
     case 'publish':
       await publish({ slug: flag('slug') });
       break;

package/lib/dev.mjs

@@ -8,12 +8,14 @@
 // Multiplayer runs from minute one — the platform is not optional (the Next
 // analogy deliberately breaks there). NO_MP=1 opts out for purely-SP work.
 import { spawn } from 'node:child_process';
+import { terminateChildTree } from './process-tree.mjs';
 import { existsSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname, basename } from 'node:path';
 import { findProject } from './project.mjs';
 import { ensureEngine } from './engine.mjs';
 import { createStaticServer } from './static-server.mjs';
+import { pruneOnStart } from './replay-store.mjs';
 import { createLlmShim, DEFAULT_API_BASE } from './llm-shim.mjs';
 import { getToken, getApiBase } from './config.mjs';
 import { resolvePorts, portInUse, killPort, lanIp, isRestricted, nextBrowserSafe } from './ports.mjs';
@@ -49,7 +51,7 @@ export function partykitBin() {
 // and publish disagreed and a creator's primitive ran in production but not on
 // their own machine. One question, one answer, both commands.
 
-export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', log = console.log } = {}) {
+export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', watch = true, log = console.log } = {}) {
   const project = findProject(cwd);
   // Q4 revision: the engine is not an npm dependency — install/refresh it from
   // the platform's login-gated registry (no-op when the pinned version is in).
@@ -62,6 +64,11 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   const { ensureBaked } = await import('./model-bake.mjs');
   await ensureBaked({ dir: project.dir, log });
 
+  // Recordings accumulate on the creator's own disk — every session played
+  // under `looop dev` writes one — so the oldest go here, before anything can
+  // be watching one. The caps and the keep marker live in replay-store.mjs.
+  pruneOnStart({ projectDir: project.dir, log });
+
   // Which ports, and may we take them? An explicit --port is obeyed as given
   // (takeover included). With no flag we step around anyone else's stack —
   // another lane, another game, an unrelated app — and only ever reclaim our
@@ -106,19 +113,8 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   const ownServer = roomServerCwd !== engine.roomServerDir;
 
   const stop = () => {
-    for (const c of children) {
-      // partykit is npx-style: node wrapper forks workerd. Kill the tree.
-      try {
-        process.kill(-c.pid, 'SIGTERM');
-      } catch {
-        try {
-          c.kill('SIGTERM');
-        } catch {
-          /* gone */
-        }
-      }
-    }
     for (const s of servers) s.close();
+    for (const c of children) terminateChildTree(c);
   };
 
   // ─── static ───
@@ -153,14 +149,15 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
       { url: '/shared/', dir: overridesDir },
       { url: '/shared/', dir: engine.sharedDir },
     ],
-    watchDirs: [project.dir, engine.sharedDir],
+    watchDirs: watch ? [project.dir, engine.sharedDir] : [],
+    injectReload: watch,
     // Present only for a framework-v2 game — injects the looop import map + the
     // lowered skeleton into the entry HTML so startGame() boots in the browser.
     skeleton: roomSkeleton,
   });
   await staticServer.listen(ports.static);
   servers.push(staticServer);
-  log(`→ static      :${ports.static}  (serving ${project.dir}, engine ${engine.version}, auto-reload on)`);
+  log(`→ static      :${ports.static}  (serving ${project.dir}, engine ${engine.version}, auto-reload ${watch ? 'on' : 'off'})`);
 
   // ─── multiplayer (partykit on the bundle's room code) ───
   // A single-player framework-v2 game (no config({ multiplayer: true })) runs its
@@ -181,7 +178,7 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
     // partykit reloader below does this as a side effect; single-player needs a
     // stripped-down version with no child to respawn. (NO_MP on a real multiplayer
     // game has no client to serve a skeleton to, so it needs none.)
-    if (singlePlayer) {
+    if (singlePlayer && watch) {
       const skelWatcher = createFileWatcher({
         files: roomInputs,
         dirs: ['entities', 'components', 'overrides/shared/ui/room'].map((d) => join(project.dir, d)),
@@ -220,28 +217,27 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
       return pk;
     };
     const killMp = async (pk) => {
+      if (pk.pid == null) return;
+      // Keep ownership when termination fails so stop() can retry the tree.
+      // Child exit callbacks cannot run between these synchronous statements.
+      terminateChildTree(pk);
       const idx = children.indexOf(pk);
       if (idx !== -1) children.splice(idx, 1);
-      if (pk.pid == null) return; // never started — nothing to reap, and 'exit' will never fire
       const exited = new Promise((resolveExit) => {
         if (pk.exitCode !== null || pk.signalCode !== null) return resolveExit();
-        pk.once('exit', resolveExit);
-        pk.once('error', resolveExit);
+        const onExit = () => {
+          pk.removeListener('exit', onExit);
+          pk.removeListener('error', onExit);
+          resolveExit();
+        };
+        pk.once('exit', onExit);
+        pk.once('error', onExit);
       });
-      try {
-        process.kill(-pk.pid, 'SIGTERM');
-      } catch {
-        try {
-          pk.kill('SIGTERM');
-        } catch {
-          /* gone */
-        }
-      }
       // partykit is a node wrapper forking workerd; if the tree ignores TERM,
       // escalate — the port must be free before the replacement binds it.
       const hardKill = setTimeout(() => {
         try {
-          process.kill(-pk.pid, 'SIGKILL');
+          terminateChildTree(pk, 'SIGKILL');
         } catch {
           /* gone */
         }
@@ -309,18 +305,18 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
       },
     });
     reloader.attach(roomServerCwd, pk);
-    roomWatcher = createFileWatcher({
+    roomWatcher = watch ? createFileWatcher({
       files: roomInputs,
       dirs: ['entities', 'components', 'overrides/shared/ui/room'].map((d) => join(project.dir, d)),
       onChange: reloader.onChange,
-    });
+    }) : null;
     // stop() (e.g. `looop test` tearing down its stack) must also stop the
     // reloader: a rebuild in flight would otherwise spawn a replacement room
     // child AFTER the children list was killed — a leaked detached process.
     servers.push({
       close: () => {
         reloader.stop();
-        roomWatcher.close();
+        roomWatcher?.close();
       },
     });
   }

package/lib/inject.mjs

@@ -137,7 +137,7 @@ function fileInfo(path) {
     return null;
   }
   const hit = parseCache.get(path);
-  if (hit && hit.mtimeMs === st.mtimeMs) return hit;
+  if (hit && hit.mtimeMs === st.mtimeMs && hit.ctimeMs === st.ctimeMs && hit.size === st.size) return hit;
   const specs = [];
   if (/\.(js|mjs)$/.test(path)) {
     let text = null;
@@ -152,35 +152,48 @@ function fileInfo(path) {
       }
     }
   }
-  const info = { mtimeMs: st.mtimeMs, specs };
+  const info = { mtimeMs: st.mtimeMs, ctimeMs: st.ctimeMs, size: st.size, specs };
   parseCache.set(path, info);
   return info;
 }
 
-// Walk in URL space: each node is a URL path, mapped to bytes through the
-// server's mount table. `memo` (shared across one rewrite pass) short-circuits
-// only entry nodes — a spec repeated in one body — not intermediates.
-function closureStampUrl(urlPath, resolveUrl, memo) {
-  if (memo?.has(urlPath)) return memo.get(urlPath);
+// A rewrite shares resolved nodes across all import closures. Each URL is
+// resolved/stat'ed once even when several roots reach it. The cache belongs to
+// this synchronous rewrite only: the next request observes edits, deletions and
+// newly-created overrides immediately, without waiting for the reload watcher.
+function rewriteContext(resolveUrl) {
+  const nodes = new Map();
+  return {
+    stamps: new Map(),
+    node(url) {
+      if (!nodes.has(url)) {
+        const path = resolveUrl(url);
+        nodes.set(url, path ? fileInfo(path) : null);
+      }
+      return nodes.get(url);
+    },
+  };
+}
+
+function closureStampUrl(urlPath, context) {
+  if (context.stamps.has(urlPath)) return context.stamps.get(urlPath);
   let max = 0;
   const seen = new Set();
   const stack = [urlPath];
   while (stack.length) {
-    const u = stack.pop();
-    if (seen.has(u)) continue;
-    seen.add(u);
-    const fs = resolveUrl(u);
-    if (!fs) continue;
-    const info = fileInfo(fs);
+    const url = stack.pop();
+    if (seen.has(url)) continue;
+    seen.add(url);
+    const info = context.node(url);
     if (!info) continue;
-    if (info.mtimeMs > max) max = info.mtimeMs;
+    max = Math.max(max, info.mtimeMs);
     for (const spec of info.specs) {
-      const child = resolveSpecToUrl(spec, u);
+      const child = resolveSpecToUrl(spec, url);
       if (child) stack.push(child);
     }
   }
   const stamp = max ? Math.floor(max) : null;
-  memo?.set(urlPath, stamp);
+  context.stamps.set(urlPath, stamp);
   return stamp;
 }
 
@@ -192,28 +205,28 @@ function closureStampUrl(urlPath, resolveUrl, memo) {
 // disk-space fallback. Resolving a relative spec beside the importer on disk
 // stamps the wrong file whenever a mount shadows it (the overrides mechanism),
 // which silently re-opens the staleness hole. No serving context → no stamp.
-function versionedPath(relPath, { baseUrl, resolveUrl, allowBareRelative = false, memo }) {
+function versionedPath(relPath, { baseUrl, resolveUrl, allowBareRelative = false, context }) {
   if (!/\.(js|mjs|json)$/.test(relPath)) return null;
   if (baseUrl == null || !resolveUrl) return null;
   const urlTarget = resolveSpecToUrl(relPath, baseUrl, { allowBareRelative });
   if (!urlTarget) return null;
-  if (!resolveUrl(urlTarget)) return null; // nothing serves it — leave the spec alone
-  const stamp = closureStampUrl(urlTarget, resolveUrl, memo);
+  if (!context.node(urlTarget)) return null;
+  const stamp = closureStampUrl(urlTarget, context);
   return stamp === null ? null : `${relPath}?v=${stamp}`;
 }
 
 export function rewriteJsImports(text, { baseUrl, resolveUrl }) {
-  const memo = new Map();
+  const context = rewriteContext(resolveUrl);
   return text.replace(JS_IMPORT_RE, (whole, prefix, quote, path) => {
-    const v = versionedPath(path, { baseUrl, resolveUrl, memo });
+    const v = versionedPath(path, { baseUrl, resolveUrl, context });
     return `${prefix}${quote}${v ?? path}${quote}`;
   });
 }
 
 export function rewriteHtmlScripts(html, { baseUrl, resolveUrl }) {
-  const memo = new Map();
+  const context = rewriteContext(resolveUrl);
   return html.replace(HTML_SCRIPT_RE, (whole, prefix, path, suffix) => {
-    const v = versionedPath(path, { baseUrl, resolveUrl, allowBareRelative: true, memo });
+    const v = versionedPath(path, { baseUrl, resolveUrl, allowBareRelative: true, context });
     return `${prefix}${v ?? path}${suffix}`;
   });
 }

package/lib/process-tree.mjs

@@ -0,0 +1,30 @@
+import { execFileSync } from 'node:child_process';
+import { win32 } from 'node:path';
+
+// PartyKit owns worker descendants. Windows has no Unix process groups, so
+// killing its wrapper alone can leave a worker holding ports and directories.
+export function terminateChildTree(child, signal = 'SIGTERM', {
+  platform = process.platform, exec = execFileSync, kill = process.kill,
+} = {}) {
+  if (child.pid == null) return;
+  if (platform === 'win32') {
+    if (child.exitCode != null || child.signalCode != null) return;
+    const taskkill = win32.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'taskkill.exe');
+    try {
+      exec(taskkill, ['/PID', String(child.pid), '/T', '/F'], {
+        stdio: 'pipe', timeout: 5000, windowsHide: true,
+      });
+    } catch (error) {
+      // An already-exited child is harmless; a live tree that could not be
+      // terminated must fail shutdown rather than silently leak workers.
+      try { kill(child.pid, 0); } catch (probe) {
+        if (probe.code === 'ESRCH') return;
+      }
+      throw error;
+    }
+    return;
+  }
+  try { kill(-child.pid, signal); } catch {
+    child.kill(signal);
+  }
+}

package/lib/replay-cmd.mjs

@@ -0,0 +1,155 @@
+// `looop replay export` — the recorded session, on disk as a table.
+//
+// This is the CLI's half: find the game, resolve the engine it is pinned to,
+// hand both to the exporter, and then say enough about what came out that the
+// next step is obvious. The table's shape and every decision about it live in
+// replay-export.mjs; nothing here knows what a column is.
+import { join, relative, resolve, sep } from 'node:path';
+import { statSync } from 'node:fs';
+import { findProject } from './project.mjs';
+import { streamDir } from './replay-store.mjs';
+import { ensureEngine } from './engine.mjs';
+import { exportSession } from './replay-export.mjs';
+
+export const EXPORTS_DIR = ['.looop', 'exports'];
+
+export const REPLAY_HELP = `looop replay — work with the sessions this game has recorded
+
+Usage:
+  looop replay export [<session>] [--out <dir>]
+
+  <session>   Which recording. Defaults to the most recent one.
+  --out       Where the tables go. Defaults to .looop/exports/
+
+Writes two Parquet tables:
+
+  <session>.state.parquet    one row per tick per entity, every declared field
+                             a column (def/id/owner/tick lead)
+  <session>.inputs.parquet   one row per input the player sent
+
+A recording holds what was PRESSED, not what happened — so the export replays
+the session through your game to work out where everything was, then writes it
+down. That costs a few seconds once; every question you ask of the table
+afterwards is free.
+
+  duckdb -c "SELECT def, count(*) FROM '.looop/exports/<session>.state.parquet' GROUP BY def"
+`;
+
+/**
+ * Split `looop replay …`'s arguments into the verb, the session, and the flags.
+ *
+ * A flag's VALUE is a positional-looking word, so dropping only the tokens that
+ * start with `--` leaves `tables` from `--out tables` sitting in the session
+ * slot — and the export then reports it cannot find a recording the creator
+ * never named. The same trap is why `--help` has to be answered before any of
+ * this is used as an id.
+ */
+export function parseReplayArgs(argv = []) {
+  const flag = (name) => {
+    const i = argv.indexOf(`--${name}`);
+    return i === -1 ? undefined : argv[i + 1];
+  };
+  const positional = argv.filter((a, i) => !a.startsWith('-') && !argv[i - 1]?.startsWith('--'));
+  const [verb, id] = positional;
+  return {
+    verb,
+    id,
+    out: flag('out'),
+    help: !verb || verb === 'help' || argv.includes('--help') || argv.includes('-h'),
+  };
+}
+
+const mb = (file) => `${(statSync(file).size / 1024 / 1024).toFixed(1)} MB`;
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.cwd]
+ * @param {string} [opts.stream] - which recording; defaults to the most recent
+ * @param {string} [opts.out] - where the tables go
+ * @param {(msg: string) => void} [opts.log]
+ * @param {(dir: string, o: object) => Promise<object>} [opts.ensureEngineImpl]
+ * @param {(o: object) => Promise<object>} [opts.exportImpl]
+ */
+export async function replayExport({
+  cwd = process.cwd(), stream, out, log = console.log,
+  ensureEngineImpl = ensureEngine, exportImpl = exportSession,
+} = {}) {
+  const project = findProject(cwd);
+  // The id is about to become a path to read from AND a filename to write. Every
+  // other door into the store runs one through `streamDir`, which refuses rather
+  // than sanitizes; this one is no different for being typed by hand.
+  if (stream) streamDir(project.dir, stream);
+  const outDir = out ? resolve(project.dir, out) : join(project.dir, ...EXPORTS_DIR);
+  // The tables are tens of megabytes and this creates directories to hold them.
+  // A path that climbs out of the game folder is a typo, not an intention.
+  if (outDir !== project.dir && !outDir.startsWith(`${resolve(project.dir)}${sep}`)) {
+    throw new Error(`--out must be inside the game folder, and ${out} is not`);
+  }
+  const engine = await ensureEngineImpl(project.dir, { log });
+
+  const started = Date.now();
+  const res = await exportImpl({
+    dir: project.dir, stream, outDir, sharedDir: engine.sharedDir,
+    engineVersion: engine.version, log,
+  });
+  const secs = ((Date.now() - started) / 1000).toFixed(1);
+
+  const rel = (f) => relative(project.dir, f);
+  log(`exported ${res.stream} in ${secs}s`);
+  log(`  ${rel(res.stateFile)}   ${res.rows.toLocaleString()} rows x ${res.columns} columns  (${mb(res.stateFile)})`);
+  log(`  ${rel(res.inputFile)}  ${res.inputs.toLocaleString()} inputs  (${mb(res.inputFile)})`);
+  // Three different ways the table can describe a world that is not the one
+  // that was played. None of them is buried: an export that looks clean and is
+  // not is worse than one that failed, because the answers it gives are wrong
+  // and confident.
+  if (res.divergences) {
+    // What bounds the damage is the keyframe: the stream carries the room's
+    // complete true state roughly every 30 s, and playback restores it, so a
+    // drift owns one keyframe interval rather than everything downstream.
+    // Saying otherwise sends a reader to bin a table that was mostly fine.
+    //
+    // Only a re-anchor AFTER the last divergence says that last drift was
+    // undone; earlier ones belong to earlier drifts. And a re-anchor is recorded
+    // only when the restore actually changed the world, so zero of them does not
+    // mean nothing corrected it — a drift that came right again on its own also
+    // records none. Claiming "the drift ran to the end of the session" from a
+    // zero count states something this code cannot know.
+    const corrected = res.lastReanchorTick != null
+      && res.lastDivergenceTick != null
+      && res.lastReanchorTick > res.lastDivergenceTick;
+    const putBack = corrected
+      ? ` Playback was put back onto the recorded state at tick ${res.lastReanchorTick}, after the last of them.`
+      : ' Nothing is recorded as putting it back after the last one, so treat the rows from there to the end as this run\'s.';
+    log(`  ⚠ the replay parted from the recording ${res.divergences} time(s) — from each of those `
+      + 'ticks until the next keyframe, the rows are this run\'s world rather than the recorded one.'
+      + putBack
+      + ' The usual cause is that the game changed since the session was recorded; a replay runs '
+      + 'the code as it is now.');
+  }
+  if (res.gaps) {
+    log(`  ⚠ the recording is missing ${res.gaps} segment(s) — the inputs in those gaps were never `
+      + 'stored, so the world after each one is not the session that was played');
+  }
+  if (res.unsupported) {
+    log(`  ⚠ ${res.unsupported} recorded event(s) cannot be reproduced by a replay (a live tune, say) `
+      + '— the world after each one is not the session that was played');
+  }
+  // Repeated from before the replay. That is the right place to say it first —
+  // the answer is known and the replay is the slow part — but a big export puts
+  // screens of output in between, so the line deciding whether to trust the
+  // table would be the one line scrolled off. Costs nothing; both values are
+  // already on the result.
+  if (res.recordedEngine && res.runningEngine && res.recordedEngine !== res.runningEngine) {
+    log(`  ⚠ recorded by engine ${res.recordedEngine}, replayed on ${res.runningEngine}`);
+  }
+  if (res.codeChanged) {
+    log('  ⚠ the game has changed since this session was recorded');
+  }
+  if (res.undoubleable) {
+    log(`  note: ${res.undoubleable} numeric cell(s) held NaN or ±Infinity, which Parquet has no double `
+      + 'for, and read as null — the same as a field the entity kind does not declare');
+  }
+  log('');
+  log(`Ask it something:  duckdb -c "SELECT def, count(*) FROM '${rel(res.stateFile)}' GROUP BY def"`);
+  return res;
+}