lynkeus 0.3.0 → 0.5.0

package/lib/knowledge/analyticsTraffic.js

@@ -0,0 +1,109 @@
+const isPlain = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const plain = (v) => (isPlain(v) ? v : undefined);
+const list = (v) => (Array.isArray(v) ? v : v === undefined ? [] : [v]);
+const named = (provider, items, name, props) => items.filter(isPlain).flatMap((item) => {
+    const n = name(item);
+    if (typeof n !== 'string' || !n)
+        return [];
+    const p = plain(props(item));
+    return [{ provider, name: n, ...(p ? { props: p } : {}) }];
+});
+const segment = (body, _path, provider) => {
+    const b = plain(body);
+    return named(provider, list(b?.batch ?? b), (i) => i.event ?? (i.type === 'screen' || i.type === 'page' ? `${i.type}: ${i.name}` : i.type), (i) => i.properties ?? i.traits);
+};
+const amplitude = (body) => named('amplitude', list(plain(body)?.events), (i) => i.event_type, (i) => i.event_properties);
+const posthog = (body) => {
+    const b = plain(body);
+    return named('posthog', list(b?.batch ?? (Array.isArray(body) ? body : b)), (i) => i.event, (i) => i.properties);
+};
+const mixpanel = (body) => named('mixpanel', list(body), (i) => i.event ?? (i.$set ? '$set' : undefined), (i) => i.properties ?? i.$set);
+/** Host pattern → the service, and how to read its body when there is a known shape. */
+const SERVICES = [
+    { host: /(^|\.)segment\.(io|com)$/, provider: 'segment', read: segment },
+    { host: /(^|\.)amplitude\.com$/, provider: 'amplitude', read: amplitude },
+    { host: /(^|\.)posthog\.com$/, provider: 'posthog', read: posthog },
+    { host: /(^|\.)mixpanel\.com$/, provider: 'mixpanel', read: mixpanel },
+    { host: /(^|\.)sentry\.io$|^sentry\./, provider: 'sentry' },
+    { host: /(^|\.)(datadoghq\.(com|eu)|ddog-gov\.com)$/, provider: 'datadog' },
+    { host: /(^|\.)app-measurement\.com$|^firebaselogging/, provider: 'firebase' },
+    { host: /(^|\.)appsflyer(sdk)?\.com$/, provider: 'appsflyer' },
+    { host: /(^|\.)branch\.io$/, provider: 'branch' },
+    { host: /(^|\.)braze\.(com|eu)$/, provider: 'braze' },
+    { host: /(^|\.)onesignal\.com$/, provider: 'onesignal' },
+    { host: /(^|\.)intercom\.(io|com)$/, provider: 'intercom' },
+    { host: /(^|\.)bugsnag\.com$/, provider: 'bugsnag' },
+    { host: /(^|\.)adjust\.(com|net|world)$/, provider: 'adjust' },
+    { host: /(^|\.)clevertap-prod\.com$|(^|\.)wzrkt\.com$/, provider: 'clevertap' },
+    { host: /(^|\.)heapanalytics\.com$/, provider: 'heap' },
+    { host: /(^|\.)statsig(api)?\.(com|net)$/, provider: 'statsig' },
+    { host: /(^|\.)launchdarkly\.com$/, provider: 'launchdarkly' },
+    // Segment-compatible: the same batch shape.
+    { host: /(^|\.)rudderstack\.com$|(^|\.)rudderlabs\.com$/, provider: 'rudderstack', read: segment },
+    { host: /^(track|cdp|track-eu|cdp-eu)\.customer\.io$/, provider: 'customerio', read: segment },
+    { host: /(^|\.)google-analytics\.com$|(^|\.)analytics\.google\.com$/, provider: 'googleanalytics' },
+    { host: /(^|\.)googletagmanager\.com$/, provider: 'googletagmanager' },
+    { host: /^graph\.facebook\.com$/, provider: 'meta' },
+    { host: /(^|\.)tiktok(v)?\.com$|(^|\.)tiktokapis\.com$/, provider: 'tiktok' },
+    { host: /(^|\.)iterable\.com$/, provider: 'iterable' },
+    { host: /(^|\.)moengage\.com$/, provider: 'moengage' },
+    { host: /(^|\.)kochava\.com$/, provider: 'kochava' },
+    { host: /(^|\.)singular\.net$/, provider: 'singular' },
+    { host: /(^|\.)emb-api\.com$|(^|\.)embrace\.io$/, provider: 'embrace' },
+    { host: /(^|\.)instabug\.com$|(^|\.)luciq\.ai$/, provider: 'instabug' },
+    { host: /(^|\.)smartlook\.(cloud|com)$/, provider: 'smartlook' },
+    { host: /(^|\.)urbanairship\.com$|(^|\.)airship\.(com|eu)$|(^|\.)asnapieu\.com$/, provider: 'airship' },
+    { host: /(^|\.)snplow\.net$|(^|\.)snowplowanalytics\.com$/, provider: 'snowplow' },
+    { host: /(^|\.)fullstory\.com$/, provider: 'fullstory' },
+    { host: /(^|\.)mparticle\.com$/, provider: 'mparticle' },
+    { host: /(^|\.)pendo\.io$/, provider: 'pendo' },
+    { host: /(^|\.)lr-ingest\.(io|com)$|(^|\.)logrocket\.(io|com)$/, provider: 'logrocket' },
+    { host: /(^|\.)newrelic\.com$|(^|\.)nr-data\.net$/, provider: 'newrelic' },
+    { host: /(^|\.)hotjar\.(com|io)$/, provider: 'hotjar' },
+    { host: /(^|\.)count\.ly$/, provider: 'countly' },
+];
+const parse = (text) => {
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Mixpanel's classic endpoint sends `data=<base64 JSON>` as a form.
+        const data = /(?:^|&)data=([^&]+)/.exec(text)?.[1];
+        if (!data)
+            return undefined;
+        try {
+            const raw = decodeURIComponent(data);
+            return JSON.parse(raw.startsWith('[') || raw.startsWith('{') ? raw : Buffer.from(raw, 'base64').toString('utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    }
+};
+/** The service a request went to, when it is one of the known ones. */
+export const serviceOf = (url) => {
+    try {
+        const host = new URL(url).hostname.toLowerCase();
+        return SERVICES.find((s) => s.host.test(host))?.provider;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** What a step's requests told analytics services: each body's events, or one per call to a service it cannot read. */
+export const trafficEvents = (requests) => requests.flatMap((r) => {
+    let url;
+    try {
+        url = new URL(r.url);
+    }
+    catch {
+        return [];
+    }
+    const service = SERVICES.find((s) => s.host.test(url.hostname.toLowerCase()));
+    if (!service)
+        return [];
+    const events = service.read?.(parse(r.request?.body), url.pathname, service.provider);
+    return events?.length ? events : [{ provider: service.provider, name: `${r.method} ${url.pathname}` }];
+});

package/lib/knowledge/errors.js

@@ -39,6 +39,12 @@ const RULES = [
         cause: (m) => `nothing is listening on ${m[1]}:${m[2]}`,
         fix: () => `start the backend (or the lynkeus driver, if this is the agent's socket) and check the port the entry dials.`,
     },
+    {
+        // Babel loads the project's config with require(); a plugin shipped as ESM only loads that way from Node 22.12.
+        re: /ERR_REQUIRE_ESM(?:[^\n]*?require\(\) of ES Module (\S+))?|require\(\) of ES Module (\S+)/,
+        cause: (m) => `Node ${process.versions.node} cannot require() an ES module${m[1] || m[2] ? ` (${m[1] || m[2]})` : ''}, which the babel config loads`,
+        fix: () => `run with Node 22.12 or newer (lynkeus-headless needs >=22), where require() loads ES modules.`,
+    },
     {
         re: /Test environment jest-environment-\w+ cannot be found|Unexpected token 'export'|SyntaxError: Cannot use import statement/,
         cause: () => `jest is not transforming a dependency (ESM in node_modules)`,

package/lib/knowledge/events.d.ts

@@ -2,9 +2,11 @@ export type AppEvent = {
     name: string;
     props?: Record<string, unknown>;
 };
+/** `provider`: the service the app's own list feeds, when the project says (`cases.appEvents`). */
 export type RunEvent = AppEvent & {
     step: number;
     route?: string;
+    provider?: string;
 };
 type Drainable = {
     command<T = unknown>(name: string, params?: unknown): Promise<T>;

package/lib/knowledge/why.d.ts

@@ -15,6 +15,8 @@ export type Evidence = {
         text?: string;
         route?: string;
     };
+    /** Whether the app made any request before `requests` begins: `requests` may be only those of the failed command. */
+    fetchedBefore?: boolean;
 };
 export type Finding = {
     rule: string;

package/lib/knowledge/why.js

@@ -128,7 +128,7 @@ export const explain = (e) => {
             rule: 'in-flight',
             message: `${e.inFlight} request(s) still in flight when the command gave up: the screen had not finished loading. A longer timeout, or wait for the request it needs.`,
         });
-    if (done.length === 0 && e.inFlight === 0 && e.target?.route)
+    if (done.length === 0 && e.inFlight === 0 && e.target?.route && !e.fetchedBefore)
         out.push({
             rule: 'no-requests',
             message: 'no request left the app while this ran: nothing was fetched. Is the user logged in, and is the app talking to the backend it should?',

package/lib/mcp/server.js

@@ -59,9 +59,24 @@ const argvFor = (c, input) => {
     }
     return av;
 };
+// What a model is told once, when it connects: the order things are done in, so "set lynkeus up" and "write me
+// a test for this" need nothing more from the person asking.
+const INSTRUCTIONS = `lynkeus drives a React Native app (bare or Expo) by what is on its screen, and runs cases written as readable steps.
+
+In a project you do not know, call status first: it lists what is set up and, for what is not, the one thing that fixes it.
+
+To set lynkeus up: call init (it installs lynkeus-agent, mounts it from the app's entry and makes the project's token; nobody sets a variable). The agent has native code, so the app must then be built again (npx react-native run-ios or run-android; npx expo run:ios or run:android, never Expo Go) with Metro restarted with --reset-cache. Do that with your shell if you have one, or ask the person to. Then status until an app is attached.
+
+To write a test: call case_init once if the project has no cases, and read the README.md it writes for the format. Go to the screen with press, type and wait, calling screen to see what is there (press with settle: true answers with the screen once the app has settled; a screen read right after a press can still be the one it left); prefer testIDs (#id) over text. Write the case as a markdown file in the cases folder, then call case_run with that file. A failed step comes back with the screen it failed on: fix the case or report the app's bug, do not weaken the check.
+
+To test without a simulator: call headless_init (it installs what the Node host needs and writes its entry; an Expo Router app works too), then headless_doctor for the native modules still to mock, then case_run with host. The backend the app talks to must be local: set apiUrl in lynkeus.config.json.
+
+To share a run: case_run with out, screenshots and push uploads it and prints the report's address. That needs LYNKEUS_REPORTS_KEY in this server's environment.
+
+For a run with everything (frames, film, requests, analytics, backend): case_run with out, screenshots, video (film needs fastsim), traces and push. When the run ends it warns about evidence it could not keep: pass that on.`;
 export const serve = async (session, options = {}) => {
     const { version } = createRequire(import.meta.url)('../../package.json');
-    const server = new Server({ name: 'lynkeus', version }, { capabilities: { tools: {} } });
+    const server = new Server({ name: 'lynkeus', version }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
     const served = commands().filter((c) => overMcp(c, !!options.full));
     const byName = new Map(served.map((c) => [identifier(c.name), c]));
     // So a model reading the app's screens knows their language before it starts guessing.
@@ -102,10 +117,36 @@ export const serve = async (session, options = {}) => {
         const c = byName.get(request.params.name);
         if (!c)
             return { ...text(`✗ no tool ${request.params.name}`), isError: true };
-        const r = await execute(argvFor(c, (request.params.arguments ?? {})), session.ctx);
+        const input = (request.params.arguments ?? {});
+        // An argument the tool does not take is dropped by argvFor; a run would then go on without it (every case
+        // instead of the one named), so it is refused, with what the tool does take.
+        const known = Object.keys(schemaFor(c).properties);
+        const unknown = Object.keys(input).filter((key) => !known.includes(key));
+        if (unknown.length)
+            return { ...text(`✗ ${request.params.name} takes no ${unknown.join(', ')}; it takes ${known.join(', ') || 'no arguments'}`), isError: true };
+        const r = await execute(argvFor(c, input), session.ctx);
         if (r.error)
             return { ...text(`✗ ${r.error}${r.why ? `\n\nwhy:\n${r.why}` : ''}`), isError: true };
-        return text(r.text || (r.json !== undefined ? JSON.stringify(r.json, null, 2) : 'ok'));
+        const body = text(r.text || (r.json !== undefined ? JSON.stringify(r.json, null, 2) : 'ok'));
+        // A command that ended with a non-zero code (a failed case, a server that does not keep the contract) is
+        // reported as such, with everything it said, so a model does not read it as success.
+        return r.code === 0 ? body : { ...body, isError: true };
     });
-    await server.connect(new StdioServerTransport());
+    // The client going away ends the server: the session holds the driver's port open, and a server left behind
+    // keeps the next one (or a case run) from binding it.
+    const transport = new StdioServerTransport();
+    let stopping = false;
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        void session
+            .stop()
+            .catch(() => undefined)
+            .finally(() => process.exit(0));
+    };
+    process.stdin.once('end', stop);
+    process.stdin.once('close', stop);
+    transport.onclose = stop;
+    await server.connect(transport);
 };

package/lib/runtime.d.ts

@@ -8,5 +8,13 @@ export type Outcome = {
     why?: string;
 };
 /** The screen, requests and trace after a failure, read as rules; empty when there is nothing to read. */
-export declare const whyFor: (base: Base, expected?: Expected) => Promise<string>;
+export declare const whyFor: (base: Base, expected?: Expected, startedAt?: number) => Promise<string>;
+/**
+ * The requests made while the failed command ran, and a little before: a 403 from minutes ago is not why a wait
+ * failed now. Only when the app's clock reads like this machine's (a simulator, an emulator); a host on a clock of
+ * its own keeps them all.
+ */
+export declare const duringCommand: <R extends {
+    startedAt: number;
+}>(requests: R[], startedAt: number | undefined, now?: number) => R[];
 export declare const execute: (argv: string[], base: Base) => Promise<Outcome>;

package/lib/runtime.js

@@ -8,16 +8,37 @@ import { describeWhy, explain } from './knowledge/why.js';
 import { helpFor, parseFor, resolve } from './registry.js';
 import { expectedOf } from './targets.js';
 /** The screen, requests and trace after a failure, read as rules; empty when there is nothing to read. */
-export const whyFor = async (base, expected) => {
+export const whyFor = async (base, expected, startedAt) => {
     try {
         const device = await base.device();
         const [screen, requests, trace] = await Promise.all([device.screen(), device.requests(), device.trace()]);
-        return describeWhy(explain({ screen, requests: requests.requests.slice(-40), inFlight: requests.inFlight, trace: trace.events.slice(-40), target: expected }));
+        const during = duringCommand(requests.requests, startedAt);
+        return describeWhy(explain({
+            screen,
+            requests: during.slice(-40),
+            inFlight: requests.inFlight,
+            trace: trace.events.slice(-40),
+            target: expected,
+            fetchedBefore: during.length < requests.requests.length,
+        }));
     }
     catch {
         return '';
     }
 };
+/**
+ * The requests made while the failed command ran, and a little before: a 403 from minutes ago is not why a wait
+ * failed now. Only when the app's clock reads like this machine's (a simulator, an emulator); a host on a clock of
+ * its own keeps them all.
+ */
+export const duringCommand = (requests, startedAt, now = Date.now()) => {
+    if (startedAt === undefined || requests.length === 0)
+        return requests;
+    const latest = Math.max(...requests.map((r) => r.startedAt));
+    if (Math.abs(latest - now) > 10 * 60_000)
+        return requests;
+    return requests.filter((r) => r.startedAt >= startedAt - 3000);
+};
 const TARGET_ARG = { press: 0, see: 0, wait: 0, swipe: 1, nav: 0, type: 1 };
 export const execute = async (argv, base) => {
     const found = resolve(argv);
@@ -35,6 +56,7 @@ export const execute = async (argv, base) => {
     }
     if (parsed.flags.help)
         return { code: 0, text: helpFor(command) };
+    const startedAt = Date.now();
     try {
         const result = await command.run({ ...base, ...parsed });
         if (result === undefined)
@@ -47,7 +69,7 @@ export const execute = async (argv, base) => {
         const out = { code: 1, error: error instanceof Error ? error.message : String(error) };
         const at = TARGET_ARG[command.name];
         if (at !== undefined) {
-            const why = await whyFor(base, expectedOf(parsed.args[at]));
+            const why = await whyFor(base, expectedOf(parsed.args[at]), startedAt);
             if (why)
                 out.why = why;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkeus",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Drive a React Native app running lynkeus-agent from the terminal, a test runner or an MCP client: screens, flows, smoke, crawl, and the app's screen graph.",
   "type": "module",
   "bin": "./lib/cli.js",
@@ -35,8 +35,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "lynkeus-client": "^0.3.0",
-    "lynkeus-protocol": "^0.3.0",
+    "lynkeus-client": "^0.5.0",
+    "lynkeus-protocol": "^0.5.0",
     "pngjs": "^7.0.0",
     "ts-morph": "^24.0.0",
     "yaml": "^2"
@@ -47,5 +47,8 @@
     "tsx": "^4.19.2",
     "typescript": "^6.0.3"
   },
-  "homepage": "https://github.com/lynkeushq/lynkeus#readme"
+  "homepage": "https://github.com/lynkeushq/lynkeus#readme",
+  "optionalDependencies": {
+    "sharp": "^0.34.4"
+  }
 }

package/src/cases/coverage.ts

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { Affected } from '../knowledge/query.js';
+import type { Case, Step } from './format.js';
+
+const ROUTE = /^[A-Z][\w.]+$/;
+
+// A step names a route when it goes there, waits for it or checks it is on screen.
+const routeOf = (step: Step): string | undefined => {
+  const v = step.value;
+  const named = (x: unknown) => (typeof x === 'string' && ROUTE.test(x) ? x : undefined);
+  if (step.verb === 'app.nav' || step.verb === 'app.wait')
+    return (
+      named(v) ??
+      (v && typeof v === 'object' && !Array.isArray(v) ? named((v as Record<string, unknown>).route ?? (v as Record<string, unknown>).what) : undefined)
+    );
+  if (step.verb === 'app.see') return v && typeof v === 'object' && !Array.isArray(v) ? named((v as Record<string, unknown>).route) : undefined;
+  return undefined;
+};
+
+/** The routes a case names in its steps. */
+export const routesNamed = (c: Case): string[] => [...new Set([...c.setup, ...c.steps].map(routeOf).filter((r): r is string => !!r))];
+
+/** What `case run --seen <dir>` kept: each passing case's screens, by case id. */
+export const readSeen = (dir: string | undefined): Record<string, string[]> => {
+  if (!dir || !fs.existsSync(dir)) return {};
+  const seen: Record<string, string[]> = {};
+  for (const file of fs.readdirSync(dir).filter((f) => f.endsWith('.json'))) {
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8')) as { id?: string; routes?: unknown };
+      if (typeof s.id === 'string' && Array.isArray(s.routes)) seen[s.id] = s.routes.filter((r): r is string => typeof r === 'string');
+    } catch {}
+  }
+  return seen;
+};
+
+export type Coverage = {
+  routes: number;
+  covered: string[];
+  uncovered: string[];
+  /** Routes a case names that the graph does not know: renamed, or a typo. */
+  unknown: string[];
+  byRoute: Record<string, string[]>;
+  files: Record<string, string>;
+};
+
+/** Which cases touch which of the app's routes, by what they name and what they went through last time they passed. */
+export const coverageOf = (cases: Case[], graphRoutes: string[], seen: Record<string, string[]> = {}): Coverage => {
+  const byRoute: Record<string, string[]> = {};
+  const files: Record<string, string> = {};
+  const add = (route: string, id: string) => {
+    byRoute[route] ??= [];
+    if (!byRoute[route].includes(id)) byRoute[route].push(id);
+  };
+  for (const c of cases) {
+    files[c.id] = c.file;
+    for (const r of routesNamed(c)) add(r, c.id);
+    for (const r of seen[c.id] ?? []) add(r, c.id);
+  }
+  const known = new Set(graphRoutes);
+  const covered = graphRoutes.filter((r) => byRoute[r]?.length);
+  return {
+    routes: graphRoutes.length,
+    covered,
+    uncovered: graphRoutes.filter((r) => !byRoute[r]?.length),
+    unknown: Object.keys(byRoute)
+      .filter((r) => !known.has(r))
+      .sort(),
+    byRoute,
+    files,
+  };
+};
+
+export type Impact = {
+  /** Each case to run, with the reached routes it touches, nearest first. */
+  cases: { id: string; file: string; routes: string[]; distance: number; via: string }[];
+  /** Routes the change reaches that no case touches. */
+  untested: string[];
+};
+
+/** The cases a change reaches: the screens it touches or imports, crossed with what each case covers. */
+export const impactOf = (affected: Affected[], coverage: Coverage): Impact => {
+  const nearest = new Map<string, Affected>();
+  for (const a of affected) if (!nearest.has(a.route) || nearest.get(a.route)!.distance > a.distance) nearest.set(a.route, a);
+  const byCase = new Map<string, Impact['cases'][number]>();
+  const untested: string[] = [];
+  for (const [route, hit] of nearest) {
+    const ids = coverage.byRoute[route] ?? [];
+    if (!ids.length) untested.push(route);
+    for (const id of ids) {
+      const c = byCase.get(id) ?? { id, file: coverage.files[id] ?? '', routes: [], distance: hit.distance, via: hit.via };
+      c.routes.push(route);
+      if (hit.distance < c.distance) Object.assign(c, { distance: hit.distance, via: hit.via });
+      byCase.set(id, c);
+    }
+  }
+  return { cases: [...byCase.values()].sort((a, b) => a.distance - b.distance || a.id.localeCompare(b.id)), untested: untested.sort() };
+};

package/src/cases/draft.ts

@@ -0,0 +1,75 @@
+import type { FixtureCommand } from 'lynkeus-protocol';
+
+import type { PlanStep } from '../knowledge/plan.js';
+
+export type DraftInput = {
+  id: string;
+  title?: string;
+  from: string;
+  to: string;
+  /** The way from `from` to `to`, as `map plan` finds it; undefined when no path is known. */
+  path: PlanStep[] | undefined;
+  /** What the project's fixtures server says it can do, offered as the setup to pick from. */
+  fixtures?: FixtureCommand[];
+  /** The project's macros (`app.login`…), offered too. */
+  macros?: string[];
+  /** The project declares a fixtures server that did not describe itself. */
+  fixturesSilent?: boolean;
+};
+
+const quote = (s: string) => JSON.stringify(s);
+
+const paramsHint = (c: FixtureCommand) => {
+  const params = Object.entries(c.params ?? {}).map(([k, p]) => `${k}${p.values ? ` (${p.values.join('|')})` : ''}`);
+  return params.length ? ` — ${params.join(', ')}` : '';
+};
+
+/**
+ * A case to finish: its frontmatter with the questions a reader needs answered, the backend's setup offered (never
+ * chosen: what state the case needs is the author's call), the way to the screen, and the checks left to write.
+ */
+export const draftCase = (d: DraftInput): string => {
+  const lines = [
+    '---',
+    `id: ${d.id}`,
+    `title: ${quote(d.title ?? `[What a person can do on ${d.to}]`)}`,
+    'description: >',
+    '  [What this case proves, in a sentence or two.]',
+    'why: >',
+    '  [What breaks for a person if it fails.]',
+    'given: >',
+    `  [Who the user is and what is true when it starts, on ${d.from}.]`,
+    '---',
+    'setup:',
+  ];
+  if (d.fixtures?.length) {
+    lines.push('  # Pick what the case needs; the backend answers these (lynkeus fixtures describe):');
+    for (const c of d.fixtures) {
+      const example = c.example ? ` ${JSON.stringify(c.example).replace(/"(\w+)":/g, '$1: ')}` : ' {}';
+      lines.push(`  # - ${c.name}:${example}${c.summary ? `    # ${c.summary}` : ''}${paramsHint(c)}`);
+    }
+  } else if (d.fixturesSilent)
+    lines.push('  # The fixtures server did not answer lynkeus.describe (lynkeus fixtures check says why): the setup options are not listed.');
+  else lines.push('  # The state the case needs, through the project’s fixtures (cases.fixtures).');
+  lines.push('', 'steps:');
+  if (d.macros?.length) lines.push(`  # The project's own steps: ${d.macros.join(', ')}`);
+  if (!d.path) {
+    lines.push(`  # No known way from ${d.from} to ${d.to}: \`lynkeus crawl --to ${d.to}\` learns one.`);
+    lines.push(`  - app.nav: ${d.to}`);
+  } else {
+    for (const s of d.path) {
+      if (s.press) lines.push(`  - app.press: ${quote(`#${s.press}`)}${s.source === 'static' ? '    # from the source: confirm it on screen' : ''}`);
+      else lines.push(`  # ${s.from} → ${s.to}: ${s.hint ?? 'find the control that leads here'}`);
+      lines.push(`  - app.wait: { what: ${s.opens ? quote(s.opens) : s.to}, timeoutMs: 10000 }`);
+    }
+  }
+  lines.push(
+    `  - app.see: { route: ${d.to} }`,
+    '  # [What the person does here, and what must be on screen after.]',
+    '',
+    'expected: |',
+    '  [What must be true when it ends, on screen and in the backend.]',
+    '',
+  );
+  return lines.join('\n');
+};

package/src/cases/fixtures.ts

@@ -13,7 +13,8 @@
  *
  *   {"command": "lynkeus.describe", "params": {}, "env": {}}
  *
- * — and a server that knows answers `{"commands": ["create_user", …]}`. With
+ * — and a server that knows answers `{"commands": ["create_user", …]}`, each entry a name or a description
+ * (`FixtureCommand` in lynkeus-protocol: summary, params, example). The contract is docs/FIXTURES.md. With
  * that, a case naming a fixture nobody answers is refused before anything
  * runs. A server that answers `"ok": false`, as one written before this did,
  * is taken to describe nothing, and its cases run unchecked. A server that is
@@ -26,9 +27,12 @@
  * answer anything.
  */
 import { type ChildProcessWithoutNullStreams, spawn } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 
+import type { FixtureCommand } from 'lynkeus-protocol';
+
 export type FixturesConfig = { command: string; cwd?: string; env?: Record<string, string>; timeoutMs?: number };
 
 export type Answer = Record<string, unknown>;
@@ -36,7 +40,23 @@ export type Answer = Record<string, unknown>;
 /** The one command that is lynkeus's own and not the project's. */
 export const DESCRIBE = 'lynkeus.describe';
 
-export type Description = { commands: string[]; down?: string };
+/** What the server answers: the names, with each command's description where it gave one. */
+export type Description = { commands: string[]; details: FixtureCommand[]; down?: string; protocol?: number };
+
+/** A description as the server sent it, names and descriptions mixed, made one shape; anything else is no description. */
+export const readDescription = (answer: Record<string, unknown> | undefined): Description | undefined => {
+  const list = answer?.commands;
+  if (!Array.isArray(list)) return undefined;
+  const details: FixtureCommand[] = [];
+  for (const c of list) {
+    if (typeof c === 'string' && c) details.push({ name: c });
+    else if (c && typeof c === 'object' && typeof (c as FixtureCommand).name === 'string' && (c as FixtureCommand).name) details.push(c as FixtureCommand);
+    else return undefined;
+  }
+  const down = typeof answer?.down === 'string' && answer.down ? answer.down : undefined;
+  const protocol = typeof answer?.protocol === 'number' ? answer.protocol : undefined;
+  return { commands: details.map((d) => d.name), details, ...(down ? { down } : {}), ...(protocol !== undefined ? { protocol } : {}) };
+};
 
 /** lynkeus's second own command: this connection works ahead of the cases. */
 export const AHEAD = 'lynkeus.ahead';
@@ -48,6 +68,18 @@ const envOf = (params: Record<string, unknown>): Record<string, string> =>
       .map(([k, v]) => [k.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase(), typeof v === 'object' ? JSON.stringify(v) : String(v)]),
   );
 
+const describedFile = (root: string) => path.join(root, '.lynkeus', 'fixtures-described.json');
+
+/** What the server last said it answers, and how long ago; undefined when it never did for this command. */
+export const lastDescription = (root: string, command: string): { at: number; description: Description } | undefined => {
+  try {
+    const kept = JSON.parse(fs.readFileSync(describedFile(root), 'utf8')) as { at: number; command: string; description: Description };
+    return kept.command === command ? { at: kept.at, description: kept.description } : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
 export class Fixtures {
   #config: FixturesConfig;
   #root: string;
@@ -55,6 +87,10 @@ export class Fixtures {
   #lines: string[] = [];
   #waiting: ((line: string | null) => void) | null = null;
   #stderr = '';
+  // Ends in a row without one answer. A command that cannot start (a wrong path, a backend that is not
+  // there) would otherwise be started again for every case, and each case would wait out its own start.
+  #silentEnds = 0;
+  #broken: string | null = null;
 
   constructor(config: FixturesConfig, root: string) {
     this.#config = config;
@@ -70,12 +106,15 @@ export class Fixtures {
       cwd: path.resolve(this.#root, this.#config.cwd ?? '.'),
       env: { ...process.env, ...this.#config.env },
     });
+    // Writing to a command that already ended fails here; its close says so to whoever waits.
+    child.stdin.on('error', () => undefined);
     child.stderr.on('data', (chunk: Buffer) => {
       this.#stderr = (this.#stderr + chunk.toString()).slice(-4000);
     });
     const reader = readline.createInterface({ input: child.stdout });
     reader.on('line', (line) => {
       if (!line.trim().startsWith('{')) return;
+      this.#silentEnds = 0;
       if (this.#waiting) {
         const resolve = this.#waiting;
         this.#waiting = null;
@@ -83,6 +122,7 @@ export class Fixtures {
       } else this.#lines.push(line);
     });
     child.on('close', () => {
+      if (this.#child === child) this.#silentEnds += 1;
       this.#child = null;
       this.#waiting?.(null);
       this.#waiting = null;
@@ -92,6 +132,7 @@ export class Fixtures {
   }
 
   async call(command: string, params: Record<string, unknown>): Promise<Answer> {
+    if (this.#broken) throw new Error(`${command}: ${this.#broken}`);
     const child = this.#start();
     child.stdin.write(`${JSON.stringify({ command, params, env: envOf(params) })}\n`);
     const timeoutMs = this.#config.timeoutMs ?? 120_000;
@@ -107,8 +148,11 @@ export class Fixtures {
         resolve(answer);
       };
     });
-    if (line === null)
-      throw new Error(`${command}: the fixtures command ended${this.#stderr ? `: ${this.#stderr.trim().split('\n').slice(-3).join(' · ')}` : ''}`);
+    if (line === null) {
+      const ended = `the fixtures command ended${this.#stderr ? `: ${this.#stderr.trim().split('\n').slice(-3).join(' · ')}` : ''}`;
+      if (this.#silentEnds >= 2) this.#broken = `${ended} (it ended twice without answering, so it is not started again in this run)`;
+      throw new Error(`${command}: ${ended}`);
+    }
     const answer = JSON.parse(line) as Answer;
     if (answer.ok === false) throw new Error(`${command}: ${String(answer.error ?? answer.message ?? 'ok=false')}`);
     return answer;
@@ -116,10 +160,15 @@ export class Fixtures {
 
   /** What the server says it answers, or nothing when it does not say. */
   async describe(): Promise<Description | undefined> {
-    const answer = await this.call(DESCRIBE, {}).catch(() => undefined);
-    const commands = answer?.commands;
-    if (!Array.isArray(commands) || !commands.every((c) => typeof c === 'string')) return undefined;
-    return typeof answer?.down === 'string' && answer.down ? { commands, down: answer.down } : { commands };
+    const d = readDescription(await this.call(DESCRIBE, {}).catch(() => undefined));
+    // Kept for `fixtures describe`: a server that boots a backend's framework takes longer to start than an MCP
+    // client waits, and what it answers changes only with its code.
+    if (d && !d.down)
+      try {
+        fs.mkdirSync(path.dirname(describedFile(this.#root)), { recursive: true });
+        fs.writeFileSync(describedFile(this.#root), JSON.stringify({ at: Date.now(), command: this.#config.command, description: d }));
+      } catch {}
+    return d;
   }
 
   /** Says this connection works ahead of the cases being run. Whatever the server answers, it goes on. */