tapline-host 1.1.0 → 1.3.0

package/dist/tools.js

@@ -1,21 +1,24 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { basename, dirname, join } from "node:path";
 import { toBuffer as qrPng } from "qrcode";
 import { z } from "zod";
 import { annotateScreenshot } from "./annotate.js";
 import { agentKind, captionFor, personKind, reasonOf } from "./captions.js";
-import { composeFilmstrip, diffImages } from "./images.js";
-import { alertNotes, describeElement, formatChanges, formatElement, formatLogs, formatOffScreenAfterList, formatTree } from "./format.js";
+import { composeFilmstrip, diffImages, imageSize } from "./images.js";
+import { alertNotes, describeElement, filterLogs, formatChanges, formatElement, formatLogAnswer, formatLogs, formatOffScreenAfterList, formatTree } from "./format.js";
 import { formatInspect, inspectResultSchema } from "./inspect.js";
 import { AUDIT_TYPES, auditResultSchema, auditTitle, formatAudit } from "./audit.js";
+import { NO_CRASH_TEXT, crashNote, disconnectNote, formatCrash } from "./crash.js";
 import { ActionLog, loggedTarget } from "./actionlog.js";
 import { Confirmations } from "./confirm.js";
 import { DEFAULT_POLICY, elementKey, listsFor, matchWord } from "./policy.js";
 import { readScript, refStep, scriptSteps } from "./script.js";
-import { EXPECT_TIMEOUT_S, MAX_STEPS, RUN_TIMEOUT_MS, RUN_TOOLS, describeRunStep, expectFailure, parseError, stepNotes, stepSchema, } from "./run.js";
+import { badUnderKeys, checkUnder, formatPerfLines, perfFirstLine, perfResultSchema } from "./perf.js";
+import { EXPECT_TIMEOUT_S, MAX_STEPS, RUN_TIMEOUT_MS, RUN_TOOLS, UNDER_KEYS, describeRunStep, expectFailure, parseError, stepNotes, stepSchema, } from "./run.js";
 import { PAIR_CODE_TTL_MS, forgetLink, pairingLink } from "./pairing.js";
 import { elementSchema, logEntrySchema, screenshotResultSchema, treeResultSchema, } from "./protocol.js";
-import { TaplineError } from "./server.js";
+import { TaplineError, identityOf } from "./server.js";
 // ---- input schemas ----------------------------------------------------------
 export const targetSchema = z
     .object({
@@ -47,6 +50,15 @@ export const targetSchema = z
         ctx.addIssue({ code: "custom", message: "index works with id, label or text." });
     }
 });
+const rectSchema = z
+    .object({
+    x: z.number().describe("Points"),
+    y: z.number().describe("Points"),
+    width: z.number().positive().describe("Points"),
+    height: z.number().positive().describe("Points"),
+})
+    .strict();
+const ignoreListSchema = z.array(z.union([rectSchema, targetSchema]));
 const targetField = targetSchema.describe("Exactly one of ref, id, label, text or x and y");
 const lookField = z
     .boolean()
