lynkeus 0.4.0 → 0.5.0

package/src/cli.ts

@@ -11,16 +11,30 @@ import { driveCommands } from './commands/drive.js';
 import { headlessCommands } from './commands/headless.js';
 import { mapCommands } from './commands/map.js';
 import { osCommands } from './commands/os.js';
+import { ciCommands } from './commands/ci.js';
+import { coverageCommands } from './commands/coverage.js';
+import { fixturesCommands } from './commands/fixtures.js';
 import { reportCommands } from './commands/report.js';
 import { runsCommands } from './commands/runs.js';
 import { graphFile, loadConfig, loadGraph, portFromEnv, readToken } from './config.js';
-import { agentMismatch } from './device/agentVersion.js';
+import { agentMismatch, appSwitched, helloIdentity } from './device/agentVersion.js';
 import { HEADLESS_HOST, pickAgentDevice, pickAndroidDevice } from './device/devices.js';
 import { Device } from './device/driver.js';
 import { type Base, commands, find, helpFor, inSession, referenceMarkdown, register, resolve, usage } from './registry.js';
 import { execute } from './runtime.js';
 
-register([...driveCommands, ...osCommands, ...mapCommands, ...runsCommands, ...caseCommands, ...reportCommands, ...headlessCommands]);
+register([
+  ...driveCommands,
+  ...osCommands,
+  ...mapCommands,
+  ...runsCommands,
+  ...caseCommands,
+  ...coverageCommands,
+  ...ciCommands,
+  ...fixturesCommands,
+  ...reportCommands,
+  ...headlessCommands,
+]);
 
 /** The global flags, read leniently from the whole argv before any command parses its own. */
 const globals = (argv: string[]) => {
@@ -42,6 +56,8 @@ export type Session = { ctx: Base; stop: () => Promise<void> };
 
 // Once per process: a suite reattaches for every case.
 let mismatchTold = false;
+let switchTold = false;
+let lastApp: string | undefined;
 
 // `ownHost`: the port belongs to a host this run started for a case; whatever dials in is the device.
 const contextFor = (argv: string[], attached = false, port?: number, ownHost = false): Session => {
@@ -58,6 +74,13 @@ const contextFor = (argv: string[], attached = false, port?: number, ownHost = f
     const attachedIn = (d: Device) => err(`attached in ${Math.round(performance.now() - started)}ms (${d.info.name})`);
     const server = new AgentServer({ token: readToken(root), port: port ?? portFromEnv(config) });
     server.on('hello', (hello: HelloEvent) => {
+      const identity = helloIdentity(hello);
+      const switched = switchTold ? undefined : appSwitched(lastApp, identity, server.port);
+      lastApp = identity;
+      if (switched) {
+        switchTold = true;
+        err(switched);
+      }
       const told = mismatchTold ? undefined : agentMismatch(hello);
       if (!told) return;
       mismatchTold = true;

package/src/commands/cases.ts

@@ -19,6 +19,8 @@ import { eventsFile } from '../knowledge/events.js';
 import { type Base, define } from '../registry.js';
 import { describeChanges, pushRun, service } from './report.js';
 import { TraceSink } from '../cases/traces.js';
+import { megabytes, sizeOf } from '../cases/runDirs.js';
+import { type NativeLogs, startNativeLogs } from '../cases/nativeLogs.js';
 
 const startHost = async (root: string, err: (line: string) => void): Promise<ChildProcess> => {
   // Its own process group: the host starts a test runner of its own, and stopping one without the other leaves an app dialing in.
@@ -28,6 +30,11 @@ const startHost = async (root: string, err: (line: string) => void): Promise<Chi
     stdio: ['ignore', 'pipe', 'pipe'],
     detached: true,
   });
+  // Everything the host prints, for the render errors and warnings a failed case points at; the console keeps the run's own lines.
+  const logFile = path.join(os.tmpdir(), `lynkeus-headless-${process.pid}.log`);
+  const logStream = fs.createWriteStream(logFile);
+  logStream.on('error', () => {});
+  host.once('exit', () => logStream.end());
   let output = '';
   const tail = (n: number) => output.trim().split('\n').slice(-n).join(' · ');
   // `headless start` ends a crash with what it usually means; without that, the error line jest printed.
@@ -40,7 +47,9 @@ const startHost = async (root: string, err: (line: string) => void): Promise<Chi
         .split('\n')
         .map((line) => line.trim())
         .join(' · ');
-    return plain.match(/^\s*(\w*Error\b.*|Cannot find module.*)$/m)?.[1]?.trim() ?? tail(3);
+    // Jest prints a suite that throws while loading as "● Test suite failed to run", then the thrown message.
+    const thrown = plain.match(/Test suite failed to run\s*\n\s*\n?\s*(\S.*)$/m)?.[1]?.trim();
+    return thrown ?? plain.match(/^\s*(\w*Error\b.*|Cannot find module.*)$/m)?.[1]?.trim() ?? tail(3);
   };
   await new Promise<void>((resolve, reject) => {
     const settle = (error?: Error) => {
@@ -50,6 +59,7 @@ const startHost = async (root: string, err: (line: string) => void): Promise<Chi
     };
     const timer = setTimeout(() => settle(new Error(`the host did not come up within 180 s: ${tail(3)}`)), 180_000);
     const read = (chunk: Buffer) => {
+      logStream.write(chunk);
       output = (output + chunk.toString()).slice(-4000);
       if (/waiting for a driver/.test(output)) settle();
     };
@@ -58,7 +68,8 @@ const startHost = async (root: string, err: (line: string) => void): Promise<Chi
     // A suite that fails to load exits right after printing why, so its explanation is read in full here.
     host.once('exit', (code) => settle(new Error(`${/Test suite failed/.test(output) ? 'the host failed to start' : `the host exited (${code})`}: ${why()}`)));
   });
-  err('host: up');
+  // The listeners above stay: the log takes all the host prints until it stops.
+  err(`host: up (its log: ${logFile})`);
   return host;
 };
 
@@ -115,19 +126,27 @@ const idleShare = async (): Promise<number> => {
   return after.all > before.all ? (after.idle - before.idle) / (after.all - before.all) : 1;
 };
 
-/** The case files named, or every case under the cases directory; a sentence when there are none. */
-const caseFiles = (args: string[], home: string, casesDir: string | undefined): string[] | string => {
+/** Every case under a directory and its subdirectories, in path order, so a suite can group its cases in folders. */
+const casesIn = (dir: string): string[] =>
+  fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => !e.name.startsWith('.') && e.name !== 'node_modules')
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .flatMap((e) => {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) return casesIn(full);
+      return e.name.endsWith('.md') && !/^(README|FORMAT|CATALOG)\.md$/i.test(e.name) ? [full] : [];
+    });
+
+/** The case files named (a directory stands for every case under it), or every case under the cases directory; a sentence when there are none. */
+export const caseFiles = (args: string[], home: string, casesDir: string | undefined): string[] | string => {
   const dir = path.resolve(home, casesDir ?? 'cases');
-  const files = args.length
-    ? args.map((f) => path.resolve(f))
-    : fs.existsSync(dir)
-      ? fs
-          .readdirSync(dir)
-          .filter((f) => f.endsWith('.md') && !/^(README|FORMAT|CATALOG)\.md$/i.test(f) && !f.startsWith('.'))
-          .sort()
-          .map((f) => path.join(dir, f))
-      : [];
-  return files.length > 0 ? files : `no cases under ${path.relative(home, dir) || '.'}; \`lynkeus case init\` writes one`;
+  const named = args.map((f) => path.resolve(f));
+  const missing = named.find((f) => !fs.existsSync(f));
+  if (missing) return `no such case file: ${path.relative(process.cwd(), missing) || missing}`;
+  const files = named.length ? named.flatMap((f) => (fs.statSync(f).isDirectory() ? casesIn(f) : [f])) : fs.existsSync(dir) ? casesIn(dir) : [];
+  const where = named.length === 1 ? path.relative(home, named[0]!) : path.relative(home, dir);
+  return files.length > 0 ? files : `no cases under ${where || '.'}; \`lynkeus case init\` writes one`;
 };
 
 type PrepareOptions = { base: Base; config: CasesConfig; store: Store; open: () => Fixtures; limit: number; idle: number; jobs: number };
@@ -182,15 +201,48 @@ const spawnHost = (command: string, port: number, job: number, cwd: string): Chi
   });
 
 /** A run that could not be uploaded still ran: the failure is said, not raised. */
