simframe 0.13.0 → 0.14.1

package/src/actions.js

@@ -2555,7 +2555,7 @@ async function runStep(deviceQuery, udid, step, ctx) {
         for (let attempt = 0; ; attempt += 1) {
           for (const one of alternatives) {
             try {
-              const found = await api.locate(deviceQuery, one, { refresh: attempt > 0 });
+              const found = await api.locate(deviceQuery, one, { refresh: step.refresh !== false, options: ctx.options });
               return `${JSON.stringify(one)} appeared at ${found.target.x},${found.target.y}`
                 + ` (first of ${alternatives.length} awaited)`;
             } catch (err) {
@@ -2563,10 +2563,12 @@ async function runStep(deviceQuery, udid, step, ctx) {
             }
           }
           if (Date.now() >= limit) {
+            const stillAny = await stillnessNote(deviceQuery, ctx);
             throw new Error(
               `none of ${alternatives.length} awaited strings appeared`
               + ` (${alternatives.map((a) => JSON.stringify(a)).join(', ')}) in ${step.timeoutMs ?? 8000}ms.`
-              + ` Last: ${lastError}`,
+              + ` Last: ${lastError}`
+              + (stillAny ? ` (${stillAny.note})` : ''),
             );
           }
           await api.waitFor(deviceQuery, { mode: 'stable', stableMs: 200, timeoutMs: 700, options: ctx.options })
@@ -2575,7 +2577,26 @@ async function runStep(deviceQuery, udid, step, ctx) {
       }
       for (let attempt = 0; ; attempt += 1) {
         try {
-          const found = await api.locate(deviceQuery, query, { index: step.index, refresh: attempt > 0 });
+          // Fresh, like `assert` — and for the same reason, found the same way.
+          //
+          // This read `refresh: attempt > 0`, so the FIRST look resolved against
+          // the remembered map. A wait that can be satisfied by memory is not a
+          // wait: if recall hands back the wrong screen's map — which it does
+          // when two screens collide on a layout hash — the target "appears"
+          // without ever having been on screen, instantly, and the caller
+          // proceeds against a screen it is not on.
+          //
+          // Caught by the fingerprint eval on CI, which is the only place it
+          // could show: `settings-general` read the **Settings root** and its
+          // `waitFor "About"` had passed. The signature is in the round numbers
+          // — r2 and r3, never r1 — because memory has to be warm before it can
+          // lie, and round 1 is always cold.
+          //
+          // `assert` was made fresh by default after this exact defect cost a
+          // reported session; `waitFor` was left as it was. One perception pass
+          // is the price, and it is the same trade: a read is cheaper than the
+          // round trip a wrong verdict causes.
+          const found = await api.locate(deviceQuery, query, { index: step.index, refresh: step.refresh !== false, options: ctx.options });
           return `"${found.target.label}" appeared at ${found.target.x},${found.target.y}`;
         } catch (err) {
           lastError = err.message;
@@ -2609,9 +2630,23 @@ async function runStep(deviceQuery, udid, step, ctx) {
           }
         }
         if (Date.now() >= limit) break;
+        // Opt-in: stop early on a screen that has plainly stopped changing.
+        if (Number.isFinite(step.failIfStillFor)) {
+          const still = await stillnessNote(deviceQuery, ctx);
+          if (still && still.ms >= step.failIfStillFor) {
+            throw new Error(`gave up on ${query} after ${Date.now() - (limit - (step.timeoutMs ?? 8000))}ms:`
+              + ` ${still.note}, which is past the ${step.failIfStillFor}ms you said to stop at.`
+              + ` Last: ${lastError}`);
+          }
+        }
         await sleep(POLL_MS);
       }
-      throw new Error(`waited ${step.timeoutMs ?? 8000}ms for ${query}: ${lastError}`);
+      // Say how long it had been still. A wait that burned three minutes on a
+      // screen static for the last twelve seconds should not make the reader
+      // work that out from a second command.
+      const still = await stillnessNote(deviceQuery, ctx);
+      throw new Error(`waited ${step.timeoutMs ?? 8000}ms for ${query}: ${lastError}`
+        + (still ? ` (${still.note} — pass failIfStillFor to stop early next time)` : ''));
     }
 
     // One assert step for every condition, because `assertText` could only ask
@@ -2639,6 +2674,32 @@ async function runStep(deviceQuery, udid, step, ctx) {
         // is the opposite of what you want learned."*
         found = await api.locate(deviceQuery, query, { index: step.index, refresh: step.refresh !== false, options: ctx.options });
       } catch (err) {
+        // Ambiguity answers "is it there", and it answers it *yes*.
+        //
+        // `locate` refuses a query that matches several elements, which is right
+        // for `tap` — picking the wrong one of two taps the wrong thing — and
+        // wrong for a question about presence. Reported from the field on
+        // 0.13.0: `assert Administrator is visible` failed, and aborted the rest
+        // of the batch, against a screen with **two** Administrators on it. The
+        // assertion's own semantics were satisfied twice over. The message was
+        // praised in the same breath — candidates, coordinates and scores — so
+        // what was wrong was the verdict, not the diagnosis.
+        //
+        // The `gone` direction had the mirror-image bug and nobody had hit it
+        // yet: any error at all returned "is gone", so a query matching two
+        // visible elements would have reported them absent. Ambiguity is the one
+        // error that is positive evidence of presence, and it was being read as
+        // proof of absence.
+        //
+        // Strict single-match resolution stays for `enabled`, `disabled` and
+        // `value`, where the question is about a *particular* element and
+        // answering it from the wrong one is how a confident wrong answer gets
+        // made.
+        if (err.ambiguous && err.candidates?.length) {
+          const n = err.candidates.length;
+          if (want === 'visible') return `${query} is visible (${n} things match it here — a presence check does not have to choose)`;
+          if (want === 'gone') throw new Error(`${query}: still here — ${n} things on this screen match it`);
+        }
         if (want === 'gone') return `${query} is gone`;
         throw new Error(`${query}: ${err.message}`);
       }
@@ -2744,3 +2805,55 @@ export function settleEvidence(w) {
   return (parts.length ? parts.join('; ') : 'nothing observed')
     + (m ? `\n${m.map}` : '');
 }
+
+/**
+ * The one-line flow summary, so `ok` and `FAIL` each mean exactly one thing.
+ *
+ * `FLOW FAILED — 3/3 steps` was reported from the field as reading like a
+ * success, and the reporter had it exactly: the denominator means *attempted*
+ * on failure and *succeeded* on success, so the same shape carries opposite
+ * meanings. `flow completed — 5/5 steps` and `FLOW FAILED — 3/3 steps` differ
+ * only in a word, and the numbers argue against the word.
+ *
+ * On failure it says how many worked and how many did not, which is the thing a
+ * caller has to know to decide whether to resume or re-plan.
+ */
+export function flowSummary(res, { withTime = true } = {}) {
+  const time = withTime && Number.isFinite(res.totalMs) ? ` in ${res.totalMs}ms` : '';
+  if (res.ok) return `flow completed — ${res.ranSteps}/${res.totalSteps} steps${time}`;
+  const failed = (res.results ?? []).filter((r) => r.ok === false).length || 1;
+  const worked = Math.max(0, res.ranSteps - failed);
+  const unattempted = Math.max(0, res.totalSteps - res.ranSteps);
+  return `FLOW FAILED — ${worked} ok, ${failed} failed`
+    + (unattempted ? `, ${unattempted} not attempted` : '')
+    + ` (of ${res.totalSteps})${time}`;
+}
+
+/**
+ * How long the screen has been still, for a wait that is about to give up.
+ *
+ * A field report: a 180-second wait for a control that never appeared, on a
+ * screen that had been static for about twelve of those seconds — the app had
+ * logged itself out and was sitting on a login form. The failure message was
+ * praised for listing what *was* on screen; it arrived three minutes late.
+ *
+ * Stillness is already tracked and already printed by other commands, so the
+ * information existed and this wait simply never asked for it. Reported on
+ * every timeout, and — only when the caller opts in — allowed to end the wait
+ * early. Opt-in and not default, because a still screen is exactly what a
+ * pending network call looks like: the target may yet arrive, and a wait that
+ * gave up on stillness alone would break the case waits exist for.
+ *
+ * This is only trustworthy because of 134. Before the animation threshold was
+ * measured, a completely static screen claimed something was animating on 54%
+ * of its frames, and "nothing has moved" could not be said with a straight face.
+ */
+async function stillnessNote(deviceQuery, ctx) {
+  try {
+    const { state } = await api.getState(deviceQuery, { options: ctx.options });
+    const ms = state?.stableForMs;
+    return Number.isFinite(ms) ? { ms, note: `the screen has not moved for ${Math.round(ms)}ms` } : null;
+  } catch {
+    return null;
+  }
+}

package/src/cli.js

@@ -12,6 +12,7 @@ import * as baseline from './baseline.js';
 import * as metrics from './metrics.js';
 import * as navigate from './navigate.js';
 import { decodePng } from './png.js';
+import * as storage from './storage.js';
 import * as store from './store.js';
 import * as view from './view.js';
 
@@ -33,6 +34,7 @@ const USAGE = `simframe — always-warm iOS Simulator frames
   simframe tap     <selector>        tap #3, "Save", or @120,400
   simframe do      <script.json>     run a scripted flow (see below)
   simframe screens [device]          list screens this device has learned
+  simframe storage [bundle-id]       what the app saved (works on a shut-down device)
   simframe goto    <screen>          walk to a known screen through known steps
   simframe flow    save <name> <script.json>   run a flow and save it if every step verifies
   simframe flow    run  <name>       replay a saved flow
@@ -801,7 +803,7 @@ async function main() {
         },
         [
           ...res.results.map(stepLine),
-          `${res.ok ? 'flow completed' : 'FLOW FAILED'} — ${res.ranSteps}/${res.totalSteps} steps in ${res.totalMs}ms`,
+          actions.flowSummary(res),
           saved && (saved.ok ? `saved flow "${saved.name}" — ${saved.steps} steps` : `not saved: ${saved.reason}`),
           map && `\n${map}`,
         ],
@@ -860,6 +862,25 @@ async function main() {
       return;
     }
 
+    case 'storage': {
+      // A file read, like `screens`, and deliberately not a daemon call. The
+      // whole value of this command is that it answers on a device that is not
+      // running — measured: simctl itself cannot, on this Xcode. Routing it
+      // through the daemon would throw that away for no gain.
+      const device = await resolveDevice(flags.device);
+      const [bundleId] = positional;
+      if (!bundleId) {
+        const list = await storage.apps(device.udid);
+        const match = flags.match ? String(flags.match).toLowerCase() : null;
+        const shown = match ? list.filter((a) => a.bundleId.toLowerCase().includes(match)) : list;
+        emit(flags, shown, storage.formatApps(shown));
+        return;
+      }
+      const result = await storage.read(device.udid, bundleId);
+      emit(flags, result, storage.format(result));
+      return;
+    }
+
     case 'screens': {
       // Reading what this device has learned is a file read. It used to go
       // through ensureDaemon, so a device whose capture had stopped could not
@@ -920,7 +941,7 @@ async function main() {
         }
         emit(flags, res, [
           ...(res.results ?? []).map(stepLine),
-          `${res.ok ? 'flow completed' : 'FLOW FAILED'} — ${res.ranSteps}/${res.totalSteps} steps`,
+          actions.flowSummary(res, { withTime: false }),
         ]);
         process.exitCode = res.ok ? 0 : 1;
         return;

package/src/graph.js

@@ -396,7 +396,18 @@ export function describe(node) {
   if (tabs.length) return tabs.slice(0, 3).join(' / ');
   const anyChrome = labels(/:(nav-bar|tab-bar):/);
   if (anyChrome.length) return anyChrome.slice(0, 3).join(' ');
-  return node.hash.slice(0, 8);
+  // No name. Say so, rather than handing back a hash dressed as one.
+  //
+  // This fell back to `node.hash.slice(0, 8)`, and the map prints the name in
+  // quotes after the identity hash — so an unnamed screen read
+  // `screen 299dd147 "a9505378"`: two hashes, one of them looking like a title,
+  // beside the `screen 089bec77 "time sheets"` a named screen produces.
+  // Reported from the field, with the right fix attached: omit the quoted part
+  // rather than echo a second hash.
+  //
+  // Callers that need *something* to print in a list supply their own fallback,
+  // which is a decision about presentation and belongs at the point of display.
+  return null;
 }
 
 /** Find a known screen by what a human would call it. */
@@ -404,7 +415,9 @@ export function findScreen(udid, query) {
   const wanted = String(query ?? '').trim();
   if (!wanted) return null;
   const scored = allNodes(udid)
-    .map((node) => ({ node, name: describe(node) }))
+    // The short hash stays searchable: `goto 089bec77` worked before `describe`
+    // stopped inventing names and must keep working.
+    .map((node) => ({ node, name: describe(node) ?? node.hash.slice(0, 8) }))
     .map((c) => ({ ...c, score: matching.nameScore(c.name, wanted) }))
     .filter((c) => c.score > 0)
     .sort((a, b) => b.score - a.score);

package/src/matching.js

@@ -170,7 +170,23 @@ export function rank(targets, intent, { screen } = {}) {
     // An icon-only control has no readable name, so a synonym is the only way
     // to reach it — this is how "back" finds a bare chevron.
     if (group && base < 0.5 && !t.label && t.rawLabel) base = 0.55;
-    if (group && base < 0.5 && names.some((n) => group.words.includes(norm(n)))) base = 0.9;
+    // Genuine synonymy only: the name must be a *different* word in the group.
+    //
+    // This branch fires only when `base < 0.5`, which means its whole job is to
+    // overrule the coverage scaling the two branches in `nameScore` were taught
+    // — and when the query already contains the name literally, that scaling was
+    // the right answer and this flat 0.9 throws it away. Reported (138): a long
+    // descriptive phrase ending "…under Settings" scored a *heading* labelled
+    // "Settings" at 0.9 and the row the caller meant at 0.265, tapped the
+    // heading, and returned `ok [no visible change]` with an `or` list untried.
+    //
+    // A name the query spells out has already been scored on how much of the
+    // query it covers. What this branch is for is the case that scoring cannot
+    // see at all: "back" reaching a control labelled "Previous", "settings"
+    // reaching "Preferences". That is synonymy, and it is unaffected.
+    const spelledOut = (n) => bare.includes(norm(n)) || norm(intent).includes(norm(n));
+    if (group && base < 0.5
+      && names.some((n) => group.words.includes(norm(n)) && !spelledOut(n))) base = 0.9;
     if (base <= 0) continue;
 
     const reasons = [matched ? `label "${matched}"` : 'icon-only'];

package/src/mcp.js

@@ -15,7 +15,8 @@ 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 { bootedDevices, listDevices, permissionServices, resolveDevice } from './platform/index.js';
+import * as storage from './storage.js';
 import * as store from './store.js';
 import * as view from './view.js';
 
@@ -132,7 +133,7 @@ const TOOLS = [
         steps: {
           type: 'array',
           description:
-            'Ordered steps. Every selector below accepts "Save" | "#3" | "@120,400", in that order of preference. 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.',
+            'Ordered steps. Every selector below accepts "Save" | "#3" | "@120,400", in that order of preference. 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}} (add "failIfStillFor":15000 to stop early once the screen has plainly stopped changing — a 180s wait once burned three minutes on an app that had logged itself out; without it a timeout still reports how long the screen had been still), {"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: {
@@ -192,7 +193,19 @@ 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, ...modeProps, ...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.' },
+        failIfStillFor: {
+          type: 'number',
+          description: 'Give up early once the screen has not moved for this long and the target is still absent.'
+            + ' Off by default, because a still screen is also what a pending network call looks like —'
+            + ' use it when the thing you await would arrive with a visible change or not at all.'
+            + ' A timeout reports the stillness either way.',
+        },
+      },
       required: ['sel'],
     },
   },
@@ -386,10 +399,42 @@ const TOOLS = [
       required: ['action'],
     },
   },
+  {
+    name: 'sim_storage',
+    description:
+      'What the app saved, as text: its UserDefaults and (for React Native) its AsyncStorage, read straight out of'
+      + ' the data container. sim_ui says what is drawn; sim_storage says what the app believes — use it when the'
+      + ' screen and the behaviour disagree, or to check a value without driving the UI to it.'
+      + ' Works on a device that is NOT running, so it can answer before anything is booted.'
+      + ' Call with no bundleId to list the apps that have a container (match filters that list).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        bundleId: { type: 'string', description: 'The app to read, e.g. com.example.myapp. Omit to list apps instead.' },
+        match: { type: 'string', description: 'When listing, show only bundle ids containing this string.' },
+        ...deviceProp,
+        ...modeProps,
+      },
+    },
+  },
   {
     name: 'sim_devices',
-    description: 'List the booted devices simframe can drive — iOS simulators and Android emulators.',
-    inputSchema: { type: 'object', properties: {} },
+    description: 'List the devices simframe can drive — iOS simulators and Android emulators.'
+      + ' Booted ones by default; pass all to see every device on the host and its state.'
+      + ' Also reports which simframe build is answering.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        all: {
+          type: 'boolean',
+          description: 'Also account for devices that are shut down, grouped by runtime.',
+        },
+        match: {
+          type: 'string',
+          description: 'With all, list shut-down devices whose name or runtime contains this, in full.',
+        },
+      },
+    },
   },
 ];
 
@@ -560,7 +605,7 @@ export async function serve({ device: defaultDevice, options: baseOptions = {} }
             options,
           );
         case 'sim_wait_for':
-          return await oneStep(target, { waitFor: args.sel, timeoutMs: args.timeoutMs }, args, options);
+          return await oneStep(target, { waitFor: args.sel, timeoutMs: args.timeoutMs, failIfStillFor: args.failIfStillFor }, args, options);
         case 'sim_assert':
           return await oneStep(target, { assert: args.sel, is: args.is, equals: args.equals }, args, options);
         case 'sim_launch':
@@ -585,8 +630,10 @@ export async function serve({ device: defaultDevice, options: baseOptions = {} }
           return await flowRun(target, args, options);
         case 'sim_capture':
           return await capture(target, args, options);
+        case 'sim_storage':
+          return await appStorage(args);
         case 'sim_devices':
-          return await devices();
+          return await devices(args);
         default:
           throw new Error(`unknown tool ${req.params.name}`);
       }
@@ -935,7 +982,7 @@ function verdictLineFor(results) {
 
 function stepLines(res) {
   const lines = [
-    `${res.ok ? 'flow completed' : 'FLOW FAILED'} — ${res.ranSteps}/${res.totalSteps} steps in ${res.totalMs}ms`,
+    actions.flowSummary(res),
   ];
   for (const r of res.results) {
     const settle = r.settled
@@ -1142,12 +1189,94 @@ function listStateDirs() {
   }
 }
 
-async function devices() {
+/**
+ * What an app has persisted.
+ *
+ * Deliberately not a daemon call and deliberately not a `simctl` call. Measured
+ * on this Xcode, `simctl get_app_container` and `simctl listapps` both refuse on
+ * a device that is not running — so the one property that made the field
+ * reporter rate this the highest-leverage thing in their session, answering
+ * *before the device is booted*, is only reachable by reading the container off
+ * the host filesystem. That is what the backend does.
+ */
+async function appStorage({ bundleId, match: query, device } = {}) {
+  const resolved = await resolveDevice(device);
+  if (!bundleId) {
+    const list = await storage.apps(resolved.udid);
+    const needle = query ? String(query).toLowerCase() : null;
+    const shown = needle ? list.filter((a) => a.bundleId.toLowerCase().includes(needle)) : list;
+    return { content: [text(storage.formatApps(shown))] };
+  }
+  const result = await storage.read(resolved.udid, bundleId);
+  return { content: [text(storage.format(result))] };
+}
+
+async function devices({ all = false, match: query } = {}) {
   const booted = await bootedDevices();
-  if (!booted.length) return { content: [text('no booted devices')] };
   // 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)] };
+  // The build that is answering, on the one call every session starts with.
+  //
+  // Reported from the field: a session told to test 0.13.0 could not find out
+  // what it was running. The globally installed CLI said 0.12.2 while the MCP
+  // server ran from a checkout, and answering "am I on the build under test?"
+  // took three shell calls and a read of `~/.claude.json`. A tool being field
+  // tested should be able to state its own build, and this is the cheapest
+  // place to put it.
+  const head = `simframe ${packageVersion()}`;
+  if (!all) {
+    if (!booted.length) {
+      // Never a bare "no devices". The host almost always has some, they are
+      // just off, and the reporter who hit this fell out of the tool entirely
+      // and went to `xcrun simctl` — for a tool whose whole job is driving
+      // simulators, that is the conspicuous hole.
+      const every = await listDevices().catch(() => []);
+      return { content: [text(`${head}\n\nno booted devices`
+        + (every.length ? ` — the host has ${every.length}, all shut down. Pass all:true to see them.` : ''))] };
+    }
+    const list = booted.map((d) => `● ${d.name} · ${d.runtime} · ${d.udid}`).join('\n');
+    return { content: [text([head, clash, list].filter(Boolean).join('\n\n'))] };
+  }
+  const every = await listDevices();
+  if (!every.length) return { content: [text(`${head}\n\nno devices on this host`)] };
+
+  // Summarised, not dumped.
+  //
+  // The first version of this listed every device in full and produced **126
+  // rows** on this host — two thousand tokens to answer "what else is here",
+  // from a tool whose entire argument is that text beats a screenshot because
+  // it is cheaper. A listing that costs more than the screenshot it replaces has
+  // lost the plot.
+  //
+  // So: booted devices in full, because those are the ones a caller can act on,
+  // and the rest grouped by runtime with counts. `match` lists in full, because
+  // a caller who names what they are looking for has already narrowed it.
+  const wanted = String(query ?? '').trim().toLowerCase();
+  const off = every.filter((d) => d.state !== 'Booted');
+  const lines = [head, clash].filter(Boolean);
+  lines.push(booted.length
+    ? booted.map((d) => `● ${d.name} · ${d.runtime} · ${d.udid}`).join('\n')
+    : 'no booted devices');
+
+  const hits = wanted
+    ? off.filter((d) => `${d.name} ${d.runtime}`.toLowerCase().includes(wanted))
+    : [];
+  if (wanted) {
+    lines.push(hits.length
+      ? `shut down, matching "${query}":\n`
+        + hits.map((d) => `○ ${d.name} · ${d.runtime} · ${d.udid}`).join('\n')
+      : `no shut-down device matches "${query}" (${off.length} are shut down)`);
+  } else if (off.length) {
+    const byRuntime = new Map();
+    for (const d of off) byRuntime.set(d.runtime, (byRuntime.get(d.runtime) ?? 0) + 1);
+    const summary = [...byRuntime.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .map(([runtime, n]) => `  ${runtime} — ${n}`)
+      .join('\n');
+    lines.push(`${off.length} device(s) shut down, by runtime:\n${summary}\n`
+      + 'pass match to list the ones you mean, e.g. match:"iPhone 17 Pro".');
+  }
+  lines.push('simframe cannot drive a device until it is booted.');
+  return { content: [text(lines.join('\n\n'))] };
 }

package/src/navigate.js

@@ -133,7 +133,10 @@ export async function goto(deviceQuery, target, { options, ...runOptions } = {})
 }
 
 export function knownScreens(udid) {
-  return graph.allNodes(udid).map((n) => ({ name: graph.describe(n), hash: n.hash.slice(0, 8), edges: n.edges.length }));
+  // A listing needs a handle for every row, so an unnamed screen falls back to
+  // its own short hash here — where it is plainly the hash column's value and
+  // not a title in quotes.
+  return graph.allNodes(udid).map((n) => ({ name: graph.describe(n) ?? n.hash.slice(0, 8), hash: n.hash.slice(0, 8), edges: n.edges.length }));
 }
 
 /**

package/src/platform/android.js

@@ -1018,6 +1018,37 @@ async function restartDevice(serial) {
   );
 }
 
+/**
+ * Reading an app's own storage is not implemented for Android, and says so.
+ *
+ * Not a stub and not a borrowed answer. The iOS version reads a CoreSimulator
+ * data container straight off the host filesystem, which an emulator has no
+ * equivalent of: an app's files live inside the emulator's own userdata image,
+ * and the way in is `adb shell run-as <package>` — which works only for a
+ * debuggable build, needs the emulator running, and would be a different
+ * feature with different guarantees rather than the same one.
+ *
+ * The standing rule is that a layer a platform does not have is declined with a
+ * reason, never described in the other platform's vocabulary. Claiming a data
+ * container here is how `doctor` once told an emulator its input driver was
+ * idb.
+ */
+const noStorage = (serial, what) => {
+  throw new Error(
+    `simframe cannot read ${what} on an emulator (${serial}) yet. The iOS version reads a`
+    + ' simulator data container off the host filesystem and an emulator has no such thing —'
+    + ' its app data lives inside the userdata image, reachable only through'
+    + ' `adb shell run-as <package>` on a debuggable build, with the emulator running.'
+    + ' That is a different feature and it has not been built.',
+  );
+};
+
+async function listApps(serial) { return noStorage(serial, 'the list of installed apps'); }
+async function appContainer(serial) { return noStorage(serial, "an app's data container"); }
+async function readPropertyList() {
+  throw new Error('property lists are an iOS format; Android has no equivalent to read');
+}
+
 /** @type {import('./index.js').Platform} */
 export const platform = {
   id: 'android',
@@ -1034,6 +1065,9 @@ export const platform = {
   terminateApp,
   openUrl,
   restartDevice,
+  listApps,
+  appContainer,
+  readPropertyList,
   setPermission,
   setPasteboard,
   getPasteboard,

package/src/platform/index.js

@@ -63,6 +63,7 @@ export const PLATFORM_SURFACE = Object.freeze([
   'geometry', 'inputDriver',
   'screenshot', 'launchApp', 'terminateApp', 'openUrl', 'restartDevice',
   'setPermission', 'setPasteboard', 'permissionServices', 'capabilities', 'toolchain',
+  'listApps', 'appContainer', 'readPropertyList',
   'bootedAt',
 ]);
 
@@ -209,6 +210,12 @@ export const openUrl = (udid, ...args) => platformFor(udid).openUrl(udid, ...arg
 export const setPermission = (udid, ...args) => platformFor(udid).setPermission(udid, ...args);
 export const setPasteboard = (udid, ...args) => platformFor(udid).setPasteboard(udid, ...args);
 
+// Reading what an app persisted. Routed like everything else, and declined by a
+// backend that has no equivalent rather than answered in the other's terms.
+export const listApps = (udid, ...args) => platformFor(udid).listApps(udid, ...args);
+export const appContainer = (udid, ...args) => platformFor(udid).appContainer(udid, ...args);
+export const readPropertyList = (udid, file) => platformFor(udid).readPropertyList(file);
+
 /**
  * The permission services a device understands, or every service any backend
  * understands when no device is named.