@aarwitz/tapp 0.17.8 → 0.17.10

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

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -1082,11 +1082,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. ---

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
 ```
@@ -349,7 +350,7 @@ jobs:
     timeout-minutes: 45
     steps:
       - uses: actions/checkout@v4
-      - uses: aarwitz/tapp@v0.17.8 # or pin the reviewed release commit SHA
+      - uses: aarwitz/tapp@v0.17.9 # or pin the reviewed release commit SHA
         with:
           project: MyApp.xcodeproj # or MyApp.xcworkspace
           scheme: MyApp
@@ -399,7 +400,7 @@ Android CI runs on Linux with an emulator/device already connected. The Action c
 or accept a prebuilt one:
 
 ```yaml
-- uses: aarwitz/tapp@v0.17.8 # or pin the reviewed release commit SHA
+- uses: aarwitz/tapp@v0.17.9 # or pin the reviewed release commit SHA
   with:
     platform: android
     android-app-id: com.acme.app
@@ -458,6 +459,15 @@ only an optional authoring/enrichment layer (`tapp_flow_generate`, `assert_ai`,
 The first tool call builds the harness once (~2 min, cached in `~/.tapp`; rebuilt automatically
 if you switch simulators). All captures land in `~/.tapp/captures/`.
 
+## Feedback
+
+Tapp accepts feedback the way agents already work: as GitHub issues on
+[aarwitz/tapp](https://github.com/aarwitz/tapp/issues). `tapp feedback "short title" --body "…"`
+(or the `tapp_feedback` MCP tool) drafts an issue with the version, platform availability, and latest
+capture id filled in and home paths and tokens redacted; `--submit` files it with your authenticated
+`gh`. Drafts are the default because issues are public — an agent should show you the draft first.
+Nothing is uploaded automatically; captures stay on your machine.
+
 ## License
 
 [MIT](./LICENSE)

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",
@@ -282,6 +282,7 @@ function safeCommandUsage(verb) {
     actor: "tapp actor set NAME --email-env ENV --password-env ENV [--replace] [--project-dir DIR]\ntapp actor list [repo]",
     app: "tapp app [repo] [--no-open] [--port PORT]",
     report: "tapp report [captureId|latest]",
+    feedback: "tapp feedback \"short title\" [--body TEXT|--body-file FILE] [--type bug|idea|question] [--capture ID|latest|none] [--as human] [--submit] [--json]\n  Drafts a public GitHub issue on aarwitz/tapp about tapp itself; --submit files it with the authenticated gh CLI.\n  Exit codes: 0 drafted or filed · 1 gh submission failed · 2 usage error",
     doctor: "tapp doctor [--json]\n  Exit codes: 0 environment healthy · 1 blocked (fix ❌ items)",
     install: "tapp install",
     mcp: "tapp mcp",
@@ -301,7 +302,7 @@ if (["--help", "-h"].includes(command)) {
 const knownCommands = new Set([
   "help", "version", "--version", "-v", "mcp", "init", "focus", "explore", "qa", "open",
   "tree", "shot", "screenshot", "apps", "build", "flow", "task", "contract", "scenario", "map",
-  "pr", "plan", "baseline", "ci", "actor", "app", "studio", "report", "doctor", "install",
+  "pr", "plan", "baseline", "ci", "actor", "app", "studio", "report", "doctor", "install", "feedback",
 ]);
 if (!knownCommands.has(command)) {
   console.error(`❌ Unknown command: ${command}`);
@@ -695,15 +696,28 @@ switch (command) {
     const launchOptions = iosLaunchOptions(flags, rest);
     let target = positionals[0] || "";
     let baselineFindings;
+    let baselineCaptureContext = null;
     if (flags.baseline) {
       try {
         const parsed = JSON.parse(fs.readFileSync(flags.baseline, "utf8"));
         baselineFindings = Array.isArray(parsed) ? parsed : parsed.findings;
+        // Accept the 0.17.7 gate JSON's stamp-shaped `capture` too (explore JSON never
+        // stamped that key — there it is the evidence-folder record).
+        if (!Array.isArray(parsed)) baselineCaptureContext = parsed.captureContext || (parsed.capture?.viewport ? parsed.capture : null);
       } catch (e) {
         console.error(`❌ Could not read baseline ${flags.baseline}: ${e.message}`);
         process.exit(2);
       }
     }
+    // The same honesty rule the CI gate applies: a baseline captured at another device/viewport
+    // makes "resolved" a layout diff, not a fix — say so on the command the JSON hint points at.
+    const applyCaptureMismatch = (structured) => {
+      if (!structured?.regression || !baselineCaptureContext || !structured.captureContext) return;
+      if (JSON.stringify(baselineCaptureContext) === JSON.stringify(structured.captureContext)) return;
+      structured.regression.captureMismatch = { baseline: baselineCaptureContext, current: structured.captureContext };
+      const describe = (c) => [c?.device, c?.viewport ? `${c.viewport.width}x${c.viewport.height}` : null, c?.deviceScaleFactor ? `@${c.deviceScaleFactor}x` : null].filter(Boolean).join(" ") || "unknown";
+      console.error(`⚠️  Capture mismatch: the baseline was captured at ${describe(baselineCaptureContext)}, this run at ${describe(structured.captureContext)}. "Resolved" findings may reflect layout differences, not fixes — re-baseline at the same device/viewport to compare honestly.`);
+    };
     const engine = await engineImport();
     // Source-preparing bare explore (ADR-0005 §5): no explicit target + a repo application model →
     // drive the model's default target end to end. Managed web is built/started/waited-for and
@@ -734,6 +748,7 @@ switch (command) {
         });
         finishProgress();
         if (r.error) { printEngineError(r); process.exit(1); }
+        applyCaptureMismatch(r.structured);
         console.log(r.text);
         if (flags.json && typeof flags.json === "string") {
           fs.writeFileSync(flags.json, JSON.stringify(r.structured, null, 2));
@@ -804,6 +819,7 @@ switch (command) {
       printEngineError(r);
       process.exit(1);
     }
+    applyCaptureMismatch(r.structured);
     console.log(r.text);
     if (flags.json && typeof flags.json === "string") {
       fs.writeFileSync(flags.json, JSON.stringify(r.structured, null, 2));
@@ -1117,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);
@@ -1126,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}`);
@@ -1141,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"}` : ""})`);
@@ -1829,6 +1860,58 @@ switch (command) {
     break;
   }
 
+  case "feedback": {
+    const { flags, positionals } = parseVerbArgs(rest);
+    const usage = 'Usage: tapp feedback "short title" [--body TEXT|--body-file FILE] [--type bug|idea|question] [--capture ID|latest|none] [--as human] [--submit] [--json]';
+    const title = positionals.join(" ").trim();
+    if (!title) { console.error(`❌ ${usage}`); process.exit(2); }
+    const fb = await import(path.join(packageRoot, "mcp-server", "src", "feedback.js"));
+    const type = typeof flags.type === "string" ? flags.type : "bug";
+    if (!fb.FEEDBACK_TYPES.includes(type)) { console.error(`❌ --type must be one of ${fb.FEEDBACK_TYPES.join(", ")}\n${usage}`); process.exit(2); }
+    let body = typeof flags.body === "string" ? flags.body : "";
+    if (typeof flags["body-file"] === "string") {
+      try { body = fs.readFileSync(flags["body-file"], "utf8"); } catch (error) { console.error(`❌ Could not read --body-file: ${error.message}`); process.exit(2); }
+    }
+    const captureFlag = typeof flags.capture === "string" ? flags.capture : "latest";
+    const captureId = captureFlag === "none" ? null : captureFlag === "latest" ? fb.latestCaptureId(tappHome) : captureFlag;
+    // Platform availability comes from doctor --json so the issue carries facts, not guesses.
+    let doctor = null;
+    try {
+      const d = run(process.execPath, [path.join(packageRoot, "bin", "tapp.js"), "doctor", "--json"], { env: { ...process.env, TAPP_HOME: tappHome } });
+      doctor = JSON.parse(d.stdout);
+    } catch { /* feedback still works without the environment summary */ }
+    let issue;
+    try {
+      issue = fb.composeFeedback({ title, body, type, version: pkg.version, doctor, captureId, filedBy: flags.as === "human" ? "human" : "agent" });
+    } catch (error) { console.error(`❌ ${error.message}\n${usage}`); process.exit(2); }
+    const url = fb.feedbackIssueUrl(issue);
+    let submitted = false, issueUrl = null;
+    if (flags.submit === true) {
+      const status = fb.ghStatus();
+      if (!status.available) {
+        if (flags.json === true) console.log(JSON.stringify({ ...issue, url, submitted: false, error: "gh not authenticated" }, null, 2));
+        else console.error(`❌ The GitHub CLI is not authenticated on this machine, so nothing was filed.\n   Open this prefilled issue instead (it is public):\n   ${url}`);
+        process.exit(1);
+      }
+      const result = fb.submitFeedbackViaGh(issue);
+      if (!result.ok) {
+        if (flags.json === true) console.log(JSON.stringify({ ...issue, url, submitted: false, error: result.detail }, null, 2));
+        else console.error(`❌ gh issue create failed: ${result.detail}\n   Prefilled issue link: ${url}`);
+        process.exit(1);
+      }
+      submitted = true; issueUrl = result.url;
+    }
+    if (flags.json === true) {
+      console.log(JSON.stringify({ ...issue, url, submitted, issueUrl }, null, 2));
+      break;
+    }
+    if (submitted) { ok("Filed feedback", issueUrl); break; }
+    console.log(`📝 Feedback draft (not filed — issues on ${fb.FEEDBACK_REPO} are public; confirm with the user first):\n`);
+    console.log(`Title:  ${issue.title}\nLabels: ${issue.labels.join(", ")}\n\n${issue.body}`);
+    console.log(`File it:  tapp feedback ${JSON.stringify(issue.title)} … --submit   (uses your authenticated gh)\nOr open:  ${url}`);
+    break;
+  }
+
   case "version":
   case "--version":
   case "-v": {
@@ -1859,6 +1942,8 @@ Repository & release:
                            (--explore grounds the UI Map · --url URL · --platform · --dry-run · --refresh)
   tapp baseline create [repo] Run/import a conclusive full gate and save a target-scoped baseline
   tapp report [captureId]  Open the HTML evidence page for a capture (default: latest)
+  tapp feedback "title"    Send a bug, idea, or question to the tapp maintainers as a GitHub issue
+                           (drafts by default · --submit files it · issues are public)
   tapp ci install [repo]   Generate a reviewable target-aware GitHub workflow + CI manifest
   tapp actor set NAME      Configure an actor using environment-variable names only (never values)
   tapp actor list [repo]   Inspect named actors, sessions, provisioning, and secret env bindings

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.8 # 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

@@ -0,0 +1,104 @@
+// Feedback to the tapp maintainers, the agent-native way: a GitHub issue on aarwitz/tapp.
+//
+// Shared by `tapp feedback` (CLI) and `tapp_feedback` (MCP). Both default to a DRAFT — the
+// composed issue plus a prefilled github.com/.../issues/new URL — and only file the issue when
+// explicitly asked (`--submit` / `submit: true`), because issues are public and an agent must not
+// publish on a user's behalf without consent. Filing uses the machine's authenticated `gh` CLI;
+// nothing is uploaded: captures stay local and only the capture id is referenced.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+export const FEEDBACK_REPO = "aarwitz/tapp";
+export const FEEDBACK_TYPES = ["bug", "idea", "question"];
+const TYPE_LABEL = { bug: "bug", idea: "idea", question: "question" };
+
+/** Strip home directories and token-shaped secrets before anything leaves the machine. */
+export function redactText(text, home = os.homedir()) {
+  let s = String(text ?? "");
+  if (home && home.length > 1) s = s.split(home).join("~");
+  s = s
+    .replace(/\/Users\/[^/\s"']+/g, "~")
+    .replace(/\/home\/[^/\s"']+/g, "~")
+    .replace(/[A-Za-z]:\\Users\\[^\\\s"']+/g, "~")
+    .replace(/\b(sk-ant-[A-Za-z0-9_-]{8,}|ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|AKIA[A-Z0-9]{16})\b/g, "[redacted]");
+  return s;
+}
+
+/** Newest capture directory name under TAPP_HOME, or null. Only the id is ever shared. */
+export function latestCaptureId(tappHome) {
+  const dir = path.join(tappHome, "captures");
+  if (!fs.existsSync(dir)) return null;
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => ({ name: e.name, mtime: fs.statSync(path.join(dir, e.name)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime);
+  return entries[0]?.name ?? null;
+}
+
+/** One line of platform availability from `tapp doctor --json` output. */
+export function summarizeDoctor(doctor) {
+  if (!doctor || typeof doctor !== "object") return null;
+  const p = doctor.platforms || {};
+  const parts = [];
+  if (p.ios) {
+    const detail = [p.ios.xcode, p.ios.bootedSimulator ? `${p.ios.bootedSimulator} booted` : ""].filter(Boolean).join(", ");
+    parts.push(`iOS ${p.ios.available ? "✅" : "⬜"}${detail ? ` (${detail})` : ""}`);
+  }
+  if (p.android) parts.push(`Android ${p.android.adb ? "✅" : "⬜"}${p.android.devicesConnected ? ` (${p.android.devicesConnected} device)` : ""}`);
+  if (p.web) parts.push(`web ${p.web.available ? "✅" : "⬜"}`);
+  return parts.join(" · ") || null;
+}
+
+/** Build the issue: redacted title/body plus an automatic, path-free context footer. */
+export function composeFeedback({
+  title, body = "", type = "bug", version = "unknown", node = process.version,
+  platform = `${process.platform} ${process.arch}`, doctor = null, captureId = null, filedBy = "agent",
+}) {
+  const cleanTitle = redactText(title).trim();
+  if (!cleanTitle) throw new Error("feedback needs a short title");
+  if (!FEEDBACK_TYPES.includes(type)) throw new Error(`type must be one of: ${FEEDBACK_TYPES.join(", ")}`);
+  const context = [`- tapp ${version} · node ${node} · ${platform}`];
+  const platforms = summarizeDoctor(doctor);
+  if (platforms) context.push(`- platforms: ${platforms}`);
+  if (captureId) context.push(`- capture: \`${redactText(captureId)}\` (kept locally — nothing is uploaded; evidence can be shared privately on request)`);
+  const description = redactText(body).trim() || "_(no description provided)_";
+  const byline = filedBy === "agent" ? ", filed by a coding agent on the user's behalf" : "";
+  const full = `${description}\n\n---\n_Filed with \`tapp feedback\` (${type}${byline}). This issue is public._\n${context.join("\n")}\n`;
+  const labels = ["feedback", TYPE_LABEL[type]];
+  if (filedBy === "agent") labels.push("agent-filed");
+  return { title: cleanTitle.slice(0, 200), body: full, labels };
+}
+
+/** Prefilled "new issue" link — works for anyone with a GitHub account, no CLI needed. */
+export function feedbackIssueUrl({ title, body, labels }) {
+  const url = new URL(`https://github.com/${FEEDBACK_REPO}/issues/new`);
+  url.searchParams.set("title", title);
+  url.searchParams.set("body", body);
+  url.searchParams.set("labels", labels.join(","));
+  return url.toString();
+}
+
+export function ghStatus(ghBin = process.env.TAPP_GH_BIN || "gh") {
+  const r = spawnSync(ghBin, ["auth", "status"], { encoding: "utf8" });
+  return { available: r.status === 0, detail: (r.stderr || r.stdout || "").trim() };
+}
+
+export function submitFeedbackViaGh(issue, ghBin = process.env.TAPP_GH_BIN || "gh") {
+  // 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", "-",
+    ...(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, 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);
@@ -2438,6 +2467,27 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
+    {
+      name: "tapp_feedback",
+      title: "Send feedback to the tapp maintainers",
+      description:
+        "Draft a public GitHub issue on aarwitz/tapp about tapp itself — a bug in tapp, an idea, or a " +
+        "question (not a finding about the app under test). Adds the tapp version, platform availability, " +
+        "and the latest capture id automatically and redacts home paths and tokens. Default is a DRAFT: " +
+        "returns the composed issue plus a prefilled github.com URL the user can open. Pass submit:true only " +
+        "after the user has agreed to file a public issue; filing uses this machine's authenticated GitHub CLI.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          title: { type: "string", description: "Short, specific title" },
+          body: { type: "string", description: "What happened, what you expected, the exact command or tool call. No secrets or private source." },
+          type: { type: "string", enum: ["bug", "idea", "question"], description: "Default bug" },
+          capture: { type: "string", description: "Capture id to reference, 'latest' (default) or 'none'" },
+          submit: { type: "boolean", description: "File the issue now with gh (needs the user's consent). Default false = draft only." },
+        },
+        required: ["title"],
+      },
+    },
     {
       name: "tapp_health",
       title: "Check Tapp readiness",
@@ -3170,6 +3220,40 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args = {} } = request.params;
 
+  if (name === "tapp_feedback") {
+    const fb = await import("./feedback.js");
+    const { fileURLToPath } = await import("node:url");
+    const packageRootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const title = String(args.title || "").trim();
+    if (!title) return errorResult("tapp_feedback needs a short title", {});
+    const type = typeof args.type === "string" ? args.type : "bug";
+    if (!fb.FEEDBACK_TYPES.includes(type)) return errorResult(`type must be one of ${fb.FEEDBACK_TYPES.join(", ")}`, {});
+    const tappHomeDir = (process.env.TAPP_HOME || path.join(os.homedir(), ".tapp")).trim();
+    const captureArg = typeof args.capture === "string" ? args.capture : "latest";
+    const captureId = captureArg === "none" ? null : captureArg === "latest" ? fb.latestCaptureId(tappHomeDir) : captureArg;
+    let doctor = null;
+    try {
+      const d = await runCommand(process.execPath, [path.join(packageRootDir, "bin", "tapp.js"), "doctor", "--json"], { timeoutMs: 60_000, env: { TAPP_HOME: tappHomeDir } });
+      doctor = JSON.parse(d.stdout);
+    } catch { /* optional context */ }
+    const version = JSON.parse(fs.readFileSync(path.join(packageRootDir, "package.json"), "utf8")).version;
+    let issue;
+    try { issue = fb.composeFeedback({ title, body: String(args.body || ""), type, version, doctor, captureId, filedBy: "agent" }); }
+    catch (error) { return errorResult(error.message, {}); }
+    const url = fb.feedbackIssueUrl(issue);
+    if (args.submit === true) {
+      const status = fb.ghStatus();
+      if (!status.available) return errorResult("The GitHub CLI is not authenticated on this machine, so nothing was filed. Give the user the prefilled link instead.", { url, ...issue, submitted: false });
+      const result = fb.submitFeedbackViaGh(issue);
+      if (!result.ok) return errorResult(`gh issue create failed: ${result.detail}`, { url, ...issue, submitted: false });
+      return richResult(`✅ Filed feedback: ${result.url}`, { submitted: true, issueUrl: result.url, ...issue });
+    }
+    return richResult(
+      `📝 Feedback drafted, not filed. Issues on ${fb.FEEDBACK_REPO} are public — confirm with the user, then call tapp_feedback again with submit: true, or give them this prefilled link:\n${url}\n\nTitle: ${issue.title}\nLabels: ${issue.labels.join(", ")}\n\n${issue.body}`,
+      { submitted: false, url, ...issue },
+    );
+  }
+
   if (name === "tapp_health") {
     const coreChecks = [];
     coreChecks.push({

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.8",
+  "version": "0.17.10",
   "mcpName": "io.github.aarwitz/tapp",
   "description": "Let coding agents verify UI changes on real iOS, Android, and web surfaces, then enforce reviewed proof in deterministic CI.",
   "license": "MIT",

package/scripts/flow_lib.py

@@ -63,6 +63,29 @@ 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 = []
@@ -97,8 +120,19 @@ 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)
+
     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

@@ -183,8 +183,9 @@ run_harness_test() {
   "OCQA_BUNDLE_ID": "$bundle_id",
   "OCQA_MAX_ACTIONS": "$max_actions",
   "OCQA_TIMEOUT_SECONDS": "$timeout_secs",
-  "OCQA_TEST_EMAIL": "${OCQA_TEST_EMAIL:-qa@example.com}",
-  "OCQA_TEST_PASSWORD": "${OCQA_TEST_PASSWORD:-Tapp123!}"$interactive_line$overrides_line$launch_args_line$launch_env_line$login_steps_line$pr_target_line$visual_ready_line$recording_started_line
+  "OCQA_TEST_EMAIL": "${OCQA_TEST_EMAIL:-}",
+  "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
 
@@ -447,8 +448,8 @@ OCQA_COMPLETE:{\"actions\":0,\"states\":0,\"issues\":1,\"screens\":\"\",\"outcom
   "OCQA_SESSION_CMD_PATH": "$SESS_CMD",
   "OCQA_SESSION_RESULT_PATH": "$SESS_RES",
   "OCQA_SESSION_TIMEOUT": "$SESS_TIMEOUT",
-  "OCQA_TEST_EMAIL": "${OCQA_TEST_EMAIL:-qa@example.com}",
-  "OCQA_TEST_PASSWORD": "${OCQA_TEST_PASSWORD:-Tapp123!}"$sess_args_line$sess_env_line
+  "OCQA_TEST_EMAIL": "${OCQA_TEST_EMAIL:-}",
+  "OCQA_TEST_PASSWORD": "${OCQA_TEST_PASSWORD:-}"$sess_args_line$sess_env_line
 }
 CONF
     xctestrun=$(find "$HARNESS_DERIVED/Build/Products" -name "*.xctestrun" 2>/dev/null | head -1)

package/skills/tapp/SKILL.md

@@ -92,7 +92,7 @@ After the focused fast path, read returned `elements[]` before any remaining act
 ids or visible labels, check `hittable`, tap a field before typing, and wait for navigation or async
 content. Use coordinates only as a last resort. End the session when finished.
 
-Do not edit the app merely because testing found a defect unless the user also asked for a fix. State
-what the evidence proves and what remains untested.
+Do not edit the app merely because testing found a defect unless the user also asked for a fix. State what the evidence proves and what remains untested.
+If tapp itself misbehaves, draft feedback with `npx -y @aarwitz/tapp@latest feedback "title"` or `tapp_feedback`; it is public — draft first, `--submit` only with the user's OK.
 
 Read [references/commands.md](references/commands.md) only for exact CLI/MCP syntax, Flow replay, credentials, or platform prerequisites.

package/skills/tapp/references/commands.md

@@ -14,6 +14,7 @@ npx -y @aarwitz/tapp@latest tree [target] --json
 npx -y @aarwitz/tapp@latest shot
 npx -y @aarwitz/tapp@latest report latest
 npx -y @aarwitz/tapp@latest doctor
+npx -y @aarwitz/tapp@latest feedback "short title" --body "what happened" --type bug|idea|question   # draft; add --submit to file (public)
 ```
 
 Platform examples:
@@ -100,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
 ```