tapline-host 1.0.0 → 1.2.0

package/dist/tools.js

@@ -1,24 +1,31 @@
-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 { 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 { composeFilmstrip, diffImages, imageSize } from "./images.js";
 import { alertNotes, describeElement, formatChanges, formatElement, formatLogs, formatOffScreenAfterList, formatTree } from "./format.js";
+import { formatInspect, inspectResultSchema } from "./inspect.js";
+import { AUDIT_TYPES, auditResultSchema, auditTitle, formatAudit } from "./audit.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 { PAIR_CODE_TTL_MS, forgetLink, pairingLink } from "./pairing.js";
 import { elementSchema, logEntrySchema, screenshotResultSchema, treeResultSchema, } from "./protocol.js";
 import { TaplineError } from "./server.js";
 // ---- input schemas ----------------------------------------------------------
 export const targetSchema = z
     .object({
-    ref: z.string().optional().describe('Element ref from your latest list, e.g. "e12"'),
-    id: z.string().optional().describe("Exact identifier (React Native testID, the iOS accessibility identifier)"),
-    label: z.string().optional().describe("Accessibility label, exact, ignoring case"),
-    text: z.string().optional().describe("Visible text: an exact match first (ignoring case), then a substring"),
-    index: z.number().int().min(0).optional().describe("With id, label or text: pick the Nth match (0-based, reading order)"),
-    x: z.number().optional().describe("X in points; use together with y"),
-    y: z.number().optional().describe("Y in points; use together with x"),
+    ref: z.string().optional().describe('From your latest list, e.g. "e12"'),
+    id: z.string().optional().describe("The testID, exact"),
+    label: z.string().optional().describe("Accessibility label, exact"),
+    text: z.string().optional().describe("Visible text: exact first, then part"),
+    index: z.number().int().min(0).optional().describe("The Nth match of id, label or text (0-based)"),
+    x: z.number().optional().describe("Points, with y"),
+    y: z.number().optional().describe("Points, with x"),
 })
     .strict()
     .superRefine((value, ctx) => {
@@ -40,22 +47,38 @@ export const targetSchema = z
         ctx.addIssue({ code: "custom", message: "index works with id, label or text." });
     }
 });
-const targetField = targetSchema.describe("Which element: exactly one of {ref}, {id}, {label}, {text} or {x, y}; add index to pick among several id, label or text matches. Prefer ref or id from your latest list.");
+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()
     .optional()
-    .describe("Set false to answer only the first line, with no change list. Call look when you need the screen.");
-const screenshotField = z.boolean().optional().describe("Add a screenshot to the answer (default false)");
+    .describe("false: only the first line; the next answer's changes then cover this action too");
+const screenshotField = z.boolean().optional().describe("Add a screenshot (default false)");
+const dryRunField = z
+    .boolean()
+    .optional()
+    .describe("true: run every check and say what would happen; touch nothing");
+/** `index` written beside `target` rather than in it: agents do that, and it means the same. */
+const indexField = z.number().int().min(0).optional().describe("Same as target.index");
 const forceField = z
     .boolean()
     .optional()
