@motujs/cli 0.0.0-stage → 0.1.0

package/src/commands/verify/region.mjs

@@ -0,0 +1,271 @@
+// `motu archipelago verify` — the command and the per-region run `check` composes.
+// Split out of commands/verify.mjs; verify.mjs re-exports the public surface.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { readRegions } from '../../lib/eject.mjs';
+import { conditionalSlots, exclusiveDeclared } from '../../lib/lagoon-declares.mjs';
+import { paths } from '../../lib/util.mjs';
+import { pageRenderLagoon, runArchipelagoLagoon } from '../../playwright-lagoon.mjs';
+import { cssChecks } from './island-static.mjs';
+import { declaredReach, reportBrowserOverride, reportRuntimeDiagnostics } from './reach.mjs';
+import { frameIsPageCheck } from './region-composition.mjs';
+import { archipelagoConfigChecks } from './region-config.mjs';
+import { catalogueCheck, regionFlowCheck, renderCoverageCheck, wiringProbe, writesCoveredCheck } from './region-flows.mjs';
+import { channelSourceCheck, exclusiveCheck, regionAuditCheck, regionRefCheck } from './region-sources.mjs';
+import { environmentalCause, makeReport, printReport, printSweep, setProgressScope, setVerbose, step, summaryOf, sweepExitCode, verifyExitCode } from './report.mjs';
+import { CHROMIUM_INSTALL } from '../../lib/framework.mjs';
+
+export async function archipelagoVerifyCommand(argv) {
+  const id = argv._[0];
+  if (!id && !argv.all) {
+    console.error('usage: motu archipelago verify <id|--all> [--no-runtime] [--json]');
+    process.exit(2);
+  }
+
+  if (argv.all) {
+    const ids = existsSync(paths.archipelagosDir)
+      ? readdirSync(paths.archipelagosDir, { withFileTypes: true })
+          .filter((e) => e.isDirectory() && existsSync(paths.archipelagoFile(e.name)))
+          .map((e) => e.name)
+      : [];
+    const results = [];
+    for (const one of ids) results.push(await runArchipelagoVerify(argv, one));
+    if (argv.json) {
+      console.log(JSON.stringify({ archipelagos: results.map(summaryOf) }, null, 2));
+    } else {
+      printSweep('motu archipelago verify — all regions', results);
+    }
+    process.exit(sweepExitCode(results));
+  }
+
+  const result = await runArchipelagoVerify(argv, id);
+  if (argv.json) {
+    console.log(JSON.stringify({ archipelago: result.kebab, pass: result.errors.length === 0, findings: result.report.findings }, null, 2));
+  } else {
+    printReport(result.report, `motu archipelago verify — ${result.kebab}`, result.errors, result.warns);
+  }
+  process.exit(verifyExitCode(result));
+}
+
+export async function runArchipelagoVerify(argv, id) {
+  setVerbose(argv?.verbose);
+  setProgressScope(id);
+  const report = makeReport();
+  const hasLayout = archipelagoConfigChecks(report, id);
+  // Static, and project-wide in what it reads: a cycle is a property of the graph, not of one file.
+  if (existsSync(paths.archipelagoFile(id))) regionRefCheck(report, id);
+  if (existsSync(paths.archipelagoFile(id))) exclusiveCheck(report, id);
+
+  // The inbound seam: a channel that orchestrates must install the app's logic, not restate it.
+  const region = readRegions(paths.archipelagosDir).find((r) => r.id === id);
+  if (region) channelSourceCheck(report, id, region);
+
+  // Is what the lagoon draws the page's own code, or a second copy of it?
+  frameIsPageCheck(report, id, region);
+
+  // The other half of what a source is worth: a flow drives it through the screen, and the branches
+  // no screen tells apart need a test that drives it directly.
+
+  // Static, so an uncovered slot shows up in the fast loop rather than behind a browser.
+  renderCoverageCheck(report, id);
+  writesCoveredCheck(report, id);
+
+  // Membership as data: static, so it runs whether or not a browser was asked for.
+  if (region?.membership === 'catalogue') await catalogueCheck(report, id, region);
+
+  // Region styling: until islands own their CSS, the shared sheet is the region's stylesheet — lint it.
+  if (existsSync(paths.sharedStyles)) {
+    cssChecks(report, readFileSync(paths.sharedStyles, 'utf8'), paths.rel(paths.sharedStyles));
+  }
+
+  // Same line as the islands: static by default, browser on request (see runIslandVerify).
+  if ((argv.runtime === true || argv.audit === true) && argv.fast) {
+    // `--fast` means NO BROWSER, and a region's runtime checks are browser-only: flows, mutation and
+    // the region render all drive the lagoon. Running them anyway made `--fast` an island-only flag
+    // whose regions still booted chromium — 43s of an 87s run, most of what was left after the islands
+    // got cheaper. Skipped, and SAID, because a flag that quietly does half of what it claims is worse
+    // than one that costs more.
+    report.skip(
+      'region-runtime',
+      'flows, mutation and the region render need a browser — re-run without --fast before handing over',
+    );
+  } else if (argv.runtime === true || argv.audit === true) {
+    reportBrowserOverride(report);
+    // FIRST, before anything that drives the mountpoints view. The lane reuses one page and a warm
+    // re-aim keeps whatever view it already had, so running this after the wiring probe measured a
+    // DIAGNOSTIC layout and reported a page that overflows by 197px as fitting every viewport. The
+    // trap this file already documents, walked into by the check that needed the region view most.
+    if (hasLayout && argv.audit === true) await regionAuditCheck(report, id, 5300 + Math.floor(Math.random() * 400));
+    if (hasLayout) await wiringProbe(report, id, 5300 + Math.floor(Math.random() * 400));
+    // THE COMPOSED PAGE, at each declared viewport. Island `responsive` mounts each island alone, so
+    // every one of them fits and the arrangement still overflows — a fixed-rail grid fits nothing on
+    // a phone and no island in it is at fault. Only under `--audit`, beside the island checks whose
+    // answer changes when the RENDERING changes rather than when a key moves.
+    // One call, both questions: do the flows hold, and could they have failed.
+    if (hasLayout) await regionFlowCheck(report, id, 5300 + Math.floor(Math.random() * 400), region);
+    if (!hasLayout) {
+      // NAME WHERE THE ARRANGEMENT WAS LOOKED FOR. The old wording ("islands are placed individually
+      // across the host") describes the PAGE, and was read as a claim about the lagoon frame — so an
+      // author who had just written a `layout` saw motu deny it and had no idea which of the three
+      // places it looks at came up empty.
+      report.warn(
+        'lagoon-render',
+        'no arrangement for this region, so the composed render was skipped. Looked for: `root:` or ' +
+          `\`layout:\` on ${paths.rel(paths.archipelagoFile(id))}, and a \`layout\` for '${id}' in the ` +
+          'lagoon overrides (`regions` or the kind-first `layout` map). Without one the islands are ' +
+          'only ever placed individually by the host, and the arrangement is not checked anywhere',
+      );
+    } else {
+      const port = 5300 + Math.floor(Math.random() * 400);
+      try {
+        const r = await step('region-mount', () => runArchipelagoLagoon({ id, port }));
+        if (r.region) {
+          const unmounted = r.islands.filter((i) => !i.tag);
+          if (r.islands.length === 0) {
+            report.error('lagoon-render', 'archipelago region rendered no island slots');
+          } else if (unmounted.length === 0) {
+            // "all N" used to mean "all N I happened to find". A slot the arrangement never places —
+            // an island behind a closed drawer, a conditional branch — simply was not in the list, so
+            // the check congratulated itself on a region missing an island. Say what is declared.
+            const declaredRegion = readRegions(paths.archipelagosDir).find((x) => x.id === id);
+            // A planned island has nothing to mount yet; demanding it here would make the survey red.
+            const declared =
+              declaredRegion?.membership === 'catalogue'
+                ? []
+                : (declaredRegion?.islands ?? []).filter((i) => !i.planned).map((i) => i.slot);
+            const placed = new Set(r.islands.map((i) => i.slot).filter(Boolean));
+            // AN ALTERNATIVE IS NOT UNPLACED. In an exclusive group the lagoon shows one member, like the
+            // page does; the others not being on screen is the declaration working, not a slot lost.
+            const alternatives = new Set(exclusiveIslandSlots(id).flatMap((g) => g.slots));
+            const unplaced = declared.filter((slot) => !placed.has(slot) && !alternatives.has(slot));
+            report.ok('lagoon-render', `region + all ${r.islands.length} island(s) mounted in the lagoon`, {
+              n: r.islands.length,
+              of: 'mounted island(s)',
+            });
+            if (unplaced.length) {
+              report.warn(
+                'lagoon-render',
+                `${unplaced.join(', ')} declared but not placed by this arrangement — behind an overlay or a ` +
+                  `conditional branch. Declared wires are still driven (the probe uses the mountpoints view), ` +
+                  `but nothing here shows it to a human: confirm that is what the page does.`,
+              );
+            }
+          } else {
+            report.error('lagoon-render', `slot(s) with no island mounted: ${unmounted.map((i) => i.slot || '?').join(', ')}`);
+          }
+        } else {
+          report.error('lagoon-render', `archipelago <${id}> did not render — unknown id or boot failure`);
+        }
+        reportRuntimeDiagnostics(report, r, 'region', declaredReach({ regionId: id }));
+
+        // THE PAGE ITSELF — the only check here that renders the application rather than the region.
+        // Reuses the same pooled page: the whole runtime lane is one browser re-aimed per check, and
+        // a second boot for this would double the cost of a region's run for one navigation.
+        const pr = await step('page-render', () => pageRenderLagoon({ id, port }));
+        if (!pr.declared) {
+          report.ok('page-render', `no \`page\` declared for '${id}' — the application's own page is not checked`, {
+            n: 0,
+            of: 'page(s)',
+          });
+        } else if (pr.crashed) {
+          report.error(
+            'page-render',
+            `the application's own page threw while rendering:\n      ${pr.crashed.split('\n').slice(0, 6).join('\n      ')}`,
+          );
+        } else {
+          const declaredRegion2 = readRegions(paths.archipelagosDir).find((x) => x.id === id);
+          const declared2 =
+            declaredRegion2?.membership === 'catalogue'
+              ? []
+              : (declaredRegion2?.islands ?? []).filter((i) => !i.planned).map((i) => i.slot);
+          const reached = new Set(pr.slots.filter((x) => x.len > 0).map((x) => x.slot));
+          // DEDUPED, because a slot name appears both in the root's mapping and in the island entry,
+          // so the raw list said "1/4" and named `login-form` twice for a region with two slots.
+          const slots2 = [...new Set(declared2)];
+          // AND A CONDITIONAL SLOT IS NOT A MISS. The region declares its own either/or with
+          // `when`/`unless`; a slot the page did not take because the region says it is an alternative
+          // is the page behaving, not a finding.
+          const conditional = conditionalSlots(paths.archipelagoFile(id));
+          // So is a member of an EXCLUSIVE group — the page passes one alternative and null for the
+          // rest, by declaration. What an exclusive group CAN fail on is the opposite: two of its
+          // islands on the page at once, which the archipelago says is a screen that cannot exist.
+          const groups = exclusiveIslandSlots(id);
+          for (const g of groups) {
+            const both = g.slots.filter((slot) => reached.has(slot));
+            if (both.length > 1) {
+              report.error(
+                'page-render',
+                `the page renders ${both.join(' AND ')} at once, and the archipelago declares ` +
+                  `[${g.group.join(', ')}] exclusive — a screen it says cannot exist. Open ?region=${id}&view=page`,
+              );
+            }
+          }
+          const alternatives = new Set(groups.flatMap((g) => g.slots));
+          const missing = slots2.filter((slot) => !reached.has(slot) && !conditional.has(slot) && !alternatives.has(slot));
+          if (!reached.size) {
+            // NOTHING AT ALL. The page mounted and reached no declared slot, so whatever it drew, it
+            // was not this region. That is a failure however the page is written.
+            report.error(
+              'page-render',
+              `the page renders and reaches NONE of its ${slots2.length} declared slot(s) — it mounted ` +
+                `without throwing and drew none of the region. Open ?region=${id}&view=page to see what ` +
+                `it did instead`,
+            );
+          } else if (missing.length) {
+            // A WARNING, LIKE `lagoon-render`'s, AND FOR THE SAME REASON. A slot the page did not reach
+            // is sometimes exactly right: two slots can be ALTERNATIVES — peps' login passes the error
+            // banner or the form and never both — and no check can tell a deliberate either/or from an
+            // accidentally unreachable branch. What is not right is not knowing, so it is named.
+            //
+            // It was an error for one run, which made a correctly-written exclusive region red. An
+            // error nobody can act on is how a check teaches people to ignore it.
+            report.warn(
+              'page-render',
+              `the page renders and reaches ${reached.size}/${slots2.length} declared slot(s); not ` +
+                `reached: ${missing.join(', ')} — either an alternative the page deliberately did not ` +
+                `take (an error banner instead of a form), or a branch that never runs. Open ` +
+                `?region=${id}&view=page and confirm which`,
+            );
+          } else {
+            report.ok('page-render', `the application's own page renders and reaches all ${slots2.length} slot(s)`, {
+              n: slots2.length,
+              of: 'slot(s) reached by the page',
+            });
+          }
+        }
+      } catch (err) {
+        const msg = String(err?.message || err).split('\n')[0];
+        const env = environmentalCause(err);
+        if (/Executable doesn't exist|playwright install/i.test(msg)) {
+          report.inconclusive('lagoon-render', `Chromium not installed — run ${CHROMIUM_INSTALL}`);
+        } else if (env) {
+          report.inconclusive('lagoon-render', `could not boot the lagoon: ${env} — the environment, not the region`);
+        } else {
+          report.error('lagoon-render', `lagoon failed: ${msg}`);
+        }
+      }
+    }
+  }
+
+  return {
+    kebab: id,
+    report,
+    errors: report.findings.filter((f) => f.level === 'error'),
+    warns: report.findings.filter((f) => f.level === 'warn'),
+  };
+}
+
+/**
+ * The island SLOTS in each exclusive group, keyed by group — the members `page-render` and
+ * `lagoon-render` can see, since both count mounted islands. A host slot or a pass-through prop in the
+ * group is invisible to them; the type of `<X.Root>` and its runtime report cover those.
+ */
+export function exclusiveIslandSlots(id) {
+  const declared = exclusiveDeclared(paths.archipelagoFile(id));
+  if (!declared) return [];
+  const slotOf = (prop) => {
+    const e = declared.slots[prop];
+    if (typeof e === 'string') return e;
+    return e && !e.region ? (e.slot ?? null) : null;
+  };
+  return declared.exclusive.map((group) => ({ group, slots: group.map(slotOf).filter(Boolean) }));
+}

