done-done-axi 0.3.0 → 0.3.2

package/dist/cli.js

@@ -4,7 +4,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { accessSync, appendFileSync, closeSync, constants, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir, userInfo } from 'node:os';
 import { basename, dirname, isAbsolute, join, matchesGlob, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createInterface } from 'node:readline/promises';
 import { parseArgs } from 'node:util';
 import { encode } from '@toon-format/toon';
@@ -17,7 +17,8 @@ import { attemptProblem, changedSince, commitFix, dirtyTracked, FIX_SCHEMA, inWo
 import { cellEnv, cellName, cellSuffix, hasMatrix, matrixManifest, splitMatrix } from './matrix.js';
 import { design, KINDS } from './design.js';
 import { checkMedia } from './media.js';
-import { domIssues, isDomRecord, SQUASHED_TEXT } from './dom.js';
+import { domIssues, domRecord, isDomRecord, lookIssues, SQUASHED_TEXT } from './dom.js';
+import { look } from './look.js';
 import { scanSecrets } from './secrets.js';
 const PASS = 0, FAIL = 1, USAGE = 2, INCONCLUSIVE = 3, WAITING = 4;
 // The shape of a journey, so a new user or agent can write one without opening the reference.
@@ -71,7 +72,7 @@ const DOCTOR_TEXT = `doctor changes nothing except the --probe call record (the
   optional: verify_skill (.agents/skills/verify-<app>/), agent (the agent the user set and its model; missing when none is
   set, with the command that saves the user's choice), agent_settings (agent, model, effort,
   args, path and agent_timeout, each with the file it came from: the global config, .done-done.yaml or default), judge (the judge route is ready: for claude-code an
-  executable claude binary, a sign-in folder and the judge kit, for answerer:<agent> that agent's CLI and the kit, for openai:key
+  executable claude binary and the judge kit (its sign-in is checked only when a capture is judged), for answerer:<agent> that agent's CLI and the kit, for openai:key
   OPENAI_API_KEY and the kit; doctor does not call the model; missing when none is set, with the command that saves the user's choice),
   judge_choice (the judge, and how far it is from the author: another agent, another model, or session-only), ffprobe (video evidence only).
   --probe also asks the agent one JSON-schema question (one call at the agent's model: its cheap default where it has one, else its own; set agent_config.<agent>.model to choose; its record goes to
@@ -80,8 +81,8 @@ const DOCTOR_TEXT = `doctor changes nothing except the --probe call record (the
 const CONFIG_TEXT = `config: ~/.done-done/config.yaml (global; DONE_DONE_HOME moves it) and .done-done.yaml (the repo), repo over global.
   agent (either file): claude, codex, opencode, pi, gemini or acp:<target>, set by the user (done-done init --agent); done-done never picks one.
   global only: agent_config.<agent>.{model,effort} (effort: minimal, low, medium, high, xhigh, max), agent_args_override.<agent>
-  (extra flags), agent_path_override.<agent> (binary), acpx_path, agent_timeout (one agent call, default 30m),
-  evidence.local_root, judge.{route,model,allow_same,claude_code.config_dir} (the judge, set by the user with
+  (extra flags), agent_path_override.<agent> (binary), acpx_path, agent_timeout (one agent call, default 30m; a streaming agent that prints nothing for 5m is stopped early),
+  evidence.local_root, judge.{route,model,allow_same} (the judge, set by the user with
   init --judge; never picked). done-done doctor shows where each agent setting came from.`;
 // One table drives `--help` and every `<command> --help`: each command's usage lines and the flags it takes.
 const FLAGS = {
@@ -92,6 +93,7 @@ const FLAGS = {
     '--outcome "<claim>"': 'the outcome the evidence files prove; the files follow as arguments',
     '--from <file | - | PR URL>': 'read the claim from the newest "## Checks" block of a file, stdin or a PR body',
     '--trusted-ref <ref>': 'read .done-done.yaml from this git ref instead of the working tree (use in CI)',
+    '--citation-base <dir>': 'resolve evidence citations against this directory (default: cwd); absolute citations stay unchanged; does not change repo, config or run storage',
     '--claim-id <id>': 'the claim the evidence proves; evidence already used for another claim id is reuse (default: the current branch, or the PR branch with --from <PR URL>; required on a detached HEAD)',
     '--judge': 'the judge the user set (judge.route, never the agent and model that did the work) says whether each PNG/JPEG capture shows the outcome (verify does this by default; check and receipt only with --judge or judge.enabled: true)',
     '--no-judge': 'skip the judge, only when the user chooses to (or judge.enabled: false in .done-done.yaml)',
@@ -108,6 +110,7 @@ const FLAGS = {
     '--action <approve|skip|fix>': 'approve: the captures do show the outcome; skip: go on without a judge pass; both end the run overridden; fix: end it fail, then fix the product or the verify skill (done-done maintain checks it against the source)',
     '--reason "<why>"': 'why (required for approve and skip); kept in the run and its receipt with who answered',
     '--limit <n>': 'how many past runs to list (default all)',
+    '--out <file.png>': 'where look writes the screenshot; its page-check record goes next to it as <file>.dom.json (default: look.png in $DONE_DONE_EVIDENCE_ROOT inside a journey, else in the current folder)',
     '--agent <agent>': 'the coding agent done-done starts (claude, codex, opencode, pi, gemini or acp:<target>), saved as agent in ~/.done-done/config.yaml; without it, init asks in a terminal',
     '--model <model>': 'with --agent: that agent\'s model, saved as agent_config.<agent>.model (opencode: provider/model)',
     '--judge <agent>': `the judge done-done starts (${JUDGES.join(' or ')}), saved as judge.route in ~/.done-done/config.yaml; never the agent and model that did the work; without it, init asks in a terminal`,
@@ -151,19 +154,19 @@ const COMMANDS = {
     },
     check: {
         usage: [
-            ['done-done check --outcome "<claim>" <files...> [--claim-id <id>] [--trusted-ref <ref>] [--judge]', 'check evidence files against a claim'],
-            ['done-done check --from <file | - | PR URL> [--claim-id <id>] [--trusted-ref <ref>] [--judge]', "check a claim's Checks block"],
+            ['done-done check --outcome "<claim>" <files...> [--claim-id <id>] [--trusted-ref <ref>] [--citation-base <dir>] [--judge]', 'check evidence files against a claim'],
+            ['done-done check --from <file | - | PR URL> [--claim-id <id>] [--trusted-ref <ref>] [--citation-base <dir>] [--judge]', "check a claim's Checks block"],
         ],
-        flags: ['--outcome "<claim>"', '--from <file | - | PR URL>', '--claim-id <id>', '--trusted-ref <ref>', '--judge'],
+        flags: ['--outcome "<claim>"', '--from <file | - | PR URL>', '--claim-id <id>', '--trusted-ref <ref>', '--citation-base <dir>', '--judge'],
         more: [CHECKS_TEXT],
     },
     receipt: {
         usage: [
-            ['done-done receipt --outcome "<claim>" <files...> [--claim-id <id>] [--trusted-ref <ref>] [--judge]', 'record a passing check for HEAD'],
-            ['done-done receipt --from <file | - | PR URL> [--claim-id <id>] [--trusted-ref <ref>] [--judge]', "record from a claim's Checks block"],
+            ['done-done receipt --outcome "<claim>" <files...> [--claim-id <id>] [--trusted-ref <ref>] [--citation-base <dir>] [--judge]', 'record a passing check for HEAD'],
+            ['done-done receipt --from <file | - | PR URL> [--claim-id <id>] [--trusted-ref <ref>] [--citation-base <dir>] [--judge]', "record from a claim's Checks block"],
             ['done-done receipt --verify <head>', 'read-only: verify a recorded receipt'],
         ],
-        flags: ['--outcome "<claim>"', '--from <file | - | PR URL>', '--claim-id <id>', '--trusted-ref <ref>', '--judge', '--verify <head>'],
+        flags: ['--outcome "<claim>"', '--from <file | - | PR URL>', '--claim-id <id>', '--trusted-ref <ref>', '--citation-base <dir>', '--judge', '--verify <head>'],
         more: [CHECKS_TEXT],
     },
     verify: {
@@ -186,6 +189,14 @@ const COMMANDS = {
         more: [`design: one judge request per screen (the judge the user set, never the author); it fails a screen on any defect it names:
   ${Object.keys(KINDS).join(', ')}; capture each variant (dark, small width, large font) as its own screen; exit 0 every screen
   passed, 1 a screen failed, 3 none failed but one is unsure`],
+    },
+    look: {
+        usage: [['done-done look <url> [--out <file.png>]', 'open a page in headless Chrome at a phone viewport, capture it with its page-check record, and fail on any squashed, clipped or cut-off UI']],
+        flags: ['--out <file.png>'],
+        more: [`look: one deterministic step a journey calls as its command or inside its script; no judge, no model. It measures horizontal
+  overflow, squashed text, text clipped by its container and elements cut off by the left, right or top edge, writes the
+  screenshot and its .dom.json record, and exits 1 naming each element, kind and text, 0 when there is none. A hit always
+  fails: never wrap it in || true. Needs Chrome or Chromium (DONE_DONE_CHROME names the binary)`],
     },
     status: {
         usage: [['done-done status [--run <run-id>]', "show a run's steps, result, findings and next step"]],
@@ -279,6 +290,10 @@ function captureHint(cfg) {
         return `done-done run <journey> (${names.join(', ')})`;
     return 'done-done run -- <capture command>';
 }
+// The words after --, as the one shell command string a run executes. One word is already a whole command,
+// so it stays verbatim (the documented `-- '<shell command>'` recipe); several words are argv, and each one
+// is quoted so spaces and shell metacharacters inside a word survive the shell that runs the string.
+const commandOf = (words) => (words.length === 1 ? words[0] : words.map(quote).join(' '));
 // A path as the user should see it: repo-relative inside the repo, else with the home directory as ~.
 const outside = (r) => r === '..' || r.startsWith(`..${sep}`) || isAbsolute(r);
 const shown = (repo, p) => {
@@ -344,7 +359,14 @@ function openRun(repo, cfg, journey, command, id) {
     mkdirSync(runDir(cfg, runId));
     return { schema: 1, run_id: runId, journey, command, ...h, started_at: new Date().toISOString(), ended_at: null, exit: null, files: [] };
 }
-function closeRun(repo, cfg, rec) {
+// The first line of a run's log that names a failure, trimmed: what a non-zero exit is about. Empty when none does.
+function firstFailure(log) {
+    if (!existsSync(log))
+        return '';
+    const line = readFileSync(log, 'utf8').split('\n').map((l) => l.replace(/\x1b\[[\d;]*m/g, '').trim()).find((l) => /\b(FAIL|FAILED|Error|failed|timed out)\b/.test(l));
+    return line ? line.slice(0, 200) : '';
+}
+function closeRun(repo, cfg, rec, log) {
     const now = head(repo);
     rec.files = captured(cfg, rec.run_id)
         .sort()
@@ -360,8 +382,10 @@ function closeRun(repo, cfg, rec) {
     let reason = '';
     if (now.commit !== rec.commit)
         reason = `HEAD moved from ${rec.commit} to ${now.commit} during the run; evidence is not tied to one commit`;
-    else if (rec.exit !== null && rec.exit !== 0)
-        reason = `the run command exited ${rec.exit}`;
+    else if (rec.exit !== null && rec.exit !== 0) {
+        const failure = log ? firstFailure(log) : '';
+        reason = `the run command exited ${rec.exit}${failure ? `: ${failure}` : ''}`;
+    }
     else if (!rec.files.length)
         reason = `the run wrote no files into its folder ${shown(repo, runDir(cfg, rec.run_id))}; the command gets it as $DONE_DONE_EVIDENCE_ROOT and its run id as $DONE_DONE_RUN_ID (or \${RUN_ID} in the command)`;
     const evidence = FULL ? rec.files.map((f) => ({ path: rel(f.path), sha256: f.sha256, bytes: f.bytes })) : rec.files.map((f) => rel(f.path));
@@ -419,7 +443,7 @@ async function cmdRun(argv) {
     const spends = journey ? cfg.journeys[journey]?.spends : undefined;
     if (spends)
         throw new UsageError(`journey ${journey} spends (${spends}), so run refuses it: nothing ran`, `Ask the user, then: done-done verify ${journey} --outcome "<what a user can now do>"`);
-    let command = dash < 0 ? null : argv.slice(dash + 1).join(' ');
+    let command = dash < 0 ? null : commandOf(argv.slice(dash + 1));
     if (journey && !command) {
         const j = cfg.journeys[journey];
         if (!j)
@@ -476,14 +500,20 @@ async function cmdRun(argv) {
     const matrix = hasMatrix(cfg.matrix) ? splitMatrix(cfg.matrix) : null;
     const failed = [];
     rec.exit = 0;
+    // The run's log lives with its run store, never in the evidence folder the judge reads: a failure names its first failing line.
+    const logFile = join(runsRoot(cfg.app), rec.run_id, 'logs', 'run.log');
+    mkdirSync(dirname(logFile), { recursive: true });
     for (const cell of matrix?.required ?? [{}]) {
         // The journey's own stdout goes to our stderr, never our stdout: stdout carries only done-done's
         // result document (TOON or --json), so a noisy journey cannot break `run --json | JSON.parse`.
         const r = await new Promise((done) => {
-            spawn(expanded, {
-                cwd: repo, shell: true, stdio: ['inherit', process.stderr, 'inherit'],
+            const child = spawn(expanded, {
+                cwd: repo, shell: true, stdio: ['inherit', 'pipe', 'pipe'],
                 env: { ...process.env, DONE_DONE_RUN_ID: rec.run_id, DONE_DONE_EVIDENCE_ROOT: runDir(cfg, rec.run_id), ...inst?.env, ...(matrix ? cellEnv(cell) : {}) },
-            }).on('error', () => done(null)).on('close', done);
+            });
+            for (const out of [child.stdout, child.stderr])
+                out?.on('data', (b) => { process.stderr.write(b); appendFileSync(logFile, b); });
+            child.on('error', () => done(null)).on('close', done);
         });
         const code = r ?? 1;
         if (code !== 0) {
@@ -493,7 +523,7 @@ async function cmdRun(argv) {
         }
     }
     reap();
-    const sealed = closeRun(repo, cfg, rec);
+    const sealed = closeRun(repo, cfg, rec, logFile);
     if (matrix && failed.length)
         return emitted({ code: FAIL, result: { ...sealed.result, reason: `the run command failed for cell ${failed.join('; ')}` } });
     return emitted(sealed);
@@ -558,9 +588,11 @@ function loadRecords(cfg) {
 async function runCheck(argv, run) {
     const { values, positionals } = parseArgs({
         args: argv,
-        options: { outcome: { type: 'string' }, from: { type: 'string' }, 'claim-id': { type: 'string' }, 'trusted-ref': { type: 'string' }, judge: { type: 'boolean' } },
+        options: { outcome: { type: 'string' }, from: { type: 'string' }, 'claim-id': { type: 'string' }, 'trusted-ref': { type: 'string' }, 'citation-base': { type: 'string' }, judge: { type: 'boolean' } },
         allowPositionals: true,
     });
+    if (values['citation-base']?.trim() === '')
+        throw new UsageError('--citation-base needs a non-empty directory');
     if (!!values.outcome === !!values.from)
         throw new UsageError('check needs exactly one of --outcome or --from');
     if (values.from && positionals.length)
@@ -600,10 +632,10 @@ async function runCheck(argv, run) {
     if (claim?.notProven) {
         const allowed = cfg.checks.not_proven === 'allow' && cfg.trusted;
         const all = findings.concat(allowed ? [] : [{ level: 'inconclusive', why: `not proven: ${claim.notProven}` }]);
-        const rep = report(all, [], { cfg, repo, claim: claim.outcome, source: values.from, notProven: true }, allowed ? 'not proven (allowed by trusted config)' : '');
+        const rep = report(all, [], { cfg, repo, claim: claim.outcome, source: values.from, citationBase: values['citation-base'], notProven: true }, allowed ? 'not proven (allowed by trusted config)' : '');
         return { code: rep.code, result: rep.result, claim: claim?.outcome, files: [], cited: [], head: now, findings: all };
     }
-    const files = claim?.files ?? [];
+    const files = (claim?.files ?? []).map((name) => values['citation-base'] === undefined ? name : resolve(values['citation-base'], name));
     const records = loadRecords(cfg);
     const seen = new Map();
     const hashes = [];
@@ -616,8 +648,21 @@ async function runCheck(argv, run) {
     };
     const befores = new Map();
     const heads = [];
+    // Citations are the paths `run` printed: repo-relative inside the repo, absolute outside it.
+    // Resolve a relative citation against the repo root first, so a check from a subdirectory
+    // finds the same evidence (a worker cwd once false-failed real proof as missing/ENOENT),
+    // then against the caller's cwd, so a shell-relative path typed for this shell still works.
+    const cite = (name) => {
+        if (isAbsolute(name))
+            return name;
+        const atRoot = resolve(repo, name);
+        if (existsSync(atRoot))
+            return atRoot;
+        const atCwd = resolve(name);
+        return existsSync(atCwd) ? atCwd : atRoot;
+    };
     for (const name of files) {
-        const path = resolve(name);
+        const path = cite(name);
         let bytes;
         try {
             if (!statSync(path).isFile())
@@ -625,7 +670,9 @@ async function runCheck(argv, run) {
             bytes = readFileSync(path);
         }
         catch (e) {
-            findings.push({ level: 'fail', why: `${name}: missing (${e.code ?? e.message})` });
+            const atCwd = !isAbsolute(name) && resolve(name) !== path ? ` or ${resolve(name)}` : '';
+            const missing = e.code !== 'ENOENT' ? undefined : under(cfg.evidence.root, path) === null ? 'checkout' : 'run';
+            findings.push({ level: 'fail', why: `${name}: no such file (looked for ${path}${atCwd}${e.code ? `, ${e.code}` : ''})`, missing });
             continue;
         }
         const v = checkMedia(path, bytes);
@@ -680,7 +727,7 @@ async function runCheck(argv, run) {
         if (stale)
             findings.push({ level: 'fail', why: `${name}: ${stale} (run ${rec.run_id})` });
         if (rec.dirty && !cfg.evidence.allow_dirty)
-            findings.push({ level: 'fail', why: `${name}: captured from a tree with uncommitted changes (run ${rec.run_id})` });
+            findings.push({ level: 'fail', why: `${name}: captured from a tree with uncommitted changes (run ${rec.run_id}); commit them, then capture again` });
         if (rec.exit !== null && rec.exit !== 0)
             findings.push({ level: 'fail', why: `${name}: its run command exited ${rec.exit} (run ${rec.run_id})` });
     }
@@ -690,16 +737,16 @@ async function runCheck(argv, run) {
             findings.push({ level: 'inconclusive', why: `${c.name}: no base capture to compare with: the drive at base_ref ${rec.base.ref} saved no ${join(BEFORE, inRoot ? relative(rec.run_id, inRoot) : c.name)}${rec.base.error ? ` (${rec.base.error})` : ''}`, file: c.name });
     // The capture matrix: every required cell needs a capture named with its suffix, never silently missing.
     if (hasMatrix(cfg.matrix))
-        for (const c of matrixManifest(cfg.matrix, files.filter((f) => (!cfg.dom || !isDomRecord(f)) && !pairOf(under(cfg.evidence.root, resolve(f))))).cells.filter((c) => !c.files.length))
+        for (const c of matrixManifest(cfg.matrix, files.filter((f) => (!cfg.dom || !isDomRecord(f)) && !pairOf(under(cfg.evidence.root, cite(f))))).cells.filter((c) => !c.files.length))
             findings.push({ level: 'fail', why: `cell ${c.cell} has no capture: name one file *${c.suffix}* (journeys name captures with DONE_DONE_CELL)` });
     // Reuse: fail only when every cited file was already used for a different claim id. The ledger lives in the
     // evidence root next to the run records it guards: one per app (repo), shared by every checkout of it, never in git.
     const ledger = join(cfg.evidence.root, '.done-done', 'ledger');
     const given = values['claim-id']?.replace(/\s+/g, ' ').trim();
-    const claimId = given || prBranch || git(repo, 'branch', '--show-current');
-    const idFrom = given ? '--claim-id' : prBranch ? 'the PR branch' : 'the current branch';
-    if (!claimId && claim)
-        throw new UsageError('HEAD is detached, so no branch names this claim; pass --claim-id <id>', 'Re-run with --claim-id <the branch or task this claim is for>');
+    // A detached HEAD (a worktree, a PR checkout) has no branch, so its claim is the commit it checks.
+    const branch = git(repo, 'branch', '--show-current');
+    const claimId = given || prBranch || branch || (claim ? now.commit : '');
+    const idFrom = given ? '--claim-id' : prBranch ? 'the PR branch' : branch ? 'the current branch' : 'the detached HEAD commit';
     const used = new Map();
     if (existsSync(ledger))
         for (const line of readFileSync(ledger, 'utf8').split('\n')) {
@@ -739,7 +786,7 @@ async function runCheck(argv, run) {
             const { choice } = j;
             judged = { ...(choice && { route: choice.route, model: choice.model, independence: choice.independence, author: `${choice.author.agent} (model ${choice.author.model || 'none'})` }), judged: rows.items.map(({ sha256, ...r }) => r) };
             if (choice && j.judged.length) {
-                const byName = new Map(captures.map((c) => [c.name, receiptPath(repo, cfg, resolve(c.name))]));
+                const byName = new Map(captures.map((c) => [c.name, receiptPath(repo, cfg, cite(c.name))]));
                 judgeBlock = { route: choice.route, model: choice.model, independence: choice.independence, author: choice.author, verdicts: j.judged.map((r) => ({ path: byName.get(r.path), sha256: r.sha256, verdict: r.verdict })) };
             }
             if (rows.omitted)
@@ -749,7 +796,7 @@ async function runCheck(argv, run) {
             judged.note = 'PNG and JPEG screens and text captures (logs, JSON, CLI output) are judged; video and other files are not';
         }
     }
-    const rep = report(findings, files, { cfg, repo, claim: claim?.outcome, source: values.from, judge: judged, judgeLevel });
+    const rep = report(findings, files, { cfg, repo, claim: claim?.outcome, source: values.from, citationBase: values['citation-base'], judge: judged, judgeLevel });
     if (rep.code === PASS) {
         mkdirSync(dirname(ledger), { recursive: true });
         appendFileSync(ledger, hashes.filter((h) => !used.get(h)?.has(claimId)).map((h) => `${h} ${claimId}\n`).join(''));
@@ -832,8 +879,8 @@ function verifyReceipt(repo, cfg, headArg) {
         try {
             bytes = readFileSync(f.path.startsWith(IN_EVIDENCE) ? join(cfg.evidence.root, f.path.slice(IN_EVIDENCE.length)) : resolve(repo, f.path));
         }
-        catch {
-            bad.push(`${f.path}: missing`);
+        catch (e) {
+            bad.push(`${f.path}: no such file (looked for ${f.path.startsWith(IN_EVIDENCE) ? join(cfg.evidence.root, f.path.slice(IN_EVIDENCE.length)) : resolve(repo, f.path)}${e.code ? `, ${e.code}` : ''})`);
             continue;
         }
         if (sha256(bytes) !== f.sha256) {
@@ -899,7 +946,7 @@ function staleness(repo, cfg, from, to) {
 }
 // Quote an argument only when a shell would split it.
 const arg = (a) => (/^[\w./@:+-]+$/.test(a) ? a : `'${a.replaceAll("'", `'\\''`)}'`);
-function checkHelp(code, files, { cfg, repo, claim, source, notProven, judgeLevel }) {
+function checkHelp(code, findings, files, { cfg, repo, claim, source, citationBase, notProven, judgeLevel }) {
     if (notProven)
         return ['Capture real proof and replace "not proven:", or set checks.not_proven: allow and re-check from a trusted ref'];
     if (judgeLevel === 'fail' && code === FAIL)
@@ -908,15 +955,27 @@ function checkHelp(code, files, { cfg, repo, claim, source, notProven, judgeLeve
         return ['Look at the capture yourself, or capture a clearer screen of the outcome and re-run this check'];
     if (code === PASS) {
         // The CI gate needs a PR on a remote; without one, a receipt records the pass locally.
+        const citationArgs = citationBase === undefined ? '' : ` --citation-base ${arg(citationBase)}`;
         if (spawnSync('git', ['remote', 'get-url', 'origin'], { cwd: repo }).status === 0)
-            return ['Gate CI on this proof: done-done check --from <PR URL> --trusted-ref origin/main'];
+            return [`Gate CI on this proof: done-done check --from <PR URL> --trusted-ref origin/main${citationArgs}`];
         const claimArgs = source ? ['--from', source] : ['--outcome', claim ?? '', ...files];
-        return [`Record this pass for HEAD: done-done receipt ${claimArgs.map(arg).join(' ')}`];
+        return [`Record this pass for HEAD: done-done receipt ${claimArgs.map(arg).join(' ')}${citationArgs}`];
     }
     const capture = captureHint(cfg);
     if (code === INCONCLUSIVE)
         return [`Capture this proof through a run so it is tied to a commit, then re-run this check: ${capture}`];
-    return [`Commit your change, re-capture with ${capture}, then check the new files`];
+    // A named file outside this checkout is not lost: point at the folder that holds it first. Re-capture is for proof the run should have written here.
+    const help = [];
+    const absent = findings.filter((f) => f.missing === 'checkout').length;
+    if (absent) {
+        const form = source ? `done-done check --from ${arg(source)} --citation-base <dir>` : 'done-done check --outcome <claim> <files...> --citation-base <dir>';
+        help.push(citationBase === undefined
+            ? `${absent} named file${absent > 1 ? 's are' : ' is'} not in this checkout. If the evidence is in another folder, check against it: ${form}`
+            : `${absent} named file${absent > 1 ? 's are' : ' is'} not under --citation-base ${arg(citationBase)} either: check the paths in the Checks block`);
+    }
+    if (findings.some((f) => f.level === 'fail' && f.missing !== 'checkout'))
+        help.push(`Commit your change, re-capture with ${capture}, then check the new files`);
+    return help;
 }
 function report(findings, files, ctx, note = '') {
     const code = findings.some((f) => f.level === 'fail') ? FAIL : findings.length ? INCONCLUSIVE : PASS;
@@ -944,7 +1003,7 @@ function report(findings, files, ctx, note = '') {
         result.findings = rows.items;
     if (rows.omitted)
         result.findings_omitted = rows.omitted;
-    result.help = checkHelp(code, files, ctx);
+    result.help = checkHelp(code, findings, files, ctx);
     return { code, result };
 }
 const CLI_PATH = fileURLToPath(import.meta.url);
@@ -1370,7 +1429,7 @@ async function runSteps(dir) {
                 if (skillFeatures(at, cfg).includes(picked))
                     run.feature ??= picked;
                 log('drive', { agent: author.agent, model: author.model, feature: run.feature ?? 'none', ...(a.ok ? { captures: answer?.captures, blocker } : { error: a.error }), record: a.record ?? a.recordError });
-                const why = !a.ok ? `${author.agent} did not finish the drive: ${a.error}`
+                const why = !a.ok ? `${author.agent} did not finish the drive: ${a.error}${a.record ? `; call record ${a.record}` : ''}`
                     : blocker ? `${author.agent} could not drive the feature: ${blocker}`
                         : changed ? `${author.agent} changed tracked files in the repo during the drive (see git status), so its captures are not of the committed code`
                             : sealed.code !== PASS ? sealed.reason : '';
@@ -1968,11 +2027,33 @@ async function cmdMaintain(argv) {
     logEvent(dir, { status: 'pending' });
     return launch(dir, cfg, 'maintain', values);
 }
+// `run` writes an evidence record, not a verify run: status shows it too, so the run id that `run` printed resolves here.
+function showRecord(repo, cfg, rec) {
+    const rel = (p) => citable(repo, join(cfg.evidence.root, p));
+    const evidence = FULL ? rec.files.map((f) => ({ path: rel(f.path), sha256: f.sha256, bytes: f.bytes })) : rec.files.map((f) => rel(f.path));
+    const rows = cap(evidence);
+    emit({
+        command: 'status',
+        run_id: rec.run_id,
+        commit: rec.commit,
+        dirty: rec.dirty,
+        files: rec.files.length,
+        record: shown(repo, join(recordsDir(cfg), `${rec.run_id}.json`)),
+        evidence: rows.items,
+        ...(rows.omitted && { evidence_omitted: rows.omitted }),
+        help: [rec.files.length ? `Check this proof: done-done check --outcome "<what you proved>" ${rel(rec.files[0].path)}` : `Read the run's folder: ${shown(repo, runDir(cfg, rec.run_id))}`],
+    });
+    return PASS;
+}
 function cmdStatus(argv) {
     const { values } = parseArgs({ args: argv, options: { run: { type: 'string' } } });
     const repo = repoRoot();
     const cfg = loadConfig(repo);
     const root = runsRoot(cfg.app);
+    const verify = values.run ? /^[\w-]+$/.test(values.run) && existsSync(join(root, values.run, 'run.json')) : runsIn(root).some((r) => r.repo === repo);
+    const rec = verify ? undefined : loadRecords(cfg).filter((r) => !values.run || r.run_id === values.run).sort((a, b) => a.started_at.localeCompare(b.started_at)).pop();
+    if (rec)
+        return showRecord(repo, cfg, rec);
     return showRun(join(root, pickId(root, repo, 'status', cfg, values.run)), cfg, 'status');
 }
 async function cmdAttach(argv) {
@@ -2352,7 +2433,7 @@ function ensureIgnored(repo, rel) {
     return true;
 }
 // `init` also scaffolds the project's verify skill from the repo's own files: a port of the
-// fleet create-verification-skill interview (surface, run, drive, observe, isolate).
+// the create-verification-skill interview (surface, run, drive, observe, isolate).
 // Every line is an action: a detected handle gets concrete drive and capture steps, and a blank detection cannot
 // fill gets the steps to find it and record it there, never an invented command. An existing skill is never
 // overwritten, so re-run is idempotent.
@@ -2897,6 +2978,9 @@ function checkJudge(cfg, agent, model) {
     if (cfg.agent)
         selectJudge({ ...cfg, judge: { ...cfg.judge, route: routeOf(agent), model } }, selectAgent(cfg));
 }
+const commitFirst = (skill) => `.done-done.yaml and ${skill} before your first capture: check refuses proof from a tree with uncommitted changes`;
+// An absolute path inside the repo in a recipe: the recipe is committed, so it would name this checkout only.
+const absoluteInside = (command, repo) => [...command.matchAll(/(?:^|[\s"'=])(\/[^\s"'`;|&<>]*)/g)].map((m) => m[1]).find((p) => p === repo || p.startsWith(`${repo}/`));
 async function cmdInit(argv) {
     const dash = argv.indexOf('--');
     const { values } = parseArgs({
@@ -2963,8 +3047,11 @@ async function cmdInit(argv) {
     };
     if (journey !== null) {
         // Record the capture recipe in the repo so any checkout can re-run the proof.
-        // The command is stored verbatim; ${RUN_ID} in it becomes the run id, like a run -- command.
-        const command = parts.join(' ');
+        // The command is built once, the same way `run --` builds it, so the recipe re-runs exactly; ${RUN_ID} in it becomes the run id.
+        const command = commandOf(parts);
+        const inside = absoluteInside(command, repo);
+        if (inside)
+            throw new UsageError(`init --journey ${journey}: ${inside} is an absolute path inside this repo, and the recipe is committed to .done-done.yaml, so other checkouts cannot run it`, `Name it relative to the repo, e.g.: done-done init --journey ${journey} -- ${command.replaceAll(inside, relative(repo, inside) || '.')}`);
         const doc = existed ? parseDocument(readFileSync(file, 'utf8')) : new Document({ app: cfg.app });
         const top = (doc.toJS() ?? {});
         if (typeof top !== 'object' || Array.isArray(top))
@@ -3000,7 +3087,7 @@ async function cmdInit(argv) {
             gitignore: added ? `added ${rel.replace(/\/+$/, '')}/` : 'unchanged',
             verify_skill: verify,
             ...agentHook.out,
-            help: [`Capture proof: done-done run ${journey}, then: ${check}`, ...agentHook.help, ...ag.help, ...jg.help],
+            help: [`Capture proof: done-done run ${journey}, then: ${check}`, ...agentHook.help, ...ag.help, ...jg.help, `Commit ${commitFirst(fresh.skill)}`],
         });
         return ag.code;
     }
@@ -3045,6 +3132,7 @@ app: ${JSON.stringify(cfg.app)}
             ...agentHook.help,
             ...ag.help,
             ...jg.help,
+            `Commit ${commitFirst(cfg.skill)}`,
         ],
     });
     return ag.code;
@@ -3086,6 +3174,8 @@ function writableDir(p) {
     }
 }
 const PROBE_SCHEMA = { type: 'object', properties: { ok: { type: 'boolean' } }, required: ['ok'], additionalProperties: false };
+// A tool-less probe starts in seconds; an agent silent for this long is stuck, so doctor says why instead of waiting the agent_timeout.
+const PROBE_IDLE_MS = 30_000;
 const unknownRow = (check, detail = 'unknown without a valid config', fix = '') => ({ check, status: 'missing', detail, fix });
 // Each effective setting of the agent and the file it came from: the global config, the repo's .done-done.yaml, or the built-in default.
 function agentSettings(cfg, agent) {
@@ -3257,7 +3347,7 @@ async function cmdDoctor(argv) {
             check: 'judge_choice',
             status: apartOk ? 'ok' : 'warning',
             detail: `${choice.route} (model ${choice.model}; from config) judges the author ${choice.author.agent} (model ${choice.author.model || 'none'}): ${apart}${accepted}`,
-            fix: apartOk ? '' : `Ask the user whether to judge with another agent (${JUDGES.join(' or ')}) and save it: done-done init --judge <agent> --judge-model <model>`,
+            fix: apartOk ? '' : `Ask the user whether to judge with another agent or model (${JUDGES.join(' or ')}) and save it: done-done init --judge <agent> --judge-model <model>`,
         });
     }
     if (values.probe && !agent)
@@ -3268,10 +3358,10 @@ async function cmdDoctor(argv) {
     else if (values.probe && agent) {
         const record = join(home(), 'agents', `probe-${new Date().toISOString().replace(/[:.]/g, '-')}-${agent.agent}.json`);
         const probe = !agent.path ? { ok: false, error: notFound, fix: installFix }
-            : await askAgent({ ...agent, prompt: 'This is a connectivity probe from done-done doctor. Use no tools. Answer with ok set to true.', schema: PROBE_SCHEMA, cwd: repo ?? process.cwd(), tools: 'none', record });
+            : await askAgent({ ...agent, prompt: 'This is a connectivity probe from done-done doctor. Use no tools. Answer with ok set to true.', schema: PROBE_SCHEMA, cwd: repo ?? process.cwd(), tools: 'none', record, idleMs: PROBE_IDLE_MS });
         checks.push(probe.ok && probe.answer?.ok === true
             ? { check: 'probe', status: 'ok', detail: `${agent.agent} (${modelPhrase(agent.agent, agent.model)}) answered the schema question; ${probe.recordError ? `the call record could not be written: ${probe.recordError}` : `record ${record}`}`, fix: '' }
-            : { check: 'probe', status: 'missing', detail: `${agent.agent} did not answer: ${probe.error ?? `answer ${JSON.stringify(probe.answer)}`}${probe.record ? `; record ${record}` : ''}${probe.recordError ? `; the call record could not be written: ${probe.recordError}` : ''}`, fix: probe.fix ?? `Check that ${agent.agent} is signed in${agent.model ? ` and can use model ${agent.model}` : ''}, or set agent_config.${agent.agent}.model` });
+            : { check: 'probe', status: 'missing', detail: `${agent.agent} did not answer: ${probe.error ?? `answer ${JSON.stringify(probe.answer)}`}${probe.record ? `; record ${record}` : ''}${probe.recordError ? `; the call record could not be written: ${probe.recordError}` : ''}`, fix: probe.fix ?? `${probe.stderr ? `${agent.agent} stderr: ${probe.stderr}. ` : ''}Check that ${agent.agent} is signed in${agent.model ? ` and can use model ${agent.model}` : ''}, or set agent_config.${agent.agent}.model` });
     }
     if (agent)
         checks.push({ check: 'agent_settings', status: 'ok', detail: agentSettings(agentCfg, agent.agent), fix: '' });
@@ -3296,6 +3386,32 @@ async function cmdDoctor(argv) {
     return missingRequired.length ? USAGE : PASS;
 }
 // The design check: every named screen, and each --mock screen, judged for visual defects.
+async function cmdLook(argv) {
+    const { values, positionals } = parseArgs({ args: argv, options: { out: { type: 'string' } }, allowPositionals: true });
+    if (positionals.length !== 1)
+        throw new UsageError('look needs one page URL', 'Re-run with the page to check: done-done look <url>');
+    // A path to a page on disk opens as its file:// URL.
+    const url = !/^[a-z][\w+.-]*:/i.test(positionals[0]) && existsSync(positionals[0]) ? pathToFileURL(resolve(positionals[0])).href : positionals[0];
+    const capture = resolve(values.out ?? join(process.env.DONE_DONE_EVIDENCE_ROOT || '.', 'look.png'));
+    if (!capture.endsWith('.png'))
+        throw new UsageError(`--out ${values.out} must be a .png file`);
+    mkdirSync(dirname(capture), { recursive: true });
+    const record = await look(url, capture, 390, 844);
+    const hits = lookIssues(record);
+    const shown = cap(hits);
+    emit({
+        command: 'look',
+        result: hits.length ? 'fail' : 'pass',
+        url,
+        viewport: '390x844',
+        capture,
+        record: domRecord(capture),
+        hits: shown.items,
+        ...(shown.omitted && { hits_omitted: shown.omitted }),
+        help: hits.length ? [`Fix each element named above so it fits the 390 px wide screen, then re-run: done-done look ${quote(positionals[0])}${values.out ? ` --out ${quote(values.out)}` : ''}`] : ['No squashed, clipped or cut-off UI on this page; look at the capture to check the rest'],
+    });
+    return hits.length ? FAIL : PASS;
+}
 async function cmdDesign(argv) {
     const { values, positionals } = parseArgs({ args: argv, options: { mock: { type: 'string', multiple: true } }, allowPositionals: true });
     const mocks = new Map();
@@ -3417,6 +3533,8 @@ async function main(argv) {
             return await cmdMaintain(rest);
         if (cmd === 'design')
             return await cmdDesign(rest);
+        if (cmd === 'look')
+            return await cmdLook(rest);
         if (cmd === 'status')
             return cmdStatus(rest);
         if (cmd === 'attach')

package/dist/config.js

@@ -70,11 +70,10 @@ const KEYS = {
     'judge.enabled': { scope: 'repo', type: 'boolean' },
     'judge.model': { scope: 'global', type: 'string' },
     'judge.route': { scope: 'global', type: 'route' },
-    'judge.claude_code': { scope: 'global', type: 'claude_code' },
     'judge.allow_same': { scope: 'global', type: 'boolean' },
 };
 const SECTIONS = new Set(['evidence', 'secrets', 'checks', 'judge']);
-const MAPS = new Set(['auto_fix', 'agent_config', 'agent_args_override', 'agent_path_override', 'judge.claude_code']);
+const MAPS = new Set(['auto_fix', 'agent_config', 'agent_args_override', 'agent_path_override']);
 export const home = () => process.env.DONE_DONE_HOME || join(homedir(), '.done-done');
 // A duration such as 90s, 30m or 1h, in milliseconds; null when the text is not one or is not a delay a timer can run.
 export const parseDuration = (text) => {
@@ -118,6 +117,7 @@ const isRegex = (v) => {
         return false;
     }
 };
+const leftoverNoticed = new Set();
 function apply(target, text, file, scope) {
     if (text === undefined)
         return;
@@ -129,6 +129,14 @@ function apply(target, text, file, scope) {
         throw new UsageError(`${file}: ${e.message.split('\n')[0]}`);
     }
     for (const [key, value] of flatten(doc, file)) {
+        // The claude judge runs the user's own claude sign-in now, so the folder key of older configs is only a leftover.
+        if (key === 'judge.claude_code') {
+            if (!leftoverNoticed.has(file)) {
+                leftoverNoticed.add(file);
+                process.stderr.write(`judge.claude_code is no longer used (the judge uses your normal claude sign-in); delete it from ${file}\n`);
+            }
+            continue;
+        }
         const spec = KEYS[key];
         if (!spec)
             throw new UsageError(`${file}: unknown key ${key}`);
@@ -140,16 +148,15 @@ function apply(target, text, file, scope) {
                     : spec.type === 'inputs' ? Array.isArray(value) && value.every((v) => typeof v === 'string' && inputPattern(v) !== '' && !isAbsolute(v) && !v.split('/').includes('..'))
                         : spec.type === 'agent' ? isAgent(value)
                             : spec.type === 'route' ? typeof value === 'string' && (value === 'claude-code' || Object.hasOwn(KEY_ROUTES, value) || ANSWERER_JUDGES.some((a) => value === `answerer:${a}`))
-                                : spec.type === 'claude_code' ? isMap(value) && Object.entries(value).every(([k, v]) => k === 'config_dir' && typeof v === 'string')
-                                    : spec.type === 'agent_config' ? isMap(value) && Object.entries(value).every(([a, c]) => isAgent(a) && isMap(c) && Object.entries(c).every(([k, m]) => ['model', 'effort'].includes(k) && typeof m === 'string'))
-                                        : spec.type === 'args' ? isMap(value) && Object.entries(value).every(([a, v]) => AGENTS.includes(a) && Array.isArray(v) && v.every((x) => typeof x === 'string'))
-                                            : spec.type === 'paths' ? isMap(value) && Object.entries(value).every(([a, v]) => AGENTS.includes(a) && isBin(v))
-                                                : spec.type === 'bin' ? isBin(value)
-                                                    : spec.type === 'duration' ? typeof value === 'string' && parseDuration(value) !== null
-                                                        : spec.type === 'auto_fix' ? isMap(value) && Object.entries(value).every(([k, n]) => AUTO_FIX_STEPS.includes(k) && Number.isInteger(n) && n >= 0)
-                                                            : spec.type === 'matrix' ? !checkMatrix(value)
-                                                                : spec.type === 'regexes' ? (key === 'secrets.allow' ? Array.isArray(value) : isMap(value)) && Object.values(value).every(isRegex)
-                                                                    : isMap(value) && Object.values(value).every((j) => j && typeof j.command === 'string' && (j.spends === undefined || (typeof j.spends === 'string' && j.spends.trim() !== '')));
+                                : spec.type === 'agent_config' ? isMap(value) && Object.entries(value).every(([a, c]) => isAgent(a) && isMap(c) && Object.entries(c).every(([k, m]) => ['model', 'effort'].includes(k) && typeof m === 'string'))
+                                    : spec.type === 'args' ? isMap(value) && Object.entries(value).every(([a, v]) => AGENTS.includes(a) && Array.isArray(v) && v.every((x) => typeof x === 'string'))
+                                        : spec.type === 'paths' ? isMap(value) && Object.entries(value).every(([a, v]) => AGENTS.includes(a) && isBin(v))
+                                            : spec.type === 'bin' ? isBin(value)
+                                                : spec.type === 'duration' ? typeof value === 'string' && parseDuration(value) !== null
+                                                    : spec.type === 'auto_fix' ? isMap(value) && Object.entries(value).every(([k, n]) => AUTO_FIX_STEPS.includes(k) && Number.isInteger(n) && n >= 0)
+                                                        : spec.type === 'matrix' ? !checkMatrix(value)
+                                                            : spec.type === 'regexes' ? (key === 'secrets.allow' ? Array.isArray(value) : isMap(value)) && Object.values(value).every(isRegex)
+                                                                : isMap(value) && Object.values(value).every((j) => j && typeof j.command === 'string' && (j.spends === undefined || (typeof j.spends === 'string' && j.spends.trim() !== '')));
         const want = {
             journeys: 'a map of name: {command: <string>, spends: <what a run spends>}',
             instance: '{command: <string>, ready: {url: <http url>} or {command: <shell command>}, ready_timeout: <duration>}',
@@ -163,7 +170,6 @@ function apply(target, text, file, scope) {
             regexes: key === 'secrets.allow' ? 'a list of valid regexes' : 'a map of <name>: <valid regex>',
             auto_fix: `a map of <step>: <attempts, 0 or more> for ${AUTO_FIX_STEPS.join(', ')}`,
             route: `claude-code (for claude), answerer:<agent> for one of ${ANSWERER_JUDGES.join(', ')}, or a key route (${Object.keys(KEY_ROUTES).join(', ')}); an acp:<target> agent cannot judge, since done-done cannot send it an image`,
-            claude_code: 'a map with config_dir, a string (the claude binary is agent_path_override.claude)',
             inputs: 'a list of repo-relative paths or globs, not absolute and with no .. segment',
         };
         if (key === 'judge.route' && (value === 'auto' || value === ''))
@@ -262,7 +268,7 @@ function defaultConfig(repo) {
         evidence: { local_root: join(home(), 'evidence'), root: '', allow_dirty: false, ignore_paths: [] },
         secrets: { patterns: {}, allow: [] },
         checks: { not_proven: 'inconclusive', fix_title: '^(fix|bugfix|hotfix)\\b' },
-        judge: { route: '', model: '', allow_same: false, claude_code: { config_dir: join(home(), 'claude') } },
+        judge: { route: '', model: '', allow_same: false },
         trusted: false,
         from: {},
     };
@@ -280,7 +286,6 @@ export function loadConfig(repo, projectText) {
     cfg.acpx_path = tilde(cfg.acpx_path);
     for (const a of Object.keys(cfg.agent_path_override))
         cfg.agent_path_override[a] = tilde(cfg.agent_path_override[a]);
-    cfg.judge.claude_code.config_dir = tilde(cfg.judge.claude_code.config_dir);
     // A relative root is under the repo (and dies with the checkout); an absolute one is used as-is.
     cfg.evidence.root = cfg.evidence.root ? resolve(repo, cfg.evidence.root) : join(local, cfg.app);
     return cfg;
@@ -345,8 +350,5 @@ judge:
   model: ""
   # Accept a judge that is the author's own agent and model in a fresh session.
   allow_same: false
-  claude_code:
-    # The claude-code judge's own Claude sign-in folder, never your ~/.claude.
-    config_dir: ${short(join(home(), 'claude'))}
 `;
 }