-const pushed = async (dir: string, to: Exclude<ReturnType<typeof service>, string>, project: string) => {
+// A run that kept evidence but none of a kind says so when it ends, not only as a gap in the report.
+export const missingEvidence = (reports: CaseReport[], asked: { video: boolean }): string[] => {
+  if (reports.length === 0) return [];
+  const steps = reports.flatMap((r) => r.steps);
+  const fromApp = steps.some((s) => s.sent?.some((e) => e.via !== 'server')) || reports.some((r) => (r.events?.length ?? 0) > 0);
+  return [
+    ...(fromApp ? [] : ['⚠ no case kept an analytics event from the app (the agent keeps the calls that reach Mixpanel, AppsFlyer and Firebase Analytics).']),
+    ...(asked.video && !reports.some((r) => r.video)
+      ? ['⚠ --video kept no film: this host does not film (fastsim does; a simulator, an emulator or headless keep frames only).']
+      : []),
+  ];
+};
+
+const pushed = async (
+  dir: string,
+  to: Exclude<ReturnType<typeof service>, string>,
+  project: string,
+  err: (line: string) => void,
+  afterPush: 'keep' | 'delete' = 'keep',
+) => {
   try {
-    const run = await pushRun(dir, { ...to, project });
-    return [`report: ${run.url}${run.refused.length ? ` (not kept on this plan: ${run.refused.join(', ')})` : ''}`, ...describeChanges(run.changes)].join('\n');
+    const run = await pushRun(dir, { ...to, project, onReady: (url) => err(`report: ${url} (its frames are on their way)`), onProgress: err });
+    return [
+      `report: ${run.url}${run.refused.length ? ` (not kept on this plan: ${run.refused.join(', ')})` : ''}`,
+      ...describeChanges(run.changes),
+      keptOrDeleted(dir, afterPush, run.refused.length === 0),
+    ].join('\n');
   } catch (error) {
     return `the report was not uploaded: ${(error as Error).message}`;
   }
 };
 
+// After a push: the folder deleted when the config asks and the service took every file, else how much it holds.
+export const keptOrDeleted = (dir: string, afterPush: 'keep' | 'delete', complete: boolean): string => {
+  const bytes = sizeOf(dir);
+  if (afterPush === 'delete' && complete) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    return `run folder deleted after the push (${megabytes(bytes)})`;
+  }
+  return `run folder: ${megabytes(bytes)} on disk${afterPush === 'delete' ? ', kept because some files were not taken' : ''} · \`lynkeus report prune ${path.dirname(dir)} --older 7d\` frees old ones`;
+};
+
 export const caseCommands = [
   define({
     name: 'case run',
@@ -207,6 +259,10 @@ export const caseCommands = [
       report: { type: 'string', help: 'append one JSON line per case', value: 'file' },
       events: { type: 'string', help: 'keep what the app told its analytics, per case, as <dir>/<case id>/events.jsonl', value: 'dir' },
       out: { type: 'string', help: 'write the run as a directory a report can read: run.json and cases.jsonl, a line per attempt', value: 'dir' },
+      'no-app-events': {
+        type: 'boolean',
+        help: "with --out: leave the app's own event list unread. Reading it can turn on the app's tracking debug, which may draw on the screen; frames two runs compare should not have it",
+      },
       screenshots: { type: 'boolean', help: 'with --out: a frame of the screen after every step of the app' },
       settle: {
         type: 'number',
@@ -214,6 +270,21 @@ export const caseCommands = [
         default: 150,
         value: 'ms',
       },
+      'frames-on-change': {
+        type: 'boolean',
+        help: 'with --screenshots: a step that only looks (app.see, app.wait) on an unchanged screen shares the last frame',
+      },
+      still: {
+        type: 'number',
+        help: 'with --screenshots, on a simulator or emulator: take each frame again until two in a row match, this many ms apart (a native transition the agent cannot see)',
+        value: 'ms',
+      },
+      frames: {
+        type: 'string',
+        help: "with --screenshots: avif, the default and a few percent of the bytes (a simulator's or emulator's PNG is encoded again), or png, exact, only for frames two runs are compared by pixel for pixel",
+        default: 'avif',
+        value: 'avif|png',
+      },
       video: { type: 'boolean', help: 'with --out: film each case, where the host films (the step says at what second it began)' },
       traces: {
         type: 'boolean',
@@ -246,6 +317,9 @@ export const caseCommands = [
       'report',
       'events',
       'settle',
+      'still',
+      'frames-on-change',
+      'frames',
       'traces',
       'traces-port',
       'video-fps',
@@ -285,6 +359,9 @@ export const caseCommands = [
               dir: out.evidenceDir(id, attempt),
               screenshots: !!ctx.flags.screenshots,
               settleMs: Number(ctx.flags.settle ?? 150),
+              ...(ctx.flags.still ? { stillMs: Number(ctx.flags.still) } : {}),
+              ...(ctx.flags['frames-on-change'] ? { onChange: true } : {}),
+              frames: ctx.flags.frames === 'png' ? ('png' as const) : ('avif' as const),
               ...(ctx.flags.video
                 ? { video: { fps: Number(ctx.flags['video-fps'] ?? 30), ...(ctx.flags['video-scale'] ? { scale: Number(ctx.flags['video-scale']) } : {}) } }
                 : {}),
@@ -292,7 +369,7 @@ export const caseCommands = [
           : undefined;
       const ledger = dry ? undefined : new Flakes(path.resolve(ctx.root, typeof ctx.flags.flakes === 'string' ? ctx.flags.flakes : '.lynkeus/flakes.json'));
       // A run file files each event under its step, so it needs them collected.
-      const events = typeof ctx.flags.events === 'string' || out !== undefined;
+      const events = typeof ctx.flags.events === 'string' || (out !== undefined && !ctx.flags['no-app-events']);
       const claimed = dry
         ? undefined
         : claimPorts(
@@ -343,6 +420,15 @@ export const caseCommands = [
         const hostCommand = typeof ctx.flags['host-command'] === 'string' && !dry ? ctx.flags['host-command'] : undefined;
         if ((jobs > 1 || hostCommand) && (ports.length < jobs || ports.some((p) => !Number.isInteger(p)) || !ctx.forPort))
           return { text: `--jobs and --host-command need a driver port per job: --ports with ${jobs}`, code: 2 };
+        // One simulator or emulator, one log: with several jobs a line could not be told to its case.
+        const native: NativeLogs | undefined =
+          out && jobs === 1 && !hostCommand && !ctx.flags.host && ctx.config.app
+            ? await ctx
+                .device()
+                .then((d) => d.resolved())
+                .then((info) => startNativeLogs(info, ctx.config.app as string))
+                .catch(() => undefined)
+            : undefined;
         // Several jobs finish together only if the longest cases start first: one left for the end runs alone
         // while the other jobs wait. A case the ledger has not timed goes first too, as it may be long.
         if (jobs > 1 && ledger && !ctx.flags['in-order']) {
@@ -405,6 +491,7 @@ export const caseCommands = [
                     continue: !!ctx.flags.continue,
                     routes: seenDir ? (host ? 'fresh' : true) : false,
                     traces,
+                    nativeLogs: native,
                   });
                   if (seenDir && report.result === 'passed' && report.routes?.length) {
                     fs.mkdirSync(seenDir, { recursive: true });
@@ -453,6 +540,7 @@ export const caseCommands = [
         await Promise.all(Array.from({ length: jobs }, (_, i) => job(i)));
         await preparing;
         if (out) out.finish({ platform: seen?.platform, native: seen?.native });
+        native?.stop();
       } finally {
         stop();
       }
@@ -466,6 +554,9 @@ export const caseCommands = [
             (ctx.attached && r.result !== 'passed' ? `\n${describe(r)}` : ''),
         ),
         `${count('passed')}/${reports.length} passed${unsupported ? `, ${unsupported} cannot run on this host` : ''}`,
+        // Its full path: a relative --out resolves against where the CLI was started, which over MCP is the app's folder.
+        ...(out ? [`run kept in ${path.resolve(ctx.flags.out as string)}`] : []),
+        ...(out ? missingEvidence(reports, { video: !!ctx.flags.video }) : []),
         ...(ledger ? ledger.flaky(reports.map((r) => r.id)) : []),
         ...(reportsTo && out
           ? [
@@ -473,6 +564,8 @@ export const caseCommands = [
                 path.resolve(ctx.flags.out as string),
                 reportsTo,
                 typeof ctx.flags.project === 'string' ? ctx.flags.project : path.basename(ctx.root),
+                ctx.err,
+                ctx.config.report?.afterPush === 'delete' ? 'delete' : 'keep',
               ),
             ]
           : []),

package/src/commands/ci.ts

@@ -0,0 +1,189 @@
+import { type ChildProcess, spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { coverageOf, impactOf, readSeen } from '../cases/coverage.js';
+import { readCases } from '../cases/format.js';
+import { screensAffectedBy } from '../knowledge/query.js';
+import { define } from '../registry.js';
+import { caseFiles } from './cases.js';
+import { changedSources } from './map.js';
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/** The case results of a run folder, by each case's last attempt. */
+export const resultsOf = (dir: string): { id: string; result: string; title?: string }[] => {
+  const file = path.join(dir, 'cases.jsonl');
+  if (!fs.existsSync(file)) return [];
+  const last = new Map<string, { id: string; result: string; title?: string }>();
+  for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    const c = JSON.parse(line) as { id: string; result: string; title?: string };
+    last.set(c.id, c);
+  }
+  return [...last.values()];
+};
+
+/** The summary a CI job shows: how many passed, which failed, and the report. */
+export const summaryOf = (results: { id: string; result: string; title?: string }[], report: string | undefined, picked: string): string => {
+  const failed = results.filter((r) => r.result === 'failed');
+  const passed = results.filter((r) => r.result === 'passed').length;
+  return [
+    `### lynkeus: ${passed}/${results.length} cases passed${failed.length ? `, ${failed.length} failed` : ''}`,
+    '',
+    picked,
+    ...(report ? ['', `[Open the report](${report})`] : []),
+    ...(failed.length ? ['', '| Failed | |', '|---|---|', ...failed.map((f) => `| \`${f.id}\` | ${f.title ?? ''} |`)] : []),
+    '',
+  ].join('\n');
+};
+
+const waitFor = async (ok: () => boolean | Promise<boolean>, timeoutMs: number, every = 3000): Promise<boolean> => {
+  const until = Date.now() + timeoutMs;
+  for (;;) {
+    if (await ok()) return true;
+    if (Date.now() > until) return false;
+    await sleep(every);
+  }
+};
+
+export const ciCommands = [
+  define({
+    name: 'ci',
+    group: 'runs',
+    summary: 'Run the suite the way a CI job does: bring the backend and N hosts up, run the cases across them, report, tear down',
+    details:
+      'Reads `ci` in lynkeus.config.json: `backend.up` / `backend.down` (the project’s commands; lynkeus knows no backend) and `backend.ready` (a URL to wait for), `hosts.count` and `hosts.command` (default: a headless host; `{port}` is where it dials), `push`, and extra `run` flags. --affected runs only the cases a branch’s changes reach (as `case impact` finds them). Writes the job summary to $GITHUB_STEP_SUMMARY when it is set. The exit code is the suite’s.',
+    flags: {
+      affected: { type: 'boolean', help: 'only the cases the changes against --base reach' },
+      base: { type: 'string', help: 'git ref --affected diffs against', default: 'origin/main', value: 'ref' },
+      jobs: { type: 'number', help: 'how many hosts and jobs (default ci.hosts.count, else 2)', value: 'n' },
+      out: { type: 'string', help: 'where the run goes', default: 'lynkeus-run', value: 'dir' },
+      'keep-up': { type: 'boolean', help: 'leave the backend and the hosts up afterwards' },
+      'dry-run': { type: 'boolean', help: 'say what it would do and run nothing' },
+    },
+    needs: 'nothing',
+    session: false,
+    mcp: false,
+    run: async (ctx) => {
+      const ci = ctx.config.ci ?? {};
+      const config = ctx.config.cases ?? {};
+      const home = config.base ?? ctx.root;
+      const self = process.argv[1]!;
+      const say = (line: string) => ctx.err(`▸ ${line}`);
+      const jobs = Math.max(1, Number(ctx.flags.jobs ?? ci.hosts?.count ?? 2));
+      const out = path.resolve(ctx.root, String(ctx.flags.out));
+
+      // Which cases: all, or the ones the branch's changes reach.
+      const all = caseFiles([], home, config.dir);
+      if (typeof all === 'string') return { text: all, code: 1 };
+      let files = all;
+      let picked = `All ${all.length} case files.`;
+      if (ctx.flags.affected) {
+        const graphFile = path.join(ctx.root, '.lynkeus', 'graph.json');
+        if (!fs.existsSync(graphFile)) spawnSync(process.execPath, [self, 'map', 'build'], { cwd: ctx.root, stdio: 'inherit' });
+        const cases = all.flatMap(readCases);
+        const graph = ctx.graph();
+        const coverage = coverageOf(cases, Object.keys(graph.screens).sort(), readSeen(path.join(ctx.root, '.lynkeus', 'seen')));
+        const changed = changedSources(ctx.root, String(ctx.flags.base), ctx.err);
+        const impact = impactOf(screensAffectedBy(graph, changed), coverage);
+        files = [...new Set(impact.cases.map((c) => c.file))];
+        picked = `${files.length} of ${all.length} case files: the ones the ${changed.length} changed source file(s) against ${ctx.flags.base} reach.`;
+        if (files.length === 0) {
+          if (process.env.GITHUB_STEP_SUMMARY) fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `### lynkeus: no case to run\n\n${picked}\n`);
+          return { text: `no case to run: ${picked}`, json: { files } };
+        }
+      }
+      const ports = Array.from({ length: jobs }, (_, i) => 8123 + i);
+      const hostCommand = ci.hosts?.command ?? `LYNKEUS_PORT={port} "${process.execPath}" "${self}" headless start`;
+      const runArgs = [
+        'case',
+        'run',
+        ...files,
+        '--jobs',
+        String(jobs),
+        '--ports',
+        ports.join(','),
+        '--out',
+        out,
+        '--screenshots',
+        ...(ci.push ? ['--push'] : []),
+        ...(ci.run ?? []),
+      ];
+      if (ctx.flags['dry-run']) {
+        const plan = [
+          picked,
+          ci.backend ? `backend: \`${ci.backend.up}\`${ci.backend.ready ? `, ready at ${ci.backend.ready}` : ''}` : 'backend: none declared (ci.backend)',
+          `hosts: ${jobs} × \`${hostCommand}\` on ${ports.join(', ')}`,
+          `run: lynkeus ${runArgs.slice(0, 2).join(' ')} … ${runArgs.slice(2 + files.length).join(' ')}`,
+        ];
+        return { text: plan.join('\n'), json: { files, ports, hostCommand, runArgs } };
+      }
+
+      const hosts: ChildProcess[] = [];
+      const down = () => {
+        if (ctx.flags['keep-up']) return say('left up (--keep-up)');
+        for (const h of hosts)
+          if (h.pid)
+            try {
+              process.kill(-h.pid, 'SIGTERM');
+            } catch {}
+        if (ci.backend?.down) {
+          say('backend down');
+          spawnSync('/bin/sh', ['-c', ci.backend.down], { cwd: ctx.root, stdio: 'inherit' });
+        }
+      };
+      try {
+        if (ci.backend) {
+          say(`backend up: ${ci.backend.up}`);
+          const up = spawnSync('/bin/sh', ['-c', ci.backend.up], { cwd: ctx.root, stdio: 'inherit' });
+          if (up.status !== 0) return { text: `the backend did not come up (\`${ci.backend.up}\` exited ${up.status})`, code: 1 };
+          if (ci.backend.ready) {
+            const url = ci.backend.ready;
+            say(`waiting for ${url}`);
+            const ready = await waitFor(
+              () =>
+                fetch(url).then(
+                  (r) => r.ok,
+                  () => false,
+                ),
+              ci.backend.timeoutMs ?? 300_000,
+            );
+            if (!ready) return { text: `${url} never answered`, code: 1 };
+          }
+        }
+        say(`${jobs} host${jobs === 1 ? '' : 's'}: ${hostCommand}`);
+        for (const port of ports)
+          hosts.push(
+            spawn('/bin/sh', ['-c', hostCommand.replaceAll('{port}', String(port))], { cwd: ctx.root, stdio: ['pipe', 'ignore', 'ignore'], detached: true }),
+          );
+        // A host compiles the app before it answers: the slow part.
+        for (const port of ports) {
+          const answered = () =>
+            spawnSync(process.execPath, [self, 'screen'], {
+              cwd: ctx.root,
+              env: { ...process.env, LYNKEUS_PORT: String(port) },
+              stdio: 'ignore',
+              timeout: 20_000,
+            }).status === 0;
+          if (!(await waitFor(answered, ci.hosts?.timeoutMs ?? 600_000, 5000))) return { text: `the host on ${port} never attached`, code: 1 };
+          say(`host on ${port} ready`);
+        }
+        say(`running ${files.length} case file(s) on ${jobs} host(s)`);
+        const run = spawnSync(process.execPath, [self, ...runArgs], {
+          cwd: ctx.root,
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'inherit'],
+          maxBuffer: 64 * 1024 * 1024,
+        });
+        process.stdout.write(run.stdout ?? '');
+        const report = /report: (https?:\/\/\S+)/.exec(run.stdout ?? '')?.[1];
+        const summary = summaryOf(resultsOf(out), report, picked);
+        if (process.env.GITHUB_STEP_SUMMARY) fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, summary);
+        return { text: summary, code: run.status ?? 1 };
+      } finally {
+        down();
+      }
+    },
+  }),
+];

package/src/commands/coverage.ts

@@ -0,0 +1,147 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { coverageOf, impactOf, readSeen } from '../cases/coverage.js';
+import { draftCase } from '../cases/draft.js';
+import { Fixtures } from '../cases/fixtures.js';
+import { readCases } from '../cases/format.js';
+import { edgesFile } from '../config.js';
+import * as edges from '../knowledge/edges.js';
+import { plan } from '../knowledge/plan.js';
+import { screensAffectedBy } from '../knowledge/query.js';
+import { type Base, define } from '../registry.js';
+import { caseFiles } from './cases.js';
+import { changedSources } from './map.js';
+
+// The project's cases and what they cover, read the way `case run` reads them.
+const coverageFor = (ctx: Base & { graph: () => { screens: Record<string, unknown> } }, seenFlag: unknown) => {
+  const config = ctx.config.cases ?? {};
+  const home = config.base ?? ctx.root;
+  const files = caseFiles([], home, config.dir);
+  if (typeof files === 'string') return files;
+  const cases = files.flatMap(readCases);
+  const seenDir = path.resolve(ctx.root, typeof seenFlag === 'string' ? seenFlag : '.lynkeus/seen');
+  return { cases, coverage: coverageOf(cases, Object.keys(ctx.graph().screens).sort(), readSeen(seenDir)) };
+};
+
+export const coverageCommands = [
+  define({
+    name: 'case coverage',
+    group: 'runs',
+    summary: 'Which of the app’s screens the cases touch, which none does, and which a case names that the app no longer has',
+    details:
+      'A screen counts as touched when a case goes to it (`app.nav`), waits for it (`app.wait`), checks it (`app.see: { route }`), or went through it on its last passing run (`case run --seen <dir>`, read from .lynkeus/seen unless --seen says where). The screens come from the route graph (`lynkeus map build`).',
+    flags: {
+      route: { type: 'string', help: 'only this screen: the cases that touch it', value: 'Route' },
+      seen: { type: 'string', help: 'where `case run --seen` kept the screens of passing cases (default .lynkeus/seen)', value: 'dir' },
+    },
+    needs: 'graph',
+    session: false,
+    mcp: 'core',
+    run: async (ctx) => {
+      const read = coverageFor(ctx, ctx.flags.seen);
+      if (typeof read === 'string') return { text: read, code: 1 };
+      const { cases, coverage } = read;
+      if (typeof ctx.flags.route === 'string') {
+        const ids = coverage.byRoute[ctx.flags.route] ?? [];
+        return { text: `${ctx.flags.route}: ${ids.length ? ids.join(', ') : 'no case'}`, json: { route: ctx.flags.route, cases: ids } };
+      }
+      const pct = coverage.routes ? Math.round((100 * coverage.covered.length) / coverage.routes) : 0;
+      const top = Object.entries(coverage.byRoute)
+        .filter(([r]) => !coverage.unknown.includes(r))
+        .sort((a, b) => b[1].length - a[1].length)
+        .slice(0, 8);
+      const lines = [
+        `${coverage.covered.length} of ${coverage.routes} screens touched by a case (${pct}%), from ${cases.length} case${cases.length === 1 ? '' : 's'}`,
+        ...(top.length ? ['most covered:', ...top.map(([r, ids]) => `  ${r.padEnd(34)} ${ids.length}`)] : []),
+        ...(coverage.unknown.length
+          ? ['named by a case, unknown to the app (renamed? a typo?):', ...coverage.unknown.map((r) => `  ${r} ← ${coverage.byRoute[r]!.join(', ')}`)]
+          : []),
+        `${coverage.uncovered.length} screen${coverage.uncovered.length === 1 ? '' : 's'} no case touches${coverage.uncovered.length ? ':' : ''}`,
+        ...coverage.uncovered.slice(0, 30).map((r) => `  ${r}`),
+        ...(coverage.uncovered.length > 30 ? [`  … ${coverage.uncovered.length - 30} more (--json)`] : []),
+      ];
+      return { text: lines.join('\n'), json: coverage };
+    },
+  }),
+  define({
+    name: 'case impact',
+    group: 'runs',
+    summary: 'The cases a branch’s changes reach, to run only those, and the reached screens no case covers',
+    details:
+      'The screens the diff against --base touches or imports (as `map check` finds them), crossed with what each case covers (as `case coverage` finds it). --files prints one case file per line: `lynkeus case run $(lynkeus case impact --files)`.',
+    flags: {
+      base: { type: 'string', help: 'git ref to diff against', default: 'main', value: 'ref' },
+      depth: { type: 'number', help: 'how many imports away a change still reaches a screen', default: 4, value: 'n' },
+      seen: { type: 'string', help: 'where `case run --seen` kept the screens of passing cases (default .lynkeus/seen)', value: 'dir' },
+      files: { type: 'boolean', help: 'print only the case files, one per line' },
+    },
+    needs: 'graph',
+    session: false,
+    mcp: 'core',
+    run: async (ctx) => {
+      const read = coverageFor(ctx, ctx.flags.seen);
+      if (typeof read === 'string') return { text: read, code: 1 };
+      const base = ctx.flags.base as string;
+      const changed = changedSources(ctx.root, base, ctx.err);
+      const affected = screensAffectedBy(ctx.graph(), changed, ctx.flags.depth as number);
+      const impact = impactOf(affected, read.coverage);
+      if (ctx.flags.files) return { text: [...new Set(impact.cases.map((c) => c.file))].join('\n'), json: impact };
+      const lines = [
+        `${changed.length} source file${changed.length === 1 ? '' : 's'} changed against ${base}; they reach ${new Set(affected.map((a) => a.route)).size} screen(s)`,
+        ...(impact.cases.length
+          ? [`cases to run (${impact.cases.length}):`, ...impact.cases.map((c) => `  ${c.id.padEnd(46)} ${c.routes.join(', ')} (via ${c.via})`)]
+          : ['no case touches them']),
+        ...(impact.untested.length ? [`reached, and touched by no case (${impact.untested.length}):`, ...impact.untested.map((r) => `  ${r}`)] : []),
+      ];
+      return { text: lines.join('\n'), json: { base, changed, ...impact } };
+    },
+  }),
+  define({
+    name: 'case new',
+    group: 'runs',
+    summary: 'Draft a case for a screen: the way there, the backend setup to pick from, and the checks left to write',
+    details:
+      'Prints a case to finish: the frontmatter with the questions a reader needs answered, the setup the project’s fixtures server offers (from `lynkeus.describe`, commented out: what state the case needs is the author’s call), the presses from --from (default `cases.start`) to the screen as `map plan` knows them, and the checks to write. --write saves it as <cases dir>/<id>.md, never over a file that is there.',
+    positionals: [{ name: 'id', help: 'the case id, which is also its file name', required: true }],
+    flags: {
+      to: { type: 'string', help: 'the screen the case is about', value: 'Route' },
+      from: { type: 'string', help: 'where it begins (default: cases.start in lynkeus.config.json)', value: 'Route' },
+      title: { type: 'string', help: 'what a person can do there, as the report will title it', value: 'text' },
+      write: { type: 'boolean', help: 'save it in the cases folder instead of printing it' },
+    },
+    needs: 'graph',
+    session: false,
+    mcp: 'core',
+    run: async (ctx) => {
+      const config = ctx.config.cases ?? {};
+      const id = ctx.args[0]!;
+      if (!/^[a-z0-9][a-z0-9._-]*$/.test(id)) return { text: `${id}: an id is lower case letters, digits, dots, dashes and underscores`, code: 2 };
+      const to = ctx.flags.to as string | undefined;
+      const from = (ctx.flags.from as string | undefined) ?? config.start;
+      if (!to) return { text: 'case new needs --to <Route>, the screen the case is about', code: 2 };
+      if (!from) return { text: 'case new needs --from <Route>, or cases.start in lynkeus.config.json', code: 2 };
+      const graph = ctx.graph();
+      if (!graph.screens[to]) return { text: `${to}: the app has no such screen (lynkeus map routes lists them)`, code: 1 };
+      const server = config.fixtures ? new Fixtures(config.fixtures, config.base ?? ctx.root) : undefined;
+      const described = server ? await server.describe().finally(() => server.close()) : undefined;
+      const text = draftCase({
+        id,
+        title: ctx.flags.title as string | undefined,
+        from,
+        to,
+        path: plan(graph, from, to, edges.load(edgesFile(ctx.root))) ?? undefined,
+        fixtures: described?.details,
+        fixturesSilent: !!server && !described,
+        macros: Object.keys(config.macros ?? {}),
+      });
+      if (!ctx.flags.write) return { text, json: { id, text } };
+      const dir = path.resolve(config.base ?? ctx.root, config.dir ?? 'cases');
+      const file = path.join(dir, `${id}.md`);
+      if (fs.existsSync(file)) return { text: `${path.relative(ctx.root, file)} is there already; pick another id or edit it`, code: 1 };
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(file, text);
+      return { text: `wrote ${path.relative(ctx.root, file)}`, json: { id, file } };
+    },
+  }),
+];