-    .describe("Skip the off-screen, covered, under-the-tab-bar and behind-an-alert checks (never disabled). Default false; prefer scrolling or dismissing what covers it, since a person would have to.");
+    .describe("Skip the reach checks (never disabled), only when you've decided a refusal is wrong");
 export const toolShapes = {
     apps: {},
     open_app: { app: z.string().describe("The app's session id, app id or name, as apps lists them") },
     pair: {
         scheme: z
             .string()
+            .optional()
             .describe('The app\'s URL scheme ("scheme" in app.json or app.config), e.g. "myapp"; for an app running in Expo Go, the address Expo prints, e.g. "exp://192.168.1.20:8081"'),
     },
     look: {
@@ -73,9 +96,17 @@ export const toolShapes = {
             .describe("Draw each actionable element's box and ref (e12) on the screenshot, so whoever views it can name elements by ref"),
     },
     check_layout: {},
-    tap: { target: targetField, force: forceField, look: lookField, screenshot: screenshotField },
+    audit: {
+        types: z
+            .array(z.enum(AUDIT_TYPES))
+            .optional()
+            .describe("Which checks to run (default all): contrast, hit_region, description, dynamic_type, clipped_text, trait, element_detection, overlap, duplicate_id"),
+    },
+    inspect: { target: targetField },
+    tap: { target: targetField, index: indexField, force: forceField, dry_run: dryRunField, look: lookField, screenshot: screenshotField },
     long_press: {
         target: targetField,
+        index: indexField,
         seconds: z
             .number()
             .min(0.1)
@@ -83,15 +114,18 @@ export const toolShapes = {
             .optional()
             .describe("How long to hold (default 1.0). Tapline calls the handler, so it doesn't wait"),
         force: forceField,
+        dry_run: dryRunField,
         look: lookField,
         screenshot: screenshotField,
     },
     type_text: {
         text: z.string().describe("Text to enter"),
         target: targetField.optional().describe("Input to type into; default: the focused input, else the only input on screen (else ambiguous; none at all is not_found)"),
+        index: indexField,
         replace: z.boolean().optional().describe("Replace the current text (default true); false appends"),
         submit: z.boolean().optional().describe("Also submit (like pressing return) after typing (default false)"),
         force: forceField,
+        dry_run: dryRunField,
         look: lookField,
         screenshot: screenshotField,
     },
@@ -105,13 +139,16 @@ export const toolShapes = {
         target: targetField
             .optional()
             .describe('Scroll view to scroll, or an element inside it; default: the largest one on screen. With to: "target", the element to bring onto the screen'),
+        dry_run: dryRunField,
         look: lookField,
         screenshot: screenshotField,
     },
     toggle: {
         target: targetField,
+        index: indexField,
         value: z.boolean().optional().describe("Desired state; omit to flip"),
         force: forceField,
+        dry_run: dryRunField,
         look: lookField,
         screenshot: screenshotField,
     },
@@ -120,13 +157,14 @@ export const toolShapes = {
         look: lookField,
         screenshot: screenshotField,
     },
-    back: { look: lookField, screenshot: screenshotField },
+    back: { dry_run: dryRunField, look: lookField, screenshot: screenshotField },
     swipe: {
         x0: z.number().describe("Where the finger starts, in points from the left"),
         y0: z.number().describe("Where the finger starts, in points from the top"),
         x1: z.number().describe("Where it lifts, in points from the left"),
         y1: z.number().describe("Where it lifts, in points from the top"),
         seconds: z.number().min(0.05).max(5).optional().describe("How long the drag takes (default 0.35)"),
+        dry_run: dryRunField,
         look: lookField,
         screenshot: screenshotField,
     },
@@ -146,6 +184,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)"),
@@ -155,13 +203,20 @@ export const toolShapes = {
     },
     viewer: {},
     record: {
+        start: z.boolean().optional().describe("Start recording: every action that succeeds from now on becomes a step"),
+        stop: z.boolean().optional().describe("Stop and save the script (to path, else to the scripts folder under name)"),
+        name: z.string().optional().describe("The script's name: letters, digits, '.', '_' and '-'"),
+        path: z.string().optional().describe("Where stop saves the script file (optional)"),
         action: z
             .enum(["start", "stop", "status", "discard"])
-            .describe("start a recording (needs name), stop and save it, see the status, or discard it"),
-        name: z.string().optional().describe("Script name for start: letters, digits, '.', '_' and '-'"),
+            .optional()
+            .describe("Older form: start, stop, status or discard"),
     },
     replay: {
-        name: z.string().optional().describe("The script to replay; omit to list saved scripts"),
+        name: z.string().optional().describe("A saved script's name; omit name and path to list saved scripts"),
+        path: z.string().optional().describe("A script file to replay (the shared agent-tools-script format)"),
+        look: lookField,
+        screenshot: screenshotField,
     },
     wait_for: {
         text: z.string().optional().describe("Wait until this visible text is on screen (or gone)"),
@@ -178,7 +233,93 @@ export const toolShapes = {
     },
     reload: { look: lookField },
     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, compare_screen (checks, never saves). 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.'),
+        trace: z.boolean().optional().describe("Also list each step that ran, one line each"),
+        dry_run: z
+            .boolean()
+            .optional()
+            .describe("Check every step's parameters and resolve step 1 (later steps depend on what it does), then touch nothing"),
+        look: lookField,
+        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)
@@ -188,6 +329,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(),
@@ -341,6 +484,10 @@ function text(message) {
 function fail(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
+/** The target with an `index` that was written beside it moved inside (its own index wins). */
+function withIndex(target, index) {
+    return index !== undefined && target.index === undefined ? { ...target, index } : target;
+}
 function toWireTarget(target) {
     const withIndex = (t) => target.index !== undefined ? { ...t, index: target.index } : t;
     if (target.ref !== undefined)
@@ -421,12 +568,75 @@ export function describeError(error) {
     }
     return `Error internal: ${error instanceof Error ? error.message : String(error)}`;
 }
+/** Ends a guarded call inside the agent's turn with the policy's answer (nothing was touched). */
+class PolicyStop extends Error {
+    answer;
+    constructor(answer) {
+        super("stopped by the policy");
+        this.answer = answer;
+    }
+}
+/** Adds a note line to the end of an answer's first text block. */
+function appendNote(answer, note) {
+    const [top, ...rest] = answer.content;
+    if (top === undefined || top.type !== "text")
+        return answer;
+    return { ...answer, content: [{ type: "text", text: [top.text.trimEnd(), note].join("\n") }, ...rest] };
+}
+/** An app's dry-run answer (AGENT-TOOLS 1.8 §11.4). */
+const dryRunResultSchema = z.object({
+    element: elementSchema.nullish(),
+    dryRun: z.literal(true),
+    point: z.object({ x: z.number(), y: z.number() }).optional(),
+    value: z.unknown().optional(),
+});
+/** For an app without dry runs: every element on its list the target could mean. */
+function candidatesFor(target, elements) {
+    if (typeof target !== "object" || target === null)
+        return [];
+    const t = target;
+    const lower = (value) => (typeof value === "string" ? value.toLowerCase() : "");
+    const x = t["x"];
+    const y = t["y"];
+    let found;
+    if (typeof t["ref"] === "string")
+        found = elements.filter((e) => e.ref === t["ref"]);
+    else if (typeof t["testID"] === "string")
+        found = elements.filter((e) => e.testID === t["testID"]);
+    else if (typeof t["label"] === "string")
+        found = elements.filter((e) => lower(e.label) === lower(t["label"]));
+    else if (typeof t["text"] === "string") {
+        const want = lower(t["text"]);
+        found = elements.filter((e) => lower(e.text).includes(want) || lower(e.label).includes(want));
+    }
+    else if (typeof x === "number" && typeof y === "number") {
+        found = elements.filter((e) => {
+            const f = e.frame;
+            return f !== null && f !== undefined && x >= f.x && x <= f.x + f.width && y >= f.y && y <= f.y + f.height;
+        });
+    }
+    else
+        found = [];
+    const index = t["index"];
+    const picked = typeof index === "number" ? found[index] : undefined;
+    return picked !== undefined ? [picked] : found;
+}
 // ---- tool handlers ----------------------------------------------------------
 /** The tool handlers behind the MCP server. They only talk to a TaplineHost, so they are easy to test. */
 export class TaplineTools {
     host;
     options;
     reloadWaitMs;
+    /** The action log (§12), when one is configured. */
+    actionLog;
+    /** When the action in flight started, for the log's `ms`. */
+    actionStartedAt;
+    /** Set while `run` runs a step: the log ties the action to its batch. */
+    batch;
+    /** Extra fields for the next log line (a dry run, a confirmed touch). */
+    logExtra;
+    confirmations;
+    policy;
     reloadSettleMs;
     noScreenshot = new Set();
     shotFiles = [];
@@ -444,6 +654,15 @@ 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;
+    /** 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;
@@ -452,6 +671,10 @@ export class TaplineTools {
         this.host = host;
         this.options = options;
         this.reloadWaitMs = options.reloadWaitMs ?? 20_000;
+        this.confirmations = options.confirmations ?? new Confirmations();
+        this.policy = options.policy ?? DEFAULT_POLICY;
+        this.actionLog = options.logDir !== undefined ? new ActionLog(options.logDir) : null;
+        this.actionLog?.open();
         this.reloadSettleMs = options.reloadSettleMs ?? 1500;
         // A finger on the phone itself: the app saw a real touch. It can't be queued like viewer input
         // (it has already happened), so it only leaves the note and makes `{ref}` targets stale.
@@ -490,15 +713,17 @@ export class TaplineTools {
             const silent = this.silentDropMessage();
             lines.push(silent !== undefined
                 ? silent
-                : state === "background" || state === "inactive"
-                    ? `${last.session.app.name} disconnected at ${when} after it went to the background (the user switched apps or locked the phone, and iOS paused it). Ask the user to open the app again: it reconnects by itself.`
-                    : `${last.session.app.name} disconnected at ${when} (${last.reason}). If the app is still open, it reconnects by itself.`);
+                : state === "inactive"
+                    ? `${last.session.app.name} disconnected at ${when} after iOS put something in front of it (a system prompt such as a password request, a call, or Control Center). Tapline can't see or answer it: ask the user to deal with it on the phone. The app reconnects by itself.`
+                    : state === "background"
+                        ? `${last.session.app.name} disconnected at ${when} after it went to the background (the user switched apps or locked the phone, and iOS paused it). Ask the user to open the app again: it reconnects by itself.`
+                        : `${last.session.app.name} disconnected at ${when} (${last.reason}). If the app is still open, it reconnects by itself.`);
         }
         return [
             "No app is connected to Tapline.",
             ...lines,
             `This host listens at ${url} on ${name}.`,
-            'To connect a phone, call `pair` with the app\'s URL scheme ("scheme" in app.json, e.g. "myapp") and show the user the QR code. They scan it with the phone\'s camera and tap Connect in the app.',
+            'To connect a phone, call `pair`. A development build loading its code from this computer then asks by itself: the user taps Connect. Other builds: pass the app\'s URL scheme ("scheme" in app.json, e.g. "myapp") and show the user the QR code to scan.',
             "The phone needs to be on the same Wi-Fi as this computer, and the app must be a build with Tapline turned on, open in the foreground.",
             "A phone that paired with this host before reconnects by itself while the app is open; one paired with a host on another port (e.g. before a restart) needs `pair` again. Once it connects, retry.",
         ].join("\n");
@@ -506,6 +731,19 @@ export class TaplineTools {
     // -- pair
     async pair(args) {
         const { url, name } = this.options.connect;
+        // Zero-QR pairing (Tapline 1.1): a development build whose JavaScript comes from this computer finds the
+        // offer itself and asks its person to connect. Open for 10 minutes, one use, local network only.
+        const offer = this.host.openDevOffer(name);
+        this.writeOffer(offer);
+        const devLine = "A development build that loads its JavaScript from this computer (Metro) on the same Wi-Fi asks by itself within a few seconds: the user only taps Connect, no QR code (open for 10 minutes, once).";
+        if (args.scheme === undefined || args.scheme.trim() === "") {
+            return text([
+                `Pairing is open for development builds for 10 minutes (${name}).`,
+                devLine,
+                "Ask the user to open the app on the phone and tap Connect, then call `apps`.",
+                "For a TestFlight or release build, call pair again with the app's URL scheme to get a QR code.",
+            ].join("\n"));
+        }
         let link;
         let forget;
         try {
@@ -540,6 +778,7 @@ export class TaplineTools {
             "",
             `Show the user the QR code (attached).${saved} They scan it with the phone's camera, open the app and tap Connect.`,
             "The phone needs to be on the same Wi-Fi as this computer, and the app must be a build with Tapline turned on.",
+            devLine,
             "Once paired, the app reconnects to this host (this address and port) by itself whenever it is open; call `apps` to check.",
             `To unpair the phone, open ${forget} on it.`,
         ];
@@ -550,6 +789,51 @@ export class TaplineTools {
             ],
         };
     }
+    /** `<offerDir>/<port>.json` (0600): the open offer for the Metro helper. Never fails the pair call. */
+    writeOffer(offer) {
+        const dir = this.options.offerDir;
+        const port = this.host.boundPort();
+        if (dir === undefined || port === undefined)
+            return;
+        try {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            const file = join(dir, `${port}.json`);
+            writeFileSync(file, JSON.stringify({ code: offer.code, name: offer.name, port, until: offer.until }), { mode: 0o600 });
+            this.host.setDevOfferFile(file);
+            const remove = () => {
+                try {
+                    // only our own offer: a newer pair call has written its own
+                    if (existsSync(file) && readFileSync(file, "utf8").includes(offer.code))
+                        rmSync(file, { force: true });
+                }
+                catch {
+                    // gone already
+                }
+            };
+            // Used: the code works once, so Metro stops handing it out at once.
+            const onConnect = () => {
+                if (this.host.currentDevOffer()?.code === offer.code)
+                    return;
+                this.host.off("connect", onConnect);
+                remove();
+            };
+            this.host.on("connect", onConnect);
+            setTimeout(() => {
+                this.host.off("connect", onConnect);
+                try {
+                    // only our own offer: a newer pair call has written its own
+                    if (existsSync(file) && readFileSync(file, "utf8").includes(offer.code))
+                        rmSync(file, { force: true });
+                }
+                catch {
+                    // gone already
+                }
+            }, Math.max(0, offer.until - Date.now())).unref();
+        }
+        catch {
+            // the host's own endpoint still has it
+        }
+    }
     // -- apps
     apps() {
         const sessions = this.host.sessions();
@@ -602,6 +886,258 @@ export class TaplineTools {
         const parts = await this.lookParts(session, args.screenshot ?? true, args.width ?? DEFAULT_SCREENSHOT_WIDTH, false, args.labels === true);
         return { content: parts.content, ...(parts.isError ? { isError: true } : {}) };
     }
+    // -- run (AGENT-TOOLS 1.8 §9): a batch of steps, answered once
+    async run(args) {
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        const steps = args.steps;
+        for (const [i, step] of steps.entries()) {
+            if (!RUN_TOOLS.includes(step.tool)) {
+                return fail(`Error bad_params: step ${i + 1}: "${step.tool}" can't be a step (steps act; use it on its own call). Steps can be: ${RUN_TOOLS.join(", ")}.`);
+            }
+            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 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;
+        const started = Date.now();
+        const batchId = `b${started.toString(36)}`;
+        const notes = [];
+        const trace = [];
+        let ran = 0;
+        let stop = null;
+        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();
+            this.batch = { id: batchId, step: i + 1 };
+            const answer = await this.runStep(step).finally(() => {
+                this.batch = undefined;
+            });
+            const said = answer.content.map((block) => (block.type === "text" ? block.text : "")).join("\n").trim();
+            if (answer.isError === true) {
+                stop = { index: i, ...parseError(said) };
+                break;
+            }
+            notes.push(...stepNotes(said, i + 1));
+            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")) {
+                const now = await this.currentRoute();
+                if (now !== null && now.join(" \u203a ") !== route.join(" \u203a ")) {
+                    stop = { index: i, code: "expect_failed", message: `its action ran, but it ended on ${now.join(" \u203a ")}; the recording ended on ${route.join(" \u203a ")}`, rest: [] };
+                    break;
+                }
+            }
+            ran++;
+            if (args.trace === true)
+                trace.push(`  ${i + 1}. ${said.split("\n")[0] ?? ""} (${((Date.now() - at) / 1000).toFixed(1)} s)`);
+        }
+        // The batch is one call: the changes below are measured from the list the agent had before it.
+        if (before > 0)
+            this.unlistedActions.set(session.id, before);
+        else
+            this.unlistedActions.delete(session.id);
+        const total = steps.length;
+        const failed = stop !== null;
+        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 diffNote = stop !== null && this.diffSaved !== null ? [`Note: the difference is saved at ${this.diffSaved}.`] : [];
+        const first = [head, ...trace, ...(stop?.rest ?? []), ...diffNote].join("\n");
+        let response;
+        const live = this.host.current();
+        if (args.look === false || live === undefined) {
+            response = text([first, ...notes].join("\n"));
+        }
+        else {
+            response = await this.withLook(live, first, args.screenshot === true);
+            if (notes.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] };
+            }
+        }
+        return failed ? { ...response, isError: true } : response;
+    }
+    /** `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 });
+            const said = answer.content.map((block) => (block.type === "text" ? block.text : "")).join("\n").trim();
+            const [line, ...rest] = said.split("\n");
+            if (answer.isError === true) {
+                const { code, message } = parseError(said);
+                return fail(`Error ${code}: ${head}; step 1 (${describeRunStep(first)}) would fail: ${message}`);
+            }
+            const would = (line ?? "").replace(/^Would /, "would ");
+            return text([`${head}; step 1 ${would}`, ...rest].join("\n"));
+        }
+        return text(`${head}; step 1 would ${describeRunStep(first)}.`);
+    }
+    /** One step of `run`, as its own tool call without a list. */
+    runStep(step) {
+        const { tool, expect: _expect, route: _route, ...rest } = step;
+        const quiet = { ...rest, look: false, screenshot: false };
+        switch (tool) {
+            case "tap":
+                return this.tap(quiet);
+            case "long_press":
+                return this.longPress(quiet);
+            case "type_text":
+                return this.typeText(quiet);
+            case "scroll":
+                return this.scroll(quiet);
+            case "toggle":
+                return this.toggle(quiet);
+            case "back":
+                return this.back(quiet);
+            case "swipe":
+                return this.swipe(quiet);
+            case "open_url":
+                return this.openUrl(quiet);
+            case "wait":
+                return this.wait({ seconds: Number(rest.seconds ?? 0) });
+            case "wait_for":
+                return this.waitFor(quiet);
+            case "app_command":
+                return this.appCommand(quiet);
+            case "compare_screen":
+                return this.compareStep(rest);
+        }
+    }
+    /** The screen's route names now (one cheap read), or null when the app has no router or didn't answer. */
+    async currentRoute() {
+        const session = this.host.current();
+        if (session === undefined)
+            return null;
+        const tree = treeResultSchema.safeParse(await this.host.request("tree", { peek: true }, { sessionId: session.id }).catch(() => null));
+        return tree.success && tree.data.route !== undefined ? tree.data.route.names : null;
+    }
+    /** 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 });
+        if (seen.isError === true)
+            return expectFailure(e, seconds);
+        if (e.value === undefined || e.gone === true)
+            return null;
+        // The element is there: wait for its value (a switch reads "on" or "off").
+        const session = this.host.current();
+        if (session === undefined)
+            return expectFailure(e, seconds);
+        const until = Date.now() + seconds * 1000;
+        let actual;
+        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 : 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;
+                // A switch takes "true" and "false" too (it reads checked=true in the list).
+                const wanted = typeof element.checked === "boolean" && (e.value === "true" || e.value === "false") ? (e.value === "true" ? "on" : "off") : e.value;
+                if (actual === wanted)
+                    return null;
+            }
+            if (Date.now() >= until)
+                return expectFailure(e, seconds, actual);
+            await sleep(100);
+        }
+    }
+    // -- inspect (Tapline 1.1): from the screen to the code
+    async inspect(args) {
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        let raw;
+        try {
+            raw = await this.host.request("inspect", { target: toWireTarget(args.target) }, { sessionId: session.id });
+        }
+        catch (error) {
+            return fail(describeError(error));
+        }
+        const parsed = inspectResultSchema.safeParse(raw);
+        if (!parsed.success)
+            return fail("Error internal: the app returned an inspect answer the host could not read.");
+        return text(formatInspect(parsed.data));
+    }
+    // -- audit (AGENT-TOOLS 1.8 §10)
+    async audit(args = {}) {
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        if (!session.capabilities.includes("audit")) {
+            return fail("Error unsupported: this app's Tapline is too old for audit; update react-native-tapline (check_layout works meanwhile).");
+        }
+        let raw;
+        try {
+            raw = await this.host.request("audit", args.types !== undefined ? { types: args.types } : {}, { sessionId: session.id });
+        }
+        catch (error) {
+            return fail(describeError(error));
+        }
+        const parsed = auditResultSchema.safeParse(raw);
+        if (!parsed.success)
+            return fail("Error internal: the app returned an audit the host could not read.");
+        const title = auditTitle(await this.currentRoute(), session.app.name);
+        return text([formatAudit(title, parsed.data, args.types), ...this.takePersonNote()].join("\n"));
+    }
     // -- check_layout
     async checkLayout(_args = {}) {
         const session = this.host.current();
@@ -754,32 +1290,42 @@ export class TaplineTools {
     /** Runs a request, then (unless disabled) appends the fresh element list and how long the app took to settle. */
     async act(method, params, describe, withLook, screenshot, extraNotes, 
     /** True when the result means nothing was done: the first line is then the whole answer. */
-    nothingDone) {
+    nothingDone, 
+    /** Runs inside the agent's turn, right before the request: an answer stops the call there (the policy). */
+    preflight) {
         const session = this.host.current();
         if (session === undefined)
             return this.notConnected();
-        if (this.personActed) {
-            const target = typeof params === "object" && params !== null ? params.target : undefined;
-            if (typeof target === "object" && target !== null && "ref" in target) {
-                // The error says it already, so the note isn't repeated.
-                this.personNotePending = false;
-                return fail("Error stale: a person used the app since your last look, so refs from that list may point elsewhere. Look again, or target by id, label or text.");
-            }
-        }
+        const stale = this.staleRef(params);
+        if (stale !== null)
+            return stale;
         let result;
+        this.actionStartedAt = Date.now();
         try {
             const timeoutMs = answerTimeoutMs(method, params);
-            const run = () => this.host.request(method, params, { sessionId: session.id, ...(timeoutMs !== undefined ? { timeoutMs } : {}) });
+            const run = async () => {
+                if (preflight !== undefined) {
+                    const stop = await preflight();
+                    if (stop !== null)
+                        throw new PolicyStop(stop);
+                }
+                return this.host.request(method, params, { sessionId: session.id, ...(timeoutMs !== undefined ? { timeoutMs } : {}) });
+            };
             // With the live viewer, a person watching goes first.
             result = this.options.control ? await this.options.control.runAgent(run) : await run();
         }
         catch (error) {
+            if (error instanceof PolicyStop)
+                return error.answer;
+            this.logExtra = undefined;
             this.showAction("agent", method, undefined, params, error instanceof TaplineError ? error.code : "internal", error instanceof TaplineError ? reasonOf(error.code, error.message) : undefined);
             return fail(describeError(error));
         }
         const line = describe(result);
-        if (nothingDone?.(result) === true)
+        if (nothingDone?.(result) === true) {
+            this.logExtra = undefined;
             return text([line, ...this.takePersonNote()].join("\n"));
+        }
         this.showAction("agent", method, result, params);
         let response;
         this.lastLookRoute = undefined;
@@ -826,8 +1372,14 @@ export class TaplineTools {
             }
         }
         if (this.recording !== null && !this.replaying) {
-            const { params: stable, fragile } = stableParams(params, result);
-            const step = { method, params: stable };
+            const { params: chosen, fragile } = stableParams(params, result);
+            // A ref saved as a label or text that several elements share needs its index (AGENT-TOOLS 1.8 §9.4).
+            const stable = await this.withIndexIfShared(params, chosen, result, session.id);
+            // A password field's text is never saved in a script (Tapwright's review, M4).
+            const secret = method === "type" && typeof result === "object" && result !== null && "secure" in result && result.secure === true;
+            const step = { method, params: secret ? { ...stable, text: "" } : stable };
+            if (secret)
+                step.secret = true;
             if (this.lastLookRoute !== undefined)
                 step.route = this.lastLookRoute;
             if (fragile)
@@ -836,6 +1388,39 @@ export class TaplineTools {
         }
         return response;
     }
+    /**
+     * When the agent's ref was saved as a testID, label or text that more than one element on screen has, add
+     * the element's `index` among them (reading order), so the replay picks the same one instead of
+     * answering `ambiguous`. One extra read, only while recording and only for ref targets.
+     */
+    async withIndexIfShared(original, chosen, result, sessionId) {
+        const before = typeof original === "object" && original !== null ? original.target : undefined;
+        const target = chosen["target"];
+        if (typeof before !== "object" || before === null || !("ref" in before))
+            return chosen;
+        if (typeof target !== "object" || target === null || "ref" in target || "index" in target)
+            return chosen;
+        const element = typeof result === "object" && result !== null && "element" in result
+            ? elementSchema.safeParse(result.element)
+            : null;
+        if (!element?.success)
+            return chosen;
+        const tree = treeResultSchema.safeParse(await this.host.request("tree", { peek: true }, { sessionId }).catch(() => null));
+        if (!tree.success)
+            return chosen;
+        const t = target;
+        const same = tree.data.elements.filter((el) => typeof t.testID === "string"
+            ? el.testID === t.testID
+            : typeof t.label === "string"
+                ? labelOfElement(el).toLowerCase() === t.label.toLowerCase()
+                : typeof t.text === "string"
+                    ? el.text === t.text
+                    : false);
+        if (same.length < 2)
+            return chosen;
+        const at = same.findIndex((el) => el.ref === element.data.ref);
+        return at < 0 ? chosen : { ...chosen, target: { ...target, index: at } };
+    }
     // -- the live viewer
     /** An element's frame (points) as 0..1 of the screen. */
     normalized(frame) {
@@ -859,15 +1444,43 @@ export class TaplineTools {
             ...(point ? { point } : {}),
         };
     }
+    /** One line in the action log (§12). Never fails the action. */
+    logAction(by, tool, params, result, code, reason) {
+        if (this.actionLog === null)
+            return;
+        const element = typeof result === "object" && result !== null && "element" in result
+            ? elementSchema.safeParse(result.element)
+            : null;
+        const session = this.host.current();
+        this.actionLog.write({
+            by,
+            tool,
+            ...loggedTarget(params),
+            // typed text never reaches the log, not even as the field's value (§12)
+            ...(element?.success ? { element: formatElement({ ...element.data, ref: "", value: null, placeholder: null }, { actions: false }) } : {}),
+            ok: code === undefined,
+            ...(code !== undefined ? { code } : {}),
+            ...(reason !== undefined ? { reason } : {}),
+            ...(by === "agent" && this.actionStartedAt !== undefined ? { ms: Date.now() - this.actionStartedAt } : {}),
+            ...(session !== undefined ? { app: session.app.id ?? session.app.name } : {}),
+            ...(by === "agent" && this.batch !== undefined ? { batch: this.batch } : {}),
+            ...(by === "agent" ? (this.logExtra ?? {}) : {}),
+        });
+        if (by === "agent")
+            this.logExtra = undefined;
+    }
     showAction(by, method, result, params, code, reason) {
         const onAction = this.options.onAction;
-        if (onAction === undefined)
+        if (onAction === undefined) {
+            this.logAction(by, by === "agent" ? agentKind(method) : method, params, result, code, reason);
             return;
+        }
         const target = typeof params === "object" && params !== null ? params.target : undefined;
         const t = typeof target === "object" && target !== null ? target : undefined;
         const screen = this.lastScreen;
         const point = t && typeof t.x === "number" && typeof t.y === "number" && screen ? { x: t.x / screen.w, y: t.y / screen.h } : undefined;
         const kind = by === "agent" ? agentKind(method) : method;
+        this.logAction(by, kind, params, result, code, reason);
         const described = this.describeAction(kind, result, point);
         // A failed step has no element in its answer: name it from the target the agent gave, if it's words.
         const named = described.label ??
@@ -968,7 +1581,10 @@ export class TaplineTools {
             }
         };
         try {
-            return this.options.control ? await this.options.control.runPerson(run) : await run();
+            const outcome = this.options.control ? await this.options.control.runPerson(run) : await run();
+            // The log (§12): a person's input too, its typed text only as a length.
+            this.logAction("person", outcome.action?.kind ?? input.type, input.type === "text" ? { text: input.text } : {}, undefined, outcome.ok ? undefined : outcome.code, outcome.reason);
+            return outcome;
         }
         catch (error) {
             return { ok: false, code: "internal", message: error instanceof Error ? error.message : String(error) };
@@ -1015,11 +1631,28 @@ export class TaplineTools {
         const links = this.options.viewerLinks?.() ?? [];
         if (links.length === 0)
             return fail("Error unsupported: this host has no live viewer.");
-        const lines = [
-            "Live viewer (watch the app, see what you do, and let the user tap and type too):",
-            ...links.map((link) => `- ${link}`),
-            "The link carries a key: give it to the user only. While they use the viewer, their touches go first and your actions wait.",
-        ];
+        const open = this.options.openViewer;
+        const local = links[0];
+        let lines;
+        if (open !== undefined && this.options.viewerLinkToAgent !== true && local !== undefined) {
+            // The key in the link can approve a held-back touch: it goes to the browser, never to the agent.
+            const opened = open(local);
+            lines = [
+                opened
+                    ? "Opened the live view in a browser on this computer: the user watches the app and what you do there, and can tap and type too."
+                    : "Couldn't open a browser on this computer. Ask the user to start the MCP server with --viewer-link if they want the link.",
+                "The link isn't shown to you: its key can approve touches that need a person's OK.",
+                ...(links.length > 1 ? ["For their own devices on Tailscale, the user finds that link in this server's log."] : []),
+                "While the user acts in the live view, their touches go first and your actions wait.",
+            ];
+        }
+        else {
+            lines = [
+                "Live viewer (watch the app, see what you do, and let the user tap and type too):",
+                ...links.map((link) => `- ${link}`),
+                "The link carries a key: give it to the user only. While they use the viewer, their touches go first and your actions wait.",
+            ];
+        }
         const feed = this.options.viewerFeed?.();
         const session = this.host.current();
         if (feed?.on === true && session !== undefined) {
@@ -1064,66 +1697,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));
+            return { kind: "error", line: 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.`);
-        }
-        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) }))
@@ -1131,12 +1797,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();
@@ -1151,8 +2094,13 @@ export class TaplineTools {
             const started = Date.now();
             if (args.tap !== undefined) {
                 // 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", { target: toWireTarget(args.tap) }, { sessionId: session.id });
+                await this.host.request("press", pressParams, { sessionId: session.id });
             }
             for (let i = frames.length; i < count; i++) {
                 const at = Date.now();
@@ -1178,9 +2126,10 @@ export class TaplineTools {
         return dir === undefined || !SCRIPT_NAME.test(name) ? null : join(dir, `${name}.json`);
     }
     async record(args) {
-        switch (args.action) {
+        const op = args.action ?? (args.start === true ? "start" : args.stop === true ? "stop" : "status");
+        switch (op) {
             case "start": {
-                const name = (args.name ?? "").trim();
+                const name = (args.name ?? "").trim() || `session-${new Date().toISOString().slice(0, 19).replace(/[-:T]/g, "")}`;
                 if (this.scriptPath(name) === null) {
                     return fail("Error bad_params: give the script a name of letters, digits, '.', '_' and '-' (e.g. \"checkout\").");
                 }
@@ -1190,7 +2139,7 @@ export class TaplineTools {
                 if (session === undefined)
                     return this.notConnected();
                 this.recording = { name, app: { name: session.app.name, ...(session.app.id ? { id: session.app.id } : {}) }, steps: [] };
-                return text(`Recording "${name}" on ${session.app.name}. Every action from now on is a step; wait_for steps check the app is where it should be. Prefer testIDs: they replay best. Stop with record { action: "stop" }.`);
+                return text(`Recording "${name}" on ${session.app.name}. Every action from now on is a step; wait_for steps check the app is where it should be. Prefer testIDs: they replay best. Stop with record { stop: true }.`);
             }
             case "status":
                 return text(this.recording === null
@@ -1204,16 +2153,17 @@ export class TaplineTools {
             case "stop": {
                 const recording = this.recording;
                 if (recording === null)
-                    return fail("Error bad_params: not recording; start with record { action: \"start\", name }.");
-                const path = this.scriptPath(recording.name);
+                    return fail("Error bad_params: not recording; start with record { start: true, name }.");
+                const path = args.path !== undefined && args.path.trim() !== "" ? args.path.trim() : this.scriptPath(recording.name);
                 if (path === null)
-                    return fail("Error internal: no scripts folder is configured.");
+                    return fail("Error internal: no scripts folder is configured; give a path.");
                 const script = {
+                    format: "agent-tools-script",
                     version: 1,
                     name: recording.name,
-                    app: recording.app,
-                    recordedAt: new Date().toISOString(),
-                    steps: recording.steps,
+                    app: recording.app.id ?? recording.app.name,
+                    fresh: true,
+                    steps: scriptSteps(recording.steps),
                 };
                 try {
                     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
@@ -1224,20 +2174,60 @@ export class TaplineTools {
                 }
                 this.recording = null;
                 const count = script.steps.length;
-                const lines = [`Saved "${script.name}": ${count} step${count === 1 ? "" : "s"} in ${path}. Replay it with replay { name: "${script.name}" }.`];
-                script.steps.forEach((step, i) => {
-                    if (step.fragile) {
-                        const target = step.params["target"];
-                        lines.push(`Note: step ${i + 1} targets ref ${String(target.ref)}, which won't exist on a new run. Give that element a testID, or record it again by its text or label.`);
-                    }
-                });
-                if (script.steps.some((step) => step.method === "type")) {
-                    lines.push("The script keeps the text typed in it (test passwords too): keep it private.");
+                // 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.`);
+                }
+                const secrets = recording.steps.filter((step) => step.secret === true).length;
+                if (secrets > 0) {
+                    lines.push(`${secrets} step${secrets === 1 ? " types" : "s type"} into a password field: that text isn't saved. Put a test password into the script before you replay it.`);
+                }
+                if (recording.steps.some((step) => step.method === "type" && step.secret !== true)) {
+                    lines.push("The script keeps the other text typed in it: keep it private.");
                 }
                 return text(lines.join("\n"));
             }
         }
     }
