@aarwitz/tapp 0.17.7 → 0.17.9

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

package/AGENTS.md

@@ -133,6 +133,10 @@ advisory). Report the finding counts and coverage; do not invent a scalar or a s
   (e.g. `["--uitesting"]` if the app has a test bypass), and/or `appLaunchEnv` (e.g. a staging
   backend URL). If the result shows `inputFieldsEncountered` and you have no credentials, **ask
   the user** for them rather than re-running blind.
+- Credential surfaces are catalogue-only without credentials, on every platform: with no
+  `testEmail`/`testPassword` supplied, exploration records a login/signup form's fields but does
+  not type into them, submit them, or open recovery/third-party-auth flows — a bare-app run may
+  be pointed at production. Supplying credentials is the explicit opt-in that enables sign-in.
 - Diff two runs: pass the previous run's `findings` as `baselineFindings` → you get a
   `regression` **comparison** (`new` / `persisting` / `resolved`) — an observation, not a gate. To gate
   a merge on regressions, run the CI gate (`tapp ci` / the GitHub Action).

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -1327,10 +1327,16 @@ class ExplorerTests: XCTestCase {
             beelineToTarget(target: targetScreen, route: route, actionCount: &actionCount, maxActions: maxActions)
         }
 
+        // Honest stop accounting: "action-budget" only survives when the while-condition itself
+        // ends the loop; every break records what actually stopped exploration so the report can
+        // say "navigation-trap" or "frontier-drained" instead of blessing a 15/20 run "completed".
+        var explorationStopCause = "action-budget"
+        var leftAppObservations = 0
         while actionCount < maxActions {
             // Subtract time spent paused for interactive input so human typing never eats the budget.
             if Date().timeIntervalSince(startTime) - totalWaitSeconds > timeoutSeconds {
                 print("OCQA_STATE:timeout_reached")
+                explorationStopCause = "time-budget"
                 break
             }
 
@@ -1374,6 +1380,32 @@ class ExplorerTests: XCTestCase {
                 }
             }
 
+            // ---- Left-app handoff: an observation, not a defect ----
+            // A tapped control can legitimately hand the user to a system surface or another
+            // app (mail composer, Settings, App Store, share sheet). Without this check the
+            // next tree read sees a backgrounded app, titles the screen "Unknown", and the
+            // hang/blank detectors file false HIGH findings (field report № 6 #26). Record
+            // the handoff against the action that caused it, come back, and keep exploring.
+            if app.state != .runningForeground {
+                leftAppObservations += 1
+                let causeAction = pendingTransitionFrom?.actionKey ?? "previous action"
+                let causeScreen = pendingTransitionFrom?.title ?? "Unknown"
+                print("OCQA_ACTION:{\"type\":\"left_app\",\"target\":\"\(escapeJSON(causeAction))\",\"screen\":\"\(escapeJSON(causeScreen))\",\"step\":\(actionCount),\"narrative\":\"\(escapeJSON("'\(causeAction)' handed off to a system surface or another app — returning to the app under test."))\"}")
+                pendingTransitionFrom = nil
+                app.activate()
+                _ = app.wait(for: .runningForeground, timeout: 5)
+                Thread.sleep(forTimeInterval: 1.0)
+                if app.state == .runningForeground {
+                    emitProgress(action: actionCount, maxActions: maxActions, states: visitedStates.count)
+                    continue
+                }
+                if leftAppObservations >= 3 {
+                    explorationStopCause = "left-app-unrecovered"
+                    break
+                }
+                continue
+            }
+
             var elements = readUITree(app)
             if elements.isEmpty {
                 // App may have gone to background, crashed, or be unresponsive.
@@ -1399,6 +1431,7 @@ class ExplorerTests: XCTestCase {
                             print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"\(escapeJSON("App crashed during \(where_)"))\",\"screen\":\"\(escapeJSON(where_))\",\"step\":\(actionCount)}")
                         }
                     }
+                    explorationStopCause = "app-crashed"
                     break
                 }
             }
