@funpixel/tools 0.0.0-stage → 0.1.0

package/dist/commands/progress.js

@@ -0,0 +1,537 @@
+import { appendFileSync, existsSync, readFileSync, statSync, mkdirSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep, isAbsolute } from 'node:path';
+import { EXIT } from "./verify.js";
+import { CAPTURE_INDEX } from "./look.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { readPipeline, evaluate, worldRead, TIER_STAGES } from "../pipeline/pipeline.js";
+import { appendEntry, autonomyOf, closedNotesSince, effectiveBudget, FORK_KINDS, heartbeatsOn, minutes, nextCard, nextQuestion, parseDuration, readProgress, unheard, unpickedNotes, } from "../progress/progress.js";
+import { answerQuestion } from "../progress/answers.js";
+import { notify } from "../progress/notify.js";
+import { handBackHolds, holdMessage } from "../progress/holds.js";
+import { apiOptions, sendJson } from "../api/http.js";
+import { apiKey } from "../keys/store.js";
+import { beat } from "../flow/flow.js";
+import { judgedLine } from "./flow.js";
+import { ui } from "../ui.js";
+import { assetCounts, countsLine } from "../assets/counts.js";
+export const PROGRESS_SUBCOMMANDS = ['status', 'card', 'heartbeat', 'ask', 'answer', 'wait', 'report'];
+const PRE_INIT = new Set(['card', 'heartbeat', 'status']);
+export const SERVED_URL = join('.funtools', 'progress-url');
+const T = 'npx @funpixel/tools';
+const trimTo = (s, n) => (s.length <= n ? s : `${s.slice(0, s.lastIndexOf(' ', n) > n * 0.6 ? s.lastIndexOf(' ', n) : n).replace(/[\s,.;:]+$/, '')}…`);
+const list = (s) => (s ?? '').split(/\s*;\s*/).map((x) => x.trim()).filter(Boolean);
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+export async function progress(opts, io = console) {
+    const u = ui(io, 'progress');
+    const root = resolve(opts.dir ?? '.');
+    if (!existsSync(join(root, 'funpixel.json'))) {
+        if (!existsSync(root) || !statSync(root).isDirectory()) {
+            u.error(`${root} is not a folder`, '--dir <game>');
+            return EXIT.error;
+        }
+        if (!PRE_INIT.has(opts.sub)) {
+            u.error(`${root} is not a game folder yet (no funpixel.json)`, `before init: ${[...PRE_INIT].join(', ')}; the rest after \`${T} init\``);
+            return EXIT.error;
+        }
+    }
+    const now = opts.now ?? (() => new Date());
+    try {
+        if (opts.sub === 'card' || opts.sub === 'heartbeat' || opts.sub === 'ask')
+            beat(root, 'work', { now: now() });
+        switch (opts.sub) {
+            case 'card': return await card(root, opts, u, io, now(), 'stage');
+            case 'heartbeat': return await card(root, opts, u, io, now(), 'heartbeat');
+            case 'ask': return await ask(root, opts, u, io, now());
+            case 'answer': {
+                const [q, pick, ...words] = opts.args;
+                if (!q || !pick) {
+                    u.error('answer needs a question and an option', `${T} progress answer Q1 <option> ["words"]`);
+                    return EXIT.error;
+                }
+                const a = answerQuestion(root, q, pick, { words: words.join(' '), now: now() });
+                const st = readProgress(root).questions.find((x) => x.id === q);
+                if (opts.json)
+                    io.log(JSON.stringify(a, null, 2));
+                else
+                    u.summary('pass', `${q} → ${pick}${st.state === 'reversed' ? ' (reverses the default taken without you)' : ''}; the agent hears it at its next card`);
+                return EXIT.pass;
+            }
+            case 'wait': return await wait(root, opts, u, io, now);
+            case 'report': return await report(root, opts, u, io, now());
+            default: return status(root, opts, u, io, now());
+        }
+    }
+    catch (e) {
+        u.error(e.message);
+        return EXIT.error;
+    }
+}
+const PLAYABLE = new Set(TIER_STAGES.deep.slice(TIER_STAGES.deep.indexOf('slice')));
+function stageNow(root, given) {
+    if (given)
+        return given;
+    const p = readPipeline(root);
+    if (p) {
+        try {
+            const c = evaluate(root, p, null).current;
+            if (c)
+                return c.stage.id;
+        }
+        catch { }
+    }
+    return readProgress(root).last?.stage ?? 'build';
+}
+async function frameOf(root, given) {
+    const index = readJson(join(root, CAPTURE_INDEX));
+    let file = given;
+    if (given === 'last') {
+        const newest = Object.values(index ?? {}).filter((x) => x?.file && existsSync(x.file)).sort((a, b) => String(b.at ?? '').localeCompare(String(a.at ?? '')))[0];
+        if (!newest)
+            return { error: `no capture yet: run \`${T} capture\` (the built game) first, then --shot last` };
+        file = newest.file;
+    }
+    const abs = isAbsolute(file) ? file : resolve(root, file);
+    if (!abs.startsWith(root + sep))
+        return { error: `${file} is outside the game folder: frames are kept in the game (capture writes .funtools/capture/)` };
+    if (!existsSync(abs) || !statSync(abs).isFile())
+        return { error: `${file} does not exist` };
+    const rel = relative(root, abs).split(sep).join('/');
+    const entry = Object.values(index ?? {}).find((x) => x?.file && resolve(x.file) === abs);
+    if (entry) {
+        const fp = entry.fingerprint ? (await fingerprint(root).catch(() => null))?.fingerprint ?? null : null;
+        return { frame: { path: rel, source: 'capture', current: fp && entry.fingerprint ? fp === entry.fingerprint : null } };
+    }
+    if (rel.startsWith('.funtools/'))
+        return { frame: { path: rel, source: 'funtools', current: null } };
+    return { frame: { path: rel, source: 'picture' } };
+}
+async function evidenceOf(root, given) {
+    const abs = resolve(root, given);
+    if (!abs.startsWith(root + sep) || !existsSync(abs))
+        return { says: given, backed: false };
+    const rel = relative(root, abs).split(sep).join('/');
+    if (/(^|\/)verify(\.webkit)?\.json$/.test(rel)) {
+        const v = readJson(abs);
+        const fp = (await fingerprint(root).catch(() => null))?.fingerprint;
+        const fresh = v?.fingerprint && fp ? v.fingerprint === fp : null;
+        const checks = Array.isArray(v?.report?.checks) ? `, ${v.report.checks.filter((c) => c?.passed || c?.verdict === 'pass').length}/${v.report.checks.length} checks` : '';
+        return { path: rel, says: `verify ${String(v?.verdict ?? 'unknown')}${checks}${fresh === false ? ' (on an older build)' : fresh ? ' on the current files' : ''}`, backed: v?.verdict === 'pass' || v?.verdict === 'fail' };
+    }
+    return { path: rel, says: `see ${rel}`, backed: true };
+}
+export function settleDefaults(root, now) {
+    if (autonomyOf(root) !== 'go')
+        return [];
+    const s = readProgress(root);
+    const due = s.open.filter((q) => q.default !== undefined && q.due !== null && q.due <= now.getTime());
+    for (const q of due) {
+        answerQuestion(root, q.id, q.default, { by: 'default', now });
+        const after = readProgress(root);
+        appendEntry(root, {
+            type: 'card', n: nextCard(after), at: now.toISOString(), kind: 'decided', stage: q.stage,
+            line: `Decided without you: ${q.id} → ${q.default}. Reply to reverse.`, observed: false, why_not: 'a decision, not a frame',
+            decisions: [`${q.text} → ${q.default} (the default, after ${minutes(q.timeout_ms ?? 0)} with no answer)`],
+            heard: [{ q: q.id, pick: q.default, by: 'default', at: readProgress(root).questions.find((x) => x.id === q.id).answer.at }],
+        });
+    }
+    return due;
+}
+async function notice(root, n, env) {
+    let url = null;
+    try {
+        url = readFileSync(join(root, SERVED_URL), 'utf8').trim() || null;
+    }
+    catch { }
+    return notify({ ...n, url }, env ?? process.env);
+}
+const gameName = (root) => { const m = readJson(join(root, 'funpixel.json')) ?? {}; return String(m.title ?? m.name ?? 'your game'); };
+async function card(root, opts, u, io, now, as) {
+    settleDefaults(root, now);
+    const s = readProgress(root);
+    const stage = stageNow(root, opts.stage);
+    if (as === 'stage' && !opts.line?.trim()) {
+        u.error('a card says what changed', `${T} progress card --line "the slice plays: drag swings the cradle" --shot last`);
+        return EXIT.error;
+    }
+    if (as === 'heartbeat' && !opts.tried?.trim()) {
+        u.error('a heartbeat says what was tried', `${T} progress heartbeat --tried "three camera heights; the ledge still clips" --shot last`);
+        return EXIT.error;
+    }
+    let shot, clip;
+    const whyNot = [];
+    for (const [flag, given] of [['--shot', opts.shot], ['--clip', opts.clip]]) {
+        if (!given)
+            continue;
+        const f = await frameOf(root, given);
+        if ('error' in f) {
+            u.error(f.error, flag === '--shot' ? `${T} capture, then --shot last` : 'a film of the build: hook, walk or play keep theirs under .funtools/');
+            return EXIT.error;
+        }
+        if (flag === '--shot')
+            shot = f.frame;
+        else
+            clip = f.frame;
+    }
+    const frames = [shot, clip].filter(Boolean);
+    const fromBuild = frames.some((f) => f.source !== 'picture');
+    if (frames.length && !fromBuild)
+        whyNot.push('a picture, not the built game: capture the build');
+    const ev = opts.evidence ? await evidenceOf(root, opts.evidence) : null;
+    if (ev && !ev.backed)
+        whyNot.push(`"${ev.says}" names no file in the game`);
+    const observed = fromBuild || !!ev?.backed;
+    if (!observed && !whyNot.length)
+        whyNot.push('no frame and no evidence on this card');
+    if (as === 'heartbeat' && shot && s.last?.shot?.path === shot.path && Date.parse(s.last.at) >= statSync(join(root, shot.path)).mtimeMs)
+        whyNot.push('the same frame as the last card: capture again for a fresh one');
+    const world = PLAYABLE.has(stage) ? worldRead(root, (await fingerprint(root).catch(() => null))?.fingerprint ?? null) : null;
+    const picked = unpickedNotes(root, s).map((n) => ({ id: n.id, text: n.text }));
+    const heard = unheard(s).map((a) => ({ q: a.q, pick: a.pick, by: a.by, at: a.at, ...(s.questions.find((q) => q.id === a.q)?.state === 'reversed' && a.by === 'owner' ? { reversed: true } : {}) }));
+    const claimed = opts.spent === undefined || opts.spent === 'account' ? undefined : Number(opts.spent);
+    if (claimed !== undefined && !(Number.isFinite(claimed) && claimed >= 0)) {
+        u.error(`--spent ${opts.spent}`, 'paid credits spent so far this run, a number (or `account`)');
+        return EXIT.error;
+    }
+    const account = opts.spent !== undefined || apiKey(opts.store ?? null) ? await accountSpend(root, s, opts.store ?? null) : null;
+    if (opts.spent === 'account' && account?.credits === undefined) {
+        u.error(`--spent account: ${account?.why ?? 'no key'}`, '`funtools login` (or FUNPIXEL_API_KEY), or pass the number you counted');
+        return EXIT.error;
+    }
+    const spent = account?.credits ?? claimed;
+    const mismatch = account?.credits !== undefined && claimed !== undefined && claimed !== account.credits;
+    const closed = closedNotesSince(root, s.last ? Date.parse(s.last.at) : 0);
+    const budget = effectiveBudget(root, s);
+    const beats = as === 'heartbeat' ? heartbeatsOn(s, stage) : 0;
+    let kind = as === 'heartbeat' ? (beats >= 2 ? 'stuck' : 'heartbeat') : 'stage';
+    if (kind === 'stage' && observed && frames.length && !s.cards.some((c) => c.observed && (c.shot || c.clip)))
+        kind = 'first';
+    const crossed = spent !== undefined && budget !== null && spent >= budget && !s.open.some((q) => q.kind === 'spend');
+    if (crossed)
+        kind = 'pause';
+    const n = nextCard(s);
+    const assetsNow = assetCounts(root);
+    let asks = null;
+    if (kind === 'stuck') {
+        asks = { type: 'ask', id: nextQuestion(s), at: now.toISOString(), kind: 'scope', stage, text: `Stuck on ${stage}: ${beats + 1} heartbeats on one gate (${opts.tried.trim()}). Skip it for now, cut it, or keep going?`, options: ['skip', 'cut', 'keep-going'], default: 'keep-going', timeout_ms: 10 * 60_000 };
+    }
+    else if (kind === 'pause') {
+        asks = { type: 'ask', id: nextQuestion(s), at: now.toISOString(), kind: 'spend', stage, text: `Spent ${spent} credits; the budget is ${budget}. Raise it by another step, or keep to free tools from here?`, options: ['raise', 'free-only'] };
+    }
+    const pipeNow = readPipeline(root);
+    const ownerStage = as === 'stage' && !!pipeNow?.stages.find((x) => x.id === stage)?.gates.some((g) => g.kind === 'owner');
+    const said = opts.line?.trim() || (kind === 'stuck' ? `Stuck on ${stage}` : `Still on ${stage}`);
+    const line = ownerStage ? `${judgedLine(root, (await fingerprint(root).catch(() => null))?.fingerprint ?? null, pipeNow)}. ${said}` : said;
+    const c = {
+        type: 'card', n, at: now.toISOString(), kind, stage, line,
+        ...(opts.next ? { next: opts.next.trim() } : {}),
+        ...(shot ? { shot } : {}), ...(clip ? { clip } : {}),
+        ...(ev ? { evidence: { ...(ev.path ? { path: ev.path } : {}), says: ev.says } } : {}),
+        observed, ...(whyNot.length ? { why_not: whyNot.join('; ') } : {}),
+        ...(spent !== undefined ? { spent, budget, spent_source: account?.credits !== undefined ? 'account' : 'agent' } : {}),
+        ...(mismatch ? { spent_claimed: claimed } : {}),
+        ...(closed.length ? { closed } : {}),
+        ...(account?.unlocked?.length ? { unlocked_art: account.unlocked } : {}),
+        ...(assetsNow ? { assets: { made: assetsNow.made, planned: assetsNow.planned, failed: assetsNow.failed, off_model: assetsNow.off_model, credits: assetsNow.credits, budget: assetsNow.budget } } : {}),
+        ...(opts.tried ? { tried: opts.tried.trim() } : {}),
+        ...(picked.length ? { picked } : {}), ...(heard.length ? { heard } : {}),
+        ...(list(opts.decision).length ? { decisions: list(opts.decision) } : {}),
+        ...(list(opts.out).length ? { out: list(opts.out) } : {}),
+        ...(list(opts.standin).length ? { standins: list(opts.standin) } : {}),
+        ...(asks ? { asks: asks.id } : {}),
+        ...(world ? { world: { state: world.state, says: world.says, ...(world.warns.length ? { warns: world.warns.slice(0, 6) } : {}) } } : {}),
+    };
+    if (asks)
+        appendEntry(root, asks);
+    appendEntry(root, c);
+    logStep(root, c);
+    const sent = asks ? await notice(root, { kind: 'needs-you', title: `${gameName(root)}: ${kind === 'pause' ? 'paused at the budget' : `stuck on ${stage}`}`, body: asks.text }, opts.env) : false;
+    if (opts.json) {
+        io.log(JSON.stringify({ card: c, ask: asks, notified: sent }, null, 2));
+        return EXIT.pass;
+    }
+    u.item(observed ? 'pass' : 'not_observed', `card ${n} · ${kind} · ${stage}: ${line}`, observed ? [shot && `frame ${shot.path}${shot.current === false ? ' (an earlier build)' : ''}`, clip && `clip ${clip.path}`, ev?.says].filter(Boolean).join(' · ') : `not observed: ${whyNot.join('; ')}`);
+    if (observed && whyNot.length)
+        u.item('warn', whyNot.join('; '));
+    if (world)
+        u.item(world.state === 'met' ? 'pass' : 'warn', `world: ${world.says}`, world.state === 'met' ? undefined : world.state === 'failing' ? 'the card shows it to the person; fix what it names, then funtools check --world' : 'funtools check --world (boxes, grounding, life) before the person plays it; funtools walk for a route');
+    if (mismatch)
+        u.item('warn', `spend: the account says ${account.credits} credits since ${account.from.slice(0, 16)}; you claimed ${claimed}`, 'the card carries the account\'s number; count from `funtools usage`, never from your own tally');
+    else if (spent !== undefined && account?.credits === undefined)
+        u.item('note', `spend ${spent} credits is your own count, not the account's${account?.why ? ` (${account.why})` : ''}`, '`funtools login` lets the card read the account');
+    if (account?.unlocked?.length)
+        u.item('warn', `${account.unlocked.length} picture(s) this run were drawn to no locked sheet: ${account.unlocked.slice(0, 6).join(', ')}`, 'pass the game_id (its locked sheets ride by default; pin them with create_game or generate_batch `lock`) or `references`');
+    if (assetsNow)
+        u.item(assetsNow.off_model.length ? 'warn' : 'note', countsLine(assetsNow), assetsNow.off_model.length ? `listed on the card: ${assetsNow.off_model.join(', ')} still drift from their cast master after one edit and one redraw — \`${T} judge identity\` names the features, or regen with the fix` : undefined);
+    for (const x of closed)
+        u.item('pass', `note ${x.id} closed${x.forced ? ' by the owner' : ''}: before ${x.before ?? '(no frame)'} → after ${x.after ?? '(no frame)'}`);
+    for (const p of picked)
+        u.item('warn', `picked up the owner's note ${p.id}: "${p.text}"`, `act on it; \`${T} note close ${p.id} --evidence <frame|sha|test>\` when it is done`);
+    for (const h of heard)
+        u.item('note', `heard ${h.q} → ${h.pick}${h.by === 'default' ? ' (the default)' : h.reversed ? ' (the person reversed your default)' : ' (the person)'}`);
+    if (asks)
+        u.item('warn', `${asks.id} (${asks.kind}) asks the person: ${asks.text}`, kind === 'pause' ? 'no paid calls until they answer; free work goes on' : `under autonomy go the default (${asks.default}) lands in 10 min: \`${T} progress wait ${asks.id}\` in the background`);
+    for (const q of readProgress(root).open.filter((q) => q.id !== asks?.id))
+        u.item('note', `${q.id} (${q.kind}) still waits: ${q.text.slice(0, 100)}`);
+    u.summary(observed ? 'pass' : 'not_observed', `card ${n} posted${sent ? '; the person was notified' : ''}`);
+    return EXIT.pass;
+}
+function logStep(root, c) {
+    const lines = [
+        ...(c.kind === 'heartbeat' ? [] : [{ kind: 'step', text: `${c.kind === 'stuck' ? 'stuck: ' : ''}${c.line}`, stage: c.stage, card: c.n, ...(c.shot || c.clip ? { evidence: (c.clip ?? c.shot).path } : {}), ...(c.observed ? {} : { observed: false }) }]),
+        ...(c.decisions ?? []).map((d) => ({ kind: 'decision', text: d, stage: c.stage, card: c.n })),
+    ];
+    if (!lines.length)
+        return;
+    const file = join(root, '.funtools', 'devlog.jsonl');
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, lines.map((l) => JSON.stringify({ at: c.at.replace(/\.\d+Z$/, 'Z'), ...l })).join('\n') + '\n');
+}
+async function ask(root, opts, u, io, now) {
+    const text = opts.args.join(' ').replace(/\s+/g, ' ').trim();
+    const kind = opts.kind;
+    if (!FORK_KINDS.includes(kind)) {
+        u.error(opts.kind ? `--kind ${opts.kind} is not a fork` : 'which fork?', `--kind taste|spend|scope; anything else is yours to decide: put it on the next card as --decision "…" (or \`${T} decide\`)`);
+        return EXIT.error;
+    }
+    if (!text) {
+        u.error('ask what?', `${T} progress ask "Keep the noon palette or try dusk?" --kind taste --options noon,dusk --default noon --timeout 10m`);
+        return EXIT.error;
+    }
+    const options = (opts.options ?? '').split(',').map((x) => x.trim()).filter(Boolean);
+    if (options.length < 2) {
+        u.error('a fork has two or more options', '--options a,b');
+        return EXIT.error;
+    }
+    if (opts.default !== undefined && !options.includes(opts.default)) {
+        u.error(`--default ${opts.default} is not one of the options`, `--options ${options.join(',')}`);
+        return EXIT.error;
+    }
+    const timeout = opts.timeout === undefined ? (opts.default !== undefined ? 10 * 60_000 : null) : parseDuration(opts.timeout);
+    if (timeout === null && opts.timeout !== undefined) {
+        u.error(`--timeout ${opts.timeout}`, '--timeout 10m (s, m or h)');
+        return EXIT.error;
+    }
+    const s = readProgress(root);
+    if (s.dropped) {
+        u.error('the owner dropped this game', 'nothing more is asked or built');
+        return EXIT.fail;
+    }
+    const a = { type: 'ask', id: nextQuestion(s), at: now.toISOString(), kind, text, options, ...(opts.default !== undefined ? { default: opts.default } : {}), ...(timeout ? { timeout_ms: timeout } : {}), stage: stageNow(root, opts.stage) };
+    appendEntry(root, a);
+    const sent = await notice(root, { kind: 'needs-you', title: `${gameName(root)} needs you (${kind})`, body: `${text}\nOptions: ${options.join(' / ')}${a.default ? ` (default ${a.default} in ${minutes(timeout)})` : ''}` }, opts.env);
+    const auto = autonomyOf(root);
+    if (opts.json) {
+        io.log(JSON.stringify({ ask: a, autonomy: auto, notified: sent }, null, 2));
+        return EXIT.pass;
+    }
+    u.item('warn', `${a.id} (${kind}): ${text}`, `options ${options.join(' / ')}${a.default ? `; default ${a.default}` : ''}`);
+    const how = auto === 'go'
+        ? a.default ? `autonomy go: keep working; \`${T} progress wait ${a.id}\` in the background takes ${a.default} at ${minutes(timeout)} if the person has not answered, and the card says "decided without you"` : 'autonomy go, and no default: work on what does not depend on it; the answer lands at your next card'
+        : `autonomy ${auto}: park this branch and work on others; if nothing else can move, \`${T} progress wait ${a.id} --for 15m\` (time-boxed; never end the session on it)`;
+    u.summary('pass', `${a.id} asked${sent ? '; the person was notified' : ''} — ${how}`);
+    return EXIT.pass;
+}
+async function wait(root, opts, u, io, base) {
+    const real = Date.now(), from = base().getTime();
+    const now = () => new Date(from + Date.now() - real);
+    const id = opts.args[0];
+    const start = now().getTime();
+    const auto = autonomyOf(root);
+    const forMs = opts.for !== undefined ? parseDuration(opts.for) : null;
+    if (opts.for !== undefined && forMs === null) {
+        u.error(`--for ${opts.for}`, '--for 15m');
+        return EXIT.error;
+    }
+    const target = (s) => s.questions.filter((q) => (id ? q.id === id : true));
+    const first = target(readProgress(root));
+    if (id && !first.length) {
+        u.error(`no question ${id}`, `${T} progress lists them`);
+        return EXIT.error;
+    }
+    const watching = new Set(first.filter((q) => q.state === 'open').map((q) => q.id));
+    if (!watching.size) {
+        u.summary('not_observed', id ? `${id} is already ${first[0].state}: ${first[0].answer?.pick}` : 'no open question');
+        return EXIT.not_observed;
+    }
+    const notesAt = new Set(unpickedNotes(root, readProgress(root)).map((n) => n.id));
+    const dues = [...watching].map((q) => first.find((x) => x.id === q).due).filter((d) => d !== null);
+    const deadline = start + (forMs ?? (auto === 'go' && dues.length ? Math.max(0, Math.max(...dues) - start) + 1000 : 15 * 60_000));
+    for (;;) {
+        const t = now();
+        const decided = settleDefaults(root, t).filter((q) => watching.has(q.id));
+        const s = readProgress(root);
+        const answered = s.questions.filter((q) => watching.has(q.id) && q.state !== 'open');
+        if (answered.length) {
+            if (opts.json)
+                io.log(JSON.stringify({ event: 'answered', questions: answered.map((q) => ({ id: q.id, pick: q.answer.pick, by: q.answer.by, words: q.answer.words ?? null })) }));
+            else
+                for (const q of answered)
+                    u.item(q.answer.by === 'default' ? 'note' : 'pass', `${q.id} → ${q.answer.pick}`, q.answer.by === 'default' ? `decided without the person (autonomy go, ${minutes(q.timeout_ms ?? 0)} with no answer); the card says so and they can reverse it` : `the person${q.answer.words ? `: "${q.answer.words}"` : ''}`);
+            if (!opts.json)
+                u.summary('pass', decided.length ? 'the default stands until the person reverses it; carry on' : 'act on the answer; your next card says you heard it');
+            return EXIT.pass;
+        }
+        const note = unpickedNotes(root, s).find((n) => !notesAt.has(n.id));
+        if (note) {
+            if (opts.json)
+                io.log(JSON.stringify({ event: 'note', note }));
+            else
+                u.summary('pass', `a note from the person came in while waiting: ${note.id} [${note.stage}] "${note.text}" — the next card picks it up`);
+            return EXIT.pass;
+        }
+        if (t.getTime() >= deadline) {
+            const open = s.questions.filter((q) => watching.has(q.id));
+            if (opts.json)
+                io.log(JSON.stringify({ event: 'timeout', open: open.map((q) => q.id), autonomy: auto }));
+            else
+                u.summary('not_observed', `${open.map((q) => q.id).join(', ')} still open after ${minutes(t.getTime() - start)} — ${open.some((q) => q.kind === 'spend') ? 'paused for paid work: keep to free work and say so' : 'park this branch and keep working on others; the page keeps the question'}. Never end the session on a wait.`);
+            return EXIT.not_observed;
+        }
+        await new Promise((r) => setTimeout(r, opts.every ?? 2000));
+    }
+}
+export function buildReport(root, now = new Date()) {
+    const s = readProgress(root);
+    const last = [...s.cards].reverse().find((c) => c.observed && (c.shot || c.clip)) ?? s.lastObserved;
+    const cuts = s.questions.filter((q) => q.kind === 'scope' && (q.answer?.pick === 'cut' || q.answer?.pick === 'skip')).map((q) => `${q.stage}: ${q.answer.pick} (${q.id}, ${q.answer.by === 'default' ? 'the default' : 'the person'})`);
+    const latest = (pick) => [...new Set(s.cards.flatMap((c) => pick(c) ?? []))];
+    const graybox = (() => { try {
+        return readFileSync(join(root, '.funtools', 'graybox'), 'utf8').split('\n').map((x) => x.trim()).filter(Boolean);
+    }
+    catch {
+        return [];
+    } })();
+    const spentCard = [...s.cards].reverse().find((c) => c.spent !== undefined);
+    return {
+        game: gameName(root), cards: s.cards.length,
+        span: s.cards.length ? minutes((s.cards.at(-1) ? Date.parse(s.cards.at(-1).at) : now.getTime()) - Date.parse(s.cards[0].at)) : null,
+        plays: last ? { card: last.n, line: last.line, frame: (last.clip ?? last.shot)?.path ?? null, evidence: last.evidence?.says ?? null } : null,
+        out: [...latest((c) => c.out), ...cuts],
+        standins: [...latest((c) => c.standins), ...graybox],
+        decidedWithout: s.questions.filter((q) => q.answers.some((a) => a.by === 'default')).map((q) => ({ q: q.id, text: q.text, pick: q.answer.pick, default: q.default ?? null, reversed: q.state === 'reversed' })),
+        open: s.open.map((q) => ({ q: q.id, kind: q.kind, text: q.text })),
+        unobserved: s.cards.filter((c) => !c.observed && c.kind !== 'decided' && c.kind !== 'waiting' && c.kind !== 'done').map((c) => ({ card: c.n, line: c.line, why: c.why_not ?? 'no frame' })),
+        notes: s.cards.flatMap((c) => (c.picked ?? []).map((p) => `${p.id} (card ${c.n}): ${p.text}`)),
+        spent: spentCard?.spent ?? null, budget: effectiveBudget(root, s),
+    };
+}
+async function report(root, opts, u, io, now) {
+    settleDefaults(root, now);
+    const r = buildReport(root, now);
+    if (!r.cards) {
+        u.summary('not_observed', `no cards yet: the hand-back has nothing to stand on (\`${T} progress card\`)`);
+        return EXIT.not_observed;
+    }
+    const s = readProgress(root);
+    const h = handBackHolds(root, (await fingerprint(root).catch(() => null))?.fingerprint ?? null, s);
+    const held = h.released ? [] : h.holds;
+    if (held.length) {
+        if (opts.json) {
+            io.log(JSON.stringify({ ...r, done: false, holds: held, waiting: h.waiting }, null, 2));
+            return EXIT.fail;
+        }
+        u.heading(`${r.game} · not done`);
+        for (const x of held)
+            u.item('fail', x.line);
+        if (h.waiting)
+            u.item('note', h.waiting);
+        u.summary('fail', holdMessage(held).split('\n').slice(-2).join(' '));
+        return EXIT.fail;
+    }
+    const already = s.last?.kind === 'done';
+    if (!already)
+        appendEntry(root, { type: 'card', n: nextCard(s), at: now.toISOString(), kind: 'done', stage: s.last?.stage ?? 'publish', line: r.plays ? `Hand-back: ${r.plays.line}` : 'Hand-back', observed: !!r.plays, ...(r.plays ? {} : { why_not: 'no card carried a frame of the build' }), ...(s.last?.shot ? { shot: s.last.shot } : {}), ...(s.last?.clip ? { clip: s.last.clip } : {}), ...(r.spent !== null ? { spent: r.spent, budget: r.budget } : {}) });
+    const sent = already ? false : await notice(root, { kind: 'done', title: `${r.game}: done`, body: `${r.plays ? `Plays: ${r.plays.line}` : 'No frame of the build on any card.'}${r.open.length ? `\n${r.open.length} question(s) still open.` : ''}` }, opts.env);
+    if (opts.json) {
+        io.log(JSON.stringify({ ...r, done: true, ...(h.holds.length ? { released: h.released, holds: h.holds } : {}), notified: sent }, null, 2));
+        return EXIT.pass;
+    }
+    u.heading(`${r.game} · ${r.cards} cards${r.span ? ` over ${r.span}` : ''}`);
+    if (h.holds.length)
+        u.item('warn', `stand-ins handed back: ${h.released}`, h.holds.map((x) => x.line).join(' · '));
+    u.item(r.plays ? 'pass' : 'not_observed', r.plays ? `what plays (card ${r.plays.card}): ${r.plays.line}` : 'what plays: no card carried a frame of the build', r.plays ? [r.plays.frame, r.plays.evidence].filter(Boolean).join(' · ') : undefined);
+    for (const o of r.out)
+        u.item('note', `out: ${o}`);
+    for (const x of r.standins)
+        u.item('warn', `stand-in: ${x}`);
+    for (const d of r.decidedWithout)
+        u.item(d.reversed ? 'note' : 'warn', d.reversed ? `taken without you, then reversed by you: ${d.q} ${trimTo(d.text, 80)} → ${d.pick} (the default was ${d.default})` : `decided without you: ${d.q} ${trimTo(d.text, 80)} → ${d.pick}; reply to reverse`);
+    for (const q of r.open)
+        u.item('warn', `still open: ${q.q} (${q.kind}) ${trimTo(q.text, 100)}`);
+    for (const x of r.unobserved)
+        u.item('not_observed', `card ${x.card} was not observed: ${x.line}`, x.why);
+    for (const n of r.notes)
+        u.item('pass', `your note ${n}`);
+    u.item('note', `cost: ${r.spent !== null ? `${r.spent} credits${r.budget !== null ? ` of ${r.budget}` : ''}` : 'no card counted credits'}`);
+    u.summary(r.plays ? 'pass' : 'not_observed', `the hand-back's spine${sent ? '; the person was notified (done)' : ''}`);
+    return EXIT.pass;
+}
+function status(root, opts, u, io, now) {
+    settleDefaults(root, now);
+    const s = readProgress(root);
+    const fresh = unheard(s), notes = unpickedNotes(root, s);
+    if (opts.json) {
+        io.log(JSON.stringify({ cards: s.cards.length, last: s.last, open: s.open, unheard: fresh, notes, autonomy: autonomyOf(root), budget: effectiveBudget(root, s) }, null, 2));
+        return s.cards.length ? EXIT.pass : EXIT.not_observed;
+    }
+    if (!s.cards.length && !s.questions.length) {
+        u.summary('not_observed', `no cards yet: the first carries a built frame (\`${T} capture\`, then \`${T} progress card --shot last --line "it boots: …"\`)`);
+        return EXIT.not_observed;
+    }
+    u.heading(`progress · ${s.cards.length} cards · autonomy ${autonomyOf(root)}`);
+    for (const c of s.cards.slice(-6))
+        u.item(c.observed ? 'pass' : c.kind === 'decided' ? 'note' : 'not_observed', `${c.n} ${c.kind} · ${c.stage}: ${c.line}`, `${minutes(now.getTime() - Date.parse(c.at))} ago`);
+    for (const q of s.open)
+        u.item('warn', `${q.id} (${q.kind}) waits: ${q.text}`, q.default ? `default ${q.default}${q.due ? (q.due > now.getTime() ? ` in ${minutes(q.due - now.getTime())}` : ' (due)') : ''}` : 'no default');
+    for (const a of fresh)
+        u.item('note', `new answer: ${a.q} → ${a.pick} (${a.by})`, 'your next card records that you heard it');
+    for (const n of notes)
+        u.item('warn', `new note from the person: ${n.id} [${n.stage}] "${n.text}"`, 'your next card picks it up');
+    u.summary('pass', s.last ? `last card ${minutes(now.getTime() - Date.parse(s.last.at))} ago` : 'questions only, no card yet');
+    return EXIT.pass;
+}
+function runStart(root, s) {
+    const first = s.cards[0]?.at ?? s.questions[0]?.at;
+    if (first)
+        return first;
+    const p = readJson(join(root, 'design', 'pipeline.json'));
+    if (typeof p?.at === 'string' && Number.isFinite(Date.parse(p.at)))
+        return p.at;
+    return new Date(Date.now() - 86_400_000).toISOString();
+}
+const PICTURE_TOOLS = new Set(['generate_image', 'generate_sprite']);
+const within = (p, ms) => Promise.race([p, new Promise((_, no) => setTimeout(() => no(new Error(`no answer in ${ms / 1000} s`)), ms).unref())]);
+export async function accountSpend(root, s, store) {
+    const from = runStart(root, s);
+    const key = apiKey(store);
+    if (!key)
+        return { from, why: 'no key: not signed in' };
+    const api = apiOptions({ key, retries: 0 });
+    if (!api)
+        return { from, why: 'no key' };
+    let credits, why, unlocked;
+    try {
+        const { json } = await within(sendJson(api, 'GET', `/v1/me/usage?from=${encodeURIComponent(from)}`), 8000);
+        if (Number.isFinite(json?.total_credits))
+            credits = json.total_credits;
+        else
+            why = 'the usage answer had no total';
+    }
+    catch (e) {
+        why = `the account could not be read: ${e instanceof Error ? e.message : String(e)}`;
+    }
+    try {
+        const { json } = await within(sendJson(api, 'GET', '/v1/jobs?limit=100'), 8000);
+        unlocked = (json?.jobs ?? [])
+            .filter((j) => PICTURE_TOOLS.has(j.tool) && j.status !== 'failed' && j.status !== 'cancelled' && Date.parse(j.created_at) >= Date.parse(from))
+            .filter((j) => !(Array.isArray(j.input?.references) && j.input.references.length))
+            .map((j) => `${j.tool} ${String(j.input?.prompt ?? '').slice(0, 40) || j.job_id.slice(0, 8)}`);
+    }
+    catch { }
+    return { from, ...(credits !== undefined ? { credits } : {}), ...(why ? { why } : {}), ...(unlocked ? { unlocked } : {}) };
+}