incanto 0.57.0 → 0.59.0

package/README.md

@@ -6,7 +6,8 @@ rule is JSON an AI agent can read, diff, and rewrite — rendered by three.js.
 ## Start with a whole game
 
 ```bash
-bunx incanto-new my-game        # Beacon Isle — the flagship 3D template
+bunx incanto new my-game        # Beacon Isle — the flagship 3D template
+bunx incanto new my-2d --template platformer-2d   # the 2D flagship
 cd my-game && bun install && bun run dev
 ```
 
@@ -20,8 +21,9 @@ rest declared in JSON. `bun run verify` plays the entire quest **headlessly**
 and replays recorded input bit-identically: the agent loop is author → verify →
 fix, no browser needed.
 
-`bunx incanto-new --list` shows the other starters (third-person shooter,
-quest vignette).
+`bunx incanto new --list` shows all five starters, grouped by dimension: three
+3D (island adventure, third-person shooter, quest vignette) and two 2D
+(platformer, survivors-like).
 
 ## Or wire the engine yourself
 
@@ -76,7 +78,7 @@ in a world full of them). In code: `physics.debugDraw = true` + `physics.debugSc
 
 ## The agent8 asset library
 
-`bunx incanto-editor --token <v8 access token>` (or `INCANTO_V8_TOKEN`) adds a
+`bunx incanto editor --token <v8 access token>` (or `INCANTO_V8_TOKEN`) adds a
 **📚** button to every field that takes a resource — model, texture, sprite
 sheet, sound. Shelves, search, real previews (a GLB is rendered by the engine
 itself), and one pick writes the URL, or the scene `assets{}` entry plus its

package/bin/incanto-check.mjs

@@ -14,6 +14,7 @@
  * each scene file.
  */
 import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -87,6 +88,15 @@ function missingArt(file, json) {
       join(sceneDir, '..', rel),
     ];
     if (candidates.some((p) => existsSync(p))) continue;
+    // A BARE PACKAGE SPECIFIER is a bundler import, not a path — and it is the
+    // form the assets skill teaches for built-in art
+    // (`incanto/assets/items/coin.png`). A scene had no way to say "this URL
+    // arrives from the bundler": a made-up placeholder (`$KNIGHT_URL`) got
+    // flagged here as art nobody copied, and an empty string — which the loop
+    // above still skips — is rejected outright by the loader. So the honest
+    // spelling was unwritable, and every 2D example that uses built-in art
+    // warned about art that works.
+    if (resolvesAsPackageAsset(url, sceneDir)) continue;
     out.push(
       `$${key} → ${url} is not in the project ` +
         `(looked in ${relativeish(root, join(root, 'public'))}, ${relativeish(root, root)}` +
@@ -96,6 +106,23 @@ function missingArt(file, json) {
   return out;
 }
 
+/**
+ * Can this url be resolved as a file inside an installed package?
+ *
+ * `incanto/assets/items/coin.png` is what the bundler is handed and what the
+ * skills teach; if the package resolves it, the file is really there.
+ */
+function resolvesAsPackageAsset(url, from) {
+  if (url.startsWith('.') || url.startsWith('/')) return false;
+  // A bare specifier: `pkg/path` or `@scope/pkg/path`.
+  if (!/^(@[^/]+\/)?[^@/][^/]*\//.test(url)) return false;
+  try {
+    return existsSync(createRequire(join(from, 'noop.js')).resolve(url));
+  } catch {
+    return false;
+  }
+}
+
 /** Nearest ancestor with a package.json, else the scene's own directory. */
 function projectRoot(from) {
   let dir = resolve(from);

package/bin/incanto-multiplay.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * incanto-multiplay — run a real match headlessly and check the clients AGREE.
+ *
+ *   bunx incanto multiplay src/game.scene.json
+ *   bunx incanto multiplay src/game.scene.json --players 3 --seconds 8 --json
+ *
+ * A desync is the purest silent failure this engine can have: both clients
+ * run, neither errors, and they are playing different games. Nothing checked
+ * for one — the harness measured room MEMBERSHIP, so "saw p2" meant "p2 is in
+ * the room", not "p2's data arrived", and a game whose replication was
+ * completely dead reported exactly what a working one did.
+ *
+ * WHAT THIS PROVES, AND WHAT IT DOES NOT. Every client runs against one
+ * in-memory server: no latency, no loss, no reordering. So this measures the
+ * APPLY path and the protocol shape, and says nothing about a live wire — a
+ * reconnect that never re-joins, a throttle that discards a payload, a batch
+ * dropped on a closed socket.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const argv = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const i = argv.indexOf(name);
+  return i >= 0 ? argv[i + 1] : fallback;
+};
+
+if (argv.includes('--help') || argv.includes('-h')) {
+  console.log(`Usage: incanto multiplay [scene.json] [options]
+
+  --players N        clients in the match (default 2)
+  --seconds N        simulated seconds (default 5)
+  --seed N           make the match reproducible (default 1)
+  --behaviors FILE   your Behavior subclasses (.ts works on bun / node >= 23.6)
+  --scenes a=b.json  a scene a NetworkSpawner names, repeatable
+  --no-late-join     skip the late-joining client
+  --json             machine-readable report
+
+Checks that every client holds the SAME value for every replicated key, plus
+one client that joins AFTER the match settles — the only observer that reads
+the authoritative snapshot fresh, and so the only one that can see a value
+erased from it.`);
+  process.exit(0);
+}
+
+const named = argv.find((a) => !a.startsWith('-') && a.endsWith('.json'));
+if (!named) {
+  console.error('incanto-multiplay: name the scene, e.g. src/game.scene.json');
+  process.exit(2);
+}
+const scenePath = resolve(named);
+if (!existsSync(scenePath)) {
+  console.error(`no such scene: ${scenePath}`);
+  process.exit(1);
+}
+
+const { playMultiplayer, multiplayText, registerAllNodes } = await import(
+  pathToFileURL(join(PKG, 'dist', 'test.js')).href
+);
+registerAllNodes();
+
+const sceneJson = JSON.parse(readFileSync(scenePath, 'utf-8'));
+const sceneDir = dirname(scenePath);
+
+// Without the game's own behaviours a scene that names one throws
+// `Unknown behavior` before a single frame runs — so load them when we are
+// given them, and stub what is left. A stubbed behaviour still lets the
+// SCENE's replication run, which is what this command measures.
+const behaviorsFile = flag('--behaviors', null);
+if (behaviorsFile) {
+  try {
+    const mod = await import(pathToFileURL(resolve(behaviorsFile)).href);
+    const { registerBehavior, Behavior } = await import(
+      pathToFileURL(join(PKG, 'dist', 'index.js')).href
+    );
+    for (const [name, value] of Object.entries(mod)) {
+      if (typeof value === 'function' && value.prototype instanceof Behavior) {
+        registerBehavior(name, value, { replace: true });
+      }
+    }
+  } catch (e) {
+    console.error(`could not load --behaviors '${behaviorsFile}' (${e?.message ?? e}).`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Scenes a `NetworkSpawner` names.
+ *
+ * `--scenes remote-player=src/remote.scene.json` is explicit; otherwise every
+ * spawner's `scene` prop is looked for as a sibling file, which is where the
+ * templates put them. A spawner whose scene cannot be found materialises
+ * nothing, and the agreement check reports that as `missing` rather than
+ * letting it read as "this game has no remote players".
+ */
+const scenes = {};
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] !== '--scenes') continue;
+  const [key, file] = String(argv[i + 1] ?? '').split('=');
+  if (key && file) scenes[key] = JSON.parse(readFileSync(resolve(sceneDir, file), 'utf-8'));
+}
+const spawnerScenes = new Set();
+const walk = (node) => {
+  if (node?.type === 'NetworkSpawner' && typeof node.props?.scene === 'string') {
+    spawnerScenes.add(node.props.scene);
+  }
+  for (const child of node?.children ?? []) walk(child);
+};
+walk(sceneJson.root);
+for (const name of spawnerScenes) {
+  if (scenes[name]) continue;
+  for (const guess of [`${name}.scene.json`, `${name}.json`]) {
+    const at = resolve(sceneDir, guess);
+    if (existsSync(at)) {
+      scenes[name] = JSON.parse(readFileSync(at, 'utf-8'));
+      break;
+    }
+  }
+}
+
+let report;
+try {
+  report = await playMultiplayer({
+    scene: sceneJson,
+    scenes,
+    players: Number(flag('--players', 2)) || 2,
+    seconds: Number(flag('--seconds', 5)) || 5,
+    seed: Number(flag('--seed', 1)) || 1,
+    lateJoin: !argv.includes('--no-late-join'),
+    load: {
+      stubMissingBehaviors: true,
+      resolveScene: (p) => JSON.parse(readFileSync(resolve(sceneDir, p), 'utf-8')),
+    },
+    // Move the owner, or every replicated key holds its authored value and two
+    // motionless clients agree about nothing in particular.
+    drive: (player, frame) => {
+      const root = player.engine.scene?.root;
+      const owner = root && findOwner(root);
+      if (!owner || !Array.isArray(owner.position)) return;
+      const spin = (player.account.charCodeAt(1) || 1) * 0.7;
+      owner.position = owner.position.map((v, i) =>
+        i === 1 && owner.position.length === 3 ? v : Math.sin(frame / 20 + spin + i) * 4,
+      );
+    },
+  });
+} catch (e) {
+  console.error(`multiplay failed: ${e?.message ?? e}`);
+  process.exit(1);
+}
+
+/** The single `network.mode === 'owner'` node, the way the manager finds it. */
+function findOwner(node) {
+  if (node.network?.mode === 'owner') return node;
+  for (const child of node.children ?? []) {
+    const found = findOwner(child);
+    if (found) return found;
+  }
+  return null;
+}
+
+if (argv.includes('--json')) {
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+} else {
+  process.stdout.write(`${multiplayText(report)}\n`);
+}
+process.exit(report.ok ? 0 : 1);

package/bin/incanto-new.mjs

@@ -2,9 +2,9 @@
 /**
  * incanto-new — scaffold a ready-to-run incanto game from a shipped template:
  *
- *   bunx incanto-new my-game                       # Beacon Isle (3D flagship)
- *   bunx incanto-new my-game --template tps-3d     # third-person shooter
- *   bunx incanto-new --list
+ *   bunx incanto new my-game                       # Beacon Isle (3D flagship)
+ *   bunx incanto new my-game --template tps-3d     # third-person shooter
+ *   bunx incanto new --list
  *
  * Copies the template, names the package after the directory, prints the
  * three commands that get you playing. Templates are real npm consumers —
@@ -19,11 +19,25 @@ const TEMPLATES_DIR = join(PKG, 'templates-app');
 
 const DESCRIPTIONS = {
   'beacon-isle-3d':
-    '3D island action-adventure (the flagship): generated world, quest NPC, terrain-nav enemies, melee',
-  'village-quest-3d': '3D quest vignette: dialogue, scene transitions, patrol AI, sword combat',
+    'island action-adventure (the 3D flagship): generated world, quest NPC, terrain-nav enemies, melee',
+  'village-quest-3d': 'quest vignette: dialogue, scene transitions, patrol AI, sword combat',
   'tps-3d': 'third-person arena shooter: GLB soldier, hitscan rifle, enemy waves',
+  'platformer-2d':
+    'side-scrolling platformer (the 2D flagship): tilemap level, coyote-time jump, follow cam, coins',
+  'star-survivor':
+    'survivors-like: waves that never stop, auto-attack, upgrades, a clock to outlast',
 };
 
+/**
+ * Which half of the engine a starter belongs to.
+ *
+ * The list was three templates, all 3D, printed in one alphabetical column —
+ * while the engine shipped a whole 2D half with its own nodes, physics,
+ * tilemaps and skill. Someone building a 2D game read that list and concluded
+ * there was nothing for them.
+ */
+const DIMENSION = (name) => (name.endsWith('-2d') || name === 'star-survivor' ? '2d' : '3d');
+
 function listTemplates() {
   if (!existsSync(TEMPLATES_DIR)) return [];
   return readdirSync(TEMPLATES_DIR, { withFileTypes: true })
@@ -34,9 +48,17 @@ function listTemplates() {
 
 const argv = process.argv.slice(2);
 if (argv.includes('--list') || argv.includes('-l')) {
-  for (const t of listTemplates()) {
-    console.log(`  ${t.padEnd(20)} ${DESCRIPTIONS[t] ?? ''}`);
+  const all = listTemplates();
+  for (const [dim, heading] of [
+    ['3d', '3D'],
+    ['2d', '2D'],
+  ]) {
+    const group = all.filter((t) => DIMENSION(t) === dim);
+    if (group.length === 0) continue;
+    console.log(`\n  ${heading}`);
+    for (const t of group) console.log(`    ${t.padEnd(20)} ${DESCRIPTIONS[t] ?? ''}`);
   }
+  console.log('\n  bunx incanto new my-game --template <name>   (default: beacon-isle-3d)\n');
   process.exit(0);
 }
 

package/bin/incanto-playtest.mjs

@@ -78,9 +78,35 @@ if (args.behaviors) {
   try {
     mod = await import(pathToFileURL(resolve(args.behaviors)).href);
   } catch (e) {
+    const why = e?.message ?? String(e);
+    // NODE CANNOT IMPORT THE PATTERN WE TEACH. Every template's behaviors.ts
+    // does `import gameJson from './game.scene.json'` — the documented way to
+    // read your own scene — and node's type stripping refuses a JSON import
+    // without `with { type: 'json' }`. Vite is fine with it, bun is fine with
+    // it, and this bin's shebang is node, so `--behaviors` failed on the
+    // engine's own flagship template. Hand the work to bun rather than telling
+    // the author their file is wrong: it is not.
+    const nodeCannotReadIt = /import attribute|Unknown file extension/i.test(why);
+    if (nodeCannotReadIt && !process.versions.bun && !process.env.INCANTO_BUN_REEXEC) {
+      const { spawnSync } = await import('node:child_process');
+      const hasBun = spawnSync('bun', ['--version'], { stdio: 'ignore' }).status === 0;
+      if (hasBun) {
+        const here = fileURLToPath(import.meta.url);
+        const again = spawnSync('bun', [here, ...process.argv.slice(2)], {
+          stdio: 'inherit',
+          env: { ...process.env, INCANTO_BUN_REEXEC: '1' },
+        });
+        process.exit(again.status ?? 1);
+      }
+    }
     console.error(
-      `could not load --behaviors '${args.behaviors}' (${e?.message ?? e}). ` +
-        'Pass the file that exports your Behavior subclasses, e.g. src/behaviors.ts.',
+      `could not load --behaviors '${args.behaviors}' (${why}).` +
+        (nodeCannotReadIt
+          ? '\n\nThis is node refusing your file, not a problem with it: node cannot' +
+            "\nimport JSON from a .ts module without `with { type: 'json' }`, and every" +
+            '\nincanto template imports its scene that way. Run it with bun, which' +
+            '\nreads the file as written: `bunx incanto playtest <scene> --behaviors <file>`.'
+          : '\nPass the file that exports your Behavior subclasses, e.g. src/behaviors.ts.'),
     );
     process.exit(1);
   }

package/bin/incanto-verify.mjs

@@ -19,8 +19,8 @@
  * what to arrange, and says so in the summary.
  */
 import { spawnSync } from 'node:child_process';
-import { existsSync, readdirSync, statSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -35,18 +35,21 @@ const flag = (name) => {
   return i >= 0 ? argv[i + 1] : null;
 };
 if (argv.includes('--help') || argv.includes('-h')) {
-  console.log(`Usage: incanto-verify [scene.json] [--behaviors FILE] [--json]
+  console.log(`Usage: incanto verify [scene.json] [--behaviors FILE] [--json]
 
 Walks the whole ladder and tells you the ONE thing to do next:
 
   loads   the scene is legal and every asset resolves       (incanto-check)
   plays   a seeded run can actually finish it               (incanto-playtest)
+  feels   the sounds and effects it declares actually fired (engine.audio/effects)
+  agrees  two clients hold the same replicated values       (incanto-multiplay)
   draws   the GPU drew something and the subject is in shot (incanto-frame)
   says    the running game logs no errors and lost no assets (incanto-logs)
 
 Without a scene it looks for one *.scene.json under the current directory.
-"draws" needs a dev server with the page open; without one it is reported as
-NOT MEASURED rather than failed — a missing measurement is not a broken game.`);
+"draws" needs a dev server with the page open, and "agrees" needs a scene with
+a "multiplayer" header; without either they are reported as NOT MEASURED rather
+than failed — a missing measurement is not a broken game.`);
   process.exit(0);
 }
 
@@ -102,7 +105,34 @@ if (!existsSync(scene) || !statSync(scene).isFile()) {
   process.exit(1);
 }
 
-const behaviors = flag('--behaviors');
+/**
+ * Find the file that holds the game's Behavior subclasses.
+ *
+ * The scene was auto-discovered from the start; the behaviours were not, and
+ * without them a playtest runs the STRUCTURE with every script stubbed. On the
+ * engine's own flagship template that means the quest never advances, so bare
+ * `incanto-verify` — the exact command the README prints — reported `plays` as
+ * a failure and told the reader to re-run a different tool by hand, with the
+ * path to a file sitting right next to the scene it had already found.
+ */
+function findBehaviors(sceneFile) {
+  const named = flag('--behaviors');
+  if (named) return { file: named, guessed: false };
+  const near = dirname(sceneFile);
+  for (const dir of [near, join(near, '..'), process.cwd(), join(process.cwd(), 'src')]) {
+    for (const base of ['behaviors', 'behaviours']) {
+      for (const ext of ['.ts', '.js', '.mjs']) {
+        const candidate = join(dir, base + ext);
+        if (existsSync(candidate) && statSync(candidate).isFile()) {
+          return { file: candidate, guessed: true };
+        }
+      }
+    }
+  }
+  return { file: null, guessed: false };
+}
+
+const { file: behaviors, guessed: guessedBehaviors } = findBehaviors(scene);
 const rungs = [];
 
 // ---- loads ---------------------------------------------------------------
@@ -145,25 +175,61 @@ if (rungs[0].status === 'pass') {
   // walkabout template has no end, and calling that a failure sends its author
   // hunting a bug that was never there.
   const noGoal = out && out.declaresWin === false;
+  // A quest — talk to the NPC, clear the enemies, light the wards — cannot be
+  // finished by a random walker, ever. Reporting that as a FAILED rung means
+  // the headline command permanently says NOT verified about a correct game,
+  // which teaches its author to stop reading it. If every run played to the
+  // end of its budget without erroring, falling or wedging, the rung has not
+  // failed: it has not measured, and the author's own scripted harness is what
+  // can judge this game.
+  // Three of the five outcomes are GAMEPLAY, not defects. `won`, `lost` and
+  // `unfinished` all mean the game ran; a random player dying half the time in
+  // a platformer is the hazards working. The defects are `error` (a behaviour
+  // threw), `fell` (left the world) and `stuck` (went nowhere), and those are
+  // what this rung is for.
+  const PLAYED = new Set(['won', 'lost', 'unfinished']);
+  const playedOut =
+    out && (out.runs?.length ?? 0) > 0 && out.runs.every((x) => PLAYED.has(x.outcome));
+  const tally = (name) => out?.runs?.filter((x) => x.outcome === name).length ?? 0;
   rungs.push(
     r.status === 0
       ? { name: 'plays', status: 'pass', summary: `${won} of ${total} seeded runs finished it` }
-      : noGoal
+      : playedOut
         ? {
             name: 'plays',
             status: 'unmeasured',
-            summary: `nothing declares a win — ${total} runs played without error, and there was no end to reach`,
-            fix: 'if it is meant to be finishable, emit `won` (GameFlow, ScoreKeeper, or your own behaviour)',
-          }
-        : {
-            name: 'plays',
-            status: 'fail',
             summary:
-              total > 0 ? `no run finished it (${total} tried)` : 'the playtest could not run',
-            fix: behaviors
-              ? `see which runs stalled and where: \`incanto-playtest ${scene} --behaviors ${behaviors}\``
-              : `run it with your behaviours — without them the structure plays and your game logic does not: \`incanto-playtest ${scene} --behaviors src/behaviors.ts\``,
-          },
+              `${total} runs played without reaching a win` +
+              ` (${[
+                tally('lost') && `${tally('lost')} lost`,
+                tally('unfinished') && `${tally('unfinished')} ran out the clock`,
+              ]
+                .filter(Boolean)
+                .join(', ')})`,
+            fix: 'nothing here is broken — a win that takes skill or a sequence is out of reach of random play. Judge it with a scripted run: `bun run verify`, or `runScript` from `incanto/test`',
+          }
+        : noGoal
+          ? {
+              name: 'plays',
+              status: 'unmeasured',
+              summary: `nothing declares a win — ${total} runs played without error, and there was no end to reach`,
+              fix: 'if it is meant to be finishable, emit `won` (GameFlow, ScoreKeeper, or your own behaviour)',
+            }
+          : {
+              name: 'plays',
+              status: 'fail',
+              summary:
+                total > 0
+                  ? `no run finished it (${total} tried)`
+                  : // "could not run" with no reason is the tool doing to its
+                    // reader exactly what this whole ladder exists to prevent:
+                    // reporting a failure it already knows the cause of. The
+                    // child printed one; pass it on.
+                    `the playtest could not run — ${firstLine(r.stderr) || `exit ${r.status}`}`,
+              fix: behaviors
+                ? `see which runs stalled and where: \`incanto-playtest ${scene} --behaviors ${behaviors}\``
+                : `run it with your behaviours — without them the structure plays and your game logic does not: \`incanto-playtest ${scene} --behaviors src/behaviors.ts\``,
+            },
   );
 } else {
   rungs.push({ name: 'plays', status: 'skipped', summary: 'not run — the scene does not load' });
@@ -211,6 +277,67 @@ if (rungs[0].status === 'pass') {
   }
 }
 
