ravensight-playtest 0.5.2 → 0.7.0

package/src/assets/measure.js

@@ -0,0 +1,392 @@
+/**
+ * What the pixels of one decoded image say: its transparency, its real pixel
+ * pitch and a guess at how it is laid out. Everything here is a measurement a
+ * person could repeat, and the layout is called a guess because that is what it is.
+ *
+ * The lessons behind these came from wiring real art into a real game:
+ * - An image described as "a 32 grid" measured 100 to 167 art pixels across, so
+ *   the pitch is measured from the pixels and nothing else is believed.
+ * - Faint alpha across the whole canvas made a trim keep the whole canvas, so
+ *   the box is reported both ways.
+ * - Tiles with their own frame draw a grid across a floor, so the edge band of a
+ *   tile is compared with its middle.
+ */
+
+/** Channel difference that still counts as the same colour when measuring runs. */
+export const RUN_TOLERANCE = 16;
+
+/** A run of 1 or 2 is an anti-aliased sliver, not an art pixel. */
+const MIN_RUN = 3;
+const MAX_RUN = 64;
+
+/** Below this there are too few runs for a near match to mean anything. */
+const MIN_SIDE_FOR_NEAR_PITCH = 64;
+
+/** Alpha at or above this counts as seen, which is half way. */
+export const ALPHA_THRESHOLD = 128;
+
+/** An image this small is treated as pixel art whatever its colours. */
+const SMALL_SIDE = 64;
+
+const MAX_COUNTED_COLOURS = 256;
+
+function emptyBox() {
+  return { minX: Infinity, minY: Infinity, maxX: -1, maxY: -1 };
+}
+
+function grow(box, x, y) {
+  if (x < box.minX) box.minX = x;
+  if (x > box.maxX) box.maxX = x;
+  if (y < box.minY) box.minY = y;
+  if (y > box.maxY) box.maxY = y;
+}
+
+function finishBox(box) {
+  return box.maxX < 0 ? null : { x: box.minX, y: box.minY, width: box.maxX - box.minX + 1, height: box.maxY - box.minY + 1 };
+}
+
+/**
+ * How transparent an image is, and the box a trim would keep two ways.
+ *
+ * @param {{width: number, height: number, rgba: Uint8Array}} image
+ * @returns {{opaque_share: number, transparent_share: number, partial_share: number, box_any: Object|null, box_threshold: Object|null}}
+ */
+export function measureAlpha({ width, height, rgba }) {
+  let opaque = 0;
+  let transparent = 0;
+  const any = emptyBox();
+  const seen = emptyBox();
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const alpha = rgba[(y * width + x) * 4 + 3];
+      if (alpha === 255) opaque += 1;
+      else if (alpha === 0) transparent += 1;
+      if (alpha > 0) grow(any, x, y);
+      if (alpha >= ALPHA_THRESHOLD) grow(seen, x, y);
+    }
+  }
+  const total = width * height;
+  return {
+    opaque_share: round(opaque / total),
+    transparent_share: round(transparent / total),
+    partial_share: round((total - opaque - transparent) / total),
+    box_any: finishBox(any),
+    box_threshold: finishBox(seen)
+  };
+}
+
+function round(value, places = 4) {
+  const scale = 10 ** places;
+  return Math.round(value * scale) / scale;
+}
+
+function greatestCommonDivisor(a, b) {
+  let x = a;
+  let y = b;
+  while (y) [x, y] = [y, x % y];
+  return x;
+}
+
+/**
+ * One direction's colour runs: the exact ones and the near-identical ones, seen
+ * pixels only. `lineStep` skips lines on a large image, which is plenty.
+ */
+function collectRuns({ width, height, rgba }, horizontal, lineStep, exact, near) {
+  const lines = horizontal ? height : width;
+  const length = horizontal ? width : height;
+  const stride = horizontal ? 4 : width * 4;
+  for (let line = 0; line < lines; line += lineStep) {
+    let at = horizontal ? line * width * 4 : line * 4;
+    let exactRun = 0;
+    let nearRun = 0;
+    let previous = -1;
+    for (let i = 0; i < length; i += 1, at += stride) {
+      if (rgba[at + 3] < ALPHA_THRESHOLD) {
+        if (exactRun) exact.set(exactRun, (exact.get(exactRun) || 0) + 1);
+        if (nearRun) near.set(nearRun, (near.get(nearRun) || 0) + 1);
+        exactRun = 0;
+        nearRun = 0;
+        previous = -1;
+        continue;
+      }
+      const hasPrevious = previous >= 0;
+      if (hasPrevious && rgba[at] === rgba[previous] && rgba[at + 1] === rgba[previous + 1] && rgba[at + 2] === rgba[previous + 2]) {
+        exactRun += 1;
+      } else {
+        if (exactRun) exact.set(exactRun, (exact.get(exactRun) || 0) + 1);
+        exactRun = 1;
+      }
+      if (hasPrevious
+        && Math.abs(rgba[at] - rgba[previous]) <= RUN_TOLERANCE
+        && Math.abs(rgba[at + 1] - rgba[previous + 1]) <= RUN_TOLERANCE
+        && Math.abs(rgba[at + 2] - rgba[previous + 2]) <= RUN_TOLERANCE) {
+        nearRun += 1;
+      } else {
+        if (nearRun) near.set(nearRun, (near.get(nearRun) || 0) + 1);
+        nearRun = 1;
+      }
+      previous = at;
+    }
+    if (exactRun) exact.set(exactRun, (exact.get(exactRun) || 0) + 1);
+    if (nearRun) near.set(nearRun, (near.get(nearRun) || 0) + 1);
+  }
+}
+
+/**
+ * The size of one art pixel in file pixels.
+ *
+ * An image upscaled cleanly has every exact colour run a multiple of one number,
+ * and that number is the answer (`exact`). Otherwise the most common run of
+ * near-identical colour is, ignoring slivers, as long as it is a real peak and
+ * leaves at least 8 art pixels across. Anything else answers 1: drawn at file
+ * resolution, or painted with no grid.
+ *
+ * @param {{width: number, height: number, rgba: Uint8Array}} image
+ * @returns {{value: number, exact: boolean, art_width: number, art_height: number}}
+ */
+export function measurePixelPitch(image) {
+  const { width, height } = image;
+  const lineStep = Math.max(1, Math.floor(Math.max(width, height) / 512));
+  const exact = new Map();
+  const near = new Map();
+  collectRuns(image, true, lineStep, exact, near);
+  collectRuns(image, false, lineStep, exact, near);
+
+  const answer = (value, isExact) => ({ value, exact: isExact, art_width: Math.round(width / value), art_height: Math.round(height / value) });
+
+  // A run that fills its whole line says nothing about the grid.
+  const lengths = [...exact.keys()].filter(length => length !== width && length !== height);
+  let divisor = 0;
+  for (const length of lengths) divisor = greatestCommonDivisor(divisor, length);
+  if (divisor > 1 && Math.min(width, height) / divisor >= 2) return answer(divisor, true);
+
+  let best = 0;
+  let bestCount = 0;
+  let total = 0;
+  for (const [length, count] of near) {
+    total += count;
+    if (length < MIN_RUN || length > MAX_RUN || length === width || length === height) continue;
+    if (count > bestCount || (count === bestCount && length < best)) {
+      best = length;
+      bestCount = count;
+    }
+  }
+  const enoughEvidence = bestCount >= Math.max(20, total * 0.02);
+  const isPeak = best > MIN_RUN || (near.get(MIN_RUN - 1) || 0) < bestCount;
+  const enoughArt = best > 0 && Math.min(width, height) >= MIN_SIDE_FOR_NEAR_PITCH && Math.min(width, height) / best >= 8;
+  return enoughEvidence && isPeak && enoughArt ? answer(best, false) : answer(1, false);
+}
+
+/** Distinct colours, stopping once there are more than a pixel artist would use. */
+function countColours({ rgba }) {
+  const seen = new Set();
+  for (let at = 0; at < rgba.length; at += 4) {
+    if (rgba[at + 3] < ALPHA_THRESHOLD) continue;
+    seen.add((rgba[at] << 16) | (rgba[at + 1] << 8) | rgba[at + 2]);
+    if (seen.size > MAX_COUNTED_COLOURS) return MAX_COUNTED_COLOURS + 1;
+  }
+  return seen.size;
+}
+
+/** How much each line varies along its own length, in brightness. */
+function lineVariation({ width, height, rgba }, vertical) {
+  const lines = vertical ? width : height;
+  const along = vertical ? height : width;
+  const step = Math.max(1, Math.floor(along / 256));
+  const out = new Float64Array(lines);
+  for (let line = 0; line < lines; line += 1) {
+    let sum = 0;
+    let squares = 0;
+    let count = 0;
+    for (let i = 0; i < along; i += step) {
+      const at = (vertical ? i * width + line : line * width + i) * 4;
+      const value = 0.299 * rgba[at] + 0.587 * rgba[at + 1] + 0.114 * rgba[at + 2];
+      sum += value;
+      squares += value * value;
+      count += 1;
+    }
+    out[line] = Math.sqrt(Math.max(0, squares / count - (sum / count) ** 2));
+  }
+  return out;
+}
+
+const GRID_COUNTS = [16, 12, 10, 8, 6, 5, 4, 3, 2];
+
+/**
+ * How many equal cells an opaque picture is cut into by gutters: lines that stay
+ * nearly one colour along their whole length, where the art around them does not.
+ * Every line of a candidate grid has to be one, and off-grid lines mostly not.
+ */
+function gutterCount(variation) {
+  const size = variation.length;
+  if (size < 16) return 1;
+  const sorted = [...variation].sort((a, b) => a - b);
+  const usual = sorted[size >> 1];
+  if (usual < 2) return 1;
+  const calm = usual * 0.6;
+  const reach = Math.max(1, Math.round(size * 0.015));
+  for (const count of GRID_COUNTS) {
+    if (size / count < 8) continue;
+    const onGrid = new Uint8Array(size);
+    let fits = true;
+    for (let k = 1; k < count && fits; k += 1) {
+      const line = Math.round((k * size) / count);
+      let lowest = Infinity;
+      for (let at = Math.max(0, line - reach); at <= Math.min(size - 1, line + reach); at += 1) {
+        onGrid[at] = 1;
+        if (variation[at] < lowest) lowest = variation[at];
+      }
+      fits = lowest <= calm;
+    }
+    if (!fits) continue;
+    let strays = 0;
+    const edge = Math.round(size * 0.03);
+    for (let at = edge; at < size - edge; at += 1) if (!onGrid[at] && variation[at] <= calm) strays += 1;
+    if (strays <= size * 0.02) return count;
+  }
+  return 1;
+}
+
+/** Spans of lines holding something seen, for finding cells split by clear gaps. */
+function seenSpans({ width, height, rgba }, horizontal) {
+  const lines = horizontal ? width : height;
+  const along = horizontal ? height : width;
+  const spans = [];
+  let start = -1;
+  for (let line = 0; line <= lines; line += 1) {
+    let seen = false;
+    if (line < lines) {
+      for (let i = 0; i < along && !seen; i += 1) {
+        const at = (horizontal ? i * width + line : line * width + i) * 4;
+        seen = rgba[at + 3] >= ALPHA_THRESHOLD;
+      }
+    }
+    if (seen && start < 0) start = line;
+    if (!seen && start >= 0) {
+      spans.push(line - start);
+      start = -1;
+    }
+  }
+  return spans;
+}
+
+/** Evenly sized spans count as cells; a stray spark next to a sprite does not. */
+function regularSpans(spans) {
+  if (spans.length < 2) return 1;
+  const largest = Math.max(...spans);
+  return spans.every(span => span >= largest * 0.6) ? spans.length : 1;
+}
+
+/**
+ * Whether a tile carries its own frame: a band at all four edges clearly lighter
+ * or darker than its middle, and which way.
+ *
+ * @returns {{framed: boolean, band: number}}
+ */
+export function measureFrame({ width, height, rgba }, cell) {
+  const band = Math.max(1, Math.round(Math.min(cell.width, cell.height) * 0.02));
+  const light = (x, y) => {
+    const at = ((cell.y + y) * width + cell.x + x) * 4;
+    return 0.299 * rgba[at] + 0.587 * rgba[at + 1] + 0.114 * rgba[at + 2];
+  };
+  const mean = (x0, y0, x1, y1) => {
+    let sum = 0;
+    let count = 0;
+    for (let y = y0; y < y1; y += 1) {
+      for (let x = x0; x < x1; x += 1) {
+        sum += light(x, y);
+        count += 1;
+      }
+    }
+    return count ? sum / count : 0;
+  };
+  const { width: w, height: h } = cell;
+  const middle = mean(Math.floor(w * 0.2), Math.floor(h * 0.2), Math.ceil(w * 0.8), Math.ceil(h * 0.8));
+  const edges = [mean(0, 0, band, h), mean(w - band, 0, w, h), mean(0, 0, w, band), mean(0, h - band, w, h)];
+  const dark = edges.every(edge => edge <= middle - 10);
+  const pale = edges.every(edge => edge >= middle + 10);
+  return { framed: dark || pale, band };
+}
+
+/**
+ * How different a tile's opposite edges are, from 0 to 1: what shows as a seam
+ * when it is laid beside itself.
+ */
+export function measureSeam({ width, rgba }, cell) {
+  let sum = 0;
+  let count = 0;
+  const pixel = (x, y) => ((cell.y + y) * width + cell.x + x) * 4;
+  const compare = (a, b) => {
+    sum += (Math.abs(rgba[a] - rgba[b]) + Math.abs(rgba[a + 1] - rgba[b + 1]) + Math.abs(rgba[a + 2] - rgba[b + 2])) / (3 * 255);
+    count += 1;
+  };
+  for (let y = 0; y < cell.height; y += 1) compare(pixel(0, y), pixel(cell.width - 1, y));
+  for (let x = 0; x < cell.width; x += 1) compare(pixel(x, 0), pixel(x, cell.height - 1));
+  return round(sum / count, 3);
+}
+
+/**
+ * A guess at the layout: one picture, one tile, a strip of frames, or a sheet.
+ *
+ * @param {{width: number, height: number, rgba: Uint8Array}} image
+ * @param {Object} alpha from measureAlpha
+ * @param {string} [relativePath] names like floor or wall tip a square opaque image towards a tile
+ * @returns {{kind: 'single'|'tile'|'strip'|'sheet', columns: number, rows: number, cell_width: number, cell_height: number, framed: boolean, seam: number|null}}
+ */
+export function guessLayout(image, alpha, relativePath = '') {
+  const { width, height } = image;
+  const opaqueEnough = alpha.opaque_share >= 0.98;
+  let columns = 1;
+  let rows = 1;
+  if (opaqueEnough) {
+    columns = gutterCount(lineVariation(image, true));
+    rows = gutterCount(lineVariation(image, false));
+  } else {
+    columns = regularSpans(seenSpans(image, true));
+    rows = regularSpans(seenSpans(image, false));
+  }
+  // Gutters one way and art the other: square cells are the likely answer.
+  if (opaqueEnough && columns > 1 && rows === 1 && height % Math.floor(width / columns) === 0) rows = height / Math.floor(width / columns);
+  else if (opaqueEnough && rows > 1 && columns === 1 && width % Math.floor(height / rows) === 0) columns = width / Math.floor(height / rows);
+  const named = /(^|[/_-])(tile|tiles|tileset|floor|wall|ground|terrain)/i.test(relativePath);
+  const cellOf = (x, y) => ({ x, y, width: Math.floor(width / columns), height: Math.floor(height / rows) });
+  const describe = kind => {
+    const out = { kind, columns, rows, cell_width: Math.floor(width / columns), cell_height: Math.floor(height / rows), framed: false, seam: null };
+    if (opaqueEnough && (kind === 'tile' || kind === 'sheet')) {
+      // A sheet reads as framed when most of its cells are.
+      let framed = 0;
+      let seam = 0;
+      for (let row = 0; row < rows; row += 1) {
+        for (let column = 0; column < columns; column += 1) {
+          const cell = cellOf(column * out.cell_width, row * out.cell_height);
+          if (measureFrame(image, cell).framed) framed += 1;
+          seam += measureSeam(image, cell);
+        }
+      }
+      out.framed = framed * 2 > columns * rows;
+      out.seam = round(seam / (columns * rows), 3);
+    }
+    return out;
+  };
+  if (columns > 1 || rows > 1) return describe('sheet');
+  if (!opaqueEnough && height >= 8 && width % height === 0 && width / height >= 2 && width / height <= 16) {
+    columns = width / height;
+    return describe('strip');
+  }
+  if (opaqueEnough && width === height && (named || width <= 128)) return describe('tile');
+  return describe('single');
+}
+
+/**
+ * Whether this reads as pixel art, which needs a nearest filter on screen.
+ *
+ * @returns {boolean}
+ */
+export function looksLikePixelArt(image, alpha, pitch, layout) {
+  if (pitch.value > 1) return true;
+  if (Math.max(image.width, image.height) <= SMALL_SIDE) return true;
+  if (layout.kind !== 'single' && Math.max(layout.cell_width, layout.cell_height) <= SMALL_SIDE) return true;
+  return alpha.partial_share < 0.01 && countColours(image) <= MAX_COUNTED_COLOURS;
+}
+
+export default { measureAlpha, measurePixelPitch, guessLayout, looksLikePixelArt, measureFrame, measureSeam };