+    /** `<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))
@@ -1245,11 +2235,10 @@ export class TaplineTools {
         const lines = [];
         for (const file of readdirSync(dir).filter((f) => f.endsWith(".json")).sort()) {
             try {
-                const parsed = scriptSchema.safeParse(JSON.parse(readFileSync(join(dir, file), "utf8")));
-                if (!parsed.success)
+                const s = readScript(readFileSync(join(dir, file), "utf8"));
+                if (s === null)
                     continue;
-                const s = parsed.data;
-                lines.push(`- ${s.name} (${s.steps.length} step${s.steps.length === 1 ? "" : "s"}, recorded ${s.recordedAt.slice(0, 10)} on ${s.app.name})`);
+                lines.push(`- ${s.name} (${s.steps.length} step${s.steps.length === 1 ? "" : "s"}${s.app ? `, ${s.app}` : ""})`);
             }
             catch {
                 // skip unreadable files
@@ -1257,66 +2246,68 @@ 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();
-        if (name === "")
+        const given = (args.path ?? "").trim();
+        if (name === "" && given === "")
             return text(this.scriptList());
         if (this.recording !== null)
             return fail(`Error bad_params: stop recording "${this.recording.name}" before replaying.`);
-        const path = this.scriptPath(name);
+        const path = given !== "" ? given : this.scriptPath(name);
         if (path === null || !existsSync(path))
-            return fail(`Error not_found: no script "${name}".\n${this.scriptList()}`);
+            return fail(`Error not_found: no script "${given || name}".\n${this.scriptList()}`);
         let script;
         try {
-            const parsed = scriptSchema.safeParse(JSON.parse(readFileSync(path, "utf8")));
-            if (!parsed.success)
-                return fail(`Error bad_params: ${path} isn't a Tapline script.`);
-            script = parsed.data;
+            script = readScript(readFileSync(path, "utf8"));
         }
         catch (error) {
             return fail(`Error internal: couldn't read ${path}: ${error instanceof Error ? error.message : String(error)}`);
         }
+        if (script === null)
+            return fail(`Error bad_params: ${path} isn't a script (format agent-tools-script, version 1).`);
+        const ref = refStep(script.steps);
+        if (ref !== null)
+            return fail(`Error bad_params: step ${ref + 1} targets a ref; a script needs an id, label, text or point.`);
+        if (script.steps.length === 0)
+            return text(`Ran 0 of 0 steps in 0.0 s.`);
         const session = this.host.current();
         if (session === undefined)
             return this.notConnected();
-        const started = Date.now();
-        const total = script.steps.length;
-        const lines = [];
-        const seconds = (ms) => (Math.round(ms / 100) / 10).toFixed(1);
+        const notes = [];
+        script.steps.forEach((step, i) => {
+            const target = step["target"];
+            if (typeof target === "object" && target !== null && "x" in target) {
+                notes.push(`Note (step ${i + 1}): a point target; it breaks when the layout changes.`);
+            }
+        });
+        if (script.fresh !== false) {
+            // Tapline can't close and open the app: it starts its JavaScript again (a development build).
+            const fresh = await this.reload({});
+            const said = fresh.content.map((block) => (block.type === "text" ? block.text : "")).join("\n");
+            if (fresh.isError === true)
+                notes.push("Note: couldn't start the app fresh (a release build has no reload); the script ran on the screen as it was.");
+            else if (said.startsWith("Reload requested, but"))
+                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 {
-            for (const [i, step] of script.steps.entries()) {
-                const at = Date.now();
-                const label = `${i + 1} ${describeStep(step)}`;
-                if (step.method === "sleep") {
-                    const s = typeof step.params["seconds"] === "number" ? step.params["seconds"] : 0;
-                    await sleep(Math.min(30, Math.max(0, s)) * 1000);
-                    lines.push(`${i + 1} ✓ ${describeStep(step)} (${seconds(Date.now() - at)} s)`);
-                    continue;
-                }
-                const result = await this.act(step.method, step.params, () => "", true);
-                const problem = result.isError
-                    ? result.content.map((block) => (block.type === "text" ? block.text : "")).join("\n").trim()
-                    : step.route !== undefined &&
-                        this.lastLookRoute !== undefined &&
-                        step.route.join(" › ") !== this.lastLookRoute.join(" › ")
-                        ? `It ended on ${this.lastLookRoute.join(" › ")}; the recording ended on ${step.route.join(" › ")}.`
-                        : null;
-                if (problem !== null) {
-                    return fail([
-                        `Replay "${script.name}" failed at step ${i + 1} of ${total}: ${describeStep(step)}`,
-                        problem,
-                        ...(lines.length > 0 ? ["Steps before it passed:", ...lines] : []),
-                        ...(step.fragile ? ["Note: this step targets a ref from the recording run; give the element a testID."] : []),
-                    ].join("\n"));
-                }
-                lines.push(`${label.replace(/^(\d+) /, "$1 ✓ ")} (${seconds(Date.now() - at)} s)`);
-            }
+            const answer = await this.run({ steps: script.steps, look: args.look, screenshot: args.screenshot });
+            if (notes.length === 0)
+                return answer;
+            const [top, ...rest] = answer.content;
+            return top !== undefined && top.type === "text"
+                ? { ...answer, content: [{ type: "text", text: [top.text.trimEnd(), ...notes].join("\n") }, ...rest] }
+                : answer;
         }
         finally {
             this.replaying = false;
+            this.replayContext = null;
         }
-        return text([`Replayed "${script.name}" on ${session.app.name}: ${total} of ${total} steps passed in ${seconds(Date.now() - started)} s.`, ...lines].join("\n"));
     }
     async withLook(session, line, screenshot = false) {
         // The session may have been replaced (app restarted) in the meantime.
@@ -1329,21 +2320,275 @@ export class TaplineTools {
         const head = first !== undefined && first.type === "text" ? first.text : "";
         return { content: [{ type: "text", text: `${line}\n${head}` }, ...rest] };
     }
-    /** The line (without its actions) of the element a result carries under `key`. */
-    elementName(result, key = "element") {
+    /**
+     * The element a result carries under `key`, for an answer's first line: without its actions, position or
+     * size (AGENT-TOOLS 1.8 §13 rule 1; the change block or list has them). `withoutValue` for type_text,
+     * whose sentence says the value (rule 5).
+     */
+    elementName(result, key = "element", withoutValue = false) {
         if (typeof result === "object" && result !== null && key in result) {
             const element = elementSchema.safeParse(result[key]);
-            if (element.success)
-                return formatElement(element.data, { actions: false });
+            if (element.success) {
+                const shown = withoutValue ? { ...element.data, value: null, placeholder: null } : element.data;
+                return formatElement(shown, { actions: false, frame: false });
+            }
         }
         return "element";
     }
+    // -- the safety policy (AGENT-TOOLS 1.8 §11)
+    /**
+     * A guarded touch: the app resolves the target in a dry run, the policy's words are matched against the
+     * element's own label and text, and a confirm word waits for a person's OK in the live view. The check runs
+     * inside the agent's turn, right before the touch, so nothing a person does in between can change what is
+     * touched; when the check can't be made, nothing is touched (fail closed).
+     */
+    async guarded(tool, method, params, dryRun, perform) {
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        this.logExtra = undefined;
+        this.actionStartedAt = Date.now();
+        const lists = listsFor(this.policy, session.app);
+        if (!dryRun && lists.confirm.length === 0 && lists.block.length === 0)
+            return perform();
+        const stale = this.staleRef(params);
+        if (stale !== null)
+            return stale;
+        if (dryRun) {
+            const resolved = await this.resolveForPolicy(session, method, params);
+            this.logExtra = { dry_run: true };
+            if (resolved.kind === "error") {
+                this.showAction("agent", method, undefined, params, resolved.code, resolved.reason);
+                return fail(resolved.text);
+            }
+            const verdict = this.policyWords(lists, resolved.elements);
+            const shown = resolved.elements[0];
+            if (verdict.kind === "blocked") {
+                this.showAction("agent", method, { element: verdict.element }, params, "not_allowed", "blocked");
+                return fail(this.blockedLine(verdict.element, verdict.word));
+            }
+            const would = this.wouldLine(tool, shown, resolved.point, resolved.value);
+            const needs = verdict.kind === "confirm" ? ` It needs a person's OK (policy word ${JSON.stringify(verdict.word)}).` : "";
+            this.showAction("agent", method, shown !== undefined ? { element: shown } : undefined, params);
+            return text([`${would}${needs}`, ...this.takePersonNote()].join("\n"));
+        }
+        let granted = false;
+        const answer = await perform(async () => {
+            const gate = await this.policyGate(session, tool, method, params, lists);
+            if ("stop" in gate)
+                return gate.stop;
+            granted = gate.granted;
+            if (granted)
+                this.logExtra = { confirmed: true };
+            return null;
+        });
+        return granted && answer.isError !== true ? appendNote(answer, "Note: a person allowed this.") : answer;
+    }
+    /**
+     * The policy's verdict on a touch about to happen: stop with an answer (blocked, needs a person's OK, or
+     * the check couldn't be made: fail closed), or go on (`granted` when a person's OK is being used up).
+     */
+    async policyGate(session, tool, method, params, lists) {
+        if (lists.confirm.length === 0 && lists.block.length === 0)
+            return { granted: false };
+        const resolved = await this.resolveForPolicy(session, method, params);
+        if (resolved.kind === "error") {
+            // Fail closed: what can't be checked isn't touched. The answer is the one the touch would give.
+            this.showAction("agent", method, undefined, params, resolved.code, resolved.reason);
+            return { stop: fail(resolved.text) };
+        }
+        const verdict = this.policyWords(lists, resolved.elements);
+        if (verdict.kind === "blocked") {
+            this.showAction("agent", method, { element: verdict.element }, params, "not_allowed", "blocked");
+            return { stop: fail(this.blockedLine(verdict.element, verdict.word)) };
+        }
+        if (verdict.kind === "none")
+            return { granted: false };
+        const label = verdict.element.label ?? verdict.element.text ?? undefined;
+        const caption = captionFor(tool, label ?? undefined, params) ?? tool;
+        // An OK is for this app, this tool and this element only (Tapwright's review, M1).
+        const check = this.confirmations.check(`${session.app.id}|${tool}|${elementKey(verdict.element)}`, { kind: tool, caption, word: verdict.word });
+        if (check.granted)
+            return { granted: true };
+        const name = this.shortName(verdict.element, false);
+        if ("held" in check) {
+            this.showAction("agent", method, { element: verdict.element }, params, "not_allowed", "needs_confirmation");
+            return {
+                stop: fail(`Error not_allowed: needs_confirmation: ${name} needs a person's OK (policy word ${JSON.stringify(verdict.word)}), and they declined it just now. Don't ask again by repeating the call: ask your user what they want.`),
+            };
+        }
+        const where = this.options.canConfirm === false
+            ? "The live view is off, so nobody can allow it here; ask your user."
+            : "The live view asks them now; when they allow it, make the same call again. If nobody is watching, ask your user.";
+        this.showAction("agent", method, { element: verdict.element }, params, "not_allowed", "needs_confirmation");
+        return {
+            stop: fail(`Error not_allowed: needs_confirmation: ${this.shortName(verdict.element, false)} needs a person's OK (policy word ${JSON.stringify(verdict.word)}). ${where}${check.suffix}`),
+        };
+    }
+    /** Which policy word, if any, the elements the target could mean carry: a block word first, then a confirm word. */
+    policyWords(lists, elements) {
+        for (const element of elements) {
+            const word = matchWord(lists.block, element);
+            if (word !== null)
+                return { kind: "blocked", element, word };
+        }
+        for (const element of elements) {
+            const word = matchWord(lists.confirm, element);
+            if (word !== null)
+                return { kind: "confirm", element, word };
+        }
+        return { kind: "none" };
+    }
+    blockedLine(element, word) {
+        return `Error not_allowed: blocked: ${this.shortName(element, false)} is blocked by the policy (${JSON.stringify(word)}); don't try another way.`;
+    }
+    /** A dry run the app answers itself (scroll, back, swipe): its checks, nothing touched, one line. */
+    async dryCall(method, params, line) {
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        if (!session.capabilities.includes("dryRun")) {
+            return fail("Error unsupported: this app's Tapline is too old for dry runs; update react-native-tapline.");
+        }
+        const stale = this.staleRef(params);
+        if (stale !== null)
+            return stale;
+        this.actionStartedAt = Date.now();
+        let result;
+        try {
+            result = await this.host.request(method, { ...params, dryRun: true }, { sessionId: session.id });
+        }
+        catch (error) {
+            this.logExtra = { dry_run: true };
+            this.showAction("agent", method, undefined, params, error instanceof TaplineError ? error.code : "internal", error instanceof TaplineError ? reasonOf(error.code, error.message) : undefined);
+            return fail(describeError(error));
+        }
+        if (typeof result !== "object" || result === null || result.dryRun !== true) {
+            return fail("Error internal: the app didn't answer the dry run.");
+        }
+        this.logExtra = { dry_run: true };
+        this.showAction("agent", method, result, params);
+        return text([line(result), ...this.takePersonNote()].join("\n"));
+    }
+    /** A dry run of a tool the policy doesn't guard (type_text): the app's checks, nothing touched. */
+    async dryRun(tool, method, params) {
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        const stale = this.staleRef(params);
+        if (stale !== null)
+            return stale;
+        const resolved = await this.resolveForPolicy(session, method, params);
+        this.logExtra = { dry_run: true };
+        if (resolved.kind === "error") {
+            this.showAction("agent", method, undefined, params, resolved.code, resolved.reason);
+            return fail(resolved.text);
+        }
+        this.showAction("agent", method, resolved.elements[0] !== undefined ? { element: resolved.elements[0] } : undefined, params);
+        return text([this.wouldLine(tool, resolved.elements[0], resolved.point, resolved.value), ...this.takePersonNote()].join("\n"));
+    }
+    /**
+     * What a touch would act on. Apps that know dry runs resolve it themselves, with every check; older
+     * apps only give their element list, and every element the target could mean is checked.
+     */
+    async resolveForPolicy(session, method, params) {
+        if (session.capabilities.includes("dryRun")) {
+            let raw;
+            try {
+                raw = await this.host.request(method, { ...params, dryRun: true }, { sessionId: session.id });
+            }
+            catch (error) {
+                const reason = error instanceof TaplineError ? reasonOf(error.code, error.message) : undefined;
+                return {
+                    kind: "error",
+                    text: describeError(error),
+                    code: error instanceof TaplineError ? error.code : "internal",
+                    ...(reason !== undefined ? { reason } : {}),
+                };
+            }
+            const parsed = dryRunResultSchema.safeParse(raw);
+            if (!parsed.success)
+                return { kind: "error", text: "Error internal: the app didn't answer the dry run.", code: "internal" };
+            return {
+                kind: "ok",
+                elements: parsed.data.element ? [parsed.data.element] : [],
+                ...(parsed.data.point !== undefined ? { point: parsed.data.point } : {}),
+                ...(parsed.data.value !== undefined ? { value: parsed.data.value } : {}),
+            };
+        }
+        // An app without dry runs: a swipe is checked by what lies under its start.
+        const target = method === "swipe" ? { x: params["x0"], y: params["y0"] } : params["target"];
+        if (method === "type" || target === undefined) {
+            return { kind: "error", text: "Error unsupported: this app's Tapline is too old for dry runs; update react-native-tapline.", code: "unsupported" };
+        }
+        let raw;
+        try {
+            raw = await this.host.request("tree", {}, { sessionId: session.id });
+        }
+        catch (error) {
+            return { kind: "error", text: describeError(error), code: error instanceof TaplineError ? error.code : "internal" };
+        }
+        const tree = treeResultSchema.safeParse(raw);
+        if (!tree.success)
+            return { kind: "error", text: "Error internal: the app returned an element list the host could not read.", code: "internal" };
+        const elements = candidatesFor(target, tree.data.elements);
+        if (elements.length === 0 && method !== "swipe") {
+            return { kind: "error", text: "Error not_found: nothing on screen matches that target.", code: "not_found" };
+        }
+        const first = elements[0];
+        const frame = elements.length === 1 && first !== undefined ? first.frame : null;
+        return {
+            kind: "ok",
+            elements,
+            ...(frame ? { point: { x: Math.round(frame.x + frame.width / 2), y: Math.round(frame.y + frame.height / 2) } } : {}),
+        };
+    }
+    /** `Would tap e12 button "Delete trip" at 215,640.` */
+    wouldLine(tool, element, point, value) {
+        const name = element !== undefined ? this.shortName(element, true) : "the element";
+        const at = point !== undefined ? ` at ${point.x},${point.y}` : "";
+        switch (tool) {
+            case "long_press":
+                return `Would long-press ${name}${at}.`;
+            case "toggle":
+                return `Would toggle ${name}${typeof value === "boolean" ? ` to ${String(value)}` : ""}${at}.`;
+            case "type_text":
+                return `Would type into ${name}.`;
+            default:
+                return `Would tap ${name}${at}.`;
+        }
+    }
+    /** `e12 button "Delete trip"`: ref (when asked), role and name, nothing else. */
+    shortName(element, withRef) {
+        return formatElement({
+            ref: withRef ? element.ref : "",
+            role: element.role ?? null,
+            type: element.type ?? null,
+            label: element.label ?? null,
+            text: element.text ?? null,
+            textMore: element.textMore ?? null,
+        }, { actions: false });
+    }
+    /** A `{ref}` target after a person used the app: refs may point elsewhere. */
+    staleRef(params) {
+        if (!this.personActed)
+            return null;
+        const target = typeof params === "object" && params !== null ? params.target : undefined;
+        if (typeof target === "object" && target !== null && "ref" in target) {
+            // The error says it already, so the note isn't repeated.
+            this.personNotePending = false;
+            return fail("Error stale: a person used the app since your last look, so refs from that list may point elsewhere. Look again, or target by id, label or text.");
+        }
+        return null;
+    }
     tap(args) {
-        return this.act("press", { target: toWireTarget(args.target), ...(args.force === true ? { force: true } : {}) }, (r) => `Tapped ${this.elementName(r)}.`, args.look, args.screenshot);
+        const params = { target: toWireTarget(withIndex(args.target, args.index)), ...(args.force === true ? { force: true } : {}) };
+        return this.guarded("tap", "press", params, args.dry_run === true, (preflight) => this.act("press", params, (r) => `Tapped ${this.elementName(r)}.`, args.look, args.screenshot, undefined, undefined, preflight));
     }
     /** `seconds` is accepted for the shared interface; Tapline calls the handler, so it doesn't hold. */
     longPress(args) {
-        return this.act("longPress", { target: toWireTarget(args.target), ...(args.force === true ? { force: true } : {}) }, (r) => `Long-pressed ${this.elementName(r)}.`, args.look, args.screenshot);
+        const params = { target: toWireTarget(withIndex(args.target, args.index)), ...(args.force === true ? { force: true } : {}) };
+        return this.guarded("long_press", "longPress", params, args.dry_run === true, (preflight) => this.act("longPress", params, (r) => `Long-pressed ${this.elementName(r)}.`, args.look, args.screenshot, undefined, undefined, preflight));
     }
     typeText(args) {
         const params = {
@@ -1352,13 +2597,18 @@ export class TaplineTools {
             submit: args.submit ?? false,
         };
         if (args.target !== undefined)
-            params["target"] = toWireTarget(args.target);
+            params["target"] = toWireTarget(withIndex(args.target, args.index));
         if (args.force === true)
             params["force"] = true;
+        // Typing isn't guarded by the policy (§11.1: the form's button is); a dry run still checks the field.
+        if (args.dry_run === true)
+            return this.dryRun("type_text", "type", params);
         return this.act("type", params, (r) => {
             const value = typeof r === "object" && r !== null && "value" in r ? r.value : undefined;
-            const shown = typeof value === "string" ? ` Value is now ${JSON.stringify(value)}.` : "";
-            return `Typed into ${this.elementName(r)}${args.submit ? " and submitted" : ""}.${shown}`;
+            // AGENT-TOOLS 1.8 §3.3: a secure field's value is never shown, not even as bullets in this line
+            const secure = typeof r === "object" && r !== null && "secure" in r && r.secure === true;
+            const shown = secure ? " The value is hidden (secure field)." : typeof value === "string" ? ` Value is now ${JSON.stringify(value)}.` : "";
+            return `Typed into ${this.elementName(r, "element", shown !== "")}${args.submit ? " and submitted" : ""}.${shown}`;
         }, args.look, args.screenshot);
     }
     scroll(args) {
@@ -1375,6 +2625,13 @@ export class TaplineTools {
         const flag = (r, key) => typeof r === "object" && r !== null && key in r ? r[key] : undefined;
         // The element was on screen and clear already: nothing was scrolled, and the first line says so.
         const alreadyThere = (r) => toTarget && flag(r, "unchanged") === true;
+        if (args.dry_run === true) {
+            return this.dryCall("scroll", params, (r) => {
+                if (toTarget)
+                    return `Would scroll ${this.elementName(r)} to ${this.elementName(r, "target")}.`;
+                return `Would scroll ${this.elementName(r)} ${args.to !== undefined ? `to ${args.to}` : (args.direction ?? "down")}.`;
+            });
+        }
         const atEndAlready = (r) => (args.to === "start" || args.to === "end") && flag(r, "moved") === false;
         return this.act("scroll", params, (r) => {
             if (alreadyThere(r))
@@ -1410,19 +2667,19 @@ export class TaplineTools {
         });
     }
     toggle(args) {
-        const params = { target: toWireTarget(args.target) };
+        const params = { target: toWireTarget(withIndex(args.target, args.index)) };
         if (args.value !== undefined)
             params["value"] = args.value;
         if (args.force === true)
             params["force"] = true;
         // The switch already had the asked value: the app touched nothing, and that line is the whole answer.
         const unchanged = (r) => typeof r === "object" && r !== null && "unchanged" in r && r.unchanged === true;
-        return this.act("toggle", params, (r) => {
+        return this.guarded("toggle", "toggle", params, args.dry_run === true, (preflight) => this.act("toggle", params, (r) => {
             const value = typeof r === "object" && r !== null && "value" in r ? r.value : undefined;
             if (unchanged(r))
                 return `${this.elementName(r)} is already ${JSON.stringify(value)}.`;
             return `Toggled ${this.elementName(r)}${value !== undefined ? ` to ${JSON.stringify(value)}` : ""}.`;
-        }, args.look, args.screenshot, undefined, unchanged);
+        }, args.look, args.screenshot, undefined, unchanged, preflight));
     }
     async appCommand(args) {
         if (args.name === undefined || args.name.trim() === "") {
@@ -1474,12 +2731,30 @@ export class TaplineTools {
         const params = { x0: args.x0, y0: args.y0, x1: args.x1, y1: args.y1 };
         if (args.seconds !== undefined)
             params["seconds"] = args.seconds;
-        return this.act("swipe", params, (r) => {
+        if (args.dry_run === true) {
+            return this.dryCall("swipe", params, (r) => {
+                const on = this.elementName(r);
+                return `Would swipe from (${args.x0}, ${args.y0}) to (${args.x1}, ${args.y1})${on === "element" ? "" : ` starting on ${on}`}.`;
+            });
+        }
+        // A swipe that moves less than 10 pt is a touch where it starts: the policy checks it (AGENT-TOOLS 1.8 §11.1).
+        const short = Math.hypot(args.x1 - args.x0, args.y1 - args.y0) < 10;
+        const perform = (preflight) => this.act("swipe", params, (r) => {
             const on = this.elementName(r);
             return `Swiped from (${args.x0}, ${args.y0}) to (${args.x1}, ${args.y1})${on === "element" ? "" : ` on ${on}`}.`;
-        }, args.look, args.screenshot);
+        }, args.look, args.screenshot, undefined, undefined, preflight);
+        return short ? this.guarded("swipe", "swipe", params, false, perform) : perform();
     }
     back(args) {
+        if (args.dry_run === true) {
+            return this.dryCall("back", {}, (r) => {
+                if (typeof r === "object" && r !== null && "closed" in r && r.closed === "sheet")
+                    return "Would close the sheet.";
+                const route = typeof r === "object" && r !== null && "route" in r ? r.route : undefined;
+                const from = Array.isArray(route) && route.every((name) => typeof name === "string") ? ` from ${route.join(" › ")}` : "";
+                return `Would go back${from}.`;
+            });
+        }
         return this.act("back", {}, (r) => {
             if (typeof r === "object" && r !== null && "closed" in r && r.closed === "sheet")
                 return "Closed the sheet.";
@@ -1488,8 +2763,16 @@ export class TaplineTools {
             return `Went back${from}.`;
         }, args.look, args.screenshot);
     }
-    openUrl(args) {
-        return this.act("openURL", { url: args.url }, () => `Opened ${args.url}.`, args.look, args.screenshot);
+    async openUrl(args) {
+        const answer = await this.act("openURL", { url: args.url }, () => `Opened ${args.url}.`, args.look, args.screenshot);
+        // The app's own forget link unpairs it, so it drops the connection before answering: that is the link working.
+        if (answer.isError === true && /(^|\/)tapline\/forget\/?$/.test(args.url.replace(/[?#].*$/, ""))) {
+            const said = answer.content.map((c) => (c.type === "text" ? c.text : "")).join("\n");
+            if (/^Error (reconnecting|not_connected)\b/.test(said)) {
+                return text("Unpaired: the app forgot this computer and disconnected. To connect it again, call `pair`.");
+            }
+        }
+        return answer;
     }
     async logs(args) {
         const session = this.host.current();