@aarwitz/tapp 0.17.0 → 0.17.2

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

package/AGENTS.md

@@ -7,13 +7,13 @@ repository-connected deterministic gate.
 ## No MCP connected? Just run the CLI
 
 The core inspect, explore, replay, and gate capabilities work as plain commands — no Tapp account,
-server, or global install. `[target]` is
-optional: with nothing, tapp finds + builds the Xcode project in the cwd (or falls back to
-the app already on the simulator); it also accepts a repo dir, a `path/to/App.app`, a
-bundle id, or (web) an http(s) URL. You never need to know a bundle id up front.
+server, or global install. `[target]` is optional: with a repository/model, Tapp selects and prepares
+one conclusive web, iOS, or Android target; it also accepts a repo dir, `path/to/App.app`, bundle id,
+APK plus app id, or an owned HTTP(S) URL. You never need to know an iOS bundle id up front.
 
 ```bash
 npx -y @aarwitz/tapp@latest explore [target]     # autonomous exploration → findings + evidence (observation, not a gate; ≈ tapp_explore)
+npx -y @aarwitz/tapp@latest focus "SCREEN OR CONTROL" [target] # source-locate + shortest observed route + screenshot
 npx -y @aarwitz/tapp@latest explore https://your-app.example --watch  # web: visibly follow the same exploration
 npx -y @aarwitz/tapp@latest open [target]   # launch + screen summary + screenshot saved to a file (≈ tapp_open_app)
 npx -y @aarwitz/tapp@latest tree [target]   # accessibility tree, --json for every element (≈ tapp_ui_tree)
@@ -60,6 +60,7 @@ installs, returns the bundle id) → `tapp_explore {appBundleId}`.
 | The user wants… | Use | NOT |
 |---|---|---|
 | "Show me / screenshot a screen" | `tapp_open_app` (launch + screenshot + tree, ~15s) | `tapp_explore` (a full multi-minute exploration) |
+| "Find/reach this named screen or control" | `tapp_session_start` with `focus`, or `tapp_focus`; plain CLI: `tapp focus` | screenshot-by-screenshot wandering |
 | "Tap through / drive / fill a form / log in" | `tapp_session_start` → `session_act` loop | repeated `open_app` calls (cold relaunch each time) |
 | "Is my app broken? Find bugs" | `tapp_explore` — `appBundleId` for iOS, `androidAppId` for Android, `url` for owned web apps; returns an observation (findings + evidence), not a ship verdict — gate a merge with the CI gate (`tapp ci` CLI / the GitHub Action) + a contract | a manual session (exploration is autonomous) |
 | "Make this flow a repeatable test" | drive it in a session, then `tapp_flow_save`; replay with `tapp_flow_run` | re-driving it by hand every time |
@@ -67,8 +68,16 @@ installs, returns the bundle id) → `tapp_explore {appBundleId}`.
 
 ## Session driving (the Playwright loop)
 
+After an initial grounding exploration, use the source-connected fast path for any named
+destination. Tapp searches the repository, matches the requested surface to `.tapp/ui-map.json`, and executes only the shortest
+runtime-observed route. Source tells Tapp where intent lives; observed UI evidence authorizes taps.
+If it returns source evidence without a route, inspect the cited file/navigation source—do not
+wander blindly or invent a route. URL-only targets correctly have no source advantage.
+
 ```
-tapp_session_start { appBundleId: "com.acme.app" }     → fresh launch + initial tree
+tapp_session_start { appBundleId: "com.acme.app", focus: "Save storefront settings visible above keyboard", projectDir: "." }
+tapp_session_start { focus: "Storefront Settings", projectDir: "." } → managed web target from the workspace
+tapp_focus         { query: "Save storefront settings visible above keyboard" } → one-call shortest observed route
 tapp_session_act   { action: "login", email: "qa@x.com", password: "…" } → atomic fill + submit + verify
 tapp_session_act   { action: "tap",  id: "Email" }      → tap by a11y id OR visible label
 tapp_session_act   { action: "type", text: "qa@x.com" } → types into the focused field
