@aarwitz/tapp 0.17.19 → 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.19",
+  "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.19",
+        "@aarwitz/tapp@0.17.20",
         "mcp"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}"

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() }
@@ -5090,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 {
@@ -5157,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/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";
@@ -1291,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

@@ -649,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;
@@ -765,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." }; }
 
@@ -1014,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);
@@ -1176,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 } : {}) });
 }
@@ -3272,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" },
@@ -4585,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.19",
+  "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,17 @@ 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 ""