@aarwitz/tapp 0.17.11 → 0.17.12

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

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -552,6 +552,21 @@ class ExplorerTests: XCTestCase {
         }
     }
 
+    /// What WAS on screen when a wait/assert missed — so a failure report points at the fix
+    /// (wrong screen? renamed label? error state?) without a separate `tapp tree` run (#20/#22).
+    private func visibleLabelsHint(limit: Int = 8) -> String {
+        let labels = readUITree(app)
+            .filter { isStaticTextType($0.type) || isInteractable($0.type) }
+            .map { normalizeVisibleText($0.label) }
+            .filter { $0.count >= 2 }
+        var seen = Set<String>(); var top: [String] = []
+        for label in labels where !seen.contains(label) {
+            seen.insert(label); top.append(label)
+            if top.count >= limit { break }
+        }
+        return top.isEmpty ? "" : " — visible: \(top.joined(separator: " · "))"
+    }
+
     private func sessionWaitFor(_ target: String, timeoutMs: Int) -> Bool {
         guard !target.isEmpty else { return false }
         let deadline = Date().addingTimeInterval(Double(timeoutMs) / 1000.0)
@@ -767,6 +782,10 @@ class ExplorerTests: XCTestCase {
             print("OCQA_FLOW_RESULT:{\"passed\":false,\"total\":0,\"failed\":0,\"error\":\"no OCQA_FLOW_JSON with steps\"}")
             return
         }
+        // Per-flow wait default (field issue #20): a splash that prefetches for ~8s makes the
+        // fixed 6s wait_for fail on a healthy app. Steps may still override individually.
+        let flowDefaultTimeoutMs = (flow["timeoutMs"] as? Int) ?? (flow["timeout"] as? Int) ?? 6000
+
         // Variable substitution: $TEST_EMAIL/$TEST_PASSWORD from creds, plus any OCQA_FLOW_VARS.
         var vars: [String: String] = ["TEST_EMAIL": resolve("OCQA_TEST_EMAIL", fallback: "test@example.com"),
                                       "TEST_PASSWORD": resolve("OCQA_TEST_PASSWORD", fallback: "TestPass123!")]
@@ -802,7 +821,7 @@ class ExplorerTests: XCTestCase {
             let (action, step) = normalizeFlowStep(raw)
             let target = subst((step["target"] as? String) ?? "")
             let value = subst((step["value"] as? String) ?? "")
-            let timeoutMs = (step["timeoutMs"] as? Int) ?? 6000
+            let timeoutMs = (step["timeoutMs"] as? Int) ?? (step["timeout"] as? Int) ?? flowDefaultTimeoutMs
             var status = "pass"
             var detail = ""
 
@@ -818,7 +837,14 @@ class ExplorerTests: XCTestCase {
                 let password = subst((step["password"] as? String) ?? "$TEST_PASSWORD")
                 let result = sessionLogin(email: email, password: password)
                 status = result.status == "ok" ? "pass" : "fail"
-                if status == "fail" { detail = result.detail.isEmpty ? result.status : result.detail }
+                if status == "fail" {
+                    detail = result.detail.isEmpty ? result.status : result.detail
+                    // Firebase's "error accessing the keychain" on a simulator is stale keychain
+                    // state, not bad credentials — name the one-line fix (field issue #21).
+                    if detail.lowercased().contains("accessing the keychain") {
+                        detail += " — simulator keychain is stale; `xcrun simctl erase <udid>` (or Device ▸ Erase All Content and Settings) usually fixes Firebase keychain errors"
+                    }
+                }
             case "swipe":
                 switch target.lowercased() { case "down": app.swipeDown(); case "left": app.swipeLeft(); case "right": app.swipeRight(); default: app.swipeUp() }
             case "back":
@@ -827,7 +853,7 @@ class ExplorerTests: XCTestCase {
                 Thread.sleep(forTimeInterval: Double(timeoutMs) / 1000.0)
             case "wait_for":
                 status = sessionWaitFor(target, timeoutMs: timeoutMs) ? "pass" : "fail"
-                if status == "fail" { detail = "‘\(target)’ never appeared within \(timeoutMs)ms" }
+                if status == "fail" { detail = "‘\(target)’ never appeared within \(timeoutMs)ms\(visibleLabelsHint())" }
             case "assert_screen":
                 let ok = pollUntil(timeoutMs: timeoutMs) { (detectTitle(readUITree(app)) ?? "").caseInsensitiveCompare(value.isEmpty ? target : value) == .orderedSame }
                 status = ok ? "pass" : "fail"
@@ -835,7 +861,7 @@ class ExplorerTests: XCTestCase {
             case "assert_exists":
                 let ok = sessionWaitFor(target, timeoutMs: timeoutMs)
                 status = ok ? "pass" : "fail"
-                if !ok { detail = "‘\(target)’ not found" }
+                if !ok { detail = "‘\(target)’ not found\(visibleLabelsHint())" }
             case "assert_absent":
                 waitForUIStability(timeout: 1.5)
                 let present = elementPresent(target)

package/bin/tapp.js

@@ -860,6 +860,14 @@ switch (command) {
         if (!snap.settled) console.error("⚠️ Page still showed a loading or changing state when the bounded wait ended.");
       } catch (error) {
         console.error(`❌ ${error.message || String(error)}`);
+        const evidence = error.timeoutEvidence;
+        if (evidence?.image) {
+          const out = typeof flags.out === "string" ? path.resolve(flags.out) : path.join(tappHome, "shots", `web-timeout-${Date.now()}.png`);
+          fs.mkdirSync(path.dirname(out), { recursive: true });
+          fs.writeFileSync(out, evidence.image);
+          console.error(`📸 Screenshot at timeout: ${out}`);
+        }
+        if (evidence?.visible?.length) console.error(`👀 Visible instead: ${evidence.visible.join(" · ")}`);
         process.exit(1);
       }
       break;
@@ -1473,6 +1481,13 @@ switch (command) {
     const python = run("python3", ["--version"]);
     report.python3 = { ok: python.code === 0, version: python.code === 0 ? python.stdout : null };
     python.code === 0 ? sayOk("python3", `${python.stdout} (used by Flows)`) : sayBad("python3", "not found — Flow replay needs python3 + pyyaml (everything else works)");
+    // Hosted macOS runners ship python3 WITHOUT PyYAML (field issue #16) — check the module,
+    // not just the interpreter, so `doctor` catches it before a Flow dies mid-CI.
+    if (python.code === 0) {
+      const pyyaml = run("python3", ["-c", "import yaml"]);
+      report.pyyaml = { ok: pyyaml.code === 0 };
+      pyyaml.code === 0 ? sayOk("PyYAML", "importable (YAML Flow replay)") : sayBad("PyYAML", "missing — `python3 -m pip install pyyaml` (YAML Flow replay needs it; JSON Flows work without)");
+    }
 
     const { storagePreflight } = await import(path.join(packageRoot, "mcp-server", "src", "environment-preflight.js"));
     const storage = storagePreflight(tappHome);

package/mcp-server/src/ci-report.js

@@ -6,7 +6,8 @@
 // summary (when GITHUB_STEP_SUMMARY is set), a machine-readable JSON report, and — the point —
 // an exit code CI can gate a merge on.
 //
-//   node src/ci-report.js --markers <ocqa-markers.txt>
+//   node src/ci-report.js --markers <ocqa-markers.txt>   # or --flows-only: no exploration ran
+//                                                         # (deliberate; suites are the whole surface)
 //                         [--baseline <baseline.json>]      # prior run's findings[] (or a full report)
 //                         [--flow-log <log> ...]            # run-flow.sh logs (repeatable)
 //                         [--json-out <report.json>]        # full report incl. findings for the next baseline
@@ -31,7 +32,7 @@
 import fs from "fs";
 import path from "node:path";
 import { execSync } from "node:child_process";
-import { buildQaReport, computeRegression, computeContentCollapse, computeReachabilityLoss, evaluateGate, GATE_EXIT } from "./report.js";
+import { buildQaReport, buildFlowsOnlyReport, computeRegression, computeContentCollapse, computeReachabilityLoss, evaluateGate, GATE_EXIT } from "./report.js";
 import { writeHtmlReport } from "./html-report.js";
 import { buildUiMapFromMarkers, writeUiMap } from "./ui-map.js";
 import { proposeSelectorMaintenance, validateWebMaintenanceProposal } from "./maintenance-proposal.js";
@@ -55,13 +56,14 @@ function parseArgs(argv) {
     else if (a === "--pr-plan") args.prPlan = argv[++i];
     else if (a === "--project-dir") args.projectDir = argv[++i];
     else if (a === "--maintenance-url") args.maintenanceUrl = argv[++i];
+    else if (a === "--flows-only") args.flowsOnly = true;
     else {
       console.error(`Unknown argument: ${a}`);
       process.exit(2);
     }
   }
-  if (!args.markers) {
-    console.error("Required: --markers <ocqa-markers.txt>");
+  if (!args.markers && !args.flowsOnly) {
+    console.error("Required: --markers <ocqa-markers.txt> (or --flows-only for a gate with no exploration)");
     process.exit(2);
   }
   if (!["gate", "absolute", "any", "high", "medium"].includes(args.failOn)) {
@@ -126,7 +128,7 @@ function parseFlowLog(logPath) {
   const name = logPath.split("/").pop().replace(/\.log$/, "");
   if (!fs.existsSync(logPath)) return { name, passed: false, total: 0, failed: 0, steps: [], missing: true, modelObserved: false, deterministicFailed: false };
   const steps = [];
-  let total = 0, executed = 0, failed = 0, passed = false, sawResult = false, flowName = null, kind = "flow", contract = "", criticality = "";
+  let total = 0, executed = 0, failed = 0, passed = false, sawResult = false, flowName = null, kind = "flow", contract = "", criticality = "", url = "";
   for (const raw of fs.readFileSync(logPath, "utf8").split(/\r?\n/)) {
     const line = raw.trim();
     if (line.startsWith("OCQA_FLOW_STEP:{")) {
@@ -145,6 +147,7 @@ function parseFlowLog(logPath) {
         if (o.kind) kind = o.kind;
         if (o.contract) contract = o.contract;
         if (o.criticality) criticality = o.criticality;
+        if (o.url) url = o.url; // the page the flow actually opened (diagnosable from the report)
         sawResult = true;
       } catch { /* ignore malformed */ }
     }
@@ -160,7 +163,7 @@ function parseFlowLog(logPath) {
   // default deterministic gate. evaluateGate reads these flags, never the raw action string.
   const modelObserved = steps.some((s) => s.action === "assert_ai");
   const deterministicFailed = steps.some((s) => s.action !== "assert_ai" && s.status === "fail");
-  return { name: flowName || name, kind, ...(contract ? { contract, criticality } : {}), passed, total, executed, failed, steps, modelObserved, deterministicFailed };
+  return { name: flowName || name, kind, ...(contract ? { contract, criticality } : {}), ...(url ? { url } : {}), passed, total, executed, failed, steps, modelObserved, deterministicFailed };
 }
 
 function loadBaseline(baselinePath) {
@@ -459,6 +462,7 @@ function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan,
     for (const f of flows) {
       const firstFail = f.steps.find((s) => s.status === "fail");
       lines.push(`- ${f.passed ? "✅" : "❌"} **${f.name}** — ${f.steps.filter((s) => s.status === "pass").length}/${f.total} steps` +
+        (f.url ? ` — \`${f.url}\`` : "") +
         (firstFail ? ` — failed at \`${firstFail.action} ${firstFail.target}\`${firstFail.detail ? `: ${firstFail.detail}` : ""}` : "") +
         (f.missing ? " — log missing (flow did not run)" : ""));
     }
@@ -509,7 +513,9 @@ function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan,
 }
 
 const args = parseArgs(process.argv.slice(2));
-const report = buildQaReport(args.markers, { platform: args.platform || "ios", target: args.label || null });
+const report = args.flowsOnly
+  ? buildFlowsOnlyReport({ platform: args.platform || "ios", target: args.label || null })
+  : buildQaReport(args.markers, { platform: args.platform || "ios", target: args.label || null });
 if (!report) {
   // Required evidence could not be obtained — this is inconclusive (fails closed), not a gate FAIL
   // and not a usage error. See the outcome model in report.js (GATE_EXIT).
@@ -517,7 +523,7 @@ if (!report) {
   process.exit(GATE_EXIT.inconclusive);
 }
 let currentUiMap = null;
-if (args.htmlDir) {
+if (args.htmlDir && !args.flowsOnly) {
   try {
     const map = buildUiMapFromMarkers({ markersPath: args.markers, platform: args.platform || "ios", target: args.label || "", runId: path.basename(args.htmlDir) });
     currentUiMap = map;
@@ -545,7 +551,10 @@ if (baseline?.targetKey && baseline.targetKey !== args.targetKey) {
 if (args.targetKey) report.targetKey = args.targetKey;
 // Content-collapse findings are cross-run by nature — merge them into the current findings
 // BEFORE the regression diff so they count as new-vs-baseline and drive the gate normally.
-const collapsed = [
+// A flows-only run carries no exploration evidence: cross-run collapse/reachability and the
+// findings regression are exploration comparisons and would read "everything resolved" — skip
+// them rather than lie.
+const collapsed = args.flowsOnly ? [] : [
   ...computeContentCollapse(report.screenElementCounts, baseline?.screenElementCounts),
   ...computeReachabilityLoss(report, baseline),
 ];
@@ -560,7 +569,7 @@ if (collapsed.length) {
   // No score/verdict to mutate — exploration is scoreless; the gate renders the outcome.
   report.headline = `${collapsed.length} screen(s) regressed vs. baseline (content collapsed or became unreachable).`;
 }
-const regression = computeRegression(report.findings, baseline?.findings ?? null);
+const regression = args.flowsOnly ? null : computeRegression(report.findings, baseline?.findings ?? null);
 // A baseline captured at a different device/viewport is a layout comparison, not a regression
 // signal: a phone run legitimately hides desktop nav links, so its "resolved" list lies. Keep
 // the diff (new findings still gate) but stamp the mismatch so every consumer can see it.

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

@@ -47,7 +47,7 @@ export const FLOW_ACTIONS = Object.freeze([
   { 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: "wait_for", target: "label / text (+ per-step timeoutMs/timeout; flow-level timeoutMs sets the default)", 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" },
@@ -172,10 +172,12 @@ export class FlowLog {
     }
   }
 
-  finish() {
+  finish(extra = {}) {
     const passed = this.failed === 0 && this.executed > 0;
-    // Keep `passed` first for marker consumers that stream-match the payload.
-    this.emit(`OCQA_FLOW_RESULT:${JSON.stringify({ passed, name: this.flow.name || "flow", kind: this.kind, ...(this.contract ? { contract: this.contract, criticality: this.criticality } : {}), total: this.flow.steps.length, executed: this.executed, failed: this.failed })}`);
-    return { passed, name: this.flow.name || "flow", kind: this.kind, ...(this.contract ? { contract: this.contract, criticality: this.criticality } : {}), total: this.flow.steps.length, executed: this.executed, failed: this.failed, logPath: this.logPath, lines: this.lines };
+    // Keep `passed` first for marker consumers that stream-match the payload. `extra` carries
+    // run context worth diagnosing from the log alone (e.g. the URL the flow actually opened —
+    // field issue #15 was six flows silently replayed against the wrong page).
+    this.emit(`OCQA_FLOW_RESULT:${JSON.stringify({ passed, name: this.flow.name || "flow", kind: this.kind, ...(this.contract ? { contract: this.contract, criticality: this.criticality } : {}), total: this.flow.steps.length, executed: this.executed, failed: this.failed, ...extra })}`);
+    return { passed, name: this.flow.name || "flow", kind: this.kind, ...(this.contract ? { contract: this.contract, criticality: this.criticality } : {}), total: this.flow.steps.length, executed: this.executed, failed: this.failed, ...extra, logPath: this.logPath, lines: this.lines };
   }
 }

package/mcp-server/src/report.js

@@ -31,6 +31,7 @@ export function parseOcqaMarkers(markersFilePath) {
   const issues = [];
   let complete = null;
   let context = null;
+  let requestedMaxActions = null;
 
   for (const line of lines) {
     if (!line.startsWith("OCQA_")) continue;
@@ -59,6 +60,7 @@ export function parseOcqaMarkers(markersFilePath) {
     if (category === "ISSUE") issues.push(parsed);
     if (category === "COMPLETE") complete = parsed;
     if (category === "CONTEXT") context = parsed;
+    if (category === "PROGRESS" && parsed && typeof parsed === "object" && Number.isFinite(parsed.max)) requestedMaxActions = parsed.max;
   }
 
   return {
@@ -75,6 +77,7 @@ export function parseOcqaMarkers(markersFilePath) {
     ),
     complete,
     context,
+    requestedMaxActions,
     actions,
     recentActions: actions.slice(-5),
     recentTransitions: transitions.slice(-5),
@@ -288,9 +291,16 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
   // placeholder anchors, and visible controls do not require a second route. Native exploration
   // retains the stronger multi-screen/action floor. A credentialless single-screen login remains
   // inconclusive so a login wall can never turn into a clean pass.
-  const coverageFloorMet = platform === "web"
-    ? screensExplored >= 1 && actionsPerformed >= 1
-    : screensExplored >= 2 && actionsPerformed >= 3;
+  // An EXPLICITLY small budget scales the floor to the request (issue #18): a --actions 1 run
+  // that performed its one action saw exactly what was asked — that is conclusive evidence of
+  // one action, not "couldn't see enough". A run that undershot even its tiny request (crash at
+  // launch: 0 of 1) stays inconclusive, so the floor's crash-detection job survives.
+  const requestedMax = Number.isFinite(base.requestedMaxActions) ? base.requestedMaxActions : null;
+  const floorActions = platform === "web" ? 1 : 3;
+  const floorScreens = platform === "web" ? 1 : 2;
+  const effectiveFloorActions = requestedMax != null ? Math.min(floorActions, requestedMax) : floorActions;
+  const effectiveFloorScreens = requestedMax != null && requestedMax < floorActions ? 1 : floorScreens;
+  const coverageFloorMet = screensExplored >= effectiveFloorScreens && actionsPerformed >= effectiveFloorActions;
   const unexercisedLoginWall = anySecure && !loginAttempted && screensExplored <= 1;
   const inconclusive = !coverageFloorMet || unexercisedLoginWall || timeBudgetExhausted;
   // "completed" is reserved for a run that exhausted its action budget; a drained frontier is
@@ -572,7 +582,47 @@ export const GATE_EXIT = { pass: 0, fail: 1, error: 2, inconclusive: 3 };
 // finding at or above that severity, and the CLI defaults web targets to `medium` — a 404 in the
 // nav is the release blocker on a website, and a field-tested green PASS over six deterministic
 // findings was exactly the dishonest verdict this product refuses to render.
-export const GATE_POLICY_VERSION = "4";
+export const GATE_POLICY_VERSION = "5";
+
+// A gate run with exploration deliberately not requested (--actions 0): reviewed Flows,
+// scenarios and contracts are the whole deterministic surface. The stub is shaped like an
+// ExplorationRun so every consumer (gate, markdown, HTML, JSON) renders it without special
+// cases, and it says plainly that exploration was not run rather than pretending coverage.
+export function buildFlowsOnlyReport({ platform = "ios", target = null } = {}) {
+  return {
+    kind: "tapp-exploration-run",
+    schemaVersion: 1,
+    runStatus: "not-run",
+    stopReason: "exploration-not-requested",
+    headline: "Exploration not requested (flows-only gate): reviewed suites are the entire deterministic surface of this run.",
+    inconclusive: false,
+    explorationRequested: false,
+    coverage: { screensExplored: 0, actionsPerformed: 0, screens: [] },
+    trace: [],
+    evidence: { markers: null },
+    captureContext: null,
+    uiMap: null,
+    comparison: null,
+    checkedFor: [],
+    notChecked: ["autonomous exploration (not requested: --actions 0 — the gate replays reviewed suites only)"],
+    conditionsNotReached: [],
+    platform,
+    target: typeof target === "string" && target.trim() ? target.trim() : null,
+    screensExplored: 0,
+    actionsPerformed: 0,
+    findingCounts: { critical: 0, high: 0, medium: 0, low: 0, total: 0 },
+    deterministicFindingCounts: { critical: 0, high: 0, medium: 0, low: 0, total: 0 },
+    sampledFindingCounts: { critical: 0, high: 0, medium: 0, low: 0, total: 0 },
+    findings: [],
+    screens: [],
+    screenElementCounts: {},
+    inputFieldsEncountered: [],
+    loginEncountered: false,
+    credentialsProvided: false,
+    credentialsUsed: false,
+    credentialWarning: false,
+  };
+}
 
 // Pure gate evaluator: frozen evidence + policy → a GateRun decision. Extracted verbatim from the
 // former inline logic in ci-report.js so the `[char]` characterization tests keep passing — the
@@ -617,7 +667,14 @@ export function evaluateGate({ report, regression = null, flows = [], scenarios
   if (prPlan?.execution?.notRun) inconclusive(`${prPlan.execution.notRun} selected release contract(s) did not run`);
   if (prPlan?.execution?.explorationFailed) inconclusive(`${prPlan.execution.explorationFailed} planned PR exploration target(s) failed or were not reached`);
 
-  if (failOn === "any") {
+  if (report.explorationRequested === false) {
+    // Flows-only gate (v5): exploration was deliberately not requested, so no exploration-
+    // derived policy applies — the reviewed suites above are the entire decision. An empty
+    // selection proves nothing and must not pass.
+    if (!flows.length && !scenarios.length && !contracts.length) {
+      inconclusive("flows-only gate (--actions 0) selected no flows, scenarios, or contracts — nothing was verified");
+    }
+  } else if (failOn === "any") {
     if (report.findingCounts.total > 0) fail(`${report.findingCounts.total} finding(s) (fail-on: any)`);
     // "any" is the strictest policy — an inconclusive run (evidence not obtained) must never pass it.
     if (report.inconclusive) inconclusive("run was inconclusive (coverage floor not met)");

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

@@ -460,12 +460,35 @@ export async function inspectWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, screensh
       try {
         await page.getByText(requested, { exact: false }).first().waitFor({ state: "visible", timeout: boundedTimeout });
       } catch {
-        throw new Error(`Timed out waiting for visible text “${requested}”`);
+        // The timeout is exactly when the screenshot matters most (field issue #22): the page
+        // may have rendered an error state. Capture what IS there and hand it to the caller.
+        const error = new Error(`Timed out waiting for visible text “${requested}”`);
+        error.timeoutEvidence = {
+          image: screenshot ? await page.screenshot({ type: "png", fullPage: !!fullPage }).catch(() => null) : null,
+          visible: await page.locator("body").innerText({ timeout: 1000 })
+            .then((text) => [...new Set(String(text).split(/\n+/).map((l) => l.trim()).filter((l) => l.length >= 2 && l.length <= 60))].slice(0, 8))
+            .catch(() => []),
+          url: page.url(),
+        };
+        throw error;
       }
       stability = await waitForWebStability(page, { timeoutMs: Math.min(5_000, boundedTimeout) });
     }
     const observed = await page.evaluate(() => {
       const visible = (element) => element.offsetParent !== null;
+      // A control's name is what a screen reader would read: ALL descendant text, shadow roots
+      // included, with spaces between the pieces. Custom card buttons render their title/price
+      // inside nested divs (or a shadow root) — plain textContent ran the pieces together and
+      // came back empty for shadow DOM, so `assert_exists: "$2,000"` had nothing to match
+      // (field issue #19).
+      const accessibleText = (node) => {
+        let out = "";
+        for (const child of (node.shadowRoot || node).childNodes) {
+          if (child.nodeType === Node.TEXT_NODE) out += child.textContent + " ";
+          else if (child.nodeType === Node.ELEMENT_NODE) out += accessibleText(child) + " ";
+        }
+        return out;
+      };
       const controls = [...document.querySelectorAll("button, a[href], input, textarea, select, summary, [role=button], [role=tab], [role=checkbox], [role=switch]")]
         .filter((element) => element.type !== "hidden" && visible(element))
         .slice(0, 80)
@@ -474,7 +497,7 @@ export async function inspectWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, screensh
           const field = ["input", "textarea", "select"].includes(tag);
           const secure = element.type === "password";
           const role = element.getAttribute("role") || (tag === "a" ? "link" : tag === "button" || tag === "summary" ? "button" : "");
-          const label = (element.labels?.[0]?.textContent || element.getAttribute("aria-label") || element.textContent || element.placeholder || element.name || element.id || "").trim().slice(0, 120);
+          const label = (element.labels?.[0]?.textContent || element.getAttribute("aria-label") || accessibleText(element).replace(/\s+/g, " ").trim() || element.placeholder || element.name || element.id || "").trim().slice(0, 120);
           const box = element.getBoundingClientRect();
           return {
             // `type` stays faithful so an agent follows links and presses buttons, not vice versa.

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

@@ -7,6 +7,16 @@ import { loadPlaywright, webContextOptions } from "./web-explorer.js";
 
 const DEFAULT_TIMEOUT = 6000;
 
+// What WAS visible when a wait missed — points a failure report at the fix (renamed label,
+// error state, wrong page) without a separate `tapp tree` run (field issue #20).
+async function visibleLabelsHint(page, limit = 8) {
+  try {
+    const text = await page.locator("body").innerText({ timeout: 1000 });
+    const labels = [...new Set(String(text).split(/\n+/).map((l) => l.trim()).filter((l) => l.length >= 2 && l.length <= 60))].slice(0, limit);
+    return labels.length ? ` — visible: ${labels.join(" · ")}` : "";
+  } catch { return ""; }
+}
+
 async function firstVisible(candidates) {
   for (const locator of candidates) {
     try {
@@ -115,12 +125,27 @@ export async function runWebRequestStep({ step, startUrl, vars = {}, timeout = D
   return { action: "request", target: `${method} ${targetUrl.pathname}`, status: "pass", detail: "" };
 }
 
+// Playwright's timeout errors bury the actual cause ("<div id=…> intercepts pointer events",
+// "element is not visible") in a multi-line retry log; single-line consumers kept only
+// "Timeout 6000ms exceeded" and the report read like the element did not exist (field issue
+// #17). Keep the first line AND name the diagnosable cause on it.
+export function distillPlaywrightFailure(message) {
+  const text = String(message || "");
+  const firstLine = text.split("\n", 1)[0].trim();
+  const cause = text.match(/(<[^>\n]{1,120}>[^\n]{0,80}intercepts pointer events)/)
+    || text.match(/element is (?:not visible|outside of the viewport|not enabled|not stable)[^\n]*/)
+    || text.match(/waiting for element to be visible, enabled and stable[^\n]*/);
+  if (!cause || firstLine.includes(cause[0])) return firstLine;
+  const reason = cause[0].includes("intercepts pointer events") ? `click intercepted by ${cause[0].replace(/\s*intercepts pointer events.*/, "").trim()}` : cause[0].trim();
+  return `${firstLine} — ${reason}`;
+}
+
 export async function executeWebFlowStep({ page, step, vars = {}, defaultTimeout = DEFAULT_TIMEOUT }) {
   const raw = normalizeFlowStep(step);
   const action = raw.action;
   const target = substituteFlowValue(raw.target, vars);
   const value = substituteFlowValue(raw.value, vars);
-  const timeout = Number(raw.params.timeoutMs) || defaultTimeout;
+  const timeout = Number(raw.params.timeoutMs ?? raw.params.timeout) || defaultTimeout;
   let status = "pass";
   let detail = "";
   try {
@@ -154,7 +179,7 @@ export async function executeWebFlowStep({ page, step, vars = {}, defaultTimeout
     } else if (action === "back") {
       await page.goBack({ waitUntil: "domcontentloaded" });
     } else if (action === "wait_for") {
-      if (!await waitForScreen(page, target, timeout)) throw new Error(`‘${target}’ never appeared within ${timeout}ms`);
+      if (!await waitForScreen(page, target, timeout)) throw new Error(`‘${target}’ never appeared within ${timeout}ms${await visibleLabelsHint(page)}`);
     } else if (action === "wait") {
       await page.waitForTimeout(timeout);
     } else if (action === "assert_screen") {
@@ -187,13 +212,34 @@ export async function executeWebFlowStep({ page, step, vars = {}, defaultTimeout
     await settle(page);
   } catch (error) {
     status = "fail";
-    detail = error.message || String(error);
+    detail = distillPlaywrightFailure(error.message || String(error));
   }
   return { action, target: action === "login" ? "sign-in form" : target || value, status, detail, task: raw.task };
 }
 
-export async function runWebFlow({ flow, url, logPath, screenshotDir, playwright, device = "", viewport = "" }) {
-  const startUrl = url || flow.url || (/^https?:\/\//i.test(flow.app || "") ? flow.app : "");
+// The gate targets ONE deployment; a Flow's `url:` names a PAGE of the app, not a deployment.
+// Under a gate url, keep the Flow's path/query/hash but rebase a differing origin onto the
+// gate's: committed Flows carry the origin they were recorded against (a dev port, the prod
+// domain) while the gate may run an ephemeral server — and six flows replaying the gate
+// homepage instead of their own pages was field issue #15.
+export function resolveGateFlowUrl(declared, gateUrl) {
+  if (!declared) return gateUrl || "";
+  if (!gateUrl) return declared;
+  try {
+    const page = new URL(declared);
+    const gate = new URL(gateUrl);
+    if (page.origin === gate.origin) return declared;
+    return new URL(page.pathname + page.search + page.hash, gate.origin).href;
+  } catch {
+    return declared;
+  }
+}
+
+export async function runWebFlow({ flow, url, logPath, screenshotDir, playwright, device = "", viewport = "", urlIsFallback = false }) {
+  // urlIsFallback = the caller is a gate: the Flow's own page wins, rebased onto the gate's
+  // deployment (see resolveGateFlowUrl). An explicit caller url (CLI positional) still overrides.
+  const declaredUrl = flow.url || (/^https?:\/\//i.test(flow.app || "") ? flow.app : "");
+  const startUrl = urlIsFallback ? resolveGateFlowUrl(declaredUrl, url) : (url || declaredUrl);
   if (!startUrl) throw new Error("Web Flow needs `url:` (or an http(s) `app:` value)");
   if (logPath) fs.rmSync(logPath, { force: true });
   const setup = flow.setup || [];
@@ -204,7 +250,7 @@ export async function runWebFlow({ flow, url, logPath, screenshotDir, playwright
   const browser = await pw.chromium.launch({ headless: true });
   const context = await browser.newContext(webContextOptions({ device, viewport, devices: pw.devices }));
   const page = await context.newPage();
-  const timeout = Number(flow.timeoutMs) || DEFAULT_TIMEOUT;
+  const timeout = Number(flow.timeoutMs ?? flow.timeout) || DEFAULT_TIMEOUT;
   page.setDefaultTimeout(timeout);
   const vars = flowVariables(flow);
   let index = 0;
@@ -250,5 +296,5 @@ export async function runWebFlow({ flow, url, logPath, screenshotDir, playwright
     await requestPhase(teardown);
     await browser.close().catch(() => {});
   }
-  return log.finish();
+  return log.finish({ url: startUrl });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.11",
+  "version": "0.17.12",
   "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/ci-gate.sh

@@ -16,7 +16,8 @@
 #   tapp ci        # in an initialized repo: reads .tapp/application-model.json for platform/target
 #                      # omit --url with --project-dir to detect/build/start/stop one owned web target
 #                      # bundle id is detected from the .app when omitted
-#                      [--actions N]              # exploration budget (default 40)
+#                      [--actions N]              # exploration budget (default 40); 0 = flows-only
+#                                                 # gate (replay reviewed suites, no exploration)
 #                      [--timeout S]              # exploration watchdog (default 600)
 #                      [--flows <glob>]           # Flow YAMLs to replay (default: <app repo>/.tapp/flows/*.yml if --project-dir given)
 #                      [--scenarios <glob>]       # Multi-actor Scenario YAMLs (web; default: <app repo>/.tapp/scenarios/*.yml)
@@ -83,7 +84,7 @@ while [[ $# -gt 0 ]]; do
 done
 [[ "$PLATFORM" == "ios" || "$PLATFORM" == "android" || "$PLATFORM" == "web" ]] || { echo "❌ --platform must be ios|android|web" >&2; exit 2; }
 [[ "$PLATFORM" == "ios" && -n "$VIEWPORT" ]] && { echo "❌ --viewport applies to web gates only; on ios --device selects the simulator" >&2; exit 2; }
-[[ "$ACTIONS" =~ ^[1-9][0-9]*$ ]] || { echo "❌ --actions must be a positive integer" >&2; exit 2; }
+[[ "$ACTIONS" =~ ^[0-9]+$ ]] || { echo "❌ --actions must be a non-negative integer (0 = flows-only gate: replay reviewed suites, no exploration)" >&2; exit 2; }
 [[ "$TIMEOUT" =~ ^[1-9][0-9]*$ ]] || { echo "❌ --timeout must be a positive integer" >&2; exit 2; }
 [[ "$FAIL_ON" == "gate" || "$FAIL_ON" == "absolute" || "$FAIL_ON" == "any" || "$FAIL_ON" == "high" || "$FAIL_ON" == "medium" ]] || { echo "❌ --fail-on must be gate|absolute|any|high|medium" >&2; exit 2; }
 if [[ -n "$PROJECT_DIR" ]]; then
@@ -328,6 +329,11 @@ if [[ "${#CONTRACT_FILES[@]}" -gt 0 ]]; then
   done
 fi
 
+if [[ "$ACTIONS" == "0" && "${#FLOW_FILES[@]}" -eq 0 && "${#SCENARIO_FILES[@]}" -eq 0 && "${#CONTRACT_COMPILED_FILES[@]}" -eq 0 ]]; then
+  echo "❌ --actions 0 is a flows-only gate, but no Flows, Scenarios, or Contracts were selected — nothing would be verified. Commit suites under .tapp/ or pass --flows/--scenarios/--contracts." >&2
+  exit 2
+fi
+
 [[ -n "$APP_PATH" && -d "$APP_PATH" ]] || { echo "❌ Required: --app <path/to/App.app> (a simulator build)" >&2; exit 2; }
 if [[ -z "$BUNDLE_ID" ]]; then
   BUNDLE_ID="$(/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "$APP_PATH/Info.plist" 2>/dev/null || true)"
@@ -366,16 +372,23 @@ step "Install $BUNDLE_ID"
 xcrun simctl install "$UDID" "$APP_PATH" || { echo "❌ simctl install failed — is $APP_PATH a SIMULATOR build?" >&2; exit 1; }
 
 # ── Autonomous exploration (quick-capture builds the harness itself if needed).
-step "Explore ($ACTIONS actions, ${TIMEOUT}s watchdog)"
-set +e
+# --actions 0 = flows-only: the reviewed suites are the whole deterministic surface. No
+# explorer touches the app — the point, for targets wired to production backends (#11).
 CAPTURE_ROOT="${TAPP_HOME:-$ROOT}/captures"
 mkdir -p "$CAPTURE_ROOT"
 CAPTURE_DIR="$(mktemp -d "$CAPTURE_ROOT/ci.XXXXXX")"
-TAPP_CAPTURE_DIR="$CAPTURE_DIR" OCQA_PR_TARGET_JSON="$IOS_PR_TARGET_JSON" "$ROOT/scripts/quick-capture.sh" explore "$BUNDLE_ID" --actions "$ACTIONS" --timeout "$TIMEOUT"
-set -e
-MARKERS="$CAPTURE_DIR/ocqa-markers.txt"
-[[ -f "$MARKERS" ]] || { echo "❌ Exploration produced no markers ($MARKERS)" >&2; exit 1; }
-echo "Markers: $MARKERS"
+MARKERS=""
+if [[ "$ACTIONS" == "0" ]]; then
+  step "Explore — skipped (flows-only gate)"
+else
+  step "Explore ($ACTIONS actions, ${TIMEOUT}s watchdog)"
+  set +e
+  TAPP_CAPTURE_DIR="$CAPTURE_DIR" OCQA_PR_TARGET_JSON="$IOS_PR_TARGET_JSON" "$ROOT/scripts/quick-capture.sh" explore "$BUNDLE_ID" --actions "$ACTIONS" --timeout "$TIMEOUT"
+  set -e
+  MARKERS="$CAPTURE_DIR/ocqa-markers.txt"
+  [[ -f "$MARKERS" ]] || { echo "❌ Exploration produced no markers ($MARKERS)" >&2; exit 1; }
+  echo "Markers: $MARKERS"
+fi
 
 # ── Replay committed Flows (each failure becomes a gate reason).
 FLOW_LOG_ARGS=()
@@ -417,6 +430,8 @@ PR_PLAN_ARGS=()
 [[ -n "$PR_PLAN_PATH" ]] && PR_PLAN_ARGS=(--pr-plan "$PR_PLAN_PATH")
 TARGET_KEY_ARGS=()
 [[ -n "$TARGET_KEY" ]] && TARGET_KEY_ARGS=(--target-key "$TARGET_KEY")
-node "$ROOT/mcp-server/src/ci-report.js" --markers "$MARKERS" --fail-on "$FAIL_ON" \
+MODE_ARGS=(--markers "$MARKERS")
+[[ "$ACTIONS" == "0" ]] && MODE_ARGS=(--flows-only)
+node "$ROOT/mcp-server/src/ci-report.js" ${MODE_ARGS[@]+"${MODE_ARGS[@]}"} --fail-on "$FAIL_ON" \
   --html-dir "$CAPTURE_DIR" --label "$BUNDLE_ID" \
   ${BASELINE_ARGS[@]+"${BASELINE_ARGS[@]}"} ${JSON_ARGS[@]+"${JSON_ARGS[@]}"} ${MD_ARGS[@]+"${MD_ARGS[@]}"} ${PR_PLAN_ARGS[@]+"${PR_PLAN_ARGS[@]}"} ${TARGET_KEY_ARGS[@]+"${TARGET_KEY_ARGS[@]}"} ${FLOW_LOG_ARGS[@]+"${FLOW_LOG_ARGS[@]}"}

package/scripts/flow_lib.py

@@ -18,7 +18,14 @@ def load_flow(path):
     raw = open(path, encoding="utf-8").read()
     if path.endswith(".json"):
         return json.loads(raw)
-    import yaml
+    try:
+        import yaml
+    except ModuleNotFoundError:
+        # Hosted macOS runners ship python3 without PyYAML (field issue #16); a raw
+        # ModuleNotFoundError reads like a tapp crash instead of a one-line fix.
+        sys.exit("tapp flow replay needs PyYAML to read YAML Flows: run `python3 -m pip install pyyaml` "
+                 "(on GitHub macOS runners: `pip3 install pyyaml`), or commit the Flow as .json. "
+                 "`tapp doctor` checks this.")
     return yaml.safe_load(raw)
 
 

package/scripts/platform-gate.js

@@ -9,7 +9,7 @@ import { fileURLToPath } from "node:url";
 import { runQaAndroid, runQaWeb, startManagedWebTarget, stopManagedWebTarget } from "../mcp-server/src/index.js";
 import { runAndroidFlow } from "../mcp-server/src/android-flow.js";
 import { inferFlowPlatform, loadFlowFile } from "../mcp-server/src/flow-runtime.js";
-import { runWebFlow } from "../mcp-server/src/web-flow.js";
+import { runWebFlow, resolveGateFlowUrl } from "../mcp-server/src/web-flow.js";
 import { runWebScenario, validateScenario } from "../mcp-server/src/scenario-runtime.js";
 import { compileReleaseContract, loadReleaseContractFile } from "../mcp-server/src/release-contract.js";
 import { prExplorationTargetsFromPlan } from "../mcp-server/src/pr-selection.js";
@@ -126,8 +126,16 @@ try {
   }
   if (args.platform === "web" && !args.url) {
     exitCode = 2;
+  } else if (args.actions === 0 && !selectedFlows.length && !selectedScenarios.length && !selectedContracts.length) {
+    console.error("❌ --actions 0 is a flows-only gate, but no Flows, Scenarios, or Contracts were selected — nothing would be verified.");
+    exitCode = 2;
   } else {
-    const qa = args.platform === "web"
+    // --actions 0: flows-only — no explorer touches the target (it may be production, #11).
+    // The reviewed suites are the whole deterministic surface; ci-report gets --flows-only.
+    const flowsOnly = args.actions === 0;
+    const qa = flowsOnly
+      ? { structured: { capture: { path: fs.mkdtempSync(path.join(os.tmpdir(), `tapp-ci-${args.platform}-flows-only-`)) } } }
+      : args.platform === "web"
       ? await runQaWeb({ url: args.url, maxActions: args.actions, timeout: args.timeout, testEmail: process.env.OCQA_TEST_EMAIL, testPassword: process.env.OCQA_TEST_PASSWORD, seedTargets: prExplorationTargets, device: args.device || "", viewport: args.viewport || "" })
       : await runQaAndroid({ appId: args.appId, apkPath: args.apk, serial: args.serial, maxActions: args.actions, timeout: args.timeout,
           testEmail: process.env.OCQA_TEST_EMAIL, testPassword: process.env.OCQA_TEST_PASSWORD, seedTargets: prExplorationTargets });
@@ -142,7 +150,7 @@ try {
   const logPath = path.join(os.tmpdir(), `tapp-ci-${args.platform}-${path.basename(flowPath).replace(/\.ya?ml$/i, "")}-${Date.now()}.log`);
   const evidenceDir = path.join(captureDir, "flows", path.basename(flowPath).replace(/\.ya?ml$/i, ""));
   try {
-    if (args.platform === "web") await runWebFlow({ flow, url: args.url, logPath, screenshotDir: evidenceDir });
+    if (args.platform === "web") await runWebFlow({ flow, url: args.url, urlIsFallback: true, logPath, screenshotDir: evidenceDir });
     else await runAndroidFlow({ flow, appId: args.appId, apkPath: undefined, serial: args.serial, logPath, screenshotDir: evidenceDir });
   } catch (error) {
     fs.writeFileSync(logPath, `OCQA_FLOW_RESULT:${JSON.stringify({ passed: false, total: flow.steps.length, failed: 1, error: error.message || String(error) })}\n`);
@@ -153,7 +161,7 @@ try {
   const logPath = path.join(os.tmpdir(), `tapp-ci-scenario-${path.basename(scenarioPath).replace(/\.ya?ml$/i, "")}-${Date.now()}.log`);
   const evidenceDir = path.join(captureDir, "scenarios", path.basename(scenarioPath).replace(/\.ya?ml$/i, ""));
   try {
-    await runWebScenario({ scenario, url: args.url, logPath, screenshotDir: evidenceDir });
+    await runWebScenario({ scenario, url: resolveGateFlowUrl(scenario.url, args.url), logPath, screenshotDir: evidenceDir });
   } catch (error) {
     fs.writeFileSync(logPath, `OCQA_FLOW_RESULT:${JSON.stringify({ passed: false, name: scenario.name, kind: "scenario", total: scenario.steps.length, executed: 0, failed: 1, error: error.message || String(error) })}\n`);
   }
@@ -164,8 +172,8 @@ try {
   const logPath = path.join(os.tmpdir(), `tapp-ci-contract-${stem}-${Date.now()}.log`);
   const evidenceDir = path.join(captureDir, "contracts", stem);
   try {
-    if (execution.kind === "scenario") await runWebScenario({ scenario: execution, url: args.url, logPath, screenshotDir: evidenceDir });
-    else if (args.platform === "web") await runWebFlow({ flow: execution, url: args.url, logPath, screenshotDir: evidenceDir });
+    if (execution.kind === "scenario") await runWebScenario({ scenario: execution, url: resolveGateFlowUrl(execution.url, args.url), logPath, screenshotDir: evidenceDir });
+    else if (args.platform === "web") await runWebFlow({ flow: execution, url: args.url, urlIsFallback: true, logPath, screenshotDir: evidenceDir });
     else await runAndroidFlow({ flow: execution, appId: args.appId, apkPath: undefined, serial: args.serial, logPath, screenshotDir: evidenceDir });
   } catch (error) {
     fs.writeFileSync(logPath, `OCQA_FLOW_RESULT:${JSON.stringify({ passed: false, name: contract.title, kind: "release-contract", contract: contract.name, criticality: contract.criticality, total: execution.steps.length, executed: 0, failed: 1, error: error.message || String(error) })}\n`);
@@ -173,7 +181,8 @@ try {
         flowLogs.push({ kind: "contract", path: logPath });
       }
 
-      const reportArgs = [path.join(root, "mcp-server", "src", "ci-report.js"), "--markers", markers, "--platform", args.platform,
+      const reportArgs = [path.join(root, "mcp-server", "src", "ci-report.js"),
+        ...(flowsOnly ? ["--flows-only"] : ["--markers", markers]), "--platform", args.platform,
         "--fail-on", args.failOn, "--html-dir", captureDir, "--label", args.url || args.appId];
       if (args.targetKey) reportArgs.push("--target-key", args.targetKey);
       if (args.baseline) reportArgs.push("--baseline", args.baseline);