package/src/cli.js

@@ -83,6 +83,16 @@ There is no spending flag: each run's model budget is set by the server from
 what the job was charged.
 `;
 
+/** The fix options parsed by the runner rather than declared here. */
+export const FIX_HELP = `
+Fix v2 (Labs beta), when the server reports it live for the game:
+  --open-pr                 after a verified fix, ask, then commit the fix's files, push the branch
+                            and open a pull request with the evidence report (needs gh auth status)
+  --no-labs                 run the ordinary fix even when Fix v2 is on
+  --allow-tests             let the checks run the project's tests and run on edited test files
+  --allow-tool-scripts      let the checks import edits to project.godot, addons, .godot or @tool scripts
+`;
+
 /** Flags every command shares. */
 function common(command) {
   return command
@@ -331,6 +341,7 @@ export function buildProgram() {
     .option('--branch <name>', 'the branch to create (default ravensight/fix-<label>-<hex>)')
     .option('--no-verify', 'do not replay the finding after the fix')
     .option('--allow-dirty', 'fix on top of uncommitted changes instead of refusing')
+    .addHelpText('after', FIX_HELP)
     .allowUnknownOption()
     // Unknown options' values land in command.args; without this commander
     // counts them as excess positional arguments and refuses the command.
@@ -372,6 +383,228 @@ export function buildProgram() {
       return simulateCommand(flagsFrom(options, { game: options.game, configFile: options.config, driverConfig: options.driverConfig, resume: options.resume }));
     }));
 
+  common(program.command('replay').description('play a recorded Godot persona run again with no model; free'))
+    .argument('<runId>', 'the run to replay')
+    .option('--ref <ref>', 'the commit or branch to replay it on, default HEAD')
+    .option('--job <jobId>', 'the run\'s job, to read an uploaded trace when this machine has none')
+    .option('--game <gameId>', 'the game, when this repo is not linked')
+    .option('--godot-project <dir>', 'the Godot project directory inside this repo')
+    .option('--godot-path <path>', 'where Godot is, if it is not on the PATH')
+    .option('--baseline', 'first replay on the commit the trace was recorded on, to show the game honors its seed')
+    .option('--headless', 'replay headless whatever the run was recorded in')
+    .option('--no-record', 'do not record the outcome on the job')
+    .action(capture(slot, async (runId, options) => {
+      const { replayCommand } = await import('./commands/replay.js');
+      return replayCommand(runId, flagsFrom(options, {
+        game: options.game,
+        ref: options.ref,
+        job: options.job,
+        godotProject: options.godotProject,
+        godotPath: options.godotPath,
+        baseline: Boolean(options.baseline),
+        headless: Boolean(options.headless),
+        record: options.record
+      }));
+    }));
+
+  common(program.command('feature').description('Labs beta: write a feature spec from a brief, or build an approved one on a new branch'))
+    .argument('<brief-or-spec>', 'a short brief in quotes writes a specification; a specification id builds it')
+    .option('--game <gameId>', 'the game, when this repo is not linked')
+    .option('--branch <name>', 'the branch to create (default ravensight/feature-<title>-<hex>)')
+    .addOption(new Option('--personas <list>', 'comma separated persona slugs, used in turn across the scenarios').argParser(list))
+    .option('--godot-project <dir>', 'the Godot project directory inside this repo')
+    .option('--godot-path <path>', 'where Godot is, if it is not on the PATH')
+    .option('--headless', 'play the scenarios headless: no screenshots, and no mouse or GUI input reaches the game')
+    .option('--open-pr', 'after a verified feature, ask, then commit its files, push the branch and open a pull request (needs gh auth status)')
+    .option('--allow-tests', 'let the checks run the project\'s tests and run on edited test files')
+    .option('--allow-tool-scripts', 'let the checks import edits to project.godot, addons, .godot or @tool scripts')
+    .option('--max-actions <n>', 'a lower ceiling on model turns in the apply loop')
+    .option('--assets-dir <dir>', 'the folder inside the project that holds your art and audio (default assets)')
+    .option('--alpha-3d', 'Alpha, a proof of concept: work on a project whose main scene has a 3D root')
+    .action(capture(slot, async (target, options) => {
+      const { featureCommand } = await import('./commands/feature.js');
+      return featureCommand(target, flagsFrom(options, {
+        game: options.game,
+        branch: options.branch,
+        personas: options.personas,
+        godotProject: options.godotProject,
+        godotPath: options.godotPath,
+        headless: Boolean(options.headless),
+        openPr: Boolean(options.openPr),
+        allowTests: Boolean(options.allowTests),
+        allowToolScripts: Boolean(options.allowToolScripts),
+        maxActions: options.maxActions === undefined ? undefined : Number(options.maxActions),
+        assetsDir: options.assetsDir,
+        alpha3d: Boolean(options.alpha3d)
+      }));
+    }));
+
+  common(program.command('template').description('Labs, Alpha: write the godot-3d proof of concept template into a new directory, for feature and validate with --alpha-3d'))
+    .argument('<name>', 'the template: godot-3d')
+    .requiredOption('--game <gameId>', 'the game this project reports to, with Labs on')
+    .option('--dir <path>', 'where to write it (default ./<name>)')
+    .option('--name <title>', 'the project\'s title')
+    .action(capture(slot, async (name, options) => {
+      const { templateCommand } = await import('./commands/template.js');
+      return templateCommand(name, flagsFrom(options, { game: options.game, dir: options.dir, name: options.name }));
+    }));
+
+  common(program.command('assets').description('list your art and audio with what was measured about each file; reads this machine only and sends nothing'))
+    .option('--assets-dir <dir>', 'the folder inside the project that holds your art and audio (default assets)')
+    .option('--godot-project <dir>', 'the Godot project directory inside this repo')
+    .option('--grid <n>', 'the grid you expect, in art pixels across, to warn about any file that differs')
+    .action(capture(slot, async options => {
+      const { assetsCommand } = await import('./commands/assets.js');
+      return assetsCommand(flagsFrom(options, {
+        assetsDir: options.assetsDir,
+        godotProject: options.godotProject,
+        grid: options.grid === undefined ? undefined : Number(options.grid)
+      }));
+    }));
+
+  common(program.command('create').description('Labs, Experimental: a small Godot 2D prototype from a brief, one validated milestone at a time, up to a declared count'))
+    .argument('<brief-or-plan>', 'a short brief in quotes starts a plan; a plan\'s job id carries it on after a person approved its design')
+    .option('--name <title>', 'the game\'s working title (default: the design\'s)')
+    .option('--dir <path>', 'where to create the project (default ./<title>)')
+    .option('--milestones <n>', 'how many milestones to buy at most: the run stops there', '3')
+    .addOption(new Option('--size <size>', 'the largest feature tier a milestone may be').choices(['small', 'medium', 'large']).default('medium'))
+    .addOption(new Option('--personas <list>', 'comma separated persona slugs, used in turn').argParser(list))
+    .option('--godot-path <path>', 'where Godot is, if it is not on the PATH')
+    .option('--headless', 'play headless: no screenshots, and no mouse or GUI input reaches the game')
+    .option('--allow-tool-scripts', 'let the checks import edits to project.godot, addons, .godot or @tool scripts')
+    .option('--assets-dir <dir>', 'the folder inside the project that holds your art and audio (default assets)')
+    .option('--stop', 'close the plan now: what finished stays paid for, and what never started comes back')
+    .option('--template <name>', 'godot-2d, the only template create uses: it does not make a 3D game')
+    .action(capture(slot, async (target, options) => {
+      const { createCommand } = await import('./commands/create.js');
+      return createCommand(target, flagsFrom(options, {
+        name: options.name,
+        dir: options.dir,
+        milestones: Number(options.milestones),
+        size: options.size,
+        personas: options.personas,
+        godotPath: options.godotPath,
+        headless: Boolean(options.headless),
+        allowToolScripts: Boolean(options.allowToolScripts),
+        assetsDir: options.assetsDir,
+        stop: Boolean(options.stop),
+        template: options.template
+      }));
+    }));
+
+  common(program.command('validate').description('Labs beta: play a branch and its base with personas, and compare them'))
+    .argument('[branch]', 'the branch to validate, default HEAD')
+    .option('--base <ref>', 'what to compare it with, default the repository\'s default branch')
+    .option('--runs <n>', 'persona runs a side, 1 to 10, default 3')
+    .addOption(new Option('--personas <list>', 'comma separated persona slugs, used in turn across the pairs').argParser(list))
+    .option('--extend-to <n>', 'if the first answer is too small to call, buy more runs up to this many a side')
+    .option('--game <gameId>', 'the game, when this repo is not linked')
+    .option('--godot-project <dir>', 'the Godot project directory inside this repo')
+    .option('--godot-path <path>', 'where Godot is, if it is not on the PATH')
+    .option('--concurrency <n>', 'runs at once, default 2')
+    .option('--headless', 'play headless: no screenshots, and no mouse or GUI input reaches the game')
+    .option('--fail-on-regression', 'exit 1 when the comparison reads regressed or mixed; with --hosted, on anything but matched')
+    .option('--resume <jobId>', 'carry on with an interrupted validation, with no second charge')
+    .option('--alpha-3d', 'Alpha, a proof of concept: compare commits of a project whose main scene has a 3D root')
+    .option('--hosted', 'play uploaded builds on hosted machines on one seed and compare them state by state, no personas')
+    .option('--seed <text>', 'with --hosted: the seed both builds play')
+    .option('--games <n>', 'with --hosted: games a side, 1 to 10, default 3')
+    .option('--steps <n>', 'with --hosted: the most actions a game, default 300')
+    .option('--no-wait', 'with --hosted: start it and exit; the job page shows the result')
+    .action(capture(slot, async (branch, options) => {
+      if (options.hosted) {
+        const { validateHostedCommand } = await import('./commands/validateHosted.js');
+        return validateHostedCommand(branch, flagsFrom(options, {
+          game: options.game, base: options.base, godotProject: options.godotProject, godotPath: options.godotPath,
+          seed: options.seed, games: options.games, steps: options.steps, wait: options.wait, alpha3d: Boolean(options.alpha3d),
+          failOnRegression: Boolean(options.failOnRegression)
+        }));
+      }
+      const { validateCommand } = await import('./commands/validate.js');
+      return validateCommand(branch, flagsFrom(options, {
+        game: options.game,
+        base: options.base,
+        runs: options.runs === undefined ? undefined : Number(options.runs),
+        personas: options.personas,
+        extendTo: options.extendTo === undefined ? undefined : Number(options.extendTo),
+        godotProject: options.godotProject,
+        godotPath: options.godotPath,
+        concurrency: options.concurrency === undefined ? undefined : Number(options.concurrency),
+        headless: Boolean(options.headless),
+        failOnRegression: Boolean(options.failOnRegression),
+        resume: options.resume,
+        alpha3d: Boolean(options.alpha3d)
+      }));
+    }));
+
+  // Labs lists. Each subcommand takes the shared flags itself, so `--json` and
+  // `--game` work after the subcommand name, where people type them.
+  const listFlags = command => common(command).option('--game <gameId>', 'the game, when this repo is not linked');
+  const statusOption = () => new Option('--status <status>', 'which items to show').choices(['open', 'done', 'dropped', 'all']).default('open');
+
+  const punch = common(program.command('punch')
+    .description('Labs beta: the punch list, what has to be finished before handover, closed one item at a time'));
+  listFlags(punch.command('list').description('show the punch list; free'))
+    .addOption(statusOption())
+    .action(capture(slot, async options => {
+      const { punchList } = await import('./commands/punch.js');
+      return punchList(flagsFrom(options, { game: options.game, status: options.status }));
+    }));
+  listFlags(punch.command('add').description('add one item; free, with plain-language hints'))
+    .argument('<text>', 'the item, in quotes')
+    .action(capture(slot, async (text, options) => {
+      const { punchAdd } = await import('./commands/punch.js');
+      return punchAdd(text, flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(punch.command('done').description('close an item as done; free'))
+    .argument('<itemId>', 'the item id, li_...')
+    .action(capture(slot, async (itemId, options) => {
+      const { punchClose } = await import('./commands/punch.js');
+      return punchClose(itemId, 'done', flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(punch.command('drop').description('close an item as dropped; free'))
+    .argument('<itemId>', 'the item id, li_...')
+    .action(capture(slot, async (itemId, options) => {
+      const { punchClose } = await import('./commands/punch.js');
+      return punchClose(itemId, 'dropped', flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(punch.command('draft').description('propose items from this game\'s findings and specs; one AI unit, saves nothing without --accept'))
+    .option('--accept', 'add every proposal to the punch list')
+    .action(capture(slot, async options => {
+      const { punchDraft } = await import('./commands/punch.js');
+      return punchDraft(flagsFrom(options, { game: options.game, accept: Boolean(options.accept) }));
+    }));
+
+  const tape = listFlags(program.command('tape')
+    .description('Labs beta: blue tape, small first-impression annoyances; tape "<text>" captures one'))
+    .argument('[text]', 'the annoyance, in quotes')
+    .action(capture(slot, async (text, options, command) => {
+      if (!text) {
+        command.outputHelp();
+        return ExitCode.FAILURE;
+      }
+      const { tapeAdd } = await import('./commands/tape.js');
+      return tapeAdd(text, flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(tape.command('list').description('show blue tape; free'))
+    .addOption(statusOption())
+    .action(capture(slot, async options => {
+      const { tapeList } = await import('./commands/tape.js');
+      return tapeList(flagsFrom(options, { game: options.game, status: options.status }));
+    }));
+  listFlags(tape.command('promote').description('move an item to the punch list; free'))
+    .argument('<itemId>', 'the item id, li_...')
+    .action(capture(slot, async (itemId, options) => {
+      const { tapePromote } = await import('./commands/tape.js');
+      return tapePromote(itemId, flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(tape.command('drop').description('drop an item; free'))
+    .argument('<itemId>', 'the item id, li_...')
+    .action(capture(slot, async (itemId, options) => {
+      const { tapeDrop } = await import('./commands/tape.js');
+      return tapeDrop(itemId, flagsFrom(options, { game: options.game }));
+    }));
+
   common(program.command('simulation-replay').description('verify a recorded simulation trace locally; creates no paid job'))
     .argument('<trace>', 'a selected trace.json written by simulate')
     .requiredOption('--driver-config <file>', 'local JSON-RPC executable configuration')