@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/jobs.js

@@ -0,0 +1,87 @@
+import { listJobs } from "../api/jobs.js";
+import { KINDS } from "../gen/kinds.js";
+import { fail, GEN_EXIT, needKey } from "./gen.js";
+import { ui } from "../ui.js";
+const REFUSAL = /policy|moderat|refus|rejected|safety|blocked|nsfw|invalid_input/i;
+export function tallyRefusals(jobs) {
+    const by = new Map();
+    for (const j of jobs) {
+        const row = by.get(j.tool) ?? { tool: j.tool, jobs: 0, refused: 0, broke: 0, rate: 0, codes: {} };
+        row.jobs++;
+        if (j.status === 'failed') {
+            const code = j.error?.code ?? 'unknown';
+            const said = `${code} ${j.error?.message ?? ''}`;
+            if (REFUSAL.test(said)) {
+                row.refused++;
+                row.codes[code] = (row.codes[code] ?? 0) + 1;
+            }
+            else
+                row.broke++;
+        }
+        by.set(j.tool, row);
+    }
+    return [...by.values()].map((r) => ({ ...r, rate: r.jobs ? Math.round((r.refused / r.jobs) * 1000) / 1000 : 0 })).sort((a, b) => b.rate - a.rate || b.jobs - a.jobs);
+}
+const MARK = {
+    queued: 'note', running: 'note', succeeded: 'pass', failed: 'fail', cancelled: 'skip',
+};
+const toolOf = (t) => (Object.hasOwn(KINDS, t) ? KINDS[t].tool : t);
+export async function jobs(opts, io = console) {
+    const r = { u: ui(io, 'jobs'), json: opts.json, io };
+    const limit = opts.limit === undefined ? undefined : Number(opts.limit);
+    if (limit !== undefined && !(Number.isInteger(limit) && limit >= 1 && limit <= 100)) {
+        return fail(r, new Error('--limit is a whole number from 1 to 100'));
+    }
+    const api = needKey(r);
+    if (!api)
+        return GEN_EXIT.error;
+    if (opts.refusals) {
+        const all = [];
+        let cursor = opts.cursor;
+        try {
+            for (let i = 0; i < 5; i++) {
+                const pg = await listJobs(api, { tool: opts.tool && toolOf(opts.tool), cursor, limit: limit ?? 100 });
+                all.push(...pg.jobs);
+                if (!pg.next_cursor)
+                    break;
+                cursor = pg.next_cursor;
+            }
+        }
+        catch (e) {
+            return fail(r, e);
+        }
+        const rows = tallyRefusals(all);
+        if (r.json) {
+            io.log(JSON.stringify({ ok: true, jobs: all.length, tools: rows }, null, 2));
+            return GEN_EXIT.done;
+        }
+        r.u.heading(`refusals per tool · the latest ${all.length} job(s)`);
+        for (const row of rows)
+            r.u.item(row.refused ? 'warn' : 'pass', row.tool, `${row.refused} of ${row.jobs} refused (${Math.round(row.rate * 100)}%)${Object.keys(row.codes).length ? `: ${Object.entries(row.codes).map(([c, n]) => `${c} ${n}`).join(', ')}` : ''}${row.broke ? `; ${row.broke} broke` : ''}`);
+        r.u.summary('note', 'measured on your own jobs: a route that refuses often wants generic descriptors (no names, no brands, no gore), not a different vendor\'s reputation');
+        return GEN_EXIT.done;
+    }
+    let page;
+    try {
+        page = await listJobs(api, { tool: opts.tool && toolOf(opts.tool), status: opts.status, cursor: opts.cursor, limit });
+    }
+    catch (e) {
+        return fail(r, e);
+    }
+    if (r.json) {
+        io.log(JSON.stringify({ ok: true, ...page }, null, 2));
+        return GEN_EXIT.done;
+    }
+    r.u.heading('jobs, newest first');
+    for (const j of page.jobs) {
+        const spent = j.charged_credits > 0 ? `, charged ${j.charged_credits} credit(s)` : '';
+        r.u.item(MARK[j.status], `${j.job_id} · ${j.tool}`, `${j.status}, ${j.created_at}${spent}`);
+        if (j.error)
+            r.u.line(`${j.error.code}: ${j.error.message}`, 2);
+    }
+    const same = [['--tool', opts.tool], ['--status', opts.status], ['--limit', opts.limit]]
+        .filter(([, v]) => v !== undefined).map(([f, v]) => ` ${f} ${v}`).join('');
+    const next = page.next_cursor ? ` — more: funtools jobs${same} --cursor ${page.next_cursor}` : '';
+    r.u.summary('note', `${page.jobs.length} job(s)${next}`);
+    return GEN_EXIT.done;
+}