@@ -1528,6 +1561,7 @@ class ExplorerTests: XCTestCase {
                     emitProgress(action: actionCount, maxActions: maxActions, states: visitedStates.count)
                     continue
                 }
+                explorationStopCause = "stuck-no-progress"
                 break
             }
 
@@ -1554,6 +1588,7 @@ class ExplorerTests: XCTestCase {
             // for an impossible back path or expecting credentials to persist after logout.
             if authSucceeded && detectedInputs.contains(where: { $0.secure }) {
                 print("OCQA_STATE:auth_cycle_complete screen=\(escapedTitle) step=\(actionCount)")
+                explorationStopCause = "auth-cycle-complete"
                 break
             }
 
@@ -1844,6 +1879,7 @@ class ExplorerTests: XCTestCase {
                     // All tab positions tried — truly stuck
                     print("OCQA_STATE:truly_stuck_dead_end screen=\(escapedTitle) step=\(actionCount)")
                     emitNavigationTrap(titleStr: titleStr, escapedTitle: escapedTitle, step: actionCount, reported: &reportedIssueKeys, issues: &issues)
+                    explorationStopCause = "navigation-trap"
                     break
                 }
 
@@ -2190,6 +2226,7 @@ class ExplorerTests: XCTestCase {
                     // Truly stuck — break
                     print("OCQA_STATE:truly_stuck screen=\(escapedTitle) step=\(actionCount)")
                     emitNavigationTrap(titleStr: titleStr, escapedTitle: escapedTitle, step: actionCount, reported: &reportedIssueKeys, issues: &issues)
+                    explorationStopCause = "navigation-trap"
                     break
                 }
             }
@@ -2201,6 +2238,23 @@ class ExplorerTests: XCTestCase {
                                             persistentThreshold: persistentThreshold,
                                             screenBounds: screenBounds)
 
+            // ---- Credential-surface policy: catalogue, don't exercise (parity with web). ----
+            // Without explicitly supplied credentials — or interactive overrides for this screen —
+            // a login/signup surface is evidence, not a playground: typing sample values and
+            // tapping Sign In / Forgot Password fires real requests against whatever backend the
+            // build points at (production, for a bare-app run). Fields are still catalogued into
+            // STATE, the report says sign-in was not checked, and navigation away stays allowed.
+            let credentialFlowLocked = (screenRole == "login" || screenRole == "signup" || detectedInputs.contains { $0.secure })
+                && (testEmail.isEmpty || testPassword.isEmpty)
+                && !detectedInputs.contains(where: { !hasNoOverride(key: $0.key, screen: titleStr, in: inputOverrides) })
+            if credentialFlowLocked {
+                if !reportedIssueKeys.contains("credlock:\(titleStr)") {
+                    reportedIssueKeys.insert("credlock:\(titleStr)")
+                    print("OCQA_STATE:credential_form_catalogued screen=\(escapedTitle) fields=\(detectedInputs.count)")
+                }
+                sorted = sorted.filter { !isTextField($0.type) && !isCredentialFlowControl($0) }
+            }
+
             // ---- Form-completion steering ----
             // A half-filled form is one tap from progress (submit) or oblivion (Close/Cancel
             // discards everything typed). While the screen has unfilled text fields, fill the
