@aarwitz/tapp 0.15.0

package/scripts/corpus-sweep.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# Corpus sweep — run a list of real open-source iOS apps through the tapp pipeline and
+# produce a friction scoreboard. Failures ARE the data: every app gets a row recording
+# how far it got (clone → detect → build → install → explore) and why it stopped.
+#
+# Usage: scripts/corpus-sweep.sh <urls-file> [--actions N] [--out <dir>]
+#   urls-file: one git URL per line (# comments ok)
+#
+# Needs a booted simulator. Rows land in <out>/scoreboard.tsv; per-app logs in <out>/<app>/.
+set -uo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+URLS_FILE="${1:?usage: corpus-sweep.sh <urls-file> [--actions N] [--out dir]}"; shift
+ACTIONS=25
+OUT="/tmp/tapp-corpus"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --actions) ACTIONS="$2"; shift 2 ;;
+    --out) OUT="$2"; shift 2 ;;
+    *) echo "unknown arg $1" >&2; exit 2 ;;
+  esac
+done
+mkdir -p "$OUT"
+BOARD="$OUT/scoreboard.tsv"
+[[ -f "$BOARD" ]] || echo -e "app\tstage\tbackend_signals\tbundle\tscreens\tactions\tfindings\tverdict\tnote" > "$BOARD"
+
+UDID="$(xcrun simctl list devices booted -j | 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"), ""))')"
+[[ -n "$UDID" ]] || { echo "❌ boot a simulator first" >&2; exit 1; }
+
+row() { echo -e "$1\t$2\t$3\t$4\t$5\t$6\t$7\t$8\t$9" >> "$BOARD"; }
+
+# Cheap backend-class signals from the repo tree (feeds the classifier's rules).
+backend_signals() {
+  local dir="$1" sig=()
+  [[ -n "$(find "$dir" -maxdepth 4 -name 'GoogleService-Info.plist' -print -quit 2>/dev/null)" ]] && sig+=("firebase-plist")
+  grep -rqli "firebase" "$dir"/Podfile "$dir"/*/Package.resolved "$dir"/Package.resolved 2>/dev/null && sig+=("firebase-dep")
+  grep -rqli "supabase" "$dir"/Podfile "$dir"/*/Package.resolved "$dir"/Package.resolved 2>/dev/null && sig+=("supabase-dep")
+  [[ -n "$(find "$dir" -maxdepth 2 -name 'docker-compose.y*ml' -print -quit 2>/dev/null)" ]] && sig+=("in-repo-backend")
+  grep -rqli "mastodon" "$dir"/Package.resolved 2>/dev/null && sig+=("mastodon-client")
+  grep -rql "YOUR_API_KEY\|INSERT_API_KEY\|<API_KEY>" --include="*.xcconfig" --include="*.plist" --include="*.swift" "$dir" 2>/dev/null | head -1 | grep -q . && sig+=("key-placeholder")
+  local IFS=","; echo "${sig[*]:-none}"
+}
+
+# fd 3 for the URL list — xcodebuild/git inside the loop consume stdin and would
+# silently swallow the remaining lines (this truncated the first sweep run).
+while IFS= read -r url <&3; do
+  [[ -z "$url" || "$url" == \#* ]] && continue
+  name="$(basename "$url" .git)"
+  dir="$OUT/$name"
+  log="$OUT/$name.log"
+  echo "━━━ $name"
+
+  # 1. clone
+  if [[ ! -d "$dir" ]]; then
+    git clone --depth 1 --recurse-submodules --shallow-submodules "$url" "$dir" >"$log" 2>&1 \
+      || { row "$name" clone none - - - - - "git clone failed"; continue; }
+  fi
+  signals="$(backend_signals "$dir")"
+
+  # 2. detect workspace/project + scheme (workspace wins; ignore Pods)
+  target="$(find "$dir" -maxdepth 3 -name '*.xcworkspace' -not -path '*/Pods/*' -not -path '*/.*' | head -1)"
+  flag="-workspace"
+  if [[ -z "$target" ]]; then
+    target="$(find "$dir" -maxdepth 3 -name '*.xcodeproj' -not -path '*/Pods/*' | head -1)"
+    flag="-project"
+  fi
+  [[ -n "$target" ]] || { row "$name" detect "$signals" - - - - - "no xcworkspace/xcodeproj found"; continue; }
+  schemes="$(xcodebuild -list -json $flag "$target" 2>>"$log" | python3 -c 'import sys,json
+try:
+  d=json.load(sys.stdin); o=d.get("workspace") or d.get("project") or {}
+  print("\n".join(o.get("schemes") or []))
+except Exception: pass')"
+  # Prefer an explicitly-iOS scheme (multi-platform repos like NetNewsWire name-match the
+  # macOS scheme first, which can't build for an iOS Simulator destination).
+  scheme="$(echo "$schemes" | grep -i "ios" | grep -iv "test\|widget\|extension\|notification\|clip" | head -1)"
+  [[ -z "$scheme" ]] && scheme="$(echo "$schemes" | grep -ix "$name" | head -1)"
+  [[ -z "$scheme" ]] && scheme="$(echo "$schemes" | grep -iv "test\|uitests\|widget\|extension\|notification\|clip\|watch\|mac" | head -1)"
+  [[ -z "$scheme" ]] && scheme="$(echo "$schemes" | head -1)"
+  [[ -n "$scheme" ]] || { row "$name" detect "$signals" - - - - - "no schemes listed"; continue; }
+  echo "  scheme: $scheme"
+
+  # 3. build for simulator (20 min cap; perl alarm — stock macOS has no `timeout`)
+  dd="$OUT/dd-$name"
+  if ! perl -e 'alarm shift; exec @ARGV' 1200 xcodebuild $flag "$target" -scheme "$scheme" \
+      -destination 'generic/platform=iOS Simulator' -derivedDataPath "$dd" \
+      CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO CODE_SIGNING_ALLOWED=NO \
+      build >>"$log" 2>&1; then
+    reason="$(grep -m1 -E "error: |xcodebuild: error" "$log" | tail -c 120 || true)"
+    row "$name" build "$signals" - - - - - "build failed: ${reason:-see log}"
+    continue
+  fi
+  app="$(find "$dd/Build/Products" -maxdepth 2 -name '*.app' -path '*iphonesimulator*' | head -1)"
+  [[ -n "$app" ]] || { row "$name" build "$signals" - - - - - "built but no simulator .app (macOS-only scheme?)"; continue; }
+  bundle="$(/usr/libexec/PlistBuddy -c 'Print CFBundleIdentifier' "$app/Info.plist" 2>/dev/null || echo "?")"
+
+  # 4. install
+  xcrun simctl install "$UDID" "$app" >>"$log" 2>&1 \
+    || { row "$name" install "$signals" "$bundle" - - - - "simctl install failed"; continue; }
+
+  # 5. explore + report
+  "$ROOT/scripts/quick-capture.sh" explore "$bundle" --actions "$ACTIONS" --timeout 420 >>"$log" 2>&1
+  cap="$(ls -td "$ROOT"/captures/*/ 2>/dev/null | head -1)"
+  if [[ ! -f "$cap/ocqa-markers.txt" ]]; then
+    row "$name" explore "$signals" "$bundle" - - - - "exploration produced no markers"
+    continue
+  fi
+  json="$OUT/$name-report.json"
+  node "$ROOT/mcp-server/src/ci-report.js" --markers "$cap/ocqa-markers.txt" --json-out "$json" >>"$log" 2>&1 || true
+  read -r screens acted findings verdict <<< "$(python3 -c "
+import json,sys
+try:
+  r=json.load(open('$json'))
+  print(r.get('screensExplored','?'), r.get('actionsPerformed','?'), r.get('findingCounts',{}).get('total','?'), r.get('verdict','?'))
+except Exception: print('? ? ? ?')")"
+  row "$name" explored "$signals" "$bundle" "$screens" "$acted" "$findings" "$verdict" "capture: $(basename "$cap")"
+  echo "  ✅ $verdict — $screens screens"
+done 3< "$URLS_FILE"
+
+echo ""
+echo "═══ scoreboard: $BOARD ═══"
+column -t -s $'\t' "$BOARD"

package/scripts/coverage-eval.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# AutoTap penetration / coverage eval — the "real-app scoreboard".
+#
+# Unlike validation-matrix.sh (which asserts *expected findings* against DemoApp, i.e. accuracy on a
+# known fixture), this measures how far AutoTap actually PENETRATES an arbitrary app: did it get past
+# launch, did it hit a login wall, how many distinct screens it reached, how much of its budget went
+# to productive exploration vs. stuck/recovery flailing, and what it found. There is no ground truth —
+# this is a diagnostic you point at real apps to see where they stall, so coverage work is measurable.
+#
+# Usage:
+#   scripts/coverage-eval.sh [bundleId ...]        # defaults to the local corpus apps
+#   scripts/coverage-eval.sh com.acme.app          # a real app (must be installed on the booted sim)
+#   ACTIONS=120 scripts/coverage-eval.sh com.acme.app
+#   VISION_ESCALATION=1 ANTHROPIC_API_KEY=... scripts/coverage-eval.sh com.acme.app
+#     # opt-in: when the a11y tree goes blank or exploration gets stuck, a sidecar
+#     # (vision_escalation_responder.py) answers the harness's OCQA_VISION_QUERY with a
+#     # model-chosen next move — same channel the desktop app serves.
+#
+# Prereqs: a booted simulator, the harness built (scripts/deploy-and-build.sh --harness), and each
+# app installed on the sim. Writes a JSON report to captures/coverage-eval-<timestamp>.json.
+#
+# NOTE: auth sessions stored in the keychain (Firebase et al) SURVIVE app reinstall — a "fresh"
+# run may silently resume the previous account. For a genuinely fresh login:
+#   xcrun simctl keychain <udid> reset
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+ACTIONS="${ACTIONS:-70}"
+TIMEOUT="${TIMEOUT:-600}"
+DEFAULT_APPS=(com.autotap.demoapp com.autotap.logindemo com.autotap.wizarddemo com.autotap.shopdemo com.autotap.restaurantdemo)
+APPS=("$@"); [ ${#APPS[@]} -eq 0 ] && APPS=("${DEFAULT_APPS[@]}")
+
+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. Boot one first."; exit 2; }
+
+XCTR="$(find "$HOME/Library/Developer/Xcode/DerivedData/OCQAHarness-"*/Build/Products -name '*.xctestrun' 2>/dev/null | head -1)"
+[ -z "$XCTR" ] && XCTR="$(find /tmp/autotap-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: scripts/deploy-and-build.sh --harness"; exit 2; }
+
+TS="$(date +%Y%m%d-%H%M%S)"
+REPORT="$ROOT/captures/coverage-eval-$TS.json"
+mkdir -p "$ROOT/captures"
+echo "AutoTap coverage eval — $ACTIONS actions/app, sim $UDID"
+echo "Apps: ${APPS[*]}"
+echo ""
+
+RESULTS_JSON="["
+FIRST=1
+for APP in "${APPS[@]}"; do
+  if ! xcrun simctl get_app_container "$UDID" "$APP" >/dev/null 2>&1; then
+    printf "  %-32s ⏭  not installed — skipping\n" "$APP"
+    continue
+  fi
+  CFG="/tmp/ocqa-coverage-$APP.json"
+  LOG="/tmp/ocqa-coverage-$APP.log"
+  RESPONDER_PID=""
+  # Real test credentials (OCQA_TEST_EMAIL / OCQA_TEST_PASSWORD env) let the heuristic login
+  # preamble get PAST a real auth wall — the single biggest coverage unlock on gated apps.
+  CREDS_LINE=""
+  [ -n "${OCQA_TEST_EMAIL:-}" ] && CREDS_LINE=",
+  \"OCQA_TEST_EMAIL\": \"$OCQA_TEST_EMAIL\", \"OCQA_TEST_PASSWORD\": \"${OCQA_TEST_PASSWORD:-}\""
+  if [ "${VISION_ESCALATION:-0}" = "1" ] && [ -n "${ANTHROPIC_API_KEY:-}" ]; then
+    VRESP="/tmp/ocqa-vision-response-eval-$APP.json"
+    VDIR="/tmp/ocqa-vision-eval-$APP"; mkdir -p "$VDIR"
+    cat > "$CFG" <<JSON
+{ "OCQA_BUNDLE_ID": "$APP", "OCQA_MAX_ACTIONS": "$ACTIONS", "OCQA_TIMEOUT_SECONDS": "$TIMEOUT",
+  "OCQA_VISION_ESCALATION": "1", "OCQA_VISION_RESPONSE_PATH": "$VRESP",
+  "OCQA_VISION_IMAGE_DIR": "$VDIR", "OCQA_VISION_BUDGET": "4", "OCQA_VISION_WAIT_TIMEOUT": "60"$CREDS_LINE }
+JSON
+    : > "$LOG"
+    python3 "$ROOT/scripts/vision_escalation_responder.py" "$LOG" "$VRESP" > "/tmp/ocqa-vision-responder-$APP.log" 2>&1 &
+    RESPONDER_PID=$!
+  else
+    cat > "$CFG" <<JSON
+{ "OCQA_BUNDLE_ID": "$APP", "OCQA_MAX_ACTIONS": "$ACTIONS", "OCQA_TIMEOUT_SECONDS": "$TIMEOUT"$CREDS_LINE }
+JSON
+  fi
+  TEST_RUNNER_OCQA_CONFIG_PATH="$CFG" xcodebuild test-without-building \
+    -xctestrun "$XCTR" -destination "platform=iOS Simulator,id=$UDID" \
+    -only-testing:"OCQAHarnessUITests/ExplorerTests/testAutonomousExploration" > "$LOG" 2>&1
+  if [ -n "$RESPONDER_PID" ]; then kill "$RESPONDER_PID" 2>/dev/null; wait "$RESPONDER_PID" 2>/dev/null; fi
+
+  ROW="$(python3 "$ROOT/scripts/coverage_eval_parse.py" "$LOG" "$APP")"
+  echo "$ROW" | python3 -c 'import sys,json; d=json.load(sys.stdin); ca=d.get("crash_action") or {}; print("  %-32s screens=%-3s launch=%-3s login_wall=%-3s stuck=%-4s findings=%s%s" % (d["app"], d["screens"], "ok" if d["launch_ok"] else "NO", "YES" if d["login_wall"] else "no", d["stuck_ratio"], d["findings_total"], ("  ⚠️ CRASHED on %s %s" % (ca.get("type",""), ca.get("screen","")) if d.get("crashed") else "")))'
+  [ $FIRST -eq 0 ] && RESULTS_JSON+=","
+  RESULTS_JSON+="$ROW"; FIRST=0
+done
+RESULTS_JSON+="]"
+echo "$RESULTS_JSON" | python3 -m json.tool > "$REPORT" 2>/dev/null || echo "$RESULTS_JSON" > "$REPORT"
+echo ""
+echo "Report: $REPORT"

package/scripts/coverage_eval_parse.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Parse a harness exploration log into penetration/coverage diagnostics for the coverage eval.
+Emits one JSON object describing how far AutoTap got into the app. No ground truth — diagnostics only."""
+import sys, re, json
+
+log = open(sys.argv[1], encoding="utf-8", errors="replace").read()
+app = sys.argv[2] if len(sys.argv) > 2 else "?"
+
+# Reasons / action types that mean "flailing to escape / not making forward progress".
+RECOVERY_REASONS = ("escape", "exhausted", "blind", "stuck", "discover", "drawer",
+                    "carousel", "probe", "dismiss", "recovery", "back_failed", "trap", "rotation")
+RECOVERY_TYPES = {"back", "swipe_dismiss", "tab_rotation", "forced_escape", "swipe_back", "swipe"}
+
+screens, findings, actions = set(), {}, 0
+recovery_actions = 0
+saw_secure_field = False
+completed = False
+test_failed = False
+last_action = None  # (type, screen, step) of the most recent action
+
+for line in log.splitlines():
+    m = re.search(r"OCQA_STATE:(\{.*\})", line)
+    if m:
+        try:
+            d = json.loads(m.group(1))
+            s = (d.get("screen") or "").strip()
+            if s and s not in ("Unknown", "pending"):
+                screens.add(s)
+            for inp in d.get("inputs", []) or []:
+                if inp.get("secure"):
+                    saw_secure_field = True
+        except Exception:
+            pass
+        continue
+    m = re.search(r"OCQA_ACTION:(\{.*\})", line)
+    if m:
+        actions += 1
+        try:
+            d = json.loads(m.group(1))
+            reason = str(d.get("reason", "")).lower()
+            atype = str(d.get("type", "")).lower()
+            last_action = (atype, (d.get("screen") or "").strip(), d.get("step"))
+            if atype in RECOVERY_TYPES or any(k in reason for k in RECOVERY_REASONS):
+                recovery_actions += 1
+        except Exception:
+            pass
+        continue
+    m = re.search(r"OCQA_ISSUE:(\{.*\})", line)
+    if m:
+        try:
+            t = json.loads(m.group(1)).get("type", "unknown")
+            findings[t] = findings.get(t, 0) + 1
+        except Exception:
+            pass
+        continue
+    if line.startswith("OCQA_COMPLETE"):
+        completed = True
+    elif "TEST EXECUTE FAILED" in line or re.search(r"Executed 1 test, with [1-9]\d* failure", line):
+        test_failed = True
+
+# ---- Host-side crash detection ----
+# A crash DURING an action kills the test's connection to the app and aborts the harness before
+# any in-harness detector can run (found on Wikipedia: WMFCaptchaViewController.refreshImage
+# assertionFailure crashes the app on login). The signal is unambiguous: the test FAILED and the
+# harness never emitted OCQA_COMPLETE, with actions performed — i.e. it died mid-run. Attribute the
+# crash to the last action and surface it as a critical finding (the whole point of the tool).
+crashed = test_failed and not completed and actions > 0
+if crashed and "crash" not in findings:
+    findings["crash"] = findings.get("crash", 0) + 1
+
+n_screens = len(screens)
+launch_ok = n_screens >= 2
+# Login wall: a password field was present but the explorer never got past a handful of screens.
+login_present = saw_secure_field
+login_wall = login_present and n_screens <= 3
+stuck_ratio = round(recovery_actions / actions, 2) if actions else 0.0
+findings_total = sum(findings.values())
+
+print(json.dumps({
+    "app": app,
+    "screens": n_screens,
+    "screen_names": sorted(screens),
+    "launch_ok": launch_ok,
+    "login_present": login_present,
+    "login_wall": login_wall,
+    "actions": actions,
+    "recovery_actions": recovery_actions,
+    "stuck_ratio": stuck_ratio,           # 0=all productive, 1=all flailing
+    "findings_total": findings_total,
+    "findings_by_type": findings,
+    "completed": completed,
+    "crashed": crashed,
+    "crash_action": ({"type": last_action[0], "screen": last_action[1], "step": last_action[2]}
+                     if crashed and last_action else None),
+}))

package/scripts/deploy-and-build.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Build AutoTap locally on this Mac
+# Usage: ./scripts/deploy-and-build.sh [--harness] [--clean]
+#   --harness  Also build the OCQAHarness XCUITest bundle
+#   --clean    Clean derived data before building
+
+PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+BUILD_HARNESS=0
+DO_CLEAN=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --harness) BUILD_HARNESS=1 ;;
+    --clean) DO_CLEAN=1 ;;
+  esac
+done
+
+echo "=== AutoTap Local Build ==="
+echo "Project: $PROJECT_ROOT"
+echo ""
+
+if [[ $DO_CLEAN -eq 1 ]]; then
+  echo "Cleaning derived data..."
+  rm -rf "$PROJECT_ROOT/build/DerivedData"
+  rm -rf /tmp/autotap-harness-derived
+  echo ""
+fi
+
+# Step 1: Generate Xcode project if needed
+if [[ ! -f "$PROJECT_ROOT/AutoTap.xcodeproj/project.pbxproj" ]] || \
+   [[ "$PROJECT_ROOT/generate-xcodeproj.rb" -nt "$PROJECT_ROOT/AutoTap.xcodeproj/project.pbxproj" ]]; then
+  echo "Generating Xcode project..."
+  cd "$PROJECT_ROOT" && ruby generate-xcodeproj.rb
+  echo ""
+fi
+
+# Step 2: Build main app
+echo "Building AutoTap..."
+xcodebuild \
+  -project "$PROJECT_ROOT/AutoTap.xcodeproj" \
+  -scheme AutoTap \
+  -configuration Debug \
+  -derivedDataPath "$PROJECT_ROOT/build/DerivedData" \
+  CODE_SIGN_IDENTITY=- \
+  CODE_SIGNING_REQUIRED=NO \
+  CODE_SIGNING_ALLOWED=NO \
+  2>&1 | tail -20
+
+echo ""
+
+# Step 3: Build harness if requested
+if [[ $BUILD_HARNESS -eq 1 ]]; then
+  echo "Building OCQAHarness..."
+
+  # Generate harness xcodeproj if needed
+  if [[ ! -f "$PROJECT_ROOT/Harness/OCQAHarness.xcodeproj/project.pbxproj" ]] || \
+     [[ "$PROJECT_ROOT/Harness/generate-harness-xcodeproj.rb" -nt "$PROJECT_ROOT/Harness/OCQAHarness.xcodeproj/project.pbxproj" ]]; then
+    cd "$PROJECT_ROOT/Harness" && ruby generate-harness-xcodeproj.rb
+  fi
+
+  # Prefer a booted simulator by UDID to avoid ambiguity when the same device
+  # name exists across multiple OS runtimes (e.g. "iPhone 16 Pro" on iOS 18 + 26).
+  SIM_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"), ""))' 2>/dev/null || true)
+
+  if [[ -n "$SIM_UDID" ]]; then
+    SIM_DEST="platform=iOS Simulator,id=$SIM_UDID"
+    echo "  Target simulator: $SIM_UDID (booted)"
+  else
+    SIM_NAME=$(xcrun simctl list devices available | grep -E 'iPhone.*(Booted|Shutdown)' | head -1 | sed 's/ (.*//' | xargs)
+    SIM_NAME=${SIM_NAME:-"iPhone 16 Pro"}
+    SIM_DEST="platform=iOS Simulator,name=$SIM_NAME"
+    echo "  Target simulator: $SIM_NAME"
+  fi
+
+  xcodebuild build-for-testing \
+    -project "$PROJECT_ROOT/Harness/OCQAHarness.xcodeproj" \
+    -scheme OCQAHarnessUITests \
+    -destination "$SIM_DEST" \
+    -derivedDataPath "/tmp/autotap-harness-derived" \
+    2>&1 | tail -5
+
+  echo ""
+  echo "Harness built. Quick capture:"
+  echo "  ./scripts/quick-capture.sh explore com.autotap.demoapp --actions 25"
+  echo "  ./scripts/quick-capture.sh screenshot"
+  echo "  ./scripts/quick-capture.sh tree com.autotap.demoapp"
+fi
+
+echo ""
+APP_PATH="$PROJECT_ROOT/build/DerivedData/Build/Products/Debug/AutoTap.app"
+if [[ -d "$APP_PATH" ]]; then
+  echo "Build artifact: $APP_PATH"
+  echo "Run: open $APP_PATH"
+else
+  echo "(check build output above for errors)"
+fi

package/scripts/flow-platform.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Resolve a Flow's target without executing it. Legacy target-less Flows are
+// iOS because that was Tapp's only driver when their format was introduced.
+import path from "node:path";
+import { inferFlowPlatform, loadFlowFile } from "../mcp-server/src/flow-runtime.js";
+
+const input = process.argv[2] ? path.resolve(process.argv[2]) : "";
+if (!input) {
+  console.error("usage: flow-platform.js <flow.yml|flow.json>");
+  process.exit(2);
+}
+
+try {
+  process.stdout.write(inferFlowPlatform(loadFlowFile(input)));
+} catch (error) {
+  console.error(error.message || String(error));
+  process.exit(2);
+}

package/scripts/flow_ai_judge.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Host-side judge for a Flow's `assert_ai` steps (see docs/flows-architecture.md).
+
+Tails the harness log for OCQA_FLOW_AI_QUERY markers, shows the screenshot + the claim to a vision
+model, and writes {index, pass, reason} to the response file the harness polls. The model call stays
+HOST-side (the harness only screenshots + asks). On any error it writes pass=false with the error so
+a broken judge can't silently green a flow.
+
+Usage: ANTHROPIC_API_KEY=... python3 flow_ai_judge.py <harness.log> <response_path>
+"""
+import base64
+import json
+import os
+import ssl
+import sys
+import time
+import urllib.request
+
+
+def _ctx():
+    try:
+        import certifi
+        return ssl.create_default_context(cafile=certifi.where())
+    except Exception:
+        return ssl.create_default_context()
+
+
+SSL_CTX = _ctx()
+MODEL = os.environ.get("AUTOTAP_VISION_MODEL", "claude-haiku-4-5-20251001")
+SYSTEM = (
+    "You are a QA test oracle. You are shown one iOS app screenshot and a CLAIM the test asserts about "
+    "it. Decide if the claim is TRUE of what is actually visible. Be strict and literal — only pass if "
+    "the screenshot clearly supports the claim. Respond with ONLY JSON: "
+    '{"pass": true|false, "reason": "<one concise sentence>"}.'
+)
+
+
+def judge(image_path, claim, key):
+    with open(image_path, "rb") as f:
+        b64 = base64.b64encode(f.read()).decode()
+    body = {
+        "model": MODEL, "max_tokens": 200, "system": SYSTEM,
+        "messages": [{"role": "user", "content": [
+            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": b64}},
+            {"type": "text", "text": f"CLAIM: {claim}\nIs this claim true of the screenshot? Respond as the JSON object."},
+        ]}],
+    }
+    req = urllib.request.Request("https://api.anthropic.com/v1/messages", data=json.dumps(body).encode(),
+                                 method="POST", headers={"x-api-key": key, "anthropic-version": "2023-06-01",
+                                                         "content-type": "application/json"})
+    with urllib.request.urlopen(req, timeout=45, context=SSL_CTX) as resp:
+        data = json.load(resp)
+    text = "\n".join(b.get("text", "") for b in data.get("content", []) if b.get("type") == "text")
+    s, e = text.find("{"), text.rfind("}")
+    obj = json.loads(text[s:e + 1]) if s >= 0 and e > s else {}
+    return bool(obj.get("pass", False)), str(obj.get("reason", ""))[:200]
+
+
+def main():
+    if len(sys.argv) < 3:
+        print("usage: flow_ai_judge.py <harness.log> <response_path>", file=sys.stderr)
+        return 2
+    log_path, response_path = sys.argv[1], sys.argv[2]
+    key = os.environ.get("ANTHROPIC_API_KEY", "")
+    if not key:
+        return 2
+    handled = set()
+    pos = 0
+    while True:
+        time.sleep(0.4)
+        try:
+            with open(log_path, errors="ignore") as f:
+                f.seek(pos)
+                chunk = f.read()
+                pos = f.tell()
+        except FileNotFoundError:
+            continue
+        for line in chunk.splitlines():
+            i = line.find("OCQA_FLOW_AI_QUERY:{")
+            if i < 0:
+                continue
+            try:
+                q = json.loads(line[i + len("OCQA_FLOW_AI_QUERY:"):])
+            except Exception:
+                continue
+            idx = q.get("index")
+            if idx in handled:
+                continue
+            handled.add(idx)
+            try:
+                ok, reason = judge(q.get("image", ""), q.get("claim", ""), key)
+            except Exception as ex:
+                ok, reason = False, f"judge error: {ex}"
+            tmp = response_path + ".tmp"
+            with open(tmp, "w") as f:
+                json.dump({"index": idx, "pass": ok, "reason": reason}, f)
+            os.replace(tmp, response_path)
+            print(f"judge: #{idx} → {'PASS' if ok else 'FAIL'} — {reason}", flush=True)
+
+
+if __name__ == "__main__":
+    sys.exit(main())