@@ -144,7 +153,8 @@ without a coding agent, model, subscription, or API key. AI generation and `asse
 ## Setup facts (tell the user when relevant)
 
 - iOS runs locally on a Mac with Xcode + a simulator. Android needs `adb` and a connected
-  emulator/device. Web needs Playwright + Chromium. `tapp doctor` reports each capability.
+  emulator/device; source builds also need JDK 17, while prebuilt APK testing does not. Web needs
+  Playwright + Chromium. `tapp doctor` reports each capability separately.
 - First tool call builds the test harness once (~2 min, cached in `~/.tapp`). `tapp install`
   prebuilds it. Switching simulators triggers an automatic rebuild.
 - The app under test must be **installed on the booted simulator** (`tapp_install_app` builds

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -82,6 +82,31 @@ class ExplorerTests: XCTestCase {
         return fallback
     }
 
+    /// Opens the visual-evidence boundary only after the target app is foregrounded and its first
+    /// UI has settled. The host starts simulator recording (and clients may reveal a live preview)
+    /// at this point, then acknowledges it. The wait is deliberately bounded: video/preview
+    /// failure must never prevent the actual exploration from running.
+    private func signalSettledVisualReady() {
+        let readyPath = resolve("OCQA_VISUAL_READY_PATH")
+        guard !readyPath.isEmpty else { return }
+        let readyURL = URL(fileURLWithPath: readyPath)
+        try? FileManager.default.createDirectory(at: readyURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+        try? Data("ready\n".utf8).write(to: readyURL, options: .atomic)
+        print("OCQA_STATE:visual_ready")
+
+        let startedPath = resolve("OCQA_RECORDING_STARTED_PATH")
+        guard !startedPath.isEmpty else { return }
+        let deadline = Date().addingTimeInterval(5.0)
+        while Date() < deadline && !FileManager.default.fileExists(atPath: startedPath) {
+            Thread.sleep(forTimeInterval: 0.05)
+        }
+        if FileManager.default.fileExists(atPath: startedPath) {
+            print("OCQA_STATE:visual_capture_started")
+        } else {
+            print("OCQA_STATE:visual_capture_ack_timeout")
+        }
+    }
+
     private func loadConfig() {
         // OCQA_CONFIG_PATH (forwarded from the host via TEST_RUNNER_OCQA_CONFIG_PATH) is
         // authoritative and per-run — checked FIRST so each device reads its own config and
@@ -585,14 +610,34 @@ class ExplorerTests: XCTestCase {
     /// the password it just typed.
     private func sessionLogin(email: String, password: String) -> (status: String, detail: String) {
         waitForUIStability(timeout: 2.0)
-        let textFields = app.textFields.allElementsBoundByIndex.filter { $0.exists && $0.frame.width > 0 }
-        let secureFields = app.secureTextFields.allElementsBoundByIndex.filter { $0.exists && $0.frame.width > 0 }
-        let emailField = textFields.first { f in
-            let hint = (f.identifier + " " + (f.placeholderValue ?? "") + " " + f.label).lowercased()
-            return hint.contains("email") || hint.contains("e-mail") || hint.contains("user")
-        } ?? (secureFields.isEmpty ? nil : textFields.first)
+        // A recorded Flow invokes login immediately after a cold launch, while a human-driven
+        // session naturally invokes it after inspecting the first tree. Poll the SAME finder for
+        // a bounded interval so those two entry paths behave identically when login fields appear
+        // after an asynchronous launch transition.
+        var textFields: [XCUIElement] = []
+        var secureFields: [XCUIElement] = []
+        var emailField: XCUIElement?
+        var passwordField: XCUIElement?
+        let fieldsDeadline = Date().addingTimeInterval(8.0)
+        repeat {
+            textFields = app.textFields.allElementsBoundByIndex.filter { $0.exists && $0.frame.width > 0 }
+            secureFields = app.secureTextFields.allElementsBoundByIndex.filter { $0.exists && $0.frame.width > 0 }
+            let plainPasswordIndex = textFields.firstIndex { f in
+                let hint = (f.identifier + " " + (f.placeholderValue ?? "") + " " + f.label).lowercased()
+                return hint.contains("password") || hint.contains("passcode")
+            }
+            passwordField = secureFields.first ?? plainPasswordIndex.map { textFields[$0] }
+            emailField = textFields.first { f in
+                let hint = (f.identifier + " " + (f.placeholderValue ?? "") + " " + f.label).lowercased()
+                return hint.contains("email") || hint.contains("e-mail") || hint.contains("user")
+            } ?? textFields.enumerated().first(where: { index, _ in
+                passwordField != nil && (plainPasswordIndex.map { index != $0 } ?? true)
+            })?.element
+            if emailField != nil && passwordField != nil { break }
+            Thread.sleep(forTimeInterval: 0.25)
+        } while Date() < fieldsDeadline
         guard let emailF = emailField else { return ("no_login_form", "no email/username field visible") }
-        guard let passF = secureFields.first else { return ("no_login_form", "no password (secure) 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)
@@ -1031,6 +1076,8 @@ class ExplorerTests: XCTestCase {
         _ = app.descendants(matching: .any).firstMatch.waitForExistence(timeout: 3)
         _ = waitForUIStability(timeout: 2.0)
 
+        signalSettledVisualReady()
+
         print("OCQA_STATE:exploration_started max_actions=\(maxActions)")
 
         let testEmail = resolve("OCQA_TEST_EMAIL")

package/README.md

@@ -9,9 +9,9 @@
 [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_MCP-000000)](cursor://anysphere.cursor-deeplink/mcp/install?name=tapp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBhYXJ3aXR6L3RhcHBAbGF0ZXN0IiwibWNwIl19)
 [![VS Code MCP](https://img.shields.io/badge/VS_Code-Install_MCP-0098FF)](https://insiders.vscode.dev/redirect/mcp/install?name=tapp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40aarwitz%2Ftapp%40latest%22%2C%22mcp%22%5D%7D)
 
-**Tapp gives coding agents hands and eyes on real iOS, Android, and web apps.** It can inspect and
-drive screens, explore for technical failures, save journeys as deterministic tests, and gate
-reviewed behavior in CI.
+**Tapp lets coding agents verify UI changes on real iOS, Android, and web surfaces, then turns
+reviewed proof into deterministic CI checks.** It can inspect and drive screens, explore for
+technical failures, and save important journeys as replayable tests.
 
 Exploration reports findings, coverage, evidence, and limits. Only the repository-connected gate
 returns `pass`, `fail`, or `inconclusive`. Tapp does not turn an autonomous crawl into a subjective
@@ -45,10 +45,11 @@ npx -y skills add aarwitz/tapp --skill tapp
 ```
 
 This installs the open Agent Skills workflow into the current project and lets the agent run the npm
-CLI directly; no MCP server, plugin, account, API key, global Tapp install, or pasted prompt block is
-required. Add `-g` for a user-wide install, or `--agent claude-code`, `--agent codex`, and similar
-selectors to constrain the clients. Start or restart the agent from the application repository and
-use the short prompt above.
+CLI directly. Inspecting, focused evidence, autonomous exploration, deterministic replay, and gating
+need no MCP server, plugin, account, API key, global Tapp install, or pasted prompt block. Add `-g`
+for a user-wide install, or `--agent claude-code`, `--agent codex`, and similar selectors to constrain
+the clients. Start or restart the agent from the application repository and use the short prompt
+above.
 
 **Claude Code — optional enhanced skill and MCP tools:**
 
@@ -57,9 +58,10 @@ claude plugin marketplace add aarwitz/tapp
 claude plugin install tapp@tapp
 ```
 
-The plugin bundles the same `tapp` Agent Skill with the matching npm-backed MCP server. Use it when
-you want inline screenshot tool results and a persistent interactive tap/read/type session; it is
-not required for the core skill-to-CLI workflow.
+The plugin bundles the same `tapp` Agent Skill with the matching npm-backed MCP server. Add it when
+you want inline screenshot results or when the agent must interactively tap, type, and record an
+arbitrary multi-step journey in one persistent session. It is not required for the core
+skill-to-CLI workflow.
 
 **No agent integration:** run the npm package directly from an app repository in one line:
 
@@ -75,22 +77,29 @@ Android and web remain available through the skill's CLI/MCP workflow.
 ```
 you:    "Add a logout button to the settings screen"
 agent:  *writes the Swift*
-agent:  *tapp: builds, opens the app, navigates to Settings, screenshots it*
+agent:  *tapp: finds Settings in source, follows its previously observed route, screenshots it*
 agent:  "Done — and here it is working on the simulator: [screenshot]"
 ```
 
 ## npm CLI quickstart
 
 Requirements: **Node ≥ 18**. iOS needs **macOS + Xcode**; Android needs `adb` plus a connected
-emulator/device; web needs Playwright + Chromium.
+emulator/device (and JDK 17 when Tapp builds source rather than installing an existing APK); web
+needs Playwright + Chromium. `tapp doctor` reports these separately.
 
-From the app repository, let the agent see the current screen and then explore it:
+From the app repository, ground Tapp once, then use the smallest operation for later checks:
 
 ```bash
-npx -y @aarwitz/tapp@latest open   # builds/launches as needed; prints a screenshot path + screen summary
-npx -y @aarwitz/tapp@latest explore     # explores the real app; prints findings + evidence (an observation, not a gate)
+npx -y @aarwitz/tapp@latest init . --explore # first run: detect/build, explore, and ground .tapp/ui-map.json
+npx -y @aarwitz/tapp@latest open            # one current screen + screenshot
+npx -y @aarwitz/tapp@latest focus "Save storefront settings visible above keyboard" # source + observed-route fast path
+npx -y @aarwitz/tapp@latest explore         # later broad exploration (observation, not a gate)
 ```
 
+Source tells `focus` where the requested UI likely lives; only a route already observed in
+`.tapp/ui-map.json` authorizes navigation. If a fresh repository has no such route yet, Tapp returns
+the source evidence instead of guessing through the app.
+
 Claude Code can read the saved image with its file-reading tool; Codex can open it with
 `view_image`. The agent should report what the screenshot proves, relay the exploration findings
 as-is (an observation, not a merge decision — `tapp ci` gates that), and link the HTML evidence
@@ -123,6 +132,9 @@ npx -y @aarwitz/tapp@latest baseline create . --platform web
 npx -y @aarwitz/tapp@latest ci install .
 ```
 
+Actor setup refuses to overwrite an existing actor. Repeat `actor set` with `--replace` only when
+you intend to replace that actor's reviewed role, session, provisioning, or credential bindings.
+
 In a repository containing multiple apps (for example, iOS plus web),
 `tapp init . --explore` without an explicit target does not guess from detection order—even when a
 prior choice is recorded. A human terminal gets a numbered
@@ -326,7 +338,7 @@ jobs:
     timeout-minutes: 45
     steps:
       - uses: actions/checkout@v4
-      - uses: aarwitz/tapp@main # pin to the newest release tag for production
+      - uses: aarwitz/tapp@v0.17.2 # or pin the reviewed release commit SHA
         with:
           project: MyApp.xcodeproj # or MyApp.xcworkspace
           scheme: MyApp
@@ -376,7 +388,7 @@ Android CI runs on Linux with an emulator/device already connected. The Action c
 or accept a prebuilt one:
 
 ```yaml
-- uses: aarwitz/tapp@main
+- uses: aarwitz/tapp@v0.17.2 # or pin the reviewed release commit SHA
   with:
     platform: android
     android-app-id: com.acme.app

package/bin/tapp.js

@@ -217,6 +217,15 @@ function printEngineError(r) {
   if (r.details && Array.isArray(r.details.errors) && r.details.errors.length) {
     console.error(r.details.errors.map((e) => "  " + e.trim()).join("\n"));
   }
+  const choices = Array.isArray(r.details?.choices) ? r.details.choices : Array.isArray(r.details?.targets) ? r.details.targets : [];
+  if (choices.length) {
+    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)}` : ""}`);
+    }
+  }
+  if (r.details?.remediation) console.error(`  Next: ${r.details.remediation}`);
 }
 
 async function promptForInitTarget(details) {
@@ -254,6 +263,7 @@ async function resolveTargetOrExit(engine, input) {
 function safeCommandUsage(verb) {
   const usage = {
     explore: "tapp explore [target] [--platform ios|android|web] [--actions N] [--timeout SEC] [--email VALUE] [--password VALUE] [--baseline FILE] [--json FILE]\n  Web: [--watch] opens Tapp's controlled browser and shows its actions\n  iOS launch configuration: [--launch-arg VALUE ...] [--launch-env '{\"KEY\":\"VALUE\"}']\n  Android: [--app-id ID] [--apk FILE] [--serial ID] [--keep-data]",
+    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]",
     tree: "tapp tree [target] [--platform ios|android|web] [--json] [--tap TEXT] [--wait-for TEXT]",
@@ -288,6 +298,16 @@ if (["--help", "-h"].includes(command)) {
   command = "help";
   rest = [];
 }
+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",
+]);
+if (!knownCommands.has(command)) {
+  console.error(`❌ Unknown command: ${command}`);
+  console.error("Run `npx -y @aarwitz/tapp@latest --help` for the command reference.");
+  process.exit(2);
+}
 const safeHelpRequested = (rest.includes("--help") || rest.includes("-h"))
   && !["help", "version", "--version", "-v"].includes(command)
   && (command !== "ci" || rest[0] === "install");
@@ -529,6 +549,143 @@ switch (command) {
   // ---- Zero-config verbs: the same engine the MCP tools use (exported by index.js),
   // invokable by any agent or human with no server setup at all.
 
+  case "focus": {
+    const { flags, positionals } = parseVerbArgs(rest);
+    const query = positionals[0] || "";
+    if (!query) {
+      console.error('usage: tapp focus "SCREEN OR CONTROL" [target] [--platform ios|android|web] [--project-dir REPO] [--target NAME|PATH] [--map FILE] [--out FILE]');
+      process.exit(2);
+    }
+    let projectDir;
+    try { projectDir = fs.realpathSync(path.resolve(typeof flags["project-dir"] === "string" ? flags["project-dir"] : process.cwd())); }
+    catch { console.error("❌ --project-dir must be an existing repository directory"); process.exit(2); }
+    const target = positionals[1] || (typeof flags.url === "string" ? flags.url : "");
+    if (typeof flags["project-dir"] !== "string" && target && !/^https?:\/\//i.test(target)) {
+      try {
+        const targetPath = fs.realpathSync(path.resolve(target));
+        if (fs.statSync(targetPath).isDirectory()) projectDir = targetPath;
+      } catch { /* a bundle/application id is not a repository path */ }
+    }
+    let platform = requestedPlatform(flags, target);
+    let modeledTarget = null;
+    const directRuntimeTarget = /^https?:\/\//i.test(target) || /\.apk$/i.test(target)
+      || (target && !fs.existsSync(path.resolve(target)));
+    const modelPath = existingProjectArtifactPath(projectDir, "application-model.json");
+    if (!directRuntimeTarget && fs.existsSync(modelPath)) {
+      try {
+        const model = JSON.parse(fs.readFileSync(modelPath, "utf8"));
+        const { selectApplicationTarget } = await import(path.join(packageRoot, "mcp-server", "src", "ci-setup.js"));
+        modeledTarget = selectApplicationTarget(model, {
+          platform:typeof flags.platform === "string" ? flags.platform.toLowerCase() : "",
+          target:typeof flags.target === "string" ? flags.target.trim() : "",
+          useDefault:true,
+        });
+        platform = modeledTarget.platform;
+      } catch (error) {
+        let choices = [];
+        try {
+          const model = JSON.parse(fs.readFileSync(modelPath, "utf8"));
+          choices = (model.targets || []).filter((item) => typeof flags.platform !== "string" || item.platform === flags.platform.toLowerCase());
+        } catch { /* the primary parse/select error is printed below */ }
+        printEngineError({ error:error.message || String(error), details:{ targets:choices } });
+        process.exit(2);
+      }
+    }
+    if (!["ios", "android", "web"].includes(platform)) { console.error("❌ --platform must be ios|android|web"); process.exit(2); }
+    const engine = await engineImport();
+    let started = null;
+    try {
+      if (platform === "ios") {
+        requireMacFor("iOS focused navigation");
+        let bundleId;
+        if (modeledTarget) {
+          const resolved = await engine.resolveAppTarget(path.resolve(projectDir, modeledTarget.sourcePath || "."), {
+            cwd:projectDir,
+            scheme:modeledTarget.build?.scheme || modeledTarget.build?.proposedScheme || "",
+            configuration:modeledTarget.build?.configuration || "Debug",
+            onStatus:(status) => console.error(`⏳ ${status}`),
+          });
+          if (resolved.error) {
+            printEngineError(resolved);
+            process.exitCode = 1;
+            break;
+          }
+          bundleId = resolved.bundleId;
+          if (resolved.via) console.error(`🎯 Target: ${bundleId} — ${resolved.via}`);
+        } else {
+          const sim = await engine.ensureBootedSim({ autoBoot:true });
+          if (sim.error) throw new Error(sim.error);
+          bundleId = await resolveTargetOrExit(engine, target || projectDir);
+        }
+        const launch = iosLaunchOptions(flags, rest);
+        started = await engine.startIosInteractiveSession(bundleId, engine.explorationEnvFromArgs({ testEmail:flags.email, testPassword:flags.password, ...launch }));
+      } else if (platform === "android") {
+        const explicitAndroid = typeof flags["app-id"] === "string" || /\.apk$/i.test(target)
+          || (target && !fs.existsSync(path.resolve(target)));
+        if (explicitAndroid) {
+          const android = androidTarget(flags, target);
+          started = await engine.startAndroidInteractiveSession(android.appId, { serial:android.serial, apkPath:android.apkPath, clearData:flags["keep-data"] !== true });
+        } else {
+          const prepared = await engine.prepareAndroidInteractiveTarget({
+            projectDir,
+            target:typeof flags.target === "string" ? flags.target : modeledTarget?.id || "",
+            onStatus:(status) => console.error(`⏳ ${status}`),
+          });
+          if (prepared.error) {
+            printEngineError(prepared);
+            process.exitCode = 1;
+            break;
+          }
+          console.error(`🎯 Target: ${prepared.appId} — built ${prepared.selectedTarget.name} → ${prepared.apkPath}`);
+          started = await engine.startAndroidInteractiveSession(prepared.appId, {
+            serial:typeof flags.serial === "string" ? flags.serial : undefined,
+            apkPath:prepared.apkPath,
+            clearData:flags["keep-data"] !== true,
+          });
+        }
+      } else {
+        started = /^https?:\/\//i.test(target)
+          ? await engine.startWebInteractiveSession(target)
+          : await engine.startManagedWebInteractiveSession({
+              projectDir,
+              requestedTarget:typeof flags.target === "string" ? flags.target : modeledTarget?.sourcePath || modeledTarget?.name || target,
+              timeout:flags.timeout,
+              testEmail:typeof flags.email === "string" ? flags.email : "",
+              testPassword:typeof flags.password === "string" ? flags.password : "",
+              onStatus:(status) => console.error(`⏳ ${status}`),
+            });
+      }
+      if (started.error) {
+        printEngineError(started);
+        process.exitCode = 1;
+        break;
+      }
+      const focused = await engine.focusInteractiveSession({ projectDir, query, platform, mapPath:typeof flags.map === "string" ? flags.map : "" });
+      const { focusedTargetSummary } = await import(path.join(packageRoot, "mcp-server", "src", "focused-navigation.js"));
+      console.log(focusedTargetSummary(focused));
+      if (focused.execution?.status === "reached") {
+        console.log(`\n⚡ Reached in ${(focused.execution.steps || []).length} route action(s).\n`);
+        console.log(engine.formatScreen(focused.screenTitle, focused.elements));
+        const frame = await engine.captureInteractiveSessionFrame(Number(flags.width) || 900);
+        if (!frame.error) {
+          const out = saveShot(frame, typeof flags.out === "string" ? path.resolve(flags.out) : null, `focus-${Date.now()}.${frame.mimeType === "image/png" ? "png" : "jpg"}`);
+          console.log(`\n📸 Screenshot: ${out}`);
+        }
+      } else if (focused.execution?.status === "failed") {
+        console.error(`\n❌ Observed route stopped: ${focused.execution.reason}`);
+        process.exitCode = 1;
+      } else {
+        console.error("\nℹ️  Tapp located the source but did not drive an unobserved route. Ground the UI Map with `npx -y @aarwitz/tapp@latest init . --explore`.");
+      }
+    } catch (error) {
+      console.error(`❌ ${error.message || String(error)}`);
+      process.exitCode = 1;
+    } finally {
+      if (started) await engine.endInteractiveSession();
+    }
+    break;
+  }
+
   case "explore":
   case "qa": {
     // `explore` is the canonical verb (ADR-0005: exploration observes; the gate judges). `qa` is a
@@ -1003,7 +1160,9 @@ switch (command) {
       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 });
-    console.log(`\nEvidence: ${evidenceDir}`);
+    const evidenceWritten = fs.existsSync(evidenceDir) && fs.readdirSync(evidenceDir).length > 0;
+    if (evidenceWritten) console.log(`\nEvidence: ${evidenceDir}`);
+    else console.error("\n⚠️ Evidence unavailable — the platform runner did not write any artifacts for this Flow run.");
     process.exit(result.status ?? 1);
   }
 
@@ -1268,7 +1427,7 @@ switch (command) {
       console.log(`  ⬜ iOS — requires macOS (this host: ${process.platform})`);
     }
 
-    const { resolveAdbPath } = await import(path.join(packageRoot, "mcp-server", "src", "android-driver.js"));
+    const { resolveAdbPath, resolveAndroidSdkRoot } = await import(path.join(packageRoot, "mcp-server", "src", "android-driver.js"));
     const adbPath = resolveAdbPath();
     const adb = adbPath ? run(adbPath, ["devices"]) : { code: 1, stdout: "" };
     if (adb.code === 0) {
@@ -1277,6 +1436,14 @@ switch (command) {
     } else {
       console.log("  ⬜ Android — adb not found (install Android SDK platform-tools)");
     }
+    const { resolveJavaRuntime } = await import(path.join(packageRoot, "mcp-server", "src", "environment-preflight.js"));
+    const java = resolveJavaRuntime();
+    const androidSdkRoot = resolveAndroidSdkRoot();
+    if (java && androidSdkRoot) ok("Android source builds", `${java.version || java.javaHome}; SDK ${androidSdkRoot}`);
+    else {
+      const missing = [!java ? "JDK 17" : "", !androidSdkRoot ? "Android SDK root" : ""].filter(Boolean).join(" and ");
+      console.log(`  ⬜ Android source builds — install/configure ${missing} (prebuilt APK testing still works)`);
+    }
 
     try {
       const { chromium } = await import("playwright");
@@ -1620,6 +1787,7 @@ Core — inspect, explore, gate (no Tapp account or server required):
   tapp explore [target]    Autonomous exploration → findings + evidence (an observation, NOT a
                            release decision — run 'npx -y @aarwitz/tapp@latest ci' to gate a merge)
                            (web: --watch · all: --platform ios|android|web · --actions N)
+  tapp focus "goal" [target] Source-locate a named screen/control and take the shortest observed route
   tapp contract run FILE   Replay a business-level release contract — the guarantees that must hold
   tapp ci ...              Merge-blocking release gate — explore + suites + baseline → pass/fail/inconclusive
                            (see: tapp ci --help)

package/docs/scenarios.md

@@ -74,7 +74,7 @@ tapp ci --platform web --url http://127.0.0.1:4180 \
 GitHub Action:
 
 ```yaml
-- uses: aarwitz/tapp@main
+- uses: aarwitz/tapp@v0.17.2 # or pin the reviewed release commit SHA
   with:
     platform: web
     url: http://127.0.0.1:4180

package/mcp-server/src/android-driver.js

@@ -33,6 +33,13 @@ export function resolveAdbPath(env = process.env) {
   return executable("adb", env);
 }
 
+/** Resolve the SDK root from the same evidence used to find adb, including common unlinked
+ * Homebrew installations. Gradle needs this even when device automation already found adb. */
+export function resolveAndroidSdkRoot(env = process.env) {
+  const adbPath = resolveAdbPath(env);
+  return adbPath ? path.dirname(path.dirname(adbPath)) : null;
+}
+
 function runFile(command, args, { encoding = "utf8", timeout = 30_000, maxBuffer = 16 * 1024 * 1024 } = {}) {
   return new Promise((resolve) => {
     execFile(command, args, { encoding, timeout, maxBuffer }, (error, stdout, stderr) => {
@@ -305,14 +312,25 @@ export class AndroidDriver {
     return r.stdout;
   }
 
-  async settle(timeoutMs = 2200) {
+  async settle(timeoutMs = 2200, previousSnapshot = null) {
     const deadline = Date.now() + timeoutMs;
+    const fingerprintOf = (snapshot) => (snapshot?.elements || [])
+      .map((e) => `${androidElementKey(e)}:${e.text}:${e.x},${e.y}`).join("|");
+    const previousScreen = String(previousSnapshot?.screenTitle || "");
+    const previousFingerprint = fingerprintOf(previousSnapshot);
     let previous = "";
     let stable = 0;
     let latest;
     while (Date.now() < deadline) {
       latest = await this.snapshot();
-      const fingerprint = latest.elements.map((e) => `${androidElementKey(e)}:${e.text}:${e.x},${e.y}`).join("|");
+      const fingerprint = fingerprintOf(latest);
+      // UIAutomator's dump command itself waits for the UI to become idle. If its first complete
+      // snapshot proves that the requested interaction changed the screen, a second identical
+      // dump adds roughly two seconds without adding evidence. Preserve the two-snapshot stability
+      // requirement when nothing changed (including delayed navigation and no-op controls).
+      if (previousSnapshot && fingerprint && (
+        String(latest.screenTitle || "") !== previousScreen || fingerprint !== previousFingerprint
+      )) return latest;
       if (fingerprint === previous) stable += 1; else stable = 0;
       if (stable >= 1) return latest;
       previous = fingerprint;

package/mcp-server/src/environment-preflight.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 
 export const STORAGE_BLOCK_BYTES = 256 * 1024 * 1024;
 export const STORAGE_WARN_BYTES = 5 * 1024 * 1024 * 1024;
@@ -41,3 +42,37 @@ export function storagePreflight(candidate, { statfs = fs.statfsSync, blockBytes
     return { ok: true, level: "unknown", path: checkedPath, freeBytes: null, message: `Free disk space could not be checked: ${error.message || String(error)}` };
   }
 }
+
+/** Find a working Java runtime for repository-owned Android builds, including common unlinked
+ * Homebrew and Android Studio installations on macOS. APK/device testing itself does not need it. */
+export function resolveJavaRuntime(env = process.env, { probe = spawnSync, minimumMajor = 17 } = {}) {
+  const executable = process.platform === "win32" ? "java.exe" : "java";
+  const homes = [
+    env.JAVA_HOME,
+    process.platform === "darwin" ? "/Applications/Android Studio.app/Contents/jbr/Contents/Home" : "",
+    process.platform === "darwin" ? "/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home" : "",
+    process.platform === "darwin" ? "/opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home" : "",
+    process.platform === "darwin" ? "/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home" : "",
+    process.platform === "darwin" ? "/usr/local/opt/openjdk/libexec/openjdk.jdk/Contents/Home" : "",
+  ].filter(Boolean);
+  const candidates = [
+    ...homes.map((home) => ({ javaHome:home, javaPath:path.join(home, "bin", executable) })),
+    ...String(env.PATH || "").split(path.delimiter).filter(Boolean).map((dir) => ({ javaHome:"", javaPath:path.join(dir, executable) })),
+  ];
+  const seen = new Set();
+  for (const candidate of candidates) {
+    if (seen.has(candidate.javaPath) || !fs.existsSync(candidate.javaPath)) continue;
+    seen.add(candidate.javaPath);
+    const checked = probe(candidate.javaPath, ["-version"], { encoding:"utf8" });
+    if ((checked.status ?? 1) !== 0) continue;
+    const version = String(checked.stderr || checked.stdout || "").split(/\r?\n/)[0].trim();
+    const matched = version.match(/version\s+"(\d+)(?:\.(\d+))?/i);
+    const major = matched ? Number(matched[1] === "1" ? matched[2] : matched[1]) : 0;
+    if (!major || major < minimumMajor) continue;
+    let javaPath = candidate.javaPath;
+    try { javaPath = fs.realpathSync(javaPath); } catch { /* preserve the discovered path */ }
+    const javaHome = candidate.javaHome || path.dirname(path.dirname(javaPath));
+    return { javaPath, javaHome, version, major };
+  }
+  return null;
+}