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

package/AGENTS.md

@@ -21,6 +21,15 @@ npx -y @aarwitz/tapp explore app.apk --platform android --app-id com.acme.app
 npx -y @aarwitz/tapp flow run .tapp/flows/smoke.yml  # committed, keyless E2E replay
 ```
 
+If repository onboarding detects multiple application targets, target detection is deterministic but
+the choice is the user's. In a human TTY, Tapp displays a numbered selector and continues in the same
+command. A non-interactive CLI prints the exact choices and exits before building. MCP returns
+`reason: "target-selection-required"` with structured `choices[]` (`platform`, `name`, `sourcePath`,
+`selector`, and exact `command`). **Do not pick one yourself.** Present those choices to the user
+with the client's native multiple-choice question UI when available, then rerun using the selected
+`--platform` and `--target`. Plain chat can list the same choices when the client has no question
+widget.
+
 For focused web evidence, `open` and `tree` accept one semantic interaction plus an async content
 wait: `tapp open https://example.com --tap "Not now" --wait-for "Dashboard"`. Tapp waits for the
 page to stabilize before capturing it and warns honestly if the bounded wait ends while it is still

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 —
@@ -1497,6 +1518,8 @@ class ExplorerTests: XCTestCase {
                     if current.isEmpty || current == ph {
                         reportedPersistenceKeys.insert(memKey)
                         let t = "Entered value did not persist: '\(fieldKey)' on \(titleStr)"
+                        issues.append((type: "state_persistence", severity: "medium", title: t,
+                                       desc: "Typed '\(typed)' into this field earlier in the run; after navigating away and returning, the field is empty — entered state was silently lost."))
                         print("OCQA_ISSUE:{\"type\":\"state_persistence\",\"severity\":\"medium\",\"title\":\"\(escapeJSON(t))\",\"screen\":\"\(escapedTitle)\",\"control\":\"\(escapeJSON(fieldKey))\",\"step\":\(actionCount),\"desc\":\"Typed '\(escapeJSON(typed))' into this field earlier in the run; after navigating away and returning, the field is empty — entered state was silently lost.\"}")
                     }
                 }
