simframe 0.10.0 → 0.11.0

package/src/mcp.js

@@ -13,11 +13,63 @@ import { REGION_COLS, REGION_ROWS, regionMap } from './analyze.js';
 import * as actions from './actions.js';
 import * as api from './index.js';
 import * as input from './input.js';
+import * as metrics from './metrics.js';
 import * as navigate from './navigate.js';
 import { bootedDevices, permissionServices } from './platform/index.js';
 import * as store from './store.js';
 import * as view from './view.js';
 
+/**
+ * Per-call overrides for the two experiment knobs.
+ *
+ * Both are read from the call first and the environment second, so an A/B is an
+ * argument rather than a server restart — and a run in the wrong mode stops
+ * being a thing that can silently happen.
+ */
+export function modesFor(base = {}, args = {}) {
+  const out = { ...base };
+  if (args.sensor) out.sensor = String(args.sensor);
+  if (args.planner) out.planner = String(args.planner);
+  if (args.supervisor) out.supervisor = String(args.supervisor);
+  return out;
+}
+
+/** Offered on every tool that reads or acts, because either can be compared. */
+/**
+ * Which declared-required argument is absent, phrased as advice.
+ *
+ * Reads the tool's own `required` array, so a tool that gains a required
+ * argument gains this for free and cannot drift out of step with it.
+ */
+function missingRequired(name, args) {
+  const tool = TOOLS.find((t) => t.name === name);
+  const need = tool?.inputSchema?.required ?? [];
+  const absent = need.filter((k) => args?.[k] === undefined || args?.[k] === null || args?.[k] === '');
+  if (!absent.length) return null;
+  const known = Object.keys(args ?? {}).filter((k) => k !== 'device');
+  return `${name}: missing required ${absent.map((k) => `"${k}"`).join(', ')}.`
+    + (known.length ? ` You passed: ${known.map((k) => `"${k}"`).join(', ')}.` : '')
+    + ` ${absent.length === 1 ? 'That argument is' : 'Those arguments are'} the one${absent.length === 1 ? '' : 's'} this tool acts on — pass ${absent.map((k) => `"${k}"`).join(' and ')} and retry.`;
+}
+
+const modeProps = {
+  sensor: {
+    type: 'string',
+    enum: ['full', 'ax-first'],
+    description: 'Perception for this call. "full" fuses accessibility and OCR (~164ms). "ax-first" reads the tree alone (~50ms) and pays for OCR only when something fails to resolve. Omit to keep the server default.',
+  },
+  planner: {
+    type: 'string',
+    enum: ['none', 'apple'],
+    description: 'Local model for this call. Orders the containers seek opens; it cannot choose an action. Omit to keep the server default.',
+  },
+  supervisor: {
+    type: 'string',
+    enum: ['none', 'apple'],
+    description: 'Local supervisor for this call. When a step fails it answers wait, retry or stop — nothing else — before the batch is abandoned. Omit to keep the server default.',
+  },
+};
+
 const deviceProp = {
   device: {
     type: 'string',
@@ -42,11 +94,12 @@ const TOOLS = [
   {
     name: 'sim_ui',
     description:
-      'READ THE SCREEN. Returns a compact text map: every element with a number, its region (nav-bar / content / tab-bar), type, label, state and tap point, plus which screen this is and how much simframe already knows about it. Roughly a tenth the cost of a screenshot and strictly more useful, because it says what is tappable and where — no measuring pixels by eye. The numbers are selectors: whatever this returns as #3, you can tap as "#3". Start here, not with sim_look.',
+      'READ THE SCREEN as text: every element numbered, with region, type, label, state, contents and tap point, plus which screen this is and what simframe knows about it. A tenth the cost of a screenshot and more useful, because it says what is tappable and where. Whatever it calls #3, you can tap as "#3". Start here, never with sim_look.',
     inputSchema: {
       type: 'object',
       properties: {
         ...deviceProp,
+        ...modeProps,
         filter: { type: 'string', description: 'Only elements whose label or read text contains this.' },
         interactive: { type: 'boolean', description: 'Only elements that look tappable.' },
         all: { type: 'boolean', description: 'Include the status bar and every collapsed region (default false).' },
@@ -57,20 +110,25 @@ const TOOLS = [
   {
     name: 'sim_do',
     description:
-      'THE MAIN TOOL. Run a whole flow in ONE call: tap, type, scroll, wait and assert, in order. Each step waits for the screen to settle against a baseline captured before it, and is verified against what that action did here last time — so a step that navigated somewhere unintended stops the flow instead of tapping on into the wrong screen. A twelve-step flow costs one round trip instead of twelve. Prefer this over the single-action tools whenever you know more than one step ahead, and put asserts in the flow rather than checking between calls. Returns the compact screen map of where the flow ended; no image.',
+      'THE MAIN TOOL, and the cheapest path. Plan the WHOLE flow and run it in one call — tap, type, scroll, wait, assert — asserting after each step that matters. Every step settles and is checked against what that action did here before, so a wrong turn halts the flow instead of tapping on. Single-action tools are for recovery.',
     inputSchema: {
       type: 'object',
       properties: {
         ...deviceProp,
+        ...modeProps,
+        supervise: {
+          type: 'string',
+          description: 'What the local supervisor should know about this app while the batch runs — how lists load, what makes a control stay disabled, what a benign failure looks like here. It has no knowledge of the app; you do. Ignored when no supervisor is enabled.',
+        },
         steps: {
           type: 'array',
           description:
-            'Ordered steps. Every selector below accepts "#3" | "Save" | "@120,400". Act: {"tap":"Save"} (add "index" if a label is ambiguous), {"type":{"into":"Name","text":"Fryer 3"}}, {"paste":{"into":"Notes","text":"long text"}}, {"scroll":"down"}, {"scrollTo":"Delete account"}, {"swipe":{"from":[x,y],"to":[x,y]}}, {"button":"HOME"}, {"launch":{"value":"com.example.app","relaunch":true,"args":["-uiTest","1"]}}, {"openUrl":"myapp://x"}, {"permission":{"value":"photos","grant":"grant","bundleId":"com.example.app"}}. Check: {"assert":{"value":"Saved","is":"visible"}} (also gone | enabled | disabled | value with "equals"), {"waitFor":{"value":"Saved","timeoutMs":5000}}, {"settle":{"stableMs":600}}, {"pause":300}.',
+            'Ordered steps. Every selector below accepts "#3" | "Save" | "@120,400". Act: {"tap":"Save"} (add "index" if a label is ambiguous), {"type":{"into":"Name","text":"Fryer 3"}}, {"paste":{"into":"Notes","text":"long text"}}, {"clear":"Notes"} to empty a field and "clear":true on a type/paste to replace rather than append (drop "into" to type into whatever already has focus, which is how you follow a browser next-field chevron — nothing can be read back then, and the step says so), {"scroll":"down"}, {"scrollTo":"Delete account"}, {"swipe":{"from":[x,y],"to":[x,y]}}, {"button":"HOME"}, {"key":"return"} (the keyboard return/enter key, which is how a mobile search field submits — also escape, tab, space, backspace, and the arrows), {"launch":{"value":"com.example.app","relaunch":true,"args":["-uiTest","1"]}}, {"openUrl":"myapp://x"}, {"permission":{"value":"photos","grant":"grant","bundleId":"com.example.app"}}. Check: {"assert":{"value":"Saved","is":"visible"}} (also gone | enabled | disabled | value with "equals"), {"waitFor":{"value":"Saved","timeoutMs":5000}}, {"settle":{"stableMs":600}}, {"pause":300}. Recover without a round trip: add "or" to any step for fallback selectors tried locally — {"tap":"Save","or":["Done","Confirm"]} — and {"seek":"change username","budget":6} explores for something not on this screen: it OPENS containers (a real action — state changes), checks, and returns to where it started, refusing to open anything that commits, abandons or answers. It does not tap the target; it leaves you on the screen where the target resolves so you tap it next. Do not point it into a flow whose progress you cannot afford to lose. A long screen is only knowable a viewport at a time, so {"sweep":"all","fill":{"Last Name":"Asadi","Email":"a@b.c"}} goes to the top, then reads and fills section by section to the bottom — filling each field while it is on screen, which beats finding one and scrolling back. Add "from":"here" to sweep down from where you are. It reports which section each element was in, what it filled, and what it never found at any scroll position. Prefer it to scrollTo on forms and long lists. Brief the supervisor from the plan: top-level "supervise" is standing guidance for the whole batch ("lists here render a count header before rows; REVIEW stays disabled until a provider is chosen") and per-step "expect" adds to it. When it stops a run the result names the steps it did not attempt — re-issue them with a corrected "supervise" note if the judgement was wrong.',
           items: { type: 'object' },
         },
         autoSettle: {
           type: 'boolean',
-          description: 'Wait for the screen to settle after each action (default true). Turn off only for deliberate rapid input.',
+          description: 'Wait for the screen to settle after each action (default true). Turn off only for deliberate rapid input — with it off the trailing map is read before the last gesture has finished, so it can describe the screen you were on rather than the one you are on.',
         },
         stableMs: { type: 'number', description: 'How still the screen must be to count as settled (default 500).' },
         timeoutMs: { type: 'number', description: 'Per-step settle timeout (default 8000).' },
@@ -92,7 +150,7 @@ const TOOLS = [
     description: 'Tap one thing. For more than one step, use sim_do — it batches the verification and costs one round trip. Returns the screen map afterwards.',
     inputSchema: {
       type: 'object',
-      properties: { ...deviceProp, ...selectorProp('What to tap'), index: { type: 'number', description: 'Which match, when the selector fits several.' } },
+      properties: { ...deviceProp, ...modeProps, ...selectorProp('What to tap'), index: { type: 'number', description: 'Which match, when the selector fits several.' } },
       required: ['sel'],
     },
   },
@@ -101,7 +159,7 @@ const TOOLS = [
     description: 'Focus a field and type into it. Prefer a sim_do step when this is part of a sequence.',
     inputSchema: {
       type: 'object',
-      properties: { ...deviceProp, ...selectorProp('The field'), text: { type: 'string' }, paste: { type: 'boolean', description: 'Use the pasteboard instead of the keyboard — much faster for long strings.' } },
+      properties: { ...deviceProp, ...modeProps, ...selectorProp('The field'), text: { type: 'string' }, paste: { type: 'boolean', description: 'Use the pasteboard instead of the keyboard — much faster for long strings.' } },
       required: ['sel', 'text'],
     },
   },
@@ -112,6 +170,7 @@ const TOOLS = [
       type: 'object',
       properties: {
         ...deviceProp,
+        ...modeProps,
         ...selectorProp('What to bring into view'),
         direction: { type: 'string', enum: ['down', 'up', 'left', 'right'] },
         maxScrolls: { type: 'number', description: 'Give up after this many screens (default 6).' },
@@ -124,7 +183,7 @@ const TOOLS = [
     description: 'Block until something appears on screen, then return the screen map. Use this instead of pausing and re-reading.',
     inputSchema: {
       type: 'object',
-      properties: { ...deviceProp, ...selectorProp('What to wait for'), timeoutMs: { type: 'number', description: 'Default 8000.' } },
+      properties: { ...deviceProp, ...modeProps, ...selectorProp('What to wait for'), timeoutMs: { type: 'number', description: 'Default 8000.' } },
       required: ['sel'],
     },
   },
@@ -135,6 +194,7 @@ const TOOLS = [
       type: 'object',
       properties: {
         ...deviceProp,
+        ...modeProps,
         ...selectorProp('What to check'),
         is: {
           type: 'string',
@@ -149,10 +209,10 @@ const TOOLS = [
   {
     name: 'sim_goto',
     description:
-      'Walk to a screen simframe has already been to, by name, planning the route through remembered transitions and verifying every step. Zero reasoning and zero images: the graph knows which taps lead where. Refuses rather than guesses — if the destination is unknown, ambiguous, or unreachable through known transitions, it says which and lists what it does know. Call it with no target to see the known screens.',
+      'Walk to a screen simframe already knows, over edges it has already verified, with no model call per step. Names come from sim_recall or a previous map. Refuses rather than guesses when the route is unknown or the name is ambiguous — a refusal is cheap and a wrong walk is not.',
     inputSchema: {
       type: 'object',
-      properties: { ...deviceProp, screen: { type: 'string', description: 'What the screen is called, e.g. "Settings" or an 8-character screen hash. Omit to list what is known.' } },
+      properties: { ...deviceProp, ...modeProps, screen: { type: 'string', description: 'What the screen is called, e.g. "Settings" or an 8-character screen hash. Omit to list what is known.' } },
     },
   },
   {
@@ -160,7 +220,7 @@ const TOOLS = [
     description: 'Replay a saved flow by name, verifying each step. Omit `name` to list the saved flows. Save one with sim_do\'s `saveAs`.',
     inputSchema: {
       type: 'object',
-      properties: { ...deviceProp, name: { type: 'string', description: 'Flow to run. Omit to list.' } },
+      properties: { ...deviceProp, ...modeProps, name: { type: 'string', description: 'Flow to run. Omit to list.' } },
     },
   },
   {
@@ -170,6 +230,7 @@ const TOOLS = [
       type: 'object',
       properties: {
         ...deviceProp,
+        ...modeProps,
         bundleId: { type: 'string' },
         relaunch: { type: 'boolean', description: 'Terminate first. Without this, launching an already-running app silently does nothing and you test the screen you were already on.' },
         args: { type: 'array', items: { type: 'string' }, description: 'Launch arguments passed to the app.' },
@@ -183,7 +244,7 @@ const TOOLS = [
     description: 'Open a URL or deep link on the device — the fastest way to reach a screen when the app has a link for it.',
     inputSchema: {
       type: 'object',
-      properties: { ...deviceProp, url: { type: 'string' } },
+      properties: { ...deviceProp, ...modeProps, url: { type: 'string' } },
       required: ['url'],
     },
   },
@@ -194,6 +255,7 @@ const TOOLS = [
       type: 'object',
       properties: {
         ...deviceProp,
+        ...modeProps,
         action: { type: 'string', enum: ['grant', 'revoke', 'reset'] },
         service: { type: 'string' },
         bundleId: { type: 'string' },
@@ -204,10 +266,10 @@ const TOOLS = [
   {
     name: 'sim_find',
     description:
-      'Resolve an intent to one control: "tap Save", "the Assets tab", "back". Understands verbs, typos, where on screen you meant, and icon-only controls by their common name. When two things answer equally well it says so and lists them rather than guessing — a wrong tap is worse than a question, because it can do something and leave you believing it did the right thing. Use it when you are unsure a selector will resolve; otherwise just tap.',
+      'Resolve one intent to one control: "tap Save", "the Assets tab", "back". Understands verbs, typos, and where on screen you meant. When two things answer equally well it says so and lists them rather than guessing. Use it when you doubt a selector will resolve; otherwise just tap. Prefer a label or a #ref over coordinates.',
     inputSchema: {
       type: 'object',
-      properties: { ...deviceProp, intent: { type: 'string', description: 'What you want to act on, in your own words.' } },
+      properties: { ...deviceProp, ...modeProps, intent: { type: 'string', description: 'What you want to act on, in your own words.' } },
       required: ['intent'],
     },
   },
@@ -219,6 +281,7 @@ const TOOLS = [
       type: 'object',
       properties: {
         ...deviceProp,
+        ...modeProps,
         since: { type: 'string', description: 'Compare against this frame hash instead of your last look.' },
       },
     },
@@ -226,11 +289,12 @@ const TOOLS = [
   {
     name: 'sim_wait',
     description:
-      'Block until the screen finishes reacting. Default mode "settle" waits for the screen to CHANGE and then hold still, which is what you want after acting — plain "stable" can return instantly in the moment before an animation starts. Returns the compact screen map by default, not an image. Inside a flow you rarely need this: sim_do settles after every step already.',
+      'Wait for the screen to change, settle, or both. sim_do already settles after every step, so you rarely need this inside a flow — reach for it when something moves without you acting, like a push or a background load. Pass `since` from a hash captured before the thing you are waiting on.',
     inputSchema: {
       type: 'object',
       properties: {
         ...deviceProp,
+        ...modeProps,
         mode: {
           type: 'string',
           enum: ['settle', 'change', 'stable'],
@@ -246,16 +310,24 @@ const TOOLS = [
   {
     name: 'sim_look',
     description:
-      'THE ONLY TOOL THAT RETURNS AN IMAGE, and the most expensive one. Returns the newest buffered frame immediately — no screenshot wait. Call it only when the text map is genuinely not enough: checking visual layout, colour, spacing, an animation, or something the accessibility tree and OCR both cannot see. For "what is on screen and what can I tap", sim_ui answers better and costs a tenth as much.',
+      'A screenshot: ~1600 tokens, the most expensive call here. Only for what text cannot answer — layout, colour, spacing, a control the map omits. NOT for what a field contains, whether a button is enabled, or whether an action worked: sim_ui reports the first two and the flow\'s own verdict already answered the third.',
     inputSchema: {
       type: 'object',
       properties: {
         ...deviceProp,
+        ...modeProps,
         detail: {
           type: 'string',
           enum: ['low', 'normal', 'high'],
           description: 'Image size: low (~420px, cheapest), normal (~700px, default), high (1024px, readable small text). Capped at 1024px on the long edge.',
         },
+        region: {
+          type: 'object',
+          description: 'Crop to part of the screen and enlarge it, in POINTS — the same coordinates the element map prints: {"x":18,"y":260,"width":366,"height":80}. Use it when a whole screen cannot answer the question at 1024px: selected versus unselected, a chevron, a validation mark. Pair it with detail:"high".',
+          properties: {
+            x: { type: 'number' }, y: { type: 'number' }, width: { type: 'number' }, height: { type: 'number' },
+          },
+        },
         maxAgeMs: { type: 'number', description: 'If the buffered frame is older than this, wait for a fresher one (default 900).' },
       },
     },
@@ -268,6 +340,7 @@ const TOOLS = [
       type: 'object',
       properties: {
         ...deviceProp,
+        ...modeProps,
         count: { type: 'number', description: 'How many frames to tile (default 5, max 12).' },
         spanMs: { type: 'number', description: 'Only include frames from the last N milliseconds.' },
         thumbMaxDim: { type: 'number', description: 'Height budget per frame in pixels (default 240).' },
@@ -277,11 +350,12 @@ const TOOLS = [
   {
     name: 'sim_recall',
     description:
-      'Look BACKWARDS in time. simframe remembers roughly the last 60 seconds of the screen. action "timeline" (default) returns a TEXT-ONLY summary of what happened and when: each change, how long ago, how long it took, how much of the screen moved. action "at" returns the buffered frame from a past moment — an image. Use this when you look up and find the screen already different, instead of re-running the action.',
+      'What happened recently, as text: the screens visited, the actions taken, and what each one did. Use it to re-orient after a failure instead of taking a screenshot, and to learn the screen names sim_goto accepts.',
     inputSchema: {
       type: 'object',
       properties: {
         ...deviceProp,
+        ...modeProps,
         action: { type: 'string', enum: ['timeline', 'at'], description: 'timeline (default) or at.' },
         spanMs: { type: 'number', description: 'For timeline: how far back to summarise (default 60000).' },
         msAgo: { type: 'number', description: 'For at: how long ago the moment of interest was, in milliseconds.' },
@@ -297,6 +371,7 @@ const TOOLS = [
       properties: {
         action: { type: 'string', enum: ['status', 'start', 'stop'] },
         ...deviceProp,
+        ...modeProps,
         fps: { type: 'number', description: 'Capture rate while the screen is moving (default 4).' },
       },
       required: ['action'],
@@ -338,9 +413,38 @@ function baselineFor(udid, explicit) {
 const text = (s) => ({ type: 'text', text: s });
 const image = (png) => ({ type: 'image', data: png.toString('base64'), mimeType: 'image/png' });
 
+/**
+ * The device's name, and its UDID when the name cannot identify it.
+ *
+ * Two booted simulators can share a name — measured on this machine: two called
+ * "iPhone 17 Pro" at once, which is the default state after creating a second
+ * device of the same model. A caller reading a header that says only
+ * "iPhone 17 Pro" has no way to tell which one answered, and a reporter spent a
+ * session unsure whether they were looking at their own app. `xcrun simctl list
+ * devices booted` makes the collision trivial to see, so the header says which.
+ */
+function deviceLabel(device) {
+  if (!device?.udid) return device?.name ?? 'unknown device';
+  const clash = (lastBooted ?? []).filter((d) => d.name === device.name).length > 1;
+  return clash ? `${device.name} (${device.udid.slice(0, 8)})` : device.name;
+}
+
+/** What the last device listing saw, so a name collision can be noticed at all. */
+let lastBooted = null;
+export function noteBooted(devices) {
+  lastBooted = Array.isArray(devices) ? devices.map((d) => ({ name: d.name, udid: d.udid })) : null;
+  const names = new Map();
+  for (const d of lastBooted ?? []) names.set(d.name, (names.get(d.name) ?? 0) + 1);
+  const shared = [...names].filter(([, n]) => n > 1).map(([name]) => name);
+  return shared.length
+    ? `WARNING: ${shared.map((n) => JSON.stringify(n)).join(', ')} names more than one booted device`
+      + ' — pass "device" with a UDID, because a name cannot identify which one you mean'
+    : null;
+}
+
 function header(device, state, ageMs, extra = '') {
   return (
-    `${device.name} · ${device.runtime} · frame #${state.seq} · ${ageMs}ms old · ` +
+    `${deviceLabel(device)} · ${device.runtime} · frame #${state.seq} · ${ageMs}ms old · ` +
     `${state.width}x${state.height} · still for ${state.stableForMs}ms${extra ? ` · ${extra}` : ''}`
   );
 }
@@ -364,7 +468,9 @@ function sinceLine(since) {
     : `unchanged since your last look ${since.ageMs}ms ago`;
 }
 
-export async function serve({ device: defaultDevice, options = {} } = {}) {
+export async function serve({ device: defaultDevice, options: baseOptions = {} } = {}) {
+  // The last device a caller named, for the life of this server.
+  let lastDevice = null;
   const server = new Server(
     { name: 'simframe', version: packageVersion() },
     { capabilities: { tools: {} } },
@@ -374,7 +480,34 @@ export async function serve({ device: defaultDevice, options = {} } = {}) {
 
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const args = req.params.arguments || {};
-    const target = args.device || defaultDevice;
+    // Sticky, and stickiness is not guessing.
+    //
+    // Reported: `sim_launch` accepted `device`, and the very next `sim_ui`
+    // refused with "2 simulators are booted and none was named" — so a UDID had
+    // to ride on all ~15 subsequent calls. Refusing to *choose* between two
+    // booted devices is right; forgetting which one the caller already named is
+    // not. This remembers only what was explicitly passed, so nothing is ever
+    // inferred from a boot list.
+    const target = args.device || lastDevice || defaultDevice;
+    if (args.device) lastDevice = String(args.device);
+    // An MCP server's environment is fixed when it spawns, so a tester asked to
+    // compare two sensor modes inside one session could not: round 6 ran its
+    // baseline and could not run either variant. The suggested workaround was
+    // three server entries with three env blocks, which is worse — three servers
+    // on one device is three writers, against the one-writer-per-device rule.
+    //
+    // So the modes are arguments. Absent, the environment still decides, so
+    // nothing that was working changes.
+    const options = modesFor(baseOptions, args);
+    // Name the missing argument, using the tool's own schema.
+    //
+    // Reported: `sim_scroll_to` called with `target:` instead of `sel:` answered
+    // `simframe: empty step` — which names neither the tool, nor the parameter,
+    // nor even that an argument was absent, and cost a schema lookup to decode.
+    // The declared `required` list is right there, so the check is generic
+    // rather than one guard per tool, and it says what to pass.
+    const missing = missingRequired(req.params.name, args);
+    if (missing) return { content: [text(missing)], isError: true };
     try {
       switch (req.params.name) {
         case 'sim_look':
@@ -450,6 +583,81 @@ export async function serve({ device: defaultDevice, options = {} } = {}) {
   await server.connect(new StdioServerTransport());
 }
 
+/**
+ * Crop a frame to a region of the screen and enlarge it.
+ *
+ * A whole screen at 1024px cannot answer a question about one control: a
+ * selected filter chip and an unselected one look identical at that size, and an
+ * agent shelled out to `simctl io` and PIL to crop and upscale a chip row for
+ * every check it made. The region arrives in **points** — the same coordinates
+ * the element map prints — because that is what a caller has in hand.
+ */
+/**
+ * Read a region argument that may not have arrived as an object.
+ *
+ * A client is free to hand a declared-object property over as a JSON string,
+ * and one did: `{"x":0,"y":60,...}` arrived as text, every field read as
+ * undefined, and the crop silently became the whole screen — reported back as
+ * `cropped to 402x874pt at 0,0`, which is a crop that did not happen described
+ * as one that did. An array is accepted too, because [x, y, width, height] is
+ * the shape anyone would try first, and it used to fail exactly as quietly.
+ */
+export function readRegion(region) {
+  let r = region;
+  if (typeof r === 'string') {
+    try { r = JSON.parse(r); } catch { return null; }
+  }
+  if (Array.isArray(r)) {
+    const [x, y, width, height] = r.map(Number);
+    return [x, y, width, height].every(Number.isFinite) ? { x, y, width, height } : null;
+  }
+  if (!r || typeof r !== 'object') return null;
+  const num = (...keys) => {
+    for (const k of keys) if (Number.isFinite(Number(r[k]))) return Number(r[k]);
+    return null;
+  };
+  const width = num('width', 'w');
+  const height = num('height', 'h');
+  // A region with no size is not a region. Saying so beats returning the whole
+  // screen under a caption that claims otherwise.
+  if (width == null && height == null) return null;
+  return { x: num('x') ?? 0, y: num('y') ?? 0, width, height };
+}
+
+async function cropRegion(png, region, points) {
+  try {
+    const { decodePng, encodePng, cropBitmap, scaleBitmap } = await import('./png.js');
+    const bmp = decodePng(png);
+    const pw = points?.width;
+    const ph = points?.height;
+    if (!Number.isFinite(pw) || !Number.isFinite(ph) || !pw || !ph) return { note: 'the screen point size is unknown' };
+    // The frame we hold is already downscaled for the model, so map points onto
+    // *this* bitmap rather than onto the device's native pixels.
+    const sx = bmp.width / pw;
+    const sy = bmp.height / ph;
+    const x = Number(region.x ?? 0) * sx;
+    const y = Number(region.y ?? 0) * sy;
+    const w = Number(region.width ?? region.w ?? pw) * sx;
+    const h = Number(region.height ?? region.h ?? ph) * sy;
+    if (!(w >= 1) || !(h >= 1)) return { note: 'the region has no size' };
+    const cut = cropBitmap(bmp, x, y, w, h);
+    // Enlarge to the same budget the whole screen gets, so the detail per point
+    // is the whole reason to ask for a region.
+    const long = Math.max(cut.width, cut.height);
+    const factor = Math.min(6, Math.max(1, Math.round(1024 / long)));
+    const big = factor > 1 ? scaleBitmap(cut, cut.width * factor, cut.height * factor) : cut;
+    return {
+      png: encodePng(big),
+      note: `cropped to ${Math.round(Number(region.width ?? region.w ?? pw))}x`
+        + `${Math.round(Number(region.height ?? region.h ?? ph))}pt at `
+        + `${Math.round(Number(region.x ?? 0))},${Math.round(Number(region.y ?? 0))}`
+        + `, enlarged ${factor}x`,
+    };
+  } catch (err) {
+    return { note: String(err.message).split('\n')[0] };
+  }
+}
+
 async function look(target, args, options) {
   const maxAge = args.maxAgeMs ?? 900;
   // Never native resolution. An image is the expensive path by a factor of ten
@@ -472,9 +680,37 @@ async function look(target, args, options) {
   const st = await api.getState(target, { since: prior, options });
   remember(res.device.udid, res.state);
   const lines = [header(res.device, res.state, res.ageMs), sinceLine(st.since)];
+  // Louder than a trailing note, because it invalidates the image itself rather
+  // than qualifying it.
+  if (res.frameBehindMs) {
+    lines.unshift(`WARNING: this image is ${Math.round(res.frameBehindMs / 100) / 10}s older than the screen state`
+      + ' — it is very likely NOT what is on the device now. Read sim_ui, which is read live,'
+      + ' or look again in a moment.');
+  }
   const warn = livenessLine(st.live);
   if (warn) lines.unshift(warn);
-  return { content: [text(lines.filter(Boolean).join('\n')), image(res.png)] };
+  let png = res.png;
+  if (args.region) {
+    const parsed = readRegion(args.region);
+    if (!parsed) {
+      lines.push('that region could not be read (expected {"x":0,"y":260,"width":402,"height":80} in points,'
+        + ' or [x, y, width, height]) — this is the whole screen');
+    }
+    // The point size, which the frame does not carry: `state.width/height` are
+    // the *captured frame's* pixels (322x700 here), not the screen's points
+    // (402x874). Scaling by them gave a 1:1 ratio, so a crop at y=760 clamped
+    // to a single pixel row and returned a 119-byte image — which looked like
+    // it had worked. `screenIdentity` answers it in ~17ms warm.
+    const geo = await api.screenIdentity(target, { options, confirmNovel: false }).catch(() => null);
+    const cropped = parsed ? await cropRegion(png, parsed, geo?.points) : { note: null };
+    if (cropped.png) {
+      png = cropped.png;
+      lines.push(cropped.note);
+    } else if (cropped.note) {
+      lines.push(`could not crop that region (${cropped.note}) — this is the whole screen`);
+    }
+  }
+  return { content: [text(lines.filter(Boolean).join('\n')), image(png)] };
 }
 
 async function state(target, args, options) {
@@ -635,10 +871,38 @@ async function recall(target, args, options) {
  * is free. Reading the screen a second time to render it was the whole cost of
  * a text-first surface, and it does not have to be paid.
  */
+/**
+ * The map at the end of an action, and why it is re-read rather than recalled.
+ *
+ * It used to be rendered from whatever `screenIdentity` had in hand during
+ * verification, which is memory-first by design — so the trailing map could
+ * describe the screen as it was seconds earlier. Reported from a real session:
+ * *"do's trailing dump is still stale, so I still ran `ui --refresh` after
+ * nearly every call — that remains the biggest speed tax."*
+ *
+ * Saying how old it was (the header does) turned out not to be enough: an agent
+ * that cannot trust the map spends a turn re-reading it, and a turn is the
+ * expensive unit here. So an action pays one perception pass — a few hundred
+ * milliseconds, locally, once — to save a model round trip. That is the whole
+ * trade this phase is about, and it is the right way round.
+ *
+ * `refresh: false` is still available for the read-only tools, where the caller
+ * asked for a map and can ask again.
+ */
 async function mapFrom(target, options, identity, extra = {}) {
   try {
-    const m = await view.screenMap(target, { options, identity: identity?.entry ? identity : undefined });
-    return view.render({ ...m, ...extra });
+    const fresh = extra.refresh !== false;
+    const m = await view.screenMap(target, {
+      options,
+      refresh: fresh,
+      identity: fresh ? undefined : (identity?.entry ? identity : undefined),
+    });
+    const rendered = view.render({ ...m, ...extra });
+    // The line that decides whether the model stops to think. Everything it
+    // needs is already computed for the map above it, so this costs nothing —
+    // and "nothing here needs you" is a thing only the daemon can say.
+    if (extra.hint === false) return rendered;
+    return `${rendered}\n${view.hintFor(m, { flowOk: extra.flowOk, escalated: extra.escalated })}`;
   } catch (err) {
     return `(could not read the screen: ${err.message})`;
   }
@@ -679,10 +943,29 @@ async function doScript(target, args, options) {
     stableMs: args.stableMs,
     timeoutMs: args.timeoutMs,
     continueOnError: args.continueOnError,
+    // The plan's briefing for its own first responder. Ignored when no
+    // supervisor is enabled, so passing it is always safe.
+    supervise: args.supervise,
     options,
   });
 
   const lines = stepLines(res);
+  // A map read without settling is not a reading of the screen you are now on,
+  // and it used to arrive looking exactly like one. Reported: two taps under
+  // `autoSettle:false` returned a map showing nothing had happened, so the
+  // agent moved on — the page had in fact zoomed all the way out, and they only
+  // found out two calls later when an unrelated failure printed a real map.
+  if (args.autoSettle === false) {
+    lines.push('autoSettle was off, so the map below was read without waiting for the last action to finish'
+      + ' — it may describe the screen before that action landed. Re-read (sim_ui) before acting on it.');
+  }
+  // Every local ruling is reported, because a wrong one has to be correctable
+  // rather than mysterious — and the model's own stated reason is shown as its
+  // claim, not as the ground for what happened.
+  for (const s_ of res.supervisions ?? []) {
+    lines.push(`supervisor at step ${s_.index}: ${s_.decision} — ${s_.outcome}`
+      + (s_.reason ? ` (it said: "${s_.reason}")` : ''));
+  }
   if (args.saveAs) {
     const saved = navigate.saveFlow(res.device.udid, args.saveAs, res);
     lines.push(
@@ -691,7 +974,12 @@ async function doScript(target, args, options) {
         : `NOT saved as "${args.saveAs}": ${saved.reason}${saved.verdicts ? ` (${saved.verdicts.join(', ')})` : ''}`,
     );
   }
-  lines.push('', await mapFrom(target, options, res.endScreen, { verdictLine: verdictLineFor(res.results) }));
+  const escalated = (res.results ?? []).some((r) => metrics.ESCALATING_VERDICTS.has(r.verification?.verdict));
+  lines.push('', await mapFrom(target, options, res.endScreen, {
+    verdictLine: verdictLineFor(res.results),
+    flowOk: res.ok,
+    escalated,
+  }));
 
   const content = [text(lines.join('\n'))];
   // Images only when explicitly asked for. A frame attached to every flow was
@@ -785,7 +1073,9 @@ async function ui(target, args, options) {
     refresh: args.refresh,
   });
   if (m.identity.state) remember(m.device.udid, m.identity.state);
-  return { content: [text(m.text)] };
+  // The hint belongs here too: the agent has just looked, so "you do not need
+  // to look again" is exactly the thing worth saying at this moment.
+  return { content: [text(`${m.text}\n${view.hintFor(m)}`)] };
 }
 
 async function find(target, args, options) {
@@ -840,7 +1130,9 @@ function listStateDirs() {
 async function devices() {
   const booted = await bootedDevices();
   if (!booted.length) return { content: [text('no booted devices')] };
-  return {
-    content: [text(booted.map((d) => `${d.name} · ${d.runtime} · ${d.udid}`).join('\n'))],
-  };
+  // Noticing a name collision here is what lets every later header disambiguate
+  // itself, and it costs nothing: this listing is already being made.
+  const clash = noteBooted(booted);
+  const list = booted.map((d) => `${d.name} · ${d.runtime} · ${d.udid}`).join('\n');
+  return { content: [text(clash ? `${clash}\n\n${list}` : list)] };
 }