@aarwitz/tapp 0.17.0-rc.1 → 0.17.0-rc.3

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -946,6 +946,7 @@ class ExplorerTests: XCTestCase {
         var elementScreenPresence: [String: Set<String>] = [:]
         var totalDistinctStates = 0
         var recentStateHashes: [String] = []
+        var recentScreenTitles: [String] = []
         var actionsSinceNewState = 0
         var sameScreenStreak = 0
         var screenTextEntryCount: [String: Int] = [:]
@@ -1238,6 +1239,15 @@ class ExplorerTests: XCTestCase {
         let initialControlsJson = mapControlsJSON(initialElements)
         print("OCQA_STATE:{\"screen\":\"\(escapeJSON(initialTitle))\",\"hash\":\"\(computeHash(initialElements))\",\"elements\":\(initialElements.count),\"action\":0,\"role\":\"\(escapeJSON(initialRole))\",\"summary\":\"\(escapeJSON(initialSummary))\",\"settled\":\(isScreenSettled() ? "true" : "false"),\"atext\":[\(initialAtext)],\"inputs\":[\(initialInputJson)],\"controls\":[\(initialControlsJson)]}")
 
+        // The launch surface is real evidence even when root normalization immediately dismisses
+        // it. Attach it before the first action so the HTML report's "every screen explored" claim
+        // includes onboarding/login sheets rather than beginning at the post-dismiss destination.
+        let initialScreenshot = app.screenshot()
+        let initialAttachment = XCTAttachment(screenshot: initialScreenshot)
+        initialAttachment.name = "state_0_\(initialTitle.replacingOccurrences(of: " ", with: "_"))"
+        initialAttachment.lifetime = .keepAlways
+        add(initialAttachment)
+
         navigateToRootScreen(actionCount: &actionCount)
 
         // The first state is the true customer launch surface. Directed replay begins after
@@ -1386,8 +1396,10 @@ class ExplorerTests: XCTestCase {
             }
 
             recentStateHashes.append(stateHash)
+            recentScreenTitles.append(titleStr)
             if recentStateHashes.count > 12 {
                 recentStateHashes.removeFirst(recentStateHashes.count - 12)
+                recentScreenTitles.removeFirst(recentScreenTitles.count - 12)
             }
 
             if previousStateHash == stateHash {
@@ -1474,10 +1486,19 @@ class ExplorerTests: XCTestCase {
             // is the fuller a11y text inventory that grounds the vision reviewer (see visionTextInventory).
             let escapedTitle = escapeJSON(titleStr)
             let settled = isScreenSettled()
-            let atextJson = visionTextInventory(elements).map { "\"\(escapeJSON($0))\"" }.joined(separator: ",")
+            let visibleTextInventory = visionTextInventory(elements)
+            let atextJson = visibleTextInventory.map { "\"\(escapeJSON($0))\"" }.joined(separator: ",")
             let controlsJson = mapControlsJSON(elements)
             print("OCQA_STATE:{\"screen\":\"\(escapedTitle)\",\"hash\":\"\(stateHash)\",\"elements\":\(elements.count),\"action\":\(actionCount),\"role\":\"\(escapeJSON(screenRole))\",\"summary\":\"\(escapeJSON(screenSummary))\",\"settled\":\(settled ? "true" : "false"),\"atext\":[\(atextJson)],\"inputs\":[\(inputJsonArray)],\"controls\":[\(controlsJson)]}")
 
+            // Signing out after a successful login is a completed auth cycle, not a navigation
+            // trap and not lost-form-state. Stop cleanly instead of probing the root login screen
+            // for an impossible back path or expecting credentials to persist after logout.
+            if authSucceeded && detectedInputs.contains(where: { $0.secure }) {
+                print("OCQA_STATE:auth_cycle_complete screen=\(escapedTitle) step=\(actionCount)")
+                break
+            }
+
             // ---- Persistence probe: on a fresh RE-ARRIVAL at a screen, fields we previously
             // typed into (and verified visible in the a11y value) should still hold their value.
             // An empty field here means the entered state was silently lost on navigation —
@@ -1591,14 +1612,14 @@ class ExplorerTests: XCTestCase {
             // content-feed app: post detail + replies-loading spinner flagged app_hang HIGH).
             let visibleTextCount = elements.filter { isStaticTextType($0.type) && normalizeVisibleText($0.label).count >= 3 }.count
             if screenVisitCount[titleStr] ?? 0 <= 1, visibleTextCount <= 4,
-               app.activityIndicators.firstMatch.exists || app.progressIndicators.firstMatch.exists {
+               hasIndeterminateLoadingIndicator() {
                 let loadingKey = "loading:\(titleStr)"
                 if !reportedIssueKeys.contains(loadingKey) {
                     var resolved = false
                     let deadline = Date().addingTimeInterval(8.0)
                     while Date() < deadline {
                         Thread.sleep(forTimeInterval: 1.0)
-                        if !(app.activityIndicators.firstMatch.exists || app.progressIndicators.firstMatch.exists) {
+                        if !hasIndeterminateLoadingIndicator() {
                             resolved = true
                             break
                         }
@@ -1658,7 +1679,7 @@ class ExplorerTests: XCTestCase {
 
             // ---- Blank-screen detection ----
             // Distinguish between "no a11y labels / custom UI" vs genuinely empty.
-            if elements.count < 5 && interactable.count == 0 {
+            if visibleTextInventory.isEmpty && interactable.count == 0 {
                 let blankKey = "blank:\(titleStr)"
                 let blankCount = (actionCounts[blankKey] ?? 0) + 1
                 actionCounts[blankKey] = blankCount
@@ -1690,16 +1711,26 @@ class ExplorerTests: XCTestCase {
             }
 
             // ---- Navigation-loop detection ----
-            // Check if recentStateHashes has a repeating cycle of length 2 or 3
+            // A cycle must actually move across distinct states. Four identical reads satisfy the
+            // arithmetic shape A,A,A,A of the old period-2 check, which mislabeled ordinary
+            // scroll/probe recovery on a stable screen as a navigation loop.
             if recentStateHashes.count >= 6 {
                 let recent = recentStateHashes
+                // Distinct structural hashes are not enough: a list and its detail rows can share
+                // one navigation title and alternate A/B while the explorer intentionally samples
+                // different rows. Calling that a navigation loop is a false positive. Require the
+                // cycle to cross distinct user-visible screen titles as well.
                 let hasLoop2 = recent.count >= 4 &&
                     recent[recent.count - 1] == recent[recent.count - 3] &&
-                    recent[recent.count - 2] == recent[recent.count - 4]
+                    recent[recent.count - 2] == recent[recent.count - 4] &&
+                    Set(recent.suffix(2)).count == 2 &&
+                    Set(recentScreenTitles.suffix(2)).count == 2
                 let hasLoop3 = recent.count >= 6 &&
                     recent[recent.count - 1] == recent[recent.count - 4] &&
                     recent[recent.count - 2] == recent[recent.count - 5] &&
-                    recent[recent.count - 3] == recent[recent.count - 6]
+                    recent[recent.count - 3] == recent[recent.count - 6] &&
+                    Set(recent.suffix(3)).count == 3 &&
+                    Set(recentScreenTitles.suffix(3)).count == 3
                 if (hasLoop2 || hasLoop3) && !(authSucceeded && detectedInputs.contains { $0.secure }) {
                     let loopKey = "nav_loop:\(titleStr)"
                     if actionCounts[loopKey] == nil {
@@ -1711,17 +1742,10 @@ class ExplorerTests: XCTestCase {
                 }
             }
 
-            // ---- Unresponsive-element detection ----
-            // Skip when we're merely re-poking a login screen we've already passed (Sign Out → re-login
-            // churn) — that's an exploration artifact, not a frozen/broken screen.
-            if repeatedStateCount >= 5 && !(authSucceeded && detectedInputs.contains { $0.secure }) {
-                let unrespKey = "unresponsive:\(titleStr)"
-                if actionCounts[unrespKey] == nil {
-                    issues.append((type: "unresponsive_element", severity: "medium", title: "Unresponsive UI on \(titleStr)", desc: "Actions are not changing app state — possible frozen or broken screen"))
-                    print("OCQA_ISSUE:{\"type\":\"unresponsive_element\",\"severity\":\"medium\",\"title\":\"Unresponsive UI\",\"screen\":\"\(escapedTitle)\",\"repeated_state_count\":\(repeatedStateCount),\"step\":\(actionCount)}")
-                    actionCounts[unrespKey] = 1
-                }
-            }
+            // Do not infer an unresponsive app merely from an unchanged state streak: recovery
+            // gestures (scroll, carousel probe, center probe) are expected to be no-ops on many
+            // healthy screens. Labeled controls have a stronger detector below: a direct tap plus
+            // two delayed, content-signature reads. Hangs have their own time-based detector.
 
             if interactable.count < 3 {
                 print("OCQA_STATE:low_interactable screen=\(escapedTitle) total=\(elements.count) interactable=\(interactable.count) global=\(globalNavElements.count) nonGlobal=\(nonGlobalCandidates.count)")
@@ -1757,10 +1781,10 @@ class ExplorerTests: XCTestCase {
                     break
                 }
 
-                let issueTitle = "Dead end: \(titleStr)"
-                issues.append((type: "dead_end", severity: "medium", title: issueTitle, desc: "No interactable elements found"))
-                print("OCQA_ISSUE:{\"type\":\"dead_end\",\"severity\":\"medium\",\"title\":\"\(escapeJSON(issueTitle))\",\"screen\":\"\(escapedTitle)\",\"step\":\(actionCount)}")
-
+                // Exhausting Tapp's untried candidate pool is not itself a user-visible dead end:
+                // leaf screens commonly have only a working Back control that was already mapped.
+                // Recover first; only the stronger navigation-trap path below emits a finding when
+                // every real back/dismiss route fails.
                 // tryGoBack does swipe-down as its last resort (sheet dismiss)
                 let preBackTitle = titleStr
                 let backWorked = tryGoBack()
@@ -1772,6 +1796,7 @@ class ExplorerTests: XCTestCase {
                     print("OCQA_ACTION:{\"type\":\"back\",\"reason\":\"dead_end_escape\",\"from\":\"\(escapedTitle)\",\"to\":\"\(escapeJSON(postTitle))\",\"step\":\(actionCount),\"screen\":\"\(escapedTitle)\",\"narrative\":\"\(escapeJSON(recoveryNarrative("back_dead_end", screen: titleStr, to: postTitle)))\"}")
                     continue
                 }
+                if actionCount >= maxActions { break }
                 // Swipe right (back gesture) as another option
                 let swipeStart = app.coordinate(withNormalizedOffset: CGVector(dx: 0.02, dy: 0.5))
                 let swipeEnd = app.coordinate(withNormalizedOffset: CGVector(dx: 0.8, dy: 0.5))
@@ -2047,6 +2072,7 @@ class ExplorerTests: XCTestCase {
                 }
                 // Back didn't change screens — fall through to global nav
                 print("OCQA_ACTION:{\"type\":\"back\",\"reason\":\"screen_exhausted_failed\",\"screen\":\"\(escapedTitle)\",\"step\":\(actionCount),\"narrative\":\"\(escapeJSON(recoveryNarrative("back_failed", screen: titleStr)))\"}")
+                if actionCount >= maxActions { break }
                 // Stuck on this screen — use global navigation (tab bar) to reach unexplored areas
                 let globalNav = interactable
                     .filter { isLikelyGlobalNavigation($0, screenBounds: screenBounds) }
@@ -3679,6 +3705,20 @@ class ExplorerTests: XCTestCase {
         return kb.exists ? kb.frame : .zero
     }
 
+    /// Activity indicators are inherently indeterminate. `ProgressIndicator`, however, is also the
+    /// XCTest type for legitimate determinate progress bars (loyalty points, upload percentage,
+    /// onboarding completion). Only value-less/loading-valued progress indicators are hang signals.
+    private func hasIndeterminateLoadingIndicator() -> Bool {
+        if app.activityIndicators.allElementsBoundByIndex.contains(where: { $0.exists && $0.frame.width > 0 && $0.frame.height > 0 }) {
+            return true
+        }
+        return app.progressIndicators.allElementsBoundByIndex.contains { indicator in
+            guard indicator.exists, indicator.frame.width > 0, indicator.frame.height > 0 else { return false }
+            let value = (indicator.value as? String ?? "").trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+            return value.isEmpty || value == "in progress" || value == "loading"
+        }
+    }
+
     /// True when the screen is in a "settled" resting state — no on-screen keyboard and no open
     /// transient overlay (menu / dropdown / popover / sheet / picker wheel). A screenshot taken while
     /// one of these is up is inherently ambiguous to a visual reviewer (the keyboard "covers" the

package/bin/tapp.js

@@ -130,6 +130,27 @@ function repeatedFlagValues(argv, name) {
   return values;
 }
 
+function iosLaunchOptions(flags, argv) {
+  const appLaunchArgs = repeatedFlagValues(argv, "launch-arg");
+  let appLaunchEnv;
+  if (typeof flags["launch-env"] === "string") {
+    try {
+      const parsed = JSON.parse(flags["launch-env"]);
+      if (!parsed || Array.isArray(parsed) || typeof parsed !== "object" || Object.values(parsed).some((value) => typeof value !== "string")) {
+        throw new Error("expected a JSON object with string values");
+      }
+      appLaunchEnv = parsed;
+    } catch (error) {
+      console.error(`❌ --launch-env must be a JSON object with string values: ${error.message}`);
+      process.exit(2);
+    }
+  }
+  return {
+    ...(appLaunchArgs.length ? { appLaunchArgs } : {}),
+    ...(appLaunchEnv ? { appLaunchEnv } : {}),
+  };
+}
+
 const engineImport = () => import(path.join(packageRoot, "mcp-server", "src", "index.js"));
 
 function requireMacFor(what) {
@@ -197,11 +218,38 @@ async function resolveTargetOrExit(engine, input) {
   return resolved.bundleId;
 }
 
+function safeCommandUsage(verb) {
+  const usage = {
+    explore: "tapp explore [target] [--platform ios|android|web] [--actions N] [--timeout SEC] [--email VALUE] [--password VALUE] [--baseline FILE] [--json FILE]\n  iOS launch configuration: [--launch-arg VALUE ...] [--launch-env '{\"KEY\":\"VALUE\"}']\n  Android: [--app-id ID] [--apk FILE] [--serial ID] [--keep-data]",
+    init: "tapp init [repo] [--explore] [--refresh] [--platform PLATFORM] [--target NAME] [--url URL] [--dry-run]",
+    open: "tapp open [target] [--platform ios|android|web] [--out FILE] [--tap TEXT] [--wait-for TEXT]",
+    tree: "tapp tree [target] [--platform ios|android|web] [--json] [--tap TEXT] [--wait-for TEXT]",
+    shot: "tapp shot [--out FILE]",
+    apps: "tapp apps",
+    build: "tapp build [repo] [--scheme NAME] [--configuration NAME]",
+    flow: "tapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--email VALUE] [--password VALUE]",
+    task: "tapp task validate FILE [--platform PLATFORM] [--map FILE]\ntapp task compile FILE --platform PLATFORM [--inputs JSON] [--out FILE]\ntapp task run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID] [--inputs JSON]",
+    contract: "tapp contract validate FILE [--platform PLATFORM] [--map FILE]\ntapp contract compile FILE --platform PLATFORM [--out FILE]\ntapp contract run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID]",
+    scenario: "tapp scenario validate FILE [--project-dir DIR]\ntapp scenario run FILE --platform web --url URL [--project-dir DIR]",
+    map: "tapp map build MARKERS [--platform PLATFORM] [--out FILE] [--replace]\ntapp map inspect [FILE]\ntapp map diff BEFORE AFTER [--comparable]",
+    pr: "tapp pr plan [--base REF|--changed-files FILE] [--head REF] [--platform PLATFORM] [--out FILE]\ntapp pr gate PLAN [gate target/options]\ntapp pr adopt PLAN --item ID [--project-dir DIR]",
+    plan: "tapp plan show [FILE]\ntapp plan review [FILE] --approve NAME[,NAME] --reject NAME[,NAME] --defer NAME[,NAME]\ntapp plan generate|validate|promote [FILE] [options]",
+    baseline: "tapp baseline create [repo] [--platform PLATFORM] [--target NAME] [--from GATE.json] [--replace]",
+    actor: "tapp actor set NAME --email-env ENV --password-env ENV [--project-dir DIR]\ntapp actor list [repo]",
+    app: "tapp app [repo] [--no-open] [--port PORT]",
+    report: "tapp report [captureId|latest]",
+    doctor: "tapp doctor",
+    install: "tapp install",
+    mcp: "tapp mcp",
+  };
+  return usage[verb] || `tapp ${verb}`;
+}
+
 // Safe help: `--help`/`-h` on ANY verb prints the command reference and does NOTHING else — never
 // builds, launches, writes, or opens (ADR-0005 manual-testing requirement). `ci` keeps its own
 // richer `--help` (a safe usage print in ci-gate.sh); help/version don't need interception.
 if ((rest.includes("--help") || rest.includes("-h")) && !["help", "version", "--version", "-v", "ci"].includes(command)) {
-  console.log(`ℹ️  '${command} --help' — showing the command reference (--help never builds, launches, writes, or opens):\n`);
+  console.log(`Usage:\n  ${safeCommandUsage(command).replaceAll("\n", "\n  ")}\n\nℹ️  --help never builds, launches, writes, or opens. Full command reference:\n`);
   command = "help";
   rest = [];
 }
@@ -271,7 +319,7 @@ switch (command) {
         testEmail: typeof flags.email === "string" ? flags.email : undefined,
         testPassword: typeof flags.password === "string" ? flags.password : undefined,
         runExploration: engine?.runInitExploration,
-        onProgress: (progress) => process.stderr.write(`\r🔍 Import exploration… ${progress.action}/${progress.max || actions} actions · ${progress.states} ${platform === "web" ? "pages" : "screens"} reached   `),
+        onProgress: (progress) => process.stderr.write(`\r🔍 Import exploration… ${progress.action}/${progress.max || actions} actions · ${progress.states} ${platform === "web" ? "pages reached" : platform === "ios" ? "structural states observed" : "screens reached"}   `),
         onStatus: (status) => console.error(`⏳ ${status}`),
         outDir,
         maxContracts,
@@ -408,6 +456,7 @@ switch (command) {
     // hidden deprecated alias.
     if (command === "qa") console.error("note: 'qa' is now 'explore' — 'qa' still works for now.\n");
     const { flags, positionals } = parseVerbArgs(rest);
+    const launchOptions = iosLaunchOptions(flags, rest);
     let target = positionals[0] || "";
     let baselineFindings;
     if (flags.baseline) {
@@ -431,7 +480,7 @@ switch (command) {
         const modelPlatform = typeof flags.platform === "string" ? flags.platform.toLowerCase() : "";
         if (modelPlatform === "ios") requireMacFor("iOS testing");
         const onProgress = (p) =>
-          process.stderr.write(`\r🔍 Exploring… ${p.action}/${p.max || flags.actions || 60} actions · ${p.states} reached   `);
+          process.stderr.write(`\r🔍 Exploring… ${p.action}/${p.max || flags.actions || 60} actions · ${p.states} states observed   `);
         const r = await engine.runExploreTarget({
           projectDir: process.cwd(),
           platform: modelPlatform,
@@ -440,6 +489,7 @@ switch (command) {
           timeout: flags.timeout,
           testEmail: flags.email,
           testPassword: flags.password,
+          ...launchOptions,
           baselineFindings,
           surface: "cli",
           onProgress,
@@ -461,15 +511,19 @@ switch (command) {
       process.exit(2);
     }
     if (platform === "ios") requireMacFor("iOS testing");
+    if (platform !== "ios" && Object.keys(launchOptions).length) {
+      console.error("❌ --launch-arg and --launch-env apply only to iOS targets");
+      process.exit(2);
+    }
     if (platform === "web" && !/^https?:\/\//i.test(target)) {
       console.error("❌ Web QA needs an http(s) URL");
       process.exit(2);
     }
     const bundleId = platform === "ios" ? await resolveTargetOrExit(engine, target) : null;
     const android = platform === "android" ? androidTarget(flags, target) : null;
-    const unit = platform === "web" ? "pages" : "screens";
+    const progressMetric = platform === "web" ? "pages reached" : platform === "ios" ? "structural states observed" : "screens reached";
     const onProgress = (p) =>
-      process.stderr.write(`\r🔍 Exploring… ${p.action}/${p.max || flags.actions || 60} actions · ${p.states} ${unit} reached   `);
+      process.stderr.write(`\r🔍 Exploring… ${p.action}/${p.max || flags.actions || 60} actions · ${p.states} ${progressMetric}   `);
     const r = platform === "web"
       ? await engine.runQaWeb({
           url: target,
@@ -497,7 +551,7 @@ switch (command) {
           bundleId,
           maxActions: flags.actions,
           timeout: flags.timeout,
-          args: { testEmail: flags.email, testPassword: flags.password, baselineFindings },
+          args: { testEmail: flags.email, testPassword: flags.password, baselineFindings, ...launchOptions },
           surface: "cli",
           onProgress,
         });
@@ -555,7 +609,6 @@ switch (command) {
       if (target.apkPath) await driver.install(target.apkPath);
       const snap = await driver.launch({ clearData: flags["clear-data"] === true });
       const data = await driver.screenshot();
-      await driver.forceStop();
       console.log(`🚀 Launched \`${target.appId}\` (Android)\n`);
       console.log(engine.formatScreen(snap.screenTitle, snap.elements));
       const out = typeof flags.out === "string" ? flags.out : path.join(tappHome, "shots", `${target.appId}-${Date.now()}.png`);
@@ -615,12 +668,17 @@ switch (command) {
       break;
     }
     if (platform === "android") {
-      const target = androidTarget(flags, positionals[0] || "");
+      const input = positionals[0] || "";
+      const hasTarget = !!(input || flags["app-id"] || flags.apk);
+      const target = hasTarget
+        ? androidTarget(flags, input)
+        : { serial: typeof flags.serial === "string" ? flags.serial : undefined };
       const { AndroidDriver } = await import(path.join(packageRoot, "mcp-server", "src", "android-driver.js"));
       const driver = new AndroidDriver(target);
       await driver.ensureDevice();
-      const snap = await driver.snapshot();
-      if (flags.json) console.log(JSON.stringify({ screenTitle: snap.screenTitle, elements: snap.elements }, null, 2));
+      if (target.apkPath) await driver.install(target.apkPath);
+      const snap = target.appId ? await driver.launch() : await driver.snapshot();
+      if (flags.json) console.log(JSON.stringify({ platform: "android", appId: target.appId || null, activity: snap.activity, screenTitle: snap.screenTitle, elements: snap.elements }, null, 2));
       else console.log(engine.formatScreen(snap.screenTitle, snap.elements));
       break;
     }

package/mcp-server/src/android-driver.js

@@ -41,6 +41,16 @@ function runFile(command, args, { encoding = "utf8", timeout = 30_000, maxBuffer
   });
 }
 
+export function parseLatestAndroidCrashExitInfo(output) {
+  const blocks = String(output || "").split(/ApplicationExitInfo #\d+:/).slice(1);
+  for (const block of blocks) {
+    const reason = block.match(/\breason=(4|5)\s+\((?:APP CRASH|NATIVE CRASH)/);
+    const identity = block.match(/\btimestamp=([^\n]+?)\s+pid=(\d+)\b/);
+    if (reason && identity) return `${identity[1].trim()}|${identity[2]}|${reason[1]}`;
+  }
+  return null;
+}
+
 function entityDecode(value) {
   return String(value || "")
     .replaceAll(""", '"').replaceAll("'", "'")
@@ -118,8 +128,15 @@ export function detectAndroidScreen(elements, activity = "") {
 
 export function isAndroidAppSnapshot(snapshot, appId) {
   if (!snapshot || !appId) return false;
-  if (String(snapshot.activity || "").startsWith(`${appId}/`)) return true;
-  return snapshot.elements.some((e) => e.package === appId);
+  const activity = String(snapshot.activity || "");
+  const ownsActivity = activity.startsWith(`${appId}/`);
+  const packages = new Set((snapshot.elements || []).map((e) => e.package).filter(Boolean));
+  const ownsElements = packages.has(appId);
+  // dumpXml and dumpsys used to run concurrently. If an app crashed while they were sampled, a
+  // stale activity from the dead app could be paired with another app's UI tree and Tapp would map
+  // that unrelated app as the crash destination. When both signals exist, require agreement.
+  if (activity && packages.size) return ownsActivity && ownsElements;
+  return ownsActivity || ownsElements;
 }
 
 export class AndroidDriver {
@@ -158,6 +175,19 @@ export class AndroidDriver {
     if (this.appId) await this.adb(["shell", "am", "force-stop", this.appId]);
   }
 
+  async isProcessAlive() {
+    if (!this.appId) return false;
+    const r = await this.adb(["shell", "pidof", this.appId]);
+    return r.code === 0 && /\d/.test(String(r.stdout || ""));
+  }
+
+  async latestCrashExitInfo() {
+    if (!this.appId) return null;
+    const r = await this.adb(["shell", "dumpsys", "activity", "exit-info", this.appId]);
+    if (r.code !== 0) return null;
+    return parseLatestAndroidCrashExitInfo(r.stdout);
+  }
+
   async clearData() {
     if (!this.appId) throw new Error("appId is required to clear Android app data");
     const r = await this.adb(["shell", "pm", "clear", this.appId]);

package/mcp-server/src/android-explorer.js

@@ -8,6 +8,8 @@ import { semanticUiKey } from "./ui-map.js";
 
 const ERROR_RE = /\b(something went wrong|internal server error|an error occurred|failed to load|unhandled exception|has stopped)\b/i;
 const DESTRUCTIVE_RE = /\b(delete|remove|purchase|buy now|pay now|reset|erase|unsubscribe|sign out|log out|logout)\b/i;
+const AUTH_SUBMIT_RE = /\b(sign[ -]?in|log[ -]?in|continue|submit)\b/i;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 function stateHash(snap) {
   return snap.elements.map((e) => `${androidElementKey(e)}:${e.text}:${e.x},${e.y}`).join("|");
@@ -40,6 +42,21 @@ function isDestructive(e) {
   return DESTRUCTIVE_RE.test(`${e.label || ""} ${e.text || ""} ${e.description || ""} ${e.id || ""}`.replace(/[_-]+/g, " "));
 }
 
+export function isAndroidAuthSubmit(element) {
+  return AUTH_SUBMIT_RE.test(`${element?.label || ""} ${element?.text || ""} ${element?.description || ""} ${element?.id || ""}`.replace(/[_-]+/g, " "));
+}
+
+export function isAndroidBlankSnapshot(snapshot) {
+  const elements = snapshot?.elements || [];
+  const meaningful = elements.some((element) =>
+    String(element.text || "").trim() ||
+    String(element.description || "").trim() ||
+    (String(element.id || "").trim() && !/^(android:)?id\/content$/i.test(String(element.id || "").trim()))
+  );
+  const interactive = elements.some((element) => element.hittable && (element.clickable || /Button|EditText|Tab|Switch|CheckBox/i.test(element.type)));
+  return !meaningful && !interactive;
+}
+
 export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40, timeoutSec = 300, outDir, testEmail = "", testPassword = "", clearData = true, seedTargets = [], onProgress = () => {}, driver }) {
   const d = driver || new AndroidDriver({ appId, serial });
   d.appId = appId;
@@ -56,7 +73,33 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
   const visited = new Map();
   let issues = 0;
   let actions = 0;
+  const crashExitBaseline = typeof d.latestCrashExitInfo === "function" ? await d.latestCrashExitInfo() : null;
   let snap = await d.launch({ clearData });
+  let crashReported = false;
+
+  const reportProcessExit = async (screen, step) => {
+    if (typeof d.isProcessAlive !== "function") return false;
+    // Android may reveal the launcher before the crashing process disappears from
+    // pidof. A one-shot liveness sample made identical crashes scheduler-dependent.
+    // Poll only after app ownership is already lost: external intents and ordinary
+    // Back boundaries keep the originating process alive and remain boundaries.
+    let alive = await d.isProcessAlive();
+    let latestCrash = typeof d.latestCrashExitInfo === "function" ? await d.latestCrashExitInfo() : null;
+    const exitDeadline = Date.now() + 2_000;
+    while (alive && (!latestCrash || latestCrash === crashExitBaseline) && Date.now() < exitDeadline) {
+      await sleep(150);
+      alive = await d.isProcessAlive();
+      latestCrash = typeof d.latestCrashExitInfo === "function" ? await d.latestCrashExitInfo() : null;
+    }
+    const recordedCrash = !!latestCrash && latestCrash !== crashExitBaseline;
+    if ((alive && !recordedCrash) || crashReported) return false;
+    crashReported = true;
+    emit("ISSUE", { type: "crash", severity: "critical", title: "App process exited during exploration", screen: screen || "Launch", step });
+    issues += 1;
+    return true;
+  };
+
+  if (!isAndroidAppSnapshot(snap, appId)) await reportProcessExit("Launch", 0);
 
   const normalizedTargets = (Array.isArray(seedTargets) ? seedTargets : []).filter((target) =>
     target?.platform === "android" && target?.status === "planned" && target?.navigation?.status === "replayable" &&
@@ -95,7 +138,11 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
       const before = state;
       snap = await d.settle();
       state = await recordState(snap);
-      if (!state) { failure = "The UI Map path left the application foreground"; break; }
+      if (!state) {
+        const crashed = await reportProcessExit(before.screen, actions);
+        failure = crashed ? "The application process exited while replaying the UI Map path" : "The UI Map path left the application foreground";
+        break;
+      }
       emit("TRANSITION", { from: before.screen, to: state.screen, action: selector, changed: before.hash !== state.hash });
       onProgress({ action: actions, max: maxActions, states: visited.size });
     }
@@ -113,7 +160,10 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
     // UIAutomator can still describe the launcher or a system surface after
     // Back/external navigation. Those are exploration boundaries, never nodes
     // in the application-owned UI Map.
-    if (!isAndroidAppSnapshot(snap, appId)) break;
+    if (!isAndroidAppSnapshot(snap, appId)) {
+      await reportProcessExit(visited.size ? [...visited.values()].at(-1) : "Launch", actions);
+      break;
+    }
     const recorded = await recordState(snap);
     if (!recorded) break;
     const { hash, screen, inputs } = recorded;
@@ -124,7 +174,7 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
       emit("ISSUE", { type: "error_surface", severity: "high", title: "Visible error surface", screen, step: actions });
       issues += 1;
     }
-    if (snap.elements.filter((e) => e.hittable).length === 0) {
+    if (isAndroidBlankSnapshot(snap)) {
       emit("ISSUE", { type: "blank_screen", severity: "high", title: "No usable controls or content", screen, step: actions });
       issues += 1;
     }
@@ -154,16 +204,24 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
     });
     if (candidate) {
       const target = controlLabel(candidate);
+      const loginSubmit = inputs.some((input) => input.secure) && isAndroidAuthSubmit(candidate);
       tried.add(`${hash}|tap|${target}`);
       const before = hash;
       const r = await d.tap(target, snap);
       actions += 1;
       snap = await d.settle();
       const after = stateHash(snap);
-      emit("ACTION", { type: "tap", target, reason: "untried_control", step: actions, screen, status: r.status });
-      if (!isAndroidAppSnapshot(snap, appId)) break;
+      emit("ACTION", { type: loginSubmit ? "login_submit" : "tap", target, reason: "untried_control", step: actions, screen, status: r.status });
+      if (!isAndroidAppSnapshot(snap, appId)) {
+        await reportProcessExit(screen, actions);
+        break;
+      }
       emit("TRANSITION", { from: screen, to: snap.screenTitle, action: target, changed: before !== after });
-      if (r.status === "ok" && before === after && candidate.clickable) {
+      const authFailed = loginSubmit && inputDescriptors(snap.elements).some((input) => input.secure);
+      if (r.status === "ok" && authFailed) {
+        emit("ISSUE", { type: "auth_failed", severity: "high", title: "Sign-in attempt remained on the login screen", screen, target, step: actions });
+        issues += 1;
+      } else if (r.status === "ok" && before === after && candidate.clickable) {
         emit("ISSUE", { type: "unresponsive_element", severity: "medium", title: `Control did not respond: ${target}`, screen, target, step: actions });
         issues += 1;
       }
@@ -179,7 +237,10 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
       actions += 1;
       const next = await d.settle();
       emit("ACTION", { type: "back", target: "system back", reason: "state_exhausted", step: actions, screen });
-      if (!isAndroidAppSnapshot(next, appId)) break;
+      if (!isAndroidAppSnapshot(next, appId)) {
+        await reportProcessExit(screen, actions);
+        break;
+      }
       emit("TRANSITION", { from: screen, to: next.screenTitle, action: "back", changed: stateHash(next) !== hash });
       if (stateHash(next) !== hash) { snap = next; continue; }
     }
@@ -187,11 +248,7 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
   }
 
   const timedOut = Date.now() >= deadline;
-  if (timedOut) {
-    emit("ISSUE", { type: "explore_timeout", severity: "medium", title: `Exploration timed out after ${timeoutSec}s`, screen: snap.screenTitle, step: actions });
-    issues += 1;
-  }
-  emit("COMPLETE", { actions, states: visited.size, issues, screens: [...new Set(visited.values())].join(","), outcome: timedOut ? "timeout" : "complete" });
+  emit("COMPLETE", { actions, states: visited.size, issues, screens: [...new Set(visited.values())].join(","), outcome: timedOut ? "timeout" : "complete", timedOut, ...(timedOut ? { timeoutSeconds: timeoutSec } : {}) });
   onProgress({ action: actions, max: maxActions, states: visited.size });
   return { markersPath, outDir, actions, states: visited.size, issues, timedOut, seedTargets: normalizedTargets };
 }

package/mcp-server/src/ci-report.js

@@ -402,7 +402,7 @@ function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan,
   } else if (gate.policy === "gate") {
     lines.push("");
     lines.push("### Baseline — 🟡 not active yet");
-    lines.push("No baseline was supplied, so this run used the blocked/inconclusive fallback. Save this report as a baseline—or run the GitHub Action on the default branch—to activate new-regression gating.");
+    lines.push("No baseline was supplied. This gate still enforces absolute blockers and reviewed suite failures, but it cannot identify new regressions until a baseline is saved.");
   }
   if (prPlan) {
     lines.push("");
@@ -487,7 +487,7 @@ function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan,
 }
 
 const args = parseArgs(process.argv.slice(2));
-const report = buildQaReport(args.markers, { platform: args.platform || "ios" });
+const report = buildQaReport(args.markers, { platform: args.platform || "ios", target: args.label || null });
 if (!report) {
   // Required evidence could not be obtained — this is inconclusive (fails closed), not a gate FAIL
   // and not a usage error. See the outcome model in report.js (GATE_EXIT).
@@ -561,7 +561,7 @@ try {
 const decision = evaluateGate({ report, regression, flows, scenarios, contracts, prPlan, baseline, failOn: args.failOn });
 const gate = {
   ...decision,
-  target: args.targetKey || null,
+  target: args.targetKey || report.target || null,
   revision: gitRevision(args.projectDir),
   checked: report.checkedFor,
   notChecked: report.notChecked,

package/mcp-server/src/html-report.js

@@ -49,7 +49,7 @@ function collectShots(captureDir) {
   }
 }
 
-export function writeHtmlReport(captureDir, { report, label = "" } = {}) {
+export function writeHtmlReport(captureDir, { report, label = "", recordingWarning = "" } = {}) {
   const r = report || buildQaReport(path.join(captureDir, "ocqa-markers.txt"));
   if (!r) return null;
 
@@ -78,7 +78,16 @@ export function writeHtmlReport(captureDir, { report, label = "" } = {}) {
 
   const videoHtml = video
     ? `<h2>Recording — the full exploration</h2>\n<video controls preload="metadata" style="width:100%;border:1px solid #d0d7de;border-radius:8px" src="${esc(video)}"></video>`
-    : "";
+    : recordingWarning
+      ? `<h2>Recording</h2>\n<p class="warning">Unavailable: ${esc(recordingWarning)}. Screenshots were still captured.</p>`
+      : "";
+
+  const scopeList = (items) => (items || []).map((item) => `<li>${esc(item)}</li>`).join("\n");
+  const scopeHtml = `<section class="scope">
+<div><h2>Checked this run</h2><ul>${scopeList(r.checkedFor) || "<li class='dim'>No automated checks completed.</li>"}</ul></div>
+<div><h2>Not checked this run</h2><ul>${scopeList(r.notChecked) || "<li class='dim'>No additional limitations recorded.</li>"}</ul></div>
+${r.conditionsNotReached?.length ? `<div><h2>Conditions not reached</h2><ul>${scopeList(r.conditionsNotReached)}</ul></div>` : ""}
+</section>`;
 
   const html = `<!doctype html>
 <html lang="en">
@@ -90,6 +99,10 @@ export function writeHtmlReport(captureDir, { report, label = "" } = {}) {
   h1 { font-size: 1.6rem; margin-bottom: 0.2rem; }
   .meta { color: #57606a; margin-bottom: 1.2rem; }
   .headline { background: #f6f8fa; border-radius: 8px; padding: 0.9rem 1.1rem; margin: 1rem 0; }
+  .warning { background: #fff8c5; border: 1px solid #d4a72c; border-radius: 8px; padding: 0.75rem 1rem; }
+  .scope { display: grid; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); gap: 0.8rem 1.5rem; }
+  .scope h2 { font-size: 1.05rem; margin-bottom: 0.35rem; }
+  .scope ul { margin-top: 0; padding-left: 1.2rem; }
   .sev { color: #fff; border-radius: 4px; padding: 0.05rem 0.45rem; font-size: 0.78rem; font-weight: 600; margin-right: 0.4rem; }
   ul.findings { padding-left: 1.1rem; } ul.findings li { margin-bottom: 0.6rem; }
   .ai { color: #57606a; font-size: 0.88rem; margin: 0.15rem 0 0 0.2rem; }
@@ -105,6 +118,7 @@ export function writeHtmlReport(captureDir, { report, label = "" } = {}) {
 <div class="meta">${esc(label)} · evidence page (observation, not a release decision)</div>
 ${r.platform === "web" ? `<div class="meta">Deterministic basis: ${r.deterministicFindingCounts?.total || 0} deterministic finding(s); ${r.sampledFindingCounts?.total || 0} sampled probe finding(s) are advisory.</div>` : ""}
 <div class="headline">${esc(r.headline)}</div>
+${scopeHtml}
 <h2>Findings</h2>
 <ul class="findings">
 ${findingsHtml}