done-done-axi 0.6.3 → 0.6.5

package/dist/cli.js

@@ -128,6 +128,8 @@ const FLAGS = {
     '--run <run-id>': 'the run to show (default: the newest run of this checkout)',
     '--probe': 'ask the configured agent one JSON-schema question and require a valid answer (one call at the agent\'s model: its cheap default where it has one, else its own; set agent_config.<agent>.model to choose)',
     '--mock <screen>=<mock>': 'judge this screen next to its approved mock (repeat per screen; the screen is judged even when not listed)',
+    '--mock <file>': 'with look: the approved design of this page (PNG or JPEG); the judge the user set compares the capture with it, as design --mock does, and a defect fails look',
+    '--act <selector>': 'with look: click the element this CSS selector names, then require the page to change what a user can read (its text, elements or address) within 5s; repeat to click several in order; look measures and captures the page they leave',
     '--step <name>': 'the step log to show (verify: resolve, drive, check, judge, gate, receipt, report; maintain: locate, hygiene, source-wave, reconcile, triage, fix, report)',
     '--feature <name>': 'with no journey, the author agent drives this feature of the verify skill (features/<name>.md); default: the only feature, else the agent picks the one the outcome is about',
     '--action <approve|skip|fix>': 'at a spend gate, approve: spend and run the journey; skip: end the run with nothing spent. At the judge gate only fix or skip: fix ends it fail, then the product or the verify skill is fixed (done-done maintain checks it against the source); skip ends it fail without the fix',
@@ -220,12 +222,14 @@ const COMMANDS = {
   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
+        usage: [['done-done look <url> [--act <selector>]... [--mock <file>] [--out <file.png>]', 'open a page in headless Chrome at a phone viewport, click each action, capture it with its page-check record, and fail on any squashed, clipped or cut-off UI, an action that changes nothing, or a mismatch with the design']],
+        flags: ['--act <selector>', '--mock <file>', '--out <file.png>'],
+        more: [`look: one step a journey calls as its command or inside its script; with no --mock, no judge and 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)`],
+  screenshot and its .dom.json record, and exits 1 naming each element, kind and text, 0 when there is none. Each --act is
+  clicked and must change the page. With a look block in .done-done.yaml (the approved reference: tokens, max_control) it
+  also fails on a control drawn as the browser's own and on one taller than max_control. A hit always fails: never wrap it
+  in || true. Exit 3 when the only doubt is an unsure judge. Needs Chrome or Chromium (DONE_DONE_CHROME names the binary)`],
     },
     gate: {
         usage: [['done-done gate [<head>] [--dir <folder>] [--pushed <time>]', 'no-model check for a hosted runner: PASS or FAIL: <reason> for a receipt committed under .done-done-receipts/']],
@@ -764,6 +768,7 @@ async function runCheck(argv, run) {
     const captures = [];
     // The run behind each cited capture, for the real-product rule and the receipt.
     const runs = new Map();
+    const warnings = [];
     // base_ref: a capture in <run id>/before/ of a run that drove its base ref pairs with <run id>/<the same name>.
     const pairOf = (inRoot) => {
         const [id, dir, ...rest] = inRoot?.split(sep) ?? [];
@@ -809,7 +814,7 @@ async function runCheck(argv, run) {
         const inRoot = under(cfg.evidence.root, path);
         const pair = pairOf(inRoot);
         if (cfg.dom && !pair && ['png', 'jpeg', 'webp', 'gif', 'mp4', 'webm'].includes(v.type))
-            for (const why of domIssues(cfg.dom, path))
+            for (const why of domIssues(cfg.dom, path, cfg.look))
                 findings.push({ level: 'fail', why: `${name}: ${why}` });
         // A base capture may equal its head capture byte for byte: the pair's judge, not this check, says the screen did not change.
         if (seen.has(hash) && !record && !pair)
@@ -839,7 +844,7 @@ async function runCheck(argv, run) {
             continue;
         }
         const rec = (atNow.length ? atNow : claims).reduce((a, b) => (b.started_at > a.started_at ? b : a));
-        runs.set(rec.run_id, { run_id: rec.run_id, journey: rec.journey, command: rec.command, ...(rec.feature && { feature: rec.feature }), ...(rec.tool && { tool: rec.tool }), ...(rec.steps && { steps: rec.steps }), ...(rec.steps_error && { steps_error: rec.steps_error }) });
+        runs.set(rec.run_id, { run_id: rec.run_id, commit: rec.commit, journey: rec.journey, command: rec.command, ...(rec.feature && { feature: rec.feature }), ...(rec.tool && { tool: rec.tool }), ...(rec.steps && { steps: rec.steps }), ...(rec.steps_error && { steps_error: rec.steps_error }) });
         // Only a capture tied to a run record can reach the judge, so a stray cited file is never sent.
         const c = { name, bytes, sha256: hash, media: v };
         if (v.status === 'ok' && !record && pair)
@@ -849,7 +854,11 @@ async function runCheck(argv, run) {
             if (rec.base)
                 heads.push([c, inRoot, rec]);
         }
-        const stale = staleness(repo, cfg, rec.commit, now.commit);
+        const kept = [];
+        const stale = staleness(repo, cfg, rec.commit, now.commit, rec, kept);
+        for (const w of kept)
+            if (!warnings.includes(w))
+                warnings.push(w);
         if (stale)
             findings.push({ level: 'fail', why: `${name}: ${stale} (run ${rec.run_id})` });
         if (rec.dirty && !cfg.evidence.allow_dirty)
@@ -873,7 +882,6 @@ async function runCheck(argv, run) {
     if (codeRuns)
         findings.push({ level: 'fail', why: codeRuns });
     // The user steps behind the captures: a cited real run needs a step record covering the claim. Runs from before step records warn.
-    const warnings = [];
     if (claim && runs.size && !codeRuns) {
         const s = stepsFault([...runs.values()], claim.outcome);
         if (s.fault)
@@ -1079,7 +1087,7 @@ function recordReceipt(repo, cfg, r) {
     return { code: PASS, result: { ...result, ...(r.judge && { judge: r.judge }), help: [`Verify this receipt (merge gate): done-done receipt --verify ${r.head.commit}`] } };
 }
 // Why evidence from `from` no longer proves `to`, or '' if it still does.
-function staleness(repo, cfg, from, to) {
+function staleness(repo, cfg, from, to, run, warnings = []) {
     if (from === to)
         return '';
     let changed;
@@ -1092,6 +1100,19 @@ function staleness(repo, cfg, from, to) {
     const outside = changed.filter((p) => !cfg.evidence.ignore_paths.some((g) => matchesGlob(p, g)));
     if (changed.length && !outside.length)
         return '';
+    // A head change that touches no journey or feature the run covered leaves its proof valid; both commits are reported.
+    const needs = outside.filter((p) => !p.startsWith(`${GATE_DIR}/`));
+    if (run && (run.journey || run.feature) && needs.length) {
+        const m = mapDiff(repo, cfg, needs, git(repo, 'ls-files', '-z').split('\0').filter(Boolean));
+        if (!m.journeys.some((j) => j.name === run.journey) && !m.features.some((f) => f.name === run.feature)) {
+            warnings.push(`run ${run.run_id} is for commit ${from.slice(0, 12)} and HEAD is ${to.slice(0, 12)}: its ${run.journey ? `journey ${run.journey}` : `feature ${run.feature}`} is untouched by the ${needs.length} changed file${needs.length === 1 ? '' : 's'} (done-done affected)`);
+            return '';
+        }
+    }
+    if (run && changed.length && !needs.length) {
+        warnings.push(`run ${run.run_id} is for commit ${from.slice(0, 12)} and HEAD is ${to.slice(0, 12)}: only gate receipts changed`);
+        return '';
+    }
     return `evidence is for commit ${from.slice(0, 12)}, HEAD is ${to.slice(0, 12)}${outside.length ? ` (changed: ${outside.slice(0, 3).join(', ')}${outside.length > 3 ? ', ...' : ''})` : ''}`;
 }
 // Quote an argument only when a shell would split it.
@@ -3812,9 +3833,9 @@ async function cmdDoctor(argv) {
     emit(result);
     return missingRequired.length ? USAGE : PASS;
 }
-// The design check: every named screen, and each --mock screen, judged for visual defects.
+// The look step: one page measured, with its actions clicked, against the project's look reference and the --mock design.
 async function cmdLook(argv) {
-    const { values, positionals } = parseArgs({ args: argv, options: { out: { type: 'string' } }, allowPositionals: true });
+    const { values, positionals } = parseArgs({ args: argv, options: { out: { type: 'string' }, mock: { type: 'string' }, act: { type: 'string', multiple: true } }, 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.
@@ -3822,23 +3843,36 @@ async function cmdLook(argv) {
     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`);
+    const cfg = loadConfig(repoOrCwd());
+    // The mock and the judge are checked before Chrome starts, so a bad one costs no capture.
+    const mock = values.mock === undefined ? undefined : loadScreen(values.mock);
+    const choice = mock && (await preflightJudge(cfg, false));
     mkdirSync(dirname(capture), { recursive: true });
-    const record = await look(url, capture, 390, 844);
-    const hits = lookIssues(record);
+    const record = await look(url, capture, 390, 844, values.act ?? []);
+    const hits = lookIssues(record, cfg.look);
+    const [judged] = mock && choice ? await design(cfg, choice, [{ ...loadScreen(capture), mock }], join(home(), 'agents')) : [];
+    for (const d of judged?.defects ?? [])
+        hits.push(`${url} differs from the approved design ${values.mock}: ${d.kind}: ${d.where}`);
+    const code = hits.length ? FAIL : judged?.verdict === 'unsure' ? INCONCLUSIVE : PASS;
     const shown = cap(hits);
+    const again = `done-done look ${[positionals[0], ...(values.act ?? []).flatMap((a) => ['--act', a]), ...(values.mock ? ['--mock', values.mock] : []), ...(values.out ? ['--out', values.out] : [])].map(quote).join(' ')}`;
     emit({
         command: 'look',
         // look measures the layout; it gives no verdict on the outcome, which only the judged check does.
-        result: hits.length ? 'fail' : 'clean',
+        result: code === FAIL ? 'fail' : code === INCONCLUSIVE ? 'inconclusive' : 'clean',
         url,
         viewport: '390x844',
         capture,
         record: domRecord(capture),
+        ...(cfg.look && { reference: { ...cfg.look, ...(values.mock && { mock: values.mock }) } }),
+        ...(judged && { judge: { route: choice.route, model: choice.model, verdict: judged.verdict, ...(judged.reason && { reason: judged.reason }), ...(judged.cached && { cached: true }) } }),
         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'],
+        help: code === FAIL ? [`Fix each element or action named above so it fits the 390 px wide screen, the design and its reference, then re-run: ${again}`]
+            : code === INCONCLUSIVE ? [`The judge is unsure the page matches ${values.mock}: look at both yourself, then re-run: ${again}`]
+                : ['No squashed, clipped or cut-off UI on this page; look at the capture to check the rest'],
     });
-    return hits.length ? FAIL : PASS;
+    return code;
 }
 // The folder of a branch where a receipt copied from the evidence root is committed, for `gate`.
 const GATE_DIR = '.done-done-receipts';
