done-done-axi 0.3.1 → 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 = {
@@ -109,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`,
@@ -187,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"]],
@@ -349,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()
@@ -365,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));
@@ -481,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) {
@@ -498,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);
@@ -623,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())
@@ -632,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);
@@ -687,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})` });
     }
@@ -697,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')) {
@@ -746,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)
@@ -839,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) {
@@ -906,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, citationBase, 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)
@@ -924,7 +964,18 @@ function checkHelp(code, files, { cfg, repo, claim, source, citationBase, notPro
     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;
@@ -952,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);
@@ -1378,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 : '';
@@ -1976,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) {
@@ -2360,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.
@@ -2905,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({
@@ -2973,6 +3049,9 @@ async function cmdInit(argv) {
         // Record the capture recipe in the repo so any checkout can re-run the proof.
         // 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))
@@ -3008,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;
     }
@@ -3053,6 +3132,7 @@ app: ${JSON.stringify(cfg.app)}
             ...agentHook.help,
             ...ag.help,
             ...jg.help,
+            `Commit ${commitFirst(cfg.skill)}`,
         ],
     });
     return ag.code;
@@ -3094,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) {
@@ -3265,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)
@@ -3276,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: '' });
@@ -3304,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();
@@ -3425,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'))}
 `;
 }

package/dist/dom.js

@@ -3,8 +3,10 @@
 // (home.dark.390w.png -> home.dark.390w.dom.json), so a matrix cell's record carries its DONE_DONE_CELL suffix:
 //   {"url": "<page url>", "overflow": <true when content is wider than the viewport>, "overflowing": ["<element>", ...],
 //    "console_errors": ["<message>", ...], "failed_requests": [{"url": "<request url>", "status": <HTTP status, 0 when none>}],
-//    "squashed_text": [{"element": "<element>", "text": "<its text, ~40 chars>", "chars": <width>, "lines": <n>, "words": <n>}]}
-// squashed_text is optional, so a record written before it stays valid.
+//    "squashed_text": [{"element": "<element>", "text": "<its text, ~40 chars>", "chars": <width>, "lines": <n>, "words": <n>}],
+//    "clipped_text": [{"element": "<element>", "text": "<its text>", "by": "<the container that cuts it>"}],
+//    "cut_off": [{"element": "<element>", "text": "<its text>", "edges": ["left" | "right" | "top", ...]}]}
+// squashed_text, clipped_text and cut_off are optional, so a record written before them stays valid.
 import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 // The measurement the recipe passes to its browser tool's eval, so no agent invents one: every visible element with its
@@ -27,8 +29,48 @@ export const SQUASHED_TEXT = `() => {
   }
   return out;
 }`.replace(/\s*\n\s*/g, ' ');
+// The rest of the look measurement, run in the page by `done-done look` next to SQUASHED_TEXT. A part of an element only
+// shows inside every ancestor that clips it (overflow other than visible; html and body clip as the viewport, so they are
+// the edges, not containers). Text is clipped when part of it shows and part runs past a hidden or clip container on an
+// axis without text-overflow: ellipsis or a line clamp; an element is cut off when part of what shows lies past the
+// left, right or top edge of the viewport (the page is at its top, so nothing above it can be scrolled to). Something
+// entirely outside its container or the viewport is hidden on purpose (a closed drawer, a visually hidden label), not cut;
+// a cut element's children are not listed again.
+// ponytail: the main frame only, and a transform or clip-path that hides part of a box is not seen; measure each frame
+// and clip-path when those show up.
+export const LOOK = `() => {
+  const vw = document.documentElement.clientWidth; const vh = document.documentElement.clientHeight; const out = { clipped_text: [], cut_off: [] }; const cut = new Set();
+  const name = (e) => e.tagName.toLowerCase() + (e.id ? '#' + e.id : e.classList[0] ? '.' + e.classList[0] : '');
+  const own = (e) => [...e.childNodes].filter((n) => n.nodeType === 3 && n.data.trim()).map((n) => n.data).join(' ').replace(/\\s+/g, ' ').trim().slice(0, 40);
+  const clips = (e) => { const out = []; for (let a = e; a && a !== document.body && a !== document.documentElement; a = a.parentElement) { const s = getComputedStyle(a); if (s.overflowX !== 'visible' || s.overflowY !== 'visible') { const r = a.getBoundingClientRect(); out.push({ a, s, l: r.left + a.clientLeft, t: r.top + a.clientTop, r: r.left + a.clientLeft + a.clientWidth, b: r.top + a.clientTop + a.clientHeight }); } } return out; };
+  const shows = (b) => b.r - b.l > 1 && b.b - b.t > 1;
+  for (const e of document.querySelectorAll('body *')) {
+    const s = getComputedStyle(e); const rect = e.getBoundingClientRect();
+    if (!e.getClientRects().length || s.visibility !== 'visible' || rect.width < 1 || rect.height < 1) continue;
+    const boxes = clips(e.parentElement);
+    const box = boxes.reduce((v, c) => ({ l: Math.max(v.l, c.l), t: Math.max(v.t, c.t), r: Math.min(v.r, c.r), b: Math.min(v.b, c.b) }), { l: rect.left, t: rect.top, r: rect.right, b: rect.bottom });
+    if (!shows(box)) continue;
+    const text = own(e);
+    const parent = [...cut].some((c) => c.contains(e));
+    const edges = [box.l < -1 && 'left', box.r > vw + 1 && 'right', box.t < -1 && 'top'].filter(Boolean);
+    if (edges.length && box.r > 0 && box.l < vw && box.b > 0 && box.t < vh && !parent) { cut.add(e); out.cut_off.push({ element: name(e), text, edges }); }
+    if (!text) continue;
+    const t = { l: Infinity, t: Infinity, r: -Infinity, b: -Infinity };
+    for (const n of e.childNodes) if (n.nodeType === 3 && n.data.trim()) { const g = document.createRange(); g.selectNodeContents(n); for (const q of g.getClientRects()) if (q.width) { t.l = Math.min(t.l, q.left); t.t = Math.min(t.t, q.top); t.r = Math.max(t.r, q.right); t.b = Math.max(t.b, q.bottom); } }
+    if (t.l === Infinity || t.t >= vh || t.b <= 0) continue;
+    for (const c of clips(e)) {
+      if (c.r - c.l <= 1 || c.b - c.t <= 1 || !(t.r > c.l && t.l < c.r && t.b > c.t && t.t < c.b) || !['hidden', 'clip'].some((v) => v === c.s.overflowX || v === c.s.overflowY)) continue;
+      const x = ['hidden', 'clip'].includes(c.s.overflowX) && c.s.textOverflow !== 'ellipsis' && (t.l < c.l - 1 || t.r > c.r + 1);
+      const y = ['hidden', 'clip'].includes(c.s.overflowY) && c.s.webkitLineClamp === 'none' && (t.t < c.t - 1 || t.b > c.b + 1);
+      if (x || y) { out.clipped_text.push({ element: name(e), text, by: c.a === e ? 'its own box' : name(c.a) }); break; }
+    }
+  }
+  return { overflow: document.documentElement.scrollWidth > vw, overflowing: [...document.querySelectorAll('body *')].filter((e) => e.getBoundingClientRect().right > vw + 1).slice(0, 10).map(name), ...out };
+}`.replace(/\s*\n\s*/g, ' ');
 const isMap = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const strings = (a) => Array.isArray(a) && a.every((s) => typeof s === 'string');
+// An optional record list: absent, or every item has an element and text and passes `more`.
+const list = (a, more) => a === undefined || (Array.isArray(a) && a.every((q) => isMap(q) && typeof q.element === 'string' && typeof q.text === 'string' && more(q)));
 const badRegex = (s) => { try {
     new RegExp(s);
     return false;
@@ -71,13 +113,23 @@ export function domIssues(dom, capture) {
     }
     if (!isMap(r) || typeof r.url !== 'string' || typeof r.overflow !== 'boolean' || !strings(r.overflowing ?? []) || !strings(r.console_errors)
         || !Array.isArray(r.failed_requests) || !r.failed_requests.every((q) => isMap(q) && typeof q.url === 'string' && typeof q.status === 'number')
-        || (r.squashed_text !== undefined && !(Array.isArray(r.squashed_text) && r.squashed_text.every((q) => isMap(q) && typeof q.element === 'string' && typeof q.text === 'string' && [q.chars, q.lines, q.words].every((n) => typeof n === 'number')))))
-        return [`page-check record ${basename(path)} is not {url, overflow, overflowing, console_errors, failed_requests: [{url, status}], squashed_text: [{element, text, chars, lines, words}]}`];
+        || !list(r.squashed_text, (q) => [q.chars, q.lines, q.words].every((n) => typeof n === 'number'))
+        || !list(r.clipped_text, (q) => typeof q.by === 'string') || !list(r.cut_off, (q) => strings(q.edges)))
+        return [`page-check record ${basename(path)} is not {url, overflow, overflowing, console_errors, failed_requests: [{url, status}], squashed_text: [{element, text, chars, lines, words}], clipped_text: [{element, text, by}], cut_off: [{element, text, edges}]}`];
     const allowed = (list, s) => list.some((re) => new RegExp(re).test(s));
     return [
-        ...(dom.fail_on_overflow && r.overflow ? [`${r.url} overflows the viewport horizontally${r.overflowing?.length ? ` (${r.overflowing.join(', ')})` : ''}`] : []),
+        ...lookIssues({ ...r, overflow: dom.fail_on_overflow && r.overflow }),
         ...r.console_errors.filter((m) => !allowed(dom.allow_console, m)).map((m) => `${r.url} console error: ${m}`),
         ...r.failed_requests.filter((q) => (q.status === 0 || q.status >= 400) && !allowed(dom.allow_requests, q.url)).map((q) => `${r.url} request failed (${q.status || 'no response'}): ${q.url}`),
+    ];
+}
+// The look defects a page-check record shows: horizontal overflow, squashed, clipped and cut-off text or elements.
+export function lookIssues(r) {
+    const quoted = (t) => (t ? ` "${t}"` : '');
+    return [
+        ...(r.overflow ? [`${r.url} overflows the viewport horizontally${r.overflowing?.length ? ` (${r.overflowing.join(', ')})` : ''}`] : []),
         ...(r.squashed_text ?? []).map((q) => `${r.url} squashed text: ${q.element} "${q.text}" is ${q.chars} characters wide (lines ${q.lines}, words ${q.words})`),
+        ...(r.clipped_text ?? []).map((q) => `${r.url} clipped text: ${q.element}${quoted(q.text)} is cut by ${q.by}`),
+        ...(r.cut_off ?? []).map((q) => `${r.url} cut off: ${q.element}${quoted(q.text)} runs past the ${q.edges.join(' and ')} edge of the viewport`),
     ];
 }