@@ -1591,14 +1614,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 +1681,13 @@ class ExplorerTests: XCTestCase {
 
             // ---- Blank-screen detection ----
             // Distinguish between "no a11y labels / custom UI" vs genuinely empty.
-            if elements.count < 5 && interactable.count == 0 {
+            // A system Back/Close affordance is navigation chrome, not screen content. Treat a
+            // destination whose only usable control is that chrome as blank too; otherwise an
+            // EmptyView pushed by NavigationStack looks like a healthy one-control screen.
+            let contentInteractables = interactable.filter {
+                !isNavBackButton($0) && !isLikelyGlobalNavigation($0, screenBounds: screenBounds)
+            }
+            if visibleTextInventory.isEmpty && contentInteractables.isEmpty {
                 let blankKey = "blank:\(titleStr)"
                 let blankCount = (actionCounts[blankKey] ?? 0) + 1
                 actionCounts[blankKey] = blankCount
@@ -1690,16 +1719,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 +1750,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 +1789,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 +1804,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 +2080,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) }
@@ -2247,12 +2281,21 @@ class ExplorerTests: XCTestCase {
             // the crash itself goes unreported. app.state is non-throwing even when the app is dead.
             // (Found on a real app: a login submit terminated the app; the run limped on but emitted
             // no crash finding.) Try one relaunch to distinguish a hard crash from a transient exit.
-            if app.state != .runningForeground {
-                print("OCQA_STATE:app_left_foreground step=\(actionCount) state=\(app.state.rawValue)")
+            let stateAfterAction = app.state
+            if stateAfterAction != .runningForeground {
+                print("OCQA_STATE:app_left_foreground step=\(actionCount) state=\(stateAfterAction.rawValue)")
+                let crashKey = "crash:\(titleStr)|\(key)"
+                // A terminated process is already proof of an in-run crash. Relaunching it may
+                // succeed, but that must not erase the user-visible failure that just happened.
+                if stateAfterAction == .notRunning && !reportedIssueKeys.contains(crashKey) {
+                    reportedIssueKeys.insert(crashKey)
+                    issues.append((type: "crash", severity: "critical", title: "App crashed after \(actionType) on \(titleStr)",
+                                   desc: "The app process terminated after \(actionType) '\(targetName)' on '\(titleStr)'."))
+                    print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"\(escapeJSON("App crashed after \(actionType) on \(titleStr)"))\",\"screen\":\"\(escapedTitle)\",\"control\":\"\(escapedTarget)\",\"step\":\(actionCount)}")
+                }
                 app.activate()
                 Thread.sleep(forTimeInterval: 3.0)
                 if app.state != .runningForeground {
-                    let crashKey = "crash:\(titleStr)|\(key)"
                     if !reportedIssueKeys.contains(crashKey) {
                         reportedIssueKeys.insert(crashKey)
                         issues.append((type: "crash", severity: "critical", title: "App crashed after \(actionType) on \(titleStr)",
@@ -2356,16 +2399,28 @@ class ExplorerTests: XCTestCase {
 
             // ---- App left foreground / crash detection ----
             // Check both .exists and .state — external links may cause either to fail
-            let appInForeground = app.state == .runningForeground
+            let stateAfterDelayedChecks = app.state
+            let appInForeground = stateAfterDelayedChecks == .runningForeground
             if !appInForeground || !app.exists {
-                print("OCQA_STATE:app_left_foreground step=\(actionCount) state=\(app.state.rawValue)")
+                print("OCQA_STATE:app_left_foreground step=\(actionCount) state=\(stateAfterDelayedChecks.rawValue)")
+                let crashKey = "crash:\(titleStr)|\(key)"
+                if stateAfterDelayedChecks == .notRunning && !reportedIssueKeys.contains(crashKey) {
+                    reportedIssueKeys.insert(crashKey)
+                    issues.append((type: "crash", severity: "critical",
+                                   title: "App crashed after \(actionType) on \(titleStr)",
+                                   desc: "The app process terminated after: \(actionDesc)"))
+                    print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"\(escapeJSON("App crashed after \(actionType) on \(titleStr)"))\",\"screen\":\"\(escapedTitle)\",\"control\":\"\(escapedTarget)\",\"step\":\(actionCount)}")
+                }
                 app.activate()
                 Thread.sleep(forTimeInterval: 3.0)
                 if app.state != .runningForeground {
-                    issues.append((type: "crash", severity: "critical",
-                                   title: "App not recoverable",
-                                   desc: "App left foreground after: \(actionDesc)"))
-                    print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"App not recoverable\",\"action\":\"\(escapedTarget)\",\"step\":\(actionCount)}")
+                    if !reportedIssueKeys.contains(crashKey) {
+                        reportedIssueKeys.insert(crashKey)
+                        issues.append((type: "crash", severity: "critical",
+                                       title: "App not recoverable",
+                                       desc: "App left foreground after: \(actionDesc)"))
+                        print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"App not recoverable\",\"action\":\"\(escapedTarget)\",\"step\":\(actionCount)}")
+                    }
                     break
                 }
                 print("OCQA_STATE:app_reactivated step=\(actionCount)")
@@ -3679,6 +3734,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/README.md

@@ -80,6 +80,12 @@ npx -y @aarwitz/tapp baseline create . --platform web
 npx -y @aarwitz/tapp ci install .
 ```
 
+On a fresh repository containing multiple apps (for example, iOS plus web), bare
+`tapp init . --explore` does not guess from detection order. A human terminal gets a numbered
+selector; a non-interactive CLI prints exact target-selection commands, while MCP also returns
+structured choices. Neither builds or writes before the choice. After you choose one, the model
+retains every detected target and records the choice as the default for the next bare `tapp explore`.
+
 The baseline command writes only after exploration and every selected deterministic suite pass
 conclusively. It stores `.tapp/baselines/<platform>/<target-id>.json`; the generated workflow
 uses that exact target identity so two apps on the same platform never share a baseline. `ci

package/bin/tapp.js

@@ -28,8 +28,8 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, "..");
 const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
 
-// Redirect all writable output away from the (possibly read-only) package dir.
-// The old environment alias remains a read-only fallback for older integrations.
+// Redirect all writable output away from the (possibly read-only) package dir. TAPP_HOME and
+// ~/.tapp are the only current runtime locations; retired environment/path aliases are ignored.
 const tappHome = (process.env.TAPP_HOME || path.join(os.homedir(), ".tapp")).trim();
 process.env.TAPP_HOME = tappHome;
 // TAPP_HOME is created lazily (just before the switch) so `--help`, `help`, and `version` never
@@ -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) {
@@ -185,6 +206,26 @@ function printEngineError(r) {
   }
 }
 
+async function promptForInitTarget(details) {
+  const choices = Array.isArray(details?.choices) ? details.choices : [];
+  if (!choices.length || !process.stdin.isTTY || !process.stderr.isTTY || process.env.CI) return null;
+  const { createInterface } = await import("node:readline/promises");
+  const terminal = createInterface({ input: process.stdin, output: process.stderr });
+  console.error("\nTapp found multiple application targets. Which one should it explore?");
+  choices.forEach((choice, index) => console.error(`  ${index + 1}) ${choice.platform} · ${choice.name} (${choice.sourcePath})`));
+  try {
+    while (true) {
+      const answer = String(await terminal.question(`Select 1-${choices.length} (or q to cancel): `)).trim();
+      if (/^(?:q|quit|cancel)$/i.test(answer)) return null;
+      const selected = Number(answer);
+      if (Number.isInteger(selected) && selected >= 1 && selected <= choices.length) return choices[selected - 1];
+      console.error(`Enter a number from 1 to ${choices.length}, or q to cancel.`);
+    }
+  } finally {
+    terminal.close();
+  }
+}
+
 // Turn whatever the user gave us (nothing / repo dir / .app / bundle id) into an installed
 // bundle id, narrating build/install progress on stderr.
 async function resolveTargetOrExit(engine, input) {
@@ -197,11 +238,48 @@ 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]",
+    ci: "tapp ci ...\ntapp ci install [repo] [--out FILE] [--manifest FILE] [--dry-run] [--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`);
+// A bare `tapp --help` puts the flag in `command`, not `rest`; normalize it before the
+// per-verb interception so the root help path receives the same no-write guarantee.
+if (["--help", "-h"].includes(command)) {
+  command = "help";
+  rest = [];
+}
+const safeHelpRequested = (rest.includes("--help") || rest.includes("-h"))
+  && !["help", "version", "--version", "-v"].includes(command)
+  && (command !== "ci" || rest[0] === "install");
+if (safeHelpRequested) {
+  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 = [];
 }
@@ -244,7 +322,7 @@ switch (command) {
     }
     const platform = typeof flags.platform === "string" ? flags.platform.toLowerCase()
       : typeof flags.url === "string" ? "web"
-      : typeof flags["app-id"] === "string" || typeof flags.apk === "string" ? "android" : "ios";
+      : typeof flags["app-id"] === "string" || typeof flags.apk === "string" ? "android" : "";
     if (explore && platform === "ios") requireMacFor("iOS init exploration");
     const actions = flags.actions === undefined ? 40 : Number(flags.actions);
     const timeout = flags.timeout === undefined ? 600 : Number(flags.timeout);
@@ -254,31 +332,52 @@ switch (command) {
     }
     const engine = explore ? await engineImport() : null;
     const { initializeProductProject } = await import(path.join(packageRoot, "mcp-server", "src", "product-operations.js"));
+    const initOptions = {
+      projectDir,
+      mode: flags["dry-run"] === true ? "inspect" : explore ? "explore" : flags.refresh === true ? "refresh" : "write",
+      ownedUrl: typeof flags.url === "string" ? flags.url : "",
+      platform: typeof flags.platform === "string" ? flags.platform.toLowerCase() : explore ? platform : "",
+      target: typeof flags.target === "string" ? flags.target : "",
+      bundleId: typeof flags["bundle-id"] === "string" ? flags["bundle-id"] : "",
+      appId: typeof flags["app-id"] === "string" ? flags["app-id"] : "",
+      apkPath: typeof flags.apk === "string" ? path.resolve(flags.apk) : undefined,
+      serial: typeof flags.serial === "string" ? flags.serial : undefined,
+      maxActions: actions,
+      timeout,
+      testEmail: typeof flags.email === "string" ? flags.email : undefined,
+      testPassword: typeof flags.password === "string" ? flags.password : undefined,
+      runExploration: engine?.runInitExploration,
+      onProgress: (progress) => {
+        const activePlatform = progress.platform || platform;
+        process.stderr.write(`\r🔍 Import exploration… ${progress.action}/${progress.max || actions} actions · ${progress.states} ${activePlatform === "web" ? "pages reached" : activePlatform === "ios" ? "structural states observed" : "screens reached"}   `);
+      },
+      onStatus: (status) => console.error(`⏳ ${status}`),
+      outDir,
+      maxContracts,
+    };
     let result;
+    let failure = null;
     try {
-      result = await initializeProductProject({
-        projectDir,
-        mode: flags["dry-run"] === true ? "inspect" : explore ? "explore" : flags.refresh === true ? "refresh" : "write",
-        ownedUrl: typeof flags.url === "string" ? flags.url : "",
-        platform: typeof flags.platform === "string" ? flags.platform.toLowerCase() : explore ? platform : "",
-        target: typeof flags.target === "string" ? flags.target : projectDir,
-        bundleId: typeof flags["bundle-id"] === "string" ? flags["bundle-id"] : "",
-        appId: typeof flags["app-id"] === "string" ? flags["app-id"] : "",
-        apkPath: typeof flags.apk === "string" ? path.resolve(flags.apk) : undefined,
-        serial: typeof flags.serial === "string" ? flags.serial : undefined,
-        maxActions: actions,
-        timeout,
-        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   `),
-        onStatus: (status) => console.error(`⏳ ${status}`),
-        outDir,
-        maxContracts,
-      });
+      result = await initializeProductProject(initOptions);
     } catch (error) {
+      failure = error;
+      const choice = explore && error.details?.reason === "target-selection-required"
+        ? await promptForInitTarget(error.details)
+        : null;
+      if (choice) {
+        if (choice.platform === "ios") requireMacFor("iOS init exploration");
+        console.error(`🎯 Exploring ${choice.platform}:${choice.name} (${choice.sourcePath})`);
+        try {
+          result = await initializeProductProject({ ...initOptions, platform: choice.platform, target: choice.selector });
+          failure = null;
+        } catch (retryError) {
+          failure = retryError;
+        }
+      }
+    }
+    if (failure) {
       if (explore) process.stderr.write("\n");
-      console.error(`❌ Could not initialize repository: ${error.message || String(error)}`);
+      printEngineError({ error: `Could not initialize repository: ${failure.message || String(failure)}`, details: failure.details || {} });
       process.exit(2);
     }
     if (explore) process.stderr.write("\n");
@@ -353,7 +452,10 @@ switch (command) {
           testPassword: typeof flags.password === "string" ? flags.password : undefined,
           startWebTarget: engine.startManagedWebTarget,
           stopWebTarget: engine.stopManagedWebTarget,
-          onProgress: (entry) => { if (entry.text) console.error(`⏳ ${entry.text}`); },
+          // Contract execution is emitted in full on stdout below. Keep build/runtime/replay
+          // status live on stderr, but do not echo the execution transcript there as well — an
+          // interactive terminal merges the streams and would otherwise show every result twice.
+          onProgress: (entry) => { if (entry.text && entry.phase !== "execute") console.error(`⏳ ${entry.text}`); },
         });
       } catch (error) {
         console.error(`❌ Could not validate contract drafts: ${error.message || String(error)}`);
@@ -408,6 +510,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 +534,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 +543,7 @@ switch (command) {
           timeout: flags.timeout,
           testEmail: flags.email,
           testPassword: flags.password,
+          ...launchOptions,
           baselineFindings,
           surface: "cli",
           onProgress,
@@ -461,15 +565,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 +605,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 +663,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 +722,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;
     }
@@ -1111,8 +1223,14 @@ switch (command) {
     }
 
     try {
-      await import("playwright");
-      ok("Web", "Playwright installed");
+      const { chromium } = await import("playwright");
+      let executable = "";
+      try { executable = chromium.executablePath(); } catch { /* report the missing browser below */ }
+      if (executable && fs.existsSync(executable)) {
+        ok("Web", `Playwright + Chromium (${executable})`);
+      } else {
+        console.log("  ⬜ Web — Playwright installed; Chromium browser missing (run: npx playwright install chromium)");
+      }
     } catch {
       console.log("  ⬜ Web — install Playwright in the app workspace: npm install -D playwright && npx playwright install chromium");
     }
@@ -1402,9 +1520,15 @@ switch (command) {
     const runs = roots
       .flatMap((root) => fs.readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => path.join(root, e.name)))
       .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
-    const wanted = rest[0] && rest[0] !== "latest" ? runs.find((r) => path.basename(r) === rest[0]) : runs[0];
+    const hasMarkers = (dir) => fs.existsSync(path.join(dir, "ocqa-markers.txt"));
+    // `latest` (default) resolves to the newest *exploration* capture — the captures directory is
+    // also full of flow-*/scenario-* evidence dirs with no ocqa-markers.txt, and picking the newest
+    // of those made `tapp report` fail even though valid exploration captures existed. An explicitly
+    // named capture is honored as-is so a non-exploration capture still gets a clear "no markers".
+    const explicit = rest[0] && rest[0] !== "latest";
+    const wanted = explicit ? runs.find((r) => path.basename(r) === rest[0]) : runs.find(hasMarkers);
     if (!wanted) {
-      bad("No captures found", rest[0] ? `no capture named "${rest[0]}"` : "run a QA exploration first");
+      bad("No captures found", explicit ? `no capture named "${rest[0]}"` : "run an exploration first (no capture with exploration markers was found)");
       process.exit(1);
     }
     const { writeHtmlReport } = await import(path.join(packageRoot, "mcp-server", "src", "html-report.js"));
@@ -1414,7 +1538,9 @@ switch (command) {
       process.exit(1);
     }
     ok("Evidence report", out);
-    spawnSync("open", [out], { stdio: "ignore" });
+    // Only launch a browser from an interactive terminal — agents, scripts, and tests that invoke
+    // `tapp report` non-interactively get the path without a surprise GUI window.
+    if (process.stdout.isTTY) spawnSync("open", [out], { stdio: "ignore" });
     break;
   }