simframe 0.12.2 → 0.14.0

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.',
+        },
+      },
+    },
   },
 ];
 
@@ -459,7 +504,13 @@ function header(device, state, ageMs, extra = '') {
 }
 
 function livenessLine(live) {
-  return live?.ok ? null : `WARNING: ${live.note}`;
+  // `ok` is not the only thing worth saying. A surface that has stopped
+  // updating leaves every hard signal green — the loop is alive, no read
+  // failed, the frame is milliseconds old — and reporting nothing is how
+  // `sim_look` served a three-minute-old login screen while announcing it as
+  // 66ms old. A note that exists must reach the caller.
+  if (live?.note) return `WARNING: ${live.note}`;
+  return null;
 }
 
 function sinceLine(since) {
@@ -554,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':
@@ -579,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}`);
       }
@@ -929,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
@@ -1136,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/metrics.js

@@ -300,11 +300,30 @@ const VERIFYING_STEPS = new Set([
  */
 export function reasonForStepError(step, err) {
   const tagged = escalationOf(err);
-  if (tagged) return tagged;
+  if (tagged) return { ...tagged, classified: true };
   const action = step?.action;
-  if (action === 'confirm' || action === 'chooseAny') return { reason: 'novel_dialog', candidates: [], tried: [] };
-  if (VERIFYING_STEPS.has(action)) return { reason: 'verification_failed', candidates: [], tried: [] };
-  return { reason: 'verification_failed', candidates: [], tried: [] };
+  if (action === 'confirm' || action === 'chooseAny') {
+    return { reason: 'novel_dialog', candidates: [], tried: [], classified: true };
+  }
+  // Everything else is a *fallback*, and it now says so.
+  //
+  // This had two branches that returned the same value, which made it look
+  // like it discriminated. It does not: any step that threw without a site
+  // tagging it lands here. In a real field session that was **90% of all
+  // escalations** — and `FACULTY` then reported every one of them as evidence
+  // against "sense of time (Phase 11)", a claim nothing in the record supports.
+  //
+  // The tester's own first call failed with `unknown step "wait_for"` — a typo
+  // — and that too would be filed as evidence about which faculty to build
+  // next. CLAUDE.md calls this log the steering wheel; a steering wheel that
+  // pools typos, inert controls and slow lists into one reason is pointing
+  // somewhere nobody chose.
+  //
+  // No sixth reason: "unknown is not a reason" stays, and a vocabulary that
+  // admits "other" collects a pile of "other". What changes is that the record
+  // carries whether the reason was *read off the failure* or *assumed*, and
+  // the report declines to recommend a faculty for the assumed ones.
+  return { reason: 'verification_failed', candidates: [], tried: [], classified: false };
 }
 
 /**
@@ -440,6 +459,10 @@ export function recordEscalation(udid, {
   modelTurns = 1,
   wallMs = null,
   detail = null,
+  // Was this reason read off the failure, or assumed because nothing said?
+  // Default `false`, so a caller that does not think about it cannot
+  // accidentally claim precision it does not have.
+  classified = false,
 } = {}) {
   if (!REASONS.includes(reason)) throw new Error(`not an escalation reason: ${reason}`);
   if (!OUTCOMES.includes(outcome)) throw new Error(`not an escalation outcome: ${outcome}`);
@@ -455,6 +478,7 @@ export function recordEscalation(udid, {
     // What was asked for, in the caller's words. Ground truth for Phase 17's
     // go/no-go, and on its own it answers "what kind of decision is costing us".
     intent: intent ? String(intent).slice(0, 120) : null,
+    classified: Boolean(classified),
     step_index: stepIndex,
     screen_fingerprint: fingerprint,
     reason,
@@ -635,7 +659,9 @@ export function hpi({ flows, baselines = {} }) {
  */
 export function breakdown(records, { session = null, flow = null } = {}) {
   const byReason = {};
-  for (const r of REASONS) byReason[r] = 0;
+  const classifiedByReason = {};
+  const assumedByReason = {};
+  for (const r of REASONS) { byReason[r] = 0; classifiedByReason[r] = 0; assumedByReason[r] = 0; }
   const byScreen = new Map();
   const byOutcome = {};
   const bySession = new Map();
@@ -659,6 +685,12 @@ export function breakdown(records, { session = null, flow = null } = {}) {
     }
     if (r.flow_name) byFlow.set(r.flow_name, (byFlow.get(r.flow_name) ?? 0) + 1);
     byReason[r.reason] += 1;
+    // Three states, not two. A record written before this field existed makes
+    // no claim either way, and folding it in with "assumed" would make an old
+    // log look like a diagnosis failure — a warning that cries wolf is how a
+    // real one gets ignored, which this file already knows in another place.
+    if (r.classified === true) classifiedByReason[r.reason] += 1;
+    else if (r.classified === false) assumedByReason[r.reason] += 1;
     byOutcome[r.outcome] = (byOutcome[r.outcome] ?? 0) + 1;
     // Already avoided locally, so not avoidable by anything unbuilt.
     if (r.outcome !== 'resolved_locally') avoidable += 1;
@@ -685,9 +717,20 @@ export function breakdown(records, { session = null, flow = null } = {}) {
     pooled: sessions.length > 1 || unattributed > 0,
     by_flow: Object.fromEntries([...byFlow.entries()].sort((a, b) => b[1] - a[1])),
     by_reason: byReason,
+    // How many of each reason were *read off the failure* rather than assumed.
+    //
+    // The breakdown above picks the next phase, so its precision has to be
+    // visible in it. A reason that is mostly assumed is not a finding about an
+    // app; it is a count of things nothing could classify, and reading it as a
+    // verdict on a faculty is how the instrument came to disagree with a
+    // tester who was right.
+    classified_by_reason: classifiedByReason,
+    assumed_by_reason: assumedByReason,
     by_outcome: byOutcome,
+    // Only where the reason was actually read. A faculty named against a pile
+    // of assumptions is advice with nothing behind it.
     faculty: Object.fromEntries(
-      REASONS.filter((r) => byReason[r]).map((r) => [r, `${FACULTY[r]}${BUILT_FACULTIES.has(FACULTY[r]) ? ' [built]' : ''}`]),
+      REASONS.filter((r) => classifiedByReason[r]).map((r) => [r, `${FACULTY[r]}${BUILT_FACULTIES.has(FACULTY[r]) ? ' [built]' : ''}`]),
     ),
     avoidable,
     avoidable_escalation_rate: total ? Number((avoidable / total).toFixed(3)) : null,

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/ollama.js

@@ -49,13 +49,23 @@ export const DEFAULT_HOST = 'http://127.0.0.1:11434';
  * would produce exactly the invisible unfairness this function exists to
  * prevent.
  */
-export function readBrief(file = SWIFT) {
+export function readBrief(file = SWIFT, { mayAbstain = false } = {}) {
   const src = fs.readFileSync(file, 'utf8');
-  const open = src.indexOf('let instructions = """');
-  if (open === -1) throw new Error(`no instructions block in ${file}`);
+  const base = block(src, 'let instructions = """', file);
+  if (!mayAbstain) return base;
+  // The addendum, from the same file and joined the way the Swift joins it.
+  // The fourth word has to reach both arms identically or the comparison is
+  // measuring two different briefs, which is the failure this whole function
+  // exists to prevent.
+  return `${base}\n\n${block(src, 'let abstainInstructions = instructions + "\\n\\n" + """', file)}`;
+}
+
+function block(src, opener, file) {
+  const open = src.indexOf(opener);
+  if (open === -1) throw new Error(`no ${JSON.stringify(opener)} block in ${file}`);
   const bodyStart = src.indexOf('\n', open) + 1;
   const close = src.indexOf('"""', bodyStart);
-  if (close === -1) throw new Error(`unterminated instructions block in ${file}`);
+  if (close === -1) throw new Error(`unterminated block in ${file}`);
   return src
     .slice(bodyStart, close)
     .split('\n')
@@ -106,11 +116,28 @@ export function promptFor(s = {}) {
  * against would be a second difference between the arms, and the rationale is
  * the one thing a supervisor is explicitly not trusted for.
  */
-export const SCHEMA = {
+export const DECISION_WORDS = ['wait', 'retry', 'stop'];
+
+/**
+ * The fourth word, available on request.
+ *
+ * Not a new capability and it cannot become one: `abstain` means "behave as if
+ * there is no supervisor", which is the `null` every caller already handles on
+ * every failure path. It strictly *shrinks* what the model can cause to happen,
+ * which is why a component whose answer space is its safety property can afford
+ * to grow one.
+ */
+export const ABSTAIN = 'abstain';
+
+export const schemaFor = ({ mayAbstain = false } = {}) => ({
   type: 'object',
-  properties: { decision: { type: 'string', enum: ['wait', 'retry', 'stop'] } },
+  properties: {
+    decision: { type: 'string', enum: mayAbstain ? [...DECISION_WORDS, ABSTAIN] : DECISION_WORDS },
+  },
   required: ['decision'],
-};
+});
+
+export const SCHEMA = schemaFor();
 
 /** Parse `ollama`, `ollama:qwen3:14b`, `ollama:qwen3:8b@http://host:port`. */
 export function parseTarget(raw) {
@@ -147,15 +174,16 @@ async function post(host, route, body, timeoutMs) {
  */
 export async function ask(target, situation, timeoutMs = 2500) {
   const { model, host } = target;
+  const mayAbstain = Boolean(situation?.mayAbstain);
   const started = Date.now();
   const out = await post(host, '/api/chat', {
     model,
     messages: [
-      { role: 'system', content: readBrief() },
+      { role: 'system', content: readBrief(SWIFT, { mayAbstain }) },
       { role: 'user', content: promptFor(situation) },
     ],
     stream: false,
-    format: SCHEMA,
+    format: schemaFor({ mayAbstain }),
     // Qwen3 reasons out loud by default. Turned off for two reasons and both
     // are about fairness rather than speed: the Apple arm does not deliberate
     // either, and a supervisor that takes twenty seconds to answer has already

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.

package/src/platform/ios.js

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
+import * as plist from './plist.js';
 
 const run = promisify(execFile);
 
@@ -178,17 +179,42 @@ function isBootedSync(udid) {
   return false;
 }
 
+/**
+ * What went wrong with a `simctl io screenshot`, in one sentence.
+ *
+ * Extracted so it can be *tested* rather than reasoned about, for the same
+ * reason `pickDevice` and `decisionOf` were: this is the line where a wrong
+ * answer was expensive, and it was wrong for a day.
+ */
+export function screenshotFailure(err) {
+  const killed = err.killed || err.signal === 'SIGTERM';
+  // `simctl` opens with `Note: No display specified …` on every run, success or
+  // failure. When the display surface is dead the command does not fail, it
+  // *hangs* — so at kill time that Note is the only thing on stderr, and the
+  // tool reported a benign informational line as the reason a capture failed.
+  // That is how this wedge stayed nameless through five CI failures.
+  const lines = String(err.stderr || '').trim().split('\n').map((l) => l.trim()).filter(Boolean);
+  const real = lines.filter((l) => !/^Note:/i.test(l)).pop();
+  if (killed && !real) {
+    // Run to completion the device names it exactly:
+    //   NSPOSIXErrorDomain code 60 — Timeout waiting for screen surfaces
+    // which is CoreSimulator saying the surface is gone, and the closest thing
+    // to a positive test for the wedge that exists.
+    return 'simctl screenshot did not return within 10s. The display surface is not answering'
+      + ' — run to completion it reports "Timeout waiting for screen surfaces" (NSPOSIXErrorDomain 60).'
+      + ' This is the device, not the capture loop: `simframe revive` restarts it.';
+  }
+  const detail = real ?? lines.pop();
+  return detail ? `simctl screenshot failed: ${detail}` : `simctl screenshot failed: ${err.message}`;
+}
+
 async function screenshot(udid, outFile, { mask = 'ignored' } = {}) {
   try {
     await run('xcrun', ['simctl', 'io', udid, 'screenshot', '--type=png', `--mask=${mask}`, outFile], {
       timeout: 10_000,
     });
   } catch (err) {
-    // Same reason as launchApp: execFile's message is "Command failed: <the
-    // whole command>" and simctl's actual complaint is in stderr. A CI failure
-    // here reported the command and nothing about why it did not work.
-    const detail = (err.stderr || '').trim().split('\n').filter(Boolean).pop();
-    throw new Error(detail ? `simctl screenshot failed: ${detail}` : `simctl screenshot failed: ${err.message}`);
+    throw new Error(screenshotFailure(err));
   }
 }
 
@@ -309,6 +335,100 @@ function ownsUdid(udid) {
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(String(udid ?? ''));
 }
 
+/**
+ * Where CoreSimulator keeps a device's data.
+ *
+ * Read straight off disk, and that is the whole point of this family rather
+ * than an optimisation. Measured on this Xcode: `simctl get_app_container` and
+ * `simctl listapps` **both** fail on a device that is not running —
+ * `Unable to lookup in current state: Shutdown`. The field report that asked
+ * for this feature rated it highest-leverage precisely because it answered
+ * "what did the app save?" *before the device was booted*, and simctl cannot do
+ * that. The filesystem can, so this reads the filesystem.
+ */
+const deviceRoot = (udid) =>
+  path.join(os.homedir(), 'Library/Developer/CoreSimulator/Devices', String(udid));
+
+const containerRoot = (udid) => path.join(deviceRoot(udid), 'data/Containers/Data/Application');
+
+/** The per-container metadata file that says which app owns it. */
+const METADATA = '.com.apple.mobile_container_manager.metadata.plist';
+
+/**
+ * Every app with a data container on this device, booted or not.
+ *
+ * The bundle id lives in `MCMMetadataIdentifier` in each container's metadata
+ * plist. It is *not* recoverable by grepping the file — the binary plist
+ * encodes strings in a way that does not leave the id as a plain substring, and
+ * an early version of this that tried to pre-filter that way matched nothing.
+ * So each metadata file is asked properly. Measured at **0.52s for 150
+ * containers**, which is a listing cost rather than a per-read one.
+ */
+async function listApps(udid) {
+  const root = containerRoot(udid);
+  let entries;
+  try {
+    entries = await fs.promises.readdir(root, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      const exists = fs.existsSync(deviceRoot(udid));
+      throw new Error(exists
+        ? `device ${udid} has no app data containers yet — nothing has been installed on it`
+        : `no simulator data directory for ${udid} (looked in ${root})`);
+    }
+    throw err;
+  }
+  const apps = [];
+  await Promise.all(entries.filter((e) => e.isDirectory()).map(async (e) => {
+    const dir = path.join(root, e.name);
+    try {
+      const { stdout } = await run('plutil',
+        ['-extract', 'MCMMetadataIdentifier', 'raw', '-o', '-', path.join(dir, METADATA)],
+        { timeout: 10_000 });
+      const bundleId = stdout.trim();
+      if (bundleId) apps.push({ bundleId, container: dir });
+    } catch {
+      // A container without readable metadata is not an app we can name, and
+      // naming it by its UUID would be offering an id nobody can use.
+    }
+  }));
+  return apps.sort((a, b) => a.bundleId.localeCompare(b.bundleId));
+}
+
+/** The data container for one app, or a listing of what is there instead. */
+async function appContainer(udid, bundleId) {
+  const apps = await listApps(udid);
+  const hit = apps.find((a) => a.bundleId === bundleId);
+  if (hit) return hit.container;
+  // Near misses first: the id is the thing people get wrong, and a bare "not
+  // installed" on a device with the app under a slightly different id is the
+  // least useful true sentence available.
+  const needle = String(bundleId).toLowerCase();
+  const near = apps.filter((a) => a.bundleId.toLowerCase().includes(needle)
+    || needle.includes(a.bundleId.toLowerCase())).slice(0, 5);
+  throw new Error(
+    `"${bundleId}" has no data container on ${udid}`
+    + (near.length ? ` — did you mean ${near.map((a) => a.bundleId).join(', ')}?` : '')
+    + ` (${apps.length} app(s) have one)`,
+  );
+}
+
+/**
+ * Read a property list, whatever it contains.
+ *
+ * `-convert xml1` and not `json`: six of the twenty real preference plists on
+ * the bench device cannot be represented as JSON at all, because `<data>` and
+ * `<date>` have no JSON form and plutil refuses rather than inventing one. See
+ * the note at the top of plist.js.
+ */
+async function readPropertyList(file) {
+  const { stdout } = await run('plutil', ['-convert', 'xml1', '-o', '-', file], {
+    timeout: 20_000,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return plist.parse(stdout);
+}
+
 /**
  * The prerequisites `simframe doctor` reports for this backend. Returned rather
  * than printed so doctor stays one renderer: a backend says what it needs, and
@@ -415,6 +535,9 @@ export const platform = {
   terminateApp,
   openUrl,
   restartDevice,
+  listApps,
+  appContainer,
+  readPropertyList,
   setPermission,
   setPasteboard,
   permissionServices: () => PERMISSION_SERVICES,