lynkeus 0.2.0 → 0.4.0

package/lib/cases/templates.d.ts

@@ -4,8 +4,8 @@
  * project starts from something that runs instead of from a blank folder.
  */
 export declare const EXAMPLE_CASE = "---\nid: example\ntitle: \"A user who was given points sees them on the first screen\"\ndescription: >\n  What this proves and why it matters, in a sentence or two. A case reads top\n  to bottom: what has to exist, what the person does, what must be true after.\n---\nsetup:\n  # Anything that is not an app step is a fixture: fixtures.mjs answers it.\n  - create_user: { as: u, name: \"Ana\" }\n\nsteps:\n  - app.see: { text: \"Hello\" }\n  # `user: u` points at what `create_user` answered (cases.refs in lynkeus.config.json).\n  - give_points: { user: u, points: 25 }\n  - app.see: { text: \"25 points\", timeoutMs: 10000 }\n  - assert: { user: u, path: points, equals: 25 }\n\nexpected: |\n  The points on screen and the points the backend holds are both 25.\n";
-export declare const FORMAT = "# Cases\n\nA case is a markdown file: frontmatter that names it, then `setup`, `steps`\nand `expected`. `lynkeus case run cases/example.md` runs one; without files\nit runs every case in this folder. A step that fails stops the case, and the\nreport carries the screen, the requests and the reason.\n\n## Steps that drive the app\n\n| Step | Value | |\n|---|---|---|\n| `app.press` | target, or `{ target, within?, nth?, optional?, hold? }` | Waits for the control to be there and enabled. `optional` presses only if it is on screen. |\n| `app.type` | `{ text, target?, submit?, clear? }` | `target` is tapped first; `submit` ends with the return key. |\n| `app.swipe` | `{ direction, target?, distance? }` or `{ from, to }` | |\n| `app.wait` | route, target, ms, `{ target, scroll? }` or `{ request, status? }` | `scroll` swipes until the target is in the window. A `request` is `METHOD /path`. |\n| `app.see` | target, or `{ testId?, text?, route?, request?, event?, layer?, absent?, timeoutMs? }` | An assertion on what the app shows or did. Everything named must hold. |\n| `app.nav` | route, or `{ route, params }` | A teleport, for getting to where the case starts. |\n| `app.back` | | |\n| `app.requests` | `mark` | From here on, `request` only counts what the app asks for. |\n| `app.call` | `{ command, params?, expect?, as? }` | A command the app registered with `qa.register`. |\n| `app.run` | `{ flow, vars? }` | A lynkeus flow, from the flows folder. |\n| `app.events` / `app.event` | `clear` / `{ name, props?, absent? }` | What the app told its analytics. |\n| `app.<command>` | its arguments by name | Any other lynkeus command: `app.mock`, `app.network`, `app.appstate`, `app.deeplink`\u2026 |\n\nA target is `#testId`, `\"text\"`, an index or `x,y`.\n\nA case that runs over several inputs declares `matrix: { locale: [en, fr] }`\nin its frontmatter and runs once per combination; `{{matrix.locale}}` is that\nrun's value.\n\nOne case runs on a host and on a device. What only one of them needs \u2014 closing a\nnative screen the host never shows \u2014 is kept to it:\n\n```yaml\n  - on: device        # or headless, ios, android\n    do:\n      - app.press: \"364,84\"\n```\n\n## Steps that prepare and read the backend\n\nAny other step name is a **fixture**: lynkeus sends it to the command in\n`cases.fixtures` (lynkeus.config.json) as one JSON line and reads one back.\n\n```\n\u2192 {\"command\": \"create_user\", \"params\": {\"name\": \"Ana\"}, \"env\": {\"NAME\": \"Ana\"}}\n\u2190 {\"ok\": true, \"user_id\": \"u_1\", \"name\": \"Ana\"}\n```\n\n`as: u` keeps the answer; `{{u.user_id}}` reads it later. `assert` calls\nthe `inspect` fixture and checks one path of its answer with `equals`,\n`includes`, `gte`, `lte`, `near`, `matches`, `present` or `absent`.\n`exec: { run: \"\u2026\", as? }` runs a shell command and keeps its JSON output.\n\n## Steps of your own\n\n`cases.macros` names a step and the steps it stands for. Inside,\n`{{param.x}}` is what the case passed, and a parameter that names an alias\nis that alias.\n\n```json\n\"macros\": {\n  \"app.login\": [\n    { \"app.call\": { \"command\": \"reset\" } },\n    { \"app.deeplink\": \"myapp://dev-login?user={{param.as.user_id}}\" },\n    { \"when\": \"wait\", \"do\": { \"app.wait\": \"{{param.wait}}\" } }\n  ]\n}\n```\n\n`when` runs a step only if the case passed that parameter (`\"when\": \"wait\"`)\nor passed that value (`\"when\": \"method=phone\"`); `unless` is the opposite.\n\n`cases.interruptions` names what the app may put in the way of any step \u2014 a\nlock screen, a consent sheet \u2014 and the steps that get past it:\n`{ \"see\": \"#unlock-keypad\", \"do\": [\"app.unlock\"], \"unless\": \"keypad\" }`. It\nruns before a press, a type, a swipe or a see finds it there; a step whose own\nwords match `unless` is about it, and is left alone.\n\nCases and fixtures often live in a repository of their own: `LYNKEUS_CONFIG`\nnames a second configuration file, read over the app's, and the paths under\nits `cases` are relative to it.\n";
-export declare const FIXTURES = "#!/usr/bin/env node\n// The fixtures of this project: how a case prepares the backend and reads it.\n// lynkeus starts this once per run and talks JSON lines to it: one line in per\n// step, one line out. Replace the bodies with calls to your backend \u2014 its\n// admin API, a script, a database seed.\nimport readline from 'node:readline';\n\nconst users = new Map();\n\nconst fixtures = {\n  async create_user({ name = 'Test user' }) {\n    const user = { user_id: `u_${users.size + 1}`, name, points: 0 };\n    users.set(user.user_id, user);\n    return user;\n  },\n  async give_points({ user_id, points }) {\n    const user = users.get(user_id);\n    if (!user) throw new Error(`no user ${user_id}`);\n    user.points += Number(points);\n    return { user_id, points: user.points };\n  },\n  // What `assert` reads.\n  async inspect({ user_id }) {\n    return users.get(user_id) ?? {};\n  },\n};\n\nfor await (const line of readline.createInterface({ input: process.stdin })) {\n  if (!line.trim()) continue;\n  const { command, params } = JSON.parse(line);\n  try {\n    const fixture = fixtures[command];\n    if (!fixture) throw new Error(`no fixture ${command}`);\n    console.log(JSON.stringify({ ok: true, ...(await fixture(params ?? {})) }));\n  } catch (error) {\n    console.log(JSON.stringify({ ok: false, error: error.message }));\n  }\n}\n";
+export declare const FORMAT = "# Cases\n\nA case is a markdown file: frontmatter that names it, then `setup`, `steps`\nand `expected`. `lynkeus case run cases/example.md` runs one; without files\nit runs every case in this folder. A step that fails stops the case, and the\nreport carries the screen, the requests and the reason.\n\n## Steps that drive the app\n\n| Step | Value | |\n|---|---|---|\n| `app.press` | target, or `{ target, within?, nth?, optional?, hold?, timeoutMs? }` | Waits for the control to be there and enabled. `optional` presses only if it is on screen. |\n| `app.type` | `{ text, target?, submit?, clear?, timeoutMs? }` | `target` is tapped first, once it is there (`timeoutMs` is how long that may take); `submit` ends with the return key. |\n| `app.swipe` | `{ direction, target?, distance? }` or `{ from, to }` | |\n| `app.wait` | route, target, ms, `{ target, scroll? }` or `{ request, status? }` | `scroll` swipes until the target is in the window. A `request` is `METHOD /path`. |\n| `app.see` | target, or `{ testId?, text?, route?, request?, event?, layer?, absent?, timeoutMs? }` | An assertion on what the app shows or did. Everything named must hold. |\n| `app.nav` | route, or `{ route, params }` | A teleport, for getting to where the case starts. |\n| `app.back` | | |\n| `app.requests` | `mark` | A `request` counts only what the app asked for after the step before it began; this marks further back, until a step has looked for a request. |\n| `app.call` | `{ command, params?, expect?, as? }` | A command the app registered with `qa.register`. |\n| `app.run` | `{ flow, vars? }` | A lynkeus flow, from the flows folder. |\n| `app.events` / `app.event` | `clear` / `{ name, props?, absent? }` | What the app told its analytics. |\n| `app.<command>` | its arguments by name | Any other lynkeus command: `app.mock`, `app.network`, `app.appstate`, `app.deeplink`\u2026 |\n\nA target is `#testId`, a text, an index or `x,y`. Where a step takes `target` it also takes `testId`. A text inside quotes of its own (`'\"Next\"'`) is always a text, where `app.wait: Next` would wait for a route called `Next`.\n\nA case that runs over several inputs declares `matrix: { locale: [en, fr] }`\nin its frontmatter and runs once per combination; `{{matrix.locale}}` is that\nrun's value.\n\nOne case runs on a host and on a device. What only one of them needs \u2014 closing a\nnative screen the host never shows \u2014 is kept to it:\n\n```yaml\n  - on: device        # or headless, ios, android\n    do:\n      - app.press: \"364,84\"\n```\n\n## Steps that prepare and read the backend\n\nAny other step name is a **fixture**: lynkeus sends it to the command in\n`cases.fixtures` (lynkeus.config.json) as one JSON line and reads one back.\n\n```\n\u2192 {\"command\": \"create_user\", \"params\": {\"name\": \"Ana\"}, \"env\": {\"NAME\": \"Ana\"}}\n\u2190 {\"ok\": true, \"user_id\": \"u_1\", \"name\": \"Ana\"}\n```\n\nBefore the first case lynkeus sends `{\"command\": \"lynkeus.describe\"}`. A\nserver that answers `{\"commands\": [\"create_user\", \u2026]}` gets its cases checked\nfirst: one that names a fixture missing from the list is refused before\nanything runs. A server that answers `\"ok\": false` is not checked.\n\n`as: u` keeps the answer; `{{u.user_id}}` reads it later. `assert` calls\nthe `inspect` fixture and checks one path of its answer with `equals`,\n`includes`, `gte`, `lte`, `near`, `matches`, `present` or `absent`.\n`exec: { run: \"\u2026\", as? }` runs a shell command and keeps its JSON output.\n\n## Steps of your own\n\n`cases.macros` names a step and the steps it stands for. Inside,\n`{{param.x}}` is what the case passed, and a parameter that names an alias\nis that alias.\n\n```json\n\"macros\": {\n  \"app.login\": [\n    { \"app.call\": { \"command\": \"reset\" } },\n    { \"app.deeplink\": \"myapp://dev-login?user={{param.as.user_id}}\" },\n    { \"when\": \"wait\", \"do\": { \"app.wait\": \"{{param.wait}}\" } }\n  ]\n}\n```\n\n`when` runs a step only if the case passed that parameter (`\"when\": \"wait\"`)\nor passed that value (`\"when\": \"method=phone\"`); `unless` is the opposite.\n\n`cases.interruptions` names what the app may put in the way of any step \u2014 a\nlock screen, a consent sheet \u2014 and the steps that get past it:\n`{ \"see\": \"#unlock-keypad\", \"do\": [\"app.unlock\"], \"unless\": \"keypad\" }`. It\nruns before a press, a type, a swipe or a see finds it there; a step whose own\nwords match `unless` is about it, and is left alone.\n\nCases and fixtures often live in a repository of their own: `LYNKEUS_CONFIG`\nnames a second configuration file, read over the app's, and the paths under\nits `cases` are relative to it.\n";
+export declare const FIXTURES = "#!/usr/bin/env node\n// The fixtures of this project: how a case prepares the backend and reads it.\n// lynkeus starts this once per run and talks JSON lines to it: one line in per\n// step, one line out. Replace the bodies with calls to your backend \u2014 its\n// admin API, a script, a database seed.\nimport readline from 'node:readline';\n\nconst users = new Map();\n\nconst fixtures = {\n  async create_user({ name = 'Test user' }) {\n    const user = { user_id: `u_${users.size + 1}`, name, points: 0 };\n    users.set(user.user_id, user);\n    return user;\n  },\n  async give_points({ user_id, points }) {\n    const user = users.get(user_id);\n    if (!user) throw new Error(`no user ${user_id}`);\n    user.points += Number(points);\n    return { user_id, points: user.points };\n  },\n  // What `assert` reads.\n  async inspect({ user_id }) {\n    return users.get(user_id) ?? {};\n  },\n};\n\nfor await (const line of readline.createInterface({ input: process.stdin })) {\n  if (!line.trim()) continue;\n  const { command, params } = JSON.parse(line);\n  // lynkeus asks once what this server answers, and refuses a case that names anything else.\n  if (command === 'lynkeus.describe') {\n    console.log(JSON.stringify({ commands: Object.keys(fixtures) }));\n    continue;\n  }\n  try {\n    const fixture = fixtures[command];\n    if (!fixture) throw new Error(`no fixture ${command}`);\n    console.log(JSON.stringify({ ok: true, ...(await fixture(params ?? {})) }));\n  } catch (error) {\n    console.log(JSON.stringify({ ok: false, error: error.message }));\n  }\n}\n";
 export declare const CONFIG: {
     dir: string;
     flows: string;

package/lib/cases/templates.js

@@ -35,20 +35,20 @@ report carries the screen, the requests and the reason.
 
 | Step | Value | |
 |---|---|---|
-| \`app.press\` | target, or \`{ target, within?, nth?, optional?, hold? }\` | Waits for the control to be there and enabled. \`optional\` presses only if it is on screen. |
-| \`app.type\` | \`{ text, target?, submit?, clear? }\` | \`target\` is tapped first; \`submit\` ends with the return key. |
+| \`app.press\` | target, or \`{ target, within?, nth?, optional?, hold?, timeoutMs? }\` | Waits for the control to be there and enabled. \`optional\` presses only if it is on screen. |
+| \`app.type\` | \`{ text, target?, submit?, clear?, timeoutMs? }\` | \`target\` is tapped first, once it is there (\`timeoutMs\` is how long that may take); \`submit\` ends with the return key. |
 | \`app.swipe\` | \`{ direction, target?, distance? }\` or \`{ from, to }\` | |
 | \`app.wait\` | route, target, ms, \`{ target, scroll? }\` or \`{ request, status? }\` | \`scroll\` swipes until the target is in the window. A \`request\` is \`METHOD /path\`. |
 | \`app.see\` | target, or \`{ testId?, text?, route?, request?, event?, layer?, absent?, timeoutMs? }\` | An assertion on what the app shows or did. Everything named must hold. |
 | \`app.nav\` | route, or \`{ route, params }\` | A teleport, for getting to where the case starts. |
 | \`app.back\` | | |
-| \`app.requests\` | \`mark\` | From here on, \`request\` only counts what the app asks for. |
+| \`app.requests\` | \`mark\` | A \`request\` counts only what the app asked for after the step before it began; this marks further back, until a step has looked for a request. |
 | \`app.call\` | \`{ command, params?, expect?, as? }\` | A command the app registered with \`qa.register\`. |
 | \`app.run\` | \`{ flow, vars? }\` | A lynkeus flow, from the flows folder. |
 | \`app.events\` / \`app.event\` | \`clear\` / \`{ name, props?, absent? }\` | What the app told its analytics. |
 | \`app.<command>\` | its arguments by name | Any other lynkeus command: \`app.mock\`, \`app.network\`, \`app.appstate\`, \`app.deeplink\`… |
 
-A target is \`#testId\`, \`"text"\`, an index or \`x,y\`.
+A target is \`#testId\`, a text, an index or \`x,y\`. Where a step takes \`target\` it also takes \`testId\`. A text inside quotes of its own (\`'"Next"'\`) is always a text, where \`app.wait: Next\` would wait for a route called \`Next\`.
 
 A case that runs over several inputs declares \`matrix: { locale: [en, fr] }\`
 in its frontmatter and runs once per combination; \`{{matrix.locale}}\` is that
@@ -73,6 +73,11 @@ Any other step name is a **fixture**: lynkeus sends it to the command in
 ← {"ok": true, "user_id": "u_1", "name": "Ana"}
 \`\`\`
 
+Before the first case lynkeus sends \`{"command": "lynkeus.describe"}\`. A
+server that answers \`{"commands": ["create_user", …]}\` gets its cases checked
+first: one that names a fixture missing from the list is refused before
+anything runs. A server that answers \`"ok": false\` is not checked.
+
 \`as: u\` keeps the answer; \`{{u.user_id}}\` reads it later. \`assert\` calls
 the \`inspect\` fixture and checks one path of its answer with \`equals\`,
 \`includes\`, \`gte\`, \`lte\`, \`near\`, \`matches\`, \`present\` or \`absent\`.
@@ -137,6 +142,11 @@ const fixtures = {
 for await (const line of readline.createInterface({ input: process.stdin })) {
   if (!line.trim()) continue;
   const { command, params } = JSON.parse(line);
+  // lynkeus asks once what this server answers, and refuses a case that names anything else.
+  if (command === 'lynkeus.describe') {
+    console.log(JSON.stringify({ commands: Object.keys(fixtures) }));
+    continue;
+  }
   try {
     const fixture = fixtures[command];
     if (!fixture) throw new Error(\`no fixture \${command}\`);

package/lib/cases/traces.d.ts

@@ -0,0 +1,58 @@
+/** A span as a backend exported it over OTLP, reduced to what a report shows. */
+export type Span = {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startNs: bigint;
+    endNs: bigint;
+    attributes: Record<string, string | number | boolean>;
+    error?: string;
+    service?: string;
+};
+/** What a step did on the backend, as the run file keeps it: one line per span, children indented by depth. */
+export type BackendSpan = {
+    name: string;
+    /** server, client, internal, producer or consumer */
+    kind: string;
+    /** ms after the step began */
+    at: number;
+    ms: number;
+    depth: number;
+    service?: string;
+    error?: string;
+    attributes?: Record<string, string | number | boolean>;
+};
+export declare const newTraceId: () => string;
+export declare const newSpanId: () => string;
+export declare const traceparent: (traceId: string, spanId: string) => string;
+export declare const decodeProtobuf: (buf: Uint8Array) => Span[];
+export declare const decodeJson: (body: unknown) => Span[];
+/**
+ * Listens for OTLP traces while a run goes on: a backend with OTEL_EXPORTER_OTLP_ENDPOINT pointed here sends
+ * what each request did, and the steps that sent those requests (their ids travel in `traceparent`) get it.
+ */
+export declare class TraceSink {
+    readonly port: number;
+    private readonly spans;
+    private server?;
+    private readonly arrived;
+    constructor(port: number);
+    start(): Promise<void>;
+    add(spans: Span[]): void;
+    /**
+     * Backends export in batches, a moment after the requests they served: wait until the trace has had
+     * nothing new for `quietMs`, or `maxMs` has passed. Other traces (a scheduler polling) do not count.
+     */
+    settle(traceId: string, quietMs?: number, maxMs?: number): Promise<void>;
+    /**
+     * The spans of one trace, each under the step whose id its chain of parents reaches: `steps` maps a step's
+     * span id to its index and the epoch ms it began. Spans of the trace that reach no step are left out.
+     */
+    take(traceId: string, steps: Map<string, {
+        index: number;
+        startedMs: number;
+    }>): Map<number, BackendSpan[]>;
+    close(): void;
+}

package/lib/cases/traces.js

@@ -0,0 +1,250 @@
+import { randomBytes } from 'node:crypto';
+import http from 'node:http';
+const KINDS = ['unspecified', 'internal', 'server', 'client', 'producer', 'consumer'];
+export const newTraceId = () => randomBytes(16).toString('hex');
+export const newSpanId = () => randomBytes(8).toString('hex');
+export const traceparent = (traceId, spanId) => `00-${traceId}-${spanId}-01`;
+const fields = (buf) => {
+    const out = [];
+    let i = 0;
+    const varint = () => {
+        let result = 0n;
+        let shift = 0n;
+        for (;;) {
+            const b = buf[i++];
+            result |= BigInt(b & 0x7f) << shift;
+            if (!(b & 0x80))
+                return result;
+            shift += 7n;
+        }
+    };
+    while (i < buf.length) {
+        const tag = Number(varint());
+        const no = tag >> 3;
+        const wire = tag & 7;
+        if (wire === 0)
+            out.push({ no, wire, value: varint() });
+        else if (wire === 1) {
+            out.push({ no, wire, value: buf.slice(i, i + 8) });
+            i += 8;
+        }
+        else if (wire === 2) {
+            const length = Number(varint());
+            out.push({ no, wire, value: buf.subarray(i, i + length) });
+            i += length;
+        }
+        else if (wire === 5) {
+            out.push({ no, wire, value: buf.slice(i, i + 4) });
+            i += 4;
+        }
+        else
+            throw new Error(`unknown protobuf wire type ${wire}`);
+    }
+    return out;
+};
+const text = (v) => (v instanceof Uint8Array ? Buffer.from(v).toString('utf8') : '');
+const hex = (v) => (v instanceof Uint8Array ? Buffer.from(v).toString('hex') : '');
+const fixed64 = (v) => (v instanceof Uint8Array ? Buffer.from(v).readBigUInt64LE(0) : 0n);
+const anyValue = (buf) => {
+    for (const f of fields(buf)) {
+        if (f.no === 1)
+            return text(f.value);
+        if (f.no === 2)
+            return f.value === 1n;
+        if (f.no === 3)
+            return Number(BigInt.asIntN(64, f.value));
+        if (f.no === 4 && f.value instanceof Uint8Array)
+            return Buffer.from(f.value).readDoubleLE(0);
+    }
+    return '';
+};
+const keyValues = (list, no) => {
+    const out = {};
+    for (const f of list) {
+        if (f.no !== no || !(f.value instanceof Uint8Array))
+            continue;
+        let key = '';
+        let value = '';
+        for (const kv of fields(f.value)) {
+            if (kv.no === 1)
+                key = text(kv.value);
+            if (kv.no === 2 && kv.value instanceof Uint8Array)
+                value = anyValue(kv.value);
+        }
+        if (key)
+            out[key] = value;
+    }
+    return out;
+};
+export const decodeProtobuf = (buf) => {
+    const spans = [];
+    for (const rs of fields(buf)) {
+        if (rs.no !== 1 || !(rs.value instanceof Uint8Array))
+            continue;
+        const parts = fields(rs.value);
+        const resource = parts.find((p) => p.no === 1);
+        const service = resource?.value instanceof Uint8Array ? keyValues(fields(resource.value), 1)['service.name'] : undefined;
+        for (const ss of parts) {
+            if (ss.no !== 2 || !(ss.value instanceof Uint8Array))
+                continue;
+            for (const sp of fields(ss.value)) {
+                if (sp.no !== 2 || !(sp.value instanceof Uint8Array))
+                    continue;
+                const s = fields(sp.value);
+                const get = (no) => s.find((f) => f.no === no)?.value;
+                const status = get(15);
+                let error;
+                if (status instanceof Uint8Array) {
+                    const st = fields(status);
+                    const code = st.find((f) => f.no === 3)?.value;
+                    if (code === 2n)
+                        error = text(st.find((f) => f.no === 2)?.value ?? new Uint8Array()) || 'error';
+                }
+                const parent = get(4);
+                spans.push({
+                    traceId: hex(get(1) ?? new Uint8Array()),
+                    spanId: hex(get(2) ?? new Uint8Array()),
+                    parentSpanId: parent instanceof Uint8Array && parent.length ? hex(parent) : undefined,
+                    name: text(get(5) ?? new Uint8Array()),
+                    kind: Number(get(6) ?? 0n),
+                    startNs: fixed64(get(7) ?? new Uint8Array(8)),
+                    endNs: fixed64(get(8) ?? new Uint8Array(8)),
+                    attributes: keyValues(s, 9),
+                    ...(error ? { error } : {}),
+                    ...(typeof service === 'string' ? { service } : {}),
+                });
+            }
+        }
+    }
+    return spans;
+};
+const jsonAttrs = (list) => Object.fromEntries((list ?? []).map(({ key, value }) => [
+    key,
+    value.stringValue ?? value.boolValue ?? (value.intValue !== undefined ? Number(value.intValue) : (value.doubleValue ?? '')),
+]));
+export const decodeJson = (body) => {
+    const spans = [];
+    const request = body;
+    for (const rs of request.resourceSpans ?? []) {
+        const service = jsonAttrs(rs.resource?.attributes)['service.name'];
+        for (const ss of rs.scopeSpans ?? [])
+            for (const s of ss.spans ?? [])
+                spans.push({
+                    traceId: s.traceId.toLowerCase(),
+                    spanId: s.spanId.toLowerCase(),
+                    parentSpanId: s.parentSpanId ? s.parentSpanId.toLowerCase() : undefined,
+                    name: s.name,
+                    kind: s.kind ?? 0,
+                    startNs: BigInt(s.startTimeUnixNano),
+                    endNs: BigInt(s.endTimeUnixNano),
+                    attributes: jsonAttrs(s.attributes),
+                    ...(s.status?.code === 2 ? { error: s.status.message || 'error' } : {}),
+                    ...(typeof service === 'string' ? { service } : {}),
+                });
+    }
+    return spans;
+};
+// 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)/;
+/**
+ * Listens for OTLP traces while a run goes on: a backend with OTEL_EXPORTER_OTLP_ENDPOINT pointed here sends
+ * what each request did, and the steps that sent those requests (their ids travel in `traceparent`) get it.
+ */
+export class TraceSink {
+    port;
+    spans = new Map();
+    server;
+    arrived = new Map();
+    constructor(port) {
+        this.port = port;
+    }
+    async start() {
+        this.server = http.createServer((req, res) => {
+            if (req.method !== 'POST' || !req.url?.startsWith('/v1/traces')) {
+                res.writeHead(404).end();
+                return;
+            }
+            const chunks = [];
+            req.on('data', (c) => chunks.push(c));
+            req.on('end', () => {
+                try {
+                    const body = Buffer.concat(chunks);
+                    const spans = (req.headers['content-type'] ?? '').includes('json') ? decodeJson(JSON.parse(body.toString('utf8'))) : decodeProtobuf(body);
+                    this.add(spans);
+                    res.writeHead(200, { 'content-type': req.headers['content-type'] ?? 'application/x-protobuf' }).end();
+                }
+                catch (error) {
+                    res.writeHead(400).end(String(error));
+                }
+            });
+        });
+        await new Promise((resolve, reject) => {
+            this.server.once('error', reject);
+            this.server.listen(this.port, '127.0.0.1', () => resolve());
+        });
+    }
+    add(spans) {
+        for (const span of spans) {
+            this.arrived.set(span.traceId, Date.now());
+            const list = this.spans.get(span.traceId) ?? [];
+            list.push(span);
+            this.spans.set(span.traceId, list);
+        }
+    }
+    /**
+     * Backends export in batches, a moment after the requests they served: wait until the trace has had
+     * nothing new for `quietMs`, or `maxMs` has passed. Other traces (a scheduler polling) do not count.
+     */
+    async settle(traceId, quietMs = 300, maxMs = 3000) {
+        const started = Date.now();
+        while (Date.now() - started < maxMs) {
+            if (Date.now() - Math.max(this.arrived.get(traceId) ?? 0, started) >= quietMs)
+                return;
+            await new Promise((r) => setTimeout(r, 50));
+        }
+    }
+    /**
+     * The spans of one trace, each under the step whose id its chain of parents reaches: `steps` maps a step's
+     * span id to its index and the epoch ms it began. Spans of the trace that reach no step are left out.
+     */
+    take(traceId, steps) {
+        const spans = this.spans.get(traceId) ?? [];
+        this.spans.delete(traceId);
+        this.arrived.delete(traceId);
+        const byId = new Map(spans.map((s) => [s.spanId, s]));
+        const out = new Map();
+        const place = (span) => {
+            let depth = 0;
+            for (let at = span; at; depth++) {
+                const step = at.parentSpanId ? steps.get(at.parentSpanId) : undefined;
+                if (step)
+                    return { step: step.index, depth };
+                at = at.parentSpanId ? byId.get(at.parentSpanId) : undefined;
+            }
+            return undefined;
+        };
+        for (const span of [...spans].sort((a, b) => (a.startNs < b.startNs ? -1 : 1))) {
+            const where = place(span);
+            if (!where)
+                continue;
+            const startedMs = [...steps.values()].find((s) => s.index === where.step).startedMs;
+            const attributes = Object.fromEntries(Object.entries(span.attributes).filter(([k]) => KEEP.test(k)));
+            const list = out.get(where.step) ?? [];
+            list.push({
+                name: span.name,
+                kind: KINDS[span.kind] ?? 'internal',
+                at: Math.max(0, Math.round(Number(span.startNs / 1000000n) - startedMs)),
+                ms: Math.round(Number(span.endNs - span.startNs) / 1e5) / 10,
+                depth: where.depth,
+                ...(span.service ? { service: span.service } : {}),
+                ...(span.error ? { error: span.error } : {}),
+                ...(Object.keys(attributes).length ? { attributes } : {}),
+            });
+            out.set(where.step, list);
+        }
+        return out;
+    }
+    close() {
+        this.server?.close();
+    }
+}

package/lib/cli.js

@@ -8,13 +8,15 @@ 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 { reportCommands } from './commands/report.js';
 import { runsCommands } from './commands/runs.js';
-import { graphFile, loadConfig, loadGraph, portFromEnv } from './config.js';
-import { HEADLESS_HOST, pickAgentDevice } from './device/devices.js';
+import { graphFile, loadConfig, loadGraph, portFromEnv, readToken } from './config.js';
+import { agentMismatch } from './device/agentVersion.js';
+import { HEADLESS_HOST, pickAgentDevice, pickAndroidDevice } from './device/devices.js';
 import { Device } from './device/driver.js';
 import { commands, find, helpFor, inSession, referenceMarkdown, register, resolve, usage } from './registry.js';
 import { execute } from './runtime.js';
-register([...driveCommands, ...osCommands, ...mapCommands, ...runsCommands, ...caseCommands, ...headlessCommands]);
+register([...driveCommands, ...osCommands, ...mapCommands, ...runsCommands, ...caseCommands, ...reportCommands, ...headlessCommands]);
 /** The global flags, read leniently from the whole argv before any command parses its own. */
 const globals = (argv) => {
     const out = {};
@@ -35,7 +37,10 @@ const globals = (argv) => {
     }
     return out;
 };
-const contextFor = (argv, attached = false) => {
+// Once per process: a suite reattaches for every case.
+let mismatchTold = false;
+// `ownHost`: the port belongs to a host this run started for a case; whatever dials in is the device.
+const contextFor = (argv, attached = false, port, ownHost = false) => {
     const g = globals(argv);
     const root = path.resolve(g.root ?? process.cwd());
     const config = loadConfig(root);
@@ -46,8 +51,18 @@ const contextFor = (argv, attached = false) => {
         const appId = g.app ?? process.env.LYNKEUS_APP_ID ?? config.app;
         const started = performance.now();
         const attachedIn = (d) => err(`attached in ${Math.round(performance.now() - started)}ms (${d.info.name})`);
-        const server = new AgentServer({ token: process.env.LYNKEUS_TOKEN, port: portFromEnv(config) });
-        const picking = pickAgentDevice(g.device ?? process.env.LYNKEUS_DEVICE ?? config.device);
+        const server = new AgentServer({ token: readToken(root), port: port ?? portFromEnv(config) });
+        server.on('hello', (hello) => {
+            const told = mismatchTold ? undefined : agentMismatch(hello);
+            if (!told)
+                return;
+            mismatchTold = true;
+            err(told);
+        });
+        // A host started for the case is the device: looking for the configured simulator would only replace a
+        // late app's error with one about a simulator nobody asked for.
+        const wantedDevice = g.device ?? process.env.LYNKEUS_DEVICE ?? config.device;
+        const picking = ownHost ? Promise.resolve(HEADLESS_HOST) : pickAgentDevice(wantedDevice);
         if (g.launch && appId) {
             const d = new Device(await picking, { appId, server });
             await d.launchApp(appId, { fresh: true });
@@ -70,7 +85,9 @@ const contextFor = (argv, attached = false) => {
             name: headless ? HEADLESS_HOST.name : String(hello.app?.name ?? hello.platform),
             platform: hello.platform === 'android' ? 'android' : 'ios',
         };
-        const d = new Device(info, { appId: appId ?? null, server, resolving: headless ? undefined : picking });
+        // The app says which platform it runs on; only then is it known whether simctl or adb names its device.
+        const resolving = headless || ownHost ? undefined : info.platform === 'android' ? pickAndroidDevice(wantedDevice) : picking;
+        const d = new Device(info, { appId: appId ?? null, server, resolving });
         attachedIn(d);
         return d;
     };
@@ -89,6 +106,10 @@ const contextFor = (argv, attached = false) => {
             device ??= connect();
             return device;
         },
+        forPort: (other) => {
+            const scoped = contextFor(argv, attached, other, true);
+            return { base: scoped.ctx, stop: scoped.stop };
+        },
     };
     return {
         ctx,