+// ---- agrees --------------------------------------------------------------
+// A desync is the purest silent failure this engine has: both clients run,
+// neither errors, and they are playing different games. Skipped outright for a
+// single-player game, because a rung that always passes is decoration.
+{
+  const isMultiplayer = (() => {
+    try {
+      const doc = JSON.parse(readFileSync(scene, 'utf-8'));
+      return Boolean(doc?.multiplayer);
+    } catch {
+      return false;
+    }
+  })();
+  if (!isMultiplayer) {
+    rungs.push({
+      name: 'agrees',
+      status: 'skipped',
+      summary: 'not run — this scene has no `multiplayer` header',
+    });
+  } else {
+    const args = [scene, '--json', '--seconds', '4'];
+    if (behaviors) args.push('--behaviors', behaviors);
+    const r = run('multiplay', args);
+    const out = safeJson(r.stdout);
+    if (!out) {
+      rungs.push({
+        name: 'agrees',
+        status: 'unmeasured',
+        summary: `the match could not run — ${firstLine(r.stderr) || `exit ${r.status}`}`,
+        fix: `see it in full: \`incanto multiplay ${scene}\``,
+      });
+    } else if (out.keysCompared === 0) {
+      // Nothing moved, so nothing was compared. Saying "pass" here is how a
+      // rung becomes decorative.
+      rungs.push({
+        name: 'agrees',
+        status: 'unmeasured',
+        summary: 'no owner node declared any sync keys, so agreement was not tested',
+        fix: 'give the player node `network: { mode: "owner", sync: ["position"] }`',
+      });
+    } else if (out.ok) {
+      rungs.push({
+        name: 'agrees',
+        status: 'pass',
+        summary:
+          `${out.keysCompared} replicated value(s) match across clients` +
+          `${out.lateJoinChecked ? ' and a late joiner' : ''}` +
+          ' — over one in-memory server, not a live wire',
+      });
+    } else {
+      const first = out.disagreements?.[0];
+      rungs.push({
+        name: 'agrees',
+        status: 'fail',
+        summary: first ? first.summary : (out.problems?.[0] ?? 'the clients disagreed'),
+        fix: `every disagreement: \`incanto multiplay ${scene}\``,
+      });
+    }
+  }
+}
+
 // ---- draws ---------------------------------------------------------------
 {
   const r = run('frame', ['--json']);
@@ -298,7 +425,16 @@ function firstLine(text) {
 }
 
 const verdict = ladderVerdict(rungs);
-console.log(asJson ? JSON.stringify({ scene, ...verdict }, null, 2) : ladderText(verdict));
+if (asJson) {
+  console.log(JSON.stringify({ scene, behaviors, ...verdict }, null, 2));
+} else {
+  if (guessedBehaviors) {
+    console.log(
+      `· behaviours: ${relative(process.cwd(), behaviors) || behaviors} (found, not named)`,
+    );
+  }
+  console.log(ladderText(verdict));
+}
 // `exitCode`, never `process.exit()`: stdout to a PIPE is written
 // asynchronously, and exiting discards whatever has not flushed. A --json
 // report read by another program came back truncated — silently, and only