@aarwitz/tapp 0.17.18 → 0.17.20

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.18",
+  "version": "0.17.20",
   "author": {
     "name": "Aaron Horowitz",
     "url": "https://github.com/aarwitz"
@@ -24,7 +24,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@aarwitz/tapp@0.17.18",
+        "@aarwitz/tapp@0.17.20",
         "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

@@ -715,8 +715,11 @@ class ExplorerTests: XCTestCase {
         guard let emailF = emailField else { return ("no_login_form", "no email/username field visible") }
         guard let passF = passwordField else { return ("no_login_form", "no password field visible") }
 
-        replaceText(on: emailF, with: email)
-        replaceText(on: passF, with: password)
+        guard replaceText(on: emailF, with: email) else { return ("input_failed", lastTypeFailure) }
+        guard (emailF.value as? String) == email else {
+            return ("input_failed", "Email field did not retain the requested value; sign-in was not submitted")
+        }
+        guard replaceText(on: passF, with: password) else { return ("input_failed", lastTypeFailure) }
 
         func formGone(within seconds: TimeInterval) -> Bool {
             let deadline = Date().addingTimeInterval(seconds)
@@ -760,7 +763,7 @@ class ExplorerTests: XCTestCase {
             // behavior). Detect and re-fill before submitting.
             let pv = (passF.value as? String) ?? ""
             if pv.isEmpty || pv == (passF.placeholderValue ?? "§none§") {
-                replaceText(on: passF, with: password)
+                guard replaceText(on: passF, with: password) else { return ("input_failed", lastTypeFailure) }
                 dismissKeyboardIfPresent()
             }
             submit = submitButton() ?? submit
@@ -807,7 +810,9 @@ class ExplorerTests: XCTestCase {
     /// 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
+        let bar = app.navigationBars.firstMatch
+        guard bar.exists else { return }
+        let title = bar.identifier
         guard !title.isEmpty, backTitleHistory.last != title else { return }
         backTitleHistory.append(title)
         if backTitleHistory.count > 20 { backTitleHistory.removeFirst() }
@@ -994,6 +999,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"),
@@ -1121,17 +1129,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)}")
@@ -1141,13 +1139,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) }
@@ -1569,9 +1583,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,
@@ -2677,7 +2702,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,
@@ -2798,8 +2824,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")
@@ -2816,12 +2842,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
@@ -2832,7 +2857,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)}")
                         }
