@vostride/agent-qa-android 0.1.21 → 0.2.2

package/dist/index.cjs

@@ -36,6 +36,10 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/adapter.ts
+var import_node_crypto = require("crypto");
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+var import_agent_qa_runner = require("@vostride/agent-qa-runner");
 var import_agent_qa_core2 = require("@vostride/agent-qa-core");
 
 // src/session.ts
@@ -106,6 +110,22 @@ async function createAndroidSession(config, farmSession) {
 
 // src/adapter.ts
 var ANDROID_FILLABLE_ROLES = /* @__PURE__ */ new Set(["textbox", "searchbox", "edittext", "combobox"]);
+var FOCUSED_XPATH = '//*[@focused="true"]';
+var FOCUSED_HINT_XPATH = '//*[@focused="true" and @showing-hint="true"]';
+var FOCUSED_MULTILINE_XPATH = '//*[@focused="true" and @multiline="true"]';
+var FOCUSED_SINGLE_LINE_XPATH = '//*[@focused="true" and @multiline="false"]';
+var FOCUS_BOUNDS_TOLERANCE = 1;
+var ANDROID_BOUNDS_RE = /^\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]$/;
+var ENTER_KEYCODE = 66;
+var CTRL_A = { keycode: 29, metastate: 4096 };
+var DEL_KEYCODE = 67;
+var MULTI_LINE_SUBMIT_NOTICE = "submit not sent: Return would add a new line in this multi-line field; tap its send or submit control";
+var LINE_BREAK_RE = /[\r\n]/;
+var ADB_SHELL_REFUSAL = "Potentially insecure feature 'adb_shell' has not been enabled";
+var WEB_FOCUS_PROBE_SCRIPT = 'var a = document.activeElement;var hit = document.elementFromPoint(arguments[0], arguments[1]);if (!a) { return { editable: false, matches: false, multiline: false, secure: false, value: null };}var tag = a.tagName;var type = tag === "INPUT" ? String(a.type || "text").toLowerCase() : "";var textual = ["text", "search", "email", "url", "tel", "password", "number"].indexOf(type) >= 0;var field = (tag === "INPUT" && textual) || tag === "TEXTAREA";var rich = !field && a.isContentEditable === true;var v = field ? a.value : (rich ? a.innerText : null);return { editable: (field && !a.readOnly && !a.disabled) || rich, matches: !!hit && (a === hit || a.contains(hit)), multiline: tag === "TEXTAREA" || rich, secure: type === "password", value: typeof v === "string" ? v : null};';
+var WEB_FOCUS_POLLS = 3;
+var WEB_FOCUS_POLL_MS = 300;
+var WEB_FIELD_VALUE_SCRIPT = 'var a = document.activeElement;if (!a) { return null; }var v = (a.tagName === "INPUT" || a.tagName === "TEXTAREA") ? a.value : (a.isContentEditable ? a.innerText : null);return typeof v === "string" ? v : null;';
 var ANDROID_NATIVE_SELECT_ROLES = /* @__PURE__ */ new Set(["combobox", "spinbutton", "listbox", "list"]);
 var ANDROID_NATIVE_SELECT_TYPES = /* @__PURE__ */ new Set([
   "android.widget.Spinner",
@@ -133,12 +153,32 @@ var ANDROID_LEVEL_MAP = {
   E: "error",
   F: "error"
 };
-function firstNonEmpty(...values) {
-  for (const value of values) {
-    const trimmed = typeof value === "string" ? value.trim() : "";
-    if (trimmed) return trimmed;
-  }
-  return void 0;
+var INPUT_FAILED = { sent: false, outcome: "not-sent", reason: "input-failed" };
+function fieldKindOf(refData) {
+  const inputType = refData?.inputType;
+  if (inputType === void 0 || (inputType & 15) === 0) return "unknown";
+  if ((inputType & 15) === 1 && (inputType & 131072) !== 0) return "multi-line";
+  return "single-line";
+}
+function webFocusEvidence(focus) {
+  return focus.editable ? "focus-elsewhere" : "no-keyboard-focus";
+}
+function parseBoundsAttr(value) {
+  if (typeof value !== "string") return void 0;
+  const match = ANDROID_BOUNDS_RE.exec(value.trim());
+  if (!match) return void 0;
+  const [left, top, right, bottom] = match.slice(1).map(Number);
+  return { x: left, y: top, width: right - left, height: bottom - top };
+}
+function rectWithin(inner, outer) {
+  return inner.x >= outer.x - FOCUS_BOUNDS_TOLERANCE && inner.y >= outer.y - FOCUS_BOUNDS_TOLERANCE && inner.x + inner.width <= outer.x + outer.width + FOCUS_BOUNDS_TOLERANCE && inner.y + inner.height <= outer.y + outer.height + FOCUS_BOUNDS_TOLERANCE;
+}
+function firstErrorLine(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return message.split("\n")[0].trim();
+}
+function isShellRefusal(err) {
+  return (err instanceof Error ? err.message : String(err)).includes(ADB_SHELL_REFUSAL);
 }
 function isAndroidWebContextName(context) {
   const normalized = context.toUpperCase();
@@ -155,6 +195,27 @@ function isAndroidNativeSelectTarget(refData) {
     role && ANDROID_NATIVE_SELECT_ROLES.has(role) || refData?.nativeType && ANDROID_NATIVE_SELECT_TYPES.has(refData.nativeType)
   );
 }
+var CONTROL_CHAR_RE = /[\u0000-\u001F\u007F]/;
+function escapeUiSelectorText(value) {
+  if (CONTROL_CHAR_RE.test(value)) {
+    throw new Error(
+      `scroll target contains a control character and cannot be used as a UiAutomator selector \u2014 provide a plain-text target for untilVisible.`
+    );
+  }
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function fingerDirectionFor(scroll) {
+  switch (scroll) {
+    case "up":
+      return "down";
+    case "down":
+      return "up";
+    case "left":
+      return "right";
+    case "right":
+      return "left";
+  }
+}
 function androidUiSelectorText(value) {
   return `android=new UiSelector().text(${JSON.stringify(value)})`;
 }
@@ -195,18 +256,65 @@ return (function() {
     H4: 'heading', H5: 'heading', H6: 'heading', IMG: 'image'
   };
 
-  var vh = window.innerHeight;
+  var doc = document;
   var vw = window.innerWidth;
-  var refCounter = 0;
-  var elements = [];
-  var refs = {};
-  var lines = [];
-  var seen = {};
+  var vh = window.innerHeight;
+  var active = doc.activeElement;
 
-  var all = document.querySelectorAll(
-    'a, button, input, textarea, select, h1, h2, h3, h4, h5, h6, img[alt], [role]'
+  var all = doc.querySelectorAll(
+    'a, button, input, textarea, select, h1, h2, h3, h4, h5, h6, img[alt], [role], [contenteditable]:not([contenteditable="false"])'
   );
 
+  var nodes = [];
+  var includedEls = [];
+  var seen = {};
+  var CAPTION_TYPES = { submit: true, button: true, reset: true };
+  var VALUELESS_TYPES = {
+    password: true, checkbox: true, radio: true, submit: true, button: true, reset: true,
+    image: true, file: true, hidden: true, range: true, color: true
+  };
+
+  function textOf(node) {
+    return node ? (node.textContent || '').trim() : '';
+  }
+
+  // 437 D-11 (CR-02): a field is named by its label, never by its value, so typed text never
+  // becomes a name. A wrapping label's text drops the field's own text (a select's options).
+  function labelText(el, label) {
+    var text = label.textContent || '';
+    var own = el.textContent || '';
+    if (own && label.contains(el)) text = text.replace(own, '');
+    return text.trim();
+  }
+
+  function fieldName(el, tag) {
+    var ids = (el.getAttribute('aria-labelledby') || '').split(' ');
+    var parts = [];
+    for (var j = 0; j < ids.length; j++) {
+      var part = ids[j] ? textOf(doc.getElementById(ids[j])) : '';
+      if (part) parts.push(part);
+    }
+    if (parts.length > 0) return parts.join(' ');
+    var label = el.labels && el.labels.length > 0 ? labelText(el, el.labels[0]) : '';
+    if (label) return label;
+    var hint = el.getAttribute('placeholder') || el.getAttribute('title');
+    if (hint) return hint;
+    if (tag === 'INPUT' && CAPTION_TYPES[String(el.type).toLowerCase()]) return el.value || '';
+    return '';
+  }
+
+  // parentIndex is the nearest INCLUDED ancestor (structural/skipped nodes collapse
+  // away, matching the mobile/web walkers' Pitfall #7 handling).
+  function nearestAncestorIndex(el) {
+    var p = el.parentElement;
+    while (p) {
+      var idx = includedEls.indexOf(p);
+      if (idx !== -1) return idx;
+      p = p.parentElement;
+    }
+    return undefined;
+  }
+
   for (var i = 0; i < all.length; i++) {
     var el = all[i];
     var rect = el.getBoundingClientRect();
@@ -216,31 +324,37 @@ return (function() {
     if (style.display === 'none' || style.visibility === 'hidden') continue;
 
     var tag = el.tagName;
+    // 2026-10-19 (444.1-05, D-09): only the outermost content-editable element is an editor;
+    // its descendants are ordinary nodes.
+    var host = el.isContentEditable === true
+      && !(el.parentElement && el.parentElement.isContentEditable === true);
     var ariaRole = el.getAttribute('role');
-    var role = ariaRole || TAG_ROLES[tag] || null;
+    var role = (ariaRole || TAG_ROLES[tag] || (host ? 'textbox' : '')).toLowerCase();
     if (!role) continue;
 
+    var field = tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
+    var editable = field || host;
+    var textual = role === 'textbox' || role === 'searchbox' || role === 'combobox';
     var name = '';
     var ariaLabel = el.getAttribute('aria-label');
     if (ariaLabel) {
       name = ariaLabel;
     } else if (tag === 'IMG') {
       name = el.alt || '';
-    } else if (tag === 'INPUT' || tag === 'TEXTAREA') {
-      name = el.getAttribute('placeholder') || el.value || '';
+    } else if (editable || textual) {
+      name = fieldName(el, tag) || el.getAttribute('aria-placeholder') || '';
     } else {
       name = (el.textContent || '').trim();
     }
 
     name = name.slice(0, 100).replace(/[\\n\\r]+/g, ' ').trim();
-    if (!name && role !== 'textbox') continue;
-
-    var key = role + ':' + name;
-    if (seen[key]) continue;
-    seen[key] = true;
+    if (!name && !editable && !textual) continue;
 
-    refCounter++;
-    var ref = 'e' + refCounter;
+    if (!editable && !textual) {
+      var key = role + ':' + name;
+      if (seen[key]) continue;
+      seen[key] = true;
+    }
 
     var bounds = {
       x: Math.round(rect.left),
@@ -249,41 +363,174 @@ return (function() {
       height: Math.round(rect.height)
     };
 
-    var offscreen = bounds.y + bounds.height < 0 || bounds.y > vh;
+    // Real DOM state signals only \u2014 the builder derives every default (D-08).
+    var state = {};
+    var disabled = el.disabled === true
+      || el.hasAttribute('disabled')
+      || el.getAttribute('aria-disabled') === 'true';
+    state.enabled = !disabled;
+    state.focused = el === active;
+    if (bounds.y + bounds.height < 0 || bounds.y > vh) state.visible = false;
+    if (tag === 'INPUT' && (el.type === 'checkbox' || el.type === 'radio')) {
+      state.checked = el.checked === true;
+    }
 
-    elements.push({ ref: ref, role: role, name: name, attributes: {} });
-    refs[ref] = { role: role, name: name, bounds: bounds };
+    var labels = {};
+    var testId = el.getAttribute('data-testid');
+    if (testId) labels.testId = testId;
+    if (ariaLabel) labels.ariaLabel = ariaLabel;
+    var placeholder = el.getAttribute('placeholder');
+    if (placeholder) labels.placeholder = placeholder;
+    var title = el.getAttribute('title');
+    if (title) labels.title = title;
 
-    var line = '- ' + role + ' "' + name.replace(/"/g, "'") + '" [ref=' + ref + ']';
-    if (offscreen) line += ' [offscreen]';
-    lines.push(line);
-  }
+    var attributes = {};
+    if (el.type) attributes.type = String(el.type);
 
-  var visCount = 0, aboveCount = 0, belowCount = 0;
-  var refKeys = Object.keys(refs);
-  for (var j = 0; j < refKeys.length; j++) {
-    var b = refs[refKeys[j]].bounds;
-    if (b.y + b.height <= 0) aboveCount++;
-    else if (b.y >= vh) belowCount++;
-    else visCount++;
-  }
+    var parentIndex = nearestAncestorIndex(el);
+
+    // 2026-10-19 (444.1-05 D-08, 444.1-22 D-33): what a field or an editor holds is its value, never its name; a password's never.
+    var observedValue = undefined;
+    var textEntry = tag === 'TEXTAREA' || (tag === 'INPUT' && !VALUELESS_TYPES[String(el.type).toLowerCase()]);
+    if (textEntry && el.value) {
+      observedValue = String(el.value).slice(0, 200);
+    } else if (tag === 'SELECT') {
+      var option = el.options && el.selectedIndex >= 0 ? el.options[el.selectedIndex] : null;
+      var optionText = option ? String(option.text || '').trim().slice(0, 200) : '';
+      if (optionText) observedValue = optionText;
+    } else if (host || (textual && !field)) {
+      var held = textOf(el).replace(/[\\n\\r]+/g, ' ').slice(0, 200).trim();
+      if (held) observedValue = held;
+    }
 
-  var header = 'Current page: ' + location.href + '\\n';
-  header += '[Viewport: ' + vw + 'x' + vh + ']';
-  if (aboveCount > 0 || belowCount > 0) {
-    header += ' [' + visCount + ' visible, ' + aboveCount + ' above, ' + belowCount + ' below]';
+    var record = {
+      role: role,
+      name: name,
+      value: observedValue,
+      bounds: bounds,
+      state: state,
+      labels: labels,
+      attributes: attributes
+    };
+    if (parentIndex !== undefined) record.parentIndex = parentIndex;
+
+    nodes.push(record);
+    includedEls.push(el);
   }
 
+  var docEl = doc.documentElement;
   return {
-    tree: header + '\\n' + lines.join('\\n'),
-    elements: elements,
-    refs: refs,
-    url: location.href,
-    viewportHeight: vh,
-    viewportWidth: vw
+    nodes: nodes,
+    viewport: { width: vw, height: vh },
+    scroll: {
+      offsetX: window.scrollX,
+      offsetY: window.scrollY,
+      contentWidth: docEl.scrollWidth,
+      contentHeight: docEl.scrollHeight
+    },
+    url: location.href
   };
 })();
 `;
+function coerceWebInterimNode(value) {
+  if (!value || typeof value !== "object") return null;
+  const v = value;
+  const role = coerceString(v.role);
+  if (!role) return null;
+  const node = { role: role.toLowerCase(), attributes: coerceStringBag(v.attributes) };
+  const name = coerceString(v.name);
+  if (name) node.name = name;
+  const fieldValue = coerceString(v.value);
+  if (fieldValue) node.value = fieldValue;
+  if (typeof v.parentIndex === "number" && Number.isInteger(v.parentIndex) && v.parentIndex >= 0) {
+    node.parentIndex = v.parentIndex;
+  }
+  const bounds = coerceWebBounds(v.bounds);
+  if (bounds) node.bounds = bounds;
+  const state = coerceWebState(v.state);
+  if (state) node.state = state;
+  const labels = coerceWebLabels(v.labels);
+  if (labels) node.labels = labels;
+  return node;
+}
+function coerceString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function coerceStringBag(value) {
+  const bag = {};
+  if (!value || typeof value !== "object") return bag;
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v === "string") bag[k] = v;
+    else if (typeof v === "number" || typeof v === "boolean") bag[k] = String(v);
+  }
+  return bag;
+}
+function coerceWebBounds(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const v = value;
+  const { x, y, width, height } = v;
+  if (typeof x === "number" && Number.isFinite(x) && typeof y === "number" && Number.isFinite(y) && typeof width === "number" && Number.isFinite(width) && typeof height === "number" && Number.isFinite(height)) {
+    return { x, y, width, height };
+  }
+  return void 0;
+}
+function coerceWebState(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const v = value;
+  const state = {};
+  if (typeof v.enabled === "boolean") state.enabled = v.enabled;
+  if (typeof v.focused === "boolean") state.focused = v.focused;
+  if (typeof v.visible === "boolean") state.visible = v.visible;
+  if (typeof v.checked === "boolean") state.checked = v.checked;
+  if (typeof v.selected === "boolean") state.selected = v.selected;
+  return Object.keys(state).length > 0 ? state : void 0;
+}
+function coerceWebLabels(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const v = value;
+  const labels = {};
+  const testId = coerceString(v.testId);
+  if (testId) labels.testId = testId;
+  const ariaLabel = coerceString(v.ariaLabel);
+  if (ariaLabel) labels.ariaLabel = ariaLabel;
+  const placeholder = coerceString(v.placeholder);
+  if (placeholder) labels.placeholder = placeholder;
+  const title = coerceString(v.title);
+  if (title) labels.title = title;
+  return Object.keys(labels).length > 0 ? labels : void 0;
+}
+function coerceViewport(value, fallback) {
+  if (value && typeof value === "object") {
+    const v = value;
+    const width = typeof v.width === "number" && Number.isFinite(v.width) ? v.width : fallback.width;
+    const height = typeof v.height === "number" && Number.isFinite(v.height) ? v.height : fallback.height;
+    return { width, height };
+  }
+  return fallback;
+}
+function coerceWebScroll(value, viewport) {
+  const num = (x, fb) => typeof x === "number" && Number.isFinite(x) ? x : fb;
+  if (value && typeof value === "object") {
+    const v = value;
+    return {
+      offsetX: num(v.offsetX, 0),
+      offsetY: num(v.offsetY, 0),
+      contentWidth: num(v.contentWidth, viewport.width),
+      contentHeight: num(v.contentHeight, viewport.height)
+    };
+  }
+  return { offsetX: 0, offsetY: 0, contentWidth: viewport.width, contentHeight: viewport.height };
+}
+function gestureArea(bounds, direction, viewport) {
+  const vertical = direction === "up" || direction === "down";
+  const length = vertical ? viewport.height : viewport.width;
+  const start = vertical ? bounds.y : bounds.x;
+  const end = start + (vertical ? bounds.height : bounds.width);
+  const from = Math.max(start, Math.round(length * 0.2));
+  const to = Math.min(end, Math.round(length * 0.8));
+  if (to - from < 1) return bounds;
+  return vertical ? { ...bounds, y: from, height: to - from } : { ...bounds, x: from, width: to - from };
+}
 var AndroidPlatformAdapter = class {
   platform = "android";
   driver = null;
@@ -294,15 +541,16 @@ var AndroidPlatformAdapter = class {
   activeWebContext = null;
   // Cached so we skip redundant switchContext round-trips.
   currentContext = null;
-  // Video recording state
-  recordingEnabled = false;
-  videoDir = null;
-  videoPath = null;
+  recordingCapability;
+  liveStreamCapability;
   consoleLogs = [];
   consoleDrainIndex = 0;
   captureConsole = true;
   appPackage = null;
   appPid = null;
+  // EXEC-03 session-cached app registry (D-10/D-12): enumerated once per session; null = not yet
+  // enumerated (or enumeration failed and may be retried). Reset in cleanup().
+  appRegistry = null;
   async setup(config) {
     this.config = config;
     this.captureConsole = config.logCapture?.console !== false;
@@ -310,17 +558,30 @@ var AndroidPlatformAdapter = class {
     this.driver = await createAndroidSession(this.config, config.farmSession);
     const appPackage = this.appPackage;
     if (appPackage && !this.config.browserName && !this.config.device?.match?.browserName) {
+      let state;
       try {
-        await this.driver.activateApp(appPackage);
-      } catch (err) {
-        throw new import_agent_qa_core2.MobileSetupError({
-          category: "app-launch",
-          message: `Failed to launch Android app "${appPackage}": ${err instanceof Error ? err.message : String(err)}`,
-          platform: "android",
-          deviceName: config.device?.name,
-          appId: appPackage,
-          cause: err
-        });
+        state = await this.driver.queryAppState(appPackage);
+      } catch {
+        try {
+          const answer = await this.driver.execute("mobile: queryAppState", { appId: appPackage });
+          if (typeof answer === "number") state = answer;
+        } catch {
+          state = void 0;
+        }
+      }
+      if (state !== 4) {
+        try {
+          await this.driver.activateApp(appPackage);
+        } catch (err) {
+          throw new import_agent_qa_core2.MobileSetupError({
+            category: "app-launch",
+            message: `Failed to launch Android app "${appPackage}": ${err instanceof Error ? err.message : String(err)}`,
+            platform: "android",
+            deviceName: config.device?.name,
+            appId: appPackage,
+            cause: err
+          });
+        }
       }
     }
     if (process.env.AGENT_QA_ANDROID_USE_MOBILE_SHELL === "1" && this.appPackage && this.driver) {
@@ -331,32 +592,18 @@ var AndroidPlatformAdapter = class {
       } catch {
       }
     }
-    if (config.recording?.enabled && this.driver) {
-      this.videoDir = config.recording.videoDir;
-      const videoSize = config.recording.videoSize ? `${config.recording.videoSize.width}x${config.recording.videoSize.height}` : void 0;
-      try {
-        await this.driver.startRecordingScreen({ videoSize, timeLimit: 1800, forceRestart: true });
-        this.recordingEnabled = true;
-      } catch {
-        try {
-          await this.driver.execute("mobile: startScreenRecording", {
-            videoSize,
-            timeLimit: 1800,
-            forceRestart: true
-          });
-          this.recordingEnabled = true;
-        } catch {
-        }
-      }
-    }
   }
   async cleanup() {
-    if (this.recordingEnabled && this.driver) {
-      try {
-        await this.stopAndSaveRecording();
-      } catch {
-      }
+    try {
+      await this.recordingCapability?.stop();
+    } catch {
+    }
+    this.recordingCapability = void 0;
+    try {
+      await this.liveStreamCapability?.stop();
+    } catch {
     }
+    this.liveStreamCapability = void 0;
     try {
       if (this.driver) {
         await this.driver.deleteSession();
@@ -369,9 +616,9 @@ var AndroidPlatformAdapter = class {
     this.consoleLogs = [];
     this.appPackage = null;
     this.appPid = null;
+    this.appRegistry = null;
     this.activeWebContext = null;
     this.currentContext = null;
-    this.recordingEnabled = false;
   }
   // Whether we've ever successfully observed via a web context.
   // Once true, we know a WebView/browser exists and should retry rather than
@@ -397,11 +644,20 @@ var AndroidPlatformAdapter = class {
     try {
       return await this.observeNative();
     } catch {
+      this.lastRefs = {};
       return {
+        platform: "android",
         tree: "(native observation unavailable \u2014 WebView content not accessible)",
         elements: [],
+        refMap: {},
         timestamp: Date.now(),
-        metadata: { coordSpace: "viewport", viewportWidth: 0, viewportHeight: 0 }
+        metadata: {
+          captureMode: "textOnly",
+          coordSpace: "viewport",
+          viewportWidth: 0,
+          viewportHeight: 0,
+          scroll: { offsetX: 0, offsetY: 0, contentWidth: 0, contentHeight: 0 }
+        }
       };
     }
   }
@@ -439,7 +695,7 @@ var AndroidPlatformAdapter = class {
     const buf = await this.captureScreenshot();
     if (buf && this.driver) {
       try {
-        const { getImageDimensions } = await import("@vostride/agent-qa-core");
+        const { getImageDimensions } = await import("@vostride/agent-qa-runner-local");
         const dims = await getImageDimensions(buf);
         const { width } = await this.driver.getWindowSize();
         if (dims && Math.abs(dims.width - width) > 1) {
@@ -475,35 +731,90 @@ var AndroidPlatformAdapter = class {
     if (!level) return newLogs;
     return newLogs.filter((e) => e.level === level);
   }
-  // ---------------------------------------------------------------------------
-  // Video recording
-  // ---------------------------------------------------------------------------
-  async getVideoPath() {
-    if (this.recordingEnabled && !this.videoPath && this.driver) {
-      await this.stopAndSaveRecording();
-    }
-    return this.videoPath;
+  /**
+   * 428 D-11: the labelled 1s snapshot preview, over `captureScreenshot()` — `takeScreenshot()`
+   * and nothing else. Never `screenshot()`: that one switches the Appium context, and a tick
+   * landing between a step's context switch and its command would run the command in the wrong
+   * context. Declared before the driver exists (a capture then answers `undefined`), so the
+   * composition's selection never falls through to `screenshot()`.
+   */
+  get liveStream() {
+    this.liveStreamCapability ??= (0, import_agent_qa_runner.createSnapshotLiveStream)({ capture: () => this.captureScreenshot() });
+    return this.liveStreamCapability;
   }
-  async stopAndSaveRecording() {
-    if (!this.driver || !this.videoDir) return;
-    this.recordingEnabled = false;
-    let base64Video;
-    try {
-      base64Video = await this.driver.stopRecordingScreen();
-    } catch {
-      try {
-        base64Video = await this.driver.execute("mobile: stopScreenRecording");
-      } catch {
-      }
+  get recording() {
+    const driver = this.driver;
+    const config = this.config?.recording;
+    if (!driver || !config) return void 0;
+    if (this.recordingCapability) return this.recordingCapability;
+    let running = false;
+    let busy = false;
+    let needsCleanup = false;
+    async function recover() {
+      if (!needsCleanup) return;
+      await driver.stopRecordingScreen();
+      needsCleanup = false;
     }
-    if (!base64Video) return;
-    const { mkdirSync, writeFileSync } = await import("fs");
-    const { join } = await import("path");
-    mkdirSync(this.videoDir, { recursive: true });
-    const filename = `android-${Date.now()}.mp4`;
-    const filePath = join(this.videoDir, filename);
-    writeFileSync(filePath, Buffer.from(base64Video, "base64"));
-    this.videoPath = filePath;
+    this.recordingCapability = {
+      async start() {
+        if (busy || running) throw new Error("Recording already started");
+        busy = true;
+        try {
+          await recover();
+          const videoSize = config.videoSize ? `${config.videoSize.width}x${config.videoSize.height}` : void 0;
+          needsCleanup = true;
+          try {
+            await driver.startRecordingScreen({ videoSize, timeLimit: 1800, forceRestart: true });
+          } catch (error) {
+            try {
+              await recover();
+            } catch {
+            }
+            throw error;
+          }
+          needsCleanup = false;
+          running = true;
+          return {};
+        } finally {
+          busy = false;
+        }
+      },
+      async stop() {
+        if (busy) throw new Error("Recording operation already in progress");
+        busy = true;
+        try {
+          if (!running) {
+            await recover();
+            return void 0;
+          }
+          running = false;
+          let base64Video;
+          try {
+            base64Video = await driver.stopRecordingScreen();
+          } catch (error) {
+            needsCleanup = true;
+            try {
+              await recover();
+            } catch {
+            }
+            throw error;
+          }
+          if (!base64Video) return void 0;
+          await (0, import_promises.mkdir)(config.videoDir, { recursive: true });
+          const stagingPath = (0, import_node_path.join)(config.videoDir, `${(0, import_node_crypto.randomUUID)()}.mp4`);
+          try {
+            await (0, import_promises.writeFile)(stagingPath, Buffer.from(base64Video, "base64"));
+          } catch (error) {
+            await (0, import_promises.rm)(stagingPath, { force: true }).catch(() => void 0);
+            throw error;
+          }
+          return { stagingPath, contentType: "video/mp4" };
+        } finally {
+          busy = false;
+        }
+      }
+    };
+    return this.recordingCapability;
   }
   // ---------------------------------------------------------------------------
   // Observation
@@ -518,22 +829,33 @@ var AndroidPlatformAdapter = class {
       );
       if (!webCtx) return null;
       await this.ensureContext(webCtx);
-      const result = await driver.execute(WEB_OBSERVER_SCRIPT);
-      if (!result || !result.elements || result.elements.length === 0) return null;
-      this.lastRefs = result.refs;
-      this.activeWebContext = webCtx;
-      return {
-        tree: result.tree,
-        elements: result.elements,
-        url: result.url,
+      const raw = await driver.execute(WEB_OBSERVER_SCRIPT);
+      if (!raw || typeof raw !== "object") return null;
+      const payload = raw;
+      const rawNodes = payload.nodes;
+      if (!Array.isArray(rawNodes) || rawNodes.length === 0) return null;
+      const nodes = [];
+      for (const candidate of rawNodes) {
+        const node = coerceWebInterimNode(candidate);
+        if (node) nodes.push(node);
+      }
+      if (nodes.length === 0) return null;
+      const windowSize = await driver.getWindowSize();
+      const viewport = coerceViewport(payload.viewport, { width: windowSize.width, height: windowSize.height });
+      const scroll = coerceWebScroll(payload.scroll, viewport);
+      const url = typeof payload.url === "string" ? payload.url : void 0;
+      const { state, binding } = (0, import_agent_qa_runner.buildScreenState)({
+        platform: "android",
+        nodes,
+        viewport,
+        scroll,
+        coordSpace: "viewport",
         timestamp: Date.now(),
-        metadata: {
-          coordSpace: "viewport",
-          viewportWidth: result.viewportWidth,
-          viewportHeight: result.viewportHeight,
-          refMap: result.refs
-        }
-      };
+        ...url !== void 0 ? { url } : {}
+      });
+      this.lastRefs = (0, import_agent_qa_core2.buildRefEntries)(nodes, binding);
+      this.activeWebContext = webCtx;
+      return state;
     } catch {
       return null;
     }
@@ -545,14 +867,18 @@ var AndroidPlatformAdapter = class {
       driver.getPageSource(),
       driver.getWindowSize()
     ]);
-    const parsed = (0, import_agent_qa_core2.parseMobileSource)(xml, "android", viewport);
-    this.lastRefs = parsed.refs;
-    return {
-      tree: parsed.tree,
-      elements: parsed.elements,
-      timestamp: Date.now(),
-      metadata: { coordSpace: "viewport", viewportWidth: viewport.width, viewportHeight: viewport.height, refMap: parsed.refs }
-    };
+    const { nodes } = (0, import_agent_qa_core2.parseMobileSource)(xml, "android", viewport);
+    const scroll = (0, import_agent_qa_core2.deriveMobileScroll)(nodes, viewport);
+    const { state, binding } = (0, import_agent_qa_runner.buildScreenState)({
+      platform: "android",
+      nodes,
+      viewport,
+      scroll,
+      coordSpace: "viewport",
+      timestamp: Date.now()
+    });
+    this.lastRefs = (0, import_agent_qa_core2.buildRefEntries)(nodes, binding);
+    return state;
   }
   // ---------------------------------------------------------------------------
   // Context management
@@ -573,7 +899,14 @@ var AndroidPlatformAdapter = class {
     try {
       if (this.driver) {
         const base64 = await this.driver.takeScreenshot();
-        return Buffer.from(base64, "base64");
+        const buf = Buffer.from(base64, "base64");
+        if (!this.activeWebContext) return buf;
+        try {
+          const { flattenOntoWhite } = await import("@vostride/agent-qa-runner-local");
+          return await flattenOntoWhite(buf);
+        } catch {
+          return buf;
+        }
       }
       return void 0;
     } catch {
@@ -581,6 +914,621 @@ var AndroidPlatformAdapter = class {
     }
   }
   // ---------------------------------------------------------------------------
+  // Compound behaviors (EXEC-01/02/03)
+  // ---------------------------------------------------------------------------
+  /** Read the live text of a focused element handle; undefined when nothing is readable. */
+  async readElementText(el) {
+    try {
+      const value = await el.getText();
+      return typeof value === "string" ? value : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  async focusedMatches(xpath) {
+    try {
+      return await (await this.driver.$(xpath)).isExisting();
+    } catch {
+      return false;
+    }
+  }
+  /** An empty field's getText() returns its hint (437 Pitfall 4), so a showing hint reads ''. */
+  async readFocusedValue(el) {
+    if (await this.focusedMatches(FOCUSED_HINT_XPATH)) return "";
+    return await this.readElementText(el);
+  }
+  /**
+   * The `mobile: shell` route of keyevent and openQuickSettings (437 D-18). A refusal by secure
+   * Appium is recorded as unavailable and any other driver error as failed; neither is a pass.
+   */
+  async runShell(verb, args) {
+    try {
+      await this.driver.execute("mobile: shell", args);
+      return { success: true };
+    } catch (err) {
+      if (isShellRefusal(err)) {
+        const shellAction2 = {
+          verb,
+          outcome: "unavailable",
+          reason: "adb-shell-disabled"
+        };
+        return {
+          success: false,
+          error: `${verb} unavailable: Appium does not allow mobile: shell here (adb_shell is not enabled), so nothing was sent. Use pressBack, pressHome or keypress where they fit.`,
+          metadata: { shellAction: shellAction2 }
+        };
+      }
+      const detail = firstErrorLine(err);
+      const shellAction = { verb, outcome: "failed", detail };
+      return { success: false, error: `${verb} failed: ${detail}`, metadata: { shellAction } };
+    }
+  }
+  /** The one submit mechanism on every Android path (437 D-13); pressed once, never retried. */
+  async pressEnter() {
+    try {
+      await this.driver.execute("mobile: pressKey", { keycode: ENTER_KEYCODE });
+      return { sent: true, outcome: "sent" };
+    } catch (err) {
+      return { sent: false, outcome: "failed", detail: firstErrorLine(err) };
+    }
+  }
+  /** 437 FA-2 (owner, 2026-10-08): line breaks into a single-line field are refused before typing. */
+  refuseLineBreaks(action, box) {
+    const fillRefusal = {
+      verb: "fill",
+      cause: "single-line-field",
+      evidence: "text-has-line-breaks"
+    };
+    return {
+      success: false,
+      error: "fill: this field is single-line and the text has line breaks; nothing was typed. Send the text without line breaks, or use a multi-line field.",
+      ...box,
+      metadata: { fillRefusal, ...action.submit ? { fillSubmit: { ...INPUT_FAILED } } : {} }
+    };
+  }
+  /**
+   * Native fill from the focused handle (437 D-08..D-10, D-12, D-13, D-15, D-17). Delivers once
+   * (addValue for append, setValue for replace), reads back from the same handle and records the
+   * shared verdict. An unknown append prior or an unreadable read-back is unverified, which never
+   * stops a requested Enter; a mismatch or a multi-line field holds it. A driver error during
+   * delivery ends the fill: nothing is typed again and no Enter follows. A secure field yields
+   * length sentinels only.
+   */
+  async fillNativeCompound(el, action, box) {
+    const isAppend = action.clearMode === "append";
+    if (LINE_BREAK_RE.test(action.text) && await this.focusedMatches(FOCUSED_SINGLE_LINE_XPATH)) {
+      return this.refuseLineBreaks(action, box);
+    }
+    const multiline = action.submit && await this.focusedMatches(FOCUSED_MULTILINE_XPATH);
+    const secure = await el.getAttribute("password").catch(() => null) === "true";
+    const prior = isAppend ? await this.readFocusedValue(el) : "";
+    try {
+      if (isAppend) {
+        await el.addValue(action.text);
+      } else {
+        await el.setValue(action.text);
+      }
+    } catch {
+      return this.interruptedFill("native", secure, action, box);
+    }
+    const actual = prior === void 0 ? void 0 : await this.readFocusedValue(el);
+    const verdict = (0, import_agent_qa_runner.compareFillReread)({ expected: (prior ?? "") + action.text, actual, secure });
+    return await this.settleFill(action, box, {
+      path: "native",
+      verdict,
+      multiline,
+      enter: () => this.pressEnter()
+    });
+  }
+  /** The focused element handle, or undefined when UiAutomator2 reports none or the lookup fails. */
+  async focusedField() {
+    try {
+      const el = await this.driver.$(FOCUSED_XPATH);
+      return await el.isExisting() ? el : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * 437 D-11 (WR-02): where the focused node is relative to the ref, judged by its read bounds.
+   * An unreadable or unparseable value is no evidence, so the native path stays (D-04, D-15).
+   * 444.1 D-07: 'elsewhere' needs positive evidence, the bounds of another observed field.
+   */
+  async focusIsElsewhere(handle, ref, bounds) {
+    let raw;
+    try {
+      raw = await handle.getAttribute("bounds");
+    } catch {
+      return "target";
+    }
+    const focused = parseBoundsAttr(raw);
+    if (focused === void 0 || rectWithin(focused, bounds)) return "target";
+    for (const [other, entry] of Object.entries(this.lastRefs)) {
+      if (other === ref || !entry.bounds) continue;
+      const field = entry.editable === true || ANDROID_FILLABLE_ROLES.has(entry.role.toLowerCase());
+      if (field && rectWithin(focused, entry.bounds)) return "elsewhere";
+    }
+    return "moved";
+  }
+  /** Ctrl+A then DEL as key input; clears only the view holding input focus (437 D-14). */
+  async clearByKeys() {
+    await this.driver.execute("mobile: pressKey", CTRL_A);
+    await this.driver.execute("mobile: pressKey", { keycode: DEL_KEYCODE });
+  }
+  /**
+   * The last-resort keyboard path (437 D-14): the tap left no focused handle. Replace clears by
+   * keys, the text goes through one `mobile: type` (Appium's Unicode IME, exact for every D-08
+   * text), and the value is read back only when a focused handle can be found afterwards. An
+   * append's prior value is unknown, so it is never better than unverified. The field's kind comes
+   * from the observed input-type (D-15): only positive evidence refuses line breaks or holds Enter.
+   */
+  async fillKeyboardPath(action, box, refData) {
+    const isAppend = action.clearMode === "append";
+    const kind = fieldKindOf(refData);
+    if (kind === "single-line" && LINE_BREAK_RE.test(action.text)) {
+      return this.refuseLineBreaks(action, box);
+    }
+    try {
+      if (!isAppend) await this.clearByKeys();
+      await this.driver.execute("mobile: type", { text: action.text });
+    } catch {
+      return this.interruptedFill("keyboard", false, action, box);
+    }
+    const handle = await this.focusedField();
+    let secure = false;
+    let actual;
+    if (handle) {
+      secure = await this.isSecure(handle);
+      if (!isAppend) actual = await this.readFocusedValue(handle);
+    }
+    const verdict = (0, import_agent_qa_runner.compareFillReread)({ expected: action.text, actual, secure });
+    return await this.settleFill(action, box, {
+      path: "keyboard",
+      verdict,
+      multiline: kind === "multi-line",
+      enter: () => this.pressEnter()
+    });
+  }
+  /**
+   * Native and keyboard clearText (437 D-16): clearValue on the focused handle, or Ctrl+A then DEL
+   * when the tap left none, then the hint-aware read-back judged against the empty string. The
+   * caller has already checked that a focused handle is the referenced field (WR-02).
+   */
+  async clearNativeOrKeyboard(box, handle) {
+    const path = handle ? "native" : "keyboard";
+    const before = handle ? await this.isSecure(handle) : false;
+    try {
+      if (handle) await handle.clearValue();
+      else await this.clearByKeys();
+    } catch {
+      return this.interruptedClear(path, before, box);
+    }
+    const readable = handle ?? await this.focusedField();
+    if (!readable) return this.settleClear(path, void 0, false, box);
+    const secure = handle ? before : await this.isSecure(readable);
+    return this.settleClear(path, await this.readFocusedValue(readable), secure, box);
+  }
+  async isSecure(el) {
+    return await el.getAttribute("password").catch(() => null) === "true";
+  }
+  settleClear(path, actual, secure, box) {
+    const verdict = (0, import_agent_qa_runner.compareFillReread)({ expected: "", actual, secure, verb: "clearText" });
+    const fillVerdict = {
+      verb: "clearText",
+      verdict: verdict.verdict,
+      path,
+      ...verdict.secure ? { secure: true } : {}
+    };
+    const metadata = { ...verdict.meta ? { fillReread: verdict.meta } : {}, fillVerdict };
+    return verdict.ok ? { success: true, ...box, metadata } : { success: false, error: verdict.selfCorrectingError, ...box, metadata };
+  }
+  /** A driver error while clearing ends the clear; it is never repeated. */
+  interruptedClear(path, secure, box) {
+    return {
+      success: false,
+      error: "clearText was interrupted by a driver error; the field may be partly cleared, and it was not cleared again. Re-observe the field before clearing it again.",
+      ...box,
+      metadata: {
+        fillVerdict: {
+          verb: "clearText",
+          verdict: "unverified",
+          path,
+          ...secure ? { secure: true } : {}
+        }
+      }
+    };
+  }
+  /** A driver error during delivery ends the fill: nothing is typed again and no Enter follows. */
+  interruptedFill(path, secure, action, box) {
+    const fillVerdict = {
+      verb: "fill",
+      verdict: "unverified",
+      path,
+      ...secure ? { secure: true } : {}
+    };
+    return {
+      success: false,
+      error: "fill: typing was interrupted by a driver error; the field may hold part of the text, and it was not typed again. Re-observe the field before filling it again.",
+      ...box,
+      metadata: { fillVerdict, ...action.submit ? { fillSubmit: { ...INPUT_FAILED } } : {} }
+    };
+  }
+  /**
+   * The shared end of every Android fill (437 D-09, D-10, D-13, D-15, D-17): records the verdict
+   * and, when a submit was requested, holds Enter on a mismatch or a multi-line field and otherwise
+   * presses it once through `enter`.
+   */
+  async settleFill(action, box, settle) {
+    const { path, verdict, multiline, enter } = settle;
+    const fillVerdict = {
+      verb: "fill",
+      verdict: verdict.verdict,
+      path,
+      ...verdict.secure ? { secure: true } : {}
+    };
+    let fillSubmit;
+    if (action.submit) {
+      if (verdict.verdict === "mismatch") {
+        fillSubmit = { sent: false, outcome: "not-sent", reason: "mismatch" };
+      } else if (multiline) {
+        fillSubmit = { sent: false, outcome: "not-sent", reason: "multi-line-field" };
+      } else {
+        fillSubmit = await enter();
+      }
+    }
+    const notice = fillSubmit?.reason === "multi-line-field" ? { data: MULTI_LINE_SUBMIT_NOTICE } : {};
+    const metadata = {
+      ...verdict.meta ? { fillReread: verdict.meta } : {},
+      fillVerdict,
+      ...fillSubmit ? { fillSubmit } : {}
+    };
+    if (!verdict.ok) return { success: false, error: verdict.selfCorrectingError, ...box, metadata };
+    if (fillSubmit?.outcome === "failed") {
+      return {
+        success: false,
+        error: "fill typed the text, but Enter failed and was not sent again. Re-observe the screen; if the field still holds the text, submit it without typing it again.",
+        ...box,
+        metadata
+      };
+    }
+    return { success: true, ...box, ...notice, metadata };
+  }
+  /** A real W3C touch tap in the WebView context at the ref's CSS-pixel centre (437 D-11). */
+  async trustedWebTap(center) {
+    await safePerform(
+      this.driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y), origin: "viewport" }).down({ button: 0 }).up({ button: 0 })
+    );
+  }
+  /** Whether the tap left an editable field focused at the ref's point; read-only. */
+  async probeWebFocus(center) {
+    const none = { editable: false, matches: false, multiline: false, secure: false };
+    try {
+      const raw = await this.driver.execute(
+        WEB_FOCUS_PROBE_SCRIPT,
+        Math.round(center.x),
+        Math.round(center.y)
+      );
+      if (!raw || typeof raw !== "object") return none;
+      return {
+        editable: raw.editable === true,
+        matches: raw.matches === true,
+        multiline: raw.multiline === true,
+        secure: raw.secure === true,
+        ...typeof raw.value === "string" ? { value: raw.value } : {}
+      };
+    } catch {
+      return none;
+    }
+  }
+  /** Polls the read-only probe until the tap's field holds focus; returns the last answer. */
+  async awaitWebFocus(center) {
+    let focus = await this.probeWebFocus(center);
+    for (let poll = 1; poll < WEB_FOCUS_POLLS && !(focus.editable && focus.matches); poll++) {
+      await this.driver.pause(WEB_FOCUS_POLL_MS);
+      focus = await this.probeWebFocus(center);
+    }
+    return focus;
+  }
+  async readWebFieldValue() {
+    try {
+      const value = await this.driver.execute(WEB_FIELD_VALUE_SCRIPT);
+      return typeof value === "string" ? value : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  /** Runs a driver call from NATIVE_APP and always returns to the active WebView context. */
+  async withNativeContext(fn) {
+    await this.ensureContext("NATIVE_APP");
+    try {
+      return await fn();
+    } finally {
+      if (this.activeWebContext) await this.ensureContext(this.activeWebContext);
+    }
+  }
+  /** 437 D-11: a tap that left no editable field, or another field, focused writes nothing. */
+  refuseFocus(verb, ref, focus, submit, box) {
+    const nothing = verb === "fill" ? "nothing was typed" : "nothing was cleared";
+    let fillRefusal;
+    let error;
+    if (focus === "moved") {
+      fillRefusal = { verb, cause: "target-not-found", evidence: "stale-target" };
+      error = `${verb}: after tapping ${ref}, the focused field is no longer where it was observed; ${nothing}. Re-observe and target the field where it is now.`;
+    } else if (focus === "elsewhere") {
+      fillRefusal = { verb, cause: "not-editable", evidence: "focus-elsewhere" };
+      error = `${verb}: after tapping ${ref}, input focus is on another field; ${nothing}. Input is never sent to a field other than the target. Re-observe and target the field itself.`;
+    } else {
+      fillRefusal = { verb, cause: "not-editable", evidence: focus };
+      error = `${verb}: the tap on ${ref} did not focus an editable field; ${nothing}. Target the input itself and try again.`;
+    }
+    return {
+      success: false,
+      error,
+      ...box,
+      metadata: { fillRefusal, ...submit ? { fillSubmit: { ...INPUT_FAILED } } : {} }
+    };
+  }
+  /**
+   * WebView clearText (437 D-11, D-16): the same tap and focus probe as the fill, W3C Ctrl+A and
+   * Backspace, then a read-back judged against the empty string. Never success without that check.
+   */
+  async clearWebViewField(ref, center, box) {
+    const driver = this.driver;
+    await this.trustedWebTap(center);
+    const focus = await this.awaitWebFocus(center);
+    if (!focus.editable || !focus.matches) {
+      return this.refuseFocus("clearText", ref, webFocusEvidence(focus), false, box);
+    }
+    try {
+      await driver.keys(["Control", "a"]);
+      await driver.keys(["Backspace"]);
+    } catch {
+      return this.interruptedClear("webview", focus.secure, box);
+    }
+    return this.settleClear("webview", await this.readWebFieldValue(), focus.secure, box);
+  }
+  /**
+   * WebView fill as trusted input (437 D-11): a W3C tap on the ref, a read-only focus probe,
+   * W3C Ctrl+A and Backspace for replace, `mobile: type` from NATIVE_APP, a read-only read-back,
+   * and one `mobile: pressKey 66` from NATIVE_APP. No script writes the field or fires an event.
+   */
+  async fillWebViewCompound(action, box, center) {
+    const driver = this.driver;
+    const isAppend = action.clearMode === "append";
+    await this.trustedWebTap(center);
+    const focus = await this.awaitWebFocus(center);
+    if (!focus.editable || !focus.matches) {
+      return this.refuseFocus("fill", action.ref, webFocusEvidence(focus), action.submit, box);
+    }
+    if (!focus.multiline && LINE_BREAK_RE.test(action.text)) {
+      return this.refuseLineBreaks(action, box);
+    }
+    const prior = isAppend ? focus.value : "";
+    try {
+      if (isAppend) {
+        await driver.keys(focus.multiline ? ["Control", "End"] : ["End"]);
+      } else {
+        await driver.keys(["Control", "a"]);
+        await driver.keys(["Backspace"]);
+      }
+      await this.withNativeContext(() => driver.execute("mobile: type", { text: action.text }));
+    } catch {
+      return this.interruptedFill("webview", focus.secure, action, box);
+    }
+    const actual = prior === void 0 ? void 0 : await this.readWebFieldValue();
+    const verdict = (0, import_agent_qa_runner.compareFillReread)({
+      expected: (prior ?? "") + action.text,
+      actual,
+      secure: focus.secure
+    });
+    return await this.settleFill(action, box, {
+      path: "webview",
+      verdict,
+      multiline: focus.multiline,
+      enter: () => this.withNativeContext(() => this.pressEnter())
+    });
+  }
+  /**
+   * EXEC-02 platform primitives injected into the shared runner scroll loops (D-02/D-03; 436-02
+   * D-25). A native swipe is `mobile: scrollGesture` over the container (the ref's bounds, else the
+   * screen), whose boolean is the driver's own boundary signal; in a WebView the touch swipe is
+   * measured over every WebView scroller before and after (436-18), paired by identity (436-23).
+   * nativeSearchScroll drives the UiAutomator
+   * `UiScrollable.scrollIntoView` rung over an injection-escaped selector; readInterimTree is a
+   * light page-source parse — NO refMap mint, NO screenshot, lastRefs untouched.
+   */
+  async buildAndroidScrollPrimitives(scrollDirection, maxSwipes, factor = 1) {
+    const driver = this.driver;
+    const viewport = await driver.getWindowSize();
+    const axisLength = scrollDirection === "left" || scrollDirection === "right" ? viewport.width : viewport.height;
+    const distance = Math.max(1, Math.round(axisLength * 0.6 * factor));
+    const webViewSwipe = async (direction, ref) => {
+      let sx = Math.round(viewport.width / 2);
+      let sy = Math.round(viewport.height / 2);
+      if (ref) {
+        const { center } = new import_agent_qa_core2.MobileElementResolver(this.lastRefs).resolve(ref);
+        sx = Math.round(center.x);
+        sy = Math.round(center.y);
+      }
+      const before = await this.readWebViewScrollers();
+      const pts = (0, import_agent_qa_core2.computeSwipe)(sx, sy, fingerDirectionFor(direction), distance);
+      await safePerform(
+        driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: pts.startX, y: pts.startY }).down({ button: 0 }).move({ x: pts.endX, y: pts.endY, duration: 300 }).up({ button: 0 })
+      );
+      const after = await this.readWebViewScrollers();
+      return (0, import_agent_qa_core2.webViewSwipeSignal)(direction, before, after);
+    };
+    return {
+      swipeOnce: async (direction, ref) => {
+        if (this.activeWebContext) return webViewSwipe(direction, ref);
+        const area = gestureArea(
+          ref ? new import_agent_qa_core2.MobileElementResolver(this.lastRefs).resolve(ref).bounds : { x: 0, y: 0, width: viewport.width, height: viewport.height },
+          direction,
+          viewport
+        );
+        const canScrollMore = await driver.execute("mobile: scrollGesture", {
+          left: Math.round(area.x),
+          top: Math.round(area.y),
+          width: Math.max(1, Math.round(area.width)),
+          height: Math.max(1, Math.round(area.height)),
+          direction,
+          percent: 0.75 * factor
+        });
+        if (canScrollMore === true) return "moved";
+        if (canScrollMore === false) return "at-boundary";
+        return "unknown";
+      },
+      nativeSearchScroll: async (target) => {
+        const escaped = escapeUiSelectorText(target);
+        const selector = `new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().textContains("${escaped}"))`;
+        try {
+          await driver.execute("mobile: scroll", { strategy: "-android uiautomator", selector, maxSwipes });
+          return true;
+        } catch {
+          return false;
+        }
+      },
+      readInterimTree: async () => {
+        const xml = await driver.getPageSource();
+        const { nodes } = (0, import_agent_qa_core2.parseMobileSource)(xml, "android", viewport);
+        return nodes;
+      }
+    };
+  }
+  /**
+   * The WebView scrollers a touch swipe may have acted on (436-18 · D-25), read by the shared
+   * WEBVIEW_SCROLLERS_SCRIPT. The touch point cannot be mapped into the WebView's CSS coordinates,
+   * so the swipe is judged over all of them.
+   * 2026-10-08 (436-23): a frame in view reads unknown; members carry an identity and are paired
+   * by it; open shadow roots are walked; only on-screen element scrollers are members.
+   */
+  async readWebViewScrollers() {
+    try {
+      return (0, import_agent_qa_core2.parseWebViewScrollers)(await this.driver.execute(import_agent_qa_core2.WEBVIEW_SCROLLERS_SCRIPT));
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * EXEC-03 openApp (D-10/D-11/D-12). Resolve a human name to a package id (or validate an
+   * explicit bundleId) over the session-cached registry, then launch via activateApp. On a
+   * resolution MISS the registry is re-enumerated exactly once (catches mid-run installs) before
+   * erroring with the resolver's candidate ids. Never a best-guess launch (T-359-04).
+   */
+  async openApp(action) {
+    const driver = this.driver;
+    let registry = await this.ensureAppRegistry();
+    if (registry === null) {
+      return {
+        success: false,
+        error: 'openApp could not enumerate installed apps: "mobile: listApps" failed and the shell fallback is disabled. Retry with an explicit openApp {bundleId}, or set AGENT_QA_ANDROID_USE_MOBILE_SHELL=1 to allow the pm-list fallback.'
+      };
+    }
+    if ("bundleId" in action) {
+      if (!registry.some((entry) => entry.id === action.bundleId)) {
+        return {
+          success: false,
+          error: `openApp: bundleId "${action.bundleId}" is not installed (not in the app registry). Verify the package id or use openApp {appName}.`
+        };
+      }
+      await driver.activateApp(action.bundleId);
+      return { success: true, metadata: { openApp: { resolvedId: action.bundleId, matchKind: "explicit" } } };
+    }
+    let resolution = (0, import_agent_qa_runner.resolveAppName)(action.appName, registry);
+    if (resolution.kind === "unknown" || resolution.kind === "ambiguous") {
+      const fresh = await this.enumerateApps();
+      if (fresh !== null) {
+        this.appRegistry = fresh;
+        registry = fresh;
+        resolution = (0, import_agent_qa_runner.resolveAppName)(action.appName, registry);
+      }
+    }
+    switch (resolution.kind) {
+      case "exact":
+      case "fuzzy":
+        await driver.activateApp(resolution.id);
+        return { success: true, metadata: { openApp: { resolvedId: resolution.id, matchKind: resolution.kind } } };
+      case "ambiguous":
+      case "unknown": {
+        const ids = resolution.candidates.map((c) => c.id).join(", ");
+        const lead = resolution.kind === "ambiguous" ? "is ambiguous between installed apps" : "did not match an installed app";
+        return {
+          success: false,
+          error: `openApp: "${action.appName}" ${lead}. Closest candidates: ${ids || "(none)"}. Retry openApp {bundleId} with the exact package id.`
+        };
+      }
+    }
+  }
+  /** Return the cached registry, enumerating once on first use. Failed enumeration returns null (uncached). */
+  async ensureAppRegistry() {
+    if (this.appRegistry !== null) return this.appRegistry;
+    const enumerated = await this.enumerateApps();
+    if (enumerated !== null) this.appRegistry = enumerated;
+    return enumerated;
+  }
+  /**
+   * Enumerate installed apps through the driver only (ownership contract — no adb/child_process).
+   * `mobile: listApps` maps package ids → AppRegistryEntry (labels only when the same call carries
+   * them, D-10 — no per-package round-trips). On failure, fall back to `mobile: shell` pm-list ONLY
+   * when the AGENT_QA_ANDROID_USE_MOBILE_SHELL gate is '1' (Pitfall 4). Null = enumeration unavailable.
+   */
+  async enumerateApps() {
+    const driver = this.driver;
+    try {
+      const raw = await driver.execute("mobile: listApps");
+      return this.mapListApps(raw);
+    } catch {
+      if (process.env.AGENT_QA_ANDROID_USE_MOBILE_SHELL === "1") {
+        try {
+          const out = String(await driver.execute("mobile: shell", { command: "pm", args: ["list", "packages"] }));
+          return this.parsePmListPackages(out);
+        } catch {
+          return null;
+        }
+      }
+      return null;
+    }
+  }
+  /** Coerce a `mobile: listApps` result (package-id-keyed map, or an array of entries) into the registry. */
+  mapListApps(raw) {
+    const labelOf = (value) => {
+      if (!value || typeof value !== "object") return void 0;
+      const v = value;
+      for (const key of ["label", "name", "appName"]) {
+        const candidate = v[key];
+        if (typeof candidate === "string" && candidate.length > 0) return candidate;
+      }
+      return void 0;
+    };
+    const entries = [];
+    if (Array.isArray(raw)) {
+      for (const item of raw) {
+        if (!item || typeof item !== "object") continue;
+        const v = item;
+        const id = v.packageName ?? v.bundleId ?? v.id;
+        if (typeof id !== "string" || id.length === 0) continue;
+        const label = labelOf(item);
+        entries.push(label !== void 0 ? { id, label } : { id });
+      }
+    } else if (raw && typeof raw === "object") {
+      for (const [id, value] of Object.entries(raw)) {
+        if (!id) continue;
+        const label = labelOf(value);
+        entries.push(label !== void 0 ? { id, label } : { id });
+      }
+    }
+    return entries;
+  }
+  /** Parse `pm list packages` output ("package:com.foo\n…") into id-only registry entries. */
+  parsePmListPackages(output) {
+    const entries = [];
+    for (const line of output.split("\n")) {
+      const id = line.trim().replace(/^package:/, "");
+      if (id) entries.push({ id });
+    }
+    return entries;
+  }
+  // ---------------------------------------------------------------------------
   // Actions
   // ---------------------------------------------------------------------------
   async executeAction(action) {
@@ -588,8 +1536,7 @@ var AndroidPlatformAdapter = class {
     const resolver = new import_agent_qa_core2.MobileElementResolver(this.lastRefs);
     const inWeb = !!this.activeWebContext;
     switch (action.type) {
-      case "tap":
-      case "click": {
+      case "tap": {
         const { center, bounds } = resolver.resolve(action.ref);
         if (inWeb) {
           await driver.execute(
@@ -614,50 +1561,20 @@ var AndroidPlatformAdapter = class {
             error: `Element ${action.ref} is not fillable (role: ${role}). Use a textbox or input element instead.`
           };
         }
+        const box = { coordinates: center, boundingBox: bounds };
         if (inWeb) {
-          await driver.execute(
-            "var el = document.elementFromPoint(arguments[0], arguments[1]);if (el) { el.focus(); el.click(); }",
-            center.x,
-            center.y
-          );
-          await driver.execute(
-            'var el = document.activeElement;if (el) { el.value = ""; el.value = arguments[0];el.dispatchEvent(new Event("input", {bubbles:true})); }',
-            action.value
-          );
-          return { success: true, coordinates: center, boundingBox: bounds };
+          return await this.fillWebViewCompound(action, box, center);
         }
         await safePerform(
           driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y) }).down({ button: 0 }).up({ button: 0 })
         );
-        try {
-          const el = await driver.$('//*[@focused="true"]');
-          if (await el.isExisting()) {
-            await el.setValue(action.value);
-            return { success: true, coordinates: center, boundingBox: bounds };
-          }
-        } catch {
-        }
-        await driver.keys([action.value]);
-        return { success: true, coordinates: center, boundingBox: bounds };
-      }
-      case "select": {
-        const { center, bounds } = resolver.resolve(action.ref);
-        if (inWeb) {
-          await driver.execute(
-            'var el = document.elementFromPoint(arguments[0], arguments[1]);if (el) { el.value = arguments[2];el.dispatchEvent(new Event("change", {bubbles:true})); }',
-            center.x,
-            center.y,
-            action.value
-          );
-          return { success: true, coordinates: center, boundingBox: bounds };
-        } else {
-          return {
-            success: false,
-            error: "select is for HTML dropdowns. Use nativeSelect for Android native picker/dropdown/list controls, or tap/swipe/tapCoordinate for custom controls.",
-            coordinates: center,
-            boundingBox: bounds
-          };
+        const focusedEl = await this.focusedField();
+        const verdict = focusedEl ? await this.focusIsElsewhere(focusedEl, action.ref, bounds) : "target";
+        if (verdict !== "target") {
+          return this.refuseFocus("fill", action.ref, verdict, action.submit, box);
         }
+        if (focusedEl) return await this.fillNativeCompound(focusedEl, action, box);
+        return await this.fillKeyboardPath(action, box, refData);
       }
       case "nativeSelect": {
         const { center, bounds } = resolver.resolve(action.ref);
@@ -704,51 +1621,61 @@ var AndroidPlatformAdapter = class {
         };
       }
       case "scroll": {
-        if (inWeb) {
-          const dx = action.scrollType === "horizontal" ? action.value : 0;
-          const dy = action.scrollType === "vertical" ? action.value : 0;
-          await driver.execute(
-            "window.scrollBy(arguments[0], arguments[1]);",
-            dx,
-            dy
-          );
-          return { success: true };
+        if (action.mode === "untilVisible") {
+          try {
+            escapeUiSelectorText(action.text);
+          } catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+          }
+          const primitives2 = await this.buildAndroidScrollPrimitives(action.direction, action.maxSwipes);
+          const { meta: meta2 } = await (0, import_agent_qa_runner.runUntilVisibleLoop)(primitives2, {
+            target: action.text,
+            direction: action.direction,
+            maxSwipes: action.maxSwipes,
+            retryOpposite: action.retryOpposite,
+            ...action.ref ? { ref: action.ref } : {}
+          });
+          return { success: true, metadata: { scrollUntilVisible: meta2 } };
         }
-        const { width, height } = await driver.getWindowSize();
-        const centerX = Math.round(width / 2);
-        const centerY = Math.round(height / 2);
-        const scrollStartX = centerX;
-        const scrollStartY = centerY;
-        const scrollEndX = action.scrollType === "horizontal" ? centerX - action.value : centerX;
-        const scrollEndY = action.scrollType === "vertical" ? centerY - action.value : centerY;
-        const scrollDuration = action.duration ?? 300;
-        await safePerform(
-          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: scrollStartX, y: scrollStartY }).down({ button: 0 }).move({ x: scrollEndX, y: scrollEndY, duration: scrollDuration }).up({ button: 0 })
-        );
-        return { success: true };
+        const factor = action.amount === "halfPage" ? 0.5 : 1;
+        const primitives = await this.buildAndroidScrollPrimitives(action.direction, 0, factor);
+        if (action.amount === "toEnd") {
+          const { meta: meta2 } = await (0, import_agent_qa_runner.runToEndScroll)(primitives, action.direction, action.ref);
+          return { success: true, metadata: { scrollUntilVisible: meta2 } };
+        }
+        const { meta } = await (0, import_agent_qa_runner.runDirectionScroll)(primitives, {
+          direction: action.direction,
+          ...action.ref ? { ref: action.ref } : {}
+        });
+        return { success: true, metadata: { scrollUntilVisible: meta } };
       }
       case "swipe": {
         if (inWeb) {
           await this.ensureContext("NATIVE_APP");
         }
         const { width, height } = await driver.getWindowSize();
-        let sx = Math.round(width / 2);
-        let sy = Math.round(height / 2);
-        if (action.ref) {
-          const { center } = resolver.resolve(action.ref);
-          sx = Math.round(center.x);
-          sy = Math.round(center.y);
-        }
-        const distance = Math.round(height * 0.6);
-        const pts = action.startX !== void 0 && action.startY !== void 0 && action.endX !== void 0 && action.endY !== void 0 ? {
-          startX: action.startX,
-          startY: action.startY,
-          endX: action.endX,
-          endY: action.endY
-        } : (0, import_agent_qa_core2.computeSwipe)(sx, sy, action.direction, distance);
+        let pts;
+        if (action.mode === "path") {
+          pts = {
+            startX: Math.round(action.from.x),
+            startY: Math.round(action.from.y),
+            endX: Math.round(action.to.x),
+            endY: Math.round(action.to.y)
+          };
+        } else {
+          let sx = Math.round(width / 2);
+          let sy = Math.round(height / 2);
+          if (action.ref) {
+            const { center } = resolver.resolve(action.ref);
+            sx = Math.round(center.x);
+            sy = Math.round(center.y);
+          }
+          const distance = Math.round(height * 0.6);
+          pts = (0, import_agent_qa_core2.computeSwipe)(sx, sy, action.direction, distance);
+        }
         (0, import_agent_qa_core2.warnIfOutOfBounds)({ x: pts.startX, y: pts.startY }, { width, height }, "swipe");
         (0, import_agent_qa_core2.warnIfOutOfBounds)({ x: pts.endX, y: pts.endY }, { width, height }, "swipe");
-        const swipeDuration = action.duration ?? 300;
+        const swipeDuration = action.durationMs;
         await safePerform(
           driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: pts.startX, y: pts.startY }).down({ button: 0 }).move({ x: pts.endX, y: pts.endY, duration: swipeDuration }).up({ button: 0 })
         );
@@ -765,13 +1692,14 @@ var AndroidPlatformAdapter = class {
         const { width: pinchW, height: pinchH } = await driver.getWindowSize();
         let pcx = Math.round(pinchW / 2);
         let pcy = Math.round(pinchH / 2);
-        if (action.ref) {
+        if ("ref" in action) {
           const { center } = resolver.resolve(action.ref);
           pcx = Math.round(center.x);
           pcy = Math.round(center.y);
+        } else {
+          pcx = action.x;
+          pcy = action.y;
         }
-        if (action.x !== void 0) pcx = action.x;
-        if (action.y !== void 0) pcy = action.y;
         (0, import_agent_qa_core2.warnIfOutOfBounds)({ x: pcx, y: pcy }, { width: pinchW, height: pinchH }, "pinch");
         const { finger1Start, finger1End, finger2Start, finger2End } = (0, import_agent_qa_core2.computePinch)(pcx, pcy, action.scale);
         const pinchDuration = 500;
@@ -785,13 +1713,14 @@ var AndroidPlatformAdapter = class {
         const { width: mtW, height: mtH } = await driver.getWindowSize();
         let mtcx = Math.round(mtW / 2);
         let mtcy = Math.round(mtH / 2);
-        if (action.ref) {
+        if ("ref" in action) {
           const { center } = resolver.resolve(action.ref);
           mtcx = Math.round(center.x);
           mtcy = Math.round(center.y);
+        } else {
+          mtcx = action.x;
+          mtcy = action.y;
         }
-        if (action.x !== void 0) mtcx = action.x;
-        if (action.y !== void 0) mtcy = action.y;
         (0, import_agent_qa_core2.warnIfOutOfBounds)({ x: mtcx, y: mtcy }, { width: mtW, height: mtH }, "multiTap");
         const positions = (0, import_agent_qa_core2.computeFingerPositions)(mtcx, mtcy, action.fingers);
         await driver.actions(
@@ -809,34 +1738,48 @@ var AndroidPlatformAdapter = class {
         return { success: true };
       }
       case "waitFor": {
-        await driver.pause(action.timeout ?? 2e3);
-        return { success: true };
+        if (action.on === "selector") {
+          return {
+            success: false,
+            error: 'waitFor {on:"selector"} (CSS/XPath) is a web-only mode. On native Android, wait on visible text with waitFor {on:"text"} or {on:"gone"}.'
+          };
+        }
+        const wantPresent = action.on === "text";
+        const needle = action.text;
+        const deadline = Date.now() + action.timeoutMs;
+        for (; ; ) {
+          let source = "";
+          try {
+            source = await driver.getPageSource();
+          } catch {
+            source = "";
+          }
+          if (source.includes(needle) === wantPresent) return { success: true };
+          if (Date.now() >= deadline) break;
+          await driver.pause(Math.min(250, Math.max(1, deadline - Date.now())));
+        }
+        return {
+          success: false,
+          error: wantPresent ? `waitFor: text "${needle}" did not appear within ${action.timeoutMs}ms.` : `waitFor: text "${needle}" was still present after ${action.timeoutMs}ms.`
+        };
       }
       case "delay": {
         await driver.pause(action.ms);
         return { success: true };
       }
       case "keypress": {
+        if (action.mode !== "press") {
+          return {
+            success: false,
+            error: `keypress {mode:"${action.mode}"} (key hold/release) is web-only. On mobile, emit keypress {mode:"press"} to send the key.`
+          };
+        }
         for (const rawKey of action.keys) {
           const mapped = import_agent_qa_core2.KEY_MAP[rawKey] ?? rawKey;
           await driver.keys([mapped]);
         }
         return { success: true };
       }
-      case "navigate": {
-        try {
-          await driver.url(action.url);
-          return { success: true };
-        } catch {
-          return { success: false, error: "navigate is not supported for this app. Use tap/fill on UI elements to navigate." };
-        }
-      }
-      case "hover": {
-        return { success: false, error: "hover is a web-only action. Use tap or longpress instead." };
-      }
-      case "assert": {
-        return { success: true };
-      }
       // --- New actions ---
       case "hideKeyboard": {
         try {
@@ -859,41 +1802,113 @@ var AndroidPlatformAdapter = class {
             error: `Element ${action.ref} is not fillable (role: ${clearRole}). clearText only works on text inputs. Use a textbox or input element instead.`
           };
         }
+        if (inWeb) {
+          return await this.clearWebViewField(action.ref, center, {
+            coordinates: center,
+            boundingBox: bounds
+          });
+        }
         await safePerform(
           driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y) }).down({ button: 0 }).up({ button: 0 })
         );
-        try {
-          const el = await driver.$('//*[@focused="true"]');
-          if (await el.isExisting()) {
-            await el.clearValue();
-          }
-        } catch {
+        const clearBox = { coordinates: center, boundingBox: bounds };
+        const clearHandle = await this.focusedField();
+        const clearVerdict = clearHandle ? await this.focusIsElsewhere(clearHandle, action.ref, bounds) : "target";
+        if (clearVerdict !== "target") {
+          return this.refuseFocus("clearText", action.ref, clearVerdict, false, clearBox);
         }
-        return { success: true, coordinates: center, boundingBox: bounds };
+        return await this.clearNativeOrKeyboard(clearBox, clearHandle);
+      }
+      // --- Android hardware / system verbs (numeric keycodes / typed driver args only) ---
+      case "pressBack":
+        await driver.execute("mobile: pressKey", { keycode: 4 });
+        return { success: true };
+      case "pressHome":
+        await driver.execute("mobile: pressKey", { keycode: 3 });
+        return { success: true };
+      case "pressRecent":
+        await driver.execute("mobile: pressKey", { keycode: 187 });
+        return { success: true };
+      case "openNotifications":
+        await driver.execute("mobile: openNotifications");
+        return { success: true };
+      case "openQuickSettings":
+        return await this.runShell("openQuickSettings", {
+          command: "cmd",
+          args: ["statusbar", "expand-settings"]
+        });
+      case "intent": {
+        const TYPE_TAG = {
+          string: "s",
+          int: "i",
+          long: "l",
+          float: "f",
+          bool: "z"
+        };
+        const intentArgs = { action: action.action };
+        if (action.data !== void 0) intentArgs.uri = action.data;
+        if (action.packageName !== void 0) intentArgs.package = action.packageName;
+        if (action.extras && action.extras.length > 0) {
+          intentArgs.extras = action.extras.map(
+            (e) => [TYPE_TAG[e.type], e.key, e.value]
+          );
+        }
+        await driver.execute("mobile: startActivity", intentArgs);
+        return { success: true };
       }
-      case "openLink": {
-        const appPackage = firstNonEmpty(action.appId, action.appPackage, this.appPackage);
-        const isWebUrl = /^https?:\/\//i.test(action.url);
-        if (!appPackage && !isWebUrl) {
-          return { success: false, error: `Missing Android app package for native deep link: ${action.url}` };
+      case "keyevent": {
+        if (!/^KEYCODE_[A-Z0-9_]+$/.test(action.keycode)) {
+          return {
+            success: false,
+            error: `keyevent: "${action.keycode}" is not a valid Android key code. Provide a symbolic code matching ^KEYCODE_[A-Z0-9_]+$ (e.g. KEYCODE_ENTER, KEYCODE_TAB).`
+          };
         }
-        try {
-          if (appPackage) {
-            await driver.execute("mobile: deepLink", { url: action.url, package: appPackage });
-          } else {
-            await driver.url(action.url);
+        return await this.runShell("keyevent", {
+          command: "input",
+          args: ["keyevent", action.keycode]
+        });
+      }
+      case "assertValue": {
+        if ("expr" in action) {
+          if (!inWeb) {
+            return {
+              success: false,
+              error: "assertValue {expr} evaluates JavaScript and is only available in an Android WebView/browser context. Assert on a native signal, or run against a web target."
+            };
           }
-          return { success: true };
-        } catch (err) {
-          if (!isWebUrl) {
-            return { success: false, error: `Failed to open link ${action.url} in Android app ${appPackage}: ${err instanceof Error ? err.message : String(err)}` };
+          const value = await driver.execute(`return (${action.expr});`);
+          return { success: true, data: value };
+        }
+        switch (action.source) {
+          case "url": {
+            if (!inWeb) {
+              return {
+                success: false,
+                error: 'assertValue {source:"url"} reads the browser URL and is only available in an Android WebView/browser context; native screens have no URL.'
+              };
+            }
+            const value = await driver.execute("return window.location.href;");
+            return { success: true, data: value };
           }
-          try {
-            await driver.url(action.url);
-            return { success: true };
-          } catch (fallbackErr) {
-            return { success: false, error: `Failed to open link: ${action.url}: ${fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr)}` };
+          case "storage": {
+            if (!inWeb) {
+              return {
+                success: false,
+                error: 'assertValue {source:"storage"} reads Web Storage and is only available in an Android WebView/browser context.'
+              };
+            }
+            const value = await driver.execute(
+              "return Object.fromEntries(Object.keys(localStorage).map(function(k){return [k, localStorage.getItem(k)];}));"
+            );
+            return { success: true, data: value };
           }
+          case "network":
+            return {
+              success: false,
+              error: 'assertValue {source:"network"} (HTTP log inspection) is not available on the Android adapter. Use a web target for network assertions, or assert on visible UI text.'
+            };
+          case "expr-result":
+            return { success: true, data: void 0 };
         }
       }
       case "drag": {
@@ -915,10 +1930,8 @@ var AndroidPlatformAdapter = class {
         );
         return { success: true, coordinates: center, boundingBox: bounds };
       }
-      case "launchApp": {
-        await driver.activateApp(action.bundleId);
-        return { success: true };
-      }
+      case "openApp":
+        return await this.openApp(action);
       case "stopApp": {
         await driver.terminateApp(action.bundleId);
         return { success: true };
@@ -949,15 +1962,21 @@ var AndroidPlatformAdapter = class {
         }
         return { success: true, coordinates: { x, y } };
       }
-      case "readConsoleLogs": {
-        await this.pollDeviceLogs();
-        const all = [...this.consoleLogs];
-        const entries = action.level ? all.filter((e) => e.level === action.level) : all;
-        return { success: true, data: entries };
-      }
-      default: {
-        return { success: false, error: `Unknown action type: ${action.type}` };
-      }
+      // Runner-minted / author-channel verbs (D-01/D-15): reportValue, assertAI, extractAI, and
+      // setVariable are intercepted at the runner dispatch seam and never reach the adapter. A
+      // grouped §7.1 defensive case surfaces a dispatch-routing error if one arrives here;
+      // assertNever remains the backstop for a genuinely unknown schema verb. (uniqueValue is
+      // web-only and is not part of ActionsFor<'android'>.)
+      case "reportValue":
+      case "assertAI":
+      case "extractAI":
+      case "setVariable":
+        return {
+          success: false,
+          error: `Action "${action.type}" is handled by the runner dispatch seam and must not reach the Android adapter (runner-minted/author-channel verb). This indicates a dispatch routing error.`
+        };
+      default:
+        return (0, import_agent_qa_runner.assertNever)(action);
     }
   }
 };