@aarwitz/tapp 0.16.5 → 0.17.0-rc.10

package/mcp-server/src/index.js

@@ -12,7 +12,7 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 
-import { parseOcqaMarkers, buildQaReport, computeRegression, qaScoreLabel, verdictBadge } from "./report.js";
+import { parseOcqaMarkers, buildQaReport, computeRegression, observationBadge, observationSummary } from "./report.js";
 import { existingProjectArtifactPath, projectArtifactDirectory } from "./project-paths.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -21,10 +21,10 @@ const repoRoot = path.resolve(__dirname, "../..");
 const scriptsDir = path.join(repoRoot, "scripts");
 // TAPP_HOME (set by the `tapp` CLI when installed) redirects writable output to a user directory.
 // The old alias remains a read-only fallback; unset repository development stays local.
-const tappHome = (process.env.TAPP_HOME || process.env.AUTOTAP_HOME || "").trim();
+const tappHome = (process.env.TAPP_HOME || "").trim();
 const capturesDir = tappHome ? path.join(tappHome, "captures") : path.join(repoRoot, "captures");
 const MAX_OUTPUT_CHARS = 60_000;
-const requiredAuthToken = (process.env.TAPP_MCP_TOKEN || process.env.AUTOTAP_MCP_TOKEN || "").trim();
+const requiredAuthToken = (process.env.TAPP_MCP_TOKEN || "").trim();
 
 function clampOutput(value, maxChars = MAX_OUTPUT_CHARS) {
   if (typeof value !== "string") {
@@ -35,8 +35,13 @@ function clampOutput(value, maxChars = MAX_OUTPUT_CHARS) {
     return value;
   }
 
-  const dropped = value.length - maxChars;
-  return `${value.slice(0, maxChars)}\n...[truncated ${dropped} chars]`;
+  // Compiler/build diagnostics are normally emitted at the end. Preserve both ends so a long
+  // dependency build cannot truncate away the one actionable error the user needs.
+  const marker = "\n...[output truncated]...\n";
+  const retained = Math.max(0, maxChars - marker.length);
+  const head = Math.ceil(retained / 2);
+  const tail = Math.floor(retained / 2);
+  return `${value.slice(0, head)}${marker}${value.slice(value.length - tail)}`;
 }
 
 function asBoolean(value, fallback = false) {
@@ -984,7 +989,10 @@ async function runExploreStreaming(bundleId, actions, timeout, env, onProgress)
   const before = new Set(listCaptureRuns(80).map((r) => r.id));
   const proc = spawn("bash", cmdArgs, { cwd: repoRoot, env: { ...process.env, ...env } });
   proc.stdout.on("data", () => {});
-  proc.stderr.on("data", () => {});
+  let captureStderr = "";
+  proc.stderr.on("data", (chunk) => {
+    captureStderr = (captureStderr + chunk.toString("utf8")).slice(-8_000);
+  });
   const closed = new Promise((res) => proc.on("close", (code) => res(code ?? 1)));
 
   let captureDir = null;
@@ -1037,7 +1045,18 @@ async function runExploreStreaming(bundleId, actions, timeout, env, onProgress)
   await closed;
   const created = listCaptureRuns(80).find((r) => !before.has(r.id))
     || (captureDir ? { id: path.basename(captureDir), path: captureDir, relativePath: path.relative(repoRoot, captureDir) } : null);
-  return { created, timedOut };
+  return { created, timedOut, captureStderr };
+}
+
+export function recordingUnavailableReason(stderr = "") {
+  const text = String(stderr);
+  if (/resource busy|host recording is already in progress/i.test(text)) {
+    return "the simulator recorder is busy with another host recording";
+  }
+  if (/could not start simulator video recording/i.test(text)) {
+    return "the simulator could not start video recording";
+  }
+  return "the simulator did not produce a recording";
 }
 
 // Grab the booted simulator's current screen and return it downscaled + JPEG-compressed so the
@@ -1066,7 +1085,7 @@ export async function captureScreenshotImage(maxWidth) {
 // change data-handling behavior. A subscription token is an explicit tapp choice, and
 // explicitly-invoked AI tools (tapp_flow_generate, assert_ai) carry their own consent.
 export function remoteAiOptedIn(env = process.env) {
-  if ((env.TAPP_SUBSCRIPTION_TOKEN || env.AUTOTAP_SUBSCRIPTION_TOKEN || "").trim()) return true;
+  if ((env.TAPP_SUBSCRIPTION_TOKEN || "").trim()) return true;
   return ["1", "true", "yes"].includes(String(env.TAPP_ENABLE_REMOTE_AI || "").trim().toLowerCase());
 }
 
@@ -1078,9 +1097,9 @@ export function isInsideDir(root, p) {
 }
 
 function resolveModelBackend() {
-  const token = (process.env.TAPP_SUBSCRIPTION_TOKEN || process.env.AUTOTAP_SUBSCRIPTION_TOKEN || "").trim();
+  const token = (process.env.TAPP_SUBSCRIPTION_TOKEN || "").trim();
   if (token) {
-    const base = (process.env.TAPP_PROXY_URL || process.env.AUTOTAP_PROXY_URL || "http://localhost:8787").replace(/\/$/, "");
+    const base = (process.env.TAPP_PROXY_URL || "http://localhost:8787").replace(/\/$/, "");
     const url = base.endsWith("/v1/messages") ? base : base + "/v1/messages";
     return { url, headers: { authorization: `Bearer ${token}`, "content-type": "application/json" } };
   }
@@ -1092,7 +1111,7 @@ function resolveModelBackend() {
 }
 
 async function callModel(backend, { system, userText, model, maxTokens = 1500 }) {
-  const body = JSON.stringify({ model: model || process.env.TAPP_FLOW_MODEL || process.env.AUTOTAP_FLOW_MODEL || "claude-sonnet-4-6", max_tokens: maxTokens, system, messages: [{ role: "user", content: userText }] });
+  const body = JSON.stringify({ model: model || process.env.TAPP_FLOW_MODEL || "claude-sonnet-4-6", max_tokens: maxTokens, system, messages: [{ role: "user", content: userText }] });
   const res = await fetch(backend.url, { method: "POST", headers: backend.headers, body });
   if (!res.ok) return { error: `model HTTP ${res.status}: ${(await res.text()).slice(0, 300)}` };
   const data = await res.json();
@@ -1307,7 +1326,7 @@ export function qaNextSteps(report, surface = "mcp") {
   if (surface === "cli") {
     const next = [];
     if (report?.findings?.length) next.push("inspect the evidence with `tapp report latest`");
-    next.push("re-run with `--baseline <report.json>` to gate a fix");
+    next.push("re-run with `--baseline <report.json>` to compare a fix (then `tapp ci` to gate it)");
     next.push("replay a committed journey with `tapp flow run <file>`");
     return next;
   }
@@ -1318,25 +1337,27 @@ export function qaNextSteps(report, surface = "mcp") {
   return next;
 }
 
-function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiConfigured, reportHtml, recording, uiMap, surface = "mcp" } = {}) {
+function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiConfigured, reportHtml, recording, recordingWarning, uiMap, surface = "mcp" } = {}) {
   const c = report.findingCounts || {};
-  const badge = verdictBadge(report);
+  const badge = observationBadge(report);
   const sevBits = ["critical", "high", "medium", "low"]
     .map((k) => (c[k] ? `${SEV[k]} ${c[k]} ${k}` : null))
     .filter(Boolean)
     .join(", ");
   const L = [];
-  L.push(`### 🧪 QA complete — ${badge} · ${qaScoreLabel(report)}${bundleId ? `\n\`${bundleId}\`` : ""}`);
+  // Exploration observes; it does not render a ship verdict. The release decision lives in the gate.
+  L.push(`### 🔭 Exploration complete — ${badge} · ${observationSummary(report)}${bundleId ? `\n\`${bundleId}\`` : ""}`);
   L.push("");
   L.push(report.headline);
   L.push("");
   L.push(`**Coverage** — ${report.screensExplored} screens · ${report.actionsPerformed} actions${timedOut ? " · ⏱️ hit time limit" : ""}`);
   if (report.platform === "web") {
-    L.push(`**Verdict basis** — ${report.verdictFindingCounts?.total || 0} deterministic finding(s); ${report.sampledFindingCounts?.total || 0} sampled probe finding(s) are advisory`);
+    L.push(`**Deterministic basis** — ${report.deterministicFindingCounts?.total || 0} deterministic finding(s); ${report.sampledFindingCounts?.total || 0} sampled probe finding(s) are advisory`);
   }
   if (uiMap) L.push(`**UI Map** — ${uiMap.nodeCount} states · ${uiMap.edgeCount} transitions · ${uiMap.controlCount} semantic controls · ${uiMap.path}`);
   if (reportHtml) L.push(`**Evidence** — 📄 ${reportHtml} (screenshots of every screen + findings, shareable)`);
   if (recording) L.push(`**Recording** — 🎬 ${recording} (full exploration, embedded in the evidence page)`);
+  else if (recordingWarning) L.push(`**Recording** — ⚠️ unavailable: ${recordingWarning}; screenshots were still captured`);
   L.push(`**Issues** — ${c.total ? `${c.total}${sevBits ? ` (${sevBits})` : ""}` : "none found ✨"}`);
   if (Array.isArray(report.findings) && report.findings.length) {
     L.push("");
@@ -1355,17 +1376,18 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
     }
   }
   if (regression && regression.counts) {
-    const g = regression.gate || {};
+    // Exploration reports the comparison (new/persisting/resolved) only — never a gate pass/fail.
+    // The merge decision is the gate's job (tapp ci), not exploration's (ADR-0005).
     L.push("");
     L.push(
-      `**Since last run** — +${regression.counts.new} new · ${regression.counts.persisting} persisting · ${regression.counts.resolved} resolved · gate ${g.failed ? "🔴 FAIL" : "🟢 PASS"}`
+      `**Since last run** — +${regression.counts.new} new · ${regression.counts.persisting} persisting · ${regression.counts.resolved} resolved (comparison only — run \`tapp ci\` to gate)`
     );
   }
   if (inputHint) {
     L.push("");
     L.push(`> ℹ️ ${inputHint}`);
   }
-  // The honesty label: a "ready" is a claim about exactly these classes, nothing more.
+  // The observation's scope: enumerate exactly what ran and what remains unchecked.
   if (Array.isArray(report.checkedFor) && report.checkedFor.length) {
     L.push("");
     L.push(`> ✅ Checked: ${report.checkedFor.join(" · ")}`);
@@ -1379,11 +1401,10 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
   const next = qaNextSteps(report, surface);
   L.push("");
   L.push(`**Next** — ${next.join(" · ")}`);
-  // The gate hook belongs at the moment the user thinks "I want this on every PR" —
-  // i.e. right after a verdict that found something, or after they hand-diffed a baseline.
+  // The gate hook belongs at the moment the user thinks "I want these checks on every PR".
   if ((report.findings && report.findings.length) || regression) {
     L.push("");
-    L.push("> 🚦 Teams: get this verdict on every PR automatically (evidence + regression gate) — https://github.com/aarwitz/tapp#ci-gate");
+    L.push("> 🚦 Teams: run these checks plus reviewed release contracts as a merge gate on every PR — https://github.com/aarwitz/tapp#ci-gate");
   }
   return L.join("\n");
 }
@@ -1464,7 +1485,7 @@ export async function runQaWeb({ url, maxActions, timeout, testEmail, testPasswo
   } catch (err) {
     return { error: String(err.message || err) };
   }
-  const report = buildQaReport(webResult.markersPath, { platform: "web" });
+  const report = buildQaReport(webResult.markersPath, { platform: "web", target: url.trim() });
   if (!report) return { error: "Web exploration produced no markers", details: { capture: { id, path: outDir } } };
   const backend = remoteAiOptedIn() ? resolveModelBackend() : null;
   if (backend && report.findings.length) {
@@ -1507,7 +1528,7 @@ export async function runQaAndroid({ appId, apkPath, serial, maxActions, timeout
   } catch (error) {
     return { error: error.message || String(error), details: { capture: { id, path: outDir } } };
   }
-  const report = buildQaReport(androidResult.markersPath, { platform: "android" });
+  const report = buildQaReport(androidResult.markersPath, { platform: "android", target: appId.trim() });
   if (!report) return { error: "Android exploration produced no markers", details: { capture: { id, path: outDir } } };
   const backend = remoteAiOptedIn() ? resolveModelBackend() : null;
   if (backend && report.findings.length) {
@@ -1539,10 +1560,10 @@ export async function runQaIos({ bundleId, maxActions, timeout, args = {}, surfa
   const timeoutSec = Math.max(30, Math.min(3600, asInteger(timeout, 600)));
   const env = explorationEnvFromArgs(args);
 
-  const { created, timedOut } = await runExploreStreaming(bundleId, actions, timeoutSec, env, onProgress);
+  const { created, timedOut, captureStderr } = await runExploreStreaming(bundleId, actions, timeoutSec, env, onProgress);
   if (!created) return { error: "Exploration produced no capture run", details: { timedOut } };
 
-  const report = buildQaReport(path.join(created.path, "ocqa-markers.txt"));
+  const report = buildQaReport(path.join(created.path, "ocqa-markers.txt"), { platform: "ios", target: bundleId });
   if (!report) {
     return {
       error: "No markers parsed from exploration (the app may not have launched)",
@@ -1572,13 +1593,14 @@ export async function runQaIos({ bundleId, maxActions, timeout, args = {}, surfa
   // Cross-run regression vs. a caller-supplied baseline (the CI gate).
   const regression = computeRegression(report.findings, args.baselineFindings);
   const uiMap = await writeRunUiMap({ markersPath: path.join(created.path, "ocqa-markers.txt"), platform: "ios", target: bundleId, runId: created.id, outDir: created.path });
+  const recording =
+    ["exploration.webm", "exploration.mov"].map((f) => path.join(created.path, f)).find((p) => fs.existsSync(p)) || null;
+  const recordingWarning = recording ? null : recordingUnavailableReason(captureStderr);
   let reportHtml = null;
   try {
     const { writeHtmlReport } = await import("./html-report.js");
-    reportHtml = writeHtmlReport(created.path, { report, label: bundleId });
+    reportHtml = writeHtmlReport(created.path, { report, label: bundleId, recordingWarning });
   } catch { /* evidence page is best-effort */ }
-  const recording =
-    ["exploration.webm", "exploration.mov"].map((f) => path.join(created.path, f)).find((p) => fs.existsSync(p)) || null;
   const structured = {
     ...report,
     regression,
@@ -1586,11 +1608,12 @@ export async function runQaIos({ bundleId, maxActions, timeout, args = {}, surfa
     inputHint,
     reportHtml,
     recording,
+    recordingWarning,
     capture: { id: created.id, path: created.path, relativePath: created.relativePath },
     timedOut,
     autoBooted: sim.autoBooted || false,
   };
-  const text = formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiConfigured: !!backend, reportHtml, recording, uiMap: uiMap.error ? null : uiMap, surface });
+  const text = formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiConfigured: !!backend, reportHtml, recording, recordingWarning, uiMap: uiMap.error ? null : uiMap, surface });
   return { structured, text };
 }
 
@@ -1690,8 +1713,8 @@ export async function runInitExploration({
     merged.provenance.lastRun = {
       id: qa.structured.capture?.id || observed.provenance?.runIds?.at(-1) || "",
       platform: selected,
-      verdict: qa.structured.verdict,
       inconclusive: qa.structured.inconclusive === true,
+      findingCount: qa.structured.findingCounts?.total ?? 0,
       statesExplored: Number(qa.structured.screensExplored || merged.nodes.length),
       actionsPerformed: Number(qa.structured.actionsPerformed || 0),
       observedAt: observed.provenance?.lastObservedAt || new Date().toISOString(),
@@ -1707,8 +1730,8 @@ export async function runInitExploration({
           resolution: targetResolution,
           evidence: {
             captureId: qa.structured.capture?.id || "",
-            verdict: qa.structured.verdict,
             inconclusive: qa.structured.inconclusive === true,
+            findingCount: qa.structured.findingCounts?.total ?? 0,
             observedAt: observed.provenance?.lastObservedAt || new Date().toISOString(),
           },
         },
@@ -1721,7 +1744,6 @@ export async function runInitExploration({
         controlCount: merged.nodes.reduce((total, node) => total + node.controls.length, 0),
       },
       mapDiff: previous ? diffUiMaps(previous, observed, { comparableFullSweep: false }) : null,
-      verdict: qa.structured.verdict,
       inconclusive: qa.structured.inconclusive === true,
       findings: qa.structured.findings || [],
       capture: qa.structured.capture,
@@ -1735,6 +1757,97 @@ export async function runInitExploration({
   }
 }
 
+/**
+ * Source-preparing bare explore (ADR-0005 §5): a `tapp explore` with no explicit target in a
+ * repository with an application model. Selects the model's default target and prepares it from
+ * source before exploring — managed web is built/started/waited-for and always stopped again,
+ * iOS is built + installed on the simulator, Android is built to an APK + installed — then runs
+ * the ordinary exploration engine. Returns the same `{ text, structured, error }` shape as the
+ * direct runQa* entrypoints, so the CLI/MCP surfaces print it unchanged. This is an OBSERVATION:
+ * no verdict, no UI-map write (that is `runInitExploration`'s job); the gate still judges.
+ */
+export async function runExploreTarget({
+  projectDir,
+  platform = "",
+  target = "",
+  maxActions,
+  timeout,
+  testEmail,
+  testPassword,
+  appLaunchArgs,
+  appLaunchEnv,
+  baselineFindings,
+  surface = "cli",
+  onProgress = () => {},
+  onStatus = () => {},
+} = {}) {
+  let root;
+  try { root = fs.realpathSync(path.resolve(projectDir || process.cwd())); }
+  catch { return { error: `Repository directory not found: ${projectDir || process.cwd()}` }; }
+
+  const modelPath = existingProjectArtifactPath(root, "application-model.json");
+  if (!fs.existsSync(modelPath)) {
+    return { error: "No application model found — run `tapp init` first, or pass an explicit target (a bundle id, a path/to/App.app, a repo dir, --app-id/--apk, or an http(s) URL)." };
+  }
+  let model;
+  try { model = JSON.parse(fs.readFileSync(modelPath, "utf8")); }
+  catch (error) { return { error: `Application model is unreadable: ${error.message || String(error)}` }; }
+
+  const { selectApplicationTarget } = await import("./ci-setup.js");
+  let selected;
+  try { selected = selectApplicationTarget(model, { platform, target, useDefault: true }); }
+  catch (error) { return { error: error.message || String(error) }; }
+  const selectedPlatform = selected.platform;
+
+  if (selectedPlatform !== "ios" && ((Array.isArray(appLaunchArgs) && appLaunchArgs.length) || (appLaunchEnv && Object.keys(appLaunchEnv).length))) {
+    return { error: "appLaunchArgs/appLaunchEnv apply only to iOS targets." };
+  }
+
+  if (selectedPlatform === "web") {
+    const ownedUrl = String(selected.runtime?.ownedUrl || "").trim();
+    if (/^https?:\/\//i.test(ownedUrl)) {
+      onStatus(`Exploring the owned URL from the application model: ${ownedUrl}`);
+      return runQaWeb({ url: ownedUrl, maxActions, timeout, testEmail, testPassword, baselineFindings, surface, onProgress });
+    }
+    // Tapp-managed: build/start the repo's web target, wait for readiness, and ALWAYS stop it.
+    onStatus(`Preparing the managed web runtime for ${selected.name}…`);
+    const started = await startManagedWebTarget({ root, requestedTarget: selected.sourcePath || selected.name || "", timeout, onStatus });
+    if (started.error) return started;
+    try {
+      return await runQaWeb({ url: started.url, maxActions, timeout, testEmail, testPassword, baselineFindings, surface, onProgress });
+    } finally {
+      await stopManagedWebTarget(started);
+      onStatus("Stopped the managed web runtime.");
+    }
+  }
+
+  if (selectedPlatform === "android") {
+    const appId = String(selected.runtime?.applicationId || "").trim();
+    if (!appId) return { error: `The Android target '${selected.name}' has no confirmed application id — confirm it and rerun \`tapp init\`, or pass --app-id.` };
+    const task = selected.build?.task || "assembleDebug";
+    onStatus(`Building the Android APK (${task})…`);
+    const built = await buildAndroidApp({
+      projectDir: root,
+      gradleProjectDir: path.resolve(root, selected.build?.projectDir || "."),
+      moduleDir: path.resolve(root, selected.sourcePath || "."),
+      task,
+    });
+    if (built.error) return built;
+    onStatus(`Installing and exploring ${appId}…`);
+    return runQaAndroid({ appId, apkPath: built.apkPath, maxActions, timeout, testEmail, testPassword, baselineFindings, surface, onProgress });
+  }
+
+  // iOS
+  if (process.platform !== "darwin") return { error: "iOS exploration requires macOS with Xcode." };
+  const scheme = selected.build?.scheme || selected.build?.proposedScheme || "";
+  const configuration = selected.build?.configuration || "Debug";
+  onStatus(`Building and installing the iOS app${scheme ? ` (scheme ${scheme})` : ""}…`);
+  const resolved = await resolveAppTarget(root, { cwd: root, onStatus, scheme, configuration });
+  if (resolved.error) return resolved;
+  if (resolved.via) onStatus(`Target ${resolved.bundleId} — ${resolved.via}`);
+  return runQaIos({ bundleId: resolved.bundleId, maxActions, timeout, args: { testEmail, testPassword, baselineFindings, appLaunchArgs, appLaunchEnv }, surface, onProgress });
+}
+
 function openLocalPort() {
   return new Promise((resolve, reject) => {
     const server = net.createServer();
@@ -1946,7 +2059,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       description:
         "Build the user's iOS app for the simulator from an Xcode project/workspace (auto-detects the " +
         "container and scheme under projectDir, default cwd), install it on the booted simulator, and " +
-        "return the bundle id. Use before tapp_run_qa / tapp_open_app when the app isn't installed yet — " +
+        "return the bundle id. Use before tapp_explore / tapp_open_app when the app isn't installed yet — " +
         "no bundle id needed up front.",
       inputSchema: {
         type: "object",
@@ -2068,22 +2181,23 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       },
     },
     {
-      name: "tapp_run_qa",
-      title: "Run autonomous QA",
+      name: "tapp_explore",
+      title: "Explore (autonomous)",
       description:
-        "Run autonomous QA against iOS (appBundleId), Android (androidAppId), OR a web app " +
-        "(url — beta, requires Playwright installed) and return a structured " +
-        "QA verdict. Use ONLY when the user wants a QA assessment / to find bugs / a verdict — this " +
+        "Autonomously explore iOS (appBundleId), Android (androidAppId), OR a web app " +
+        "(url — beta, requires Playwright installed) and return a structured EXPLORATION OBSERVATION. " +
+        "Exploration OBSERVES — it surfaces findings + coverage + evidence; it does NOT render a ship " +
+        "verdict or score. To gate a merge, run the deterministic gate (contracts + baseline via CI). " +
+        "Use when the user wants to find bugs / observe what breaks — this " +
         "runs for MINUTES exploring the whole app. Do NOT use it just to view, screenshot, or reach a specific " +
         "screen — use tapp_open_app (launch + screenshot) or a session for that. Tapp explores the app " +
         "like a tester (taps, types, navigates, scrolls) and detects real issues — crashes, dead buttons, failed sign-ins, error screens, " +
         "stuck/hung screens; on web also uncaught JS exceptions, failed/5xx requests, broken links and assets. " +
-        "Returns {verdict: ready|caution|blocked, confidence, releaseScore, headline, screensExplored, " +
-        "actionsPerformed, findings:[{type,severity,category,title,screen,evaluationTier}]}. Exploratory web " +
-        "sets confidence/releaseScore to null and separates deterministic verdict findings from advisory " +
-        "sampled control probes. The verdict has a coverage floor: " +
-        "if the app barely explored (crash on launch / sign-in wall) it returns 'caution' + inconclusive, never a " +
-        "false pass. For iOS the app must already be installed on a booted simulator (use tapp_list_simulators / " +
+        "Returns {kind:'tapp-exploration-run', headline, inconclusive, screensExplored, " +
+        "actionsPerformed, findingCounts, findings:[{type,severity,category,authority,title,screen}]} — NO " +
+        "verdict/releaseScore. Web separates deterministic findings from advisory sampled control probes. " +
+        "There is a coverage floor: if the app barely explored (crash on launch / sign-in wall) it reports " +
+        "`inconclusive` — absence of findings is NEVER a pass. For iOS the app must already be installed on a booted simulator (use tapp_list_simulators / " +
         "tapp_boot_simulator first). For web, only point it at an app/environment you own — it CLICKS things. " +
         "Tapp explores autonomously and does NOT pause to prompt for input — " +
         "it fills forms with safe defaults. The result includes `inputFieldsEncountered` (and `inputHint`): if " +
@@ -2138,10 +2252,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             type: "array",
             items: { type: "object" },
             description:
-              "Findings from a previous run (pass back the `findings` array a prior tapp_run_qa returned). " +
-              "When provided, the result adds `regression` {counts:{new,persisting,resolved}, newFindings, resolved, " +
-              "gate:{newHigh,newCritical,failed}} comparing this run to that baseline. For a CI gate: store the " +
-              "baseline once, then fail the build when regression.gate.failed is true (new high/critical introduced).",
+              "Findings from a previous run (pass back the `findings` array a prior tapp_explore returned). " +
+              "When provided, the result adds a `regression` COMPARISON {counts:{new,persisting,resolved}, " +
+              "newFindings, resolved} vs. that baseline — an observation, not a gate signal. To gate a merge, " +
+              "run `tapp ci` (or the GitHub Action): it applies the deterministic policy and returns the " +
+              "pass/fail/inconclusive outcome.",
           },
         },
       },
@@ -2356,7 +2471,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       description:
         "Replay a deterministic, authored end-to-end test (a Flow) against iOS (XCUITest), Android " +
         "(ADB/UIAutomator), or web (Playwright), and return a scannable pass/fail report. A Flow is a list of steps + assertions " +
-        "(see docs/flows-architecture.md). Unlike tapp_run_qa (autonomous exploration), a Flow does EXACTLY " +
+        "(see docs/flows-architecture.md). Unlike tapp_explore (autonomous exploration), a Flow does EXACTLY " +
         "what you specify, the same way every time — use it for regression tests and verifying a fix. Steps: " +
         "{tap: X} · {type: {field: F, value: V}} · {swipe: up} · {back} · {wait_for: SCREEN}. Assertions " +
         "(deterministic): {assert_screen: X} · {assert_exists: X} · {assert_absent: X} · {assert_text: {of, contains}}. " +
@@ -2411,8 +2526,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         "Write a deterministic E2E Flow from a natural-language goal (e.g. 'sign in and open Settings'), " +
         "GROUNDED in the app's real screens so it can't invent steps. Tapp explores the app to build a " +
         "screen/control map (or reuses a recent run via captureId), then a model authors a Flow using only " +
-        "screens/controls that were actually observed. Saves it to .tapp/flows/<name>.yml and returns the " +
-        "YAML for review (optionally runs it). Needs a model backend (Tapp subscription token or " +
+        "screens/controls that were actually observed. Saves it as an UNTRUSTED PROPOSAL under " +
+        ".tapp/proposals/flows/<name>.yml (never directly into .tapp/flows/) and returns the YAML for " +
+        "review (optionally runs it). Review → replay against the real app → explicitly PROMOTE (move to " +
+        ".tapp/flows/) before CI depends on it. Needs a model backend (Tapp subscription token or " +
         "ANTHROPIC_API_KEY). Use this to bootstrap a test you then refine; use tapp_flow_run to replay it.",
       inputSchema: {
         type: "object",
@@ -2487,7 +2604,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       description:
         "Launch an installed iOS or Android app and return a SCREENSHOT of the screen it lands on " +
         "(plus the accessibility tree) — with NO exploration. This is the fast way (seconds) to just SEE a " +
-        "screen. Use this — NOT tapp_run_qa — whenever the user wants to view or screenshot a screen. Pass " +
+        "screen. Use this — NOT tapp_explore — whenever the user wants to view or screenshot a screen. Pass " +
         "appLaunchArgs like [\"--uitesting\"] to bypass login and land on the home screen, and appLaunchEnv for " +
         "a backend override. The app is launched fresh and closed afterward. (To screenshot a screen reached by " +
         "real login or several taps, use a session instead and call tapp_screenshot along the way.)",
@@ -2529,7 +2646,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: "tapp_install_app",
       title: "Install app on sim",
       description:
-        "Build a target iOS app for the booted simulator and install it, so it's ready for tapp_run_qa or " +
+        "Build a target iOS app for the booted simulator and install it, so it's ready for tapp_explore or " +
         "a session. Provide the Xcode project OR workspace path + scheme. Best-effort — apps with CocoaPods/" +
         "signing quirks may still need their normal build. Returns {ok, installed, simulator}.",
       inputSchema: {
@@ -2679,7 +2796,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const text =
       `🔨 Built **${path.basename(built.appPath)}** (scheme \`${built.scheme}\`) in ${fmtDuration(Date.now() - startedAt)}` +
       (bundleId ? ` — installed on the simulator as \`${bundleId}\`` : "") +
-      `\n\nNext: \`tapp_run_qa\` with \`appBundleId: "${bundleId || "<install it first>"}"\`.`;
+      `\n\nNext: \`tapp_explore\` with \`appBundleId: "${bundleId || "<install it first>"}"\`.`;
     return richResult(text, { ok: true, appPath: built.appPath, scheme: built.scheme, container: built.container, bundleId });
   }
 
@@ -2845,7 +2962,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     return richResult(L.join("\n"), summary);
   }
 
-  if (name === "tapp_run_qa") {
+  if (name === "tapp_explore" || name === "tapp_run_qa") { // tapp_run_qa: deprecated alias
     const unauthorized = ensureAuthorized(args);
     if (unauthorized) return unauthorized;
     const wantsWeb = isNonEmptyString(args.url);
@@ -2859,12 +2976,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // MCP concerns: auth, arg validation, and progress notifications.
     const progressToken = request.params && request.params._meta ? request.params._meta.progressToken : undefined;
     const budget = Math.max(1, Math.min(1000, asInteger(args.maxActions, 60)));
-    const notifyProgress = (unit) => (p) => {
+    const notifyProgress = (metric) => (p) => {
       if (progressToken === undefined) return;
       const total = p.max || budget;
       server.notification({
         method: "notifications/progress",
-        params: { progressToken, progress: p.action || 0, total, message: `🔍 Exploring… ${p.action}/${total} actions · ${p.states} ${unit} reached` },
+        params: { progressToken, progress: p.action || 0, total, message: `🔍 Exploring… ${p.action}/${total} actions · ${p.states} ${metric}` },
       }).catch(() => {});
     };
     if (wantsWeb) {
@@ -2875,7 +2992,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         testEmail: args.testEmail,
         testPassword: args.testPassword,
         baselineFindings: args.baselineFindings,
-        onProgress: notifyProgress("pages"),
+        onProgress: notifyProgress("pages reached"),
       });
       if (r.error) return errorResult(r.error, r.details || {});
       return richResult(r.text, r.structured);
@@ -2892,14 +3009,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         testPassword: args.testPassword,
         baselineFindings: args.baselineFindings,
         clearData: args.clearData !== false,
-        onProgress: notifyProgress("screens"),
+        onProgress: notifyProgress("screens reached"),
       });
       if (r.error) return errorResult(r.error, r.details || {});
       return richResult(r.text, r.structured);
     }
 
     let lastProgress = null;
-    const iosProgress = notifyProgress("screens");
+    const iosProgress = notifyProgress("structural states observed");
     const r = await runQaIos({
       bundleId: String(args.appBundleId).trim(),
       maxActions: args.maxActions,
@@ -2930,14 +3047,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (!isInsideDir(projectDir, resolvedOut)) return errorResult("outDir must be inside projectDir");
       const selectedPlatform = isNonEmptyString(args.platform) ? args.platform.trim().toLowerCase()
         : isNonEmptyString(args.url) ? "web"
-        : isNonEmptyString(args.androidAppId) || isNonEmptyString(args.apkPath) ? "android" : "ios";
+        : isNonEmptyString(args.androidAppId) || isNonEmptyString(args.apkPath) ? "android" : "";
       const progressToken = request.params && request.params._meta ? request.params._meta.progressToken : undefined;
       const budget = Math.max(1, Math.min(1000, asInteger(args.maxActions, 40)));
       const result = await initializeProductProject({
         projectDir, mode: operation, outDir,
         ownedUrl: isNonEmptyString(args.url) ? args.url.trim() : "",
         platform: isNonEmptyString(args.platform) ? args.platform.trim().toLowerCase() : operation === "explore" ? selectedPlatform : "",
-        target: isNonEmptyString(args.target) ? args.target.trim() : projectDir,
+        target: isNonEmptyString(args.target) ? args.target.trim() : "",
         bundleId: isNonEmptyString(args.appBundleId) ? args.appBundleId.trim() : "",
         appId: isNonEmptyString(args.androidAppId) ? args.androidAppId.trim() : "",
         apkPath: isNonEmptyString(args.apkPath) ? path.resolve(projectDir, args.apkPath.trim()) : undefined,
@@ -2953,9 +3070,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const { model, plan, written, exploration } = result;
       const blocking = model.requirements.filter((item) => item.severity === "blocking");
       const pending = plan.items.filter((item) => item.decision === "pending");
-      const summary = `🧭 Tapp init — ${model.application.name} · ${model.targets.length} target(s) · UI Map ${model.uiMap.status} (${model.uiMap.nodeCount} states/${model.uiMap.edgeCount} transitions) · ${plan.items.length} plan item(s), ${pending.length} pending · ${blocking.length} blocking requirement(s)${exploration ? ` · real ${exploration.platform} exploration ${exploration.verdict}${exploration.inconclusive ? " (inconclusive)" : ""}` : ""}`;
+      const summary = `🧭 Tapp init — ${model.application.name} · ${model.targets.length} target(s) · UI Map ${model.uiMap.status} (${model.uiMap.nodeCount} states/${model.uiMap.edgeCount} transitions) · ${plan.items.length} plan item(s), ${pending.length} pending · ${blocking.length} blocking requirement(s)${exploration ? ` · real ${exploration.platform} exploration: ${(exploration.findings || []).length} finding(s)${exploration.inconclusive ? " (inconclusive)" : ""}` : ""}`;
       return richResult(summary, { model, plan, written: written ? { modelPath: written.modelPath, planPath: written.planPath } : null, exploration });
-    } catch (error) { return errorResult("Could not initialize Tapp repository artifacts", { detail: error.message || String(error) }); }
+    } catch (error) {
+      const detail = error.message || String(error);
+      const message = error.details?.reason === "target-selection-required"
+        ? detail
+        : "Could not initialize Tapp repository artifacts";
+      return errorResult(message, { detail, ...(error.details || {}) });
+    }
   }
 
   if (name === "tapp_actor_config") {
@@ -3493,21 +3616,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const parsed = parseGeneratedFlow(mres.text);
     if (!parsed) return errorResult("Model did not return a valid Flow", { raw: mres.text.slice(0, 500) });
 
-    // 3) Ground-check + write.
+    // 3) Ground-check + write as an UNTRUSTED PROPOSAL (ADR-0005 decision 8: AI-generated work lands
+    //    as a draft under .tapp/proposals/, requires real-target replay + explicit human promotion,
+    //    and only then enters .tapp/flows/ where CI depends on it — never a direct write).
     const ungrounded = ungroundedScreens(parsed.steps, grounding);
     const flow = { name: args.name || parsed.name, app: bundleId, steps: parsed.steps };
     const slug = flow.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "generated-flow";
-    const dir = path.join(repoRoot, ".tapp", "flows");
+    const dir = path.join(repoRoot, ".tapp", "proposals", "flows");
     fs.mkdirSync(dir, { recursive: true });
     const outPath = path.join(dir, `${slug}.yml`);
+    const promotedPath = path.join(".tapp", "flows", `${slug}.yml`);
     const yamlRes = await runCommand("python3", [path.join(scriptsDir, "flow_lib.py"), "to-yaml", JSON.stringify(flow)], { cwd: repoRoot });
     const yaml = (yamlRes.stdout || "").trim();
     if (!yaml) return errorResult("Failed to render flow YAML", { stderr: yamlRes.stderr });
     fs.writeFileSync(outPath, yaml + "\n");
     const rel = path.relative(repoRoot, outPath);
 
-    const L = [`🤖 Generated flow **${flow.name}** from your goal → \`${rel}\``];
-    L.push(`Grounded in ${grounding.screens.length} observed screen(s). ${ungrounded.length ? `⚠️ references unobserved: ${ungrounded.join(", ")} — review before relying on it.` : "All referenced screens were observed."}`);
+    const L = [`🤖 Generated a flow **proposal** **${flow.name}** from your goal → \`${rel}\``];
+    L.push(`⚠️ This is an **untrusted draft**, not a committed test. Grounded in ${grounding.screens.length} observed screen(s). ${ungrounded.length ? `⚠️ references unobserved: ${ungrounded.join(", ")} — review before relying on it.` : "All referenced screens were observed."}`);
+    L.push(`**Review → replay → promote:** review it, replay it against the real app, and only then promote it (move to \`${promotedPath}\`) so CI can depend on it.`);
     L.push("", "```yaml", yaml, "```");
 
     // 4) Optionally replay it now.
@@ -3522,9 +3649,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         L.push("", "---", "", (rep.stdout || "").trim());
       }
     } else {
-      L.push("", `Replay it: \`tapp_flow_run\` with \`flowPath: "${rel}"\`.`);
+      L.push("", `Replay the proposal: \`tapp_flow_run\` with \`flowPath: "${rel}"\`. After it passes, promote it to \`.tapp/flows/\`.`);
     }
-    return richResult(L.join("\n"), { path: rel, flow, groundedScreens: grounding.screens.length, ungrounded });
+    return richResult(L.join("\n"), { path: rel, proposal: true, promotePath: promotedPath, flow, groundedScreens: grounding.screens.length, ungrounded });
   }
 
   if (name === "tapp_ui_tree") {
@@ -3592,7 +3719,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (isNonEmptyString(args.apkPath)) await driver.install(path.resolve(args.apkPath));
         const snap = await driver.launch({ clearData: args.clearData === true });
         const data = await driver.screenshot();
-        await driver.forceStop().catch(() => {});
         return {
           content: [
             { type: "text", text: `🚀 Launched \`${appId}\` (Android)\n\n` + formatScreen(snap.screenTitle, snap.elements) },

package/mcp-server/src/pr-selection.js

@@ -428,16 +428,17 @@ export function adoptPrCoverageProposal({ projectDir, prPlanPath, item, releaseP
   if (!ground || !fs.existsSync(mapPath)) throw new Error("Coverage proposal requires the repository's persistent UI Map");
   const map = JSON.parse(fs.readFileSync(mapPath, "utf8"));
   const node = (map.nodes || []).find((candidate) => candidate.id === ground.id && candidate.status !== "proposed");
-  if (!node) throw new Error(`Coverage proposal UI Map node is stale or missing: ${ground.id}`);
+  const refreshAdvice = "refresh the persistent UI Map with `tapp init --explore --refresh`, rerun `tapp pr gate`, then retry `tapp pr adopt`";
+  if (!node) throw new Error(`Coverage proposal UI Map node is stale or missing: ${ground.id}; ${refreshAdvice}`);
   if (target.navigation?.route && !(node.routes || []).some((route) => route.platform === target.platform && route.path === target.navigation.route && route.replayable === true)) {
-    throw new Error(`Coverage proposal route is stale in the persistent UI Map: ${target.navigation.route}`);
+    throw new Error(`Coverage proposal route is stale in the persistent UI Map: ${target.navigation.route}; ${refreshAdvice}`);
   }
   if (target.navigation?.mode === "ui-map-path") {
     const currentNavigation = replayableUiMapNavigation(map, node.id, target.platform);
     const expectedEdges = (target.navigation.steps || []).map((step) => step.edgeId);
     const currentEdges = (currentNavigation.steps || []).map((step) => step.edgeId);
     if (currentNavigation.status !== "replayable" || JSON.stringify(expectedEdges) !== JSON.stringify(currentEdges)) {
-      throw new Error(`Coverage proposal UI Map path is stale for ${node.name}`);
+      throw new Error(`Coverage proposal UI Map path is stale for ${node.name}; ${refreshAdvice}`);
     }
   }
   const releasePlan = JSON.parse(fs.readFileSync(targetPath, "utf8"));