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

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

@@ -118,8 +118,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 +165,12 @@ 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 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,7 @@ 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;
 
 function stateHash(snap) {
   return snap.elements.map((e) => `${androidElementKey(e)}:${e.text}:${e.x},${e.y}`).join("|");
@@ -40,6 +41,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;
@@ -57,6 +73,18 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
   let issues = 0;
   let actions = 0;
   let snap = await d.launch({ clearData });
+  let crashReported = false;
+
+  const reportProcessExit = async (screen, step) => {
+    const alive = typeof d.isProcessAlive === "function" ? await d.isProcessAlive() : true;
+    if (alive || 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 +123,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 +145,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 +159,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 +189,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 +222,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 +233,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}

package/mcp-server/src/index.js

@@ -984,7 +984,10 @@ async function runExploreStreaming(bundleId, actions, timeout, env, onProgress)
   const before = new Set(listCaptureRuns(80).map((r) => r.id));
   const proc = spawn("bash", cmdArgs, { cwd: repoRoot, env: { ...process.env, ...env } });
   proc.stdout.on("data", () => {});
-  proc.stderr.on("data", () => {});
+  let captureStderr = "";
+  proc.stderr.on("data", (chunk) => {
+    captureStderr = (captureStderr + chunk.toString("utf8")).slice(-8_000);
+  });
   const closed = new Promise((res) => proc.on("close", (code) => res(code ?? 1)));
 
   let captureDir = null;
@@ -1037,7 +1040,18 @@ async function runExploreStreaming(bundleId, actions, timeout, env, onProgress)
   await closed;
   const created = listCaptureRuns(80).find((r) => !before.has(r.id))
     || (captureDir ? { id: path.basename(captureDir), path: captureDir, relativePath: path.relative(repoRoot, captureDir) } : null);
-  return { created, timedOut };
+  return { created, timedOut, captureStderr };
+}
+
+export function recordingUnavailableReason(stderr = "") {
+  const text = String(stderr);
+  if (/resource busy|host recording is already in progress/i.test(text)) {
+    return "the simulator recorder is busy with another host recording";
+  }
+  if (/could not start simulator video recording/i.test(text)) {
+    return "the simulator could not start video recording";
+  }
+  return "the simulator did not produce a recording";
 }
 
 // Grab the booted simulator's current screen and return it downscaled + JPEG-compressed so the
@@ -1318,7 +1332,7 @@ export function qaNextSteps(report, surface = "mcp") {
   return next;
 }
 
-function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiConfigured, reportHtml, recording, uiMap, surface = "mcp" } = {}) {
+function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiConfigured, reportHtml, recording, recordingWarning, uiMap, surface = "mcp" } = {}) {
   const c = report.findingCounts || {};
   const badge = observationBadge(report);
   const sevBits = ["critical", "high", "medium", "low"]
@@ -1338,6 +1352,7 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
   if (uiMap) L.push(`**UI Map** — ${uiMap.nodeCount} states · ${uiMap.edgeCount} transitions · ${uiMap.controlCount} semantic controls · ${uiMap.path}`);
   if (reportHtml) L.push(`**Evidence** — 📄 ${reportHtml} (screenshots of every screen + findings, shareable)`);
   if (recording) L.push(`**Recording** — 🎬 ${recording} (full exploration, embedded in the evidence page)`);
+  else if (recordingWarning) L.push(`**Recording** — ⚠️ unavailable: ${recordingWarning}; screenshots were still captured`);
   L.push(`**Issues** — ${c.total ? `${c.total}${sevBits ? ` (${sevBits})` : ""}` : "none found ✨"}`);
   if (Array.isArray(report.findings) && report.findings.length) {
     L.push("");
@@ -1367,7 +1382,7 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
     L.push("");
     L.push(`> ℹ️ ${inputHint}`);
   }
-  // The honesty label: a "ready" is a claim about exactly these classes, nothing more.
+  // The observation's scope: enumerate exactly what ran and what remains unchecked.
   if (Array.isArray(report.checkedFor) && report.checkedFor.length) {
     L.push("");
     L.push(`> ✅ Checked: ${report.checkedFor.join(" · ")}`);
@@ -1381,11 +1396,10 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
   const next = qaNextSteps(report, surface);
   L.push("");
   L.push(`**Next** — ${next.join(" · ")}`);
-  // The gate hook belongs at the moment the user thinks "I want this on every PR" —
-  // i.e. right after a verdict that found something, or after they hand-diffed a baseline.
+  // The gate hook belongs at the moment the user thinks "I want these checks on every PR".
   if ((report.findings && report.findings.length) || regression) {
     L.push("");
-    L.push("> 🚦 Teams: get this verdict on every PR automatically (evidence + regression gate) — https://github.com/aarwitz/tapp#ci-gate");
+    L.push("> 🚦 Teams: run these checks plus reviewed release contracts as a merge gate on every PR — https://github.com/aarwitz/tapp#ci-gate");
   }
   return L.join("\n");
 }
@@ -1466,7 +1480,7 @@ export async function runQaWeb({ url, maxActions, timeout, testEmail, testPasswo
   } catch (err) {
     return { error: String(err.message || err) };
   }
-  const report = buildQaReport(webResult.markersPath, { platform: "web" });
+  const report = buildQaReport(webResult.markersPath, { platform: "web", target: url.trim() });
   if (!report) return { error: "Web exploration produced no markers", details: { capture: { id, path: outDir } } };
   const backend = remoteAiOptedIn() ? resolveModelBackend() : null;
   if (backend && report.findings.length) {
@@ -1509,7 +1523,7 @@ export async function runQaAndroid({ appId, apkPath, serial, maxActions, timeout
   } catch (error) {
     return { error: error.message || String(error), details: { capture: { id, path: outDir } } };
   }
-  const report = buildQaReport(androidResult.markersPath, { platform: "android" });
+  const report = buildQaReport(androidResult.markersPath, { platform: "android", target: appId.trim() });
   if (!report) return { error: "Android exploration produced no markers", details: { capture: { id, path: outDir } } };
   const backend = remoteAiOptedIn() ? resolveModelBackend() : null;
   if (backend && report.findings.length) {
@@ -1541,10 +1555,10 @@ export async function runQaIos({ bundleId, maxActions, timeout, args = {}, surfa
   const timeoutSec = Math.max(30, Math.min(3600, asInteger(timeout, 600)));
   const env = explorationEnvFromArgs(args);
 
-  const { created, timedOut } = await runExploreStreaming(bundleId, actions, timeoutSec, env, onProgress);
+  const { created, timedOut, captureStderr } = await runExploreStreaming(bundleId, actions, timeoutSec, env, onProgress);
   if (!created) return { error: "Exploration produced no capture run", details: { timedOut } };
 
-  const report = buildQaReport(path.join(created.path, "ocqa-markers.txt"));
+  const report = buildQaReport(path.join(created.path, "ocqa-markers.txt"), { platform: "ios", target: bundleId });
   if (!report) {
     return {
       error: "No markers parsed from exploration (the app may not have launched)",
@@ -1574,13 +1588,14 @@ export async function runQaIos({ bundleId, maxActions, timeout, args = {}, surfa
   // Cross-run regression vs. a caller-supplied baseline (the CI gate).
   const regression = computeRegression(report.findings, args.baselineFindings);
   const uiMap = await writeRunUiMap({ markersPath: path.join(created.path, "ocqa-markers.txt"), platform: "ios", target: bundleId, runId: created.id, outDir: created.path });
+  const recording =
+    ["exploration.webm", "exploration.mov"].map((f) => path.join(created.path, f)).find((p) => fs.existsSync(p)) || null;
+  const recordingWarning = recording ? null : recordingUnavailableReason(captureStderr);
   let reportHtml = null;
   try {
     const { writeHtmlReport } = await import("./html-report.js");
-    reportHtml = writeHtmlReport(created.path, { report, label: bundleId });
+    reportHtml = writeHtmlReport(created.path, { report, label: bundleId, recordingWarning });
   } catch { /* evidence page is best-effort */ }
-  const recording =
-    ["exploration.webm", "exploration.mov"].map((f) => path.join(created.path, f)).find((p) => fs.existsSync(p)) || null;
   const structured = {
     ...report,
     regression,
@@ -1588,11 +1603,12 @@ export async function runQaIos({ bundleId, maxActions, timeout, args = {}, surfa
     inputHint,
     reportHtml,
     recording,
+    recordingWarning,
     capture: { id: created.id, path: created.path, relativePath: created.relativePath },
     timedOut,
     autoBooted: sim.autoBooted || false,
   };
-  const text = formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiConfigured: !!backend, reportHtml, recording, uiMap: uiMap.error ? null : uiMap, surface });
+  const text = formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiConfigured: !!backend, reportHtml, recording, recordingWarning, uiMap: uiMap.error ? null : uiMap, surface });
   return { structured, text };
 }
 
@@ -1753,6 +1769,8 @@ export async function runExploreTarget({
   timeout,
   testEmail,
   testPassword,
+  appLaunchArgs,
+  appLaunchEnv,
   baselineFindings,
   surface = "cli",
   onProgress = () => {},
@@ -1776,6 +1794,10 @@ export async function runExploreTarget({
   catch (error) { return { error: error.message || String(error) }; }
   const selectedPlatform = selected.platform;
 
+  if (selectedPlatform !== "ios" && ((Array.isArray(appLaunchArgs) && appLaunchArgs.length) || (appLaunchEnv && Object.keys(appLaunchEnv).length))) {
+    return { error: "appLaunchArgs/appLaunchEnv apply only to iOS targets." };
+  }
+
   if (selectedPlatform === "web") {
     const ownedUrl = String(selected.runtime?.ownedUrl || "").trim();
     if (/^https?:\/\//i.test(ownedUrl)) {
@@ -1818,7 +1840,7 @@ export async function runExploreTarget({
   const resolved = await resolveAppTarget(root, { cwd: root, onStatus, scheme, configuration });
   if (resolved.error) return resolved;
   if (resolved.via) onStatus(`Target ${resolved.bundleId} — ${resolved.via}`);
-  return runQaIos({ bundleId: resolved.bundleId, maxActions, timeout, args: { testEmail, testPassword, baselineFindings }, surface, onProgress });
+  return runQaIos({ bundleId: resolved.bundleId, maxActions, timeout, args: { testEmail, testPassword, baselineFindings, appLaunchArgs, appLaunchEnv }, surface, onProgress });
 }
 
 function openLocalPort() {
@@ -2949,12 +2971,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // MCP concerns: auth, arg validation, and progress notifications.
     const progressToken = request.params && request.params._meta ? request.params._meta.progressToken : undefined;
     const budget = Math.max(1, Math.min(1000, asInteger(args.maxActions, 60)));
-    const notifyProgress = (unit) => (p) => {
+    const notifyProgress = (metric) => (p) => {
       if (progressToken === undefined) return;
       const total = p.max || budget;
       server.notification({
         method: "notifications/progress",
-        params: { progressToken, progress: p.action || 0, total, message: `🔍 Exploring… ${p.action}/${total} actions · ${p.states} ${unit} reached` },
+        params: { progressToken, progress: p.action || 0, total, message: `🔍 Exploring… ${p.action}/${total} actions · ${p.states} ${metric}` },
       }).catch(() => {});
     };
     if (wantsWeb) {
@@ -2965,7 +2987,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         testEmail: args.testEmail,
         testPassword: args.testPassword,
         baselineFindings: args.baselineFindings,
-        onProgress: notifyProgress("pages"),
+        onProgress: notifyProgress("pages reached"),
       });
       if (r.error) return errorResult(r.error, r.details || {});
       return richResult(r.text, r.structured);
@@ -2982,14 +3004,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         testPassword: args.testPassword,
         baselineFindings: args.baselineFindings,
         clearData: args.clearData !== false,
-        onProgress: notifyProgress("screens"),
+        onProgress: notifyProgress("screens reached"),
       });
       if (r.error) return errorResult(r.error, r.details || {});
       return richResult(r.text, r.structured);
     }
 
     let lastProgress = null;
-    const iosProgress = notifyProgress("screens");
+    const iosProgress = notifyProgress("structural states observed");
     const r = await runQaIos({
       bundleId: String(args.appBundleId).trim(),
       maxActions: args.maxActions,
@@ -3686,7 +3708,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (isNonEmptyString(args.apkPath)) await driver.install(path.resolve(args.apkPath));
         const snap = await driver.launch({ clearData: args.clearData === true });
         const data = await driver.screenshot();
-        await driver.forceStop().catch(() => {});
         return {
           content: [
             { type: "text", text: `🚀 Launched \`${appId}\` (Android)\n\n` + formatScreen(snap.screenTitle, snap.elements) },

package/mcp-server/src/pr-selection.js

@@ -428,16 +428,17 @@ export function adoptPrCoverageProposal({ projectDir, prPlanPath, item, releaseP
   if (!ground || !fs.existsSync(mapPath)) throw new Error("Coverage proposal requires the repository's persistent UI Map");
   const map = JSON.parse(fs.readFileSync(mapPath, "utf8"));
   const node = (map.nodes || []).find((candidate) => candidate.id === ground.id && candidate.status !== "proposed");
-  if (!node) throw new Error(`Coverage proposal UI Map node is stale or missing: ${ground.id}`);
+  const refreshAdvice = "refresh the persistent UI Map with `tapp init --explore --refresh`, rerun `tapp pr gate`, then retry `tapp pr adopt`";
+  if (!node) throw new Error(`Coverage proposal UI Map node is stale or missing: ${ground.id}; ${refreshAdvice}`);
   if (target.navigation?.route && !(node.routes || []).some((route) => route.platform === target.platform && route.path === target.navigation.route && route.replayable === true)) {
-    throw new Error(`Coverage proposal route is stale in the persistent UI Map: ${target.navigation.route}`);
+    throw new Error(`Coverage proposal route is stale in the persistent UI Map: ${target.navigation.route}; ${refreshAdvice}`);
   }
   if (target.navigation?.mode === "ui-map-path") {
     const currentNavigation = replayableUiMapNavigation(map, node.id, target.platform);
     const expectedEdges = (target.navigation.steps || []).map((step) => step.edgeId);
     const currentEdges = (currentNavigation.steps || []).map((step) => step.edgeId);
     if (currentNavigation.status !== "replayable" || JSON.stringify(expectedEdges) !== JSON.stringify(currentEdges)) {
-      throw new Error(`Coverage proposal UI Map path is stale for ${node.name}`);
+      throw new Error(`Coverage proposal UI Map path is stale for ${node.name}; ${refreshAdvice}`);
     }
   }
   const releasePlan = JSON.parse(fs.readFileSync(targetPath, "utf8"));

package/mcp-server/src/report.js

@@ -1,6 +1,6 @@
 // Pure report/gate logic shared by the MCP server (index.js) and the CI gate CLI
-// (ci-report.js). Turns a capture's OCQA markers into the same ship/no-ship report the Tapp
-// app produces, and diffs two runs' findings into the CI regression gate. No shell, no server —
+// (ci-report.js). Turns a capture's OCQA markers into a scoreless exploration observation,
+// and applies explicit policy separately in the CI gate. No shell, no server —
 // keep it dependency-free so the CI path stays importable and testable.
 import fs from "fs";
 import path from "path";
@@ -133,9 +133,9 @@ export function observationSummary(report) {
   return `${report?.screensExplored || 0} screens · ${report?.actionsPerformed || 0} actions · ${n} finding(s) · observation only`;
 }
 
-// Turn a capture's OCQA markers into the same ship/no-ship report Tapp produces:
-// deduped findings + a trustworthy verdict with a coverage floor (mirrors OrchestratorService).
-export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
+// Turn a capture's OCQA markers into a scoreless observation with deduped findings and an
+// explicit coverage floor. Release judgment is applied later by evaluateGate.
+export function buildQaReport(markersFilePath, { platform = "ios", target = null } = {}) {
   const base = parseOcqaMarkers(markersFilePath);
   if (!base) return null;
 
@@ -145,6 +145,7 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
   const inputsByScreen = new Map();
   const screenElementCounts = {}; // screen -> max elements observed (content-collapse detection)
   let anySecure = false;
+  let loginAttempted = false;
   let actions = 0;
 
   for (const line of raw.split(/\r?\n/)) {
@@ -163,6 +164,17 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
       }
     } else if (t.startsWith("OCQA_ACTION:")) {
       actions += 1;
+      try {
+        const action = JSON.parse(t.slice("OCQA_ACTION:".length));
+        if (action?.type === "login" || String(action?.type || "").startsWith("login_")) loginAttempted = true;
+      } catch {
+        /* ignore malformed */
+      }
+    } else if (
+      t === "OCQA_STATE:login_preamble_submitted" ||
+      t === "OCQA_STATE:login_preamble_two_step_submitted"
+    ) {
+      loginAttempted = true;
     } else if (t.startsWith("OCQA_STATE:{")) {
       try {
         const s = JSON.parse(t.slice("OCQA_STATE:".length));
@@ -202,7 +214,12 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
   const missingResources = new Set(normalizedIssues
     .filter((issue) => issue.type === "missing_asset" && issue.target)
     .map((issue) => issue.target));
+  // Older native captures represented the caller's wall-clock budget as a high-severity app
+  // finding. A timeout makes the evidence partial/inconclusive; it does not prove an app
+  // performance defect (the harness has a separate app_hang detector for that).
+  const timeBudgetExhausted = base.complete?.timedOut === true || normalizedIssues.some((issue) => issue.type === "explore_timeout");
   const reportIssues = normalizedIssues.filter((issue) =>
+    issue.type !== "explore_timeout" &&
     !(issue.type === "network_error" && issue.target && missingResources.has(issue.target) && /^Request failed:/i.test(String(issue.title || ""))));
 
   // Dedup by stable signature (type|screen|target) so repeated detections count once —
@@ -226,8 +243,13 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
   findings.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
 
   const screensExplored = screens.size || base.uniqueScreens.length;
-  const actionsPerformed =
-    actions || (base.complete && typeof base.complete === "object" ? base.complete.actions || 0 : 0);
+  // Some native recovery operations are counted by the harness budget but intentionally do not
+  // emit a public action narrative. Preserve the larger authoritative completion count instead of
+  // understating coverage whenever at least one narrated action exists.
+  const actionsPerformed = Math.max(
+    actions,
+    base.complete && typeof base.complete === "object" ? base.complete.actions || 0 : 0,
+  );
   const crit = findings.filter((f) => f.severity === "critical").length;
   const high = findings.filter((f) => f.severity === "high").length;
   const med = findings.filter((f) => f.severity === "medium").length;
@@ -244,9 +266,22 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
   // Coverage floor: exploration is inconclusive if the app wasn't actually exercised. Exploration
   // OBSERVES — it does not render a ship verdict or score (ADR-0005). Judgment (pass/fail/
   // inconclusive) is the gate's job (evaluateGate), computed from these findings + coverage + policy.
-  const inconclusive = screensExplored < 2 || actionsPerformed < 3;
-
-  const headline = inconclusive
+  // A one-page web target can still be swept exhaustively: page errors, requests, links, assets,
+  // placeholder anchors, and visible controls do not require a second route. Native exploration
+  // retains the stronger multi-screen/action floor. A credentialless single-screen login remains
+  // inconclusive so a login wall can never turn into a clean pass.
+  const coverageFloorMet = platform === "web"
+    ? screensExplored >= 1 && actionsPerformed >= 1
+    : screensExplored >= 2 && actionsPerformed >= 3;
+  const credentiallessLoginWall = anySecure && !loginAttempted && screensExplored <= 1;
+  const inconclusive = !coverageFloorMet || credentiallessLoginWall || timeBudgetExhausted;
+  const stopReason = credentiallessLoginWall ? "login-wall-no-credentials"
+    : timeBudgetExhausted ? "time-budget-exhausted"
+    : coverageFloorMet ? "completed" : "coverage-floor-not-met";
+
+  const headline = timeBudgetExhausted
+    ? `Inconclusive — exploration reached its ${base.complete?.timeoutSeconds || "configured"}s time budget after ${actionsPerformed} action(s) across ${screensExplored} screen(s). Findings are partial; this is not an app performance finding. Increase --timeout or request fewer actions.`
+    : inconclusive
     ? `Inconclusive — only ${screensExplored} screen(s) / ${actionsPerformed} action(s) explored. The app may have crashed on launch, be stuck behind a sign-in wall, or otherwise prevent exploration. Absence of issues is NOT a pass.`
     : findings.length === 0
     ? platform === "web"
@@ -254,7 +289,7 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
       : "No issues surfaced in the exercised surfaces. An observation, not a release decision."
     : `${findings.length} issue(s) surfaced for review (${crit} critical, ${high} high, ${med} medium, ${low} low). An observation, not a release decision.`;
 
-  // The verdict's own honesty label: exactly which defect classes this run checked, which
+  // The observation's honesty label: exactly which defect classes this run checked, which
   // it structurally could NOT check, and which conditions never came up — so "checked" is
   // never claimed for a state the run didn't reach. Platform-aware: a web run doesn't
   // inherit iOS keyboard assertions and vice versa.
@@ -300,9 +335,12 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
       "content & reachability regressions require a baseline" ,
     ];
   }
-  // "Failed sign-ins" is only a claim when a sign-in surface was actually encountered.
-  if (anySecure) checkedFor.splice(2, 0, "failed sign-ins");
+  // "Failed sign-ins" is only a claim when credentials were actually submitted. Merely seeing a
+  // password field proves that a login surface was reached, not that authentication was exercised.
+  if (loginAttempted) checkedFor.splice(2, 0, "failed sign-ins");
+  else if (anySecure) notChecked.push("sign-in behavior (login form reached, no test credentials supplied)");
   else conditionsNotReached.push("sign-in (no login form encountered this run)");
+  if (timeBudgetExhausted) notChecked.push("the full requested action budget (run reached its wall-clock timeout)");
 
   return {
     // An ExplorationRun observation: findings + coverage + evidence, NO ship verdict or score
@@ -313,7 +351,7 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
     // ended; coverage/evidence/uiMap/comparison are the structured observation. uiMap and comparison
     // are populated by consumers that build the map / diff a baseline (null in the bare observation).
     runStatus: inconclusive ? "limited" : "completed",
-    stopReason: inconclusive ? "coverage-floor-not-met" : "completed",
+    stopReason,
     headline,
     inconclusive,
     coverage: { screensExplored, actionsPerformed, screens: Array.from(screens) },
@@ -324,6 +362,7 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
     notChecked,
     conditionsNotReached,
     platform,
+    target: typeof target === "string" && target.trim() ? target.trim() : null,
     screensExplored,
     actionsPerformed,
     findingCounts: { critical: crit, high, medium: med, low, total: findings.length },
@@ -453,7 +492,7 @@ export function computeRegression(current, baseline) {
 // the evidence." Exit codes are the CI contract; precedence is fail > inconclusive > pass.
 export const GATE_EXIT = { pass: 0, fail: 1, error: 2, inconclusive: 3 };
 // Bump when the gate's decision semantics change (NOT the npm version). Recorded on every GateRun.
-export const GATE_POLICY_VERSION = "1";
+export const GATE_POLICY_VERSION = "2";
 
 // Pure gate evaluator: frozen evidence + policy → a GateRun decision. Extracted verbatim from the
 // former inline logic in ci-report.js so the `[char]` characterization tests keep passing — the
@@ -484,6 +523,16 @@ export function evaluateGate({ report, regression = null, flows = [], scenarios
     const needsReview = suites.filter((s) => classify(s) === "needs-review");
     if (needsReview.length) inconclusive(`${needsReview.length} ${label}(s) contain assert_ai (model-observed); the deterministic gate cannot decide them — review, or add an explicit probabilistic policy`);
   }
+  // A submitted sign-in that remains on the login surface is an explicit exercised guarantee,
+  // not ordinary pre-existing UI debt. Letting it pass without a baseline would produce the
+  // contradictory public result "failed sign-in detected" + gate PASS. Keep sampled probes out,
+  // but fail every deterministic auth failure under every gate policy (including with a baseline).
+  const authFailures = (report.findings || []).filter((finding) =>
+    finding?.type === "auth_failed" &&
+    finding?.authority !== "model-observed" &&
+    finding?.evaluationTier !== "sampled"
+  );
+  if (authFailures.length) fail(`${authFailures.length} deterministic sign-in attempt(s) failed`);
   // Selected-but-unexecuted work is missing evidence, not an observed violation → inconclusive.
   if (prPlan?.execution?.notRun) inconclusive(`${prPlan.execution.notRun} selected release contract(s) did not run`);
   if (prPlan?.execution?.explorationFailed) inconclusive(`${prPlan.execution.explorationFailed} planned PR exploration target(s) failed or were not reached`);

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

@@ -45,7 +45,7 @@ export function webPlaceholderLinkFindings(links = []) {
   const seen = new Set();
   for (const link of links || []) {
     const rawHref = String(link?.rawHref || "").trim().toLowerCase();
-    const placeholder = rawHref === "#" || /^javascript:(?:void\(0\);?|;?)$/.test(rawHref);
+    const placeholder = rawHref === "" || rawHref === "#" || /^javascript:(?:void\(0\);?|;?)$/.test(rawHref);
     if (!placeholder || link?.handlerHint) continue;
     const label = String(link?.label || "").replace(/\s+/g, " ").trim().slice(0, 100);
     const fingerprint = String(link?.fingerprint || "link").replace(/\s+/g, " ").trim().slice(0, 100) || "link";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.0-rc.1",
+  "version": "0.17.0-rc.2",
   "mcpName": "io.github.aarwitz/tapp",
   "description": "Release contracts, autonomous QA, and evidence-backed CI gates for iOS, Android, and web.",
   "license": "MIT",
@@ -87,7 +87,7 @@
     "mobile"
   ],
   "scripts": {
-    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/action.test.js tests/package-surface.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js",
+    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/android-primitives-protocol.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/action.test.js tests/package-surface.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js",
     "test:browser-journey": "node --test tests/browser-journey.test.js",
     "test:browser-native": "TAPP_RUN_NATIVE_BROWSER=1 node --test tests/browser-native-journey.test.js"
   }

package/scripts/ci-gate.sh

@@ -3,9 +3,11 @@
 #
 # Boots a simulator if needed, installs the app build under test, runs the autonomous exploration
 # harness, replays every committed Flow (deterministic E2E tests), diffs the findings against a
-# stored baseline, writes a GitHub Actions step summary, and exits non-zero when the gate fails
-# (new high/critical findings vs. baseline, or any failed Flow). Wrapped by ../action.yml for
-# GitHub Actions; equally usable from any other CI or locally.
+# stored baseline, writes a GitHub Actions step summary, and exits with the public outcome contract:
+# pass 0, deterministic fail 1, infrastructure/usage error 2, inconclusive evidence 3. Absolute
+# blockers and reviewed Flow/Scenario/Contract failures are enforced even without a baseline;
+# baseline comparisons additionally catch new high/critical regressions. Wrapped by ../action.yml
+# for GitHub Actions; equally usable from any other CI or locally.
 #
 # Usage:
 #   scripts/ci-gate.sh [--platform ios] --app <path/to/App.app> [--bundle-id <com.example.app>]
@@ -35,7 +37,7 @@ set -uo pipefail
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 
 usage() {
-  sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'
+  sed -n '2,/^set -uo pipefail$/p' "$0" | sed '$d; s/^# \{0,1\}//'
 }
 
 PLATFORM="ios" APP_PATH="" BUNDLE_ID="" APK_PATH="" APP_ID="" URL="" WEB_TARGET="" TARGET_KEY="" SERIAL="" ACTIONS=40 TIMEOUT=600 FLOWS="" SCENARIOS="" CONTRACTS="" PROJECT_DIR="" BASELINE="" FAIL_ON="gate" JSON_OUT="" MD_OUT="" DEVICE="iPhone 16 Pro" PR_BASE="" PR_HEAD="HEAD" CHANGED_FILES_FILE="" PR_PLAN_OUT=""
@@ -82,7 +84,6 @@ fi
 TAPP_PROJECT_ARTIFACTS=""
 if [[ -n "$PROJECT_DIR" ]]; then
   [[ -d "$PROJECT_DIR/.tapp" ]] && TAPP_PROJECT_ARTIFACTS="$PROJECT_DIR/.tapp"
-  [[ -z "$TAPP_PROJECT_ARTIFACTS" && -d "$PROJECT_DIR/.autotap" ]] && TAPP_PROJECT_ARTIFACTS="$PROJECT_DIR/.autotap"
 fi
 [[ -z "$FLOWS" && -n "$TAPP_PROJECT_ARTIFACTS" && -d "$TAPP_PROJECT_ARTIFACTS/flows" ]] && FLOWS="$TAPP_PROJECT_ARTIFACTS/flows/*.yml"
 [[ "$PLATFORM" == "web" && -z "$SCENARIOS" && -n "$TAPP_PROJECT_ARTIFACTS" && -d "$TAPP_PROJECT_ARTIFACTS/scenarios" ]] && SCENARIOS="$TAPP_PROJECT_ARTIFACTS/scenarios/*.yml"

package/scripts/platform-gate.js

@@ -37,7 +37,10 @@ for (let i = 2; i < process.argv.length; i += 1) {
   else if (key === "--json-out") args.jsonOut = value;
   else if (key === "--md-out") args.mdOut = value;
   else if (key === "--pr-plan") args.prPlan = value;
-  else throw new Error(`Unknown argument: ${key}`);
+  else {
+    console.error(`Unknown argument: ${key}`);
+    process.exit(2);
+  }
 }
 if (!["web", "android"].includes(args.platform)) throw new Error("--platform must be web|android");
 if (args.platform === "web" && !args.url && !args.projectDir) throw new Error("Web gate requires --url or --project-dir for managed build/start");
@@ -94,7 +97,7 @@ if (args.prPlan) {
 }
 
 let managedRuntime = null;
-let exitCode = 1;
+let exitCode = 2;
 try {
   if (args.platform === "web" && !args.url) {
     const started = await startManagedWebTarget({
@@ -106,7 +109,7 @@ try {
     if (started.error) {
       console.error(`❌ ${started.error}`);
       if (started.details?.remediation) console.error(`   ${started.details.remediation}`);
-      process.exitCode = 1;
+      exitCode = 2;
     } else {
       managedRuntime = started;
       args.url = started.url;
@@ -114,7 +117,7 @@ try {
     }
   }
   if (args.platform === "web" && !args.url) {
-    exitCode = 1;
+    exitCode = 2;
   } else {
     const qa = args.platform === "web"
       ? await runQaWeb({ url: args.url, maxActions: args.actions, timeout: args.timeout, testEmail: process.env.OCQA_TEST_EMAIL, testPassword: process.env.OCQA_TEST_PASSWORD, seedTargets: prExplorationTargets })
@@ -122,7 +125,7 @@ try {
           testEmail: process.env.OCQA_TEST_EMAIL, testPassword: process.env.OCQA_TEST_PASSWORD, seedTargets: prExplorationTargets });
     if (qa.error) {
       console.error(`❌ ${qa.error}`);
-      exitCode = 1;
+      exitCode = 2;
     } else {
       const captureDir = qa.structured.capture.path;
       const markers = path.join(captureDir, "ocqa-markers.txt");
@@ -177,6 +180,9 @@ try {
       exitCode = report.status ?? 1;
     }
   }
+} catch (error) {
+  console.error(`❌ ${error?.message || String(error)}`);
+  exitCode = 2;
 } finally {
   if (managedRuntime) {
     await stopManagedWebTarget(managedRuntime);

package/scripts/quick-capture.sh

@@ -262,58 +262,92 @@ case "$MODE" in
     echo "Running autonomous exploration ($MAX_ACTIONS actions, timeout: ${EXPLORE_TIMEOUT}s, app: $APP_BUNDLE)..."
     ensure_harness_built "$SIM_NAME"
 
-    # Start video recording in background
-    cleanup_stale_recorders "$UDID"
-    RECORD_PID=""
-    if xcrun simctl io "$UDID" recordVideo --codec=h264 "$CAPTURE_DIR/exploration.mov" & then
-      RECORD_PID=$!
-    fi
-    sleep 0.5
-    if ! kill -0 "$RECORD_PID" 2>/dev/null; then
-      echo "WARNING: Could not start simulator video recording. Continuing without video." >&2
-      RECORD_PID=""
+    # XCUITest can block inside `app.launch()` until the outer watchdog when the target dies in its
+    # initializer, producing a misleading timeout after minutes. For an ordinary unconfigured
+    # launch, probe the target directly first and verify that the returned PID survives a short
+    # settle window. (Configured launch args/env skip this probe because simctl would not reproduce
+    # that launch contract.) The harness still performs its own fresh launch for healthy apps.
+    PREFLIGHT_CRASH=0
+    PREFLIGHT_OUTPUT=""
+    if [[ -z "${OCQA_APP_LAUNCH_ARGS_JSON:-}" && -z "${OCQA_APP_LAUNCH_ENV_JSON:-}" ]]; then
+      xcrun simctl terminate "$UDID" "$APP_BUNDLE" >/dev/null 2>&1 || true
+      PREFLIGHT_OUTPUT="$(xcrun simctl launch "$UDID" "$APP_BUNDLE" 2>&1 || true)"
+      PREFLIGHT_PID="$(echo "$PREFLIGHT_OUTPUT" | sed -n 's/.*: \([0-9][0-9]*\)$/\1/p' | tail -1)"
+      if [[ -n "$PREFLIGHT_PID" ]]; then
+        sleep 2
+        if ! kill -0 "$PREFLIGHT_PID" 2>/dev/null; then PREFLIGHT_CRASH=1; fi
+      fi
+      xcrun simctl terminate "$UDID" "$APP_BUNDLE" >/dev/null 2>&1 || true
     fi
 
-    # Run exploration with watchdog timeout to avoid silent hangs.
     local_output_file="$CAPTURE_DIR/harness-output.txt"
-    run_harness_test "testAutonomousExploration" "$SIM_NAME" "$APP_BUNDLE" "$MAX_ACTIONS" "$EXPLORE_TIMEOUT" > "$local_output_file" 2>&1 &
-    HARNESS_PID=$!
-
-    START_TS=$(date +%s)
     TIMED_OUT=0
-    while kill -0 "$HARNESS_PID" 2>/dev/null; do
-      NOW_TS=$(date +%s)
-      ELAPSED=$((NOW_TS - START_TS))
-      if [[ "$ELAPSED" -ge "$EXPLORE_TIMEOUT" ]]; then
-        TIMED_OUT=1
-        kill -TERM "$HARNESS_PID" 2>/dev/null || true
-        sleep 2
-        kill -KILL "$HARNESS_PID" 2>/dev/null || true
-        break
+    RECORD_PID=""
+    if [[ "$PREFLIGHT_CRASH" -eq 1 ]]; then
+      OUTPUT="OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"App crashed during launch preflight\",\"screen\":\"Launch\",\"step\":0}
+OCQA_COMPLETE:{\"actions\":0,\"states\":0,\"issues\":1,\"screens\":\"\",\"outcome\":\"launch_crash\"}"
+      printf '%s\n%s\n' "$PREFLIGHT_OUTPUT" "$OUTPUT" > "$local_output_file"
+      echo "WARNING: Target process exited during launch preflight; recorded a crash instead of waiting for the exploration timeout." >&2
+    else
+
+      # Start video recording in background
+      cleanup_stale_recorders "$UDID"
+      if xcrun simctl io "$UDID" recordVideo --codec=h264 "$CAPTURE_DIR/exploration.mov" & then
+        RECORD_PID=$!
+      fi
+      sleep 0.5
+      if ! kill -0 "$RECORD_PID" 2>/dev/null; then
+        echo "WARNING: Could not start simulator video recording. Continuing without video." >&2
+        RECORD_PID=""
       fi
-      sleep 2
-    done
 
-    wait "$HARNESS_PID" 2>/dev/null || true
-    OUTPUT="$(cat "$local_output_file" 2>/dev/null || true)"
+      # Run exploration with watchdog timeout to avoid silent hangs.
+      run_harness_test "testAutonomousExploration" "$SIM_NAME" "$APP_BUNDLE" "$MAX_ACTIONS" "$EXPLORE_TIMEOUT" > "$local_output_file" 2>&1 &
+      HARNESS_PID=$!
+
+      START_TS=$(date +%s)
+      while kill -0 "$HARNESS_PID" 2>/dev/null; do
+        NOW_TS=$(date +%s)
+        ELAPSED=$((NOW_TS - START_TS))
+        if [[ "$ELAPSED" -ge "$EXPLORE_TIMEOUT" ]]; then
+          TIMED_OUT=1
+          kill -TERM "$HARNESS_PID" 2>/dev/null || true
+          sleep 2
+          kill -KILL "$HARNESS_PID" 2>/dev/null || true
+          break
+        fi
+        sleep 2
+      done
+
+      wait "$HARNESS_PID" 2>/dev/null || true
+      OUTPUT="$(cat "$local_output_file" 2>/dev/null || true)"
 
-    # Stop recording
-    if [[ -n "$RECORD_PID" ]]; then
-      kill -INT "$RECORD_PID" 2>/dev/null || true
-      wait "$RECORD_PID" 2>/dev/null || true
+      # Stop recording
+      if [[ -n "$RECORD_PID" ]]; then
+        kill -INT "$RECORD_PID" 2>/dev/null || true
+        wait "$RECORD_PID" 2>/dev/null || true
+      fi
+      sleep 1
     fi
-    sleep 1
 
     # Parse OCQA_ markers
     echo "$OUTPUT" | grep "^OCQA_" > "$CAPTURE_DIR/ocqa-markers.txt" || true
     if [[ "$TIMED_OUT" -eq 1 ]]; then
-      echo "OCQA_ISSUE:{\"type\":\"explore_timeout\",\"severity\":\"high\",\"title\":\"Exploration timed out\",\"timeoutSeconds\":$EXPLORE_TIMEOUT}" >> "$CAPTURE_DIR/ocqa-markers.txt"
-      echo "OCQA_COMPLETE:{\"actions\":0,\"states\":0,\"issues\":1,\"screens\":\"\",\"timedOut\":true,\"timeoutSeconds\":$EXPLORE_TIMEOUT}" >> "$CAPTURE_DIR/ocqa-markers.txt"
-      echo "WARNING: Exploration hit timeout after ${EXPLORE_TIMEOUT}s" >&2
+      # The caller's wall-clock budget expiring means the evidence is partial; it is not proof that
+      # the app itself is slow or hung. Preserve observed coverage in the terminal marker and let
+      # report.js classify the run as inconclusive instead of inventing an app finding.
+      TIMED_ACTIONS="$(echo "$OUTPUT" | sed -n 's/^OCQA_PROGRESS:{"action":\([0-9][0-9]*\).*/\1/p' | tail -1)"
+      TIMED_STATES="$(echo "$OUTPUT" | sed -n 's/^OCQA_PROGRESS:.*"states":\([0-9][0-9]*\).*/\1/p' | tail -1)"
+      TIMED_ISSUES="$(echo "$OUTPUT" | grep -c '^OCQA_ISSUE:' || true)"
+      TIMED_ACTIONS="${TIMED_ACTIONS:-0}"
+      TIMED_STATES="${TIMED_STATES:-0}"
+      TIMED_ISSUES="${TIMED_ISSUES:-0}"
+      echo "OCQA_COMPLETE:{\"actions\":$TIMED_ACTIONS,\"states\":$TIMED_STATES,\"issues\":$TIMED_ISSUES,\"screens\":\"\",\"timedOut\":true,\"timeoutSeconds\":$EXPLORE_TIMEOUT}" >> "$CAPTURE_DIR/ocqa-markers.txt"
+      echo "WARNING: Exploration reached its ${EXPLORE_TIMEOUT}s time budget; evidence is partial" >&2
     fi
     echo "$OUTPUT" > "$CAPTURE_DIR/full-output.txt"
 
-    COMPLETE_LINE=$(echo "$OUTPUT" | grep "OCQA_COMPLETE" | tail -1)
+    COMPLETE_LINE=$(grep "OCQA_COMPLETE" "$CAPTURE_DIR/ocqa-markers.txt" | tail -1 || true)
     if [[ -n "$COMPLETE_LINE" ]]; then
       echo ""
       echo "Exploration complete: $COMPLETE_LINE"