@@ -2214,8 +2268,8 @@ class ExplorerTests: XCTestCase {
             // screen or it abandons a form whose remaining field the pool has dropped (observed:
             // signup's Confirm Password missing from the pool while hittable in the tree).
             // Termination is per-field via typedFieldKeys, so this can never loop.
-            let treeHasFields = elements.contains(where: { isTextField($0.type) })
-            let unfilledFields = elements.filter {
+            let treeHasFields = !credentialFlowLocked && elements.contains(where: { isTextField($0.type) })
+            let unfilledFields = credentialFlowLocked ? [SimpleElement]() : elements.filter {
                 isTextField($0.type) && $0.isEnabled && $0.isHittable
                     && fieldLooksUnfilled($0, screen: titleStr, typedKeys: typedFieldKeys)
             }
@@ -2287,7 +2341,7 @@ class ExplorerTests: XCTestCase {
                 if !numericCells.isEmpty { sorted = others + numericCells }
             }
 
-            guard let target = sorted.first else { break }
+            guard let target = sorted.first else { explorationStopCause = "frontier-drained"; break }
 
             if !isTextField(target.type) {
                 dismissKeyboardIfNeeded()
@@ -2360,6 +2414,7 @@ class ExplorerTests: XCTestCase {
                                        desc: "The app terminated after \(actionType) '\(targetName)' on '\(titleStr)' and did not recover on relaunch."))
                         print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"\(escapeJSON("App crashed after \(actionType) on \(titleStr)"))\",\"screen\":\"\(escapedTitle)\",\"control\":\"\(escapedTarget)\",\"step\":\(actionCount)}")
                     }
+                    explorationStopCause = "app-crashed"
                     break
                 }
                 print("OCQA_STATE:app_reactivated step=\(actionCount)")
@@ -2479,6 +2534,7 @@ class ExplorerTests: XCTestCase {
                                        desc: "App left foreground after: \(actionDesc)"))
                         print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"App not recoverable\",\"action\":\"\(escapedTarget)\",\"step\":\(actionCount)}")
                     }
+                    explorationStopCause = "app-crashed"
                     break
                 }
                 print("OCQA_STATE:app_reactivated step=\(actionCount)")
@@ -2529,7 +2585,7 @@ class ExplorerTests: XCTestCase {
         let uniqueScreens = screenTitles.values
         let screenList = Array(Set(uniqueScreens)).sorted().joined(separator: ",")
         didEmitComplete = true
-        print("OCQA_COMPLETE:{\"actions\":\(actionCount),\"states\":\(visitedStates.count),\"issues\":\(issues.count),\"screens\":\"\(screenList)\"}")
+        print("OCQA_COMPLETE:{\"actions\":\(actionCount),\"states\":\(visitedStates.count),\"issues\":\(issues.count),\"screens\":\"\(screenList)\",\"stop\":\"\(explorationStopCause)\",\"timedOut\":\(explorationStopCause == "time-budget" ? "true" : "false")}")
 
         let finalScreenshot = app.screenshot()
         let finalAttachment = XCTAttachment(screenshot: finalScreenshot)
@@ -3380,6 +3436,19 @@ class ExplorerTests: XCTestCase {
 
     /// Dismiss-style controls (Close/Cancel/X) that discard a form in progress. Deprioritized —
     /// never excluded — while unfilled fields remain, so they stay available as an escape hatch.
+    /// Any control that advances a credential flow: submitting, account recovery, account
+    /// creation, or third-party auth. Used by the credential-surface lock — none of these may
+    /// fire when no credentials were supplied, because each one sends real traffic to the
+    /// app's live backend. Navigation controls (tabs, Skip, Continue as guest) do not match.
+    private func isCredentialFlowControl(_ element: SimpleElement) -> Bool {
+        if isLikelySubmitControl(element) { return true }
+        let text = (element.label + " " + element.identifier).lowercased()
+        let flowTokens = ["forgot", "reset password", "recover", "with apple", "with google",
+                          "with facebook", "create account", "sign up", "verification code",
+                          "magic link", "resend"]
+        return flowTokens.contains(where: { text.contains($0) })
+    }
+
     private func isDismissControl(_ element: SimpleElement) -> Bool {
         let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
         let id = element.identifier.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()

package/README.md

@@ -29,10 +29,11 @@ Supported targets:
 |---|---|
 | iOS | Simulator on macOS with Xcode; driven through XCUITest and accessibility |
 | Android | Connected emulator or device with `adb`; driven through UIAutomator |
-| Web (beta) | Owned browser app in Playwright Chromium |
+| Web | Owned browser app in Playwright Chromium |
+| Windows desktop | WPF, WinForms, and WinUI apps through Windows UI Automation — early runs are set up through the pilot |
 
-Windows can host Android and web testing when their prerequisites are installed. Windows desktop
-UI applications such as WinForms, WPF, and WinUI are not currently Tapp targets.
+Windows hosts Android and web testing when their prerequisites are installed, and is the home of
+the Windows desktop target.
 
 ## Give Tapp to your coding agent
 
@@ -173,7 +174,7 @@ npx -y @aarwitz/tapp@latest apps            # what's installed on the simulator
 npx -y @aarwitz/tapp@latest build [dir]     # just build + install (scheme auto-detected)
 ```
 
-Web (beta): `npx -y @aarwitz/tapp@latest explore http://localhost:3000` *(one-time setup:
+Web: `npx -y @aarwitz/tapp@latest explore http://localhost:3000` *(one-time setup:
 `npm i -g playwright && npx playwright install chromium`)*. Add `--watch` to open Tapp's controlled,
 isolated Chromium window and follow its clicks with an on-page pointer/action label. Tapp hides that
 watch UI from saved evidence screenshots and does not automate your personal/default browser profile.
@@ -348,7 +349,7 @@ jobs:
     timeout-minutes: 45
     steps:
       - uses: actions/checkout@v4
-      - uses: aarwitz/tapp@v0.17.7 # 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
@@ -398,7 +399,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.7 # 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
@@ -437,7 +438,7 @@ Every driver speaks one protocol: structured `OCQA_*` markers (state, actions, i
 transitions) that the engine parses into trees, screenshots, findings, coverage, and the gate outcome.
 On **iOS**, a generic **XCUITest harness** attaches to any app by bundle id — no SDK or app code
 changes — and acts through the accessibility tree. On **Android**, ADB + UIAutomator provide the
-same black-box driver contract. On **web** (beta), a deterministic **Playwright crawler** does the
+same black-box driver contract. On **web**, a deterministic **Playwright crawler** does the
 same in a real browser. Same detectors' spirit,
 same dedup, same regression gate, same honest `pass`/`fail`/`inconclusive` outcome. Core exploration,
 evidence collection, and gate evaluation run entirely locally — no telemetry, nothing phones home. Optional AI
@@ -457,6 +458,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

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

package/mcp-server/src/application-model.js

@@ -913,7 +913,7 @@ function invalidatedGeneration(generation) {
   };
 }
 
-function mergePlanDecisions(next, prior, { invalidateValidation = false } = {}) {
+export function mergePlanDecisions(next, prior, { invalidateValidation = false } = {}) {
   if (!prior || prior.schemaVersion !== 1 || prior.kind !== "tapp-release-plan") return next;
   const priorItems = new Map((prior.items || []).map((item) => [item.id, item]));
   const priorByNameScope = new Map();

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

@@ -178,7 +178,9 @@ function loadBaseline(baselinePath) {
     actionsPerformed: parsed.actionsPerformed || 0,
     platform: parsed.baselineIdentity?.platform || parsed.platform || null,
     targetKey: parsed.baselineIdentity?.targetId || parsed.targetKey || null,
-    capture: parsed.capture || null,
+    // 0.17.7 gate JSONs briefly published the stamp as `capture`; explore JSONs use that key
+    // for the evidence-folder record. Accept the old key only when it is actually a stamp.
+    captureContext: parsed.captureContext || (parsed.capture?.viewport ? parsed.capture : null),
   };
 }
 
@@ -496,8 +498,8 @@ function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan,
   lines.push(`**Gate (${gate.policy}): ${badge}**${gate.reasons.length ? " — " + gate.reasons.join("; ") : ""}${ignoredNote}`);
   // The gate is only authoritative about what it actually ran — record the scope explicitly.
   const rev = gate.revision?.sha ? `${String(gate.revision.sha).slice(0, 12)}${gate.revision.dirty ? "-dirty" : ""}` : "unknown";
-  const captured = report.capture
-    ? ` · capture: ${[report.capture.device, report.capture.viewport ? `${report.capture.viewport.width}x${report.capture.viewport.height}` : null, report.capture.deviceScaleFactor ? `@${report.capture.deviceScaleFactor}x` : null].filter(Boolean).join(" ")}`
+  const captured = report.captureContext
+    ? ` · capture: ${[report.captureContext.device, report.captureContext.viewport ? `${report.captureContext.viewport.width}x${report.captureContext.viewport.height}` : null, report.captureContext.deviceScaleFactor ? `@${report.captureContext.deviceScaleFactor}x` : null].filter(Boolean).join(" ")}`
     : "";
   const stableId = report.targetKey && report.targetKey !== gate.target ? ` (${report.targetKey})` : "";
   lines.push(`_target: ${gate.target || "—"}${stableId} · revision: ${rev} · policy: ${gate.policy} v${gate.policyVersion || "?"}${captured}_`);
@@ -562,8 +564,8 @@ const regression = 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.
-if (regression && baseline?.capture && report.capture && JSON.stringify(baseline.capture) !== JSON.stringify(report.capture)) {
-  regression.captureMismatch = { baseline: baseline.capture, current: report.capture };
+if (regression && baseline?.captureContext && report.captureContext && JSON.stringify(baseline.captureContext) !== JSON.stringify(report.captureContext)) {
+  regression.captureMismatch = { baseline: baseline.captureContext, current: report.captureContext };
 }
 const runs = args.flowLogs.map(parseFlowLog);
 const contracts = runs.filter((run) => run.kind === "release-contract");

package/mcp-server/src/feedback.js

@@ -0,0 +1,97 @@
+// 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") {
+  const r = spawnSync(ghBin, [
+    "issue", "create", "--repo", FEEDBACK_REPO,
+    "--title", issue.title, "--body-file", "-", "--label", issue.labels.join(","),
+  ], { encoding: "utf8", input: issue.body });
+  const out = (r.stdout || "").trim();
+  const err = (r.stderr || "").trim();
+  const url = (out.match(/https:\/\/github\.com\/\S+/) || [])[0] || null;
+  return { ok: r.status === 0 && Boolean(url), url, detail: r.status === 0 ? out : (err || out) };
+}

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

@@ -140,7 +140,7 @@ ${r.conditionsNotReached?.length ? `<div><h2>Conditions not reached</h2><ul>${sc
 <h1>${esc(observationBadge(r))} <span class="dim">· ${esc(observationSummary(r))}</span></h1>
 <div class="meta">${esc(label)} · evidence page (observation, not a release decision)</div>
 ${r.platform === "web" ? `<div class="meta">Deterministic basis: ${r.deterministicFindingCounts?.total || 0} deterministic finding(s); ${r.sampledFindingCounts?.total || 0} sampled probe finding(s) are advisory.</div>` : ""}
-${r.capture ? `<div class="meta">Captured at ${esc([r.capture.device, r.capture.viewport ? `${r.capture.viewport.width}×${r.capture.viewport.height}` : null, r.capture.deviceScaleFactor ? `@${r.capture.deviceScaleFactor}x` : null].filter(Boolean).join(" "))} — every screenshot on this page shares these conditions.</div>` : ""}
+${r.captureContext ? `<div class="meta">Captured at ${esc([r.captureContext.device, r.captureContext.viewport ? `${r.captureContext.viewport.width}×${r.captureContext.viewport.height}` : null, r.captureContext.deviceScaleFactor ? `@${r.captureContext.deviceScaleFactor}x` : null].filter(Boolean).join(" "))} — every screenshot on this page shares these conditions.</div>` : ""}
 <div class="headline">${esc(r.headline)}</div>
 ${r.credentialWarning ? `<div class="warning">${esc(r.credentialWarning)}</div>` : ""}
 ${scopeHtml}

package/mcp-server/src/index.js

@@ -2438,6 +2438,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 +3191,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/product-operations.js

@@ -10,6 +10,7 @@ import {
   buildInitArtifacts,
   generateApprovedContractProposals,
   mergeGeneratedTaskProposalValidation,
+  mergePlanDecisions,
   promoteValidatedProposals,
   recordContractProposalValidation,
   recordGeneratedTaskProposalValidation,
@@ -411,6 +412,13 @@ export async function initializeProductProject({
     maxContracts: Number(maxContracts),
   });
   let written = null;
+  // Dry-run must preview the SAME plan a real refresh would produce: merge reviewed
+  // decisions from the existing plan (pure, no writes). Returning the raw regenerated
+  // plan told users their approvals would be lost on refresh (field report № 6 #25).
+  let previewPlan = built.plan;
+  if (mode === "inspect" && fs.existsSync(paths.plan)) {
+    previewPlan = mergePlanDecisions(built.plan, readJson(paths.plan));
+  }
   if (mode !== "inspect") {
     const existing = fs.existsSync(paths.model) || fs.existsSync(paths.plan);
     written = writeInitArtifacts({
@@ -422,7 +430,7 @@ export async function initializeProductProject({
     });
   }
   const requirementScope = scopeProductRequirements(built.model, { selectedTargetId: selectedTarget?.id || "" });
-  return { operation: "initialize", mode, model: built.model, plan: written?.plan || built.plan, exploration, selectedTarget, requirementScope, written, project: readProductProject({ projectDir: root, outDir }) };
+  return { operation: "initialize", mode, model: built.model, plan: written?.plan || previewPlan, exploration, selectedTarget, requirementScope, written, project: readProductProject({ projectDir: root, outDir }) };
 }
 
 function resolvePlan(root, outDir, planPath = "") {

package/mcp-server/src/report.js

@@ -303,6 +303,9 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
     : !coverageFloorMet ? "coverage-floor-not-met"
     : driverStop === "frontier-drained" ? "no-unexplored-in-scope-controls"
     : driverStop === "probe-cap" ? "probe-cap-reached"
+    // 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)
     : "completed";
 
   const headline = timeBudgetExhausted
@@ -410,8 +413,10 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
     evidence: { markers: base.relativeMarkersFilePath },
     // Capture conditions shared by every screenshot/marker in this run (web: from the driver's
     // CONTEXT marker). A baseline diff across different captures is a layout comparison, not a
-    // regression signal — consumers must be able to see that.
-    capture: base.context && typeof base.context === "object"
+    // regression signal — consumers must be able to see that. Named captureContext because
+    // exploration consumers already publish `capture` as the evidence-folder record (field
+    // report № 7): the stamp must survive in the file people pass as --baseline.
+    captureContext: base.context && typeof base.context === "object"
       ? { device: base.context.device || null, viewport: base.context.viewport || null, deviceScaleFactor: base.context.deviceScaleFactor ?? null }
       : null,
     uiMap: null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.7",
+  "version": "0.17.9",
   "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

@@ -34,7 +34,9 @@
 #                                                 # blocks; see ci-report.js)
 #                      [--json-out <file.json>]   # write the full report (use as the next baseline)
 #                      [--md-out <file.md>]       # write the rendered markdown report (for a PR comment)
-#                      [--device <name>]          # simulator device to boot if none is (default "iPhone 16 Pro")
+#                      [--device <name>]          # ios: simulator to boot (default "iPhone 16 Pro")
+#                                                 # web: Playwright device profile, same as `tapp explore`
+#                      [--viewport WxH]           # web only: explicit viewport, e.g. 390x844
 #                      [--serial <adb-serial>]    # Android emulator/device (default: first connected device)
 #
 # The app must be a SIMULATOR build (xcodebuild ... -destination 'generic/platform=iOS Simulator').
@@ -47,7 +49,7 @@ usage() {
 
 PLATFORM="ios" APP_PATH="" BUNDLE_ID="" APK_PATH="" APP_ID="" URL="" WEB_TARGET="" TARGET_KEY="" SERIAL="" ACTIONS=40 TIMEOUT=600 FLOWS="" SCENARIOS="" CONTRACTS="" PROJECT_DIR="" BASELINE="" FAIL_ON="gate" JSON_OUT="" MD_OUT="" DEVICE="iPhone 16 Pro" PR_BASE="" PR_HEAD="HEAD" CHANGED_FILES_FILE="" PR_PLAN_OUT=""
 IOS_PR_TARGET_JSON=""
-FLOWS_EXPLICIT=false SCENARIOS_EXPLICIT=false CONTRACTS_EXPLICIT=false PLATFORM_EXPLICIT=false FAIL_ON_EXPLICIT=false
+FLOWS_EXPLICIT=false SCENARIOS_EXPLICIT=false CONTRACTS_EXPLICIT=false PLATFORM_EXPLICIT=false FAIL_ON_EXPLICIT=false DEVICE_EXPLICIT=false VIEWPORT=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --platform) PLATFORM="$2"; PLATFORM_EXPLICIT=true; shift 2 ;;
@@ -73,12 +75,14 @@ while [[ $# -gt 0 ]]; do
     --fail-on) FAIL_ON="$2"; FAIL_ON_EXPLICIT=true; shift 2 ;;
     --json-out) JSON_OUT="$2"; shift 2 ;;
     --md-out) MD_OUT="$2"; shift 2 ;;
-    --device) DEVICE="$2"; shift 2 ;;
+    --device) DEVICE="$2"; DEVICE_EXPLICIT=true; shift 2 ;;
+    --viewport) VIEWPORT="$2"; shift 2 ;;
     --help|-h) usage; exit 0 ;;
     *) echo "Unknown argument: $1" >&2; exit 2 ;;
   esac
 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; }
 [[ "$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; }
@@ -283,6 +287,16 @@ if [[ "$PLATFORM" != "ios" ]]; then
   [[ -n "$URL" ]] && PLATFORM_ARGS+=(--url "$URL")
   [[ -n "$PROJECT_DIR" ]] && PLATFORM_ARGS+=(--project-dir "$PROJECT_DIR")
   [[ -n "$WEB_TARGET" ]] && PLATFORM_ARGS+=(--web-target "$WEB_TARGET")
+  # On a web gate --device/--viewport carry the SAME meaning as `tapp explore` (a Playwright
+  # rendering profile) — one flag must not silently mean "simulator" here and get dropped.
+  if [[ "$PLATFORM" == "web" ]]; then
+    [[ "$DEVICE_EXPLICIT" == "true" ]] && PLATFORM_ARGS+=(--device "$DEVICE")
+    [[ -n "$VIEWPORT" ]] && PLATFORM_ARGS+=(--viewport "$VIEWPORT")
+  elif [[ "$PLATFORM" == "android" ]]; then
+    if [[ "$DEVICE_EXPLICIT" == "true" || -n "$VIEWPORT" ]]; then
+      echo "❌ --device/--viewport have no meaning on an android gate (use --serial to pick a device)" >&2; exit 2
+    fi
+  fi
   [[ -n "$TARGET_KEY" ]] && PLATFORM_ARGS+=(--target-key "$TARGET_KEY")
   [[ -n "$APP_ID" ]] && PLATFORM_ARGS+=(--app-id "$APP_ID")
   [[ -n "$APK_PATH" ]] && PLATFORM_ARGS+=(--apk "$APK_PATH")

package/scripts/platform-gate.js

@@ -27,6 +27,8 @@ for (let i = 2; i < process.argv.length; i += 1) {
   else if (key === "--project-dir") args.projectDir = value;
   else if (key === "--web-target") args.webTarget = value;
   else if (key === "--target-key") args.targetKey = value;
+  else if (key === "--device") args.device = value;
+  else if (key === "--viewport") args.viewport = value;
   else if (key === "--app-id") args.appId = value;
   else if (key === "--apk") args.apk = value;
   else if (key === "--serial") args.serial = value;
@@ -126,7 +128,7 @@ try {
     exitCode = 2;
   } else {
     const qa = 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 })
+      ? 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 });
     if (qa.error) {

package/scripts/quick-capture.sh

@@ -183,8 +183,8 @@ 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:-}"$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 +447,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: