@aarwitz/tapp 0.17.9 → 0.17.11

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

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -387,7 +387,8 @@ class ExplorerTests: XCTestCase {
                     app.coordinate(withNormalizedOffset: .zero).withOffset(CGVector(dx: x, dy: y)).tap()
                 } else { status = "bad_args" }
             case "type":
-                status = sessionType(cmd["text"] as? String ?? "", id: cmd["id"] as? String) ? "ok" : "not_found"
+                status = sessionType(cmd["text"] as? String ?? "", id: cmd["id"] as? String) ? "ok" : (lastTypeFailure.isEmpty ? "not_found" : "focus_failed")
+                if status == "focus_failed" { loginDetail = lastTypeFailure }
             case "swipe":
                 switch (cmd["direction"] as? String ?? "up") {
                 case "down": app.swipeDown(); case "left": app.swipeLeft(); case "right": app.swipeRight(); default: app.swipeUp()
@@ -578,10 +579,12 @@ class ExplorerTests: XCTestCase {
         // credential the server rejects with no visible cause.
         if let id = id, !id.isEmpty {
             for field in [app.textFields[id], app.secureTextFields[id], app.textViews[id]] where field.exists {
-                replaceText(on: field, with: text); lastTypedInto = fieldDesc(field); return true
+                guard replaceText(on: field, with: text) else { return false }
+                lastTypedInto = fieldDesc(field); return true
             }
             if let field = resolveFieldByHint(id) {
-                replaceText(on: field, with: text); lastTypedInto = fieldDesc(field); return true
+                guard replaceText(on: field, with: text) else { return false }
+                lastTypedInto = fieldDesc(field); return true
             }
             return false
         }
@@ -590,8 +593,7 @@ class ExplorerTests: XCTestCase {
         if app.keyboards.firstMatch.exists {
             if let focused = focusedField() {
                 lastTypedInto = fieldDesc(focused)
-                replaceText(on: focused, with: text)
-                return true
+                return replaceText(on: focused, with: text)
             }
             app.typeText(text)
             lastTypedInto = "focused field"
@@ -599,7 +601,8 @@ class ExplorerTests: XCTestCase {
         }
         // Nothing focused and no usable id — last resort: the first text field or text view.
         for first in [app.textFields.firstMatch, app.textViews.firstMatch] where first.exists {
-            replaceText(on: first, with: text); lastTypedInto = fieldDesc(first); return true
+            guard replaceText(on: first, with: text) else { return false }
+            lastTypedInto = fieldDesc(first); return true
         }
         return false
     }
@@ -809,7 +812,7 @@ class ExplorerTests: XCTestCase {
                 if status == "fail" { detail = "could not tap ‘\(target)’" }
             case "type":
                 status = sessionType(value, id: target.isEmpty ? nil : target) ? "pass" : "fail"
-                if status == "fail" { detail = "no field ‘\(target)’ to type into" }
+                if status == "fail" { detail = lastTypeFailure.isEmpty ? "no field ‘\(target)’ to type into" : lastTypeFailure }
             case "login":
                 let email = subst((step["email"] as? String) ?? "$TEST_EMAIL")
                 let password = subst((step["password"] as? String) ?? "$TEST_PASSWORD")
@@ -1082,11 +1085,23 @@ class ExplorerTests: XCTestCase {
 
         let testEmail = resolve("OCQA_TEST_EMAIL")
         let testPassword = resolve("OCQA_TEST_PASSWORD")
-        if resolve("OCQA_CREDENTIALS_EXPLICIT") == "1" {
-            // Presence only: never print, persist, or expose credential values. Report rebuilding
-            // needs this durable marker to distinguish "not supplied" from "supplied but unused".
+        // Presence only: never print, persist, or expose credential values. Report rebuilding
+        // needs this durable marker to distinguish "not supplied" from "supplied but unused".
+        // Decided by what actually reached the run config, not by a separate flag the run config
+        // never carried (feedback #3: every iOS run reported credentialsProvided=false).
+        if resolve("OCQA_CREDENTIALS_EXPLICIT") == "1" || !testEmail.isEmpty || !testPassword.isEmpty {
             print("OCQA_STATE:credentials_supplied")
         }
+        // Capture conditions shared by every screenshot in this run, so a baseline diff across a
+        // different device/scale is visibly a layout comparison (feedback #5: iOS reports carried
+        // captureContext: null while the changelog promised it).
+        do {
+            let env = ProcessInfo.processInfo.environment
+            let device = env["SIMULATOR_DEVICE_NAME"] ?? env["SIMULATOR_MODEL_IDENTIFIER"] ?? "iOS Simulator"
+            let bounds = app.windows.firstMatch.exists ? app.windows.firstMatch.frame : app.frame
+            let scale = UIScreen.main.scale
+            print("OCQA_CONTEXT:{\"device\":\"\(escapeJSON(device))\",\"viewport\":{\"width\":\(Int(bounds.width.rounded())),\"height\":\(Int(bounds.height.rounded()))},\"deviceScaleFactor\":\(scale)}")
+        }
 
         // --- Explicit login replay (config-driven): a recorded type/tap/wait sequence for custom
         // login UIs the heuristic preamble below can't parse. When configured it takes precedence. ---
@@ -4706,9 +4721,62 @@ class ExplorerTests: XCTestCase {
         print("OCQA_PROGRESS:{\"action\":\(action),\"max\":\(maxActions),\"states\":\(states)}")
     }
 
-    // Replace existing field contents to avoid repeatedly appending test text.
-    private func replaceText(on element: XCUIElement, with text: String) {
-        element.tap()
+    /// Why the last replaceText could not type — surfaced as the step's detail so a flow says
+    /// "the field never took keyboard focus" instead of dying on an XCTest assertion.
+    private var lastTypeFailure = ""
+
+    /// Give a field keyboard focus and PROVE it before typing. `element.tap()` returning is not
+    /// proof: SwiftUI fields inside a ScrollView regularly report an accessibility frame that
+    /// lags the visible layout (content above them resolved and shifted), so the first tap lands
+    /// on empty space, `typeText` then fails XCTest's "Neither element nor any descendant has
+    /// keyboard focus" assertion and the whole run dies. Strategy: tap, poll for focus, and on a
+    /// miss re-resolve the element (fresh snapshot) and try a coordinate tap at its centre, then
+    /// 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 }
+        func settleUntilFocused() -> Bool {
+            let deadline = Date().addingTimeInterval(1.2)
+            repeat {
+                if focused() { return true }
+                Thread.sleep(forTimeInterval: 0.15)
+            } while Date() < deadline
+            return focused()
+        }
+        for attempt in 0..<3 {
+            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:
+                // 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()
+            }
+            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")")
+        }
+        return false
+    }
+
+    // Replace existing field contents to avoid repeatedly appending test text. Returns false
+    // (and records `lastTypeFailure`) instead of letting XCTest abort the run when the field
+    // cannot be focused.
+    @discardableResult
+    private func replaceText(on element: XCUIElement, with text: String) -> Bool {
+        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"
+                + (app.keyboards.count == 0 ? " — no keyboard appeared" : "")
+                + (focusedField().map { " — focus is on ‘\(fieldDesc($0))’" } ?? "")
+            print("OCQA_STATE:type_focus_failed detail=\(escapeJSON(lastTypeFailure))")
+            return false
+        }
 
         if let existing = element.value as? String,
            !existing.isEmpty,
@@ -4718,5 +4786,6 @@ class ExplorerTests: XCTestCase {
         }
 
         element.typeText(text)
+        return true
     }
 }

package/README.md

@@ -199,6 +199,7 @@ one by hand:
 
 ```bash
 npx -y @aarwitz/tapp@latest flow example
+npx -y @aarwitz/tapp@latest flow steps      # the step vocabulary: target semantics and pass condition per step
 npx -y @aarwitz/tapp@latest flow validate .tapp/flows/smoke.yml
 npx -y @aarwitz/tapp@latest flow run .tapp/flows/smoke.yml
 ```

package/bin/tapp.js

@@ -270,7 +270,7 @@ function safeCommandUsage(verb) {
     shot: "tapp shot [--out FILE]",
     apps: "tapp apps",
     build: "tapp build [repo] [--scheme NAME] [--configuration NAME]",
-    flow: "tapp flow example\ntapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--actor NAME] [--email VALUE] [--password VALUE] [--device \"iPhone 13\"] [--viewport 390x844]\n  Exit codes: 0 replay passed · 1 replay failed · 2 infrastructure/usage error",
+    flow: "tapp flow example\ntapp flow steps [--json]\ntapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--actor NAME] [--email VALUE] [--password VALUE] [--device \"iPhone 13\"] [--viewport 390x844]\n  Exit codes: 0 replay passed · 1 replay failed · 2 infrastructure/usage error",
     task: "tapp task validate FILE [--platform PLATFORM] [--map FILE]\ntapp task compile FILE --platform PLATFORM [--inputs JSON] [--out FILE]\ntapp task run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID] [--inputs JSON]",
     contract: "tapp contract validate FILE [--platform PLATFORM] [--map FILE]\ntapp contract compile FILE --platform PLATFORM [--out FILE]\ntapp contract run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID]\n  Exit codes: 0 contract held · 1 contract failed · 2 infrastructure/usage error",
     scenario: "tapp scenario validate FILE [--project-dir DIR]\ntapp scenario run FILE --platform web --url URL [--project-dir DIR]\n  Exit codes: 0 scenario passed · 1 scenario failed · 2 infrastructure/usage error",
@@ -1133,8 +1133,16 @@ switch (command) {
       console.log(`# Tapp Flow — deterministic, keyless replay\nname: sign-in-smoke\nplatform: web\nurl: https://example.test/login\nsteps:\n  - login:\n      email: $TEST_EMAIL\n      password: $TEST_PASSWORD\n  - wait_for: Dashboard\n  - assert_screen: Dashboard\n`);
       break;
     }
+    if (verb === "steps") {
+      const { FLOW_ACTIONS } = await import(path.join(packageRoot, "mcp-server", "src", "flow-runtime.js"));
+      if (flags.json === true) { console.log(JSON.stringify(FLOW_ACTIONS, null, 2)); break; }
+      console.log("Flow step vocabulary — identical on ios, android, and web. Anything else fails `tapp flow validate`.\n");
+      for (const a of FLOW_ACTIONS) console.log(`  ${a.action.padEnd(14)} target: ${a.target}\n  ${"".padEnd(14)} passes: ${a.passes}\n`);
+      console.log("Targets are labels / accessibility ids / visible text, never coordinates. `assert_screen` checks the detected screen TITLE; use `assert_exists` for \"this text is on screen\".");
+      break;
+    }
     if (!["run", "validate"].includes(verb) || !flowPath) {
-      console.error("usage: tapp flow example\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> [--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>");
       process.exit(2);
     }
     const absolute = path.resolve(flowPath);
@@ -1142,7 +1150,7 @@ switch (command) {
       console.error(`❌ Flow not found: ${absolute}`);
       process.exit(2);
     }
-    const { loadFlowFile } = await import(path.join(packageRoot, "mcp-server", "src", "flow-runtime.js"));
+    const { loadFlowFile, validateFlowSteps } = await import(path.join(packageRoot, "mcp-server", "src", "flow-runtime.js"));
     let flow;
     try { flow = loadFlowFile(absolute); } catch (error) {
       console.error(`❌ Invalid Flow: ${error.message}`);
@@ -1157,6 +1165,13 @@ switch (command) {
       console.error(`❌ Unsupported Flow platform: ${platform}`);
       process.exit(2);
     }
+    // Static step checks run before validate AND run: a Flow outside the vocabulary (or a
+    // coordinate tap) can never replay, so it must not reach a simulator (feedback #2).
+    const stepErrors = validateFlowSteps(flow, platform);
+    if (stepErrors.length) {
+      console.error(`❌ Invalid ${platform} Flow — ${flow.name || path.basename(absolute)}:\n${stepErrors.map((e) => `   • ${e}`).join("\n")}\n   Vocabulary: tapp flow steps`);
+      process.exit(2);
+    }
     if (verb === "validate") {
       const taskCount = Array.isArray(flow.taskPlan) ? flow.taskPlan.length : 0;
       console.log(`✅ Valid ${platform} Flow — ${flow.name} (${flow.steps.length} deterministic steps${taskCount ? ` compiled from ${taskCount} Task call${taskCount === 1 ? "" : "s"}` : ""})`);

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@v0.17.9 # or pin the reviewed release commit SHA
+- uses: aarwitz/tapp@v0.17.10 # or pin the reviewed release commit SHA
   with:
     platform: web
     url: http://127.0.0.1:4180

package/mcp-server/src/feedback.js

@@ -86,12 +86,19 @@ export function ghStatus(ghBin = process.env.TAPP_GH_BIN || "gh") {
 }
 
 export function submitFeedbackViaGh(issue, ghBin = process.env.TAPP_GH_BIN || "gh") {
-  const r = spawnSync(ghBin, [
+  // Labels can only be set by accounts with triage rights on the repo. Anyone else (which is
+  // every real user) gets the issue filed without them; the footer already carries the kind
+  // and the maintainer applies labels on triage. Try with labels first, then without.
+  const attempt = (withLabels) => spawnSync(ghBin, [
     "issue", "create", "--repo", FEEDBACK_REPO,
-    "--title", issue.title, "--body-file", "-", "--label", issue.labels.join(","),
+    "--title", issue.title, "--body-file", "-",
+    ...(withLabels ? ["--label", issue.labels.join(",")] : []),
   ], { encoding: "utf8", input: issue.body });
+  let r = attempt(true);
+  let labelsApplied = r.status === 0;
+  if (r.status !== 0 && /label/i.test(`${r.stderr || ""}${r.stdout || ""}`)) { r = attempt(false); labelsApplied = false; }
   const out = (r.stdout || "").trim();
   const err = (r.stderr || "").trim();
   const url = (out.match(/https:\/\/github\.com\/\S+/) || [])[0] || null;
-  return { ok: r.status === 0 && Boolean(url), url, detail: r.status === 0 ? out : (err || out) };
+  return { ok: r.status === 0 && Boolean(url), url, labelsApplied, detail: r.status === 0 ? out : (err || out) };
 }

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

@@ -36,6 +36,60 @@ export function normalizeFlowStep(raw) {
   return { action: key.toLowerCase(), target: body === true ? "" : String(body ?? ""), value: body === true ? "" : String(body ?? ""), params: {}, ...(raw.__tappTask?.name ? { task: raw.__tappTask.name } : {}) };
 }
 
+// The committed Flow step vocabulary. Every driver (XCUITest, Android, browser) implements exactly
+// this table; `tapp flow steps` prints it and `tapp flow validate` rejects anything outside it, so
+// a Flow that validates can actually replay (feedback #2: coordinate taps and `click:` used to
+// validate and then fail at runtime).
+export const FLOW_ACTIONS = Object.freeze([
+  { action: "tap", target: "a visible label / accessibility id", passes: "the control was found and tapped; coordinates are not accepted — use the session's tap-by-point to learn the label" },
+  { action: "type", target: "{field, value}", passes: "the field was found and now holds the value ($TEST_EMAIL/$TEST_PASSWORD substitute)" },
+  { action: "login", target: "{email, password} (defaults to $TEST_EMAIL/$TEST_PASSWORD)", passes: "credentials were entered and submitted and the login form went away" },
+  { action: "swipe", target: "up | down | left | right", passes: "the gesture was performed" },
+  { action: "back", target: "(none)", passes: "the platform back navigation was performed" },
+  { action: "wait", target: "milliseconds (fixed pause; prefer wait_for)", passes: "always" },
+  { action: "wait_for", target: "label / text (+ timeoutMs)", passes: "the element appeared before the timeout" },
+  { action: "assert_screen", target: "the detected SCREEN TITLE (navigation bar / heading), not arbitrary text", passes: "the current screen's title equals the target" },
+  { action: "assert_exists", target: "label / text", passes: "an element with that text or id is present" },
+  { action: "assert_absent", target: "label / text", passes: "no element with that text or id is present" },
+  { action: "assert_text", target: "{of, contains}", passes: "the element's text contains the substring" },
+  { action: "assert_ai", target: "a natural-language expectation", passes: "the vision judge agrees (needs ANTHROPIC_API_KEY; advisory)" },
+]);
+const FLOW_ACTION_NAMES = new Set(FLOW_ACTIONS.map((a) => a.action));
+const ALIASES = { click: "tap", press: "tap", fill: "type", input: "type", sleep: "wait", wait_for_text: "wait_for", assert_visible: "assert_exists", expect: "assert_exists" };
+
+// Static checks a Flow must pass before any runtime is launched. Returns human-readable errors;
+// an empty array means every step is in the vocabulary and shaped so a driver can execute it.
+export function validateFlowSteps(flow, platform = inferFlowPlatform(flow)) {
+  const errors = [];
+  const steps = Array.isArray(flow?.steps) ? flow.steps : [];
+  steps.forEach((raw, i) => {
+    const step = normalizeFlowStep(raw);
+    const n = i + 1;
+    if (step.action === "noop") { errors.push(`step ${n}: empty step`); return; }
+    if (!FLOW_ACTION_NAMES.has(step.action)) {
+      const alias = ALIASES[step.action];
+      errors.push(`step ${n}: unknown action '${step.action}'${alias ? ` — did you mean '${alias}'? (web flows use tap:, not click:)` : ""}; run \`tapp flow steps\` for the vocabulary`);
+      return;
+    }
+    if (step.action === "tap" && /^\s*-?\d+(\.\d+)?\s*,\s*-?\d+(\.\d+)?\s*$/.test(step.target)) {
+      errors.push(`step ${n}: tap target '${step.target.trim()}' is a coordinate; Flow taps are label-only on ${platform} (use tapp_session_act tap {x,y} to learn the label, then record it)`);
+    }
+    if (["tap", "wait_for", "assert_screen", "assert_exists", "assert_absent"].includes(step.action) && !step.target.trim()) {
+      errors.push(`step ${n}: ${step.action} needs a target`);
+    }
+    if (step.action === "type" && (!step.target.trim() || !("value" in (step.params || {})))) {
+      errors.push(`step ${n}: type needs {field, value}`);
+    }
+    if (step.action === "assert_text" && (!step.target.trim() || !step.value)) {
+      errors.push(`step ${n}: assert_text needs {of, contains}`);
+    }
+    if (step.action === "swipe" && step.target && !["up", "down", "left", "right"].includes(step.target.trim().toLowerCase())) {
+      errors.push(`step ${n}: swipe direction must be up|down|left|right`);
+    }
+  });
+  return errors;
+}
+
 export function flowVariables(flow, overrides = {}) {
   return {
     TEST_EMAIL: process.env.OCQA_TEST_EMAIL || "test@example.com",

package/mcp-server/src/index.js

@@ -907,10 +907,39 @@ function recordStep(cmd, result) {
   if (newScreen) activeSession.lastScreen = newScreen;
 }
 
+// Argument shapes tapp_session_act accepts, per action. A malformed call is answered here with
+// the accepted shape and never reaches the driver, so it can neither time out nor disturb the
+// session (feedback #7: `{action:"wait", seconds:3}` used to wait on an empty target).
+const SESSION_ACT_ARGS = Object.freeze({
+  tap: "{id: <label|accessibility id>} or {x, y} (points)",
+  type: "{id|label: <field>, text: <value>}",
+  wait: "{text|id: <label to wait for>, timeoutMs?: <default 5000, max 60000>} — there is no fixed sleep; wait for something",
+  login: "{email?, password?} (defaults to the session's credentials)",
+  swipe: "{direction: up|down|left|right}",
+  back: "{}",
+  tree: "{verbose?: true}",
+  screenshot: "{label?}",
+});
+export function sessionActUsageError(cmd = {}) {
+  const action = String(cmd.action || "");
+  if (!SESSION_ACT_ARGS[action]) return `Unknown action '${action || "(none)"}'. Accepted: ${Object.keys(SESSION_ACT_ARGS).join(", ")}.`;
+  const has = (k) => cmd[k] !== undefined && cmd[k] !== null && String(cmd[k]).trim() !== "";
+  const bad = (why) => `${why}. ${action} takes ${SESSION_ACT_ARGS[action]}.`;
+  if (action === "wait" && !has("text") && !has("id")) return bad(`wait needs a target${cmd.seconds !== undefined || cmd.ms !== undefined ? " (seconds/ms are not arguments)" : ""}`);
+  if (action === "wait" && cmd.timeoutMs !== undefined && !(Number.isFinite(Number(cmd.timeoutMs)) && Number(cmd.timeoutMs) > 0)) return bad("timeoutMs must be a positive number of milliseconds");
+  if (action === "tap" && !has("id") && !has("label") && !(Number.isFinite(cmd.x) && Number.isFinite(cmd.y))) return bad("tap needs an id/label or both x and y");
+  if (action === "type" && !has("id") && !has("label")) return bad("type needs the field's id/label");
+  if (action === "type" && cmd.text === undefined) return bad("type needs text");
+  if (action === "swipe" && cmd.direction !== undefined && !["up", "down", "left", "right"].includes(String(cmd.direction))) return bad("direction must be up|down|left|right");
+  return null;
+}
+
 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." });
+  const usage = sessionActUsageError(cmd);
+  if (usage) return done({ status: "usage", detail: usage, ...treeSnapshot(), recordedSteps: activeSession.recording.length });
   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);

package/mcp-server/src/report.js

@@ -298,6 +298,7 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
   // 40-action campaign. Drivers signal the real cause in COMPLETE.stop; captures from drivers
   // that predate the field keep the old inference.
   const driverStop = base.complete && typeof base.complete === "object" ? base.complete.stop : null;
+  const nativeOutcome = base.complete && typeof base.complete === "object" && typeof base.complete.outcome === "string" ? base.complete.outcome : null;
   const stopReason = unexercisedLoginWall ? (credentialsProvided ? "login-wall-credentials-unused" : "login-wall-no-credentials")
     : timeBudgetExhausted ? "time-budget-exhausted"
     : !coverageFloorMet ? "coverage-floor-not-met"
@@ -306,6 +307,11 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
     // Any other driver-signalled cause (navigation-trap, app-crashed, stuck-no-progress …)
     // passes through verbatim: "completed" is ONLY the exhausted action budget.
     : driverStop && driverStop !== "action-budget" && driverStop !== "time-budget" ? String(driverStop)
+    // XCUITest predates COMPLETE.stop and signals the cause through COMPLETE.outcome instead
+    // (feedback #5: a run whose marker said limited_surface must not read as "completed").
+    : nativeOutcome === "limited_surface" ? "limited-surface"
+    : nativeOutcome === "timeout" ? "time-budget-exhausted"
+    : nativeOutcome && nativeOutcome.startsWith("crash") ? "app-crashed"
     : "completed";
 
   const headline = timeBudgetExhausted

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.9",
+  "version": "0.17.11",
   "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",
@@ -89,7 +89,7 @@
     "mobile"
   ],
   "scripts": {
-    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/focused-navigation.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-link-audit.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/android-primitives-protocol.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/mcp-workspace.test.js tests/action.test.js tests/package-surface.test.js tests/agent-surface.test.js tests/presentation-contract.test.js tests/landing-brand.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js vscode-extension/test/bridge.test.js",
+    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/focused-navigation.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-link-audit.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/android-primitives-protocol.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/mcp-workspace.test.js tests/action.test.js tests/package-surface.test.js tests/agent-surface.test.js tests/presentation-contract.test.js tests/landing-brand.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js tests/feedback-triage-0919.test.js vscode-extension/test/bridge.test.js",
     "test:browser-journey": "node --test tests/browser-journey.test.js",
     "test:browser-native": "TAPP_RUN_NATIVE_BROWSER=1 node --test tests/browser-native-journey.test.js"
   }

package/scripts/flow_lib.py

@@ -63,12 +63,36 @@ def raw_json(path):
     print(json.dumps(load_flow(path) or {}))
 
 
+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 (?:EXECUTE )?FAILED \*\*",
+]
+
+
+def harness_abort_reason(log):
+    """First XCTest/xcodebuild line that explains why a run ended before step 1."""
+    for pat in ABORT_PATTERNS:
+        m = re.search(pat, log)
+        if m:
+            return m.group(0).strip()[:300]
+    return None
+
+
 def report(path, as_json=False):
     log = open(path, encoding="utf-8", errors="replace").read()
     steps = []
     result = None
     name = "flow"
     kind = "flow"
+    declared_total = None
     for line in log.splitlines():
         line = line.strip()
         if line.startswith("OCQA_FLOW_STEP:"):
@@ -83,6 +107,9 @@ def report(path, as_json=False):
             km = re.search(r"\bkind=([^ ]+)", line)
             if km:
                 kind = km.group(1)
+            tm = re.search(r"\btotal=(\d+)", line)
+            if tm:
+                declared_total = int(tm.group(1))
         elif line.startswith("OCQA_FLOW_RESULT:{"):
             try:
                 result = json.loads(line[len("OCQA_FLOW_RESULT:"):])
@@ -97,8 +124,29 @@ def report(path, as_json=False):
     executed = (result or {}).get("executed", len(steps))
     passed_steps = sum(1 for s in steps if s.get("status") == "pass")
 
+    # A run that died before step 1 used to print `0 passed · 0 failed · 0/0 executed` and
+    # nothing else; the XCTest reason lived only in flow.log (feedback #1). Surface it as the
+    # 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)
+        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)
+    elif result is None and steps:
+        # 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)
+        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}"})
+        failed += 1
+        passed = False
+
     if as_json:
-        print(json.dumps({"name": name, "kind": kind, "passed": passed, "total": total, "executed": executed, "failed": failed, "steps": steps}))
+        print(json.dumps({"name": name, "kind": kind, "passed": passed, "total": total, "executed": executed, "failed": failed,
+                          **({"abortReason": abort_reason} if abort_reason else {}), "steps": steps}))
         return 0 if passed else 1
 
     icon = {"pass": "✅", "fail": "❌", "skip": "⚪️"}

package/scripts/quick-capture.sh

@@ -184,7 +184,8 @@ run_harness_test() {
   "OCQA_MAX_ACTIONS": "$max_actions",
   "OCQA_TIMEOUT_SECONDS": "$timeout_secs",
   "OCQA_TEST_EMAIL": "${OCQA_TEST_EMAIL:-}",
-  "OCQA_TEST_PASSWORD": "${OCQA_TEST_PASSWORD:-}"$interactive_line$overrides_line$launch_args_line$launch_env_line$login_steps_line$pr_target_line$visual_ready_line$recording_started_line
+  "OCQA_TEST_PASSWORD": "${OCQA_TEST_PASSWORD:-}",
+  "OCQA_CREDENTIALS_EXPLICIT": "${OCQA_CREDENTIALS_EXPLICIT:-}"$interactive_line$overrides_line$launch_args_line$launch_env_line$login_steps_line$pr_target_line$visual_ready_line$recording_started_line
 }
 CONF
 

package/skills/tapp/references/commands.md

@@ -101,6 +101,8 @@ ask the user rather than pretending the explored surface was complete.
 Flow YAML belongs under `.tapp/flows/` and can replay without a model or API key:
 
 ```bash
+npx -y @aarwitz/tapp@latest flow steps     # vocabulary: assert_screen = screen TITLE, assert_exists = text present; taps are label-only
+npx -y @aarwitz/tapp@latest flow validate .tapp/flows/smoke.yml
 npx -y @aarwitz/tapp@latest flow run .tapp/flows/smoke.yml
 npx -y @aarwitz/tapp@latest ci
 ```