@@ -3326,7 +3351,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
@@ -5049,6 +5095,7 @@ class ExplorerTests: XCTestCase {
     /// a tap nudged to the top of the frame. Three attempts, ~4 s worst case.
     private func focusForTyping(_ element: XCUIElement) -> Bool {
         func focused() -> Bool { (element.value(forKey: "hasKeyboardFocus") as? Bool) ?? false }
+        if focused() { return true }
         func settleUntilFocused() -> Bool {
             let deadline = Date().addingTimeInterval(1.2)
             repeat {
@@ -5116,11 +5163,28 @@ class ExplorerTests: XCTestCase {
             return false
         }
 
-        if let existing = element.value as? String,
-           !existing.isEmpty,
-           existing.lowercased() != "optional" {
-            let deleteString = String(repeating: XCUIKeyboardKey.delete.rawValue, count: existing.count)
-            element.typeText(deleteString)
+        func hasContent() -> Bool {
+            guard let value = element.value as? String else { return false }
+            return !value.isEmpty && value != element.placeholderValue
+        }
+        if hasContent() {
+            // A tap may put the cursor in the middle. Select the complete field instead of
+            // deleting only the prefix, then prove it is empty before inserting new text.
+            element.typeKey("a", modifierFlags: .command)
+            element.typeText(XCUIKeyboardKey.delete.rawValue)
+            if hasContent(), let remaining = element.value as? String {
+                // Some simulator keyboard configurations ignore Command-A. Clear on both
+                // sides of the cursor in that case; backspace alone leaves the suffix intact.
+                let count = remaining.utf16.count
+                element.typeText(String(repeating: XCUIKeyboardKey.delete.rawValue, count: count)
+                    + String(repeating: XCUIKeyboardKey.forwardDelete.rawValue, count: count))
+            }
+            let deadline = Date().addingTimeInterval(1.0)
+            while hasContent() && Date() < deadline { Thread.sleep(forTimeInterval: 0.1) }
+            guard !hasContent() else {
+                lastTypeFailure = "Field contents could not be cleared; replacement was not entered"
+                return false
+            }
         }
 
         element.typeText(text)

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

@@ -102,13 +102,8 @@ function bootBestSimulator(preferredName = "iPhone 16 Pro") {
 }
 
 function harnessXctestrun() {
-  const dir = path.join(tappHome, "harness-derived", "Build", "Products");
-  try {
-    const found = fs.readdirSync(dir).find((f) => f.endsWith(".xctestrun"));
-    return found ? path.join(dir, found) : null;
-  } catch {
-    return null;
-  }
+  const result = run("bash", [path.join(packageRoot, "scripts/quick-capture.sh"), "harness-path"]);
+  return result.code === 0 && result.stdout ? result.stdout : null;
 }
 
 // Flags/positionals for the zero-config verbs (qa/open/tree/shot). `--key value` or bare `--key`.
@@ -172,17 +167,6 @@ function requireMacFor(what) {
   process.exit(1);
 }
 
-function ensureIOSHarness() {
-  const result = spawnSync("bash", [path.join(packageRoot, "scripts", "quick-capture.sh"), "build-harness"], {
-    stdio: "inherit",
-    env: process.env,
-  });
-  if ((result.status ?? 1) !== 0) {
-    console.error("❌ Could not prepare the iOS test harness.");
-    process.exit(result.status ?? 1);
-  }
-}
-
 function requestedPlatform(flags, target = "") {
   if (typeof flags.platform === "string") return flags.platform.toLowerCase();
   if (/^https?:\/\//i.test(target)) return "web";
@@ -222,7 +206,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 +234,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 +270,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 +966,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 +1234,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;
@@ -1266,7 +1275,6 @@ switch (command) {
       invocation = [process.execPath, [path.join(packageRoot, "scripts", "run-android-flow.js"), absolute, target.appId, target.apkPath || "", target.serial || ""]];
     } else {
       requireMacFor("iOS Flow replay");
-      ensureIOSHarness();
       invocation = ["bash", [path.join(packageRoot, "scripts", "run-flow.sh"), absolute, typeof flags["bundle-id"] === "string" ? flags["bundle-id"] : flow.app || ""]];
     }
     const result = spawnSync(invocation[0], invocation[1], { stdio: "inherit", env });

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();
 
@@ -588,6 +649,18 @@ export async function resolveAppTarget(input, { cwd = process.cwd(), onStatus =
 let activeSession = null;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
+export function sessionFailureReason(log = "", credentials = {}) {
+  for (const pattern of [/Failed to get matching snapshot:[^\n]*/, /Failed to synthesize event:[^\n]*/, /error:\s*[^\n]+/, /Error Domain=[^\n]+/, /Test Case '[^']*' failed[^\n]*/]) {
+    const match = String(log).match(pattern);
+    if (match) {
+      let message = match[0].trim();
+      for (const secret of Object.values(credentials).filter((value) => typeof value === "string" && value)) message = message.split(secret).join("[redacted]");
+      return message.slice(0, 1200);
+    }
+  }
+  return "The XCTest session process exited; reopen the app to start a new session.";
+}
+
 function consumeSessionStdout(chunk) {
   if (!activeSession) return;
   activeSession.buffer += chunk;
@@ -704,9 +777,9 @@ async function startSession(bundleId, extraEnv = {}) {
   while (!activeSession.ready && Date.now() < deadline && !activeSession.ended) await sleep(300);
   if (activeSession.ended) {
     // Surface the real failure from the harness output instead of a shrug.
-    const errLine = ((activeSession.buffer || "").match(/error:\s*([^\n]+)/) || [])[1];
+    const errLine = sessionFailureReason(activeSession.buffer, activeSession.creds);
     activeSession = null;
-    return { error: `Session process exited before it became ready${errLine ? ` — ${errLine.trim()}` : " (build/launch failed?)."}` };
+    return { error: `Session process exited before it became ready — ${errLine}` };
   }
   if (!activeSession.ready) { return { error: "Session did not become ready within the time limit." }; }
 
@@ -953,9 +1026,14 @@ export function sessionActUsageError(cmd = {}) {
 async function sessionAct(cmd) {
   const startedAt = Date.now();
   const done = (result) => ({ ...result, durationMs: Date.now() - startedAt });
-  if (!activeSession || activeSession.ended) return done({ error: "No active session. Call tapp_session_start first." });
+  if (!activeSession) return done({ error: "No active session. Call tapp_session_start first." });
+  if (activeSession.ended) return done({ error: sessionFailureReason(activeSession.buffer, activeSession.creds) });
   const usage = sessionActUsageError(cmd);
   if (usage) return done({ status: "usage", detail: usage, ...treeSnapshot(), recordedSteps: activeSession.recording.length });
+  if (cmd.action === "login") {
+    if (cmd.email) activeSession.creds.email = cmd.email;
+    if (cmd.password) activeSession.creds.password = cmd.password;
+  }
   let coordinateResolvedTarget = "";
   if (cmd.action === "tap" && !cmd.id && Number.isFinite(cmd.x) && Number.isFinite(cmd.y)) {
     coordinateResolvedTarget = semanticTargetAtPoint(activeSession.latestTree?.elements, cmd.x, cmd.y);
@@ -1115,6 +1193,10 @@ async function sessionAct(cmd) {
   const td = Date.now() + 5_000;
   while (activeSession.treeVersion === beforeVer && Date.now() < td && !activeSession.ended) await sleep(150);
   const snap = treeSnapshot();
+  if (status === "timeout" && activeSession.ended) {
+    status = "harness_failed";
+    detail = sessionFailureReason(activeSession.buffer, activeSession.creds);
+  }
   if (status === "ok") recordStep(cmd, snap); // record only successful acts
   return done({ status, typedInto, detail, ...snap, recordedSteps: activeSession ? activeSession.recording.length : 0, ...(coordinateResolvedTarget ? { coordinateResolvedTarget } : {}) });
 }
@@ -3211,6 +3293,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           action: { type: "string", enum: ["login", "tap", "type", "swipe", "back", "wait", "tree", "screenshot"] },
           email: { type: "string", description: "login: email/username to sign in with" },
           password: { type: "string", description: "login: password to sign in with" },
+          actor: { type: "string", description: "login: configured actor; explicit email/password override its environment bindings" },
           id: { type: "string", description: "Element accessibility id or visible/partial label (for tap/type/wait)" },
           x: { type: "number", description: "Tap X coordinate (points), if not using id" },
           y: { type: "number", description: "Tap Y coordinate (points), if not using id" },
@@ -4524,6 +4607,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (action === "login") {
       if (isNonEmptyString(args.email)) cmd.email = args.email.trim();
       if (isNonEmptyString(args.password)) cmd.password = args.password;
+      if (isNonEmptyString(args.actor)) {
+        try {
+          const { resolveActorCredentials } = await import("./project-config.js");
+          Object.assign(cmd, resolveActorCredentials(workspaceRoot, { actor: args.actor.trim(), email: cmd.email, password: cmd.password }));
+        } catch (error) { return errorResult(error.message); }
+      }
     }
     if (action === "wait") cmd.timeoutMs = Math.max(500, Math.min(60_000, asInteger(args.timeoutMs, 5000)));
     const r = await sessionAct(cmd);

package/mcp-server/src/project-config.js

@@ -4,6 +4,24 @@ import { TAPP_DIRECTORY, projectArtifactDirectory } from "./project-paths.js";
 
 export const PROJECT_CONFIG_RELATIVE_PATH = `${TAPP_DIRECTORY}/project.json`;
 
+// Resolve a named actor entirely inside the engine. Never return these values as tool
+// output or fall back to another identity when a binding is absent.
+export function resolveActorCredentials(projectDir, { actor, email, password, env = process.env } = {}) {
+  const loaded = readProjectConfig(projectDir);
+  if (loaded.errors.length) throw new Error(`Invalid ${loaded.relativePath}: ${loaded.errors.join("; ")}`);
+  const configured = loaded.config.actors?.[actor];
+  if (!configured) throw new Error(`Actor '${actor}' is not configured in ${loaded.relativePath}`);
+  const credentials = { email, password };
+  for (const key of ["email", "password"]) {
+    if (typeof credentials[key] === "string" && credentials[key]) continue;
+    const binding = configured.credentials?.[key]?.env;
+    if (!binding) throw new Error(`Actor '${actor}' has no ${key} environment binding`);
+    if (!env[binding]) throw new Error(`Actor '${actor}' requires $${binding} in the Tapp process environment`);
+    credentials[key] = env[binding];
+  }
+  return credentials;
+}
+
 const ACTOR_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 const ENV_NAME = /^[A-Z_][A-Z0-9_]{0,127}$/;
 const CREDENTIAL_NAME = /^[a-z][A-Za-z0-9_-]{0,63}$/;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.18",
+  "version": "0.17.20",
   "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/flow_lib.py

@@ -10,6 +10,7 @@ Usage:
   flow_lib.py report --json <harness.log>            # prints machine JSON {passed,total,failed,steps}
 """
 import json
+import os
 import re
 import sys
 
@@ -73,23 +74,34 @@ def raw_json(path):
 ABORT_PATTERNS = [
     r"Failed to synthesize event: [^\n]*",
     r"Neither element nor any descendant has keyboard focus[^\n]*",
-    r"Test Case '[^']*' failed \([^)]*\)",
     r"Error Domain=[^\n]*",
     r"Unable to (?:find|launch|boot)[^\n]*",
     r"App state is [^\n]*",
     r"Timed out [^\n]*",
     r"Testing failed:[^\n]*",
     r"error: [^\n]*",
+    r"Test Case '[^']*' failed \([^)]*\)",
     r"\*\* TEST (?:EXECUTE )?FAILED \*\*",
 ]
 
 
-def harness_abort_reason(log):
+def harness_abort_reason(log, path=None):
     """First XCTest/xcodebuild line that explains why a run ended before step 1."""
+    if path:
+        for summary_path in [path + ".xctest-summary.json", os.path.join(os.path.dirname(path), "xctest-summary.json")]:
+            try:
+                with open(summary_path, encoding="utf-8") as summary_file:
+                    summary = json.load(summary_file)
+                messages = [failure["failureText"] for failure in summary.get("testFailures", [])
+                            if isinstance(failure.get("failureText"), str) and failure["failureText"].strip()]
+                if messages:
+                    return " | ".join(dict.fromkeys(messages))[:1200]
+            except (OSError, ValueError, TypeError, AttributeError):
+                pass
     for pat in ABORT_PATTERNS:
         m = re.search(pat, log)
         if m:
-            return m.group(0).strip()[:300]
+            return m.group(0).strip()[:1200]
     return None
 
 
@@ -102,7 +114,14 @@ def report(path, as_json=False):
     declared_total = None
     for line in log.splitlines():
         line = line.strip()
-        if line.startswith("OCQA_FLOW_STEP:"):
+        if line.startswith("OCQA_FLOW_PLAN:"):
+            try:
+                plan = json.loads(line[len("OCQA_FLOW_PLAN:"):])
+                name = plan.get("name", name)
+                declared_total = plan.get("total", declared_total)
+            except (ValueError, TypeError, AttributeError):
+                pass
+        elif line.startswith("OCQA_FLOW_STEP:"):
             try:
                 steps.append(json.loads(line[len("OCQA_FLOW_STEP:"):]))
             except Exception:
@@ -124,7 +143,7 @@ def report(path, as_json=False):
             except Exception:
                 pass
 
-    total = (result or {}).get("total", len(steps))
+    total = (result or {}).get("total", declared_total if declared_total is not None else len(steps))
     failed = (result or {}).get("failed", sum(1 for s in steps if s.get("status") == "fail"))
     passed = (result or {}).get("passed", failed == 0 and bool(steps))
 
@@ -136,7 +155,7 @@ def report(path, as_json=False):
     # failure of the first step so the scoreboard says why instead of looking like a crash.
     abort_reason = None
     if not steps and not passed:
-        abort_reason = harness_abort_reason(log)
+        abort_reason = harness_abort_reason(log, path)
         steps.append({"index": 1, "action": "harness", "target": "", "status": "fail",
                       "detail": abort_reason or "the harness exited before the first step; see flow.log"})
         failed = max(failed, 1)
@@ -144,7 +163,7 @@ def report(path, as_json=False):
         # The harness died MID-run (an XCTest assertion, the test time budget, a crash): there is
         # no final OCQA_FLOW_RESULT line. This used to be reported as "PASSED 16/16" because
         # `total` silently became the number of steps that happened to run before the death.
-        abort_reason = harness_abort_reason(log)
+        abort_reason = harness_abort_reason(log, path)
         total = declared_total or total
         steps.append({"index": len(steps) + 1, "action": "harness", "target": "", "status": "fail",
                       "detail": (abort_reason or "the harness exited") + f" — run ended after step {executed} of {total}"})

package/scripts/quick-capture.sh

@@ -67,44 +67,58 @@ cleanup_stale_recorders() {
   sleep 1
 }
 
+harness_fingerprint() {
+  # SDK names in .xctestrun filenames describe the BUILD SDK, not the simulator OS.
+  # Record the source/project and selected toolchain, then reuse the exact build product.
+  {
+    find "$(dirname "$HARNESS_PROJECT")" -type f \( -name '*.swift' -o -name project.pbxproj -o -name '*.xcscheme' -o -name '*.plist' \) -print0 \
+      | sort -z | xargs -0 shasum
+    xcode-select -p
+    xcodebuild -version
+    xcrun --sdk iphonesimulator --show-sdk-version
+  } | shasum | cut -c1-40
+}
+
+cached_harness_path() {
+  local marker="$HARNESS_DERIVED/.last-sim-udid"
+  [[ -f "$marker" ]] || return 1
+  [[ "$(sed -n 1p "$marker")" == "$UDID" ]] || return 1
+  [[ "$(sed -n 2p "$marker")" == "$(harness_fingerprint)" ]] || return 1
+  local selected="$(sed -n 3p "$marker")"
+  [[ -n "$selected" && "$selected" != */* && "$selected" == *.xctestrun ]] || return 1
+  [[ -f "$HARNESS_DERIVED/Build/Products/$selected" ]] || return 1
+  printf '%s\n' "$HARNESS_DERIVED/Build/Products/$selected"
+}
+
 ensure_harness_built() {
   local sim_name="${1:-iPhone 16 Pro}"
   local udid="${UDID:-}"
   local marker="$HARNESS_DERIVED/.last-sim-udid"
-  local last_udid="" last_fp=""
-  if [[ -f "$marker" ]]; then
-    last_udid=$(sed -n 1p "$marker" 2>/dev/null || true)
-    last_fp=$(sed -n 2p "$marker" 2>/dev/null || true)
-  fi
-  # Fingerprint the harness source so a package update actually reaches users — without this,
-  # a warm cache serves the OLD harness forever (npm normalizes mtimes, so hash the content).
-  local src_file="$(dirname "$HARNESS_PROJECT")/OCQAHarnessUITests/ExplorerTests.swift"
-  local src_fp=$(shasum "$src_file" 2>/dev/null | cut -c1-12)
-  local xctestrun=$(find "$HARNESS_DERIVED/Build/Products" -name "*.xctestrun" 2>/dev/null | head -1)
-
-  # Reuse the cached harness ONLY if it was built for the currently-booted simulator AND from
-  # the same harness sources. A harness built for a different sim can fail to launch the
-  # interactive session; a stale-source harness silently lacks shipped fixes.
-  if [[ -n "$xctestrun" && ( -z "$udid" || "$udid" == "$last_udid" ) && "$src_fp" == "$last_fp" ]]; then
+  local xctestrun
+  if xctestrun=$(cached_harness_path); then
     echo "Harness already built for this sim: $xctestrun" >&2
     return 0
   fi
-  if [[ -n "$xctestrun" && "$src_fp" != "$last_fp" ]]; then
-    echo "Harness sources changed — rebuilding for $sim_name..." >&2
-  elif [[ -n "$xctestrun" ]]; then
-    echo "Booted simulator changed ($last_udid -> $udid) — rebuilding harness for $sim_name..." >&2
-  else
-    echo "Building harness for $sim_name..." >&2
-  fi
+  echo "Preparing harness for $sim_name (source, simulator, or Xcode cache changed)..." >&2
+  local src_fp=$(harness_fingerprint)
+  mkdir -p "$HARNESS_DERIVED/Build/Products"
+  rm -f "$marker"
+  # Xcode leaves old SDK descriptors beside the new one. Only the descriptor emitted by
+  # this successful build may become current; never select an arbitrary directory entry.
+  find "$HARNESS_DERIVED/Build/Products" -maxdepth 1 -name '*.xctestrun' -type f -delete
   xcodebuild build-for-testing \
     -project "$HARNESS_PROJECT" \
     -scheme OCQAHarnessUITests \
     -destination "platform=iOS Simulator,id=$UDID" \
     -derivedDataPath "$HARNESS_DERIVED" \
     2>&1 | tail -5 >&2
-  # Record which sim + harness sources this build came from so the next run detects both
-  # a simulator switch and a package update.
-  printf '%s\n%s\n' "$udid" "$src_fp" > "$marker"
+  local products=()
+  while IFS= read -r product; do products+=("$product"); done < <(find "$HARNESS_DERIVED/Build/Products" -maxdepth 1 -name '*.xctestrun' -type f)
+  if [[ ${#products[@]} -ne 1 ]]; then
+    echo "ERROR: Harness build produced ${#products[@]} test descriptors; no cache was selected." >&2
+    return 1
+  fi
+  printf '%s\n%s\n%s\n' "$udid" "$src_fp" "$(basename "${products[0]}")" > "$marker"
 }
 
 run_harness_test() {
@@ -189,7 +203,7 @@ run_harness_test() {
 }
 CONF
 
-  local xctestrun=$(find "$HARNESS_DERIVED/Build/Products" -name "*.xctestrun" 2>/dev/null | head -1)
+  local xctestrun=$(cached_harness_path)
   if [[ -z "$xctestrun" ]]; then
     echo "ERROR: No xctestrun found. Run: tapp install" >&2
     return 1
@@ -226,15 +240,23 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
-mkdir -p "$CAPTURE_DIR"
 UDID=$(get_booted_sim)
 SIM_NAME=$(get_sim_name)
 
 if [[ -z "$UDID" ]]; then
-  echo "ERROR: No booted simulator found. Boot one first:"
-  echo "  xcrun simctl boot 'iPhone 16 Pro'"
+  echo "ERROR: No booted simulator found. Boot one first:" >&2
+  echo "  xcrun simctl boot 'iPhone 16 Pro'" >&2
   exit 1
 fi
+if [[ "$MODE" == "harness-path" ]]; then
+  cached_harness_path
+  exit $?
+elif [[ "$MODE" == "prepare-harness" ]]; then
+  ensure_harness_built "$SIM_NAME"
+  cached_harness_path
+  exit $?
+fi
+mkdir -p "$CAPTURE_DIR"
 echo "Simulator: $SIM_NAME ($UDID)"
 echo "Output: $CAPTURE_DIR"
 echo ""
@@ -452,7 +474,7 @@ OCQA_COMPLETE:{\"actions\":0,\"states\":0,\"issues\":1,\"screens\":\"\",\"outcom
   "OCQA_TEST_PASSWORD": "${OCQA_TEST_PASSWORD:-}"$sess_args_line$sess_env_line
 }
 CONF
-    xctestrun=$(find "$HARNESS_DERIVED/Build/Products" -name "*.xctestrun" 2>/dev/null | head -1)
+    xctestrun=$(cached_harness_path)
     if [[ -z "$xctestrun" ]]; then
       echo "ERROR: No xctestrun. Run: tapp install" >&2
       exit 1
@@ -470,7 +492,7 @@ CONF
     # for a fast first tool call later. No capture output.
     ensure_harness_built "$SIM_NAME"
     rmdir "$CAPTURE_DIR" 2>/dev/null || true
-    echo "Harness ready: $(find "$HARNESS_DERIVED/Build/Products" -name '*.xctestrun' 2>/dev/null | head -1)"
+    echo "Harness ready: $(cached_harness_path)"
     ;;
 
   *)

package/scripts/run-flow.sh

@@ -24,19 +24,13 @@ APP="${2:-}"
 
 UDID="$(xcrun simctl list devices booted -j 2>/dev/null | python3 -c 'import sys,json; d=json.load(sys.stdin); print(next((x["udid"] for v in d["devices"].values() for x in v if x.get("state")=="Booted"), ""))')"
 [ -z "$UDID" ] && { echo "❌ No booted simulator."; exit 2; }
-# When run through the installed `tapp` CLI, the harness cache lives under TAPP_HOME.
-XCTR=""
-TAPP_RUNTIME_HOME="${TAPP_HOME:-}"
-[ -n "$TAPP_RUNTIME_HOME" ] && XCTR="$(find "$TAPP_RUNTIME_HOME/harness-derived/Build/Products" -name '*.xctestrun' 2>/dev/null | head -1)"
-[ -z "$XCTR" ] && XCTR="$(find "$HOME/Library/Developer/Xcode/DerivedData/OCQAHarness-"*/Build/Products -name '*.xctestrun' 2>/dev/null | head -1)"
-[ -z "$XCTR" ] && XCTR="$(find /tmp/tapp-harness-derived/Build/Products -name '*.xctestrun' 2>/dev/null | head -1)"
-[ -z "$XCTR" ] && XCTR="$(find /tmp/harness-build/Build/Products -name '*.xctestrun' 2>/dev/null | head -1)"
-[ -z "$XCTR" ] && { echo "❌ Harness not built. Run: tapp install"; exit 2; }
+# CLI, MCP, sessions, and doctor share the same source/toolchain-validated descriptor.
+XCTR="$(bash "$ROOT/scripts/quick-capture.sh" prepare-harness)" || exit 2
 
 NAME="$(python3 -c "import sys,json;print(json.loads(sys.argv[1]).get('name','flow'))" "$FLOW_JSON")"
 echo "▶️  Running flow \"$NAME\" against $APP …"
 
-TOKEN="$(date +%s)"
+TOKEN="$$-$(date +%s)"
 CFG="/tmp/ocqa-flow-$TOKEN.json"
 AI_RESP="/tmp/ocqa-flow-ai-$TOKEN.json"
 AI_DIR="/tmp/ocqa-flow-ai-$TOKEN"
@@ -83,10 +77,15 @@ if [ "$?" -ne 0 ]; then
 fi
 
 LOG="${FLOW_LOG:-/tmp/ocqa-flow-$TOKEN.log}"
+python3 - "$FLOW_JSON" > "$LOG" <<'PY'
+import json, sys
+flow = json.loads(sys.argv[1])
+print("OCQA_FLOW_PLAN:" + json.dumps({"name": flow.get("name", "flow"), "total": len(flow.get("steps", []))}))
+PY
 # assert_ai judge sidecar (only when a key is present) — same file-channel as vision escalation.
 RESPONDER_PID=""
 if [ -n "${ANTHROPIC_API_KEY:-}" ]; then
-  mkdir -p "$AI_DIR"; : > "$LOG"
+  mkdir -p "$AI_DIR"
   python3 "$ROOT/scripts/flow_ai_judge.py" "$LOG" "$AI_RESP" > "/tmp/ocqa-flow-judge-$TOKEN.log" 2>&1 &
   RESPONDER_PID=$!
 fi
@@ -94,10 +93,18 @@ fi
 TEST_RUNNER_OCQA_CONFIG_PATH="$CFG" xcodebuild test-without-building \
   -xctestrun "$XCTR" -destination "platform=iOS Simulator,id=$UDID" \
   -only-testing:"OCQAHarnessUITests/ExplorerTests/testReplayFlow" \
-  -resultBundlePath "$RESULT_BUNDLE" > "$LOG" 2>&1
+  -resultBundlePath "$RESULT_BUNDLE" >> "$LOG" 2>&1
+XCODE_STATUS=$?
 [ -n "$RESPONDER_PID" ] && { kill "$RESPONDER_PID" 2>/dev/null; wait "$RESPONDER_PID" 2>/dev/null; }
 
 cp "$LOG" "$EVIDENCE_DIR/flow.log"
+# XCTest can put the actionable failure only in the result bundle. Keep that summary
+# beside the log so both the CLI and MCP report readers surface it before generic status.
+if [ "$XCODE_STATUS" -ne 0 ] && [ -d "$RESULT_BUNDLE" ]; then
+  xcrun xcresulttool get test-results summary --path "$RESULT_BUNDLE" > "$EVIDENCE_DIR/xctest-summary.json" 2> "$EVIDENCE_DIR/xcresulttool.log" || true
+  cp "$EVIDENCE_DIR/xctest-summary.json" "$LOG.xctest-summary.json"
+fi
+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"