@@ -175,6 +187,16 @@ export const toolShapes = {
             .max(1320)
             .optional()
             .describe("Screenshot width in pixels, 160 to 1320 (default 600); keep it the same for a name"),
+        threshold: z
+            .number()
+            .min(0)
+            .max(100)
+            .optional()
+            .describe("The share of the screen, in percent, 0 to 100 (default 0.5), that may change and still match"),
+        ignore: z
+            .array(z.union([rectSchema, targetSchema]))
+            .optional()
+            .describe("Painted out on both pictures before comparing (a clock, an avatar): targets {id}, {label}, {text}, {ref}, or a rect {x, y, width, height} in points"),
     },
     filmstrip: {
         frames: z.number().int().min(2).max(9).optional().describe("How many frames (default 6)"),
@@ -211,15 +233,29 @@ export const toolShapes = {
     },
     logs: {
         since: z.number().optional().describe("Only lines after this timestamp (epoch milliseconds)"),
+        level: z.enum(["error", "warning", "info"]).optional().describe("That level and above (default info: everything)"),
+        grep: z.string().optional().describe("Only lines containing this text (case-insensitive)"),
+        limit: z.number().int().min(1).max(500).optional().describe("At most this many lines, the newest (1 to 500, default 100)"),
+    },
+    crash: {
+        all: z.boolean().optional().describe("The last 5 crashes instead of only the newest"),
     },
     reload: { look: lookField },
+    performance: {
+        launch: z
+            .boolean()
+            .optional()
+            .describe("true: reload the app's JavaScript and time it to the first settled screen (development builds only; not a cold start)"),
+        seconds: z.number().min(0.5).max(30).optional().describe("Measure for this long, 0.5 to 30 seconds (default 3)"),
+        tap: targetField.optional().describe("Tap this first, then measure what it sets off"),
+    },
     wait: { seconds: z.number().min(0.1).max(30).describe("How long to wait, 0.1 to 30 seconds"), screenshot: screenshotField },
     run: {
         steps: z
             .array(stepSchema)
             .min(1)
             .max(MAX_STEPS)
-            .describe('The steps, in order: each is a tool call as an object, {"tool": "tap", "target": {...}, "expect": {...}}. Tools: tap, long_press, type_text, scroll, toggle, back, swipe, open_url, wait, wait_for, app_command. expect (optional): one of text, id or label, with gone, value and timeout (seconds, default 2).'),
+            .describe('The steps, in order: each is a tool call as an object, {"tool": "tap", "target": {...}, "expect": {...}}. Tools: tap, long_press, type_text, scroll, toggle, back, swipe, open_url, wait, wait_for, app_command, compare_screen (checks, never saves), performance. expect (optional): one of text, id or label, with gone, value and timeout (seconds, default 2); or matches (a reference name, alone or with one of them) with threshold; on a performance step, under: limits such as {"launch_s": 2, "drops": 0, "fps_min": 50, "busy_ms": 200, "js_heap_mb": 80}.'),
         trace: z.boolean().optional().describe("Also list each step that ran, one line each"),
         dry_run: z
             .boolean()
@@ -229,6 +265,78 @@ export const toolShapes = {
         screenshot: screenshotField,
     },
 };
+// ---- compare_screen ---------------------------------------------------------
+const DEFAULT_MATCH_THRESHOLD = 0.5;
+const MAX_REGION_LINES = 8;
+function describeIgnore(item) {
+    if (item.id !== undefined)
+        return `id=${item.id}`;
+    if (item.label !== undefined)
+        return `label ${JSON.stringify(item.label)}`;
+    if (item.text !== undefined)
+        return JSON.stringify(item.text);
+    if (item.ref !== undefined)
+        return item.ref;
+    return `${String(item.x)},${String(item.y)}`;
+}
+/** The pixel rectangles to paint out for `ignore`, from a fresh element list; targets not on the screen give a note. */
+/**
+ * An element as a {label} target matches it: its accessibility label, else its text, as the app's SDK matches
+ * (labelOf in the SDK). The ignore masks, recorded indexes and expectations use the same rule as the targets.
+ */
+function labelOfElement(e) {
+    return e.label ?? e.text ?? "";
+}
+function ignoreRects(ignore, elements, scale, size) {
+    const rects = [];
+    const notes = [];
+    const add = (x, y, width, height) => {
+        const x0 = Math.max(0, Math.floor(x * scale));
+        const y0 = Math.max(0, Math.floor(y * scale));
+        const x1 = Math.min(size.width, Math.ceil((x + width) * scale));
+        const y1 = Math.min(size.height, Math.ceil((y + height) * scale));
+        if (x1 > x0 && y1 > y0)
+            rects.push({ x: x0, y: y0, width: x1 - x0, height: y1 - y0 });
+    };
+    for (const item of ignore) {
+        if ("width" in item) {
+            add(item.x, item.y, item.width, item.height);
+            continue;
+        }
+        let found = [];
+        if (item.ref !== undefined)
+            found = elements.filter((e) => e.ref === item.ref);
+        else if (item.id !== undefined)
+            found = elements.filter((e) => e.testID === item.id);
+        else if (item.label !== undefined) {
+            const wanted = item.label.toLowerCase();
+            found = elements.filter((e) => labelOfElement(e).toLowerCase() === wanted);
+        }
+        else if (item.text !== undefined) {
+            const wanted = item.text.toLowerCase();
+            found = elements.filter((e) => (e.text ?? "").toLowerCase() === wanted);
+            if (found.length === 0)
+                found = elements.filter((e) => wanted !== "" && (e.text ?? "").toLowerCase().includes(wanted));
+        }
+        else if (item.x !== undefined && item.y !== undefined) {
+            const px = item.x;
+            const py = item.y;
+            found = elements
+                .filter((e) => e.frame && px >= e.frame.x && px <= e.frame.x + e.frame.width && py >= e.frame.y && py <= e.frame.y + e.frame.height)
+                .sort((a, b) => (a.frame?.width ?? 0) * (a.frame?.height ?? 0) - (b.frame?.width ?? 0) * (b.frame?.height ?? 0))
+                .slice(0, 1);
+        }
+        found = found.filter((e) => e.frame !== undefined);
+        if (item.index !== undefined)
+            found = found.slice(item.index, item.index + 1);
+        if (found.length === 0)
+            notes.push(`ignore ${describeIgnore(item)} isn't on the screen; skipped.`);
+        for (const e of found)
+            if (e.frame)
+                add(e.frame.x, e.frame.y, e.frame.width, e.frame.height);
+    }
+    return { rects, notes };
+}
 /**
  * Under this many points from its first point, a pointer path is a tap or a hold, not a drag.
  * Tapwright uses the same number, and the viewer page's pending ring (TAP_SLOP in viewer.html)
@@ -238,6 +346,8 @@ const TAP_SLOP = 10;
 /** Held at least this long, a tap is a long press. */
 const LONG_PRESS_MS = 500;
 const SCRIPT_NAME = /^[A-Za-z0-9][\w.-]{0,60}$/;
+/** The answer to a reference name that isn't one: no slashes, so no way out of the references folder. */
+const BAD_REFERENCE_NAME = "Error bad_params: name the reference with letters, digits, '.', '_' and '-'.";
 const scriptSchema = z.object({
     version: z.literal(1),
     name: z.string(),
@@ -407,6 +517,18 @@ function toWireTarget(target) {
         return withIndex({ text: target.text });
     return { x: target.x ?? 0, y: target.y ?? 0 };
 }
+/** A target as the agent wrote it, in words: `id=save`, `"Save"`, `e3`, `120,300`. */
+function targetWords(target) {
+    if (target.id !== undefined)
+        return `id=${target.id}`;
+    if (target.text !== undefined)
+        return JSON.stringify(target.text);
+    if (target.label !== undefined)
+        return JSON.stringify(target.label);
+    if (target.ref !== undefined)
+        return target.ref;
+    return `${target.x ?? 0},${target.y ?? 0}`;
+}
 function candidateLines(details) {
     const lines = [];
     const bareRefs = [];
@@ -529,6 +651,12 @@ function candidatesFor(target, elements) {
     return picked !== undefined ? [picked] : found;
 }
 // ---- tool handlers ----------------------------------------------------------
+/** Every tool whose answer can end with a crash note (all but `crash`, which tells it in full). */
+const CRASH_NOTED_TOOLS = [
+    "apps", "openApp", "pair", "look", "run", "inspect", "audit", "checkLayout", "viewer", "compareScreen", "filmstrip",
+    "record", "replay", "tap", "longPress", "typeText", "scroll", "toggle", "appCommand", "waitFor", "swipe", "back",
+    "openUrl", "logs", "reload", "performance", "wait",
+];
 /** The tool handlers behind the MCP server. They only talk to a TaplineHost, so they are easy to test. */
 export class TaplineTools {
     host;
@@ -561,10 +689,27 @@ export class TaplineTools {
     personNotePending = false;
     recording = null;
     replaying = false;
+    /**
+     * While a script replays (AGENT-TOOLS 1.9 §14.3): the references folder next to it (looked in first), where a
+     * failed check puts its red picture, and whether the checks save instead of compare (`--update-references`).
+     */
+    replayContext = null;
+    /** Where the latest failed check of the running batch saved its picture. */
+    diffSaved = null;
+    /** What the last `performance` call measured, for the `under` limits of a `run` step. */
+    lastPerf;
+    /** The elements the latest comparison painted its ignore list from: a recording saves its mask from the same list. */
+    lastMaskElements;
     /** The screen size in points from the latest list or overlay, for the live viewer's 0..1 positions. */
     lastScreen;
     shotCount = 0;
     pairWrites = 0;
+    /** Per app (by identity): crash events up to this one have been told to the agent. */
+    notedCrashSeqs = new Map();
+    /** Crash events up to this one happened before this agent's session: an app with no entry above starts here. */
+    crashBaseline;
+    /** Set inside a tool call (and everything it awaits), so a call within a call (`run`'s steps) adds no notes. */
+    noteScope = new AsyncLocalStorage();
     constructor(host, options) {
         this.host = host;
         this.options = options;
@@ -580,6 +725,70 @@ export class TaplineTools {
             if (this.host.current()?.id === session.id)
                 this.markPersonUsedApp();
         });
+        // Crashes before this agent's session began are not its news.
+        this.crashBaseline = host.crashMark();
+        for (const name of CRASH_NOTED_TOOLS) {
+            const original = Reflect.get(this, name);
+            if (typeof original !== "function")
+                continue;
+            const method = original;
+            Reflect.set(this, name, (...args) => this.noting(() => method.apply(this, args)));
+        }
+    }
+    /**
+     * Runs a tool call and ends its answer with a note when the app stopped (AGENT-TOOLS 15.2): during this
+     * call, or earlier, with its time, once. Calls inside a call (`run`'s steps) add nothing of their own.
+     */
+    noting(run) {
+        // Nesting belongs to the call and what it awaits (not to this object), so calls running side by side each
+        // count as outermost, and only a step inside a call is skipped.
+        if (this.noteScope.getStore() === true)
+            return run();
+        const mark = this.host.crashMark();
+        const startedWith = this.host.current();
+        return this.noteScope.run(true, () => {
+            const result = run();
+            if (result instanceof Promise)
+                return result.then((answer) => this.withCrashNotes(answer, mark, startedWith));
+            return this.withCrashNotes(result, mark, startedWith);
+        });
+    }
+    /** What was told about this app's crashes so far: the crash events up to this number. */
+    notedSeqOf(app) {
+        return this.notedCrashSeqs.get(identityOf(app)) ?? this.crashBaseline;
+    }
+    /**
+     * The notes for the app this call used (the one at its start, the one at its end, or, with none connected, the
+     * one that dropped last). Other apps' events stay pending until that app is the one being driven.
+     */
+    withCrashNotes(answer, mark, startedWith) {
+        const apps = new Map();
+        const current = this.host.current();
+        // A call that started on an app answers for that app only: another app that became current meanwhile (the first
+        // one dropped) keeps its crashes pending until it is the one being driven (Codex review of 1.3.0).
+        const endedWith = startedWith === undefined ? (current ?? this.host.lastDisconnect()?.session) : current !== undefined && identityOf(current) === identityOf(startedWith) ? current : undefined;
+        for (const app of [startedWith, endedWith])
+            if (app !== undefined)
+                apps.set(identityOf(app), app);
+        const events = [...apps.values()]
+            .flatMap((app) => this.host.crashEventsAfter(this.notedSeqOf(app), app))
+            .sort((a, b) => a.seq - b.seq);
+        if (events.length === 0)
+            return answer;
+        const told = this.host.crashMark();
+        for (const key of apps.keys())
+            this.notedCrashSeqs.set(key, told);
+        let noted = answer;
+        for (const event of events) {
+            // During this call: no time. A crash the phone had kept and sent later says when it happened.
+            const during = event.seq > mark;
+            // A crash kept by an earlier run of the app (this host had not started yet) says so, with its date.
+            const earlier = event.kind === "crash" && event.crash.source === "saved" && event.crash.ts < this.host.startedAt;
+            noted = appendNote(noted, event.kind === "crash"
+                ? crashNote(event.crash, !(during && event.crash.source === "live"), earlier)
+                : disconnectNote(during ? undefined : event.at));
+        }
+        return noted;
     }
     /** A person used the app: the next answer says so once, and `{ref}` targets are stale until the next full list. */
     markPersonUsedApp() {
@@ -796,11 +1005,55 @@ export class TaplineTools {
             }
             const shape = toolShapes[step.tool];
             const { tool: _tool, expect: _expect, route: _route, ...params } = step;
+            if (step.tool === "compare_screen" && params.update !== undefined) {
+                return fail(`Error bad_params: step ${i + 1}: update can't be used in run (a step never saves a reference)`);
+            }
+            const under = step.expect?.under;
+            if (under !== undefined) {
+                if (step.tool !== "performance") {
+                    return fail(`Error bad_params: step ${i + 1} (${describeRunStep(step)}): under goes only on a performance step.`);
+                }
+                const unknown = badUnderKeys(under);
+                if (unknown.length > 0) {
+                    return fail(`Error bad_params: step ${i + 1} (${describeRunStep(step)}): under has ${unknown.map((key) => JSON.stringify(key)).join(", ")}; the limits are ${UNDER_KEYS.join(", ")}.`);
+                }
+                if (Object.keys(under).length === 0) {
+                    return fail(`Error bad_params: step ${i + 1} (${describeRunStep(step)}): under is empty; give at least one limit (${UNDER_KEYS.join(", ")}).`);
+                }
+                const negative = Object.entries(under).filter(([, limit]) => limit < 0 || !Number.isFinite(limit));
+                if (negative.length > 0) {
+                    return fail(`Error bad_params: step ${i + 1} (${describeRunStep(step)}): under limits can't be negative (${negative.map(([key]) => key).join(", ")}).`);
+                }
+                if (under["launch_s"] !== undefined && step.launch !== true) {
+                    return fail(`Error bad_params: step ${i + 1} (${describeRunStep(step)}): launch_s goes only on a launch step (performance with launch: true).`);
+                }
+            }
+            // A step's own look and screenshot are ignored (§9.1).
+            if (step.tool === "performance") {
+                delete params["look"];
+                delete params["screenshot"];
+                // Checked before any step runs (and in a dry run), not when this step's turn comes.
+                if (params["launch"] === true && params["tap"] !== undefined) {
+                    return fail(`Error bad_params: step ${i + 1} (${describeRunStep(step)}): launch reloads the app and tap taps in it; give one of them.`);
+                }
+            }
             const parsed = z.object(shape).strict().safeParse(params);
             if (!parsed.success) {
                 return fail(`Error bad_params: step ${i + 1} (${describeRunStep(step)}): ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "params"}: ${issue.message}`).join("; ")}`);
             }
+            // Every reference name is checked before any step runs: a name with a path in it never reaches the disk.
+            const names = [step.tool === "compare_screen" ? params.name : undefined, step.expect?.matches];
+            if (names.some((name) => typeof name === "string" && !SCRIPT_NAME.test(name.trim()))) {
+                return fail(`Error bad_params: step ${i + 1} (${describeRunStep(step)}): name the reference with letters, digits, '.', '_' and '-'.`);
+            }
+            if (step.expect?.ignore !== undefined) {
+                const ignored = ignoreListSchema.safeParse(step.expect.ignore);
+                if (!ignored.success) {
+                    return fail(`Error bad_params: step ${i + 1} (${describeRunStep(step)}): expect.ignore: ${ignored.error.issues.map((issue) => issue.message).join("; ")}`);
+                }
+            }
         }
+        this.diffSaved = null;
         if (args.dry_run === true)
             return this.dryRunBatch(steps);
         const before = this.unlistedActions.get(session.id) ?? 0;
@@ -810,12 +1063,15 @@ export class TaplineTools {
         const trace = [];
         let ran = 0;
         let stop = null;
+        // The newest log time when the current step began: a failed step shows the app's warnings since then (§15.4).
+        let stepMark;
         for (const [i, step] of steps.entries()) {
             if (Date.now() - started > RUN_TIMEOUT_MS) {
                 stop = { index: i, code: "timeout", message: `the batch ran longer than ${RUN_TIMEOUT_MS / 1000} s`, rest: [] };
                 break;
             }
             const at = Date.now();
+            stepMark = this.newestLogTs(session.id);
             this.batch = { id: batchId, step: i + 1 };
             const answer = await this.runStep(step).finally(() => {
                 this.batch = undefined;
@@ -826,12 +1082,40 @@ export class TaplineTools {
                 break;
             }
             notes.push(...stepNotes(said, i + 1));
-            if (step.expect !== undefined) {
+            if (step.expect?.under !== undefined) {
+                // AGENT-TOOLS §15.3: the limits a performance step must keep; every broken one is listed.
+                const measured = this.lastPerf;
+                if (measured === undefined) {
+                    // A limit nobody measured must not pass.
+                    stop = { index: i, code: "expect_failed", message: "no measurement to check.", rest: [] };
+                    break;
+                }
+                const checked = checkUnder(step.expect.under, measured);
+                notes.push(...checked.notes.map((note) => `Note (step ${i + 1}): ${note}`));
+                if (checked.missed.length > 0) {
+                    stop = { index: i, code: "expect_failed", message: `${checked.missed.join("; ")}.`, rest: [] };
+                    break;
+                }
+            }
+            else if (step.expect !== undefined) {
                 const missed = await this.expectMissed(step.expect);
                 if (missed !== null) {
                     stop = { index: i, code: "expect_failed", message: `its action ran, but ${missed}`, rest: [] };
                     break;
                 }
+                // A picture check that held is kept in a recording, as compare_screen's is: right after the action, the
+                // script makes it that step's `matches` again (AGENT-TOOLS 1.9 §14.2).
+                if (step.expect.matches !== undefined) {
+                    const recorded = await this.recordCompare({
+                        name: step.expect.matches,
+                        ...(step.expect.threshold !== undefined ? { threshold: step.expect.threshold } : {}),
+                        ...(step.expect.ignore !== undefined ? { ignore: ignoreListSchema.parse(step.expect.ignore) } : {}),
+                    });
+                    if (recorded !== null) {
+                        stop = { index: i, ...parseError(recorded) };
+                        break;
+                    }
+                }
             }
             const route = step.route;
             if (Array.isArray(route) && route.every((part) => typeof part === "string")) {
@@ -855,29 +1139,61 @@ export class TaplineTools {
         const head = stop === null
             ? `Ran ${total} of ${total} steps in ${((Date.now() - started) / 1000).toFixed(1)} s.`
             : `Error ${stop.code}: Ran ${ran} of ${total} steps; stopped at step ${stop.index + 1} (${describeRunStep(steps[stop.index])}): ${stop.message}`;
-        const first = [head, ...trace, ...(stop?.rest ?? [])].join("\n");
+        const diffNote = stop !== null && this.diffSaved !== null ? [`Note: the difference is saved at ${this.diffSaved}.`] : [];
+        const first = [head, ...trace, ...(stop?.rest ?? []), ...diffNote].join("\n");
+        const tail = [...(stop !== null ? this.failureLogs(session.id, stop.index + 1, stepMark) : []), ...notes];
         let response;
         const live = this.host.current();
         if (args.look === false || live === undefined) {
-            response = text([first, ...notes].join("\n"));
+            response = text([first, ...tail].join("\n"));
         }
         else {
             response = await this.withLook(live, first, args.screenshot === true);
-            if (notes.length > 0) {
+            if (tail.length > 0) {
                 const [top, ...rest] = response.content;
                 if (top !== undefined && top.type === "text")
-                    response = { ...response, content: [{ type: "text", text: [top.text.trimEnd(), ...notes].join("\n") }, ...rest] };
+                    response = { ...response, content: [{ type: "text", text: [top.text.trimEnd(), ...tail].join("\n") }, ...rest] };
             }
         }
         return failed ? { ...response, isError: true } : response;
     }
+    /** The newest log time of a session (or of the app's current session), undefined without lines. */
+    newestLogTs(sessionId) {
+        return this.sessionLogs(sessionId).reduce((max, e) => (e.ts !== undefined && (max === undefined || e.ts > max) ? e.ts : max), undefined);
+    }
+    /**
+     * A session's buffered lines, also when it has ended. When the same app on the same phone came back as a new
+     * session, that session's lines follow. Another app's lines never stand in for it (Codex review of 1.3.0).
+     */
+    sessionLogs(sessionId) {
+        const record = this.host.sessionRecord(sessionId);
+        if (record === undefined)
+            return [];
+        const now = this.host.current();
+        if (now === undefined || now.id === sessionId || identityOf(now) !== record.identity)
+            return record.events;
+        try {
+            return [...record.events, ...this.host.logs(now.id)];
+        }
+        catch {
+            return record.events;
+        }
+    }
+    /** AGENT-TOOLS §15.4: `Logs (since step <n>):` and up to 20 lines at warning or above since the step began. */
+    failureLogs(sessionId, step, since) {
+        const lines = filterLogs(this.sessionLogs(sessionId), { since, level: "warning", limit: 20 });
+        return lines.length === 0 ? [] : [`Logs (since step ${step}):`, ...formatLogs(lines).split("\n")];
+    }
     /** `run` with dry_run (§11.4): the steps are checked already; step 1 is resolved, nothing is touched. */
     async dryRunBatch(steps) {
         const total = steps.length;
         const first = steps[0];
         const head = `Would run ${total} step${total === 1 ? "" : "s"}`;
-        if (["tap", "long_press", "toggle", "type_text", "scroll", "back", "swipe"].includes(first.tool)) {
-            const answer = await this.runStep({ ...first, dry_run: true });
+        // A performance step with a tap: the tap resolves like any touch; nothing is measured (AGENT-TOOLS §15.3).
+        const perfTap = first.tool === "performance" ? first["tap"] : undefined;
+        const probe = perfTap !== undefined ? { tool: "tap", target: perfTap } : first;
+        if (["tap", "long_press", "toggle", "type_text", "scroll", "back", "swipe"].includes(probe.tool)) {
+            const answer = await this.runStep({ ...probe, dry_run: true });
             const said = answer.content.map((block) => (block.type === "text" ? block.text : "")).join("\n").trim();
             const [line, ...rest] = said.split("\n");
             if (answer.isError === true) {
@@ -887,6 +1203,10 @@ export class TaplineTools {
             const would = (line ?? "").replace(/^Would /, "would ");
             return text([`${head}; step 1 ${would}`, ...rest].join("\n"));
         }
+        if (first.tool === "performance") {
+            const p = first;
+            return text(`${head}; step 1 would ${p["launch"] === true ? "reload the app and time it to the first settled screen" : `measure ${Number(p["seconds"] ?? 3)} s`}.`);
+        }
         return text(`${head}; step 1 would ${describeRunStep(first)}.`);
     }
     /** One step of `run`, as its own tool call without a list. */
@@ -916,6 +1236,10 @@ export class TaplineTools {
                 return this.waitFor(quiet);
             case "app_command":
                 return this.appCommand(quiet);
+            case "compare_screen":
+                return this.compareStep(rest);
+            case "performance":
+                return this.performance(rest);
         }
     }
     /** The screen's route names now (one cheap read), or null when the app has no router or didn't answer. */
@@ -928,6 +1252,15 @@ export class TaplineTools {
     }
     /** Null when the expectation holds within its time; else how it failed. */
     async expectMissed(e) {
+        if (e.text !== undefined || e.id !== undefined || e.label !== undefined) {
+            const missed = await this.textExpectMissed(e);
+            if (missed !== null)
+                return missed;
+        }
+        // A picture check comes last, once the rest held.
+        return e.matches === undefined ? null : this.matchMissed(e.matches, e.threshold ?? DEFAULT_MATCH_THRESHOLD, ignoreListSchema.parse(e.ignore ?? []));
+    }
+    async textExpectMissed(e) {
         const seconds = e.timeout ?? EXPECT_TIMEOUT_S;
         const which = e.text !== undefined ? { text: e.text } : e.id !== undefined ? { id: e.id } : { label: e.label };
         const seen = await this.waitFor({ ...which, ...(e.gone === true ? { gone: true } : {}), timeout: Math.max(0.5, seconds), look: false });
@@ -944,7 +1277,7 @@ export class TaplineTools {
         for (;;) {
             const tree = treeResultSchema.safeParse(await this.host.request("tree", { peek: true }, { sessionId: session.id }).catch(() => null));
             const element = tree.success
-                ? tree.data.elements.find((el) => (e.id !== undefined ? el.testID === e.id : (el.label ?? "").toLowerCase() === (e.label ?? "").toLowerCase()))
+                ? tree.data.elements.find((el) => (e.id !== undefined ? el.testID === e.id : labelOfElement(el).toLowerCase() === (e.label ?? "").toLowerCase()))
                 : undefined;
             if (element !== undefined) {
                 actual = typeof element.checked === "boolean" ? (element.checked ? "on" : "off") : typeof element.value === "string" ? element.value : undefined;
@@ -1270,7 +1603,7 @@ export class TaplineTools {
         const same = tree.data.elements.filter((el) => typeof t.testID === "string"
             ? el.testID === t.testID
             : typeof t.label === "string"
-                ? (el.label ?? "").toLowerCase() === t.label.toLowerCase()
+                ? labelOfElement(el).toLowerCase() === t.label.toLowerCase()
                 : typeof t.text === "string"
                     ? el.text === t.text
                     : false);
@@ -1555,66 +1888,99 @@ export class TaplineTools {
         else
             content.push({ type: "image", data: image.data, mimeType: image.mime });
     }
-    async compareScreen(args) {
-        const session = this.host.current();
-        if (session === undefined)
-            return this.notConnected();
-        const name = args.name.trim();
-        if (!SCRIPT_NAME.test(name))
-            return fail("Error bad_params: name the reference with letters, digits, '.', '_' and '-'.");
+    /** Where this app's reference pictures are kept, or an error answer. */
+    referenceFolder(session) {
         const dir = this.options.baselinesDir;
         if (dir === undefined)
             return fail("Error internal: no folder for reference pictures is configured.");
-        const appFolder = (session.app.id ?? session.app.name).replace(/[^\w.-]/g, "_");
-        const path = join(dir, appFolder, `${name}.jpg`);
+        return join(dir, (session.app.id ?? session.app.name).replace(/[^\w.-]/g, "_"));
+    }
+    /** The element list for naming regions and masking, read as a peek: the agent's refs and baseline must stay as they are. */
+    async peekElements(sessionId) {
+        try {
+            const tree = treeResultSchema.safeParse(await this.host.request("tree", { peek: true }, { sessionId }));
+            if (tree.success && tree.data.screen)
+                return { scaleBase: tree.data.screen.width, elements: tree.data.elements };
+        }
+        catch {
+            // positions stay in pixels
+        }
+        return { scaleBase: undefined, elements: [] };
+    }
+    /**
+     * Takes the screen and compares it with the saved reference called `name`, never saving. `referencesDirs` are the
+     * folders to look in, in order. A missing reference hands back the screenshot, so the caller may save it.
+     */
+    async checkAgainstReference(session, name, options) {
         let shot;
         try {
-            shot = await this.takeShot(session.id, args.width ?? DEFAULT_SCREENSHOT_WIDTH, 0.9);
+            shot = await this.takeShot(session.id, options.width, 0.9);
         }
         catch (error) {
-            return fail(describeError(error));
-        }
-        if (args.update === true || !existsSync(path)) {
-            try {
-                mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-                writeFileSync(path, Buffer.from(shot.data, "base64"), { mode: 0o600 });
-            }
-            catch (error) {
-                return fail(`Error internal: couldn't save the reference: ${error instanceof Error ? error.message : String(error)}`);
-            }
-            return text(`Saved the reference picture "${name}" (${shot.width ?? "?"}x${shot.height ?? "?"}) in ${path}. Next time, compare_screen { name: "${name}" } shows what changed.`);
+            return { kind: "error", line: describeError(error) };
         }
-        let diff;
+        this.lastMaskElements = undefined;
+        if (!SCRIPT_NAME.test(name))
+            return { kind: "error", line: BAD_REFERENCE_NAME };
+        const path = options.referencesDirs.map((dir) => join(dir, `${name}.jpg`)).find((candidate) => existsSync(candidate));
+        if (path === undefined)
+            return { kind: "missing", shot };
+        let reference;
         try {
-            diff = diffImages({ mime: "image/jpeg", data: readFileSync(path).toString("base64") }, shot);
+            reference = { mime: "image/jpeg", data: readFileSync(path).toString("base64") };
         }
         catch (error) {
-            return fail(`Error bad_params: ${error instanceof Error ? error.message : String(error)} To start over, use update: true.`);
+            // A reference that can't be read (no permission, a folder in its place) is a failed check, never a crash.
+            return { kind: "error", line: `Error bad_params: the reference "${name}" can't be read (${error instanceof Error ? error.message : String(error)}). To start over, use update: true.` };
         }
-        if (diff.changedPixels === 0)
-            return text(`No visible change from the reference "${name}".`);
-        // Name the regions in points, with the elements they touch, from a fresh element list.
-        let scale = 1;
-        let elements = [];
+        let refSize;
+        let shotSize;
         try {
-            // `peek`: the agent isn't given this list, so its refs and its baseline for changes must stay as they are.
-            const tree = treeResultSchema.safeParse(await this.host.request("tree", { peek: true }, { sessionId: session.id }));
-            if (tree.success && tree.data.screen) {
-                scale = diff.width / tree.data.screen.width;
-                elements = tree.data.elements;
+            refSize = imageSize(reference);
+            shotSize = imageSize(shot);
+        }
+        catch (error) {
+            return { kind: "error", line: `Error bad_params: ${error instanceof Error ? error.message : String(error)} To start over, use update: true.` };
+        }
+        if (refSize.width !== shotSize.width || refSize.height !== shotSize.height) {
+            return {
+                kind: "size",
+                message: `the reference "${name}" is ${refSize.width}x${refSize.height} px and this screen is ${shotSize.width}x${shotSize.height}; take it at the same width, or update: true.`,
+            };
+        }
+        let seen;
+        const notes = [];
+        const mask = [];
+        if (options.ignore.length > 0) {
+            seen = await this.peekElements(session.id);
+            this.lastMaskElements = seen.elements;
+            if (seen.scaleBase === undefined) {
+                return { kind: "error", line: "Error internal: couldn't read the screen's elements to paint out what ignore names." };
             }
+            const masked = ignoreRects(options.ignore, seen.elements, shotSize.width / seen.scaleBase, shotSize);
+            mask.push(...masked.rects);
+            notes.push(...masked.notes);
         }
-        catch {
-            // positions stay in pixels
+        let diff;
+        try {
+            diff = diffImages(reference, shot, { mask });
         }
+        catch (error) {
+            return { kind: "error", line: `Error bad_params: ${error instanceof Error ? error.message : String(error)} To start over, use update: true.` };
+        }
+        // The pass bar compares the exact share; the rounded percent is only for showing (a few pixels round to 0%).
+        const exactPercent = (diff.changedPixels / Math.max(1, diff.width * diff.height)) * 100;
+        if (diff.changedPixels === 0 || exactPercent <= options.threshold) {
+            return { kind: "match", percent: diff.changedPercent, notes };
+        }
+        // Name the regions in points, with the elements they touch.
+        const found = seen ?? (await this.peekElements(session.id));
+        const scale = found.scaleBase === undefined ? 1 : diff.width / found.scaleBase;
         const unit = scale === 1 ? "pixels" : "points";
-        const lines = [
-            `${diff.changedPercent}% of the screen changed from the reference "${name}", in ${diff.boxes.length} region${diff.boxes.length === 1 ? "" : "s"} (${unit}):`,
-        ];
-        for (const box of diff.boxes) {
+        const regions = diff.boxes.map((box) => {
             const b = { x: box.x / scale, y: box.y / scale, width: box.width / scale, height: box.height / scale };
             // The smallest named elements there: a page-sized container overlaps every change.
-            const near = elements
+            const near = found.elements
                 .filter((e) => e.frame && e.frame.x < b.x + b.width && e.frame.x + e.frame.width > b.x && e.frame.y < b.y + b.height && e.frame.y + e.frame.height > b.y)
                 .filter((e) => (e.text ?? "") !== "" || (e.label ?? "") !== "" || (e.testID ?? "") !== "")
                 .map((e) => ({ e, area: (e.frame?.width ?? 0) * (e.frame?.height ?? 0) }))
@@ -1622,12 +1988,289 @@ export class TaplineTools {
                 .sort((x, y) => x.area - y.area)
                 .slice(0, 2)
                 .map(({ e }) => describeElement(e));
-            lines.push(`- @${Math.round(b.x)},${Math.round(b.y)} ${Math.round(b.width)}x${Math.round(b.height)}${near.length > 0 ? `: ${near.join(", ")}` : ""}`);
+            return { at: `@${Math.round(b.x)},${Math.round(b.y)} ${Math.round(b.width)}x${Math.round(b.height)}`, near };
+        });
+        const count = regions.length;
+        const where = `in ${count} region${count === 1 ? "" : "s"} (${unit})`;
+        const lines = [`Differs from the reference "${name}": ${diff.changedPercent}% changed, ${where}:`];
+        for (const region of regions.slice(0, MAX_REGION_LINES)) {
+            lines.push(`- ${region.at}${region.near.length > 0 ? `: ${region.near.join(", ")}` : ""}`);
+        }
+        if (count > MAX_REGION_LINES)
+            lines.push(`(+${count - MAX_REGION_LINES} more regions)`);
+        const listed = regions.slice(0, MAX_REGION_LINES).map((region) => region.at).join(", ");
+        const reason = `${diff.changedPercent}% changed from the reference "${name}" (threshold ${options.threshold}%), ${where}: ${listed}${count > MAX_REGION_LINES ? `, +${count - MAX_REGION_LINES} more` : ""}.`;
+        return { kind: "differs", percent: diff.changedPercent, lines, reason, image: diff.image, notes };
+    }
+    /** Why a check does not hold (for `run`, as a step or as `matches`), or null when it matches. */
+    referenceReason(check, name) {
+        switch (check.kind) {
+            case "match":
+                return null;
+            case "missing":
+                return { code: "expect_failed", message: `no reference "${name}" yet; save one with compare_screen { name: "${name}" }.` };
+            case "size":
+                return { code: "bad_params", message: check.message };
+            case "error": {
+                const { code, message } = parseError(check.line);
+                return { code, message };
+            }
+            case "differs":
+                return { code: "expect_failed", message: check.reason };
+        }
+    }
+    /** Whether the screen matches the reference `name` now (`expect.matches`): null when it does, else the reason. */
+    async matchMissed(name, threshold, ignore) {
+        this.lastMaskElements = undefined;
+        if (!SCRIPT_NAME.test(name))
+            return parseError(BAD_REFERENCE_NAME).message;
+        const session = this.host.current();
+        if (session === undefined)
+            return "the app isn't connected";
+        const folder = this.referenceFolder(session);
+        if (typeof folder !== "string")
+            return parseError(folder.content.map((block) => (block.type === "text" ? block.text : "")).join("\n")).message;
+        if (this.replayContext?.update === true) {
+            // --update-references: the check saves the screen into the script's folder, and holds.
+            const saved = await this.saveReferenceHere(session, name, DEFAULT_SCREENSHOT_WIDTH, this.replayContext.referencesDir);
+            return saved.isError === true ? parseError(saved.content.map((block) => (block.type === "text" ? block.text : "")).join("\n")).message : null;
+        }
+        const check = await this.checkAgainstReference(session, name, {
+            threshold,
+            ignore,
+            width: DEFAULT_SCREENSHOT_WIDTH,
+            referencesDirs: this.referencesDirs(folder),
+        });
+        this.keepDiff(check, name);
+        return this.referenceReason(check, name)?.message ?? null;
+    }
+    /** Where a check looks for `<name>.jpg`: the folder next to a replayed script first, then the app's own store. */
+    referencesDirs(folder) {
+        return this.replayContext !== null ? [this.replayContext.referencesDir, folder] : [folder];
+    }
+    /** In a replay, a failed check leaves its red picture at `<script>.diff/<name>.jpg`. */
+    keepDiff(check, name) {
+        if (this.replayContext === null || check.kind !== "differs" || !SCRIPT_NAME.test(name))
+            return;
+        const path = join(this.replayContext.diffDir, `${name}.jpg`);
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, Buffer.from(check.image.data, "base64"));
+            this.diffSaved = path;
+        }
+        catch {
+            // the failure still reads without the picture
+        }
+    }
+    /** Takes the screen and saves it as the reference `name` in `dir`. */
+    async saveReferenceHere(session, name, width, dir) {
+        try {
+            return this.writeReference(dir, name, await this.takeShot(session.id, width, 0.9));
+        }
+        catch (error) {
+            return fail(describeError(error));
+        }
+    }
+    writeReference(folder, name, shot) {
+        // Every write checks the name itself, whatever the caller checked: no way out of the references folder.
+        if (!SCRIPT_NAME.test(name))
+            return fail(BAD_REFERENCE_NAME);
+        const path = join(folder, `${name}.jpg`);
+        try {
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            writeFileSync(path, Buffer.from(shot.data, "base64"), { mode: 0o600 });
+        }
+        catch (error) {
+            return fail(`Error internal: couldn't save the reference: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        let size = `${shot.width ?? "?"}x${shot.height ?? "?"}`;
+        try {
+            const real = imageSize(shot);
+            size = `${real.width}x${real.height}`;
+        }
+        catch {
+            // the app's own size stays
+        }
+        return text(`Saved the reference "${name}" (${size} px).`);
+    }
+    /** A `compare_screen` step of `run`: it never saves; it holds on a match and stops the batch otherwise. */
+    async compareStep(args) {
+        this.lastMaskElements = undefined;
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        const name = args.name.trim();
+        if (!SCRIPT_NAME.test(name))
+            return fail("Error bad_params: name the reference with letters, digits, '.', '_' and '-'.");
+        const folder = this.referenceFolder(session);
+        if (typeof folder !== "string")
+            return folder;
+        if (this.replayContext?.update === true) {
+            return this.saveReferenceHere(session, name, args.width ?? DEFAULT_SCREENSHOT_WIDTH, this.replayContext.referencesDir);
+        }
+        const check = await this.checkAgainstReference(session, name, {
+            threshold: args.threshold ?? DEFAULT_MATCH_THRESHOLD,
+            ignore: args.ignore ?? [],
+            width: args.width ?? DEFAULT_SCREENSHOT_WIDTH,
+            referencesDirs: this.referencesDirs(folder),
+        });
+        this.keepDiff(check, name);
+        const why = this.referenceReason(check, name);
+        if (why !== null)
+            return fail(`Error ${why.code}: ${why.message}`);
+        if (check.kind !== "match")
+            return fail("Error internal: the comparison gave no answer.");
+        // A check that held inside `run` is kept in a recording too, with its options.
+        const recorded = await this.recordCompare({
+            name,
+            ...(args.threshold !== undefined ? { threshold: args.threshold } : {}),
+            ...(args.ignore !== undefined ? { ignore: args.ignore } : {}),
+            ...(args.width !== undefined ? { width: args.width } : {}),
+        });
+        if (recorded !== null)
+            return fail(recorded);
+        return text([`Matches the reference "${name}": ${check.percent}% changed.`, ...check.notes.map((n) => `Note: ${n}`)].join("\n"));
+    }
+    /**
+     * Saves a visual check that held as a `compareScreen` step of the recording, when one is running: the name, and the
+     * threshold, the ignore list (refs made stable) and the width when given. `update` is never written. Answers an
+     * error line when an ignore ref can't be kept in a script, else null (also when nothing is recording).
+     */
+    async recordCompare(check) {
+        if (this.recording === null || this.replaying)
+            return null;
+        const session = this.host.current();
+        let kept = check.ignore;
+        if (session !== undefined && kept !== undefined && kept.length > 0) {
+            const stable = await this.stableIgnore(session.id, kept, this.lastMaskElements);
+            if (typeof stable === "string")
+                return stable;
+            kept = stable;
+        }
+        if (this.recording === null)
+            return null;
+        this.recording.steps.push({
+            method: "compareScreen",
+            params: {
+                name: check.name.trim(),
+                ...(check.threshold !== undefined ? { threshold: check.threshold } : {}),
+                ...(kept !== undefined && kept.length > 0 ? { ignore: kept } : {}),
+                ...(check.width !== undefined ? { width: check.width } : {}),
+            },
+        });
+        return null;
+    }
+    /**
+     * `ignore` as a script keeps it (AGENT-TOOLS 1.9 §14.2): a ref becomes the element's id, else label, else text,
+     * read from the list now. A string is the error answer when a ref can't be kept.
+     */
+    async stableIgnore(sessionId, ignore, known) {
+        if (!ignore.some((item) => !("width" in item) && item.ref !== undefined))
+            return ignore;
+        // The elements the comparison painted out when it had them, so the script keeps exactly that mask.
+        const seen = known !== undefined ? { elements: known } : await this.peekElements(sessionId);
+        const kept = [];
+        for (const item of ignore) {
+            if ("width" in item || item.ref === undefined) {
+                kept.push(item);
+                continue;
+            }
+            const element = seen.elements.find((e) => e.ref === item.ref);
+            if (element === undefined)
+                return `Error bad_params: ignore ${item.ref} isn't on the screen, so it can't be saved in a script.`;
+            // When several elements share the name, the saved item keeps which one it was (`index`, counted as ignoreRects
+            // counts: elements with a frame, in list order), so a replay paints out that one and not all of them.
+            const framed = seen.elements.filter((e) => e.frame !== undefined);
+            const withIndex = (saved, same) => {
+                const matching = framed.filter(same);
+                const at = matching.indexOf(element);
+                return matching.length > 1 && at >= 0 ? { ...saved, index: at } : saved;
+            };
+            if (typeof element.testID === "string" && element.testID !== "") {
+                const id = element.testID;
+                kept.push(withIndex({ id }, (e) => e.testID === id));
+            }
+            else if (typeof element.label === "string" && element.label !== "") {
+                const label = element.label.toLowerCase();
+                kept.push(withIndex({ label: element.label }, (e) => labelOfElement(e).toLowerCase() === label));
+            }
+            else if (typeof element.text === "string" && element.text !== "") {
+                const text = element.text.toLowerCase();
+                kept.push(withIndex({ text: element.text }, (e) => (e.text ?? "").toLowerCase() === text));
+            }
+            else {
+                return `Error bad_params: ignore ${describeElement(element)} has no id, label or text, so a script couldn't find it again; give it a testID, or ignore a rect {x, y, width, height}.`;
+            }
+        }
+        return kept;
+    }
+    async compareScreen(args) {
+        // Each check starts with no mask list: an update, or a first save, never records from an earlier comparison.
+        this.lastMaskElements = undefined;
+        const recording = this.recording !== null && !this.replaying;
+        const session = this.host.current();
+        // An ignore ref that a script couldn't find again is refused before anything is compared.
+        if (recording && session !== undefined && args.ignore !== undefined && args.ignore.length > 0) {
+            const stable = await this.stableIgnore(session.id, args.ignore);
+            if (typeof stable === "string")
+                return fail(stable);
+        }
+        const answer = await this.compareScreenNow(args);
+        if (recording && answer.isError !== true) {
+            // `update` is never written: the script checks against the reference it carries.
+            const recorded = await this.recordCompare({
+                name: args.name,
+                ...(args.threshold !== undefined ? { threshold: args.threshold } : {}),
+                ...(args.ignore !== undefined ? { ignore: args.ignore } : {}),
+                ...(args.width !== undefined ? { width: args.width } : {}),
+            });
+            if (recorded !== null)
+                return fail(recorded);
+        }
+        return answer;
+    }
+    async compareScreenNow(args) {
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        const name = args.name.trim();
+        if (!SCRIPT_NAME.test(name))
+            return fail("Error bad_params: name the reference with letters, digits, '.', '_' and '-'.");
+        const folder = this.referenceFolder(session);
+        if (typeof folder !== "string")
+            return folder;
+        const width = args.width ?? DEFAULT_SCREENSHOT_WIDTH;
+        const save = (shot) => this.writeReference(folder, name, shot);
+        if (args.update === true) {
+            try {
+                return save(await this.takeShot(session.id, width, 0.9));
+            }
+            catch (error) {
+                return fail(describeError(error));
+            }
+        }
+        const check = await this.checkAgainstReference(session, name, {
+            threshold: args.threshold ?? DEFAULT_MATCH_THRESHOLD,
+            ignore: args.ignore ?? [],
+            width,
+            referencesDirs: [folder],
+        });
+        switch (check.kind) {
+            case "missing":
+                return save(check.shot);
+            case "error":
+                return fail(check.line);
+            case "size":
+                return fail(`Error bad_params: ${check.message}`);
+            case "match":
+                return text([`Matches the reference "${name}": ${check.percent}% changed.`, ...check.notes.map((n) => `Note: ${n}`)].join("\n"));
+            case "differs": {
+                const lines = [...check.lines, "The image shows the screen now, faded, with the changed pixels in red.", ...check.notes.map((n) => `Note: ${n}`)];
+                const content = [];
+                this.deliver(session.id, check.image, lines, content);
+                return { content: [{ type: "text", text: lines.join("\n") }, ...content] };
+            }
         }
-        lines.push("The image shows the screen now, faded, with the changed pixels in red.");
-        const content = [];
-        this.deliver(session.id, diff.image, lines, content);
-        return { content: [{ type: "text", text: lines.join("\n") }, ...content] };
     }
     async filmstrip(args) {
         const session = this.host.current();
@@ -1644,11 +2287,19 @@ export class TaplineTools {
                 // A screenshot takes a few hundred ms on a phone, so frame 1 is the "before".
                 // The tap is a touch like any other: the safety policy decides first.
                 const pressParams = { target: toWireTarget(args.tap) };
-                const gate = await this.policyGate(session, "tap", "press", pressParams, listsFor(this.policy, session.app));
-                if ("stop" in gate)
-                    return gate.stop;
-                frames.push(await this.takeShot(session.id, frameWidth, 0.8));
-                await this.host.request("press", pressParams, { sessionId: session.id });
+                // The policy check, the "before" frame and the tap are one turn of the live view's queue: a pause refuses
+                // it, a person's input goes first, and the screen can't change between the check and the tap (PR #4 review).
+                const turn = async () => {
+                    const gate = await this.policyGate(session, "tap", "press", pressParams, listsFor(this.policy, session.app));
+                    if ("stop" in gate)
+                        return gate.stop;
+                    frames.push(await this.takeShot(session.id, frameWidth, 0.8));
+                    await this.host.request("press", pressParams, { sessionId: session.id });
+                    return null;
+                };
+                const stopped = this.options.control ? await this.options.control.runAgent(turn) : await turn();
+                if (stopped !== null)
+                    return stopped;
             }
             for (let i = frames.length; i < count; i++) {
                 const at = Date.now();
@@ -1722,7 +2373,10 @@ export class TaplineTools {
                 }
                 this.recording = null;
                 const count = script.steps.length;
-                const lines = [`Saved ${count} step${count === 1 ? "" : "s"} to ${path}.`];
+                // AGENT-TOOLS 1.9 §14.3: the references the steps use travel with the script.
+                const copied = this.copyReferences(script.steps, recording.app, path);
+                const withPictures = copied === null ? "" : `, and ${copied.count} reference picture${copied.count === 1 ? "" : "s"} to ${copied.folder}`;
+                const lines = [`Saved ${count} step${count === 1 ? "" : "s"} to ${path}${withPictures}.`];
                 const ref = refStep(script.steps);
                 if (ref !== null) {
                     lines.push(`Note: step ${ref + 1} targets a ref, which won't exist on a new run, so replay refuses the script. Give that element a testID, or record it again by its text or label.`);
@@ -1738,6 +2392,41 @@ export class TaplineTools {
             }
         }
     }
+    /** `<script dir>/<script name>.references` and `.diff` for a script file. */
+    scriptSideFolder(path, kind) {
+        return join(dirname(path), `${basename(path).replace(/\.json$/i, "")}.${kind}`);
+    }
+    /** Copies each reference the steps use from the app's store next to the script; null when there are none. */
+    copyReferences(steps, app, scriptPath) {
+        const dir = this.options.baselinesDir;
+        if (dir === undefined)
+            return null;
+        const names = new Set();
+        for (const step of steps) {
+            const p = step;
+            if (step.tool === "compare_screen" && typeof p["name"] === "string" && SCRIPT_NAME.test(p["name"]))
+                names.add(p["name"]);
+            if (step.expect?.matches !== undefined && SCRIPT_NAME.test(step.expect.matches))
+                names.add(step.expect.matches);
+        }
+        const store = join(dir, (app.id ?? app.name).replace(/[^\w.-]/g, "_"));
+        const folder = this.scriptSideFolder(scriptPath, "references");
+        let count = 0;
+        for (const name of names) {
+            const from = join(store, `${name}.jpg`);
+            if (!existsSync(from))
+                continue;
+            try {
+                mkdirSync(folder, { recursive: true });
+                copyFileSync(from, join(folder, `${name}.jpg`));
+                count++;
+            }
+            catch {
+                // the script still saved; the picture stays in the store
+            }
+        }
+        return count === 0 ? null : { count, folder };
+    }
     scriptList() {
         const dir = this.options.scriptsDir;
         if (dir === undefined || !existsSync(dir))
@@ -1756,7 +2445,7 @@ export class TaplineTools {
         }
         return lines.length === 0 ? "No saved scripts." : ["Saved scripts:", ...lines].join("\n");
     }
-    async replay(args) {
+    async replay(args, options = {}) {
         const name = (args.name ?? "").trim();
         const given = (args.path ?? "").trim();
         if (name === "" && given === "")
@@ -1800,6 +2489,11 @@ export class TaplineTools {
                 notes.push("Note: the app hadn't reconnected after starting fresh when the steps began.");
         }
         this.replaying = true;
+        this.replayContext = {
+            referencesDir: this.scriptSideFolder(path, "references"),
+            diffDir: this.scriptSideFolder(path, "diff"),
+            update: options.updateReferences === true,
+        };
         try {
             const answer = await this.run({ steps: script.steps, look: args.look, screenshot: args.screenshot });
             if (notes.length === 0)
@@ -1811,6 +2505,7 @@ export class TaplineTools {
         }
         finally {
             this.replaying = false;
+            this.replayContext = null;
         }
     }
     async withLook(session, line, screenshot = false) {
@@ -2294,37 +2989,213 @@ export class TaplineTools {
                 // fall through with an empty list
             }
         }
-        const last = entries.reduce((max, e) => (e.ts !== undefined && (max === undefined || e.ts > max) ? e.ts : max), undefined);
-        const footer = last !== undefined ? `\n(latest ts ${last}; pass since=${last} for newer lines)` : "";
-        return text(`${formatLogs(entries)}${footer}`);
+        const newest = entries.reduce((max, e) => (e.ts !== undefined && (max === undefined || e.ts > max) ? e.ts : max), undefined);
+        const query = { since: args.since, level: args.level, grep: args.grep, limit: args.limit };
+        return text(formatLogAnswer(filterLogs(entries, query), query, newest ?? args.since ?? 0));
+    }
+    /** The newest fatal JS error of the app (`all`: the last 5). Reading them tells the agent what the notes did. */
+    crash(args = {}) {
+        // The app being driven, else the one that stopped last. Never every app's crashes at once.
+        const known = this.host.current() ?? this.host.lastCrashEvent()?.of;
+        if (known === undefined)
+            return text(NO_CRASH_TEXT);
+        // Reading them tells the agent what the notes of this app said; other apps' stay pending.
+        this.notedCrashSeqs.set(identityOf(known), this.host.crashMark());
+        const crashes = this.host.crashes(known);
+        if (crashes.length === 0)
+            return text(NO_CRASH_TEXT);
+        return text(crashes.slice(0, args.all === true ? 5 : 1).map(formatCrash).join("\n\n"));
     }
     async reload(args) {
         const session = this.host.current();
         if (session === undefined)
             return this.notConnected();
         try {
-            await this.host.request("reload", {}, { sessionId: session.id, timeoutMs: 5000 });
-        }
-        catch (error) {
-            // The app dies mid-reload, so a dropped connection or a missing answer means it worked.
-            const worked = error instanceof TaplineError && (error.code === "reconnecting" || error.code === "timeout" || error.code === "not_answering");
-            if (!worked)
-                return fail(describeError(error));
+            try {
+                // The app goes away on purpose: that is no crash.
+                this.host.expectEnd(session.id);
+                await this.host.request("reload", {}, { sessionId: session.id, timeoutMs: 5000 });
+            }
+            catch (error) {
+                // The app dies mid-reload, so a dropped connection or a missing answer means it worked.
+                const worked = error instanceof TaplineError && (error.code === "reconnecting" || error.code === "timeout" || error.code === "not_answering");
+                if (!worked)
+                    return fail(describeError(error));
+            }
+            if (args.look === false)
+                return text("Reload requested.");
+            const deadline = Date.now() + this.reloadWaitMs;
+            for (;;) {
+                const now = this.host.current();
+                if (now !== undefined && now.id !== session.id)
+                    break;
+                if (Date.now() > deadline)
+                    return text("Reload requested, but the app has not reconnected yet. Try look in a few seconds.");
+                await sleep(100);
+            }
         }
-        if (args.look === false)
-            return text("Reload requested.");
-        const deadline = Date.now() + this.reloadWaitMs;
-        for (;;) {
-            const now = this.host.current();
-            if (now !== undefined && now.id !== session.id)
-                break;
-            if (Date.now() > deadline)
-                return text("Reload requested, but the app has not reconnected yet. Try look in a few seconds.");
-            await sleep(100);
+        finally {
+            // Whatever happened, the wait is over: a reload that "worked" without the app going away must not
+            // leave a later, real crash of this session explained.
+            this.host.expectEnd(session.id, false);
         }
         await sleep(this.reloadSettleMs);
         return this.withLook(this.host.current() ?? session, "Reloaded; the app reconnected.");
     }
+    // -- performance (AGENT-TOOLS §15.3)
+    /**
+     * `launch`: a JavaScript reload (development builds), timed from the request to the new session's first
+     * settled screen. Stops with the answer when the reload can't be made or the app doesn't come back.
+     */
+    async timedReload(session) {
+        const started = Date.now();
+        let fresh;
+        try {
+            try {
+                // The app goes away on purpose: that is no crash.
+                this.host.expectEnd(session.id);
+                await this.host.request("reload", {}, { sessionId: session.id, timeoutMs: 5000 });
+            }
+            catch (error) {
+                // The app dies mid-reload, so a dropped connection or a missing answer means it worked.
+                const worked = error instanceof TaplineError && (error.code === "reconnecting" || error.code === "timeout" || error.code === "not_answering");
+                if (!worked) {
+                    if (error instanceof TaplineError && error.code === "unsupported") {
+                        return { stop: fail(`Error unsupported: launch is a JavaScript reload, and only development builds can do one (${error.message}).`) };
+                    }
+                    return { stop: fail(describeError(error)) };
+                }
+            }
+            const deadline = Date.now() + this.reloadWaitMs;
+            // Only the same app on the same phone, back as a new session, counts: another connected app that became
+            // current meanwhile is never measured as the reload (Codex review of 1.3.0).
+            const same = identityOf(session);
+            while (fresh === undefined) {
+                const back = this.host.sessions().find((s) => s.id !== session.id && identityOf(s) === same);
+                if (back !== undefined) {
+                    fresh = back;
+                    // and the agent goes on driving it, not whichever app the host picked when the old session dropped
+                    if (this.host.current()?.id !== back.id)
+                        this.host.select(back.id);
+                }
+                else if (Date.now() > deadline) {
+                    return { stop: fail(`Error timeout: the app hadn't reconnected ${Number((this.reloadWaitMs / 1000).toFixed(1))} s after the reload; try look in a few seconds.`) };
+                }
+                else
+                    await sleep(100);
+            }
+        }
+        finally {
+            // The wait is over, whatever happened: a reload that "worked" without the app going away must not leave
+            // a later crash of this session explained away.
+            this.host.expectEnd(session.id, false);
+        }
+        // The first settled screen: the app waits until React hasn't committed for a moment (§6).
+        // The first settled screen: a launch time is only reported when the app said it settled.
+        try {
+            await this.host.request("perfSettle", {}, { sessionId: fresh.id, timeoutMs: 8000 });
+        }
+        catch (error) {
+            return { stop: fail(describeError(error)) };
+        }
+        return { session: fresh, seconds: (Date.now() - started) / 1000 };
+    }
+    /** One measuring window in the app: start, (the tap,) wait out `seconds`, stop. */
+    async measureWindow(session, seconds, press) {
+        const id = { sessionId: session.id };
+        // The window's number: the stop names it, so a call never takes another call's numbers (an older SDK has none).
+        let stopParams = {};
+        try {
+            const started = await this.host.request("perfStart", {}, id);
+            const windowId = typeof started === "object" && started !== null ? started.id : undefined;
+            if (typeof windowId === "number")
+                stopParams = { id: windowId };
+        }
+        catch (error) {
+            if (error instanceof TaplineError && error.code === "unsupported") {
+                throw new TaplineError("unsupported", "this app's Tapline is too old for performance; update react-native-tapline.");
+            }
+            throw error;
+        }
+        const started = Date.now();
+        try {
+            // The caller holds the live view's queue for the whole window when there is a tap (see performance).
+            if (press !== undefined)
+                await this.host.request("press", press, id);
+            const rest = seconds * 1000 - (Date.now() - started);
+            if (rest > 0)
+                await sleep(rest);
+        }
+        catch (error) {
+            await this.host.request("perfStop", stopParams, id).catch(() => undefined);
+            throw error;
+        }
+        const parsed = perfResultSchema.safeParse(await this.host.request("perfStop", stopParams, id));
+        if (!parsed.success)
+            throw new TaplineError("internal", "the app returned performance numbers the host could not read.");
+        return parsed.data;
+    }
+    async performance(args = {}) {
+        this.lastPerf = undefined;
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        if (args.launch === true && args.tap !== undefined) {
+            return fail("Error bad_params: launch reloads the app and tap taps in it; give one of them.");
+        }
+        const seconds = args.seconds ?? 3;
+        try {
+            let measure;
+            if (args.launch === true) {
+                const launched = await this.timedReload(session);
+                if ("stop" in launched)
+                    return launched.stop;
+                measure = { result: await this.measureWindow(launched.session, seconds), launchS: launched.seconds };
+            }
+            else {
+                let press;
+                if (args.tap !== undefined) {
+                    // The tap is a touch like any other: the safety policy decides first (as for filmstrip).
+                    press = { target: toWireTarget(args.tap) };
+                    const stale = this.staleRef(press);
+                    if (stale !== null)
+                        return stale;
+                }
+                // With a tap, the policy check and the whole window are one turn of the live view's queue: a pause refuses
+                // it, a person's input goes first and waits for the window, and the screen can't change between the check
+                // and the tap (Codex and CodeRabbit reviews of 1.3.0).
+                const tapped = press;
+                const window = async () => {
+                    if (tapped !== undefined) {
+                        const gate = await this.policyGate(session, "tap", "press", tapped, listsFor(this.policy, session.app));
+                        if ("stop" in gate)
+                            return { stop: gate.stop };
+                    }
+                    return { result: await this.measureWindow(session, seconds, tapped) };
+                };
+                const outcome = tapped !== undefined && this.options.control ? await this.options.control.runAgent(window) : await window();
+                if ("stop" in outcome)
+                    return outcome.stop;
+                measure = { result: outcome.result };
+            }
+            this.lastPerf = measure;
+            if (this.recording !== null && !this.replaying) {
+                this.recording.steps.push({
+                    method: "performance",
+                    params: {
+                        ...(args.launch === true ? { launch: true } : {}),
+                        ...(args.seconds !== undefined ? { seconds: args.seconds } : {}),
+                        ...(args.tap !== undefined ? { tap: args.tap } : {}),
+                    },
+                });
+            }
+            const tapWords = args.tap === undefined ? undefined : targetWords(args.tap);
+            return text([perfFirstLine(measure, tapWords), ...formatPerfLines(measure.result), ...this.takePersonNote()].join("\n"));
+        }
+        catch (error) {
+            return fail(describeError(error));
+        }
+    }
     async wait(args) {
         const session = this.host.current();
         if (session === undefined)