@aarwitz/tapp 0.17.13 → 0.17.16

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.13",
+  "version": "0.17.16",
   "author": {
     "name": "Aaron Horowitz",
     "url": "https://github.com/aarwitz"
@@ -24,7 +24,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@aarwitz/tapp@0.17.13",
+        "@aarwitz/tapp@0.17.16",
         "mcp"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}"

package/AGENTS.md

@@ -133,6 +133,11 @@ advisory). Report the finding counts and coverage; do not invent a scalar or a s
   (e.g. `["--uitesting"]` if the app has a test bypass), and/or `appLaunchEnv` (e.g. a staging
   backend URL). If the result shows `inputFieldsEncountered` and you have no credentials, **ask
   the user** for them rather than re-running blind.
+- `tapp audit <url>` is the read-only pass: it renders the page and reads the tree but never
+  clicks, so it is the one analysis safe to point at production. It finds controls that were
+  never alive — dead in-page anchors, `aria-controls` naming nothing, placeholder links, buttons
+  with no handler/form/link — which Flows structurally cannot find, because nobody writes a test
+  for a button they believe does nothing. Exit 1 when it finds any.
 - Credential surfaces are catalogue-only without credentials, on every platform: with no
   `testEmail`/`testPassword` supplied, exploration records a login/signup form's fields but does
   not type into them, submit them, or open recovery/third-party-auth flows — a bare-app run may

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -231,6 +231,11 @@ class ExplorerTests: XCTestCase {
         for query in queries {
             let element = query[identifier]
             if element.exists && element.isHittable {
+                if !waitForEnabled(element) {
+                    print("OCQA_ACTION:{\"type\":\"tap\",\"identifier\":\"\(identifier)\",\"status\":\"disabled\"}")
+                    Thread.sleep(forTimeInterval: 0.5)
+                    return
+                }
                 element.tap()
                 print("OCQA_ACTION:{\"type\":\"tap\",\"identifier\":\"\(identifier)\"}")
                 Thread.sleep(forTimeInterval: 0.5)
@@ -240,8 +245,12 @@ class ExplorerTests: XCTestCase {
         let predicate = NSPredicate(format: "label == %@", identifier)
         let match = app.descendants(matching: .any).matching(predicate).firstMatch
         if match.exists && match.isHittable {
-            match.tap()
-            print("OCQA_ACTION:{\"type\":\"tap\",\"label\":\"\(identifier)\"}")
+            if !waitForEnabled(match) {
+                print("OCQA_ACTION:{\"type\":\"tap\",\"label\":\"\(identifier)\",\"status\":\"disabled\"}")
+            } else {
+                match.tap()
+                print("OCQA_ACTION:{\"type\":\"tap\",\"label\":\"\(identifier)\"}")
+            }
         } else {
             print("OCQA_ACTION:{\"type\":\"tap\",\"identifier\":\"\(identifier)\",\"status\":\"not_found\"}")
         }
@@ -434,10 +443,27 @@ class ExplorerTests: XCTestCase {
     /// Returns "ok" if tapped, "not_hittable" if the element exists but couldn't be tapped (disabled,
     /// or covered by the keyboard even after dismissing it), or "not_found" if nothing matched. The
     /// distinction tells the caller whether to enter valid input first vs. that the target is absent.
+    /// A disabled control is still `exists` and still `isHittable`, so tapping one
+    /// succeeds and reports a normal action while nothing happens: the step passes and
+    /// the flow carries on against a screen that never advanced. Wait before calling it
+    /// disabled — a button guarded by form validation becomes enabled a moment after the
+    /// last field is filled, and failing on that would be its own kind of wrong answer.
+    private func waitForEnabled(_ element: XCUIElement, timeout: TimeInterval = 3) -> Bool {
+        if element.isEnabled { return true }
+        let deadline = Date().addingTimeInterval(timeout)
+        while Date() < deadline {
+            if element.isEnabled { return true }
+            Thread.sleep(forTimeInterval: 0.15)
+        }
+        return false
+    }
+
     private func sessionTapById(_ identifier: String) -> String {
         var existedButNotHittable = false
+        var existedButDisabled = false
         func tryTap(_ el: XCUIElement) -> Bool {
             guard el.exists else { return false }
+            if !waitForEnabled(el) { existedButDisabled = true; return false }
             if el.isHittable { el.tap(); return true }
             // Often covered by the keyboard (a submit button below filled fields) — dismiss + retry,
             // like Playwright auto-scrolls a target into view.
@@ -472,6 +498,9 @@ class ExplorerTests: XCTestCase {
         // label) — "Password" must reach the secureTextField or a later `type` lands in whatever
         // field still has keyboard focus.
         if let field = resolveFieldByHint(identifier), tryTap(field) { return "ok" }
+        // "disabled" outranks the others: the control was found and refused to act, which
+        // is a different answer from "it is not here" and needs a different fix.
+        if existedButDisabled { return "disabled" }
         return existedButNotHittable ? "not_hittable" : "not_found"
     }
 
@@ -827,8 +856,19 @@ class ExplorerTests: XCTestCase {
 
             switch action {
             case "tap":
-                status = sessionTapById(target) == "ok" ? "pass" : "fail"
-                if status == "fail" { detail = "could not tap ‘\(target)’" }
+                let tapStatus = sessionTapById(target)
+                status = tapStatus == "ok" ? "pass" : "fail"
+                if status == "fail" {
+                    // Name which of the three it was. "Disabled" in particular sends the
+                    // author somewhere completely different from "not found": the control
+                    // is right there, and something upstream in the flow has not satisfied
+                    // whatever guards it.
+                    switch tapStatus {
+                    case "disabled":     detail = "‘\(target)’ is on screen but disabled — an earlier step has not met whatever enables it"
+                    case "not_hittable": detail = "‘\(target)’ exists but could not be reached, even after dismissing the keyboard and scrolling"
+                    default:             detail = "could not find ‘\(target)’ on this screen"
+                    }
+                }
             case "type":
                 status = sessionType(value, id: target.isEmpty ? nil : target) ? "pass" : "fail"
                 if status == "fail" { detail = lastTypeFailure.isEmpty ? "no field ‘\(target)’ to type into" : lastTypeFailure }
@@ -1389,6 +1429,10 @@ class ExplorerTests: XCTestCase {
         // say "navigation-trap" or "frontier-drained" instead of blessing a 15/20 run "completed".
         var explorationStopCause = "action-budget"
         var leftAppObservations = 0
+        // A loop the EXPLORER created by going back is its own traversal strategy, not an app
+        // defect (field issue #9: "Personal Info ↔ back" filed as a finding). Remember when we
+        // last navigated backwards so the loop detector can tell the two apart.
+        var lastExplorerBackStep = -99
         while actionCount < maxActions {
             // Subtract time spent paused for interactive input so human typing never eats the budget.
             if Date().timeIntervalSince(startTime) - totalWaitSeconds > timeoutSeconds {
@@ -1889,10 +1933,11 @@ class ExplorerTests: XCTestCase {
                     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 period = hasLoop2 ? 2 : 3
+                let explorerDroveTheLoop = actionCount - lastExplorerBackStep <= period * 2
+                if (hasLoop2 || hasLoop3) && !explorerDroveTheLoop && !(authSucceeded && detectedInputs.contains { $0.secure }) {
                     let loopKey = "nav_loop:\(titleStr)"
                     if actionCounts[loopKey] == nil {
-                        let period = hasLoop2 ? 2 : 3
                         issues.append((type: "navigation_loop", severity: "low", title: "Navigation loop detected (period \(period))", desc: "Exploration is cycling between the same \(period) screens"))
                         print("OCQA_ISSUE:{\"type\":\"navigation_loop\",\"severity\":\"low\",\"title\":\"Navigation loop\",\"screen\":\"\(escapedTitle)\",\"period\":\(period),\"step\":\(actionCount)}")
                         actionCounts[loopKey] = 1
@@ -1947,6 +1992,7 @@ class ExplorerTests: XCTestCase {
                 // tryGoBack does swipe-down as its last resort (sheet dismiss)
                 let preBackTitle = titleStr
                 let backWorked = tryGoBack()
+                lastExplorerBackStep = actionCount
                 actionCount += 1
                 Thread.sleep(forTimeInterval: 0.3)
                 let postElements = readUITree(app)
@@ -2214,6 +2260,7 @@ class ExplorerTests: XCTestCase {
                 // Scrolling done — try to go back and verify the screen actually changed
                 let preBackTitle = titleStr
                 let backResult = tryGoBack()
+                lastExplorerBackStep = actionCount
                 actionCount += 1
                 Thread.sleep(forTimeInterval: 0.3)
                 let postBackElements = readUITree(app)
@@ -2270,6 +2317,7 @@ class ExplorerTests: XCTestCase {
                     let swipeStart = app.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.3))
                     let swipeEnd = app.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.9))
                     swipeStart.press(forDuration: 0.1, thenDragTo: swipeEnd)
+                    lastExplorerBackStep = actionCount
                     actionCount += 1
                     print("OCQA_ACTION:{\"type\":\"swipe_dismiss\",\"reason\":\"escape_stuck\",\"step\":\(actionCount),\"screen\":\"\(escapedTitle)\",\"narrative\":\"\(escapeJSON(recoveryNarrative("swipe_dismiss", screen: titleStr)))\"}")
                     Thread.sleep(forTimeInterval: 0.5)
@@ -4784,23 +4832,46 @@ class ExplorerTests: XCTestCase {
             } while Date() < deadline
             return focused()
         }
-        for attempt in 0..<3 {
+        // A field further down a form is usually UNDER the keyboard that the previous
+        // field opened, so every tap below lands on a key instead and three attempts
+        // report "never took keyboard focus" for a field that was simply unreachable.
+        // sessionTapById already dismisses and scrolls for taps; typing needs the same
+        // or no form taller than the keyboard can be filled at all.
+        func keyboardCovers(_ el: XCUIElement) -> Bool {
+            let keyboard = app.keyboards.firstMatch
+            guard keyboard.exists else { return false }
+            let f = el.frame, k = keyboard.frame
+            return f.intersects(k) || f.minY >= k.minY
+        }
+
+        for attempt in 0..<5 {
             switch attempt {
             case 0:
                 if element.isHittable { element.tap() } else { element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap() }
             case 1:
                 element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap()
-            default:
+            case 2:
                 // Frame may be stale by a few rows: tap just inside its top edge, which stays
                 // within the visible control when content shifted up.
                 element.coordinate(withNormalizedOffset: CGVector(dx: 0.35, dy: 0.2)).tap()
+            case 3:
+                // Get the keyboard out of the way and try where the field now sits.
+                dismissKeyboardIfPresent()
+                waitForAnimationsToSettle()
+                if element.isHittable { element.tap() } else { element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap() }
+            default:
+                // Still out of reach: bring it up the screen, then tap.
+                dismissKeyboardIfPresent()
+                app.swipeUp()
+                Thread.sleep(forTimeInterval: 0.25)
+                if element.isHittable { element.tap() } else { element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap() }
             }
             if settleUntilFocused() {
                 if attempt > 0 { print("OCQA_STATE:type_focus_recovered attempt=\(attempt + 1)") }
                 return true
             }
             let f = element.frame
-            print("OCQA_STATE:type_focus_miss attempt=\(attempt + 1) frame=\(Int(f.minX)),\(Int(f.minY)),\(Int(f.width))x\(Int(f.height)) keyboard=\(app.keyboards.count) focusedElsewhere=\(focusedField().map { fieldDesc($0) } ?? "none")")
+            print("OCQA_STATE:type_focus_miss attempt=\(attempt + 1) frame=\(Int(f.minX)),\(Int(f.minY)),\(Int(f.width))x\(Int(f.height)) keyboard=\(app.keyboards.count) covered=\(keyboardCovers(element)) focusedElsewhere=\(focusedField().map { fieldDesc($0) } ?? "none")")
         }
         return false
     }
@@ -4813,7 +4884,7 @@ class ExplorerTests: XCTestCase {
         lastTypeFailure = ""
         guard focusForTyping(element) else {
             let f = element.frame
-            lastTypeFailure = "‘\(fieldDesc(element))’ was found (frame \(Int(f.minX)),\(Int(f.minY)) \(Int(f.width))×\(Int(f.height))) but never took keyboard focus after 3 taps"
+            lastTypeFailure = "‘\(fieldDesc(element))’ was found (frame \(Int(f.minX)),\(Int(f.minY)) \(Int(f.width))×\(Int(f.height))) but never took keyboard focus, including after dismissing the keyboard and scrolling it into view"
                 + (app.keyboards.count == 0 ? " — no keyboard appeared" : "")
                 + (focusedField().map { " — focus is on ‘\(fieldDesc($0))’" } ?? "")
             print("OCQA_STATE:type_focus_failed detail=\(escapeJSON(lastTypeFailure))")

package/bin/tapp.js

@@ -283,6 +283,7 @@ function safeCommandUsage(verb) {
     app: "tapp app [repo] [--no-open] [--port PORT]",
     report: "tapp report [captureId|latest]",
     feedback: "tapp feedback \"short title\" [--body TEXT|--body-file FILE] [--type bug|idea|question] [--capture ID|latest|none] [--as human] [--submit] [--json]\n  Drafts a public GitHub issue on aarwitz/tapp about tapp itself; --submit files it with the authenticated gh CLI.\n  Exit codes: 0 drafted or filed · 1 gh submission failed · 2 usage error",
+    audit: "tapp audit <url> [--json] [--device NAME] [--viewport WxH]\n  Read-only: renders the page and reads the tree, never clicks — safe to point at production.\n  Exit codes: 0 no dead controls · 1 dead controls found · 2 usage/infrastructure",
     doctor: "tapp doctor [--json]\n  Exit codes: 0 environment healthy · 1 blocked (fix ❌ items)",
     install: "tapp install",
     mcp: "tapp mcp",
@@ -302,7 +303,7 @@ if (["--help", "-h"].includes(command)) {
 const knownCommands = new Set([
   "help", "version", "--version", "-v", "mcp", "init", "focus", "explore", "qa", "open",
   "tree", "shot", "screenshot", "apps", "build", "flow", "task", "contract", "scenario", "map",
-  "pr", "plan", "baseline", "ci", "actor", "app", "studio", "report", "doctor", "install", "feedback",
+  "pr", "plan", "baseline", "ci", "actor", "app", "studio", "report", "doctor", "install", "feedback", "audit",
 ]);
 if (!knownCommands.has(command)) {
   console.error(`❌ Unknown command: ${command}`);
@@ -1150,9 +1151,48 @@ switch (command) {
       break;
     }
     if (!["run", "validate"].includes(verb) || !flowPath) {
-      console.error("usage: tapp flow example\n       tapp flow steps [--json]\n       tapp flow run <flow.yml> [--platform ios|android|web] [--actor NAME] [--email VALUE] [--password VALUE] [--url URL] [--app-id ID] [--apk FILE] [--serial ID]\n       tapp flow validate <flow.yml>");
+      console.error("usage: tapp flow example\n       tapp flow steps [--json]\n       tapp flow run <flow.yml|glob> [...more] [--platform ios|android|web] [--actor NAME] [--email VALUE] [--password VALUE] [--url URL] [--app-id ID] [--apk FILE] [--serial ID]\n       tapp flow validate <flow.yml|glob> [...more]\n       Several Flows (or a glob) run in sequence and print one line per Flow; exit 1 if any failed.");
       process.exit(2);
     }
+    // Several Flows in one command (field issue #9): the shell usually expands the glob, but a
+    // quoted pattern arrives whole. Everyone writes this loop by hand otherwise.
+    const expandFlowPattern = (pattern) => {
+      if (!/[*?]/.test(pattern)) return [pattern];
+      const dir = path.dirname(pattern);
+      const rx = new RegExp(`^${path.basename(pattern).replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
+      try {
+        return fs.readdirSync(dir).filter((name) => rx.test(name)).sort().map((name) => path.join(dir, name));
+      } catch { return []; }
+    };
+    const flowPaths = positionals.slice(1).flatMap(expandFlowPattern);
+    if (flowPaths.length > 1) {
+      const passThrough = Object.entries(flags).flatMap(([key, value]) =>
+        value === true ? [`--${key}`] : typeof value === "string" ? [`--${key}`, value] : []);
+      const rows = [];
+      for (const candidate of flowPaths) {
+        const name = path.basename(candidate).replace(/\.(ya?ml|json)$/i, "");
+        process.stderr.write(`▶️  ${name}\n`);
+        const child = spawnSync(process.execPath, [path.join(packageRoot, "bin", "tapp.js"), "flow", verb, candidate, ...passThrough], { encoding: "utf8", env: process.env });
+        const output = `${child.stdout || ""}\n${child.stderr || ""}`;
+        // Prefer the cause tapp already distilled; never the last line of a boxed error (#23).
+        const lines = output.split("\n");
+        const errorAt = lines.findIndex((line) => line.trim().startsWith("❌"));
+        // A validation error puts its reasons on the bullet lines under the ❌ headline; a
+        // headline alone ("Invalid web Flow — b-bad:") names no cause.
+        const headline = errorAt >= 0
+          ? [lines[errorAt], ...(/[:：]\s*$/.test(lines[errorAt]) ? [lines[errorAt + 1] || ""] : [])].map((line) => line.trim()).filter(Boolean).join(" ")
+          : "";
+        const cause = (output.match(/^\s*(?:\*\*)?First failure:.*$/m)?.[0] || headline || "")
+          .replace(/\*\*/g, "").replace(/\s+/g, " ").trim().slice(0, 160);
+        rows.push({ name, ok: (child.status ?? 1) === 0, cause });
+      }
+      const width = Math.max(...rows.map((row) => row.name.length));
+      console.log("");
+      for (const row of rows) console.log(`${row.name.padEnd(width)}  ${row.ok ? "PASS" : "FAIL"}${row.ok || !row.cause ? "" : `  ${row.cause}`}`);
+      const failed = rows.filter((row) => !row.ok).length;
+      console.log(`\n${rows.length - failed}/${rows.length} ${verb === "validate" ? "valid" : "passed"}`);
+      process.exit(failed ? 1 : 0);
+    }
     const absolute = path.resolve(flowPath);
     if (!fs.existsSync(absolute)) {
       console.error(`❌ Flow not found: ${absolute}`);
@@ -1463,6 +1503,38 @@ switch (command) {
     process.exit(2);
   }
 
+  case "audit": {
+    const { flags, positionals } = parseVerbArgs(rest);
+    const url = positionals[0] || "";
+    if (!/^https?:\/\//i.test(url)) {
+      console.error("usage: tapp audit <http(s) url> [--json] [--device NAME] [--viewport WxH]\n       Read-only structural audit: never clicks, safe against production.");
+      process.exit(2);
+    }
+    try {
+      const { auditWebPage } = await import(path.join(packageRoot, "mcp-server", "src", "web-explorer.js"));
+      const result = await auditWebPage({
+        url,
+        device: typeof flags.device === "string" ? flags.device : "",
+        viewport: typeof flags.viewport === "string" ? flags.viewport : "",
+      });
+      if (flags.json === true) {
+        console.log(JSON.stringify({ kind: "tapp-structural-audit", readOnly: true, ...result }, null, 2));
+      } else {
+        console.log(`🔎 Structural audit — ${result.url}\n   ${result.controlsExamined} control(s) examined · nothing was clicked`);
+        if (!result.findings.length) console.log("\n✅ No structurally dead controls found.");
+        else {
+          console.log("");
+          for (const finding of result.findings) console.log(`  ⚠️  ${finding.title}`);
+          console.log(`\n${result.findings.length} dead control(s). These are controls no Flow would cover — nobody writes a test for a button they believe does nothing.`);
+        }
+      }
+      process.exit(result.findings.length ? 1 : 0);
+    } catch (error) {
+      console.error(`❌ ${error.message || String(error)}`);
+      process.exit(2);
+    }
+  }
+
   case "doctor": {
     const { flags: doctorFlags } = parseVerbArgs(rest);
     const jsonMode = doctorFlags.json === true;
@@ -1541,14 +1613,29 @@ switch (command) {
 
     try {
       const { chromium } = await import("playwright");
+      // Launch for real rather than stat the path executablePath() reports.
+      // They are not the same question: web Flows launch headless, Playwright
+      // may serve that from a separate binary, and executablePath() answers
+      // for the full browser either way — so a stat can say Web is ready while
+      // every launch fails on a binary nobody was asked to install. Whatever a
+      // future Playwright resolves headless to, opening and closing one is the
+      // only answer that stays true.
       let executable = "";
-      try { executable = chromium.executablePath(); } catch { /* report the missing browser below */ }
-      if (executable && fs.existsSync(executable)) {
+      try { executable = chromium.executablePath(); } catch { /* the launch below is the real check */ }
+      let launchError = "";
+      try {
+        const probe = await chromium.launch({ headless: true });
+        await probe.close();
+      } catch (error) {
+        launchError = String(error?.message || error).split("\n").find((line) => line.trim()) || "";
+      }
+      if (!launchError) {
         report.platforms.web = { available: true, chromium: executable };
-        sayOk("Web", `Playwright + Chromium (${executable})`);
+        sayOk("Web", `Playwright + Chromium${executable ? ` (${executable})` : ""}`);
       } else {
-        report.platforms.web = { available: false, reason: "Chromium browser missing (run: npx playwright install chromium)" };
+        report.platforms.web = { available: false, reason: "Chromium browser missing (run: npx playwright install chromium)", detail: launchError };
         say("  ⬜ Web — Playwright installed; Chromium browser missing (run: npx playwright install chromium)");
+        say(`     ${launchError}`);
       }
     } catch {
       report.platforms.web = { available: false, reason: "Playwright not installed" };
@@ -1951,6 +2038,9 @@ Primitives — an agent's eyes and hands:
                            (web: --tap TEXT · --wait-for TEXT · --out FILE)
   tapp tree [target]       Accessibility tree of the current screen (--json for every element)
                            (web: --tap TEXT · --wait-for TEXT)
+  tapp audit <url>         Read-only structural audit — dead anchors, placeholder links, buttons
+                           with nothing behind them. Never clicks, so it is safe against
+                           production (exit 1 when dead controls are found)
 
 Repository & release:
   tapp init [repo]         Detect targets and write the application model + reviewable release plan

package/mcp-server/src/index.js

@@ -471,10 +471,26 @@ export async function prepareAndroidInteractiveTarget({ projectDir = process.cwd
   return { ...built, appId, selectedTarget:selected };
 }
 
-export async function installAppOnBootedSim(appPath, { cleanInstall = true } = {}) {
+// Said before a build overwrites whatever is on the simulator. The clean install
+// below wipes the old app's data with it, so a build someone deliberately
+// configured — pointed at a local server, a staging key, a test account —
+// disappears without being mentioned. Naming it is the difference between "my run
+// is slow" and "my run is now testing something else entirely". Passing a bundle
+// id instead of a project path uses what is installed and never builds.
+export function replacingInstalledBuildNotice(bundleId) {
+  const id = String(bundleId || "").trim();
+  if (!id) return "";
+  return `Replacing the installed build of ${id} (its data is wiped too). To use what is already installed instead of building, pass the bundle id: ${id}`;
+}
+
+export async function installAppOnBootedSim(appPath, { cleanInstall = true, onStatus = () => {} } = {}) {
   const bid = await runCommand("/usr/libexec/PlistBuddy", ["-c", "Print CFBundleIdentifier", path.join(appPath, "Info.plist")], { timeoutMs: 30_000 });
   const bundleId = (bid.stdout || "").trim();
   if (!bundleId) return { error: `Could not read CFBundleIdentifier from ${appPath}/Info.plist — is this a simulator .app build?` };
+  if (cleanInstall) {
+    const existing = await runCommand("xcrun", ["simctl", "get_app_container", "booted", bundleId, "app"], { timeoutMs: 15_000 });
+    if (existing.code === 0 && (existing.stdout || "").trim()) onStatus(replacingInstalledBuildNotice(bundleId));
+  }
   if (cleanInstall) {
     // Clean install: stale keychain items from a previous install leave apps half-signed-in
     // (Firebase Auth's "error accessing the keychain") — uninstall first for a fresh state.
@@ -496,7 +512,7 @@ export async function resolveAppTarget(input, { cwd = process.cwd(), onStatus =
     const sim = await ensureBootedSim({ autoBoot: true });
     if (sim.error) return { error: sim.error };
     onStatus(`Installing ${path.basename(appPath)}…`);
-    const inst = await installAppOnBootedSim(appPath);
+    const inst = await installAppOnBootedSim(appPath, { onStatus });
     if (inst.error) return inst;
     return {
       bundleId: inst.bundleId,
@@ -522,7 +538,7 @@ export async function resolveAppTarget(input, { cwd = process.cwd(), onStatus =
     const built = await buildAppForSim({ container, scheme, configuration });
     if (built.error) return built;
     onStatus(`Built ${path.basename(built.appPath)} (scheme ${built.scheme}) — installing…`);
-    const inst = await installAppOnBootedSim(built.appPath);
+    const inst = await installAppOnBootedSim(built.appPath, { onStatus });
     if (inst.error) return inst;
     return {
       bundleId: inst.bundleId,
@@ -917,7 +933,7 @@ const SESSION_ACT_ARGS = Object.freeze({
   login: "{email?, password?} (defaults to the session's credentials)",
   swipe: "{direction: up|down|left|right}",
   back: "{}",
-  tree: "{verbose?: true}",
+  tree: "{verbose?: true} — verbose returns every element and the complete control list",
   screenshot: "{label?}",
 });
 export function sessionActUsageError(cmd = {}) {
@@ -1769,13 +1785,15 @@ function elementBreakdown(elements) {
 }
 
 /** Scannable "Read screen X — N elements (...)" readout, plus the tappable/typeable controls. */
-export function formatScreen(screenTitle, elements) {
+export function formatScreen(screenTitle, elements, { full = false } = {}) {
   const els = elements || [];
   const interactable = els.filter((e) => e.isEnabled !== false && (String(e.type).includes("Button") || String(e.type).includes("Link") || String(e.type).includes("rawValue: 9") || String(e.type).includes("TextField") || String(e.type).includes("rawValue: 49") || String(e.type).includes("rawValue: 50") || String(e.type).includes("Cell") || String(e.type).includes("rawValue: 75")));
   const allLabels = interactable
     .map((e) => (e.label || e.identifier || "").trim())
     .filter((s) => s && s.length <= 40 && !s.includes("."));
-  const labels = allLabels.slice(0, 8);
+  // A verbose/full readout must actually be full: the 8-item cap hid the fifth tab's label
+  // and left tapping by coordinate as the only way to reach it (field issue #9).
+  const labels = full ? allLabels : allLabels.slice(0, 8);
   const L = [`🌳 Read screen **${screenTitle || "Unknown"}** — ${els.length} elements (${elementBreakdown(els)})`];
   // A silently cut list reads as complete; say when it isn't.
   if (labels.length) L.push("", "**Controls:** " + labels.map((l) => `\`${l}\``).join(" · ")
@@ -4523,8 +4541,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const detailNote = !ok && r.detail ? ` — ${r.detail}` : "";
     const head = `${did} — ${ok ? "ok" : `⚠️ ${r.status}${detailNote}`} → now on **${r.screenTitle || "Unknown"}**`;
     const rec = typeof r.recordedSteps === "number" ? `\n\n🔴 Recording — ${r.recordedSteps} step(s). \`tapp_flow_save\` to keep it as a test.` : "";
-    const screen = agentScreenProjection(r, { full: action === "tree" && args.full === true });
-    const result = richResult(head + "\n\n" + formatScreen(screen.screenTitle, screen.elements) + rec, { ...r, ...screen });
+    // `verbose` is the documented spelling (SESSION_ACT_ARGS.tree); `full` is the original.
+    // Accepting only `full` meant the documented flag silently did nothing (field issue #9).
+    const fullTree = action === "tree" && (args.full === true || args.verbose === true || cmd.verbose === true || cmd.full === true);
+    const screen = agentScreenProjection(r, { full: fullTree });
+    const result = richResult(head + "\n\n" + formatScreen(screen.screenTitle, screen.elements, { full: fullTree }) + rec, { ...r, ...screen });
     if (!ok) result.isError = true;
     return result;
   }

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

@@ -139,6 +139,11 @@ function cssAttrEscape(value) {
 async function installWebListenerTracking(context) {
   await context.addInitScript(() => {
     const key = Symbol.for("tapp.clickListeners");
+    // Delegated handlers live on document/window, not on the control, so an
+    // element-only record says "nothing is listening" for a page where every
+    // button works. Keep their source text: it is the only way to tell which
+    // controls such a handler actually claims.
+    const delegatedKey = Symbol.for("tapp.delegatedClickHandlers");
     const add = EventTarget.prototype.addEventListener;
     const remove = EventTarget.prototype.removeEventListener;
     EventTarget.prototype.addEventListener = function tappTrackedAdd(type, listener, options) {
@@ -146,6 +151,11 @@ async function installWebListenerTracking(context) {
         if (!this[key]) Object.defineProperty(this, key, { value: new Set(), configurable: true });
         this[key].add(listener);
       }
+      if (type === "click" && listener && (this === document || this === window)) {
+        const target = this === window ? window : document;
+        if (!target[delegatedKey]) Object.defineProperty(target, delegatedKey, { value: new Set(), configurable: true });
+        try { target[delegatedKey].add(String(listener).slice(0, 4000)); } catch { /* exotic handler */ }
+      }
       return add.call(this, type, listener, options);
     };
     EventTarget.prototype.removeEventListener = function tappTrackedRemove(type, listener, options) {
@@ -1175,3 +1185,149 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
   }
   return { markersPath, outDir, actions, screens: screenCount, seedRoutes: normalizedSeeds, seedTargets: normalizedTargets };
 }
+
+// ---- Read-only structural audit (field issue #24) -------------------------------------
+// Flows hold known-good behaviour fixed; they cannot find a control that was NEVER alive,
+// because nobody writes a flow for a button they believe does nothing. This pass renders the
+// page and reads the tree — it never clicks — so it is the one analysis that can be pointed
+// at production, which is where dead controls actually live.
+export function auditFindingsFromControls(controls = []) {
+  const findings = [];
+  for (const control of controls) {
+    const where = control.label || control.identifier || control.selector || "(unlabelled)";
+    if (control.kind === "dead_anchor") {
+      findings.push({ type: "anchor_missing", severity: "medium",
+        title: `In-page link “${where}” points at #${control.fragment}, which is not on the page`, target: control.href });
+    } else if (control.kind === "placeholder_link") {
+      findings.push({ type: "placeholder_link", severity: "medium",
+        title: `Link “${where}” has no destination (href="${control.href}")`, target: control.href });
+    } else if (control.kind === "dangling_aria_controls") {
+      findings.push({ type: "dangling_aria_controls", severity: "medium",
+        title: `“${where}” declares aria-controls="${control.controls}", but no such element exists`, target: control.controls });
+    } else if (control.kind === "unwired_control") {
+      findings.push({ type: "unwired_control", severity: "medium",
+        title: `Button “${where}” has no click handler, form, or link behind it`, target: control.selector });
+    }
+  }
+  return findings;
+}
+
+// Collected inside the page: every structurally dead control, WITHOUT interacting with any.
+export async function auditWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, device = "", viewport = "" }) {
+  let target;
+  try { target = new URL(url); }
+  catch { throw new Error("Audit needs a valid http(s) URL"); }
+  if (!/^https?:$/.test(target.protocol)) throw new Error("Audit needs a valid http(s) URL");
+  const { chromium, devices } = await loadPlaywright();
+  const browser = await chromium.launch(webBrowserLaunchOptions(process.env, {}));
+  try {
+    const context = await browser.newContext(webContextOptions({ device, viewport, devices }));
+    await installWebListenerTracking(context);
+    const page = await context.newPage();
+    const bounded = Math.max(1000, Math.min(60_000, Number(timeoutMs) || NAV_TIMEOUT_MS));
+    page.setDefaultTimeout(bounded);
+    const response = await page.goto(target.href, { waitUntil: "domcontentloaded", timeout: bounded });
+    if (response && response.status() >= 400) throw new Error(`Could not open ${target.href}: HTTP ${response.status()}`);
+    await waitForWebStability(page, { timeoutMs: Math.min(5_000, bounded) });
+    const controls = await page.evaluate(() => {
+      const key = Symbol.for("tapp.clickListeners");
+      const visible = (el) => {
+        const style = window.getComputedStyle(el);
+        return style.visibility !== "hidden" && style.display !== "none" && el.getClientRects().length > 0;
+      };
+      const name = (el) => (el.getAttribute("aria-label") || el.textContent || el.getAttribute("value") || "").replace(/\s+/g, " ").trim().slice(0, 80);
+      const selectorFor = (el) => el.id ? `#${el.id}` : el.getAttribute("data-testid") ? `[data-testid="${el.getAttribute("data-testid")}"]` : el.tagName.toLowerCase();
+      // Some controls are wired in CSS, not JavaScript: a menu that opens while
+      // its trigger is hovered or focused has no listener to find, and calling
+      // it dead is wrong. Collect the selectors that some rule reacts to — the
+      // trigger side of any `X:hover Y` / `X:focus-within Y` rule whose
+      // declarations change whether Y can be seen. A rule that only restyles
+      // the trigger itself (`button:hover { background: … }`) is not behaviour
+      // and is ignored, which is why the descendant part must be present.
+      const REVEALS = /(^|;)\s*(display|visibility|opacity|height|max-height|transform|pointer-events|clip-path)\s*:/i;
+      const revealTriggers = [];
+      const collectTriggers = (rules) => {
+        for (const rule of rules || []) {
+          // A plain style rule also exposes .cssRules now that CSS nesting is
+          // supported — an empty list, which is truthy. Recursing on that and
+          // skipping the rule would walk straight past every selector there is.
+          if (rule.cssRules && rule.cssRules.length) collectTriggers(rule.cssRules);
+          const selector = rule.selectorText;
+          if (!selector || !REVEALS.test(rule.style?.cssText || "")) continue;
+          for (const part of selector.split(",")) {
+            const match = part.match(/^(.*?):(?:hover|focus-within|focus-visible|focus)\b(.+)$/);
+            if (!match) continue;
+            const trigger = match[1].trim();
+            if (trigger && match[2].trim()) revealTriggers.push(trigger);
+          }
+        }
+      };
+      for (const sheet of document.styleSheets) {
+        try { collectTriggers(sheet.cssRules); } catch { /* cross-origin sheet */ }
+      }
+      const opensSomethingOnHoverOrFocus = (el) => revealTriggers.some((trigger) => {
+        try { return el.matches(trigger) || Boolean(el.closest(trigger)); } catch { return false; }
+      });
+
+      // What a delegated handler on document/window claims. The dominant idiom is
+      // `e.target.closest(SELECTOR)` / `.matches(SELECTOR)`, so pull those
+      // selectors out and test controls against them. A handler we cannot read
+      // this way (an outside-click closer, say) claims nothing and is ignored,
+      // rather than excusing every unwired control on the page.
+      const delegatedSelectors = [];
+      for (const source of [
+        ...(document[Symbol.for("tapp.delegatedClickHandlers")] || []),
+        ...(window[Symbol.for("tapp.delegatedClickHandlers")] || []),
+      ]) {
+        for (const m of String(source).matchAll(/\.(?:closest|matches)\(\s*["'`]([^"'`]+)["'`]/g)) {
+          delegatedSelectors.push(m[1]);
+        }
+      }
+      const claimedByDelegate = (el) => delegatedSelectors.some((selector) => {
+        try { return el.matches(selector) || Boolean(el.closest(selector)); } catch { return false; }
+      });
+
+      const dead = [];
+      for (const el of document.querySelectorAll("a[href], button, [role=button], [aria-controls]")) {
+        if (!visible(el)) continue;
+        const label = name(el);
+        const href = el.getAttribute("href");
+        const ariaControls = el.getAttribute("aria-controls");
+        if (ariaControls && !document.getElementById(ariaControls)) {
+          dead.push({ kind: "dangling_aria_controls", label, selector: selectorFor(el), controls: ariaControls });
+          continue;
+        }
+        if (href != null) {
+          if (href === "#" || href.trim() === "" || /^javascript:\s*(void\(0\))?;?$/i.test(href)) {
+            dead.push({ kind: "placeholder_link", label, selector: selectorFor(el), href });
+          } else if (href.startsWith("#")) {
+            const fragment = decodeURIComponent(href.slice(1));
+            const found = fragment && (document.getElementById(fragment) || document.getElementsByName(fragment).length > 0);
+            if (!found) dead.push({ kind: "dead_anchor", label, selector: selectorFor(el), href, fragment });
+          }
+          continue;
+        }
+        // A button with nothing behind it: no listener on itself or an ancestor, no inline
+        // handler, and not a submit inside a form.
+        let wired = false;
+        for (let node = el; node && node !== document.body; node = node.parentElement) {
+          if ((node[key] && node[key].size > 0) || typeof node.onclick === "function" || node.hasAttribute("onclick")) { wired = true; break; }
+        }
+        if (!wired && el.matches("button[type=submit], input[type=submit]") && el.closest("form")) wired = true;
+        if (!wired && el.closest("label")) wired = true; // a label drives its own control
+        if (!wired && opensSomethingOnHoverOrFocus(el)) wired = true;
+        if (!wired && claimedByDelegate(el)) wired = true;
+        if (!wired) dead.push({ kind: "unwired_control", label, selector: selectorFor(el) });
+      }
+      return { dead, controlCount: document.querySelectorAll("a[href], button, [role=button]").length, title: document.title };
+    });
+    return {
+      url: page.url(),
+      title: controls.title,
+      controlsExamined: controls.controlCount,
+      findings: auditFindingsFromControls(controls.dead),
+    };
+  } finally {
+    await browser.close().catch(() => {});
+  }
+}

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

@@ -10,9 +10,13 @@ const DEFAULT_TIMEOUT = 6000;
 // What WAS visible when a wait missed — points a failure report at the fix (renamed label,
 // error state, wrong page) without a separate `tapp tree` run (field issue #20).
 async function visibleLabelsHint(page, limit = 8) {
+  const collect = async (scope) => {
+    try { return String(await scope.locator("body").innerText({ timeout: 1000 })); } catch { return ""; }
+  };
   try {
-    const text = await page.locator("body").innerText({ timeout: 1000 });
-    const labels = [...new Set(String(text).split(/\n+/).map((l) => l.trim()).filter((l) => l.length >= 2 && l.length <= 60))].slice(0, limit);
+    // Include same-origin frames: the text a reader can see may live inside an embedded modal.
+    const texts = [await collect(page), ...(await Promise.all(sameOriginFrames(page).map(collect)))];
+    const labels = [...new Set(texts.join("\n").split(/\n+/).map((l) => l.trim()).filter((l) => l.length >= 2 && l.length <= 60))].slice(0, limit);
     return labels.length ? ` — visible: ${labels.join(" · ")}` : "";
   } catch { return ""; }
 }
@@ -31,19 +35,49 @@ function cssId(value) {
   return "#" + String(value).replace(/([^a-zA-Z0-9_-])/g, "\\$1");
 }
 
-export async function locateWebElement(page, target) {
+// A frame whose content the page's own origin may script. An `about:blank`/`srcdoc` frame
+// inherits its parent's origin. Cross-origin frames (third-party widgets) stay out of scope:
+// a Flow should not assert on content the page itself cannot read.
+function sameOriginFrames(page) {
+  if (typeof page.frames !== "function") return []; // non-Playwright page (tests, fakes)
+  let origin;
+  try { origin = new URL(page.url()).origin; } catch { return []; }
+  const main = typeof page.mainFrame === "function" ? page.mainFrame() : null;
+  return page.frames().filter((frame) => {
+    if (frame === main) return false;
+    const url = frame.url() || "";
+    if (!url || url === "about:blank" || url.startsWith("about:srcdoc")) return true;
+    try { return new URL(url).origin === origin; } catch { return false; }
+  });
+}
+
+function targetCandidates(scope, target) {
   const exact = { exact: true };
-  const candidates = [
-    page.getByTestId(target),
-    page.locator(cssId(target)),
-    page.getByLabel(target, exact),
-    page.getByRole("button", { name: target, exact: true }),
-    page.getByRole("link", { name: target, exact: true }),
-    page.getByText(target, exact),
-    page.getByLabel(target),
-    page.getByText(target),
+  return [
+    scope.getByTestId(target),
+    scope.locator(cssId(target)),
+    scope.getByLabel(target, exact),
+    scope.getByRole("button", { name: target, exact: true }),
+    scope.getByRole("link", { name: target, exact: true }),
+    scope.getByText(target, exact),
+    scope.getByLabel(target),
+    scope.getByText(target),
   ];
-  return firstVisible(candidates);
+}
+
+export async function locateWebElement(page, target) {
+  const top = await firstVisible(targetCandidates(page, target));
+  if (top) return top;
+  // A modal rendered into a same-origin <iframe> is visibly on screen but invisible to a
+  // top-document-only search, so `wait_for` timed out on text the screenshot plainly showed
+  // (field issue #14). Top document first, then each same-origin frame in document order.
+  for (const frame of sameOriginFrames(page)) {
+    try {
+      const inFrame = await firstVisible(targetCandidates(frame, target));
+      if (inFrame) return inFrame;
+    } catch { /* a frame can detach mid-search — keep looking */ }
+  }
+  return null;
 }
 
 async function screenCandidates(page) {
@@ -125,6 +159,21 @@ export async function runWebRequestStep({ step, startUrl, vars = {}, timeout = D
   return { action: "request", target: `${method} ${targetUrl.pathname}`, status: "pass", detail: "" };
 }
 
+// Playwright (and its install prompt) wrap guidance in box-drawing art spanning many lines.
+// Consumers that keep ONE line of an error — a scoreboard row, a CI table — kept the box's
+// bottom border `╚═══╝` and threw the cause away (field issue #23). Put the cause first and
+// carry any actionable instruction with it, so the first AND last line are both useful.
+export function distillErrorMessage(message) {
+  const lines = String(message || "").split("\n")
+    .map((line) => line.replace(/[╔╗╚╝═║│┌┐└┘─]/g, " ").trim())
+    .filter(Boolean);
+  if (!lines.length) return String(message || "").trim();
+  const headline = lines[0];
+  // A boxed Playwright prompt carries the fix as a bare command line inside the art.
+  const fix = lines.slice(1).find((line) => /^(npx|npm|pip3?|python3|yarn|pnpm) /.test(line));
+  return fix && !headline.includes(fix) ? `${headline} — fix: ${fix}` : headline;
+}
+
 // Playwright's timeout errors bury the actual cause ("<div id=…> intercepts pointer events",
 // "element is not visible") in a multi-line retry log; single-line consumers kept only
 // "Timeout 6000ms exceeded" and the report read like the element did not exist (field issue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.13",
+  "version": "0.17.16",
   "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-web-flow.js

@@ -3,8 +3,9 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { loadFlowFile } from "../mcp-server/src/flow-runtime.js";
-import { runWebFlow } from "../mcp-server/src/web-flow.js";
+import fs from "node:fs";
+import { FlowLog, loadFlowFile } from "../mcp-server/src/flow-runtime.js";
+import { distillErrorMessage, runWebFlow } from "../mcp-server/src/web-flow.js";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const flowPath = process.argv[2];
@@ -30,6 +31,16 @@ try {
   process.stdout.write((report.stdout || "").trim() + "\n");
   process.exit(result.passed ? 0 : 1);
 } catch (error) {
-  console.error(`❌ ${error.message || error}`);
+  // A run that dies before step 1 (no browser installed, bad url) still owes a structured
+  // report: without one the scoreboard shows an empty row and consumers keep whatever text
+  // line they can reach — for a boxed Playwright prompt, its bottom border (field issue #23).
+  const cause = distillErrorMessage(error?.message || String(error));
+  console.error(`❌ ${cause}`);
+  try {
+    fs.rmSync(logPath, { force: true });
+    const log = new FlowLog({ logPath, flow });
+    log.step({ index: 1, action: "harness", target: flow.name || "flow", status: "fail", detail: cause });
+    log.finish({ abortReason: cause });
+  } catch { /* the console line above is still the answer */ }
   process.exit(2);
 }

package/skills/tapp/references/commands.md

@@ -11,6 +11,7 @@ npx -y @aarwitz/tapp@latest explore [target]
 npx -y @aarwitz/tapp@latest focus "Save storefront settings visible above keyboard" [target]
 npx -y @aarwitz/tapp@latest open [target]
 npx -y @aarwitz/tapp@latest tree [target] --json
+npx -y @aarwitz/tapp@latest audit https://example.com --json   # read-only: never clicks, safe against production
 npx -y @aarwitz/tapp@latest shot
 npx -y @aarwitz/tapp@latest report latest
 npx -y @aarwitz/tapp@latest doctor