package/src/commands/verify/report.mjs

@@ -0,0 +1,338 @@
+// The report every verify builds, how it prints, and what its exit code means.
+// Split out of commands/verify.mjs; verify.mjs re-exports the public surface.
+import { unchangedSinceLastRun } from '../../lib/finding-memory.mjs';
+import { readLiveUrl } from '../../lib/live-url.mjs';
+import { color } from '../../lib/util.mjs';
+
+/**
+ * Say what is happening while it happens.
+ *
+ * The runtime checks drive a real browser, and a run that prints nothing until the end is
+ * indistinguishable from a run that has hung — which is exactly how it read at fifteen islands. With
+ * `--verbose` each step names itself as it starts and reports what it cost, so a slow check is
+ * identifiable rather than merely suspected.
+ */
+export let progressLabel = '';
+
+export let verbose = false;
+
+export function setProgressScope(label) {
+  progressLabel = label;
+}
+
+/** Turned on once per command (`--verbose`), rather than threaded through every check's arguments. */
+export function setVerbose(on) {
+  verbose = !!on;
+}
+
+/** Whether `--verbose` is on, for a check that has a finer profile of its own to print. */
+export const isVerbose = () => verbose;
+
+/**
+ * Total time inside instrumented steps. Read by `motu check --verbose` to print the REMAINDER.
+ *
+ * A list of timed parts reads as a partition of the run, and it is not one: after the flow session was
+ * merged into `regionFlowCheck` it stopped being wrapped, and a `--runtime` profile accounted for 13.8s
+ * of 31.8 — 57% invisible, while every printed line looked precise. A profile that cannot say what it
+ * missed is a profile you will optimise the wrong half of.
+ */
+export let stepMsTotal = 0;
+
+export const profiledMs = () => stepMsTotal;
+
+export async function step(name, run) {
+  const started = Date.now();
+  if (!verbose) {
+    try {
+      return await run();
+    } finally {
+      stepMsTotal += Date.now() - started;
+    }
+  }
+  const at = Date.now();
+  process.stderr.write(color.dim(`  · ${progressLabel ? `${progressLabel} ` : ''}${name}…`));
+  try {
+    return await run();
+  } finally {
+    stepMsTotal += Date.now() - at;
+    process.stderr.write(color.dim(` ${((Date.now() - at) / 1000).toFixed(1)}s\n`));
+  }
+}
+
+export function makeReport() {
+  const findings = [];
+  return {
+    findings,
+    error: (check, msg, line) => findings.push({ level: 'error', check, msg, line }),
+    warn: (check, msg, line) => findings.push({ level: 'warn', check, msg, line }),
+    /**
+     * A claim that HELD — and, optionally, how much was looked at to say so.
+     *
+     * `seen` is not decoration. The worst bug of the Twenty adoption was `removal-check` printing
+     * "no motu references in the host application" over a fully integrated app: it scanned the wrong
+     * directories, examined ZERO files, and reported that as success. A check that looked at nothing
+     * cannot have held, so passing `seen: 0` is converted to a `skip` here rather than trusted —
+     * every call site gets the invariant whether or not its author thought about emptiness.
+     */
+    ok: (check, msg, seen) => {
+      const n = Array.isArray(seen) ? seen.length : typeof seen === 'object' && seen ? seen.n : seen;
+      const of = typeof seen === 'object' && seen && !Array.isArray(seen) ? seen.of : undefined;
+      if (n === 0) {
+        findings.push({
+          level: 'skip',
+          check,
+          msg: `nothing to look at${of ? ` (no ${of})` : ''} — "${msg}" is not a result this run can claim`,
+          examined: 0,
+        });
+        return;
+      }
+      findings.push({ level: 'ok', check, msg, ...(n === undefined ? {} : { examined: n, examinedOf: of }) });
+    },
+    /**
+     * A rule that does not apply to this project's posture.
+     *
+     * Deliberately NOT `ok`: a rule silently reported as passing is indistinguishable from a rule that
+     * ran, so the two host modes could drift apart with every report still green. `skip` always states
+     * the reason.
+     */
+    skip: (check, msg) => findings.push({ level: 'skip', check, msg }),
+    /**
+     * COULD NOT LOOK — the check did not run, for a reason that is not the code's fault.
+     *
+     * A port that never opened, a browser that is not installed, a dev server that lost a race. A
+     * human shrugs and re-runs. An AGENT reads `✗` and repairs a bug that does not exist, and with
+     * several agents that is several confident wrong repairs — so this is the third outcome the
+     * report needs, distinct from both "holds" and "contradicted", and the run exits 2 rather than 1
+     * so a loop can tell "retry" from "fix".
+     */
+    inconclusive: (check, msg) => findings.push({ level: 'inconclusive', check, msg }),
+  };
+}
+
+/**
+ * Condense a lagoon boot failure into one actionable line.
+ *
+ * startLagoon attaches vite's own stdout/stderr to the error, but taking only the first line threw it
+ * away — so every misconfiguration surfaced as "vite did not open port N in time", which says nothing
+ * about the cause. Keep the headline, then append the first line of vite output that actually names
+ * the problem.
+ */
+/**
+ * Was this the ENVIRONMENT failing, rather than the code?
+ *
+ * Decided on two signals, and the second one matters more than the first: a known environmental
+ * signature, AND the absence of any application cause in the output. `lagoonFailure` already appends
+ * the first line of vite's output that names a problem — when that line exists, something in the
+ * project is broken and this is a finding, whatever the headline says.
+ */
+/*
+ * RESOURCE EXHAUSTION BELONGS HERE, and its absence was measured rather than guessed. On a machine
+ * running several agents at once, Vite's dev server died with
+ * `ENOSPC: System limit for number of file watchers reached` — the box was out of inotify watches,
+ * nothing to do with the island — and `island verify --runtime` reported it as exit 1, FAIL. That is
+ * precisely the outcome the three-code design exists to prevent: an unattended agent reads `✗` and
+ * repairs a bug that does not exist. Two arms of one bench run hit it.
+ *
+ * ENOSPC is listed with its siblings (EMFILE/ENFILE — descriptors, ENOMEM — memory) because they are
+ * the same class: the machine ran out of something, and no edit to the project changes that.
+ */
+export const ENVIRONMENTAL =
+  /did not open port .* in time|Executable doesn't exist|playwright install|EADDRINUSE|ECONNREFUSED|ETIMEDOUT|Target page, context or browser has been closed|browserType\.launch|ENOSPC|System limit for number of file watchers|EMFILE|ENFILE|ENOMEM|JavaScript heap out of memory/i;
+
+export function environmentalCause(err) {
+  const full = String(err?.message || err);
+  if (!ENVIRONMENTAL.test(full)) return null;
+  // An application cause anywhere in the output disqualifies it: the port never opened BECAUSE the
+  // project does not build, and that is a finding.
+  // …but the environmental line itself is not an application cause, and it usually LOOKS like one:
+  // node prints `Error: ENOSPC: System limit for number of file watchers reached`, which matches the
+  // `^Error` disqualifier and sent the whole classification back to FAIL. Skip any line that is
+  // itself a known environmental signature before deciding the project is at fault.
+  const appCause = full
+    .split('\n')
+    .find(
+      (l) =>
+        /^(Error|\s*failed to|.*ERR_[A-Z_]+|.*Cannot find)/.test(l) &&
+        !l.includes('did not open port') &&
+        !ENVIRONMENTAL.test(l),
+    );
+  return appCause ? null : full.split('\n')[0];
+}
+
+export function lagoonFailure(err) {
+  const full = String(err?.message || err);
+  const headline = full.split('\n')[0];
+  const detail = full
+    .split('\n')
+    .find((l) => /^(Error|\s*failed to|.*ERR_[A-Z_]+|.*Cannot find)/.test(l) && !l.includes('did not open port'));
+  return detail ? `${headline} — ${detail.trim()}` : headline;
+}
+
+/**
+ * 0 pass · 1 contradicted · 2 could not look.
+ *
+ * The third code is the whole point: an unattended loop must be able to tell "the declarations are
+ * wrong, fix them" from "the check never ran, try again". Collapsing them into 1 is what makes an
+ * agent repair a bug that does not exist.
+ */
+export function verifyExitCode(result) {
+  if (result.errors.length) return 1;
+  return result.report.findings.some((f) => f.level === 'inconclusive') ? 2 : 0;
+}
+
+/**
+ * A SWEEP's exit code: the worst verdict any member reached.
+ *
+ * Both sweeps used to gate on `errors.length === 0` alone, which made them the one path where an
+ * inconclusive run reported success — no Chromium, every runtime check unanswered, `--all` exits 0
+ * and CI goes green on a question nobody asked. The single-target form has always used
+ * `verifyExitCode`; this is the same rule applied across members.
+ *
+ * An error still beats an inconclusive, exactly as it does for one member: a run that found something
+ * wrong has an answer, and that answer is 1.
+ */
+export function sweepExitCode(results) {
+  const codes = results.map(verifyExitCode);
+  if (codes.includes(1)) return 1;
+  return codes.includes(2) ? 2 : 0;
+}
+
+/** `--json` shape for one member of a sweep. */
+export function summaryOf(r) {
+  return { name: r.kebab, tag: r.tag, pass: r.errors.length === 0, findings: r.report.findings };
+}
+
+/**
+ * A sweep's result: one line per member, and findings only for those that have something to say.
+ *
+ * A full report per island is unreadable at fourteen of them, and what a sweep answers is "is anything
+ * wrong, and where" — so a clean island costs one line.
+ */
+/** Per-sweep tally of how much of this section the reader has already seen. */
+export const sweepSeen = { total: 0, repeated: 0 };
+
+export function printSweep(title, results) {
+  console.log(color.bold(`\n${title}\n`));
+  for (const r of results) {
+    const mark = r.errors.length ? color.red('✗') : r.warns.length ? color.yellow('!') : color.green('✓');
+    const tally = r.errors.length
+      ? color.red(`${r.errors.length} error(s)`) + color.dim(`, ${r.warns.length} warning(s)`)
+      : color.dim(`${r.warns.length} warning(s)`);
+    console.log(`  ${mark} ${color.dim(r.kebab.padEnd(20))} ${tally}`);
+    for (const f of r.report.findings) {
+      if (f.level !== 'error' && f.level !== 'warn') continue;
+      const m = f.level === 'error' ? color.red('✗') : color.yellow('!');
+      const again = unchangedSinceLastRun(f) ? color.dim('  · unchanged') : '';
+      sweepSeen.total++;
+      if (again) sweepSeen.repeated++;
+      console.log(`      ${m} ${color.dim(f.check.padEnd(18))} ${f.msg}${again}${f.line ? color.dim(`  (line ${f.line})`) : ''}`);
+    }
+  }
+  const failed = results.filter((r) => r.errors.length).length;
+  const warned = results.reduce((n, r) => n + r.warns.length, 0);
+  console.log('');
+  const head = failed
+    ? color.red(color.bold('FAIL')) + `  ${failed}/${results.length} with errors`
+    : color.green(color.bold('PASS')) + `  ${results.length}/${results.length} clean`;
+  // WHAT MOVED, on the line a reader piping through `tail` will actually see.
+  const { total, repeated } = sweepSeen;
+  const delta =
+    total && repeated === total
+      ? color.dim(' · all unchanged since your last run')
+      : repeated
+        ? color.dim(` · ${repeated} unchanged, ${total - repeated} new since your last run`)
+        : '';
+  console.log(head + color.dim(` · ${warned} warning(s) total`) + delta);
+  sweepSeen.total = 0;
+  sweepSeen.repeated = 0;
+}
+
+/** Pretty-print a report's findings + the PASS/FAIL summary line (shared by island + archipelago verify). */
+export function printReport(report, title, errors, warns) {
+  console.log(color.bold(`\n${title}\n`));
+  const line = (f) => {
+    const mark =
+      f.level === 'error'
+        ? color.red('✗')
+        : f.level === 'warn'
+          ? color.yellow('!')
+          : f.level === 'skip'
+            ? color.dim('–')
+            : f.level === 'inconclusive'
+              ? color.yellow('?')
+              : color.green('✓');
+    const at = f.line ? color.dim(`  (line ${f.line})`) : '';
+    // WHAT IT LOOKED AT, on the line itself. A reader skimming a wall of green cannot tell a check
+    // that examined forty files from one that examined none, and an agent reporting the former while
+    // doing the latter is the failure this whole report exists to catch.
+    const seen =
+      f.examined === undefined ? '' : color.dim(`  · ${f.examined} ${f.examinedOf ?? 'examined'}`);
+    // UNCHANGED SINCE THE LAST RUN OF THIS SAME COMMAND. Half of everything read in the check loop
+    // was a repeat; saying so is what lets a reader skip it and look at the delta instead.
+    const again = f.level === 'ok' || f.level === 'skip' ? '' : unchangedSinceLastRun(f) ? color.dim('  · unchanged') : '';
+    console.log(`  ${mark} ${color.dim(f.check.padEnd(18))} ${f.msg}${seen}${again}${at}`);
+  };
+
+  // THE PASSES COLLAPSE; EVERYTHING ELSE DOES NOT.
+  //
+  // One island under `--runtime` printed 24 rows, 20 of them green, and `motu check --runtime` does
+  // that once per island — so the findings worth reading were a fifth of the output and got skimmed
+  // past. Warnings, errors, skips and inconclusives keep their own line, because each is something to
+  // act on or to know was not run.
+  //
+  // The ids are still NAMED, not just counted. `report.ok(check, msg, 0)` already becomes a `skip`, so
+  // a check that examined nothing is never inside this line — but a check that never RAN would leave
+  // no trace at all, and the whole point of the seen-count is that silence must be legible. Listing
+  // them keeps a missing check visible; `--verbose` prints the full rows with their counts.
+  const passed = report.findings.filter((f) => f.level === 'ok');
+  for (const f of report.findings) if (verbose || f.level !== 'ok') line(f);
+  if (!verbose && passed.length) {
+    console.log(`  ${color.green('✓')} ${color.dim('passed'.padEnd(18))} ${passed.length} check(s)`);
+    // A pass that counted an island's PORTALED output (lib/island-render.mjs) keeps that on its name
+    // even collapsed — "data-flow" passing on a dialog is a different claim from passing on the subtree.
+    const named = (f) => (/\bportals?\b/.test(`${f.examinedOf ?? ''} ${f.msg}`) ? `${f.check} (incl. portal)` : f.check);
+    console.log(`    ${color.dim(passed.map(named).join(', '))}`);
+  }
+  console.log('');
+  const unknown = report.findings.filter((f) => f.level === 'inconclusive');
+  // THE DELTA, ON THE VERDICT LINE. Every agent observed in the bench piped this report through
+  // `tail`, so the end is the only part reliably read — which makes it where "what moved" belongs.
+  const actionable = report.findings.filter((f) => f.level === 'error' || f.level === 'warn');
+  const repeated = actionable.filter((f) => unchangedSinceLastRun(f)).length;
+  const delta =
+    repeated && repeated < actionable.length
+      ? color.dim(` · ${repeated} unchanged, ${actionable.length - repeated} new since your last run`)
+      : repeated && repeated === actionable.length
+        ? color.dim(' · all unchanged since your last run')
+        : '';
+  if (errors.length) {
+    console.log(color.red(color.bold('FAIL')) + `  ${errors.length} error(s), ${warns.length} warning(s)` + delta);
+  } else if (unknown.length) {
+    // NOT a pass: nothing contradicted the declarations, but some of them were never examined.
+    console.log(
+      color.yellow(color.bold('INCONCLUSIVE')) +
+        color.dim(`  ${unknown.length} check(s) could not run, ${warns.length} warning(s) — retry, do not repair`),
+    );
+  } else {
+    console.log(color.green(color.bold('PASS')) + color.dim(`  ${warns.length} warning(s)`));
+  }
+  printLagoonAvailability();
+}
+
+/**
+ * WHERE A PERSON CAN LOOK AT THIS RIGHT NOW — printed under every verdict, pass or fail.
+ *
+ * A green report describes files. The thing the work is FOR is a rendered region, and for the whole
+ * of a bench run no agent ever handed one over: each finished on a passing check and a summary, and
+ * the person who asked for the work had nothing to open. The rules already said to look; nothing in
+ * the loop ever mentioned it, so it was the step that quietly did not happen.
+ *
+ * This is a NUDGE, not a gate, and deliberately so. Failing a static check because no dev server is
+ * running would make `motu check` depend on a process and a network — untrue to what it examines, and
+ * unrunnable in CI. So: the URL when there is one, and how to get one when there is not.
+ */
+export function printLagoonAvailability() {
+  const url = readLiveUrl();
+  if (url) console.log(color.dim('  look at it: ') + url);
+  else console.log(color.dim('  no live lagoon — start one with: motu lagoon serve --watch --detach'));
+}