package/dist/commands/journal.js

@@ -0,0 +1,58 @@
+import { userInfo } from 'node:os';
+import { resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { detectHost } from "../doctor/host.js";
+import { appendJournal, journalLine, readJournal } from "../memory/journal.js";
+import { ui } from "../ui.js";
+const me = () => { try {
+    return userInfo().username || 'person';
+}
+catch {
+    return 'person';
+} };
+export async function journal(opts, io = console, env = process.env, now = new Date()) {
+    const u = ui(io, 'journal');
+    const root = resolve(opts.dir ?? '.');
+    const what = opts.text?.replace(/\s+/g, ' ').trim();
+    if (!what) {
+        const all = readJournal(root);
+        if (opts.json) {
+            io.log(JSON.stringify({ entries: all }, null, 2));
+            return all.length ? EXIT.pass : EXIT.not_observed;
+        }
+        u.heading(`journal · ${all.length} entr${all.length === 1 ? 'y' : 'ies'}`);
+        if (!all.length) {
+            u.item('note', 'nothing recorded yet', 'after a change you made by hand: funtools journal "slowed the ghosts to 3.2" --why "kids lost in 20 s"');
+            return EXIT.not_observed;
+        }
+        for (const e of all.slice(-20))
+            u.line(journalLine(e).slice(2));
+        if (all.length > 20)
+            u.line(`(${all.length - 20} earlier in .funtools/journal.jsonl)`);
+        return EXIT.pass;
+    }
+    const values = {};
+    for (const pair of (opts.values ?? '').split(',').map((s) => s.trim()).filter(Boolean)) {
+        const i = pair.indexOf('=');
+        if (i < 1) {
+            u.error(`--values takes name=value pairs, got "${pair}"`, 'e.g. --values ghostSpeed=3.2,lives=4');
+            return EXIT.error;
+        }
+        values[pair.slice(0, i).trim()] = pair.slice(i + 1).trim();
+    }
+    const files = (opts.files ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    const viaAgent = detectHost(env) !== null;
+    const entry = {
+        by: opts.by?.trim() || me(), via: viaAgent ? 'agent' : 'cli', what,
+        ...(opts.why?.trim() ? { why: opts.why.replace(/\s+/g, ' ').trim() } : {}),
+        ...(files.length ? { files } : {}),
+        ...(Object.keys(values).length ? { values } : {}),
+    };
+    const saved = appendJournal(root, entry, now);
+    if (opts.json) {
+        io.log(JSON.stringify(saved, null, 2));
+        return EXIT.pass;
+    }
+    u.summary('pass', `recorded in .funtools/journal.jsonl${saved.why ? '' : ' (no --why: the next session sees what, not why)'}`);
+    return EXIT.pass;
+}

package/dist/commands/journey.js

@@ -0,0 +1,228 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { roundDir, roundsFiled } from "../play/session.js";
+import { checkJourney, JOURNEY_DIR, JOURNEY_LIMITS } from "../journey/script.js";
+import { journeyFromRound } from "../journey/from-round.js";
+import { readRun, replay, runsDir, runsOf } from "../journey/run.js";
+import { diffLines, diffRuns } from "../journey/diff.js";
+import { record } from "../journey/record.js";
+import { ui } from "../ui.js";
+export const JOURNEY_SUBCOMMANDS = ['record', 'from-play', 'replay', 'diff'];
+export const JOURNEY_DEFAULTS = { seed: 1, seconds: 120, repeat: 1 };
+const scriptPath = (root, name) => join(root, JOURNEY_DIR, `${name}.json`);
+function loadJourney(root, name, u) {
+    const file = scriptPath(root, name);
+    if (!existsSync(file)) {
+        u.error(`no journey "${name}" in ${join(root, JOURNEY_DIR)}`, 'record one (journey record <name>), take a blind round (journey from-play last <name>) or write the JSON');
+        return null;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        u.error(`${file} is not JSON: ${e.message}`);
+        return null;
+    }
+    const c = checkJourney(raw);
+    if (c.problems.length) {
+        for (const p of c.problems)
+            u.item('fail', p);
+        u.error(`${file} is not a journey yet`, 'fix the lines above');
+        return null;
+    }
+    return c;
+}
+async function save(root, j, force, u) {
+    const file = scriptPath(root, j.name);
+    if (existsSync(file) && !force) {
+        u.error(`${file} exists`, 'pick another name, or --force to replace it (its runs stay)');
+        return null;
+    }
+    const c = checkJourney(j);
+    if (c.problems.length) {
+        for (const p of c.problems)
+            u.item('fail', p);
+        u.error('the journey could not be written');
+        return null;
+    }
+    await mkdir(join(root, JOURNEY_DIR), { recursive: true });
+    await writeFile(file, JSON.stringify(j, null, 2) + '\n');
+    return file;
+}
+const markLine = (m) => {
+    const e = m.expect.map((x) => `${x.field}${x.op}${x.want} ${x.verdict === 'pass' ? 'held' : x.verdict === 'fail' ? `was ${JSON.stringify(x.got)}` : 'not read'}`);
+    const c = Object.entries(m.counters).slice(0, 6).map(([k, v]) => `${k} ${JSON.stringify(v)}`);
+    return [e.join(', '), m.state_observed ? c.join(' · ') : 'no __FPX_STATE__ here', m.moments.length ? `moments ${m.moments.join(', ')}` : '', m.page_errors.length ? `${m.page_errors.length} page error(s): ${m.page_errors[0]}` : '']
+        .filter(Boolean).join(' — ');
+};
+function printDiff(u, d, label) {
+    u.heading(`${label}: run ${d.before} → run ${d.after}${d.same_build ? ' (same build)' : ''}`);
+    if (!d.same_test)
+        u.item('warn', `not the same test: ${d.not_same.join('; ')}`, 'numbers across it do not compare');
+    const lines = diffLines(d);
+    for (const l of lines)
+        u.item('note', l);
+    u.item(lines.length ? 'note' : 'pass', lines.length ? `${d.unchanged.length} of ${d.marks.length} mark(s) unchanged` : `all ${d.marks.length} mark(s) look and count the same`);
+}
+export async function journey(opts, io = console) {
+    const u = ui(io, 'journey');
+    const root = resolve(opts.dir);
+    switch (opts.sub) {
+        case 'list': {
+            const dir = join(root, JOURNEY_DIR);
+            const names = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5)).sort() : [];
+            const rows = names.map((name) => { const last = runsOf(root, name).at(-1); const r = last ? readRun(root, name, last) : null; return { name, runs: runsOf(root, name).length, last: r ? { run: r.run, verdict: r.verdict, why: r.why, at: r.at } : null }; });
+            if (opts.json) {
+                io.log(JSON.stringify({ journeys: rows }, null, 2));
+                return EXIT.pass;
+            }
+            u.heading(`journeys · ${dir}`);
+            if (!rows.length)
+                u.item('note', 'none yet', 'journey record <name> (you play), journey from-play last <name> (the blind player\'s round), or write test/journeys/<name>.json');
+            for (const r of rows)
+                u.item(r.last ? (r.last.verdict === 'pass' ? 'pass' : r.last.verdict === 'fail' ? 'fail' : 'not_observed') : 'note', `${r.name}: ${r.runs} run(s)`, r.last ? `run ${r.last.run}: ${r.last.why}` : 'never replayed');
+            return EXIT.pass;
+        }
+        case 'record': {
+            const name = opts.args[0];
+            if (!name) {
+                u.error('no name', 'funtools journey record first-win [--viewport phone]');
+                return EXIT.error;
+            }
+            if (existsSync(scriptPath(root, name)) && !opts.force) {
+                u.error(`${scriptPath(root, name)} exists`, 'pick another name, or --force to replace it');
+                return EXIT.error;
+            }
+            const viewport = opts.viewport ?? 'desktop';
+            const r = await record({ root, viewport, orientation: opts.orientation, seed: opts.seed ?? JOURNEY_DEFAULTS.seed, seconds: opts.seconds ?? JOURNEY_DEFAULTS.seconds, note: (l) => u.item('note', l) });
+            if (typeof r === 'string') {
+                u.error(r, 'build the game first (npm run build)');
+                return EXIT.error;
+            }
+            if (!r.events) {
+                u.error('nothing was pressed: no journey written');
+                return EXIT.error;
+            }
+            const j = { name, viewport, ...(opts.orientation ? { orientation: opts.orientation } : {}), seed: opts.seed ?? JOURNEY_DEFAULTS.seed, steps: r.steps, source: `recorded ${new Date().toISOString().slice(0, 10)}, ${r.events} input events, ${r.seconds} s` };
+            const file = await save(root, j, !!opts.force, u);
+            if (!file)
+                return EXIT.error;
+            if (opts.json) {
+                io.log(JSON.stringify({ file, ...r }, null, 2));
+                return EXIT.pass;
+            }
+            u.item('pass', `${r.steps.length} steps from ${r.events} input events over ${r.seconds} s`, r.screens.length ? `screens reached: ${r.screens.join(' → ')}` : 'no __FPX_STATE__().screen to mark: add expectations to the marks by hand');
+            u.item('note', 'a drag replays as a straight line from where it went down to where it came up');
+            if (r.overlapped)
+                u.item('warn', `${r.overlapped} press(es) overlapped another: they replay one after the other`, 'a two-thumb move is written by hand as "drag … & drag …"');
+            u.line(file);
+            u.line(`next: funtools journey replay ${name}   (twice with --repeat 2 shows how much two runs differ on their own)`);
+            return EXIT.pass;
+        }
+        case 'from-play': {
+            const [which, name] = opts.args;
+            if (!which || !name) {
+                u.error('from-play <round|last> <name>', 'funtools journey from-play last first-round');
+                return EXIT.error;
+            }
+            const filed = roundsFiled(root);
+            const round = which === 'last' ? filed.at(-1) : Number(which);
+            if (!round || !existsSync(join(roundDir(root, round), 'log.jsonl'))) {
+                u.error(`no play round ${which} here`, `rounds with a log: ${filed.join(', ') || 'none'} (funtools play)`);
+                return EXIT.error;
+            }
+            const r = journeyFromRound(root, round, name, opts.seed ?? JOURNEY_DEFAULTS.seed);
+            if (typeof r === 'string') {
+                u.error(r);
+                return EXIT.error;
+            }
+            const { journey: j, cut, acts, thinned } = r;
+            const steps = j.steps;
+            const file = await save(root, j, !!opts.force, u);
+            if (!file)
+                return EXIT.error;
+            if (opts.json) {
+                io.log(JSON.stringify({ file, round, acts, steps: steps.length, cut, thinned }, null, 2));
+                return EXIT.pass;
+            }
+            u.item('pass', `round ${round}: ${steps.length} steps, a mark after ${thinned ? 'most' : 'each'} of ${acts} act(s) expecting the screen the player saw`);
+            if (thinned)
+                u.item('note', `${thinned} of ${acts + 1} marks dropped (a journey keeps ${JOURNEY_LIMITS.marks} frames): every step is kept, and so is each change of screen`);
+            if (cut)
+                u.item('note', cut);
+            u.item('note', 'the player\'s clock was held while it thought; the replay plays the acts back to back, so a mark may land earlier in the game\'s time');
+            u.line(file);
+            return EXIT.pass;
+        }
+        case 'replay': {
+            const name = opts.args[0];
+            if (!name) {
+                u.error('no name', 'funtools journey replay <name>');
+                return EXIT.error;
+            }
+            const c = loadJourney(root, name, u);
+            if (!c)
+                return EXIT.error;
+            const runs = [];
+            for (let i = 0; i < (opts.repeat ?? 1); i++) {
+                const r = await replay({ root, journey: c.journey, steps: c.steps });
+                if (typeof r === 'string') {
+                    u.error(r, 'build the game first (npm run build)');
+                    return EXIT.error;
+                }
+                runs.push(r);
+            }
+            const last = runs.at(-1);
+            const prevN = opts.against ?? (runs.length > 1 ? runs.at(-2).run : runsOf(root, name).filter((n) => n < last.run).at(-1));
+            const prev = prevN ? readRun(root, name, prevN) : null;
+            if (opts.against && !prev)
+                u.item('warn', `no run ${opts.against} of ${name} to compare against`);
+            const d = prev ? await diffRuns(prev, last, join(runsDir(root, name), String(last.run), `vs-${prev.run}`)) : null;
+            if (opts.json) {
+                io.log(JSON.stringify({ run: last, runs: runs.map((r) => r.run), diff: d }, null, 2));
+                return EXIT[last.verdict];
+            }
+            u.heading(`journey ${name} · run ${last.run} · ${last.viewport} ${last.size}${last.orientation ? ` ${last.orientation}` : ''} · seed ${last.seed} · ${last.steps} steps in ${(last.ms / 1000).toFixed(1)} s`);
+            for (const m of last.marks) {
+                const status = m.expect.some((e) => e.verdict === 'fail') ? 'fail' : m.expect.length && m.expect.every((e) => e.verdict === 'pass') ? 'pass' : m.expect.length ? 'not_observed' : 'note';
+                u.item(status, `${m.name} (after step ${m.step}, ${(m.at_ms / 1000).toFixed(1)} s)`, markLine(m));
+            }
+            for (const e of last.step_errors)
+                u.item('fail', `step ${e.n} ${e.step}`, e.error);
+            if (last.browser_lost)
+                u.item('warn', last.browser_lost, 'not evidence about the game; replay again');
+            if (d)
+                printDiff(u, d, opts.against ? `against run ${opts.against}` : runs.length > 1 ? 'two runs of this build (noise)' : 'against the last run');
+            else
+                u.item('note', 'first run: the next replay is set beside it');
+            u.line(join(runsDir(root, name), String(last.run)));
+            u.summary(last.verdict, last.why);
+            return EXIT[last.verdict];
+        }
+        case 'diff': {
+            const name = opts.args[0];
+            if (!name) {
+                u.error('no name', 'funtools journey diff <name> [a] [b]');
+                return EXIT.error;
+            }
+            const all = runsOf(root, name);
+            const [a, b] = opts.args.length >= 3 ? [Number(opts.args[1]), Number(opts.args[2])] : opts.args.length === 2 ? [Number(opts.args[1]), all.at(-1)] : [all.at(-2), all.at(-1)];
+            const ra = a ? readRun(root, name, a) : null, rb = b ? readRun(root, name, b) : null;
+            if (!ra || !rb) {
+                u.error(`need two runs of ${name}`, `runs kept: ${all.join(', ') || 'none'} (journey replay ${name})`);
+                return EXIT.error;
+            }
+            const d = await diffRuns(ra, rb, join(runsDir(root, name), String(rb.run), `vs-${ra.run}`));
+            if (opts.json) {
+                io.log(JSON.stringify(d, null, 2));
+                return EXIT.pass;
+            }
+            printDiff(u, d, `journey ${name}`);
+            u.line(join(runsDir(root, name), String(rb.run), `vs-${ra.run}`));
+            return EXIT.pass;
+        }
+    }
+}