@@ -3916,6 +3950,25 @@ function cmdLint(argv) {
     console.log(!v.ok ? `FAIL: ${v.why}` : v.warn ? `WARN: ${v.warn}` : 'PASS');
     return v.ok ? PASS : FAIL;
 }
+// A screen or mock file for the design judge.
+function loadScreen(name) {
+    let bytes;
+    try {
+        bytes = readFileSync(name);
+    }
+    catch (e) {
+        throw new UsageError(`${name}: cannot read (${e.code ?? e.message})`, 'Pass screen and mock files that exist');
+    }
+    return { name, bytes, sha256: sha256(bytes), media: checkMedia(name, bytes) };
+}
+function repoOrCwd() {
+    try {
+        return repoRoot();
+    }
+    catch {
+        return process.cwd();
+    }
+}
 async function cmdDesign(argv) {
     const { values, positionals } = parseArgs({ args: argv, options: { mock: { type: 'string', multiple: true } }, allowPositionals: true });
     const mocks = new Map();
@@ -3928,25 +3981,8 @@ async function cmdDesign(argv) {
     const names = [...new Set([...positionals, ...[...mocks.keys()].filter((p) => !positionals.some((n) => resolve(n) === p))])];
     if (!names.length)
         throw new UsageError('design needs at least one screen file', 'Re-run with the screens to check: done-done design <screens...>');
-    const load = (name) => {
-        let bytes;
-        try {
-            bytes = readFileSync(name);
-        }
-        catch (e) {
-            throw new UsageError(`${name}: cannot read (${e.code ?? e.message})`, 'Pass screen and mock files that exist');
-        }
-        return { name, bytes, sha256: sha256(bytes), media: checkMedia(name, bytes) };
-    };
-    const screens = names.map((n) => ({ ...load(n), ...(mocks.has(resolve(n)) && { mock: load(mocks.get(resolve(n))) }) }));
-    let repo;
-    try {
-        repo = repoRoot();
-    }
-    catch {
-        repo = process.cwd();
-    }
-    const cfg = loadConfig(repo);
+    const screens = names.map((n) => ({ ...loadScreen(n), ...(mocks.has(resolve(n)) && { mock: loadScreen(mocks.get(resolve(n))) }) }));
+    const cfg = loadConfig(repoOrCwd());
     const choice = await preflightJudge(cfg, false);
     const judged = await design(cfg, choice, screens, join(home(), 'agents'));
     const count = (v) => judged.filter((j) => j.verdict === v).length;
@@ -3992,6 +4028,13 @@ function defaultBranch(repo) {
     }
 }
 const isAncestor = (repo, a, b) => spawnSync('git', ['merge-base', '--is-ancestor', a, b], { cwd: repo, stdio: 'ignore' }).status === 0;
+// The journeys and features `changed` needs (src/affected.ts), from the verify skill at the working tree.
+function mapDiff(repo, cfg, changed, tracked, noBase) {
+    const featDir = join(repo, cfg.skill, 'features');
+    const features = Object.fromEntries(skillFeatures(repo, cfg).map((n) => [n, repoText(join(featDir, `${n}.md`)) ?? '']));
+    const coreLine = featureMap(repo, cfg).split('\n').find((l) => /^\s*[-*] /.test(l) && l.includes(MARK.core));
+    return mapChange({ changed, tracked, journeys: cfg.journeys, skill: cfg.skill, features, coreFeature: coreLine?.match(/\]\(([^)#]+)\.md\)/)?.[1], noBase });
+}
 // Which journeys the change needs (src/affected.ts) and whether HEAD's proof covers them. The change is read from `baseArg`,
 // else from the newest receipt before HEAD (the commits since the last proof), else from the merge base with the default
 // branch; with none, the mapping is uncertain and the core journey is needed.
@@ -4025,10 +4068,7 @@ function affectedOf(repo, cfg, baseArg) {
     // Untracked files are no part of the change until added, as everywhere else in done-done.
     const uncommitted = list('diff', '--name-only', '--no-renames', '-z', 'HEAD').filter(counts);
     const changed = [...new Set([...(base ? list('diff', '--name-only', '--no-renames', '-z', base.commit, 'HEAD').filter(counts) : []), ...uncommitted])];
-    const featDir = join(repo, cfg.skill, 'features');
-    const features = Object.fromEntries(skillFeatures(repo, cfg).map((n) => [n, repoText(join(featDir, `${n}.md`)) ?? '']));
-    const coreLine = featureMap(repo, cfg).split('\n').find((l) => /^\s*[-*] /.test(l) && l.includes(MARK.core));
-    const m = mapChange({ changed, tracked, journeys: cfg.journeys, skill: cfg.skill, features, coreFeature: coreLine?.match(/\]\(([^)#]+)\.md\)/)?.[1], noBase: base ? undefined : 'no receipt before HEAD and no default branch to diff against' });
+    const m = mapDiff(repo, cfg, changed, tracked, base ? undefined : 'no receipt before HEAD and no default branch to diff against');
     const needed = [...m.journeys.map((j) => j.name), ...m.features.map((f) => `feature ${f.name}`)];
     // Proof: a valid receipt for HEAD whose runs include every journey and feature the change needs, with nothing uncommitted.
     const verified = verifyReceipt(repo, cfg, 'HEAD');

package/dist/config.js

@@ -1,9 +1,9 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, isAbsolute, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { parse } from 'yaml';
 import { checkMatrix } from './matrix.js';
-import { parseDom } from './dom.js';
+import { parseDom, parseLook } from './dom.js';
 export class UsageError extends Error {
     help;
     // The exact next command, when the error has one.
@@ -66,6 +66,7 @@ const KEYS = {
     instance: { scope: 'repo', type: 'instance' },
     matrix: { scope: 'repo', type: 'matrix' },
     dom: { scope: 'repo', type: 'dom' },
+    look: { scope: 'repo', type: 'look' },
     base_ref: { scope: 'repo', type: 'string' },
     'evidence.root': { scope: 'repo', type: 'string' },
     'evidence.allow_dirty': { scope: 'repo', type: 'boolean' },
@@ -219,6 +220,14 @@ function apply(target, text, file, scope) {
             target.dom = d;
             continue;
         }
+        if (key === 'look') {
+            const l = parseLook(value, dirname(file));
+            if (typeof l === 'string')
+                throw new UsageError(`${file}: look ${l}`);
+            target.from[key] = scope;
+            target.look = l;
+            continue;
+        }
         if (!ok)
             throw new UsageError(`${file}: ${key} must be ${want[spec.type] ?? `a ${spec.type}`}${key === 'matrix' ? `: ${checkMatrix(value)}` : ''}`);
         if (key === 'agent_config')
@@ -279,6 +288,7 @@ function defaultConfig(repo) {
         instance: null,
         matrix: null,
         dom: null,
+        look: null,
         base_ref: '',
         evidence: { local_root: join(home(), 'evidence'), root: '', allow_dirty: false, ignore_paths: [] },
         secrets: { patterns: {}, allow: [] },

package/dist/dom.js

@@ -5,10 +5,12 @@
 //    "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>}],
 //    "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.
+//    "cut_off": [{"element": "<element>", "text": "<its text>", "edges": ["left" | "right" | "top", ...]}],
+//    "controls": [{"element": "<element>", "text": "<its label>", "native": <true when drawn as the browser's own control>, "height": <px, absent for a textarea or list box>}],
+//    "actions": [{"selector": "<what was clicked>", "text": "<its label>", "failed": "<why it did not complete, absent when it did>"}]}
+// squashed_text, clipped_text, cut_off, controls and actions are optional, so a record written before them stays valid.
 import { readFileSync } from 'node:fs';
-import { basename } from 'node:path';
+import { basename, resolve } from 'node:path';
 // The measurement the recipe passes to its browser tool's eval, so no agent invents one: every visible element with its
 // own non-empty text is squashed when its box is under 8 characters wide (box width / the average glyph width of its
 // font) while its text is wider than the box, or when its text sits on more line boxes than it has words.
@@ -67,6 +69,39 @@ export const LOOK = `() => {
   }
   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, ' ');
+// Every visible control with its label and height, and whether it is drawn as the browser's own: its background and
+// border are what the browser gives the same control (same tag, input type and colour scheme) on a page with no styles.
+// A checkbox, radio, range, colour or file input is not measured, and a textarea or list box has no height to hold.
+export const CONTROLS = `() => {
+  const name = (e) => e.tagName.toLowerCase() + (e.id ? '#' + e.id : e.classList[0] ? '.' + e.classList[0] : '');
+  const f = document.createElement('iframe'); f.style.cssText = 'position:fixed;width:0;height:0;border:0'; document.documentElement.append(f);
+  const d = f.contentDocument; d.open(); d.write('<!doctype html><body>'); d.close();
+  const keys = ['backgroundColor', 'borderTopStyle', 'borderTopWidth', 'borderTopColor', 'borderTopLeftRadius']; const out = [];
+  for (const e of document.querySelectorAll('button, select, textarea, input, [role=button]')) {
+    const s = getComputedStyle(e); const r = e.getBoundingClientRect();
+    if (!e.getClientRects().length || s.visibility !== 'visible' || r.width < 1 || r.height < 1 || (e.tagName === 'INPUT' && ['checkbox', 'radio', 'range', 'color', 'file'].includes(e.type))) continue;
+    let native = false;
+    if (['BUTTON', 'SELECT', 'TEXTAREA', 'INPUT'].includes(e.tagName)) { const t = d.createElement(e.tagName); if (e.tagName === 'INPUT') t.type = e.type; t.style.colorScheme = s.colorScheme; d.body.append(t); const u = f.contentWindow.getComputedStyle(t); native = keys.every((k) => s[k] === u[k]); }
+    const tall = e.tagName === 'TEXTAREA' || (e.tagName === 'SELECT' && (e.multiple || e.size > 1));
+    out.push({ element: name(e), text: (e.getAttribute('aria-label') || e.innerText || e.value || e.placeholder || '').replace(/\\s+/g, ' ').trim().slice(0, 40), native, ...(!tall && { height: Math.round(r.height) }) });
+  }
+  f.remove(); return out;
+}`.replace(/\s*\n\s*/g, ' ');
+// What a user can read of the page: its address, how many elements it has and its visible text. An action completes when
+// this changes: a card moves, a reply shows as saved, a toast says so.
+const STATE = "(() => location.href + '\\n' + document.querySelectorAll('body *').length + '\\n' + document.body.innerText)()";
+// Where to click the action `sel` names, with its label and the page state before it, or why it cannot be clicked.
+export const AIM = `(sel) => {
+  const e = document.querySelector(sel); if (!e) return { text: '', failed: 'is not on the page' };
+  e.scrollIntoView({ block: 'center' }); const r = e.getBoundingClientRect(); const x = r.left + r.width / 2; const y = r.top + r.height / 2;
+  const text = (e.getAttribute('aria-label') || e.innerText || e.value || '').replace(/\\s+/g, ' ').trim().slice(0, 40);
+  if (e.disabled || e.getAttribute('aria-disabled') === 'true') return { text, failed: 'is disabled' };
+  const hit = document.elementFromPoint(x, y);
+  if (!hit || (hit !== e && !e.contains(hit))) return { text, failed: 'is covered by ' + (hit ? hit.tagName.toLowerCase() + (hit.id ? '#' + hit.id : hit.classList[0] ? '.' + hit.classList[0] : '') : 'nothing that takes a click') };
+  return { text, x, y, before: ${STATE} };
+}`.replace(/\s*\n\s*/g, ' ');
+// Whether the page state differs from `before` within `ms`, checked each 50 ms.
+export const CHANGED = `async (before, ms) => { for (let t = 0; t <= ms; t += 50) { if (${STATE} !== before) return true; await new Promise((r) => setTimeout(r, 50)); } return false; }`;
 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`.
@@ -100,8 +135,41 @@ export function parseDom(v) {
         return 'fail_on_overflow must be true or false';
     return { allow_console: v.allow_console ?? [], allow_requests: v.allow_requests ?? [], fail_on_overflow: v.fail_on_overflow ?? true };
 }
+// The look block read from config in `repo`, or the reason it is not one. max_control is a number of px, or the name of
+// a custom property in the tokens file (--ctl-h: 2.75rem), read as px with a rem or em of 16 px.
+export function parseLook(v, repo) {
+    if (v == null)
+        v = {};
+    if (!isMap(v))
+        return 'a mapping with optional tokens and max_control';
+    for (const k of Object.keys(v))
+        if (!['tokens', 'max_control'].includes(k))
+            return `unknown key ${k} (tokens, max_control)`;
+    const { tokens, max_control: max } = v;
+    if (tokens !== undefined && (typeof tokens !== 'string' || !tokens))
+        return 'tokens must be the path of the design tokens file';
+    if (typeof max === 'number')
+        return max > 0 ? { ...(tokens && { tokens }), max_control: max } : 'max_control must be more than 0 px';
+    if (max === undefined)
+        return tokens ? { tokens } : {};
+    if (typeof max !== 'string' || !/^--[\w-]+$/.test(max))
+        return 'max_control must be a number of px or the name of a token such as --ctl-h';
+    if (!tokens)
+        return `max_control ${max} names a token, so tokens must name the file that sets it`;
+    let text;
+    try {
+        text = readFileSync(resolve(repo, tokens), 'utf8');
+    }
+    catch (e) {
+        return `tokens ${tokens} does not read: ${e.code ?? e.message}`;
+    }
+    const m = new RegExp(`(?<![\\w-])${max}\\s*:\\s*([\\d.]+)(px|rem|em)\\s*[;}]`).exec(text);
+    if (!m)
+        return `max_control ${max} is not set in ${tokens} as a px, rem or em size`;
+    return { tokens, max_control: Number(m[1]) * (m[2] === 'px' ? 1 : 16) };
+}
 // Every non-allowed issue the capture's page-check record shows; a missing or malformed record is an issue too.
-export function domIssues(dom, capture) {
+export function domIssues(dom, capture, ref) {
     const path = domRecord(capture);
     let r;
     try {
@@ -114,22 +182,28 @@ 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')
         || !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}]}`];
+        || !list(r.clipped_text, (q) => typeof q.by === 'string') || !list(r.cut_off, (q) => strings(q.edges))
+        || !list(r.controls, (q) => typeof q.native === 'boolean' && ['number', 'undefined'].includes(typeof q.height))
+        || !(r.actions === undefined || (Array.isArray(r.actions) && r.actions.every((q) => isMap(q) && typeof q.selector === 'string' && typeof q.text === 'string' && ['string', 'undefined'].includes(typeof q.failed)))))
+        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}], controls: [{element, text, native, height}], actions: [{selector, text, failed}]}`];
     const allowed = (list, s) => list.some((re) => new RegExp(re).test(s));
     return [
-        ...lookIssues({ ...r, overflow: dom.fail_on_overflow && r.overflow }),
+        ...lookIssues({ ...r, overflow: dom.fail_on_overflow && r.overflow }, ref),
         ...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) {
+// The look defects a page-check record shows: horizontal overflow, squashed, clipped and cut-off text or elements, and an
+// action that did not complete; against a reference, also a control drawn as the browser's own or taller than max_control.
+export function lookIssues(r, ref) {
     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`),
+        ...(ref ? r.controls ?? [] : []).filter((q) => q.native).map((q) => `${r.url} unstyled control: ${q.element}${quoted(q.text)} is drawn as the browser's own control, not with the design's style`),
+        ...(ref?.max_control ? r.controls ?? [] : []).filter((q) => q.height > ref.max_control + 0.5).map((q) => `${r.url} oversized control: ${q.element}${quoted(q.text)} is ${q.height} px tall, over the ${ref.max_control} px the design allows`),
+        ...(r.actions ?? []).filter((q) => q.failed).map((q) => `${r.url} action did not complete: ${q.selector}${quoted(q.text)} ${q.failed}`),
     ];
 }

package/dist/lint.js

@@ -1,6 +1,7 @@
 // `done-done lint`: the deterministic merge gate on a worker's claim. It reads the newest "## Checks" block of a PR body
 // or report file and fails an unproven, reused or oversized claim. No judge, no model; the repo config only switches on
-// the two optional size rules (checks.upstream_catch_up, checks.moved_from) and extra generated paths (checks.generated_paths).
+// the two optional size rules (checks.upstream_catch_up, checks.moved_from) and extra generated paths (checks.generated_paths);
+// files the target repo marks generated in .gitattributes are not counted either.
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs';
@@ -8,6 +9,26 @@ import { basename, dirname, isAbsolute, join, matchesGlob, resolve } from 'node:
 // Third-party, legal text and committed build output are not reviewable code.
 const GENERATED = /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.lock|go\.sum|[^/]*\.lock)$|(^|\/)vendor\/|(^|\/)dist\/|(^|\/)(LICENSE|LICENSES|NOTICE|COPYING)[^/]*$/;
 const generatedBy = (globs = []) => (p) => GENERATED.test(p) || globs.some((g) => matchesGlob(p, g));
+// A target repo's own .gitattributes marks generated files: linguist-generated, linguist-generated=true or -diff. The last matching line wins;
+// linguist-generated=false and an unset attribute mean not generated. A pattern with no slash matches the basename, like git.
+function attrGenerated(attrs) {
+    const rules = attrs.split('\n').map((l) => l.trim().split(/\s+/)).filter((w) => w[0] && !w[0].startsWith('#') && w.length > 1);
+    return (p) => {
+        let gen = false;
+        for (const [pat, ...as] of rules) {
+            const glob = pat.replace(/^\//, '');
+            if (!matchesGlob(glob.includes('/') ? p : basename(p), glob.endsWith('/') ? `${glob}**` : glob))
+                continue;
+            for (const a of as) {
+                if (/^(linguist-generated(=true)?|-diff)$/.test(a))
+                    gen = true;
+                else if (/^(linguist-generated=false|-linguist-generated|!linguist-generated)$/.test(a))
+                    gen = false;
+            }
+        }
+        return gen;
+    };
+}
 export const SIZE_LIMIT = 1000;
 const FIX_TITLE = /^(fix|bugfix|hotfix)\b/i;
 const NOT_APPLICABLE = /^n\/?a\b/i;
@@ -70,7 +91,8 @@ function movedLines(run, nwo, body, paths, isGenerated) {
 const sha256 = (p) => createHash('sha256').update(readFileSync(p)).digest('hex');
 // src: a PR URL or a report file; ev: the folder the evidence names are relative to; dir: where the hash store and log live.
 export function lint(src, ev, dir, rules = {}, run = gh) {
-    const isGenerated = generatedBy(rules.generated_paths);
+    const byConfig = generatedBy(rules.generated_paths);
+    let isGenerated = byConfig;
     let warn = ''; // set for a PR that touches src/ with no journeys/ file; it only softens a PASS
     const log = (v) => {
         if (v.ok && warn)
@@ -95,6 +117,12 @@ export function lint(src, ev, dir, rules = {}, run = gh) {
         const author = pr.author?.login ?? '';
         if (/^(app\/)?(dependabot|renovate)(\[bot\])?$/.test(author))
             return log({ ok: true, why: 'bot', head });
+        const nwo = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\//.exec(src)?.[1];
+        const attrs = nwo && [head, pr.baseRefOid].map((ref) => ref && run('api', '-H', 'Accept: application/vnd.github.raw', `repos/${nwo}/contents/.gitattributes?ref=${ref}`)).find((a) => a && a.status === 0);
+        if (attrs) {
+            const byAttr = attrGenerated(attrs.stdout);
+            isGenerated = (p) => byConfig(p) || byAttr(p);
+        }
         const paths = (pr.files ?? []).map((f) => f.path ?? '');
         if (paths.some((p) => p.startsWith('src/')) && !paths.some((p) => p.startsWith('journeys/')))
             warn = 'the diff changes src/ and no journeys/ file: run the journey, commit it, then open the PR';
@@ -103,7 +131,6 @@ export function lint(src, ev, dir, rules = {}, run = gh) {
             const d = run('pr', 'diff', src);
             if (!d.status) {
                 let net = netLines(d.stdout, isGenerated);
-                const nwo = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\//.exec(src)?.[1];
                 if (nwo && rules.upstream_catch_up && total(net) >= SIZE_LIMIT)
                     net = without(net, upstreamDelta(run, nwo, head, pr.baseRefOid ?? '', isGenerated));
                 if (nwo && rules.moved_from && total(net) >= SIZE_LIMIT)

package/dist/look.js

@@ -3,14 +3,17 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { UsageError } from './config.js';
-import { domRecord, LOOK, SQUASHED_TEXT } from './dom.js';
+import { AIM, CHANGED, CONTROLS, domRecord, LOOK, SQUASHED_TEXT } from './dom.js';
 import { findBin } from './agents.js';
 // done-done look: opens one page in headless Chrome at a phone viewport over the DevTools protocol (Node's own
-// WebSocket, no browser library), writes the screenshot and its page-check record next to it, and returns the record.
+// WebSocket, no browser library), clicks each action in `acts` in order (a CSS selector each) and waits for it to complete,
+// then writes the screenshot and its page-check record next to it, and returns the record.
 // Chrome runs without its sandbox so it starts in containers: point look at your own app, not untrusted sites.
 const BROWSERS = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'];
 const WAIT = 30_000;
-export async function look(url, capture, width, height) {
+// How long an action has to change what a user can read of the page.
+const ACT = 5_000;
+export async function look(url, capture, width, height, acts = []) {
     const bin = process.env.DONE_DONE_CHROME ? findBin(process.env.DONE_DONE_CHROME) : BROWSERS.map(findBin).find(Boolean);
     if (!bin)
         throw new UsageError(`look needs Chrome or Chromium: ${process.env.DONE_DONE_CHROME ? `DONE_DONE_CHROME=${process.env.DONE_DONE_CHROME} is not an executable` : `none of ${BROWSERS.slice(0, 4).join(', ')} is on PATH`}`, 'Install Chrome or Chromium, or set DONE_DONE_CHROME to its binary');
@@ -93,8 +96,23 @@ export async function look(url, capture, width, height) {
             throw new Error(`${url} did not load: ${nav.errorText}`);
         await loaded;
         // Web fonts change text widths, so measure once they are in and two frames have painted.
-        await evaluate('document.fonts.ready.then(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))))');
-        const record = { url, ...(await evaluate(`(${LOOK})()`)), console_errors: consoleErrors, failed_requests: failed, squashed_text: await evaluate(`(${SQUASHED_TEXT})()`) };
+        const settle = () => evaluate('document.fonts.ready.then(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))))');
+        await settle();
+        // Each action is a real click at its centre, so a control under a toast or overlay fails as covered.
+        const actions = [];
+        for (const selector of acts) {
+            const at = await evaluate(`(${AIM})(${JSON.stringify(selector)})`);
+            if (!at.failed) {
+                for (const type of ['mousePressed', 'mouseReleased'])
+                    await send('Input.dispatchMouseEvent', { type, x: at.x, y: at.y, button: 'left', clickCount: 1 });
+                if (!(await evaluate(`(${CHANGED})(${JSON.stringify(at.before)}, ${ACT})`)))
+                    at.failed = `changed nothing a user can read on the page (its text, elements or address) within ${ACT / 1000}s`;
+            }
+            actions.push({ selector, text: at.text, ...(at.failed && { failed: at.failed }) });
+        }
+        if (acts.length)
+            await evaluate('scrollTo(0, 0)').then(settle);
+        const record = { url, ...(await evaluate(`(${LOOK})()`)), console_errors: consoleErrors, failed_requests: failed, squashed_text: await evaluate(`(${SQUASHED_TEXT})()`), controls: await evaluate(`(${CONTROLS})()`), ...(acts.length && { actions }) };
         const shot = await send('Page.captureScreenshot', { format: 'png' });
         writeFileSync(capture, Buffer.from(shot.data, 'base64'));
         writeFileSync(domRecord(capture), `${JSON.stringify(record, null, 2)}\n`);

package/docs/examples/statechart-pilot/PaneAttach.tla

@@ -0,0 +1,151 @@
+------------------------------ MODULE PaneAttach ------------------------------
+(* Two Herdr panes, one shared tree refresh and one attach, as muxr v0.2.9 runs  *)
+(* them on @byokit/herdr 0.16.1. Pane A closes; pane B survives and is the pane  *)
+(* the user opens. Each action names the code it stands for; see README.md.      *)
+EXTENDS FiniteSets
+
+CONSTANTS
+    Matched,     \* reply-id shapes socket.js counts as a refusal of its own watch
+    DrainsQueue  \* runBootstrap starts the queued follow-up (FALSE: broken variant)
+
+Panes   == {"A", "B"}
+Callers == {"R", "U"}  \* R: any other refresh caller; U: the user's attach to B
+\* Herdr answers a watch on a closed pane with id "<id>:sub:0:probe" (muxr PR 1006).
+RefusalShape == "subProbe"
+
+VARIABLES
+    alive,        \* Herdr: the pane exists
+    closedEvt,    \* A's pane_closed event is on its way to the kit's event socket
+    booting,      \* kit.js `booting`
+    queued,       \* kit.js `queued`
+    phase,        \* runBootstrap: "idle", "reading" (snapshot in flight), "acks"
+    waiters,      \* kit.js `waiters`
+    nextWaiters,  \* kit.js `nextWaiters`
+    watch,        \* per-pane status watch socket
+    ready,        \* that watch's `ready` promise
+    refusal,      \* Herdr has refused this pane's watch (the pane is gone for good)
+    caller        \* each refresh() caller
+
+vars == <<alive, closedEvt, booting, queued, phase, waiters, nextWaiters,
+          watch, ready, refusal, caller>>
+
+TypeOK ==
+    /\ alive \in [Panes -> BOOLEAN]
+    /\ closedEvt \in BOOLEAN /\ booting \in BOOLEAN /\ queued \in BOOLEAN
+    /\ phase \in {"idle", "reading", "acks"}
+    /\ waiters \subseteq Callers /\ nextWaiters \subseteq Callers
+    /\ watch \in [Panes -> {"none", "opening", "retry", "open", "stopped"}]
+    /\ ready \in [Panes -> {"none", "pending", "ok", "refused"}]
+    /\ refusal \in [Panes -> BOOLEAN]
+    /\ caller \in [Callers -> {"idle", "waiting", "done"}]
+
+\* The kit has started: its first bootstrap landed and both watches acked.
+Init ==
+    /\ alive = [p \in Panes |-> TRUE]
+    /\ closedEvt = FALSE /\ booting = FALSE /\ queued = FALSE /\ phase = "idle"
+    /\ waiters = {} /\ nextWaiters = {}
+    /\ watch = [p \in Panes |-> "open"]
+    /\ ready = [p \in Panes |-> "ok"]
+    /\ refusal = [p \in Panes |-> FALSE]
+    /\ caller = [c \in Callers |-> "idle"]
+
+\* runBootstrap -> bootstrap sends `session.snapshot` (kit.js:523-530, 363-371).
+StartBoot == booting' = TRUE /\ phase' = "reading"
+
+\* kit.refresh() (kit.js:694-706). U reaches it through open -> resolvePane ->
+\* refreshSnapshot -> client.kit.refresh() (herdrSessionSource.ts:2606, 1878-1897, 1578-1583).
+Refresh(c) ==
+    /\ caller[c] = "idle"
+    /\ caller' = [caller EXCEPT ![c] = "waiting"]
+    /\ IF booting
+         THEN /\ queued' = TRUE /\ nextWaiters' = nextWaiters \cup {c}
+              /\ UNCHANGED <<waiters, booting, phase>>
+         ELSE /\ waiters' = waiters \cup {c} /\ StartBoot
+              /\ UNCHANGED <<queued, nextWaiters>>
+    /\ UNCHANGED <<alive, closedEvt, watch, ready, refusal>>
+
+\* Pane A closes. Herdr closes an acked watch's socket, which re-dials after 2 s
+\* (socket.js:115-121); a watch still opening is answered by HerdrAnswer.
+CloseA ==
+    /\ alive["A"]
+    /\ alive' = [alive EXCEPT !["A"] = FALSE]
+    /\ closedEvt' = TRUE
+    /\ watch' = IF watch["A"] = "open" THEN [watch EXCEPT !["A"] = "retry"] ELSE watch
+    /\ UNCHANGED <<booting, queued, phase, waiters, nextWaiters, ready, refusal, caller>>
+
+\* A structural event queues a bootstrap, or a follow-up while one runs (kit.js:582-597, 562-568).
+ClosedEventLands ==
+    /\ closedEvt
+    /\ closedEvt' = FALSE
+    /\ IF booting
+         THEN queued' = TRUE /\ UNCHANGED <<booting, phase>>
+         ELSE StartBoot /\ UNCHANGED queued
+    /\ UNCHANGED <<alive, waiters, nextWaiters, watch, ready, refusal, caller>>
+
+\* The snapshot lands: stop the old status watches, open one per agent pane in it
+\* (kit.js:409-414, 440-447; openStatusWatch kit.js:496-514).
+SnapshotLands ==
+    /\ phase = "reading"
+    /\ phase' = "acks"
+    /\ watch' = [p \in Panes |-> IF alive[p] THEN "opening"
+                                 ELSE IF watch[p] = "none" THEN "none" ELSE "stopped"]
+    /\ ready' = [p \in Panes |-> IF alive[p] THEN "pending" ELSE "none"]
+    /\ UNCHANGED <<alive, closedEvt, booting, queued, waiters, nextWaiters, refusal, caller>>
+
+\* Herdr answers one `events.subscribe` (socket.js:94-112). A live pane acks. A closed
+\* pane is refused, then Herdr closes the socket: a matched refusal settles `ready` false
+\* and stops; an unmatched one is ignored and the close handler re-dials (socket.js:115-121).
+HerdrAnswer(p) ==
+    /\ watch[p] = "opening"
+    /\ IF alive[p]
+         THEN /\ watch' = [watch EXCEPT ![p] = "open"]
+              /\ ready' = IF ready[p] = "pending" THEN [ready EXCEPT ![p] = "ok"] ELSE ready
+              /\ UNCHANGED refusal
+         ELSE /\ refusal' = [refusal EXCEPT ![p] = TRUE]
+              /\ IF RefusalShape \in Matched
+                   THEN /\ watch' = [watch EXCEPT ![p] = "stopped"]
+                        /\ ready' = IF ready[p] = "pending" THEN [ready EXCEPT ![p] = "refused"] ELSE ready
+                   ELSE /\ watch' = [watch EXCEPT ![p] = "retry"] /\ UNCHANGED ready
+    /\ UNCHANGED <<alive, closedEvt, booting, queued, phase, waiters, nextWaiters, caller>>
+
+\* later(open, backoff) dials a fresh watch with a new id (socket.js:88-92, 120-124).
+Retry(p) ==
+    /\ watch[p] = "retry"
+    /\ watch' = [watch EXCEPT ![p] = "opening"]
+    /\ UNCHANGED <<alive, closedEvt, booting, queued, phase, waiters, nextWaiters, ready, refusal, caller>>
+
+\* Every watch this bootstrap opened has settled (Promise.allSettled, kit.js:446-447), so
+\* runBootstrap's statusWatchReady() returns: answer the waiters and start the queued
+\* follow-up for nextWaiters (kit.js:531-557). An answered attach finds B in the tree.
+AcksSettle ==
+    /\ phase = "acks"
+    /\ \A p \in Panes : ready[p] # "pending"
+    /\ caller' = [c \in Callers |-> IF c \in waiters THEN "done" ELSE caller[c]]
+    /\ IF queued /\ DrainsQueue
+         THEN /\ queued' = FALSE /\ waiters' = nextWaiters /\ nextWaiters' = {}
+              /\ StartBoot
+         ELSE /\ waiters' = {} /\ booting' = FALSE /\ phase' = "idle"
+              /\ UNCHANGED <<queued, nextWaiters>>
+    /\ UNCHANGED <<alive, closedEvt, watch, ready, refusal>>
+
+KitStep == ClosedEventLands \/ SnapshotLands \/ AcksSettle
+           \/ \E p \in Panes : HerdrAnswer(p) \/ Retry(p)
+
+Next == KitStep \/ CloseA \/ \E c \in Callers : Refresh(c)
+
+\* Herdr answers every request and the kit's timers fire: weak fairness on the kit and
+\* Herdr's replies. Pane closes and user actions get none; they may never happen.
+Spec == Init /\ [][Next]_vars
+        /\ WF_vars(ClosedEventLands) /\ WF_vars(SnapshotLands) /\ WF_vars(AcksSettle)
+        /\ \A p \in Panes : WF_vars(HerdrAnswer(p)) /\ WF_vars(Retry(p))
+
+\* Property 1: after a final refusal, its watch settles (stops for good).
+WatchSettles == \A p \in Panes : refusal[p] ~> (watch[p] = "stopped")
+
+\* Property 2: an attach to the surviving pane B eventually answers. This model has no
+\* failure path (no outage, no snapshot error), so an answer here is a success.
+AttachAnswers == (caller["U"] = "waiting") ~> (caller["U"] = "done")
+
+\* Witness: violated exactly when some run opens B, so the properties are not vacuous.
+NeverAttached == caller["U"] # "done"
+=============================================================================

package/docs/examples/statechart-pilot/README.md

@@ -0,0 +1,109 @@
+# Pane-attach race: a statechart pilot
+
+A small statechart and an executable model of one real bug: in muxr v0.2.9, a pane that closes before its status watch opens leaves the shared Herdr tree read waiting forever, so opening a pane that is still alive hangs. A pinned model checker finds that path on the old code, and the path is written below as the steps a user takes.
+
+**This is supporting evidence only. It is not proof that muxr works or fails.** Real-product replay: **not checked**. No Herdr lifecycle command was run and muxr was not touched. The journey entry that a real replay would follow is [pane-attach-race.md](pane-attach-race.md). It is written in the format of muxr's project skill and is waiting for an isolated Herdr lab.
+
+Files: [PaneAttach.tla](PaneAttach.tla) (model and properties), [check.mjs](check.mjs) (repeatable check), [pane-attach-race.md](pane-attach-race.md) (project-skill journey entry).
+
+## The code it models
+
+| Model action | Real code (muxr tag `v0.2.9`, `@byokit/herdr` 0.16.1 as published on npm) |
+|---|---|
+| `Refresh(U)`: the user opens pane B | `open` → `resolvePane` → `refreshSnapshot` → `client.kit.refresh()` (`apps/host/src/agent/infrastructure/herdrSessionSource.ts:2606, 1878-1897, 1578-1583`) |
+| `Refresh(c)` joins a running read or starts one | `HerdrKit.refresh()` (`dist/kit.js:694-706`) |
+| `StartBoot` / `SnapshotLands` | `runBootstrap` → `bootstrap` sends `session.snapshot`, stops the old status watches and opens one per agent pane (`dist/kit.js:523-530, 363-371, 409-414, 440-447`; `openStatusWatch` `dist/kit.js:496-514`) |
+| `CloseA`, then `ClosedEventLands` | a structural event queues a bootstrap, or a follow-up while one runs (`dist/kit.js:582-597, 562-568`); Herdr closing an acked watch's socket re-dials it (`dist/socket.js:115-121`) |
+| `HerdrAnswer(p)` | the watch's frame handler. Only an error whose id is `''` or exactly the watch's id counts as a refusal (`dist/socket.js:94-112`). Herdr refuses a watch on a closed pane with id `<id>:sub:0:probe` (the record in muxr PR 1006) |
+| `Retry(p)` | `later(open, backoff)` dials a new watch with a new id (`dist/socket.js:88-92, 120-124`) |
+| `AcksSettle` | `Promise.allSettled` over the watches' `ready` promises; `runBootstrap` then answers its waiters and starts the queued follow-up (`dist/kit.js:446-447, 531-557`) |
+
+Source identity: muxr `v0.2.9` is commit `3b8321f897f984ee1bf186177bf89ebfd812de2d`, whose `apps/host/package.json` pins `@byokit/herdr` `0.16.1`. The kit tarball `herdr-0.16.1.tgz` has sha256 `407fc6fce982fd61e5f1a77f60b0516c51ef6bf6963998f8ac80330d6bc2f2c9` (gitHead `39be7f88b7b13b7a9f32fbc1a1d74567016198b0`). Its `dist/socket.js` has sha256 `525d439da77312880dc170f9bf8f186bb0a295fb3d7210372ab19eda44700a90` and its `dist/kit.js` has sha256 `e4e6eb848e3043e97f4c95c485390a963879df67feb7f57a3f188828960f8597`.
+
+## Statechart
+
+One tree read in the kit:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Reading: refresh() or a pane event
+    Reading --> Reading: refresh() while reading, queued as a follow-up
+    Reading --> AwaitingWatches: snapshot lands, one watch opened per agent pane
+    AwaitingWatches --> Idle: every watch settled, waiters answered
+    AwaitingWatches --> Reading: every watch settled, queued follow-up starts
+```
+
+One pane's status watch:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Opening
+    Opening --> Open: Herdr accepts (pane alive), ready = true
+    Opening --> Stopped: refusal with an empty id or the watch's own id, ready = false
+    Opening --> Redial: refusal with id ...sub:0:probe, ignored in 0.16.1
+    Open --> Redial: Herdr closes the socket (pane closed)
+    Redial --> Opening: re-dial with a new id
+    Open --> Stopped: the next snapshot stops old watches
+```
+
+The bad loop is `Opening → Redial → Opening`, entered while the tree read waits in `AwaitingWatches`. The watch's `ready` never settles, so the tree read never leaves `AwaitingWatches`. Every `refresh()` waits behind it, and so does every pane open.
+
+## Properties
+
+1. **After a final refusal, its watch settles** (`WatchSettles`): once Herdr refuses a pane's watch, which happens only after the pane has closed for good, that watch eventually stops.
+2. **Opening a surviving pane eventually answers** (`AttachAnswers`): once the user opens pane B, the open eventually finishes. This model has no outage or snapshot error, so the only answer is success. Explicit failure paths are outside its scope.
+
+`NeverAttached` is a witness. It is violated exactly when some run opens B, which shows the properties are not passing trivially.
+
+## Results
+
+Run on 22 October 2026 with `node docs/examples/statechart-pilot/check.mjs <tla2tools.jar> <out-dir>`, which exited 0:
+
+| Run | Kit behaviour | Checks | Expected | Got | Distinct states |
+|---|---|---|---|---|---|
+| `old-watch` | 0.16.1 matcher (`''` or `<id>`) | `WatchSettles` | violated | violated | 460 |
+| `old-attach` | 0.16.1 matcher | `AttachAnswers` | violated | violated | 460 |
+| `old-witness` | 0.16.1 matcher | `NeverAttached` | violated (B can open) | violated | 97 |
+| `fixed` | also matches `<id>:` ids (the kit fix named in PR 1006) | both | hold | hold | 399 |
+| `fixed-witness` | corrected matcher | `NeverAttached` | violated (B can open) | violated | 93 |
+| `broken-attach` | corrected matcher, but `runBootstrap` never starts the queued follow-up | `AttachAnswers` | violated | violated | 435 |
+| `broken-watch` | the same broken variant | `WatchSettles` | holds | holds | 435 |
+
+The broken variant is caught by the attach property, which was not written for it. The watch property still holds for that variant, so the two properties check different things.
+
+### The counterexample, as user steps (`old-attach`)
+
+1. Umer opens agent B on the phone. The host asks the kit to re-read the Herdr tree.
+2. Something else re-reads the tree at the same moment, such as another open. It queues behind the first read.
+3. The tree comes back listing agents A and B. The kit opens a status watch for each and waits for both.
+4. Agent A's pane closes before Herdr has accepted A's watch.
+5. Herdr accepts B's watch.
+6. Herdr refuses A's watch with id `<id>:sub:0:probe` and closes the socket. The kit does not see that id as a refusal, logs nothing, and dials A's watch again.
+7. Each new dial gets the same refusal, forever.
+
+What Umer sees: B stays on "connecting" even though B is alive. Every later open queues behind the same tree read. Only stopping the kit (a host restart) rejects the waiting opens. `old-watch` reaches the same loop one read later: the first tree read lands, and the queued follow-up read is the one that hangs.
+
+## Model report
+
+- Checker: TLC2 Version 2.19 of 08 August 2024 (rev: 5a47802), from [tla2tools.jar v1.7.4](https://github.com/tlaplus/tlaplus/releases/tag/v1.7.4). Its sha256 is `936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88` and its sha1 `bee4a54f3ee3d4afc347c3240ec2d9e93b075104` matches the release notes. `check.mjs` refuses any other jar. It ran on OpenJDK 21.0.2 with `-workers 1 -deadlock`: v1.7.4's liveness check is only sound with one worker (tlaplus issue 971), and finished runs are allowed to stop.
+- Model `PaneAttach.tla` sha256: `47caab3c3d5eb0fe34841ae841e93cafb51873b67e861fdd1d1e63aee3e7e739`.
+- Properties (sha256 of each definition's text): `WatchSettles` `7b79e33aa012dad92414f12b13df535f87fb3ee4facee03b6b07d1695cf373a0`, `AttachAnswers` `40e9a75d27e47f467113ddc84428528769d192a80c73fa112891eb5e8b0da678`, `NeverAttached` `ab58eddaa46974dcbc9273bc1698e06255a1e04c74f44c5f22e501e1b71f122c`.
+- Source commit: muxr `3b8321f897f984ee1bf186177bf89ebfd812de2d` (`v0.2.9`) with `@byokit/herdr` 0.16.1 (identity above).
+- Bounds: two panes (A may close, B never closes), one other refresh caller and one open of B, each made once. Every open and dial of a watch is modelled, with no retry cap, because the watch loop is finite in state. A full search finds every reachable state; no depth limit is used.
+- Assumptions:
+  - Herdr answers every request and the kit's timers fire. This is weak fairness on the kit and Herdr steps. The refusal is a delivered answer, not a lost packet, so a network that never answers is not mistaken for this bug.
+  - Closing a pane and the user's actions get no fairness; they may never happen.
+  - A closed pane never comes back.
+  - A snapshot shows the panes alive when it lands. A pane closing between Herdr's read and the reply landing is the same race as closing just after it lands.
+  - The `<id>:sub:0:probe` refusal shape comes from the record in muxr PR 1006, not from a Herdr run here.
+  - Not modelled: Herdr outages, snapshot errors, the event socket reconnecting, `kit.stop()`, and the 20-second refresh bound and kit restart that PR 1006 adds to the host. Whether that host recovery repairs the property is a separate check and is not claimed here.
+
+## Rerun it
+
+```bash
+curl -fLo tla2tools.jar https://github.com/tlaplus/tlaplus/releases/download/v1.7.4/tla2tools.jar
+node docs/examples/statechart-pilot/check.mjs tla2tools.jar <out-dir>
+```
+
+Each run's TLC transcript, counterexamples included, and `model-report.json` with every hash land in `<out-dir>`. The command exits 1 when any run differs from the expected result above. When the kit or `herdrSessionSource.ts` changes, re-read the cited lines, update the model to match the code, and rerun. If the code no longer matches a row in the code-map table, the model is stale and its results do not apply.

package/docs/examples/statechart-pilot/check.mjs

@@ -0,0 +1,72 @@
+// Model check for the pane-attach race pilot: runs the pinned TLC on PaneAttach.tla for the old kit, the corrected
+// kit, a deliberately broken variant and two reachability witnesses, and fails unless each gives its expected result.
+// Usage: node docs/examples/statechart-pilot/check.mjs <tla2tools.jar> <out-dir>. Needs java on PATH; writes one TLC
+// transcript per run and model-report.json into <out-dir>. This is supporting evidence, never real-product proof.
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// tla2tools.jar from https://github.com/tlaplus/tlaplus/releases/tag/v1.7.4 (sha1 bee4a54f… as its release notes list).
+const TLC_SHA256 = '936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88';
+const OLD = '{"exact", "empty"}'; // socket.js:95: frame.id === '' || frame.id === id
+const FIXED = '{"exact", "empty", "subProbe"}'; // the kit fix PR 1006 names: match "<id>:" ids too
+const RUNS = [
+  { name: 'old-watch', matched: OLD, drains: 'TRUE', check: 'PROPERTY WatchSettles', expect: 'violated' },
+  { name: 'old-attach', matched: OLD, drains: 'TRUE', check: 'PROPERTY AttachAnswers', expect: 'violated' },
+  { name: 'old-witness', matched: OLD, drains: 'TRUE', check: 'INVARIANT NeverAttached', expect: 'violated' },
+  { name: 'fixed', matched: FIXED, drains: 'TRUE', check: 'PROPERTY WatchSettles AttachAnswers', expect: 'holds' },
+  { name: 'fixed-witness', matched: FIXED, drains: 'TRUE', check: 'INVARIANT NeverAttached', expect: 'violated' },
+  // Broken variant: the corrected kit, but runBootstrap never starts the queued follow-up (kit.js:550-555).
+  { name: 'broken-attach', matched: FIXED, drains: 'FALSE', check: 'PROPERTY AttachAnswers', expect: 'violated' },
+  { name: 'broken-watch', matched: FIXED, drains: 'FALSE', check: 'PROPERTY WatchSettles', expect: 'holds' },
+];
+
+const [jar, outArg] = process.argv.slice(2);
+if (!jar || !outArg) {
+  console.error('usage: node docs/examples/statechart-pilot/check.mjs <tla2tools.jar> <out-dir>');
+  process.exit(2);
+}
+const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+const jarHash = sha256(readFileSync(jar));
+if (jarHash !== TLC_SHA256) {
+  console.error(`check: ${jar} has sha256 ${jarHash}, not the pinned TLC v1.7.4 ${TLC_SHA256}`);
+  process.exit(2);
+}
+const here = dirname(fileURLToPath(import.meta.url));
+const model = readFileSync(join(here, 'PaneAttach.tla'), 'utf8');
+const definition = (name) => model.match(new RegExp(`^${name} ==.*(?:\\n[ \\t].*)*`, 'm'))[0];
+const out = resolve(outArg);
+mkdirSync(out, { recursive: true });
+const work = mkdtempSync(join(tmpdir(), 'dd-paneattach-'));
+const report = {
+  tool: '', java: spawnSync('java', ['-version'], { encoding: 'utf8' }).stderr.split('\n')[0], tla2tools_sha256: jarHash,
+  model_sha256: sha256(model),
+  properties: Object.fromEntries(['WatchSettles', 'AttachAnswers', 'NeverAttached'].map((p) => [p, sha256(definition(p))])),
+  runs: [],
+};
+let failed = false;
+try {
+  copyFileSync(join(here, 'PaneAttach.tla'), join(work, 'PaneAttach.tla'));
+  for (const run of RUNS) {
+    const cfg = `SPECIFICATION Spec\nCONSTANTS\n  Matched = ${run.matched}\n  DrainsQueue = ${run.drains}\nINVARIANT TypeOK\n${run.check}\n`;
+    writeFileSync(join(work, `${run.name}.cfg`), cfg);
+    // One worker: TLC 1.7.4 liveness checking is only sound single-threaded (tlaplus issue 971).
+    const r = spawnSync('java', ['-cp', resolve(jar), 'tlc2.TLC', '-workers', '1', '-deadlock', '-cleanup',
+      '-metadir', join(work, `${run.name}.states`), '-config', `${run.name}.cfg`, 'PaneAttach.tla'], { cwd: work, encoding: 'utf8' });
+    const text = r.stdout + r.stderr;
+    writeFileSync(join(out, `${run.name}.txt`), `${cfg}\n${text}`);
+    report.tool ||= text.match(/TLC2 Version [^\n]*/)?.[0] ?? '';
+    const got = /No error has been found/.test(text) ? 'holds' : /(Temporal properties were violated|Invariant \w+ is violated)/.test(text) ? 'violated' : 'error';
+    const states = text.match(/(\d+) distinct states found/)?.[1];
+    report.runs.push({ ...run, cfg_sha256: sha256(cfg), got, distinct_states: Number(states), exit: r.status });
+    console.log(`${got === run.expect ? 'ok  ' : 'FAIL'} ${run.name}: expected ${run.expect}, got ${got} (${states} distinct states)`);
+    if (got !== run.expect) failed = true;
+  }
+} finally {
+  rmSync(work, { recursive: true, force: true });
+}
+writeFileSync(join(out, 'model-report.json'), `${JSON.stringify(report, null, 2)}\n`);
+process.exit(failed ? 1 : 0);

package/docs/examples/statechart-pilot/pane-attach-race.md

@@ -0,0 +1,37 @@
+# A pane that closes before its watch opens never stops other panes opening
+
+A journey entry in the format of muxr's project skill (`.agents/skills/done-done-verify-pockit/features/`). It turns the model checker's counterexample in [README.md](README.md) into a journey on the real product. The entry lives here until muxr's verification owner replays it in an isolated Herdr lab and moves it into muxr's skill.
+
+**Real-product replay: not checked.** The model results are supporting evidence only. They never count as proof that this journey passes or fails.
+
+## Sub-features
+
+- While a tree read waits on the status watches, an agent pane closes before Herdr accepts its watch. Opening a different, live agent still finishes: the terminal opens, or the phone shows an explicit error. It never stays on "connecting".
+- Later opens after that moment answer at normal speed, without a host restart.
+
+## How to get to it (user POV)
+
+- On a busy computer, agents come and go. Open any live agent on the phone right as another agent finishes. The terminal opens.
+
+## Driving it with the private stack
+
+Needs a separately authorized, isolated Herdr lab session. Never drive the captain's live Herdr.
+
+1. Start a lab host against a named lab Herdr session with two agent panes, A and B, and pair a lab phone client (Umer).
+2. Hold A's `pane.agent_status_changed` subscribe at a socket proxy so the kit's tree read waits for A's watch, then close pane A. This is step 4 of the counterexample.
+3. Release the subscribe. Herdr answers `{"id":"<id>:sub:0:probe","error":{"code":"pane_not_found"}}` and closes the socket.
+4. Open B from the phone, type a short line, and read it back in the terminal.
+5. Open B a second time.
+
+Pass: steps 4 and 5 each open the terminal and show the typed line, or show an explicit failure on the phone, within 60 seconds. Fail: either open is still on "connecting" after 60 seconds.
+
+PR 1006's `scripts/diagnostics/application/checkHerdrVanishedWatch.mjs` already holds a subscribe at a proxy, according to that PR's record. It checks the host client's tree read, not the phone, so it covers steps 1-3 only.
+
+## Evidence
+
+- A phone screenshot after step 4 and after step 5.
+- The host journal for the run, plus a proxy log showing A's refusal frame and its id.
+- `steps.json` naming the muxr version, the starting state (two agents, A held), the steps above and what Umer sees at the end.
+- Kept separately as supporting evidence: the model report from `node docs/examples/statechart-pilot/check.mjs` in done-done, at the muxr and kit commits that were driven.
+
+On muxr v0.2.9 with `@byokit/herdr` 0.16.1, the model predicts step 4 hangs. With the kit's refusal-id fix, the model predicts both opens answer. Neither prediction has been checked on the real product.

package/docs/reference.md

@@ -177,18 +177,23 @@ done-done never drives the browser: the recipe or journey writes one page-check
 {"url": "http://127.0.0.1:4100/", "overflow": true, "overflowing": ["div#wide"], "console_errors": ["boom"], "failed_requests": [{"url": "http://127.0.0.1:4100/x.js", "status": 404}],
  "squashed_text": [{"element": "h3.card-title", "text": "Approved", "chars": 1.6, "lines": 8, "words": 1}],
  "clipped_text": [{"element": "h3.card-title", "text": "Answered: the release notes are approved", "by": "its own box"}],
- "cut_off": [{"element": "div.clock", "text": "12:30", "edges": ["top"]}]}
+ "cut_off": [{"element": "div.clock", "text": "12:30", "edges": ["top"]}],
+ "controls": [{"element": "button#request", "text": "Request changes", "native": true, "height": 21}],
+ "actions": [{"selector": "#request", "text": "Request changes", "failed": "changed nothing a user can read on the page (its text, elements or address) within 5s"}]}
 ```
 
+`controls` and `actions` are optional too; [`done-done look`](#look-check) writes `controls` on every page and `actions` when it clicks one. With a [`look` block](#look-check), the check fails on each control in `controls` drawn as the browser's own, and on one taller than `max_control`; it fails on each `actions` item with a `failed` reason with or without one. A recipe that drives its own browser runs done-done's `CONTROLS` measurement (exported from `dom.js` next to `LOOK`) for `controls`, and `AIM` and `CHANGED` around each click for `actions`.
+
 With your browser tool, for example chrome-devtools-axi: `overflow` and `overflowing` from `eval` (document `scrollWidth` beyond `clientWidth`, and the elements whose right edge passes it), `console_errors` from `console --type error`, `failed_requests` (status 400 or more, or 0 for no response) from `network`, `squashed_text` from `eval` of done-done's measurement function, run in each frame of the page (an embedded frame too). It lists every visible HTML element with its own text (SVG text has no layout box and is skipped; widths are untransformed layout pixels, so a scaled ancestor does not shrink them) whose box is under 8 characters wide (its width over the average glyph width of its font) while its text is wider than the box, or whose text sits on more lines (distinct line boxes) than it has words: a title wrapped one letter per line in a narrow column. `squashed_text`, `clipped_text` and `cut_off` are optional, so a record written without them stays valid; [`done-done look`](#look-check) writes all of them, and the check fails on each `clipped_text` and `cut_off` item as it does on `squashed_text`. The agent drive prompt carries the recipe, and a verify skill should carry it too. Verify's check and `done-done check` fail naming the capture and each issue not on an allow list, and fail when a capture has no record or a record is not this shape. No `dom` block keeps today's behaviour.
 
 ### Look check
 
-`done-done look` is the look step a journey calls on a web page. It opens the page in headless Chrome at a 390x844 phone viewport (a mobile device at 1x scale), measures the look defects in the DOM, writes the screenshot with its page-check record next to it, and exits 1 on any hit, naming the element, the kind and its text. It is a measurement step, not a verdict: with no hit it ends `result: clean` (exit 0), never `pass`, and its capture is judged when a `check` or `verify` cites it. No model runs here, so the same page gives the same answer. A worker's claim that a phone UI works needs this 390 px capture of the real page, plus the page's scroll-container count, as proof; a mock or another width is not proof.
+`done-done look` is the look step a journey calls on a web page. It opens the page in headless Chrome at a 390x844 phone viewport (a mobile device at 1x scale), clicks each `--act` and checks it completes, measures the look defects in the DOM, writes the screenshot with its page-check record next to it, and exits 1 on any hit, naming the element, the kind and its text. It is a measurement step, not a verdict: with no hit it ends `result: clean` (exit 0), never `pass`, and its capture is judged when a `check` or `verify` cites it. Without `--mock` no model runs here, so the same page gives the same answer. A worker's claim that a phone UI works needs this 390 px capture of the real page, plus the page's scroll-container count, as proof; a mock or another width is not proof.
 
 ```sh
 done-done look http://127.0.0.1:3000/inbox --out "$DONE_DONE_EVIDENCE_ROOT/inbox.png"
 done-done look ./public/inbox.html                     # a path on disk opens as its file:// URL
+done-done look "$DONE_DONE_BASE_URL/#decide" --act '#item-1 .approve' --mock design/decide.png --out "$DONE_DONE_EVIDENCE_ROOT/decide.png"
 ```
 
 A journey in `.done-done.yaml` that calls it (one command per screen, `&&` between them, so the first hit stops the journey):
@@ -211,17 +216,31 @@ journeys:
   | squashed text | done-done's [squashed-text measurement](#dom-assertions): a text block under 8 characters wide while its text does not fit, or on more lines than it has words |
   | clipped text | part of an element's text shows and part runs past a container that hides its overflow (`overflow: hidden` or `clip`), with no `text-overflow: ellipsis` (sideways) or line clamp (downwards): a card title cut to one line |
   | cut off | part of an element shows and part lies past the left, right or top edge of the viewport: a status-bar clock clipped at the top. The page is at its top, so content below the bottom edge is fine |
+  | action did not complete | an `--act <selector>` names nothing, a disabled control, or one covered where its centre is (a toast over a button), or its click changes nothing a user can read within 5 seconds: the page's visible text, its element count and its address all stay the same. A card that moves, a reply that shows as saved or a toast that says so is a change; a button that is only there is not |
+  | unstyled control | with a `look` block: a button, select, textarea or input drawn as the browser's own, its background and border the ones the browser gives the same control (same tag, input type and colour scheme) on a page with no styles. Checkbox, radio, range, colour and file inputs are not measured |
+  | oversized control | with `look.max_control`: a button, select, input or `role=button` taller than that many px. A textarea or list box is not measured |
+  | differs from the approved design | with `--mock <file>`: the [design check](#design-check)'s judge (the one the user set) names a defect on the capture next to that approved mock, the same request as `design --mock`, cached the same way |
 
   Something entirely outside its container or the viewport is hidden on purpose (a closed drawer, a visually hidden label) and is not a hit; a cut element's children are not listed again. Content in a scrolling container (`overflow: auto` or `scroll`, such as a carousel) scrolls into view and is not clipped.
-- **What it writes.** `--out <file.png>` (default `look.png` in `$DONE_DONE_EVIDENCE_ROOT` inside a journey, else in the current folder) gets the viewport screenshot, exactly the viewport size in pixels, and `<file>.dom.json` next to it the page-check record of [DOM assertions](#dom-assertions), with the page's console errors and failed requests too. look itself fails only on the four kinds above; with a `dom` block, verify's check also reads the record and applies its allow lists to console errors and failed requests.
+- **The approved reference.** A `look` block in `.done-done.yaml` is the project's approved design reference; with none, look behaves as before:
+
+  ```yaml
+  look:
+    tokens: web/tokens.css   # the approved design tokens file, relative to the repo
+    max_control: --ctl-h     # the tallest a control may be: px (44), or a token in tokens set in px, rem or em (a rem or em is 16 px)
+  ```
+
+  The block alone turns on the unstyled-control check; `max_control` adds the size check. A token that is not set in the file, a tokens file that does not read or an unknown key is a config error (exit 2). The per-page reference is its mock: pass `--mock <file>` with the approved design of that screen. The `--act` clicks are real mouse clicks at each control's centre, in order, and the page they leave is the one measured and captured, so a journey drives the page to the state to check with them.
+- **What it writes.** `--out <file.png>` (default `look.png` in `$DONE_DONE_EVIDENCE_ROOT` inside a journey, else in the current folder) gets the viewport screenshot, exactly the viewport size in pixels, and `<file>.dom.json` next to it the page-check record of [DOM assertions](#dom-assertions), with the page's console errors and failed requests too. look itself fails only on the kinds above; with a `dom` block, verify's check also reads the record and applies its allow lists to console errors and failed requests.
 - **Chrome.** look starts its own headless Chrome or Chromium (`google-chrome`, `google-chrome-stable`, `chromium` or `chromium-browser` on PATH, or `DONE_DONE_CHROME` naming the binary) with a throwaway profile, and removes both when it ends. It runs Chrome without its sandbox so it starts in containers, so point it at your own app, not untrusted sites. No Chrome is a usage error (exit 2) that says how to install or point to one; a page that does not load (its network error, or no load event within 30 seconds) is exit 2 with the cause.
-- **Limits.** Only the main frame is measured, not an embedded frame; a transform or `clip-path` that hides part of a box is not seen; nothing is clicked or scrolled first, so drive the page to the state to check (a URL per state) before you call look. Look at the capture too: a defect the DOM cannot see (a stretched image, a colour) is the [design check](#design-check)'s.
+- **Limits.** Only the main frame is measured, not an embedded frame; a transform or `clip-path` that hides part of a box is not seen; nothing is scrolled first, and only `--act` clicks; drive any other state (typing, a URL per state) before you call look. Look at the capture too: a defect the DOM cannot see (a stretched image, a colour) is the [design check](#design-check)'s.
 
 | Result | Exit |
 |---|---|
 | no hit | 0 |
 | a hit of any kind | 1 |
-| bad flags, no Chrome, or the page did not load | 2 |
+| bad flags, a bad `look` block, no Chrome, the page did not load, or `--mock` with no judge set | 2 |
+| no hit, but the `--mock` judge is unsure | 3 |
 
 ### Lint check
 
@@ -238,6 +257,7 @@ journeys:
   - `checks.upstream_catch_up: true`: in a fork, lines the parent repo already shipped are not authored here, so lint subtracts the changes between the PR's base and the merge base with the parent's default branch. A PR that merges in no new upstream commit loses nothing.
   - `checks.moved_from: true`: a line in the PR body `moved-from: <owner>/<repo>@<ref> <dst-prefix>=<src-prefix>` (more `dst=src` pairs may follow) cancels added lines that match, byte for byte after trimming, the file at the same path under `<src-prefix>` in that repo at `<ref>`. The source repo must have the PR's owner; authored lines still count.
   - `checks.generated_paths: ["gen/**", "*.snap"]`: globs for the repo's own generated files, counted as generated beside the built-in ones above, so they stay out of the size count. Default none, so results do not change. Like the two rules above it applies to a PR URL, never a report file.
+  - `.gitattributes` in the target repo: a file it marks `linguist-generated`, `linguist-generated=true` or `-diff` is counted as generated too, with no config. `linguist-generated=false` and an unset attribute are not; the last matching line wins. `lint` reads the file at the PR head (else its base) and, like the rules above, only for a PR URL.
 
 ### Base-ref before
 
@@ -348,7 +368,7 @@ evidence: <paths of the evidence files, or "not proven: <cause>">
 |---|---|
 | Not empty | The file must contain bytes. |
 | Valid media | The magic bytes match the extension. PNG and JPEG are complete (end markers present) and at least 64×64. PNG is not a blank frame. WebP and GIF are not truncated. MP4/MOV and WebM/MKV decode at least two video packets (`ffprobe`). Text and log files hold text; JSON parses. |
-| Fresh | The file is in a run record whose commit is HEAD. The one exception: if the only commits since the run touch `ignore_paths`, the evidence still counts. An empty commit does not count as touching only `ignore_paths`. |
+| Fresh | The file is in a run record whose commit is HEAD. Two exceptions: if the only commits since the run touch `ignore_paths`, the evidence still counts; and if the changed files touch no journey or feature the run covered (the same mapping as `done-done affected`, model-free), the proof holds and the result warns with both commits. A change that does touch the run's journey is stale. A receipt keeps each run's `commit` beside its own `head`. An empty commit does not count as touching only `ignore_paths`. |
 | Clean | The run was not dirty, unless `evidence.allow_dirty: true`. The run command also exited 0. |
 | Not reused | Fails when the files are byte-identical within one claim. Also fails when every file was already used to prove a different claim in this repo. A claim is named by `--claim-id <id>`, by default the current branch (with `--from <PR URL>`, the PR's branch; on a detached HEAD, the commit), so rewording the outcome is not reuse. One branch is one claim: several claims on one branch each need their own `--claim-id`, or they share one reuse scope. The ledger is `<root>/.done-done/ledger` in the evidence root, so each repo keeps its own (pin `app`, as `init` does, so two repos with the same directory name do not share one); `DONE_DONE_HOME` moves it only with the default evidence root. |
 
@@ -652,6 +672,7 @@ An `agent_config` entry merges with the defaults field by field, so `claude: { m
 | `instance` | none; the app under test started per run, see [Run-instance harness](#run-instance-harness) |
 | `matrix` | none, so each journey runs once; `theme`, `width`, `form` and `skip` set the [capture matrix](#capture-matrix) |
 | `dom` | none; page-check records per capture, see [DOM assertions](#dom-assertions) |
+| `look` | none; the look step's approved design reference (`tokens`, `max_control`), see [Look check](#look-check) |
 | `inputs` | `[]`; repo-relative paths or globs the drive must leave alone, see [Input guard](#input-guard) |
 | `base_ref` | none; a ref `verify` also drives, pairing its captures with the head's, see [Base-ref before](#base-ref-before) |
 | `evidence.root` | `<local_root>/<app>`, outside the repo. A relative path is under the repo; an absolute path is used as-is |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "done-done-axi",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "license": "Apache-2.0",
   "description": "Proof that the real product works before a task is called done: commit-bound evidence runs and evidence checks.",
   "type": "module",

package/skills/done-done/SKILL.md

@@ -50,7 +50,11 @@ its findings and captures, and end it with `done-done respond --action fix` only
 A journey that `spends` runs only after the user approves spending: `done-done run <journey>` refuses it, so ask the user and use `verify`.
 
 For a web page, `done-done look <url>` is the look step a journey calls: it captures the page at a 390x844 phone viewport
-with its page-check record and exits 1 on squashed, clipped or cut-off UI, naming each element. A hit fails the journey;
+with its page-check record and exits 1 on squashed, clipped or cut-off UI, naming each element. `--act <selector>` clicks a
+control and fails when the page does not change (a card moves, a reply saves, a toast shows): a button that is only there
+is not proof it works. A `look` block in `.done-done.yaml` (`tokens`, `max_control`) is the approved reference: look
+then fails on a control drawn as the browser's own or taller than `max_control`, and `--mock <file>` has the judge compare
+the page with its approved mock. A hit fails the journey;
 never wrap it in `|| true` or log the exit and go on. A claim that a phone UI works needs a 390 px capture of the real
 page and the page's scroll-container count as proof: a mock, a different width or a claim with no count is not proof. A journey in `.done-done.yaml` that calls it: