@aarwitz/tapp 0.17.17 → 0.17.19

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tapp",
   "description": "Give Claude hands and eyes on iOS, Android, and web apps, with exploration, replayable flows, evidence, and deterministic CI gates.",
-  "version": "0.17.17",
+  "version": "0.17.19",
   "author": {
     "name": "Aaron Horowitz",
     "url": "https://github.com/aarwitz"
@@ -24,7 +24,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@aarwitz/tapp@0.17.17",
+        "@aarwitz/tapp@0.17.19",
         "mcp"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}"

package/AGENTS.md

@@ -24,6 +24,11 @@ npx -y @aarwitz/tapp@latest explore app.apk --platform android --app-id com.acme
 npx -y @aarwitz/tapp@latest flow run .tapp/flows/smoke.yml  # committed, keyless E2E replay
 ```
 
+On iOS, `tree` only uses an installed app: it never builds, uninstalls, or replaces it. With
+no target it uses the repository's recorded iOS target or the sole installed app; ambiguity
+requires a choice. Pass a bundle id to inspect a particular sandbox build. To replace a build,
+run `tapp build` explicitly first.
+
 If repository onboarding detects multiple application targets, target detection is deterministic but
 the choice is the user's. Explicit `init --explore` asks even when the model has a saved default; a
 later bare `explore` may consume that default. In a human TTY, Tapp displays a numbered selector and

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -377,6 +377,7 @@ class ExplorerTests: XCTestCase {
             let action = (cmd["action"] as? String ?? "").lowercased()
             var status = "ok"
             var loginDetail = ""
+            noteNavigationTitle() // navigation history, so `back` can recognise its control
 
             switch action {
             case "login":
@@ -429,7 +430,7 @@ class ExplorerTests: XCTestCase {
                 }
             case "back":
                 status = sessionBack()
-                if status == "no_effect" { loginDetail = "the screen did not change — there may be no back destination here, or the Back control belongs to a different navigation stack (try tap {id: \"Back\"})" }
+                if status == "no_effect" { loginDetail = "no back control on this screen, or tapping it did not change the screen — this is a root screen, or its Back belongs to a different navigation stack (try tap {id: \"Back\"}, or `swipe` for a gesture)" }
             case "wait":
                 let target = (cmd["id"] as? String).flatMap { $0.isEmpty ? nil : $0 } ?? (cmd["text"] as? String ?? "")
                 let waitMs = (cmd["timeoutMs"] as? Int) ?? 5000
@@ -484,6 +485,8 @@ class ExplorerTests: XCTestCase {
         return false
     }
 
+    private var backTitleHistory: [String] = []
+
     private func sessionTapById(_ identifier: String) -> String {
         var existedButNotHittable = false
         var existedButDisabled = false
@@ -799,6 +802,17 @@ class ExplorerTests: XCTestCase {
         return nil
     }
 
+    /// iOS labels a pushed screen's back button with the PARENT screen's title ("Todo List"),
+    /// not "Back", so a back control cannot be recognised by its own label alone. Remember the
+    /// titles we have actually been on; a leading navigation-bar button named after one of them
+    /// is a genuine back control, while a custom leading action (Share, Delete) is not.
+    private func noteNavigationTitle() {
+        let title = app.navigationBars.firstMatch.identifier
+        guard !title.isEmpty, backTitleHistory.last != title else { return }
+        backTitleHistory.append(title)
+        if backTitleHistory.count > 20 { backTitleHistory.removeFirst() }
+    }
+
     /// Leave a system-owned surface. A share sheet is a presented sheet, not a pushed screen:
     /// `back` does nothing and a mid-screen swipe scrolls its content instead of dismissing it.
     /// Try its real affordances in order, and say honestly whether we actually got out.
@@ -855,24 +869,74 @@ class ExplorerTests: XCTestCase {
         let beforeTitle = detectTitle(beforeElements) ?? "Unknown"
         let beforeHash = computeHash(beforeElements)
 
-        // A NavigationStack inside a sheet has its own navigation bar; `navigationBars.firstMatch`
-        // can resolve the wrong one, so prefer an explicitly labelled, hittable Back control.
-        let labelled = app.buttons.matching(NSPredicate(format: "label ==[c] %@", "Back")).allElementsBoundByIndex
-        if let back = labelled.first(where: { $0.exists && $0.isHittable }) {
-            back.tap()
-        } else {
-            let backButton = app.navigationBars.buttons.firstMatch
-            if backButton.exists && backButton.isHittable {
-                backButton.tap()
-            } else {
-                app.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0.5))
-                    .press(forDuration: 0.05, thenDragTo: app.coordinate(withNormalizedOffset: CGVector(dx: 0.8, dy: 0.5)))
-            }
-        }
+        // ONLY a real back affordance counts. Tapping `navigationBars.buttons.firstMatch` meant
+        // that on a screen with no back button, `back` fired whatever toolbar action happened to
+        // come first — observed live: it tapped Share, opened the share sheet, saw the screen
+        // change and reported "ok". A back that performs an unrelated (possibly destructive)
+        // action is worse than one that does nothing.
+        let isBackAffordance = NSPredicate(format:
+            "label ==[c] 'Back' OR label BEGINSWITH[c] 'Back to' OR identifier ==[c] 'BackButton' OR identifier CONTAINS[c] 'back-button'")
+        var backControls = app.buttons.matching(isBackAffordance).allElementsBoundByIndex
+        if backControls.first(where: { $0.exists && $0.isHittable }) == nil {
+            // The standard iOS back button: the navigation bar's leading control, labelled with
+            // a screen we have already been on. A leading button named anything else (Share,
+            // Delete) is an app action, not a back, and must never be tapped by `back`.
+            // The navigation bar's leading control. Recognising it cannot depend on the nav-bar
+            // identifier being readable (that varies by iOS version), so accept three shapes of
+            // the standard back button — named after a screen we have been on, named after the
+            // current screen (a detail view that inherits its parent's title), or a bare chevron
+            // with no label — while never accepting a named app action.
+            let appActionLabels: Set<String> = ["share", "delete", "remove", "add", "edit", "save",
+                                                "done", "cancel", "close", "more", "sign out",
+                                                "log out", "settings", "search", "filter", "menu"]
+            let leading = app.navigationBars.buttons.allElementsBoundByIndex.first
+            if let leading, leading.exists, leading.isHittable,
+               !appActionLabels.contains(leading.label.lowercased()),
+               backTitleHistory.contains(leading.label) || leading.label == beforeTitle || leading.label.isEmpty {
+                backControls = [leading]
+            }
+        }
+        guard let back = backControls.first(where: { $0.exists && $0.isHittable }) else {
+            // No back affordance: say so, and do nothing. The edge-swipe fallback used to run
+            // here and it was not a back — on a screen whose content scrolls sideways the drag
+            // landed in the content and navigated FORWARD ("Dashboard" → "What's New"), which
+            // `back` then reported as a successful pop. A caller who wants the gesture can ask
+            // for it explicitly with `swipe`.
+            print("OCQA_STATE:back_check before=\(beforeTitle) control=none")
+            return "no_effect"
+        }
+        let backLabel = back.label
+        // The CONTROLS on screen are the evidence a pop happened. Re-reading the tapped element
+        // does not work: XCUIElement is a lazy query, so `back.exists` after the tap re-resolves
+        // "the navigation bar's first button" against the NEW screen and finds whatever leads it
+        // there — so a successful pop looked like the control was still present. Titles do not
+        // work either: a detail view that inherits its parent's title reads the same on both
+        // sides. A pop replaces the screen's controls, and that is what we compare.
+        let controlLabels = { (elements: [SimpleElement]) -> Set<String> in
+            Set(elements.filter { self.isInteractable($0.type) && $0.isEnabled }
+                .map { self.normalizeVisibleText($0.label) }
+                .filter { !$0.isEmpty })
+        }
+        let beforeControls = controlLabels(beforeElements)
+        back.tap()
         waitForUIStability(timeout: 1.5)
         let afterElements = readUITree(app)
         let afterTitle = detectTitle(afterElements) ?? "Unknown"
-        if afterTitle != beforeTitle || computeHash(afterElements) != beforeHash { return "ok" }
+        let afterControls = controlLabels(afterElements)
+        // Two or more controls differing is a screen change; one is ordinary content churn.
+        let changedControls = beforeControls.symmetricDifference(afterControls).count
+        print("OCQA_STATE:back_check before=\(beforeTitle) after=\(afterTitle) control=\(backLabel) changedControls=\(changedControls)")
+        if changedControls >= 2 { return "ok" }
+        // Navigation is a change of SCREEN, and the screen's identity is its title. A raw tree
+        // hash is too sensitive to be evidence of it: a dashboard with delayed content or a
+        // relative timestamp changes hash on its own, which made a no-op back at a root screen
+        // look like a successful pop (observed on the corpus app). Fall back to the hash only
+        // when neither read produced a title to compare.
+        // Observability: a back that reports the wrong thing is invisible without this.
+        if afterTitle != beforeTitle { return "ok" }
+        if beforeTitle == "Unknown" && afterTitle == "Unknown" {
+            return computeHash(afterElements) != beforeHash ? "ok" : "no_effect"
+        }
         return "no_effect"
     }
 
@@ -930,6 +994,9 @@ class ExplorerTests: XCTestCase {
         // Per-flow wait default (field issue #20): a splash that prefetches for ~8s makes the
         // fixed 6s wait_for fail on a healthy app. Steps may still override individually.
         let flowDefaultTimeoutMs = (flow["timeoutMs"] as? Int) ?? (flow["timeout"] as? Int) ?? 6000
+        // XCTest runs teardown blocks even when a step aborts unexpectedly. Keep the final
+        // visible frame inspectable for both successful and failing replays (public issue #26).
+        addTeardownBlock { [self] in recordFlowScreenshot(name: "flow-final") }
 
         // Variable substitution: $TEST_EMAIL/$TEST_PASSWORD from creds, plus any OCQA_FLOW_VARS.
         var vars: [String: String] = ["TEST_EMAIL": resolve("OCQA_TEST_EMAIL", fallback: "test@example.com"),
@@ -964,6 +1031,7 @@ class ExplorerTests: XCTestCase {
             let taskName = (raw["__tappTask"] as? [String: Any])?["name"] as? String ?? ""
             // A step is either {action: value} sugar or {action:..., target/value/...}. Normalize.
             let (action, step) = normalizeFlowStep(raw)
+            noteNavigationTitle() // navigation history, so `back` can recognise its control
             let target = subst((step["target"] as? String) ?? "")
             let value = subst((step["value"] as? String) ?? "")
             let timeoutMs = (step["timeoutMs"] as? Int) ?? (step["timeout"] as? Int) ?? flowDefaultTimeoutMs
@@ -1004,7 +1072,11 @@ class ExplorerTests: XCTestCase {
             case "swipe":
                 switch target.lowercased() { case "down": app.swipeDown(); case "left": app.swipeLeft(); case "right": app.swipeRight(); default: app.swipeUp() }
             case "back":
-                _ = tryGoBack()
+                // Same rule as the session (#10): a back that did not navigate is a failed step,
+                // not a silent pass — the rest of the Flow would otherwise run against the wrong
+                // screen and fail somewhere unrelated.
+                status = sessionBack() == "ok" ? "pass" : "fail"
+                if status == "fail" { detail = "back did not navigate: no back control on this screen, or tapping it did not change the screen\(visibleLabelsHint())" }
             case "wait":
                 Thread.sleep(forTimeInterval: Double(timeoutMs) / 1000.0)
             case "wait_for":
@@ -1052,17 +1124,7 @@ class ExplorerTests: XCTestCase {
                 // Web and Android flows write flow-failure-N.png next to the log; iOS buried the
                 // evidence in the .xcresult, so seeing the failing screen needed a second run
                 // (field issue #8). Write the same file, and keep the XCTest attachment too.
-                let failureShot = app.screenshot()
-                let failureAttachment = XCTAttachment(screenshot: failureShot)
-                failureAttachment.name = "flow_failure_\(idx)"
-                failureAttachment.lifetime = .keepAlways
-                add(failureAttachment)
-                let evidenceDir = resolve("OCQA_FLOW_EVIDENCE_DIR")
-                if !evidenceDir.isEmpty {
-                    let destination = URL(fileURLWithPath: evidenceDir).appendingPathComponent("flow-failure-\(idx).png")
-                    try? FileManager.default.createDirectory(at: URL(fileURLWithPath: evidenceDir), withIntermediateDirectories: true)
-                    try? failureShot.pngRepresentation.write(to: destination)
-                }
+                recordFlowScreenshot(name: "flow-failure-\(idx)")
                 // A failed step surfaces as a finding, with the same shape QA findings use.
                 let screen = detectTitle(readUITree(app)) ?? "Unknown"
                 print("OCQA_ISSUE:{\"type\":\"flow_assertion_failed\",\"severity\":\"high\",\"title\":\"\(escapeJSON("Step \(idx) (\(action)) failed: \(detail)"))\",\"screen\":\"\(escapeJSON(screen))\",\"step\":\(idx)}")
@@ -1072,13 +1134,29 @@ class ExplorerTests: XCTestCase {
             waitForAnimationsToSettle()
         }
 
-        let shot = app.screenshot()
-        let att = XCTAttachment(screenshot: shot); att.name = "flow_final"; att.lifetime = .keepAlways; add(att)
         let contractResult = contractName.isEmpty ? "" : ",\"contract\":\"\(escapeJSON(contractName))\",\"criticality\":\"\(escapeJSON(contractCriticality))\""
         print("OCQA_FLOW_RESULT:{\"passed\":\(failed == 0),\"name\":\"\(escapeJSON(flow["name"] as? String ?? "flow"))\",\"kind\":\"\(escapeJSON(evidenceKind))\"\(contractResult),\"total\":\(steps.count),\"executed\":\(executed),\"failed\":\(failed)}")
         if failed > 0 { XCTFail("Flow had \(failed) failed step(s)") }
     }
 
+    private func recordFlowScreenshot(name: String) {
+        // Screen capture also works after an app crash and includes system sheets covering it.
+        let shot = XCUIScreen.main.screenshot()
+        let attachment = XCTAttachment(screenshot: shot)
+        attachment.name = name.replacingOccurrences(of: "-", with: "_")
+        attachment.lifetime = .keepAlways
+        add(attachment)
+        let evidenceDir = resolve("OCQA_FLOW_EVIDENCE_DIR")
+        guard !evidenceDir.isEmpty else { return }
+        do {
+            let directory = URL(fileURLWithPath: evidenceDir)
+            try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+            try shot.pngRepresentation.write(to: directory.appendingPathComponent("\(name).png"), options: .atomic)
+        } catch {
+            print("OCQA_EVIDENCE_WARNING:Could not write \(name).png: \(error.localizedDescription); screenshot retained in result.xcresult")
+        }
+    }
+
     /// Accepts both sugar (`{ tap: "Sign In" }`) and explicit (`{ action: "tap", target: "Sign In" }`).
     private func normalizeFlowStep(_ raw: [String: Any]) -> (String, [String: Any]) {
         if let action = raw["action"] as? String { return (action.lowercased(), raw) }
@@ -1500,9 +1578,20 @@ class ExplorerTests: XCTestCase {
             return
         }
 
-        // Trigger the interruption monitor on any pending system alerts
-        app.tap()
-        Thread.sleep(forTimeInterval: 0.3)
+        // Dismiss an observed system alert directly. A blind app.tap() here used to press
+        // whichever app control occupied the center BEFORE the first screen was recorded,
+        // so the explorer could then flag its own second tap as unresponsive (issue #27).
+        let startupAlert = XCUIApplication(bundleIdentifier: "com.apple.springboard").alerts.firstMatch
+        if startupAlert.exists {
+            for label in ["Allow While Using App", "Allow Once", "OK", "Allow", "Don't Allow"] {
+                let button = startupAlert.buttons[label]
+                if button.exists && button.isHittable {
+                    button.tap()
+                    waitForAnimationsToSettle()
+                    break
+                }
+            }
+        }
 
         // Record the TRUE initial screen (e.g. a "Get Started" welcome sheet) before
         // navigateToRootScreen() below auto-dismisses it. Without this, grounding (AI-generate,
@@ -2608,7 +2697,8 @@ class ExplorerTests: XCTestCase {
                 dismissKeyboardIfNeeded()
             }
 
-            let preContentSig = contentSignature(elements)
+            // Compare with the screen immediately before the action, after keyboard dismissal.
+            let preContentSig = contentSignature(readUITree(app))
             let actionDesc = performSmartAction(
                 on: target,
                 in: app,
@@ -2729,8 +2819,8 @@ class ExplorerTests: XCTestCase {
                 // value change) is likely a dead control — exactly the "clicking a button does
                 // nothing" case. We compare a content signature (labels + values) so controls that
                 // only change a value (counters, toggles) are never falsely flagged, exclude
-                // selection/value controls, and require a second confirming read to rule out a
-                // merely-delayed update. NATIVE buttons only (rawValue:9): web buttons/links live
+                // selection/value controls, and observe unchanged controls for a bounded window
+                // to allow asynchronous updates. NATIVE buttons only (rawValue:9): web buttons/links live
                 // inside a WKWebView, whose dynamic DOM changes aren't reliably reflected in the
                 // accessibility tree, so we can't measure their responsiveness this way.
                 let isButton = target.type.contains("rawValue: 9")
@@ -2747,12 +2837,11 @@ class ExplorerTests: XCTestCase {
                     && !isInsideSelectionContainer(target)
                     && !isSystemHandoffControl(humanLabel)
                     && app.state == .runningForeground && !reportedIssueKeys.contains(noOpKey) {
-                    let post1 = readUITree(app)
-                    if !post1.isEmpty, contentSignature(post1) == preContentSig {
-                        // Confirm it's genuinely inert, not just a delayed update.
-                        Thread.sleep(forTimeInterval: 0.6)
-                        let post2 = readUITree(app)
-                        if app.state == .runningForeground, !post2.isEmpty, contentSignature(post2) == preContentSig {
+                    let remaining = timeoutSeconds - (Date().timeIntervalSince(startTime) - totalWaitSeconds)
+                    // A shortened observation is inconclusive, never evidence of a dead control.
+                    if remaining >= 8.0 {
+                        let response = observeControlResponse(previousContent: preContentSig)
+                        if response == .unchanged {
                             reportedIssueKeys.insert(noOpKey)
                             // A dead NAVIGATION control (Back/Close/Done/Cancel) is worse than a dead
                             // feature button: it strands the user on the screen (and strands this
@@ -2763,7 +2852,7 @@ class ExplorerTests: XCTestCase {
                             let issueTitle = isNavControl
                                 ? "Navigation control does nothing: '\(humanLabel)' — users may be stuck on this screen"
                                 : "Control may be unresponsive: '\(humanLabel)'"
-                            let issueDesc = "Tapping '\(humanLabel)' on '\(titleStr)' produced no visible change (no navigation, content, or state change)."
+                            let issueDesc = "Tapping '\(humanLabel)' on '\(titleStr)' produced no observable navigation, content, selection, or enabled-state change within 8 seconds."
                             issues.append((type: "unresponsive_element", severity: sev, title: issueTitle, desc: issueDesc))
                             print("OCQA_ISSUE:{\"type\":\"unresponsive_element\",\"severity\":\"\(sev)\",\"title\":\"\(escapeJSON(issueTitle))\",\"screen\":\"\(escapedTitle)\",\"control\":\"\(escapeJSON(humanLabel))\",\"step\":\(actionCount)}")
                         }
@@ -3257,7 +3346,28 @@ class ExplorerTests: XCTestCase {
     /// text). Used to tell a genuinely dead button ("nothing happened") from one that only changed
     /// a value.
     private func contentSignature(_ elements: [SimpleElement]) -> String {
-        elements.map { "\($0.type)|\($0.identifier)|\($0.label)|\($0.value)" }.sorted().joined(separator: "~")
+        elements.map { "\($0.type)|\($0.identifier)|\($0.label)|\($0.value)|\($0.isSelected)|\($0.isEnabled)" }.sorted().joined(separator: "~")
+    }
+
+    private enum ControlResponse { case changed, unchanged, unobserved }
+
+    /// Stable element counts only establish that animations settled; they say nothing about a
+    /// pending network response. Exit immediately on a semantic change, but require the full
+    /// observation window before reporting a no-op. Missing trees and ongoing loading cannot
+    /// establish that a control is inert.
+    private func observeControlResponse(previousContent: String, timeout: TimeInterval = 8.0) -> ControlResponse {
+        guard !previousContent.isEmpty else { return .unobserved }
+        let deadline = Date().addingTimeInterval(timeout)
+        while true {
+            guard app.state == .runningForeground else { return .unobserved }
+            let current = readUITree(app)
+            guard !current.isEmpty else { return .unobserved }
+            if contentSignature(current) != previousContent { return .changed }
+            if Date() >= deadline {
+                return hasIndeterminateLoadingIndicator() ? .unobserved : .unchanged
+            }
+            Thread.sleep(forTimeInterval: min(0.25, max(0, deadline.timeIntervalSinceNow)))
+        }
     }
 
     /// Machine identifiers sometimes leak into a11y titles — mangled runtime type names

package/README.md

@@ -163,8 +163,8 @@ configuration and existing-file collisions, and never commits, pushes, enables b
 or creates GitHub resources. Review and pin the generated Tapp release reference to its immutable
 commit SHA before production.
 
-Every verb takes whatever you have: nothing (auto-detects the repo you're in, or the app
-already on the simulator), a repo directory, a `path/to/App.app`, or a bundle id:
+`open` and `explore` accept a repo directory, a `path/to/App.app`, a bundle id, or no target
+(auto-detecting the repository or installed app):
 
 ```bash
 npx -y @aarwitz/tapp@latest open [target]   # launch the app → screen summary + screenshot file
@@ -174,6 +174,14 @@ npx -y @aarwitz/tapp@latest apps            # what's installed on the simulator
 npx -y @aarwitz/tapp@latest build [dir]     # just build + install (scheme auto-detected)
 ```
 
+On iOS, `tree` inspects an installed app and never builds, uninstalls, or replaces it. With no
+target, it uses the repository's recorded iOS target or the sole installed app. If the choice
+is ambiguous, it lists the installed apps for you to select. Pass a bundle id to inspect a
+specific sandbox build; run `tapp build` explicitly when you intend to replace it.
+
+iOS Flow evidence includes `flow-final.png` on passing and failing replays, plus
+`flow-failure-N.png` at a failed step, alongside the log, JSON report, and XCTest result bundle.
+
 Web: `npx -y @aarwitz/tapp@latest explore http://localhost:3000` *(one-time setup:
 `npm i -g playwright && npx playwright install chromium`)*. Add `--watch` to open Tapp's controlled,
 isolated Chromium window and follow its clicks with an on-page pointer/action label. Tapp hides that

package/bin/tapp.js

@@ -222,7 +222,7 @@ function printEngineError(r) {
     console.error("  Available targets:");
     for (const choice of choices) {
       const selector = choice.name || choice.id || choice.sourcePath;
-      console.error(`    ${choice.platform ? `${choice.platform} · ` : ""}${choice.name || choice.id}${choice.sourcePath ? ` (${choice.sourcePath})` : ""}${selector ? ` — use --target ${JSON.stringify(selector)}` : ""}`);
+      console.error(`    ${choice.platform ? `${choice.platform} · ` : ""}${choice.name || choice.id}${choice.sourcePath ? ` (${choice.sourcePath})` : ""}${choice.command ? ` — ${choice.command}` : selector ? ` — use --target ${JSON.stringify(selector)}` : ""}`);
     }
   }
   if (r.details?.remediation) console.error(`  Next: ${r.details.remediation}`);
@@ -250,8 +250,28 @@ async function promptForInitTarget(details) {
 
 // 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) {
-  const resolved = await engine.resolveAppTarget(input || "", { onStatus: (s) => console.error(`⏳ ${s}`) });
+async function resolveTargetOrExit(engine, input, { inspect = false } = {}) {
+  let resolved = inspect
+    ? await engine.resolveInstalledAppTarget(input || "")
+    : await engine.resolveAppTarget(input || "", { onStatus: (s) => console.error(`⏳ ${s}`) });
+  if (inspect && resolved.details?.choices?.length && process.stdin.isTTY && process.stderr.isTTY && !process.env.CI) {
+    const { createInterface } = await import("node:readline/promises");
+    const terminal = createInterface({ input: process.stdin, output: process.stderr });
+    const choices = resolved.details.choices;
+    console.error(`\n${resolved.error}`);
+    choices.forEach((choice, index) => console.error(`  ${index + 1}) ${choice.name} (${choice.bundleId})`));
+    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)) break;
+        const selected = Number(answer);
+        if (Number.isInteger(selected) && selected >= 1 && selected <= choices.length) {
+          resolved = await engine.resolveInstalledAppTarget(choices[selected - 1].bundleId);
+          break;
+        }
+      }
+    } finally { terminal.close(); }
+  }
   if (resolved.error) {
     printEngineError(resolved);
     process.exit(1);
@@ -266,11 +286,11 @@ function safeCommandUsage(verb) {
     focus: "tapp focus \"SCREEN OR CONTROL\" [target] [--platform ios|android|web] [--project-dir REPO] [--target NAME|PATH] [--map FILE] [--out FILE]",
     init: "tapp init [repo] [--explore] [--refresh] [--platform PLATFORM] [--target NAME] [--url URL] [--watch] [--dry-run]",
     open: "tapp open [target] [--platform ios|android|web] [--out FILE] [--tap TEXT] [--wait-for TEXT]\n  Web: [--device \"iPhone 13\"] [--viewport 390x844] [--full-page]",
-    tree: "tapp tree [target] [--platform ios|android|web] [--json] [--tap TEXT] [--wait-for TEXT]\n  Web: [--device \"iPhone 13\"] [--viewport 390x844]",
+    tree: "tapp tree [target] [--platform ios|android|web] [--json] [--tap TEXT] [--wait-for TEXT]\n  iOS: inspects an installed app; never builds or installs. Use tapp build explicitly first if needed.\n  Web: [--device \"iPhone 13\"] [--viewport 390x844]",
     shot: "tapp shot [--out FILE]",
     apps: "tapp apps",
     build: "tapp build [repo] [--scheme NAME] [--configuration NAME]",
-    flow: "tapp flow example\ntapp flow steps [--json]\ntapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--actor NAME] [--email VALUE] [--password VALUE] [--device \"iPhone 13\"] [--viewport 390x844]\n  Exit codes: 0 replay passed · 1 replay failed · 2 infrastructure/usage error",
+    flow: "tapp flow example\ntapp flow steps [--json]\ntapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--actor NAME] [--email VALUE] [--password VALUE] [--device \"iPhone 13\"] [--viewport 390x844]\n  iOS: [--launch-arg ARG] [--launch-env JSON]\n  Exit codes: 0 replay passed · 1 replay failed · 2 infrastructure/usage error",
     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]\n  Exit codes: 0 contract held · 1 contract failed · 2 infrastructure/usage error",
     scenario: "tapp scenario validate FILE [--project-dir DIR]\ntapp scenario run FILE --platform web --url URL [--project-dir DIR]\n  Exit codes: 0 scenario passed · 1 scenario failed · 2 infrastructure/usage error",
@@ -962,7 +982,7 @@ switch (command) {
       console.error(`❌ ${sim.error}`);
       process.exit(1);
     }
-    const bundleId = await resolveTargetOrExit(engine, positionals[0]);
+    const bundleId = await resolveTargetOrExit(engine, positionals[0], { inspect: true });
     const r = await engine.captureUiTree(bundleId);
     if (r.error) {
       console.error(`❌ ${r.error}`);
@@ -1230,6 +1250,11 @@ switch (command) {
     const evidenceDir = path.join(tappHome, "captures", `flow-${platform}-${token}`);
     fs.mkdirSync(path.dirname(flowLog), { recursive: true });
     const env = { ...process.env, FLOW_LOG: flowLog, TAPP_FLOW_EVIDENCE_DIR: evidenceDir };
+    if (platform === "ios") {
+      const launch = iosLaunchOptions(flags, rest);
+      if (launch.appLaunchArgs) env.OCQA_APP_LAUNCH_ARGS_JSON = JSON.stringify(launch.appLaunchArgs);
+      if (launch.appLaunchEnv) env.OCQA_APP_LAUNCH_ENV_JSON = JSON.stringify(launch.appLaunchEnv);
+    }
     if (typeof flags.email === "string") env.OCQA_TEST_EMAIL = flags.email;
     if (typeof flags.password === "string") env.OCQA_TEST_PASSWORD = flags.password;
     if (typeof flags.device === "string") env.TAPP_WEB_DEVICE = flags.device;

package/mcp-server/src/index.js

@@ -137,7 +137,9 @@ function runCommand(command, args = [], options = {}) {
       const timeoutMessage = timedOut ? `\nProcess timed out after ${timeoutMs}ms` : "";
       resolve({
         code: timedOut ? 124 : (code ?? 1),
-        stdout: clampOutput(stdout),
+        // Structured inventories are parsed internally; diagnostic truncation would corrupt
+        // their JSON/plist before the caller sees it (large hosted simulator inventories).
+        stdout: options.rawStdout ? stdout : clampOutput(stdout),
         stderr: clampOutput(`${stderr}${timeoutMessage}`.trim()),
         timedOut,
       });
@@ -147,7 +149,7 @@ function runCommand(command, args = [], options = {}) {
       clearTimeout(timer);
       resolve({
         code: 1,
-        stdout: clampOutput(stdout),
+        stdout: options.rawStdout ? stdout : clampOutput(stdout),
         stderr: clampOutput(`${stderr}\n${error.message}`.trim()),
         timedOut: false,
       });
@@ -205,7 +207,7 @@ function summarizeCapture(runPath) {
 
 
 async function listSimulators() {
-  const res = await runCommand("xcrun", ["simctl", "list", "devices", "-j"]);
+  const res = await runCommand("xcrun", ["simctl", "list", "devices", "-j"], { rawStdout: true });
   if (res.code !== 0) return { error: res.stderr || "simctl failed", simulators: [] };
   let data;
   try {
@@ -280,12 +282,12 @@ function notInstalledError(bundleId, booted) {
 // and the tapp_build MCP tool.
 
 export async function listInstalledUserApps() {
-  const r = await runCommand("xcrun", ["simctl", "listapps", "booted"], { timeoutMs: 30_000 });
+  const r = await runCommand("xcrun", ["simctl", "listapps", "booted"], { timeoutMs: 30_000, rawStdout: true });
   if (r.code !== 0) return { error: "Could not list installed apps", details: { stderr: r.stderr } };
   // simctl emits an old-style plist; plutil converts it.
   const tmp = path.join(os.tmpdir(), `tapp-apps-${Date.now().toString(36)}.plist`);
   fs.writeFileSync(tmp, r.stdout);
-  const conv = await runCommand("plutil", ["-convert", "json", "-o", "-", tmp], { timeoutMs: 30_000 });
+  const conv = await runCommand("plutil", ["-convert", "json", "-o", "-", tmp], { timeoutMs: 30_000, rawStdout: true });
   try { fs.rmSync(tmp, { force: true }); } catch {}
   let data;
   try {
@@ -502,6 +504,65 @@ export async function installAppOnBootedSim(appPath, { cleanInstall = true, onSt
   return { bundleId };
 }
 
+// Inspection must never enter the build/install resolver. Even a clean install of the same
+// bundle id can replace a staging binary and destroy its data (public issue #25).
+export async function resolveInstalledAppTarget(input, { cwd = process.cwd(), listApps = listInstalledUserApps, isInstalled = appInstalledOnBootedSim } = {}) {
+  const target = String(input || "").trim();
+  let bundleId = "";
+  let dir = cwd;
+  if (target) {
+    const candidate = path.resolve(cwd, target);
+    if (!target.includes("/") && target.includes(".") && !fs.existsSync(candidate)) {
+      // Explicit ids may name system apps too; the user-app picker intentionally omits them.
+      if (!await isInstalled(target)) return { error: `${target} is not installed on the booted simulator. Install the intended build first; tree will not replace it.` };
+      return { bundleId: target, via: "using the installed app", targetResolution: { kind: "installed-application", bundleId: target } };
+    }
+    else if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory() && !/\.(app|xcodeproj|xcworkspace)$/.test(candidate)) dir = candidate;
+    else return { error: "tree inspects an installed app. Pass its bundle id, or run npx -y @aarwitz/tapp@latest build explicitly before inspecting it." };
+  }
+  const listed = await listApps();
+  if (listed.error) return listed;
+  const apps = listed.apps;
+  if (!bundleId) {
+    const modelPath = existingProjectArtifactPath(dir, "application-model.json");
+    if (fs.existsSync(modelPath)) {
+      let model;
+      try {
+        model = JSON.parse(fs.readFileSync(modelPath, "utf8"));
+        if (model.kind !== "tapp-application-model" || !Array.isArray(model.targets)) throw new Error("invalid application model");
+      } catch (error) {
+        return { error: `Cannot read ${modelPath}: ${error.message}. Pass an installed bundle id explicitly.` };
+      }
+      const targets = model.targets.filter((item) => item.platform === "ios");
+      const selected = targets.find((item) => item.id === model.application?.defaultTargetId)
+        || (targets.length === 1 ? targets[0] : null);
+      bundleId = String(selected?.runtime?.bundleId || "").trim();
+      // A repository with multiple/unconfirmed targets must not silently fall back to an
+      // unrelated app just because it is the only one installed on this simulator.
+      if (!bundleId) return installedAppChoices(apps, "The repository has no unambiguous installed iOS target. Pass the app's bundle id.");
+    } else if (target) {
+      return installedAppChoices(apps, "This repository has no recorded iOS bundle id. Pass the installed app's bundle id; tree does not build it.");
+    } else if (apps.length === 1) {
+      bundleId = apps[0].bundleId;
+    }
+  }
+  if (bundleId) {
+    if (!apps.some((item) => item.bundleId === bundleId)) return { error: `${bundleId} is not installed on the booted simulator. Install the intended build first; tree will not replace it.` };
+    return { bundleId, via: "using the installed app", targetResolution: { kind: "installed-application", bundleId } };
+  }
+  return installedAppChoices(apps, apps.length ? "Choose the installed app to inspect." : "No user app is installed. Install the intended build first; tree does not build or install apps.");
+}
+
+function installedAppChoices(apps, error) {
+  return {
+    error,
+    details: {
+      reason: apps.length ? "target-selection-required" : "app-not-installed",
+      choices: apps.map((app) => ({ platform: "ios", name: app.name, bundleId: app.bundleId, selector: app.bundleId, command: `npx -y @aarwitz/tapp@latest tree ${app.bundleId}` })),
+    },
+  };
+}
+
 export async function resolveAppTarget(input, { cwd = process.cwd(), onStatus = () => {}, scheme = "", configuration = "Debug" } = {}) {
   const t = (input || "").trim();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.17",
+  "version": "0.17.19",
   "mcpName": "io.github.aarwitz/tapp",
   "description": "Let coding agents verify UI changes on real iOS, Android, and web surfaces, then enforce reviewed proof in deterministic CI.",
   "license": "MIT",

package/scripts/run-flow.sh

@@ -98,6 +98,7 @@ TEST_RUNNER_OCQA_CONFIG_PATH="$CFG" xcodebuild test-without-building \
 [ -n "$RESPONDER_PID" ] && { kill "$RESPONDER_PID" 2>/dev/null; wait "$RESPONDER_PID" 2>/dev/null; }
 
 cp "$LOG" "$EVIDENCE_DIR/flow.log"
+grep '^OCQA_EVIDENCE_WARNING:' "$LOG" >&2 || true
 python3 "$ROOT/scripts/flow_lib.py" report --json "$LOG" > "$EVIDENCE_DIR/flow-report.json"
 echo ""
 python3 "$ROOT/scripts/flow_lib.py" report "$LOG"