package/dist/commands/judge.js

@@ -0,0 +1,191 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { changed, JUDGE_DIR, picturesIn, readAnswer, readPic, runs, spread } from "../judge/common.js";
+import { judgeStructure, overall, QUESTIONS, STRUCTURE_RUBRIC, structurePrompt } from "../judge/structure.js";
+import { IDENTITY_RUBRIC, identityPrompt, judgeIdentity } from "../judge/identity.js";
+import { conceptFor, MAX_VIEWS, renderedViews, subjectFor } from "../judge/sources.js";
+import { ui } from "../ui.js";
+export const JUDGE_SUBCOMMANDS = ['structure', 'identity', 'report'];
+const MODEL = /\.(glb|gltf|fbx)$/i;
+export async function judge(opts, io = console) {
+    const u = ui(io, 'judge');
+    try {
+        return opts.sub === 'report' ? report(opts, io, u) : await prepare(opts, io, u);
+    }
+    catch (e) {
+        u.error(e instanceof Error ? e.message : String(e));
+        return EXIT.error;
+    }
+}
+function expand(paths) {
+    return paths.flatMap((p) => (existsSync(p) && statSync(p).isDirectory() ? picturesIn(p) : [p]));
+}
+const LABELS = (i, prefix) => (prefix ? `${prefix}${i + 1}` : String.fromCharCode(65 + i));
+function fingerprint(files, prefix) {
+    const pics = [], missing = [], bad = [];
+    files.forEach((f, i) => {
+        const r = readPic(LABELS(i, prefix), f);
+        if ('missing' in r)
+            missing.push(r.missing);
+        else if ('bad' in r)
+            bad.push(r.bad);
+        else
+            pics.push(r);
+    });
+    return { pics, missing, bad };
+}
+function notObserved(io, u, json, why, next) {
+    if (json)
+        io.log(JSON.stringify({ ready: false, state: 'not_observed', reason: why }, null, 2));
+    else
+        u.summary('not_observed', `${why} — ${next}`);
+    return EXIT.not_observed;
+}
+async function prepare(opts, io, u) {
+    const root = resolve(opts.dir);
+    const at = (p) => resolve(p);
+    let plan;
+    let concept;
+    if (opts.sub === 'structure') {
+        const all = expand(opts.positionals.map(at));
+        if (!all.length)
+            return notObserved(io, u, opts.json, 'no picture to judge', 'funtools judge structure <picture|folder> [--prompt "what it should be"]');
+        const files = spread(all, MAX_VIEWS);
+        const { pics, missing, bad } = fingerprint(files, '');
+        if (bad.length) {
+            u.error(bad[0], 'give PNG, JPEG or WebP pictures');
+            return EXIT.error;
+        }
+        if (!pics.length)
+            return notObserved(io, u, opts.json, missing[0] ?? 'no picture to judge', 'name a picture that exists');
+        const subject = opts.prompt ?? (pics.length === 1 ? subjectFor(root, pics[0].file) : null);
+        plan = { kind: 'structure', rubric: STRUCTURE_RUBRIC, subject, pictures: pics, left_out: all.length - files.length + missing.length };
+    }
+    else {
+        const model = opts.positionals.length === 1 && MODEL.test(opts.positionals[0]) ? at(opts.positionals[0]) : null;
+        const views = model ? renderedViews(root, model) : { dir: '', files: spread(expand(opts.positionals.map(at)), MAX_VIEWS) };
+        const conceptFile = opts.concept ? at(opts.concept) : model ? conceptFor(root, model) : null;
+        if (!conceptFile)
+            return notObserved(io, u, opts.json, 'no concept image to hold the views to', 'pass --concept <the picture it was made from>');
+        const c = readPic('CONCEPT', conceptFile);
+        if ('bad' in c) {
+            u.error(c.bad, 'the concept is a PNG, JPEG or WebP picture');
+            return EXIT.error;
+        }
+        if ('missing' in c)
+            return notObserved(io, u, opts.json, c.missing, 'pass --concept <the picture it was made from>');
+        concept = c;
+        if (!views.files.length) {
+            return notObserved(io, u, opts.json, model ? `no rendered views of ${opts.positionals[0]} in ${views.dir}` : 'no views to judge', model ? `render them first (headless, no browser): funtools model --local render ${opts.positionals[0]} (your Blender, free) or funtools model render ${opts.positionals[0]} (hosted)` : 'name the view pictures or their folder');
+        }
+        const { pics, missing, bad } = fingerprint(views.files, 'V');
+        if (bad.length) {
+            u.error(bad[0], 'views are PNG, JPEG or WebP pictures');
+            return EXIT.error;
+        }
+        if (!pics.length)
+            return notObserved(io, u, opts.json, missing[0] ?? 'no views', 'name view pictures that exist');
+        const medium = opts.medium === 'model' || opts.medium === 'sprites' ? opts.medium : model || pics.some((p) => /turn_\d+|view_/.test(p.file)) ? 'model' : 'sprites';
+        plan = { kind: 'identity', rubric: IDENTITY_RUBRIC, medium, concept, pictures: pics, left_out: missing.length };
+    }
+    const n = (runs(root).at(-1) ?? 0) + 1;
+    const out = join(root, JUDGE_DIR, String(n));
+    await mkdir(out, { recursive: true });
+    const seat = join(out, 'seat.md'), answer = join(out, 'answer.json');
+    const text = plan.kind === 'structure' ? structurePrompt(plan.pictures, plan.subject ?? null, answer) : identityPrompt(concept, plan.pictures, plan.medium, answer);
+    await writeFile(seat, text);
+    const full = { n, at: new Date().toISOString(), ...plan, seat, answer };
+    await writeFile(join(out, 'plan.json'), JSON.stringify(full, null, 2) + '\n');
+    if (opts.json) {
+        io.log(JSON.stringify({ ready: true, dir: out, ...full }, null, 2));
+        return EXIT.pass;
+    }
+    u.heading(`judge ${n} · ${plan.kind} · ${plan.pictures.length} ${plan.kind === 'structure' ? 'picture(s)' : `view(s) of a ${plan.medium === 'model' ? 'model' : 'sprite set'}`}`);
+    if (plan.kind === 'structure')
+        u.item(plan.subject ? 'note' : 'warn', 'subject', plan.subject ?? 'no description: counts are judged against what the subject plainly is (--prompt names it)');
+    else
+        u.item('note', 'concept', concept.file);
+    for (const p of plan.pictures)
+        u.line(`${p.label}: ${p.file}`, 2);
+    if (plan.left_out)
+        u.item('warn', `${plan.left_out} picture(s) not in this seat (missing, or past the ${MAX_VIEWS} a seat reads)`);
+    u.item('note', 'seat', `one seat on your own agent reads ${plan.pictures.length + (concept ? 1 : 0)} picture(s); run it in a fresh agent handed only ${seat}, then \`funtools judge report\``);
+    u.summary('pass', 'ready — no model called');
+    return EXIT.pass;
+}
+const CODE = { pass: EXIT.pass, fail: EXIT.fail, not_observed: EXIT.not_observed };
+function report(opts, io, u) {
+    const root = resolve(opts.dir);
+    const n = opts.positionals[0] ? Number(opts.positionals[0]) : runs(root).at(-1);
+    if (!n || !existsSync(join(root, JUDGE_DIR, String(n), 'plan.json'))) {
+        u.summary('not_observed', n ? `no judge run ${n} here` : 'no judge run here yet — funtools judge structure|identity first');
+        return EXIT.not_observed;
+    }
+    const plan = JSON.parse(readFileSync(join(root, JUDGE_DIR, String(n), 'plan.json'), 'utf8'));
+    const { answer, problem } = readAnswer(plan.answer);
+    if (!answer) {
+        if (opts.json)
+            io.log(JSON.stringify({ n, kind: plan.kind, state: 'not_observed', reason: problem }, null, 2));
+        else
+            u.summary('not_observed', `the seat's answer: ${problem} (${plan.answer}) — nothing passed`);
+        return EXIT.not_observed;
+    }
+    const stale = plan.pictures.filter(changed).map((p) => p.label);
+    if (plan.kind === 'structure') {
+        const v = judgeStructure(plan.pictures, answer);
+        for (const p of v.pictures)
+            if (stale.includes(p.image)) {
+                p.state = 'not_observed';
+                p.findings = [];
+            }
+        v.state = overall(v.pictures.map((p) => p.state));
+        if (opts.json) {
+            io.log(JSON.stringify({ n, kind: plan.kind, rubric: plan.rubric, stale, ...v }, null, 2));
+            return CODE[v.state];
+        }
+        u.heading(`judge ${n} · structure · ${plan.subject ?? 'no description'}`);
+        for (const p of v.pictures) {
+            u.item(p.state, `${p.image} ${p.file}`, stale.includes(p.image) ? 'changed since the seat judged it: judge it again' : p.seen);
+            for (const f of p.findings) {
+                if (f.answer === 'no')
+                    u.line(`${f.question}: NO — ${f.evidence}`, 2);
+                else if (f.answer === 'unseen')
+                    u.line(`${f.question}: not counted (${f.why})`, 2);
+            }
+        }
+        u.summary(v.state, v.state === 'fail' ? 'a structural no: fix or regenerate the named part — no score buys it back'
+            : v.state === 'pass' ? `built right on all ${QUESTIONS.length} questions (structure only; says nothing about the look)` : 'not every question was answered with evidence — nothing passed');
+        return CODE[v.state];
+    }
+    const conceptStale = !!plan.concept && changed(plan.concept);
+    const v = judgeIdentity(plan.pictures.filter((p) => !stale.includes(p.label)), answer);
+    if (conceptStale || (stale.length && v.state === 'pass'))
+        v.state = 'not_observed';
+    if (opts.json) {
+        io.log(JSON.stringify({ n, kind: plan.kind, rubric: plan.rubric, medium: plan.medium, concept: plan.concept?.file, stale, concept_changed: conceptStale, ...v }, null, 2));
+        return CODE[v.state];
+    }
+    u.heading(`judge ${n} · identity · ${plan.pictures.length} view(s) against ${plan.concept?.file}`);
+    if (conceptStale)
+        u.item('not_observed', 'the concept changed since the seat judged it: judge again');
+    if (v.features.length)
+        u.item('note', 'key features', v.features.join(' · '));
+    for (const t of v.traits) {
+        const seen = t.levels.filter((l) => l.level !== 'unseen').length;
+        u.item(t.state, t.trait, !t.worst ? (t.trait === 'features' && !v.features.length ? 'the seat listed no key features from the concept' : 'no view showed it')
+            : t.worst.level === 'none' ? `holds in all ${seen} view(s) that show it` : `worst ${t.worst.level} in ${t.worst.view} (${t.worst.file}): ${t.worst.evidence}`);
+        for (const [k, xs] of [['lost', t.lost], ['gained', t.gained], ['changed', t.changed]]) {
+            if (xs.length)
+                u.line(`${k}: ${xs.slice(0, 8).join('; ')}${xs.length > 8 ? `; +${xs.length - 8} more (--json)` : ''}`, 2);
+        }
+    }
+    for (const s of stale)
+        u.item('not_observed', `${s} changed since the seat judged it`);
+    for (const s of v.unanswered)
+        u.item('not_observed', `${s}: no answer`);
+    u.summary(v.state, v.state === 'fail' ? 'major drift from the concept: regenerate from the concept or fix the named part'
+        : v.state === 'pass' ? `holds the concept on every trait${v.traits.some((t) => t.state === 'warn') ? ' (minor drift said above)' : ''}` : 'not every trait was seen with evidence — nothing passed');
+    return CODE[v.state];
+}