simframe 0.7.0 → 0.8.0

package/README.md

@@ -4,11 +4,11 @@
 [![npm](https://img.shields.io/npm/v/simframe.svg)](https://www.npmjs.com/package/simframe)
 [![license](https://img.shields.io/npm/l/simframe.svg)](./LICENSE)
 
-**Eyes, hands and memory for an agent driving the iOS Simulator.**
+**Eyes, hands and memory for an agent driving the iOS Simulator or an Android emulator.**
 
 [Website](https://lvlrsajjad.github.io/simframe/) · [npm](https://www.npmjs.com/package/simframe)
 
-An agent driving the iOS Simulator is slow for three reasons, and only the first
+An agent driving a simulator is slow for three reasons, and only the first
 one is obvious:
 
 1. **Every look is a wait.** `simctl io screenshot` costs ~130 ms of blocking
@@ -37,6 +37,7 @@ Same four-tab navigation flow, on a real production app:
 | | Before | With simframe |
 | --- | --- | --- |
 | Look at the screen | ~130–400 ms, blocking | **~20 ms**, already captured |
+
 | "Did anything change?" | a full image | **~2 ms**, text only |
 | Finding a control | read tree (~570 ms) + reason | **~1 ms** from memory |
 | A 4-step flow, verified | 4+ model round trips | **1 call**, 3.6 s |
@@ -44,6 +45,13 @@ Same four-tab navigation flow, on a real production app:
 | A 10-step flow | 10 turns, 10 images (~16,000 tokens at best) | **1 turn, 0 images, ~1,650 characters** |
 | Reading a screen | an image: ~1,600 tokens, no tap points | **~330 tokens** of text, with tap points |
 
+Every figure above is the cost inside a live process — the MCP server, or the
+daemon answering a socket — which is how an agent actually uses simframe. A
+one-shot `simframe` command from a shell pays about 200 ms of Node startup on
+top, and a frame sitting on an idle screen can be older than 20 ms because the
+capture loop throttles when nothing moves. `~20 ms` is the read, not the
+process.
+
 The four-tab tour, three times back to back from a cleared memory:
 
 | Pass | Wall clock | Steps verified | Controls from memory |
@@ -67,10 +75,16 @@ npm install -g simframe
 simframe doctor
 ```
 
-The first `simframe start` builds a small Swift daemon from source — a few
-seconds, once. It needs the Xcode command line tools, which you already have if
-you have a simulator. Without them simframe falls back to the original
-`simctl` loop and says so.
+**Whichever of those two commands you run first** builds a small Swift daemon
+from source — including `doctor`, which is why a cold `doctor` takes around 15
+seconds and every later one takes two. It needs the Xcode command line tools,
+which you already have if you have a simulator. Without them simframe falls
+back to the original `simctl` loop and says so.
+
+If more than one simulator is booted, name the one you mean — `--device=<udid>`,
+or `export SIMFRAME_DEVICE=<udid>` once per shell. simframe refuses to choose
+for you, because the first booted device is nobody's idea of "yours" and the
+command that would act on it is a tap.
 
 `doctor` checks each capability separately and tells you what you have:
 
@@ -143,7 +157,7 @@ boundary hands it frames and nothing above it knows what a simulator is.
 | Read labels + coordinates from pixels | yes | the same Vision OCR + CV, off the same PNG |
 | Screen map, refs, screen memory, the graph | yes | unchanged above the boundary |
 | Tap, type, swipe, keys | yes | the console's `event mouse` as a real down/move/up, `event text` for characters, `input keyevent` for keys |
-| Clipboard | yes | the emulator's gRPC `setClipboard`, over `node:http2`, no dependency |
+| Clipboard, and `paste` into a field | yes | the emulator's gRPC `setClipboard`, over `node:http2`, no dependency, then `KEYCODE_PASTE` to deliver it |
 | List/resolve devices, launch, terminate, open a URL, permissions | yes | `adb`, with the permission state read back off the device |
 | Accessibility tree | **not available (OCR + CV only)** | `uiautomator dump` costs **2,012 ms** a read, against 45 ms for the iOS tree. See [`docs/DEFERRED.md`](docs/DEFERRED.md) |
 
@@ -154,6 +168,17 @@ simframe ui --device=emulator-5554
 simframe do --device=emulator-5554 flow.json
 ```
 
+A host with a booted simulator **and** a booted emulator has no default, and
+simframe will not pick one for you: preferring iOS because it came first would
+tap a simulator while you were driving an emulator, and acting on the wrong
+device is worse than refusing. So a command with no device names both and stops.
+`--device` answers it per command; `SIMFRAME_DEVICE` answers it per shell:
+
+```bash
+export SIMFRAME_DEVICE=emulator-5554
+simframe ui               # the emulator, without saying so every time
+```
+
 The tree is a deliberate omission, not an oversight. Making it fast needs a
 resident instrumentation APK on the device — the shape uiautomator2, Maestro and
 Appium all converged on — and that would be simframe's first runtime artifact
@@ -517,8 +542,14 @@ simframe frame --out=now.png   # newest frame, native resolution, to a file
 simframe strip --count=6       # contact sheet, for an animation
 simframe doctor --strict       # any degraded layer is a non-zero exit
 simframe start / status / stop [--force] / devices
+simframe ui --device=emulator-5554      # or export SIMFRAME_DEVICE once
 ```
 
+`--device` takes `--device=X` and `--device X` alike. It used to take only the
+first: the space form set the flag to `true` and then resolved a device named
+"true", which is a poor answer to a flag `doctor`'s own advice tells you to
+type.
+
 ### The Claude Code skill
 
 [`skills/simframe/SKILL.md`](skills/simframe/SKILL.md) teaches the CLI path

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "simframe",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "mcpName": "io.github.lvlrSajjad/simframe",
-  "description": "Always-warm iOS Simulator frames: agents read the screen in ~20ms instead of waiting on screenshots. MCP server + CLI.",
+  "description": "Always-warm iOS Simulator and Android emulator frames: agents read the screen in ~20ms instead of waiting on screenshots. MCP server + CLI.",
   "keywords": [
     "ios",
     "simulator",
+    "android",
+    "emulator",
     "mcp",
     "model-context-protocol",
     "claude",

package/scripts/check-package.mjs

@@ -123,4 +123,19 @@ if (missing.length) {
   );
   process.exit(1);
 }
+// The MCP Registry rejects a description over 100 characters, and it does so at
+// `mcp-publisher validate` — after the tag is pushed and the release has begun.
+// A 0.7.1 release found that out the hard way with a 113-character one. The
+// constraint is the registry's; discovering it locally is this script's job.
+const DESCRIPTION_MAX = 100;
+const server = JSON.parse(fs.readFileSync(path.join(ROOT, 'server.json'), 'utf8'));
+if (server.description.length > DESCRIPTION_MAX) {
+  console.error(
+    `server.json description is ${server.description.length} characters; the MCP Registry accepts ` +
+      `${DESCRIPTION_MAX}. It would fail at validate, with the tag already pushed.`,
+  );
+  process.exit(1);
+}
+console.log(`server.json description ${server.description.length}/${DESCRIPTION_MAX} chars`);
+
 console.log('ok — every build input ships');

package/scripts/ci-memory.mjs

@@ -257,7 +257,14 @@ if (first) {
   // to defend — and it is how this check has failed twice.
   if (moved) {
     const stale = await cli(['find', `#${first.ref}`], { expectFail: true });
-    check(/different screen|read the screen/i.test(stale),
+    // Matched on prose, which is this check's weakness: simframe refused
+    // correctly with "#1 cannot be trusted here — simframe does not recognise
+    // this screen. Read it again", and the check failed because that wording was
+    // not one of the two it knew. The refusal is what matters, so the
+    // alternation covers how a refusal is actually phrased; the durable fix is a
+    // machine-readable reason on the failure, which `find --json` does not yet
+    // carry.
+    check(/different screen|read the screen|read it again|does not recognise this screen|cannot be trusted/i.test(stale),
       'a ref numbered on another screen refuses instead of tapping those coordinates',
       stale.trim().split('\n')[0]?.slice(0, 90));
   }
@@ -398,7 +405,13 @@ check(Array.isArray(nonsense.known) && nonsense.known.length > 0,
 
 const target = screens[0];
 const walked = await jsonRetry(['goto', target.hash], { allowFail: true });
-const outcomes = ['no-route', 'unreplayable-edge', 'ambiguous', 'unknown-screen'];
+// `no-identity` is new in 0.7.2 and belongs here: `goto` used to *throw*
+// `Cannot read properties of null (reading 'slice')` on a screen whose token set
+// was empty, because `hashTokens` returns null for one on purpose. A crash is
+// neither walking there nor naming why it cannot, so this check failed with an
+// empty detail — the reason was `undefined` — and the check was right to fail.
+// Now there is a name for it, and the list has to know the name.
+const outcomes = ['no-route', 'unreplayable-edge', 'ambiguous', 'unknown-screen', 'no-identity'];
 check(walked.ok === true || outcomes.includes(walked.reason),
   'and asked for a screen it knows, it either walks there or names why it cannot',
   walked.ok ? (walked.already ? 'already there' : `walked ${walked.ranSteps} step(s)`) : walked.reason);

package/src/actions.js

@@ -6,7 +6,7 @@ import * as api from './index.js';
 import * as graph from './graph.js';
 import * as input from './input.js';
 import * as intent from './intent.js';
-import { launchApp, openUrl, setPasteboard, setPermission, terminateApp } from './platform/index.js';
+import { launchApp, openUrl, setPermission, terminateApp } from './platform/index.js';
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const MAX_PAUSE_MS = 5000;
@@ -272,6 +272,33 @@ export async function runScript(
   };
 }
 
+/**
+ * Tap a field and wait for it to take focus, for the steps that then put text
+ * in it.
+ *
+ * `locate`, not `tapLabel`: tapLabel asks the accessibility tree directly, so a
+ * field only OCR can see was untypeable and a selector (`#4`, `@x,y`) meant
+ * nothing here. The returned `quiet` says when the field never visibly took
+ * focus — usually fine, since a field that already had focus does not move, but
+ * also exactly what a tap that missed looks like, so the caller should be told.
+ */
+async function focusField(deviceQuery, udid, step, ctx) {
+  const found = await api.locate(deviceQuery, step.into, { index: step.index, refresh: step.refresh });
+  await input.tapPoint(udid, found.target.x, found.target.y);
+  const focused = await api.waitFor(deviceQuery, {
+    mode: 'settle',
+    stableMs: FOCUS_STABLE_MS,
+    reactionMs: FOCUS_REACTION_MS,
+    timeoutMs: FOCUS_TIMEOUT_MS,
+    options: ctx.options,
+  });
+  return {
+    found,
+    where: `"${found.target.label}" at ${found.target.x},${found.target.y}`,
+    quiet: focused.satisfied ? '' : ' [the field did not visibly take focus]',
+  };
+}
+
 async function runStep(deviceQuery, udid, step, ctx) {
   switch (step.action) {
     case 'tap': {
@@ -298,33 +325,25 @@ async function runStep(deviceQuery, udid, step, ctx) {
     }
     case 'type': {
       if (step.into) {
-        // locate, not tapLabel: tapLabel asks the accessibility tree directly,
-        // so a field that only OCR can see was untypeable, and a selector
-        // (`#4`, `@x,y`) meant nothing here.
-        const found = await api.locate(deviceQuery, step.into, { index: step.index, refresh: step.refresh });
-        await input.tapPoint(udid, found.target.x, found.target.y);
-        const focused = await api.waitFor(deviceQuery, {
-          mode: 'settle',
-          stableMs: FOCUS_STABLE_MS,
-          reactionMs: FOCUS_REACTION_MS,
-          timeoutMs: FOCUS_TIMEOUT_MS,
-          options: ctx.options,
-        });
+        const field = await focusField(deviceQuery, udid, step, ctx);
         await input.typeText(udid, step.text ?? step.value);
-        // Say when the field never visibly took focus. It is usually fine — a
-        // field that was already focused does not move — but it is also what a
-        // tap that missed looks like, and the caller should be able to tell.
-        const quiet = focused.satisfied ? '' : ' [the field did not visibly take focus]';
-        return `typed into "${found.target.label}" at ${found.target.x},${found.target.y}${quiet}`;
+        return `typed into ${field.where}${field.quiet}`;
       }
       await input.typeText(udid, step.text ?? step.value);
       return 'typed text';
     }
     case 'paste': {
-      // Long strings are much faster on the pasteboard than through the keyboard.
-      await setPasteboard(udid, step.text ?? step.value);
-      if (step.into) await input.tapLabel(udid, step.into, { index: step.index, durationMs: 900 });
-      return 'placed text on the pasteboard';
+      // Long strings are much faster on the pasteboard than through the
+      // keyboard. `pasteText` delivers the keystroke as well as setting the
+      // pasteboard, and throws if it cannot — this step used to do neither and
+      // report success anyway.
+      if (step.into) {
+        const field = await focusField(deviceQuery, udid, step, ctx);
+        await input.pasteText(udid, step.text ?? step.value);
+        return `pasted into ${field.where}${field.quiet}`;
+      }
+      await input.pasteText(udid, step.text ?? step.value);
+      return 'pasted into the focused field';
     }
     case 'swipe': {
       const from = { x: step.from?.[0] ?? step.from?.x, y: step.from?.[1] ?? step.from?.y };

package/src/cli.js

@@ -86,14 +86,39 @@ The reliable pattern around an action is:
   simframe state --since=$H
 `;
 
+/**
+ * Flags that take a value, so `--flag value` can mean what it looks like.
+ *
+ * Deliberately not every flag: `--json`, `--refresh` and friends have a bare
+ * form, and letting those swallow the next argument would turn
+ * `simframe tap --refresh Save` into a tap on nothing.
+ */
+const VALUE_FLAGS = new Set([
+  'ago', 'count', 'detail', 'device', 'durationMs', 'engine', 'filter', 'fps', 'index', 'maxDim',
+  'mode', 'out', 'ringSize', 'since', 'spanMs', 'stableMs', 'timeoutMs',
+]);
+
 function parseArgs(argv) {
   const flags = {};
   const positional = [];
-  for (const arg of argv) {
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
     if (arg.startsWith('--')) {
       const [key, value] = arg.slice(2).split('=');
       const camel = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-      flags[camel] = value === undefined ? true : value;
+      if (value !== undefined) {
+        flags[camel] = value;
+      } else if (VALUE_FLAGS.has(camel) && argv[i + 1] != null && !argv[i + 1].startsWith('--')) {
+        // `--device X` as well as `--device=X`. Only for flags whose bare form
+        // means nothing: `simframe doctor --device B55AB0AE` used to set
+        // `device` to `true`, push the udid to positional, and resolve the
+        // literal string "true" — and doctor's own advice is to name a device
+        // with --device, which is exactly how someone would write it.
+        flags[camel] = argv[i + 1];
+        i += 1;
+      } else {
+        flags[camel] = true;
+      }
     } else {
       positional.push(arg);
     }
@@ -218,6 +243,11 @@ async function main() {
         `stopped ${stopped} daemon${stopped === 1 ? '' : 's'}` +
           (inUse ? `; left ${inUse} in use by another client (pass --force to stop anyway)` : ''),
       );
+      // Asked to stop one device, refused, and exited 0 — which is a success
+      // code for work not done, and a script checking `$?` could not tell the
+      // difference. `--all` is informational by nature, so it keeps exiting 0
+      // when it skips a device somebody else holds.
+      if (!flags.all && inUse && !stopped) process.exitCode = 1;
       return;
     }
 
@@ -800,6 +830,25 @@ async function doctor({ json = false, strict = false, device } = {}) {
       const wanted = await resolveDevice(device);
       booted = booted.filter((d) => d.udid === wanted.udid);
     }
+    // Which devices get *probed*, as opposed to listed. The probes below start
+    // a capture loop and read frames, and doctor used to do that to every
+    // booted device on the host. On a shared machine that means starting a
+    // daemon on a colleague's simulator and capturing their screen to answer a
+    // question about this one. Listing is free and stays; probing is not, so
+    // without --device it goes to a device already running its own capture loop
+    // (nothing new is started), or to the only booted device, and otherwise to
+    // none, with a line saying which flag would pick one.
+    let probed = booted;
+    if (!device && booted.length > 1) {
+      probed = booted.filter((d) => engineModule.runningEngine(d.udid));
+      if (probed.length !== 1) {
+        probed = [];
+        add('device probes', 'warn',
+          `${booted.length} devices are booted and none is clearly yours — name one with --device ` +
+            'to check its capture, input and accessibility layers',
+          { key: 'probes.skipped', value: booted.length });
+      }
+    }
     // `deviceNoun` earns its place here: one platform's devices are called by
     // its own word, and a mixed set by the neutral one. An emulator reported as
     // a "booted simulator" is the same small lie as an emulator reported as
@@ -807,7 +856,7 @@ async function doctor({ json = false, strict = false, device } = {}) {
     const nouns = [...new Set(booted.map((d) => capabilitiesFor(d.udid) && PLATFORMS[d.platform].deviceNoun))];
     add(`booted ${nouns.length === 1 ? nouns[0] : 'device'}`, booted.length ? 'ok' : 'warn',
       booted.map((d) => `${d.name} (${d.runtime})`).join(', ') || 'none');
-    for (const d of booted) {
+    for (const d of probed) {
       const input = await import('./input.js');
       const control = await import('./control.js');
       // What this device's platform can do at all. Without asking, doctor
@@ -871,9 +920,9 @@ async function doctor({ json = false, strict = false, device } = {}) {
         ax.available ? `${ax.name}: ${ax.version}` : `unavailable: ${ax.reason}`,
         { key: 'ax.driver', value: ax.name });
     }
-    if (booted.length) {
+    if (probed.length) {
       const t0 = Date.now();
-      const res = await api.getFrame(booted[0].udid);
+      const res = await api.getFrame(probed[0].udid);
       add('capture', 'ok',
         `frame #${res.state.seq} ${res.width}x${res.height} in ${Date.now() - t0}ms (age ${res.ageMs}ms)`,
         { key: 'capture.frames', value: res.state.seq });
@@ -881,7 +930,7 @@ async function doctor({ json = false, strict = false, device } = {}) {
       // to ask the capture loop rather than look at the frames. `fail`, not
       // `warn`: nothing here is degraded-but-working, and the cure is a device
       // restart that simframe deliberately does not perform.
-      for (const d of booted) {
+      for (const d of probed) {
         const live = api.liveness(d.udid, (await api.getState(d.udid)).state);
         if (live.stalled) add(`capture health (${d.name})`, 'fail', live.note, { key: 'capture.stalled', value: true });
       }
@@ -893,8 +942,21 @@ async function doctor({ json = false, strict = false, device } = {}) {
   // doctor is a diagnostic, not a way to start things. If it had to start a
   // daemon to answer "which engine is in use", it stops it again rather than
   // leaving a detached process behind.
+  //
+  // And it says when it could not. This was `catch { /* best effort */ }`, and
+  // best effort silently failed: a stop refused because another client holds
+  // the device left a capture loop running on a machine somebody else was
+  // using, with doctor reporting a clean bill of health. A diagnostic that
+  // leaves something behind has to name it.
   for (const udid of startedHere) {
-    try { await api.stopDaemon(udid); } catch { /* best effort */ }
+    try {
+      await api.stopDaemon(udid);
+    } catch (err) {
+      add('cleanup', 'warn',
+        `started a capture loop on ${udid} to answer a question and could not stop it again ` +
+          `(${err.message}) — stop it with: simframe stop --device=${udid}`,
+        { key: 'cleanup.left', value: udid });
+    }
   }
 
   const failed = checks.filter((c) => c.level === 'fail');

package/src/daemon.js

@@ -159,6 +159,12 @@ export async function runDaemon(device, options = {}) {
         store.writeCaptureHealth(udid, null);
       }
       consecutiveErrors = 0;
+      // And the clock, which it did not. A second stall then kept the first
+      // one's timestamp — `stalledSince ??=` only fills a null — and reported
+      // "unreadable for 4 hours" about a wedge four seconds old. The Swift loop
+      // resets it (main.swift), which is what made this a missed line rather
+      // than a difference of opinion between the two engines.
+      stalledSince = null;
 
       const hash = frameHash(bmp);
       const layout = layoutHash(bmp);

package/src/index.js

@@ -223,9 +223,19 @@ function spawnNodeDaemon(udid, options) {
   for (const key of ['fps', 'maxDim', 'ringSize', 'idleExitMs']) {
     if (options[key] != null) args.push(`--${key}=${options[key]}`);
   }
+  // stderr goes to the device's own log, the way the Swift daemon's does
+  // (engine.js). It was `stdio: 'ignore'`, so anything this loop said about
+  // itself went to /dev/null — including the Android backend's notice that the
+  // console capture path had failed and it had fallen back to adb at five times
+  // the latency. A silent fallback is the failure mode this project has been
+  // bitten by twice; it does not get a third time for want of a file handle.
+  // The directory may not exist yet on a first start, and `writeCaptureHealth`
+  // already taught this project that an unwritable path here fails silently.
+  fs.mkdirSync(store.paths(udid).dir, { recursive: true });
+  const log = fs.openSync(store.paths(udid).log, 'a');
   const child = spawn(process.execPath, args, {
     detached: true,
-    stdio: 'ignore',
+    stdio: ['ignore', log, log],
     env: process.env,
   });
   child.unref();

package/src/input.js

@@ -3,7 +3,7 @@
 // even available?" before it answers anything else.
 import { execFile } from 'node:child_process';
 import * as control from './control.js';
-import { geometryFor, inputDriverFor } from './platform/index.js';
+import { capabilitiesFor, geometryFor, inputDriverFor, setPasteboard } from './platform/index.js';
 import { promisify } from 'node:util';
 
 const run = promisify(execFile);
@@ -207,6 +207,14 @@ export async function describeAll(udid) {
       /* daemon went away mid-call; fall through to idb */
     }
   }
+  // A platform with no accessibility tree is not a machine missing idb.
+  // `doctor` learned that when it reported "input driver: idb" for an emulator;
+  // this path had not, so every Android screen map carried a note telling the
+  // reader to brew-install a tool that has never spoken to an Android device —
+  // and on a machine where idb *is* installed, spawned it against an emulator
+  // serial on every map build.
+  const ax = capabilitiesFor(udid).ax;
+  if (!ax.supported) throw new Error(`no accessibility tree on this device — ${ax.note}`);
   // Passing --json here yields empty output; the default already emits JSON.
   const out = await idb(['ui', 'describe-all', '--udid', udid]);
   const nodes = [];
@@ -357,6 +365,39 @@ export async function typeText(udid, value) {
   await idb(['ui', 'text', '--udid', udid, String(value)]);
 }
 
+/**
+ * Put text on the pasteboard **and deliver it** into the focused field.
+ *
+ * The delivery is the whole point, and it is what was missing: the `paste` step
+ * used to set the pasteboard, long-press the field, and report success while
+ * the field stayed empty — on both platforms, not just the one it was filed
+ * against. iOS had the mechanism and did not use it (the daemon's `paste` is
+ * pbcopy *plus* Cmd-V) and Android had the keycode sitting unused in `KEYS`.
+ *
+ * When nothing can deliver the keystroke this throws rather than returning a
+ * cheerful description of half the job. A step that cannot do what it says has
+ * to say so; `type` still works on every device.
+ */
+export async function pasteText(udid, value) {
+  const own = inputDriverFor(udid);
+  if (own?.key) {
+    // The clipboard goes over gRPC; KEYCODE_PASTE is what puts it in the field.
+    await setPasteboard(udid, String(value));
+    await own.key(udid, 'paste');
+    return;
+  }
+  if (control.available(udid)) {
+    // One round trip: the daemon copies and presses Cmd-V.
+    await control.paste(udid, String(value));
+    return;
+  }
+  await setPasteboard(udid, String(value));
+  throw new Error(
+    'the text is on the pasteboard but nothing here can paste it: the keystroke needs the simframe ' +
+      'daemon (start it with `simframe start`), or use `type`, which carries the characters itself',
+  );
+}
+
 /** Key events rather than text: for shortcuts and search-as-you-type. */
 export async function typeKeys(udid, value) {
   const own = inputDriverFor(udid);

package/src/navigate.js

@@ -51,6 +51,13 @@ export async function goto(deviceQuery, target, { options, ...runOptions } = {})
     return { ok: true, already: true, screen: found.name, steps: [] };
   }
 
+  // `hashTokens` returns null for an empty token set on purpose — a constant
+  // hash for "I could read nothing" is the self-confirming-emptiness bug. So a
+  // screen with no identity has to be reported, not sliced: this threw
+  // `Cannot read properties of null (reading 'slice')` instead of answering.
+  // Not hypothetical on Android, where README's own table puts the launcher at
+  // one token.
+  if (!here.hash) return { ok: false, reason: 'no-identity', to: found.name };
   const path_ = graph.route(udid, { hash: here.hash, tokens: here.tokens }, found.node.hash);
   if (!path_) return { ok: false, reason: 'no-route', from: here.hash.slice(0, 8), to: found.name };
 
@@ -65,7 +72,7 @@ export async function goto(deviceQuery, target, { options, ...runOptions } = {})
     steps,
     ranSteps: result.ranSteps,
     results: result.results,
-    arrived: arrived.hash.slice(0, 8),
+    arrived: arrived.hash ? arrived.hash.slice(0, 8) : null,
   };
 }
 

package/src/platform/android.js

@@ -10,6 +10,10 @@
 // below, and the reason two of them are not the obvious command:
 //
 //   emulator console `screenrecord screenshot <dir>`     20 ms, written host-side
+//
+// Those are screenshot costs. A *frame* — screenshot plus the resize that makes
+// it readable — measures 41 ms, which is the number README quotes; the two were
+// quoted interchangeably in three files and agreed with each other in none.
 //   adb exec-out screencap -p                           113 ms, 9 KB over adb
 //   adb exec-out screencap (raw RGBA, 3.7 MB)           218 ms — the transfer, not the encode
 //   adb shell getprop x4 in one hop                      28 ms
@@ -107,7 +111,14 @@ async function fetchDevices() {
   const serials = [];
   for (const line of stdout.split('\n').slice(1)) {
     const [serial, state] = line.trim().split(/\s+/);
-    if (serial && state) serials.push({ serial, adbState: state });
+    // Only emulators. Physical devices are a stated non-goal, and this list is
+    // "devices simframe can drive" — `ownsUdid` claims emulator serials and
+    // nothing else, so listing a plugged-in phone here made listing and routing
+    // disagree: `devices` offered it, a bare `resolveDevice` could return it,
+    // and the tap that followed failed with a complaint about the serial rather
+    // than an honest "not supported". A unit test asserts the two agree; it
+    // passed only because nobody had a phone attached.
+    if (serial && state && ownsUdid(serial)) serials.push({ serial, adbState: state });
   }
   const out = [];
   for (const { serial, adbState } of serials) {
@@ -165,6 +176,18 @@ async function resolveDevice(query, opts) {
           : 'no booted emulator (start one with `emulator -avd <name>`)',
       );
     }
+    // See the same guard in ios.js: an arbitrary pick is a tap on the wrong
+    // device, and this backend can act too.
+    if (booted.length > 1) {
+      throw Object.assign(
+        new Error(
+          `${booted.length} emulators are running and none was named: ` +
+            `${booted.map((d) => `${d.name} (${d.udid})`).join(', ')} — name one with --device, ` +
+            'or set SIMFRAME_DEVICE to pick a default for this shell',
+        ),
+        { ambiguous: true },
+      );
+    }
     return booted[0];
   }
   const q = loose(query);
@@ -556,6 +579,12 @@ async function screenshot(udid, outFile, { mask: _mask = 'ignored' } = {}) {
     try {
       const { stdout } = await adb(udid, ['exec-out', 'screencap', '-p'], { encoding: 'buffer', timeout: 20_000 });
       fs.writeFileSync(outFile, stdout);
+      // stderr, not a store write: a backend below the boundary has no business
+      // knowing where simframe keeps its files. The capture loop is now spawned
+      // with its stderr pointed at `daemon.log` (src/index.js), which is what
+      // makes this line readable at all — it used to go to a daemon started
+      // `stdio: 'ignore'`, so a five-times-slower capture path could be in
+      // effect for a whole session with no trace of it anywhere.
       process.env.SIMFRAME_QUIET === '1' ||
         process.stderr.write(`simframe: emulator console unavailable (${consoleErr.message}); used adb screencap\n`);
     } catch (adbErr) {
@@ -796,7 +825,14 @@ async function launchApp(udid, bundleId, { args = [], env = {}, terminateFirst =
 }
 
 async function terminateApp(udid, bundleId) {
-  await adb(udid, ['shell', 'am', 'force-stop', bundleId]);
+  // `am` reports failure on stdout and still exits 0 — the same trap launchApp
+  // and openUrl already check for. Without this, terminating a package that is
+  // not installed answered "terminated com.typo.app".
+  const { stdout, stderr } = await adb(udid, ['shell', 'am', 'force-stop', bundleId]);
+  const error = /^Error:.*$/m.exec(`${stdout}${stderr}`);
+  if (error) {
+    throw new Error(`could not terminate ${bundleId}: ${error[0].replace(/^Error:\s*/, '')}`);
+  }
 }
 
 async function openUrl(udid, url) {
@@ -928,10 +964,15 @@ function toolchain() {
  * There is no framebuffer engine, so `screenshot` is not a downgrade on this
  * platform and doctor must not report it as one.
  *
- * Input and the accessibility tree: not yet, and said so rather than answered
- * with the iOS driver's name. Both paths are measured and unwired — the console's
- * `event mouse` puts a real down/move/up on the touch screen in ~20 ms, and
- * `uiautomator dump` costs 2 s a read, which is the interesting problem.
+ * Input: yes, through the emulator console — `event mouse` puts a real
+ * down/move/up on the touch screen, and `event text` carries characters rather
+ * than key positions, so a non-Latin host layout cannot reinterpret them. This
+ * comment said "not yet" for a release after it shipped; a stale comment above
+ * a live value is worse than no comment, because the next reader believes it.
+ *
+ * The accessibility tree: no, and said so rather than answered with the iOS
+ * driver's name. `uiautomator dump` costs 2,012 ms a read, which is why it is
+ * not the answer; see docs/DEFERRED.md for the shape of the one that would be.
  */
 function capabilities() {
   return {

package/src/platform/index.js

@@ -147,18 +147,30 @@ export async function bootedDevices(opts) {
  * device is the wrong-device bug wearing a different hat.
  *
  * Cross-platform ambiguity — one name matching a simulator and an emulator — is
- * reported rather than guessed at. Which of them a bare query should prefer is
- * a question for the step that adds the second backend, not one to invent an
- * answer to here.
+ * reported rather than guessed at, and so is a *bare* query on a host with a
+ * booted device on both platforms. That case is not exotic: it is the mixed
+ * setup the second backend exists for, and it used to break every command that
+ * did not name a device, with the word "undefined" standing in for the query.
+ *
+ * There is no defensible way to pick for you. Preferring iOS because it came
+ * first would silently tap a simulator while you were driving an emulator,
+ * which is the one failure this project will not ship. So a bare query on a
+ * mixed host says so and names both devices — and `SIMFRAME_DEVICE` exists so
+ * the answer can be given once per shell instead of on every command.
  *
  * @returns {Promise<Device>}
  */
 export async function resolveDevice(query, opts) {
-  return resolveAcross(query, opts, backends());
+  return resolveAcross(query ?? process.env.SIMFRAME_DEVICE ?? undefined, opts, backends());
 }
 
 /** As above, over a given set of backends — the testable half. @returns {Promise<Device>} */
 export async function resolveAcross(query, opts, all) {
+  // A backend is entitled to assume a query is a string. `--device X` used to
+  // parse as `device: true`, which reached ios.js as `query.toLowerCase` and
+  // crashed with a TypeError where an unmatched device should have been a
+  // sentence. The parser no longer produces that, and this makes it unable to.
+  if (query != null && typeof query !== 'string') query = String(query);
   const hits = [];
   const misses = [];
   for (const backend of all) {
@@ -171,9 +183,12 @@ export async function resolveAcross(query, opts, all) {
   }
   if (hits.length === 1) return hits[0];
   if (hits.length > 1) {
+    const named = hits.map((d) => `${d.name} (${d.platform}, ${d.udid})`).join(', ');
     throw new Error(
-      `"${query}" matches a device on more than one platform: ` +
-        `${hits.map((d) => `${d.name} (${d.platform})`).join(', ')} — name one by its id`,
+      (query == null || query === ''
+        ? 'no device named, and there is a booted device on more than one platform'
+        : `"${query}" matches a device on more than one platform`) +
+        `: ${named} — name one by its id, or set SIMFRAME_DEVICE to pick a default`,
     );
   }
   // One backend: its own message, unchanged. It is the better message, because

package/src/platform/ios.js

@@ -66,6 +66,29 @@ async function resolveDevice(query, opts) {
   const booted = all.filter((d) => d.state === 'Booted');
   if (!query) {
     if (booted.length === 0) throw new Error('no booted simulator (open Simulator.app or run `xcrun simctl boot <udid>`)');
+    // `booted[0]` was the wrong-device bug, and it was worse than it looked.
+    // simctl's order is not "yours" by any definition, so on a machine with
+    // more than one booted simulator a bare `simframe ui` read whichever came
+    // first — and a bare `simframe tap` would have *injected input* into it. A
+    // reviewer reproduced it deterministically against a colleague's simulator.
+    //
+    // `doctor` got a guard for its own fan-out and this default did not, which
+    // is how the same command set could pick two different devices in one
+    // moment. Refusing is the only safe answer here: the seam cannot see which
+    // device simframe is already driving (that is store state, above the
+    // boundary), and a backend must never guess when the cost of guessing wrong
+    // is a tap on somebody else's screen. `ambiguous` so that a second platform
+    // matching cleanly cannot override this — see resolveAcross.
+    if (booted.length > 1) {
+      throw Object.assign(
+        new Error(
+          `${booted.length} simulators are booted and none was named: ` +
+            `${booted.map((d) => `${d.name} (${d.udid})`).join(', ')} — name one with --device, ` +
+            'or set SIMFRAME_DEVICE to pick a default for this shell',
+        ),
+        { ambiguous: true },
+      );
+    }
     return booted[0];
   }
   const q = query.toLowerCase();