lynkeus 0.3.0 → 0.5.0

package/src/cases/traces.ts

@@ -193,7 +193,7 @@ export const decodeJson = (body: unknown): Span[] => {
 
 // What a report keeps of a span's attributes: what it did, not every label an instrumentation adds.
 const KEEP =
-  /^(http\.(request\.)?method|http\.(response\.)?status_code|http\.route|http\.target|url\.(path|full)|server\.address|net\.peer\.name|db\.(system|statement|operation|sql\.table)|messaging\.|code\.(namespace|function)|rpc\.|exception\.message|enduser\.id)/;
+  /^(http\.(request\.)?method|http\.(response\.)?status_code|http\.route|http\.target|url\.(path|full)|server\.address|net\.peer\.name|messaging\.|code\.(namespace|function)|rpc\.|exception\.message|enduser\.id)/;
 
 /**
  * Listens for OTLP traces while a run goes on: a backend with OTEL_EXPORTER_OTLP_ENDPOINT pointed here sends
@@ -272,6 +272,8 @@ export class TraceSink {
       return undefined;
     };
     for (const span of [...spans].sort((a, b) => (a.startNs < b.startNs ? -1 : 1))) {
+      // A database query never leaves the machine: its statement names the backend's tables and columns.
+      if (span.attributes['db.system'] !== undefined) continue;
       const where = place(span);
       if (!where) continue;
       const startedMs = [...steps.values()].find((s) => s.index === where.step)!.startedMs;

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 } from './config.js';
-import { agentMismatch } from './device/agentVersion.js';
+import { graphFile, loadConfig, loadGraph, portFromEnv, readToken } from './config.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 => {
@@ -56,8 +72,15 @@ const contextFor = (argv: string[], attached = false, port?: number, ownHost = f
     const appId = (g.app as string | undefined) ?? process.env.LYNKEUS_APP_ID ?? config.app;
     const started = performance.now();
     const attachedIn = (d: Device) => err(`attached in ${Math.round(performance.now() - started)}ms (${d.info.name})`);
-    const server = new AgentServer({ token: process.env.LYNKEUS_TOKEN, port: port ?? portFromEnv(config) });
+    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

@@ -2,6 +2,7 @@ import { type ChildProcess, spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
 
 import { Fixtures } from '../cases/fixtures.js';
 import { readCases } from '../cases/format.js';
@@ -18,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.
@@ -27,8 +30,27 @@ 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.
+  const why = () => {
+    const plain = stripVTControlCharacters(output);
+    const explained = plain.split('lynkeus: what this looks like')[1];
+    if (explained)
+      return explained
+        .trim()
+        .split('\n')
+        .map((line) => line.trim())
+        .join(' · ');
+    // 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) => {
       clearTimeout(timer);
@@ -37,15 +59,17 @@ 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();
-      else if (/Test suite failed/.test(output)) settle(new Error(`the host failed to start: ${tail(5)}`));
     };
     host.stdout?.on('data', read);
     host.stderr?.on('data', read);
-    host.once('exit', (code) => settle(new Error(`the host exited (${code}): ${tail(3)}`)));
+    // 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;
 };
 
@@ -102,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 };
@@ -169,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',
@@ -194,7 +259,32 @@ 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',
+        help: 'with --screenshots: how long the screen must stay still before a frame, in ms; 700 for frames two runs can be compared by',
+        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',
@@ -204,6 +294,7 @@ export const caseCommands = [
       push: { type: 'boolean', help: 'with --out: upload the run to the reports service when it ends and print the report’s address' },
       project: { type: 'string', help: 'with --push: the project the run is filed under (default: the app’s folder name)', value: 'name' },
       'video-fps': { type: 'number', help: 'frames per second of the film', default: 30, value: 'n' },
+      'video-scale': { type: 'number', help: 'pixels per point of the film, where the host takes one (fastsim: 1 to 3, 2 unless told)', value: 'n' },
       flakes: { type: 'string', help: 'the ledger of how each case did across runs (default .lynkeus/flakes.json)', value: 'file' },
       prepared: { type: 'string', help: 'where `case prepare` leaves setups made ahead; a case found there skips its setup', value: 'dir' },
       jobs: { type: 'number', help: 'cases at once, each on its own host (needs --ports)', value: 'n', default: 1 },
@@ -220,7 +311,33 @@ export const caseCommands = [
     },
     needs: 'nothing',
     session: false,
-    mcp: false,
+    mcp: 'core',
+    mcpOmit: [
+      'seen',
+      'report',
+      'events',
+      'settle',
+      'still',
+      'frames-on-change',
+      'frames',
+      'traces',
+      'traces-port',
+      'video-fps',
+      'video-scale',
+      'flakes',
+      'prepared',
+      'jobs',
+      'ports',
+      'host-command',
+      'in-order',
+      'ahead',
+      'idle',
+      'continue',
+      'video',
+      'project',
+    ],
+    mcpDetails:
+      'Runs case files (default: all in cases.dir) against the attached app, or with `host` in Node. A case that fails comes back with its screen and reason. `out` + `screenshots` + `push` uploads the run and prints its address.',
     run: async (ctx) => {
       const config = ctx.config.cases ?? {};
       const home = config.base ?? ctx.root;
@@ -241,12 +358,18 @@ export const caseCommands = [
           ? {
               dir: out.evidenceDir(id, attempt),
               screenshots: !!ctx.flags.screenshots,
-              ...(ctx.flags.video ? { video: { fps: Number(ctx.flags['video-fps'] ?? 30) } } : {}),
+              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']) } : {}) } }
+                : {}),
             }
           : 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(
@@ -297,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']) {
@@ -359,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 });
@@ -407,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();
       }
@@ -414,9 +548,15 @@ export const caseCommands = [
       const unsupported = count('unsupported');
       const summary = [
         ...reports.map(
-          (r) => `${{ passed: '✅', failed: '❌', unsupported: '🚫' }[r.result]} ${r.id}${r.retried && r.result === 'passed' ? '  ⚠ passed on retry' : ''}`,
+          (r) =>
+            `${{ passed: '✅', failed: '❌', unsupported: '🚫' }[r.result]} ${r.id}${r.retried && r.result === 'passed' ? '  ⚠ passed on retry' : ''}` +
+            // In a session or over MCP the caller reads this answer and nothing else: a case that did not pass brings its steps.
+            (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
           ? [
@@ -424,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',
               ),
             ]
           : []),
@@ -481,7 +623,7 @@ export const caseCommands = [
     flags: { force: { type: 'boolean', help: 'overwrite what is there' } },
     needs: 'nothing',
     session: false,
-    mcp: false,
+    mcp: 'core',
     run: async (ctx) => {
       const dir = path.resolve(ctx.root, ctx.config.cases?.dir ?? 'cases');
       fs.mkdirSync(dir, { recursive: true });

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();
+      }
+    },
+  }),
+];