@aarwitz/tapp 0.16.5 → 0.17.0-rc.10

package/mcp-server/src/android-driver.js

@@ -41,6 +41,16 @@ function runFile(command, args, { encoding = "utf8", timeout = 30_000, maxBuffer
   });
 }
 
+export function parseLatestAndroidCrashExitInfo(output) {
+  const blocks = String(output || "").split(/ApplicationExitInfo #\d+:/).slice(1);
+  for (const block of blocks) {
+    const reason = block.match(/\breason=(4|5)\s+\((?:APP CRASH|NATIVE CRASH)/);
+    const identity = block.match(/\btimestamp=([^\n]+?)\s+pid=(\d+)\b/);
+    if (reason && identity) return `${identity[1].trim()}|${identity[2]}|${reason[1]}`;
+  }
+  return null;
+}
+
 function entityDecode(value) {
   return String(value || "")
     .replaceAll(""", '"').replaceAll("'", "'")
@@ -118,8 +128,22 @@ export function detectAndroidScreen(elements, activity = "") {
 
 export function isAndroidAppSnapshot(snapshot, appId) {
   if (!snapshot || !appId) return false;
-  if (String(snapshot.activity || "").startsWith(`${appId}/`)) return true;
-  return snapshot.elements.some((e) => e.package === appId);
+  const activity = String(snapshot.activity || "");
+  const ownsActivity = activity.startsWith(`${appId}/`);
+  const packages = new Set((snapshot.elements || []).map((e) => e.package).filter(Boolean));
+  const ownsElements = packages.has(appId);
+  // dumpXml and dumpsys used to run concurrently. If an app crashed while they were sampled, a
+  // stale activity from the dead app could be paired with another app's UI tree and Tapp would map
+  // that unrelated app as the crash destination. When both signals exist, require agreement.
+  if (activity && packages.size) return ownsActivity && ownsElements;
+  return ownsActivity || ownsElements;
+}
+
+function isSystemOverlayOverApp(snapshot, appId) {
+  if (!snapshot || !appId || !String(snapshot.activity || "").startsWith(`${appId}/`)) return false;
+  const packages = new Set((snapshot.elements || []).map((element) => element.package).filter(Boolean));
+  return packages.size > 0 && !packages.has(appId)
+    && [...packages].every((name) => name === "android" || name.startsWith("com.android.systemui"));
 }
 
 export class AndroidDriver {
@@ -158,6 +182,19 @@ export class AndroidDriver {
     if (this.appId) await this.adb(["shell", "am", "force-stop", this.appId]);
   }
 
+  async isProcessAlive() {
+    if (!this.appId) return false;
+    const r = await this.adb(["shell", "pidof", this.appId]);
+    return r.code === 0 && /\d/.test(String(r.stdout || ""));
+  }
+
+  async latestCrashExitInfo() {
+    if (!this.appId) return null;
+    const r = await this.adb(["shell", "dumpsys", "activity", "exit-info", this.appId]);
+    if (r.code !== 0) return null;
+    return parseLatestAndroidCrashExitInfo(r.stdout);
+  }
+
   async clearData() {
     if (!this.appId) throw new Error("appId is required to clear Android app data");
     const r = await this.adb(["shell", "pm", "clear", this.appId]);
@@ -175,7 +212,42 @@ export class AndroidDriver {
     const r = await this.adb(["shell", "am", "start", "-W", "-n", component], { timeout: 30_000 });
     if (r.code !== 0 || !/Status:\s*ok/i.test(String(r.stdout))) throw new Error((r.stderr || r.stdout || `Could not launch ${this.appId}`).trim());
     await sleep(600);
-    return this.snapshot();
+    return this.waitForOwnedSnapshot();
+  }
+
+  async closeSystemDialogs() {
+    // A crash dialog from the previous app can outlive that process and cover a
+    // newly launched app. The shell broadcast only closes system-owned surfaces;
+    // it does not clear crash history or interact with the app under test.
+    await this.adb(["shell", "am", "broadcast", "-a", "android.intent.action.CLOSE_SYSTEM_DIALOGS"]);
+  }
+
+  async waitForOwnedSnapshot(timeoutMs = 12_000) {
+    const deadline = Date.now() + timeoutMs;
+    let latest;
+    let consecutiveOwned = 0;
+    let overlayDismissed = false;
+    do {
+      latest = await this.snapshot();
+      if (isAndroidAppSnapshot(latest, this.appId)) {
+        consecutiveOwned += 1;
+        // One mixed dumpsys/UIAutomator sample caused cross-run contamination.
+        // Require agreement twice before handing the surface to exploration.
+        if (consecutiveOwned >= 2) return latest;
+      } else {
+        consecutiveOwned = 0;
+        if (!overlayDismissed && isSystemOverlayOverApp(latest, this.appId)) {
+          overlayDismissed = true;
+          await this.closeSystemDialogs();
+        }
+      }
+      if (Date.now() >= deadline) break;
+      // Activity and UIAutomator are intentionally required to agree. During app
+      // launch they may momentarily describe opposite sides of the transition;
+      // retry that mixed snapshot instead of turning it into zero-screen evidence.
+      await sleep(150);
+    } while (Date.now() < deadline);
+    return latest;
   }
 
   async currentActivity() {
@@ -210,6 +282,19 @@ export class AndroidDriver {
     return { screenTitle: detectAndroidScreen(elements, activity), elements, activity, xml };
   }
 
+  async observeActivityTransition(beforeActivity, timeoutMs = 700) {
+    const initial = String(beforeActivity || "");
+    if (!initial) return false;
+    const deadline = Date.now() + timeoutMs;
+    do {
+      const current = await this.currentActivity();
+      if (current && current !== initial) return true;
+      if (Date.now() >= deadline) break;
+      await sleep(60);
+    } while (Date.now() < deadline);
+    return false;
+  }
+
   async screenshot(filePath) {
     const r = await this.adb(["exec-out", "screencap", "-p"], { encoding: "buffer", timeout: 30_000, maxBuffer: 32 * 1024 * 1024 });
     if (r.code !== 0 || !r.stdout?.length) throw new Error("Android screenshot failed");

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

@@ -8,6 +8,8 @@ import { semanticUiKey } from "./ui-map.js";
 
 const ERROR_RE = /\b(something went wrong|internal server error|an error occurred|failed to load|unhandled exception|has stopped)\b/i;
 const DESTRUCTIVE_RE = /\b(delete|remove|purchase|buy now|pay now|reset|erase|unsubscribe|sign out|log out|logout)\b/i;
+const AUTH_SUBMIT_RE = /\b(sign[ -]?in|log[ -]?in|continue|submit)\b/i;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 function stateHash(snap) {
   return snap.elements.map((e) => `${androidElementKey(e)}:${e.text}:${e.x},${e.y}`).join("|");
@@ -40,8 +42,24 @@ function isDestructive(e) {
   return DESTRUCTIVE_RE.test(`${e.label || ""} ${e.text || ""} ${e.description || ""} ${e.id || ""}`.replace(/[_-]+/g, " "));
 }
 
-export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40, timeoutSec = 300, outDir, testEmail = "", testPassword = "", clearData = true, seedTargets = [], onProgress = () => {}, driver }) {
+export function isAndroidAuthSubmit(element) {
+  return AUTH_SUBMIT_RE.test(`${element?.label || ""} ${element?.text || ""} ${element?.description || ""} ${element?.id || ""}`.replace(/[_-]+/g, " "));
+}
+
+export function isAndroidBlankSnapshot(snapshot) {
+  const elements = snapshot?.elements || [];
+  const meaningful = elements.some((element) =>
+    String(element.text || "").trim() ||
+    String(element.description || "").trim() ||
+    (String(element.id || "").trim() && !/^(android:)?id\/content$/i.test(String(element.id || "").trim()))
+  );
+  const interactive = elements.some((element) => element.hittable && (element.clickable || /Button|EditText|Tab|Switch|CheckBox/i.test(element.type)));
+  return !meaningful && !interactive;
+}
+
+export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40, timeoutSec = 300, outDir, testEmail = "", testPassword = "", clearData = true, seedTargets = [], onProgress = () => {}, driver, screenshotDelayMs }) {
   const d = driver || new AndroidDriver({ appId, serial });
+  const visualSettleMs = Number.isFinite(screenshotDelayMs) ? Math.max(0, screenshotDelayMs) : (driver ? 0 : 350);
   d.appId = appId;
   await d.ensureDevice();
   if (apkPath) await d.install(apkPath);
@@ -56,7 +74,33 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
   const visited = new Map();
   let issues = 0;
   let actions = 0;
+  const crashExitBaseline = typeof d.latestCrashExitInfo === "function" ? await d.latestCrashExitInfo() : null;
   let snap = await d.launch({ clearData });
+  let crashReported = false;
+
+  const reportProcessExit = async (screen, step) => {
+    if (typeof d.isProcessAlive !== "function") return false;
+    // Android may reveal the launcher before the crashing process disappears from
+    // pidof. A one-shot liveness sample made identical crashes scheduler-dependent.
+    // Poll only after app ownership is already lost: external intents and ordinary
+    // Back boundaries keep the originating process alive and remain boundaries.
+    let alive = await d.isProcessAlive();
+    let latestCrash = typeof d.latestCrashExitInfo === "function" ? await d.latestCrashExitInfo() : null;
+    const exitDeadline = Date.now() + 2_000;
+    while (alive && (!latestCrash || latestCrash === crashExitBaseline) && Date.now() < exitDeadline) {
+      await sleep(150);
+      alive = await d.isProcessAlive();
+      latestCrash = typeof d.latestCrashExitInfo === "function" ? await d.latestCrashExitInfo() : null;
+    }
+    const recordedCrash = !!latestCrash && latestCrash !== crashExitBaseline;
+    if ((alive && !recordedCrash) || crashReported) return false;
+    crashReported = true;
+    emit("ISSUE", { type: "crash", severity: "critical", title: "App process exited during exploration", screen: screen || "Launch", step });
+    issues += 1;
+    return true;
+  };
+
+  if (!isAndroidAppSnapshot(snap, appId)) await reportProcessExit("Launch", 0);
 
   const normalizedTargets = (Array.isArray(seedTargets) ? seedTargets : []).filter((target) =>
     target?.platform === "android" && target?.status === "planned" && target?.navigation?.status === "replayable" &&
@@ -69,6 +113,10 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
     const screen = snapshot.screenTitle;
     if (!visited.has(hash)) {
       visited.set(hash, screen);
+      // UIAutomator can expose a fully populated hierarchy a fraction before
+      // SurfaceFlinger composites the first app frame. Give real devices one
+      // bounded draw interval so retained PNG evidence matches the tree.
+      if (visualSettleMs) await sleep(visualSettleMs);
       await d.screenshot(path.join(screenshots, `${String(visited.size).padStart(2, "0")}-${screen.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}.png`)).catch(() => {});
     }
     const inputs = inputDescriptors(snapshot.elements);
@@ -95,7 +143,11 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
       const before = state;
       snap = await d.settle();
       state = await recordState(snap);
-      if (!state) { failure = "The UI Map path left the application foreground"; break; }
+      if (!state) {
+        const crashed = await reportProcessExit(before.screen, actions);
+        failure = crashed ? "The application process exited while replaying the UI Map path" : "The UI Map path left the application foreground";
+        break;
+      }
       emit("TRANSITION", { from: before.screen, to: state.screen, action: selector, changed: before.hash !== state.hash });
       onProgress({ action: actions, max: maxActions, states: visited.size });
     }
@@ -113,7 +165,10 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
     // UIAutomator can still describe the launcher or a system surface after
     // Back/external navigation. Those are exploration boundaries, never nodes
     // in the application-owned UI Map.
-    if (!isAndroidAppSnapshot(snap, appId)) break;
+    if (!isAndroidAppSnapshot(snap, appId)) {
+      await reportProcessExit(visited.size ? [...visited.values()].at(-1) : "Launch", actions);
+      break;
+    }
     const recorded = await recordState(snap);
     if (!recorded) break;
     const { hash, screen, inputs } = recorded;
@@ -124,7 +179,7 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
       emit("ISSUE", { type: "error_surface", severity: "high", title: "Visible error surface", screen, step: actions });
       issues += 1;
     }
-    if (snap.elements.filter((e) => e.hittable).length === 0) {
+    if (isAndroidBlankSnapshot(snap)) {
       emit("ISSUE", { type: "blank_screen", severity: "high", title: "No usable controls or content", screen, step: actions });
       issues += 1;
     }
@@ -154,16 +209,31 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
     });
     if (candidate) {
       const target = controlLabel(candidate);
+      const loginSubmit = inputs.some((input) => input.secure) && isAndroidAuthSubmit(candidate);
       tried.add(`${hash}|tap|${target}`);
       const before = hash;
       const r = await d.tap(target, snap);
       actions += 1;
-      snap = await d.settle();
+      // UIAutomator can miss a short-lived Activity that opens and cleanly
+      // returns before its next hierarchy dump. Observe the cheaper Activity
+      // signal in parallel so a real transient response is not called dead.
+      const activityEffect = r.status === "ok" && typeof d.observeActivityTransition === "function"
+        ? d.observeActivityTransition(snap.activity)
+        : Promise.resolve(false);
+      const [settledSnap, activityEffectObserved] = await Promise.all([d.settle(), activityEffect]);
+      snap = settledSnap;
       const after = stateHash(snap);
-      emit("ACTION", { type: "tap", target, reason: "untried_control", step: actions, screen, status: r.status });
-      if (!isAndroidAppSnapshot(snap, appId)) break;
+      emit("ACTION", { type: loginSubmit ? "login_submit" : "tap", target, reason: "untried_control", step: actions, screen, status: r.status });
+      if (!isAndroidAppSnapshot(snap, appId)) {
+        await reportProcessExit(screen, actions);
+        break;
+      }
       emit("TRANSITION", { from: screen, to: snap.screenTitle, action: target, changed: before !== after });
-      if (r.status === "ok" && before === after && candidate.clickable) {
+      const authFailed = loginSubmit && inputDescriptors(snap.elements).some((input) => input.secure);
+      if (r.status === "ok" && authFailed) {
+        emit("ISSUE", { type: "auth_failed", severity: "high", title: "Sign-in attempt remained on the login screen", screen, target, step: actions });
+        issues += 1;
+      } else if (r.status === "ok" && before === after && candidate.clickable && !activityEffectObserved) {
         emit("ISSUE", { type: "unresponsive_element", severity: "medium", title: `Control did not respond: ${target}`, screen, target, step: actions });
         issues += 1;
       }
@@ -179,7 +249,10 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
       actions += 1;
       const next = await d.settle();
       emit("ACTION", { type: "back", target: "system back", reason: "state_exhausted", step: actions, screen });
-      if (!isAndroidAppSnapshot(next, appId)) break;
+      if (!isAndroidAppSnapshot(next, appId)) {
+        await reportProcessExit(screen, actions);
+        break;
+      }
       emit("TRANSITION", { from: screen, to: next.screenTitle, action: "back", changed: stateHash(next) !== hash });
       if (stateHash(next) !== hash) { snap = next; continue; }
     }
@@ -187,11 +260,7 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
   }
 
   const timedOut = Date.now() >= deadline;
-  if (timedOut) {
-    emit("ISSUE", { type: "explore_timeout", severity: "medium", title: `Exploration timed out after ${timeoutSec}s`, screen: snap.screenTitle, step: actions });
-    issues += 1;
-  }
-  emit("COMPLETE", { actions, states: visited.size, issues, screens: [...new Set(visited.values())].join(","), outcome: timedOut ? "timeout" : "complete" });
+  emit("COMPLETE", { actions, states: visited.size, issues, screens: [...new Set(visited.values())].join(","), outcome: timedOut ? "timeout" : "complete", timedOut, ...(timedOut ? { timeoutSeconds: timeoutSec } : {}) });
   onProgress({ action: actions, max: maxActions, states: visited.size });
   return { markersPath, outDir, actions, states: visited.size, issues, timedOut, seedTargets: normalizedTargets };
 }

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

@@ -114,8 +114,8 @@ function applyRuntimeTargetValidation(root, targets, validation) {
         build: { container, scheme, configuration },
         evidence: {
           ...(captureId ? { capture: portableEvidenceReference(`tapp-capture:${captureId}`) } : {}),
-          verdict: String(validation.evidence?.verdict || "unknown"),
           inconclusive: validation.evidence?.inconclusive === true,
+          findingCount: Number(validation.evidence?.findingCount || 0),
           ...(validation.evidence?.observedAt ? { observedAt: String(validation.evidence.observedAt) } : {}),
         },
         detail: "Tapp built this repository target with the recorded scheme, installed it, launched it, and produced UI Map evidence.",
@@ -149,8 +149,8 @@ function persistedTargetValidations(root, outDir) {
       },
       evidence: {
         captureId: capture.startsWith("tapp-capture:") ? capture.slice("tapp-capture:".length) : "",
-        verdict: validation.evidence?.verdict,
         inconclusive: validation.evidence?.inconclusive === true,
+        findingCount: Number(validation.evidence?.findingCount || 0),
         observedAt: validation.evidence?.observedAt,
       },
     }];
@@ -424,7 +424,7 @@ function applicationName(root, targets) {
   return pkg?.name || (targets.length === 1 ? targets[0].name : path.basename(root));
 }
 
-export async function inspectApplicationRepository({ projectDir, ownedUrl = "", platform = "", targetValidation = null, outDir = ".tapp" } = {}) {
+export async function inspectApplicationRepository({ projectDir, ownedUrl = "", platform = "", targetValidation = null, defaultTargetId = "", outDir = ".tapp" } = {}) {
   const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
   const inventory = walk(root);
   let targets = [
@@ -567,9 +567,14 @@ export async function inspectApplicationRepository({ projectDir, ownedUrl = "",
   for (const error of taskErrors) requirements.push({ id: stableId("task-error", error.path), severity: "blocking", status: "invalid", message: error.error, remediation: `Fix ${error.path} before generation.` });
   for (const error of contractErrors) requirements.push({ id: stableId("contract-error", error.path), severity: "blocking", status: "invalid", message: error.error, remediation: `Fix ${error.path} before trusting the release plan.` });
 
+  const recordedDefaultTargetId = targets.some((target) => target.id === defaultTargetId)
+    ? defaultTargetId
+    : targets.length === 1 ? targets[0].id : "";
   const model = {
     schemaVersion: 1, kind: "tapp-application-model",
-    application: { name: applicationName(root, targets), repositoryRoot: ".", platforms: [...new Set(targets.map((target) => target.platform))].sort(), targetIds: targets.map((target) => target.id) },
+    // defaultTargetId is recorded only when selection is unambiguous or the user explicitly chose
+    // a target during source-connected exploration. Detection order is not user intent.
+    application: { name: applicationName(root, targets), repositoryRoot: ".", platforms: [...new Set(targets.map((target) => target.platform))].sort(), targetIds: targets.map((target) => target.id), defaultTargetId: recordedDefaultTargetId },
     targets,
     actors,
     entities,
@@ -1415,8 +1420,8 @@ export function recordContractProposalValidation(plan, { id = "", name = "", pla
 export function recordGeneratedTaskProposalValidation({ projectDir, item, platform, evidence = "", detail = "" } = {}) {
   if (!["ios", "android", "web"].includes(platform)) throw new Error("platform must be ios|android|web");
   const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
-  const proposalMarkers = [".tapp", ".autotap"].map((directory) => `${path.sep}${directory}${path.sep}proposals${path.sep}tasks${path.sep}`);
-  const reviewedMarkers = [".tapp", ".autotap"].map((directory) => `${path.sep}${directory}${path.sep}tasks${path.sep}`);
+  const proposalMarkers = [`${path.sep}.tapp${path.sep}proposals${path.sep}tasks${path.sep}`];
+  const reviewedMarkers = [`${path.sep}.tapp${path.sep}tasks${path.sep}`];
   const updated = [];
   for (const taskPath of item?.generation?.taskPaths || []) {
     const absolute = path.resolve(root, taskPath);
@@ -1461,8 +1466,7 @@ export function mergeGeneratedTaskProposalValidation(plan, updates = []) {
 }
 
 function promotedDestination(root, source, kind) {
-  const marker = [".tapp", ".autotap"]
-    .map((directory) => `${path.sep}${directory}${path.sep}proposals${path.sep}${kind}${path.sep}`)
+  const marker = [`${path.sep}.tapp${path.sep}proposals${path.sep}${kind}${path.sep}`]
     .find((candidate) => source.includes(candidate));
   if (!marker) throw new Error(`Proposal ${kind.slice(0, -1)} is outside .tapp/proposals/${kind}: ${relative(root, source)}`);
   const index = source.indexOf(marker);
@@ -1505,7 +1509,7 @@ export async function promoteValidatedProposals(plan, { projectDir, ids = [] } =
     for (const taskPath of item.generation.taskPaths || []) {
       const source = path.resolve(root, taskPath);
       if (!fs.existsSync(source)) throw new Error(`Generated Task is missing: ${taskPath}`);
-      if (![".tapp", ".autotap"].some((directory) => String(source).includes(`${path.sep}${directory}${path.sep}proposals${path.sep}tasks${path.sep}`))) continue;
+      if (!String(source).includes(`${path.sep}.tapp${path.sep}proposals${path.sep}tasks${path.sep}`)) continue;
       const destination = promotedDestination(root, source, "tasks");
       moves.set(source, destination);
       let task = taskRecords.get(source);

package/mcp-server/src/browser-product.js

@@ -109,7 +109,7 @@ function assetPath(pathname) {
 }
 
 function captureRoot() {
-  return path.join(process.env.TAPP_HOME || process.env.AUTOTAP_HOME || path.join(os.homedir(), ".tapp"), "captures");
+  return path.join(process.env.TAPP_HOME || path.join(os.homedir(), ".tapp"), "captures");
 }
 
 function capturePath(captureId, relative = "report.html") {

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

@@ -16,17 +16,19 @@
 //                         [--pr-plan <plan.json>]           # selected PR contract execution manifest
 //                         [--project-dir <repo> --maintenance-url <url>]
 //                                                           # optional disposable web patch replay
-//                         [--fail-on <gate|blocked|any>]    # default: gate
+//                         [--fail-on <gate|absolute|any>]    # default: gate
 //
 // Gate policy (--fail-on):
 //   gate     fail when the run introduced NEW high/critical findings vs. the baseline
-//            (no baseline ⇒ falls back to `blocked`), or when any flow failed. The default:
-//            pre-existing debt doesn't block, regressions and broken flows do.
-//   blocked  fail when the verdict is blocked/inconclusive, or when any flow failed.
-//   any      fail on any finding at all, or any flow failure. Strictest.
+//            (no baseline ⇒ falls back to `absolute`), or when any suite failed. The default:
+//            pre-existing debt doesn't block, regressions and broken suites do.
+//   absolute fail on any current-run deterministic findings-block (critical / risk threshold) or an
+//            inconclusive run, or any failed suite — no baseline needed.
+//   any      fail on any finding at all, or any suite failure. Strictest.
 import fs from "fs";
 import path from "node:path";
-import { buildQaReport, computeRegression, computeContentCollapse, computeReachabilityLoss, qaScoreLabel, verdictBadge } from "./report.js";
+import { execSync } from "node:child_process";
+import { buildQaReport, computeRegression, computeContentCollapse, computeReachabilityLoss, evaluateGate, GATE_EXIT } from "./report.js";
 import { writeHtmlReport } from "./html-report.js";
 import { buildUiMapFromMarkers, writeUiMap } from "./ui-map.js";
 import { proposeSelectorMaintenance, validateWebMaintenanceProposal } from "./maintenance-proposal.js";
@@ -59,13 +61,31 @@ function parseArgs(argv) {
     console.error("Required: --markers <ocqa-markers.txt>");
     process.exit(2);
   }
-  if (!["gate", "blocked", "any"].includes(args.failOn)) {
-    console.error(`--fail-on must be gate|blocked|any, got: ${args.failOn}`);
+  if (!["gate", "absolute", "any"].includes(args.failOn)) {
+    console.error(`--fail-on must be gate|absolute|any, got: ${args.failOn}`);
     process.exit(2);
   }
   return args;
 }
 
+// A GateRun records the revision it judged. A commit SHA alone doesn't represent a dirty local
+// checkout, so record both. Best-effort: CI env → git → nulls (never throws / fails the gate).
+function gitRevision(repoDir) {
+  // Inspect the TARGET repository (--project-dir) when given, not the process cwd, so a gate run
+  // launched from elsewhere doesn't record the wrong repo's SHA. GITHUB_SHA still wins in CI.
+  const opts = { stdio: ["ignore", "pipe", "ignore"], ...(repoDir ? { cwd: repoDir } : {}) };
+  const sh = (cmd) => execSync(cmd, opts).toString().trim();
+  let sha = process.env.GITHUB_SHA || null;
+  let dirty = false;
+  try {
+    if (!sha) sha = sh("git rev-parse HEAD") || null;
+    dirty = sh("git status --porcelain").length > 0;
+  } catch {
+    /* not a git checkout / git unavailable */
+  }
+  return { sha, dirty };
+}
+
 async function validateMaintenancePlan(plan, args) {
   if (!plan || plan.platform !== "web" || !args.projectDir || !args.maintenanceUrl) return plan;
   let remaining = 3;
@@ -101,7 +121,7 @@ async function validateMaintenancePlan(plan, args) {
 // Port of flow_lib.py report() / FlowRunnerService.parseReport — kept in sync deliberately.
 function parseFlowLog(logPath) {
   const name = logPath.split("/").pop().replace(/\.log$/, "");
-  if (!fs.existsSync(logPath)) return { name, passed: false, total: 0, failed: 0, steps: [], missing: true };
+  if (!fs.existsSync(logPath)) return { name, passed: false, total: 0, failed: 0, steps: [], missing: true, modelObserved: false, deterministicFailed: false };
   const steps = [];
   let total = 0, executed = 0, failed = 0, passed = false, sawResult = false, flowName = null, kind = "flow", contract = "", criticality = "";
   for (const raw of fs.readFileSync(logPath, "utf8").split(/\r?\n/)) {
@@ -132,7 +152,12 @@ function parseFlowLog(logPath) {
     failed = steps.filter((s) => s.status === "fail").length;
     passed = steps.length > 0 && failed === 0;
   }
-  return { name: flowName || name, kind, ...(contract ? { contract, criticality } : {}), passed, total, executed, failed, steps };
+  // Structural evidence authority (ADR-0005): assert_ai steps are model-observed. A deterministic
+  // step failure is real; a suite that only carries a model assertion cannot be decided by the
+  // default deterministic gate. evaluateGate reads these flags, never the raw action string.
+  const modelObserved = steps.some((s) => s.action === "assert_ai");
+  const deterministicFailed = steps.some((s) => s.action !== "assert_ai" && s.status === "fail");
+  return { name: flowName || name, kind, ...(contract ? { contract, criticality } : {}), passed, total, executed, failed, steps, modelObserved, deterministicFailed };
 }
 
 function loadBaseline(baselinePath) {
@@ -338,16 +363,19 @@ function enrichPrPlan(plan, contracts, currentUiMap = null, markersPath = "", pr
 }
 
 const SEV_ICON = { critical: "🟥", high: "🟧", medium: "🟨", low: "🟩" };
+const GATE_BADGE = { pass: "🟢 PASS", fail: "🔴 FAIL", inconclusive: "🟡 INCONCLUSIVE" };
 
 function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan, gate) {
   const lines = [];
-  lines.push(`## tapp release check — ${verdictBadge(report)}`);
+  // The header shows the GATE decision (pass/fail/inconclusive), not a ship verdict — exploration
+  // only observes; the gate judges (ADR-0005).
+  lines.push(`## tapp release check — ${GATE_BADGE[gate.outcome] || gate.outcome}`);
   lines.push("");
   lines.push(report.headline);
   lines.push("");
-  lines.push(`**${qaScoreLabel(report)}** · ${report.screensExplored} screens · ${report.actionsPerformed} actions · ${report.findingCounts.total} finding(s)`);
+  lines.push(`${report.screensExplored} screens · ${report.actionsPerformed} actions · ${report.findingCounts.total} finding(s)`);
   if (report.platform === "web") {
-    lines.push(`**Verdict basis:** ${report.verdictFindingCounts?.total || 0} deterministic finding(s); ${report.sampledFindingCounts?.total || 0} sampled probe finding(s) are advisory.`);
+    lines.push(`**Deterministic basis:** ${report.deterministicFindingCounts?.total || 0} deterministic finding(s); ${report.sampledFindingCounts?.total || 0} sampled probe finding(s) are advisory.`);
   }
   if (report.uiMap) lines.push(`**UI Map:** ${report.uiMap.nodeCount} states · ${report.uiMap.edgeCount} transitions · ${report.uiMap.controlCount} semantic controls`);
   if (report.findings.length) {
@@ -359,18 +387,22 @@ function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan,
     }
   }
   if (regression) {
-    const g = regression.gate;
+    // This is the GATE's report, so it may judge the regression. computeRegression is comparison-only,
+    // so derive the new-high/critical count here (mirrors evaluateGate).
+    const newCritical = regression.newFindings.filter((f) => f.severity === "critical").length;
+    const newHigh = regression.newFindings.filter((f) => f.severity === "high").length;
+    const regFailed = newCritical + newHigh > 0;
     lines.push("");
-    lines.push(`### Since baseline — ${g.failed ? "🔴 regression gate FAILED" : "🟢 regression gate passed"}`);
+    lines.push(`### Since baseline — ${regFailed ? "🔴 regression gate FAILED" : "🟢 regression gate passed"}`);
     lines.push(`+${regression.counts.new} new · ${regression.counts.persisting} persisting · ${regression.counts.resolved} resolved` +
-      (g.failed ? ` — **${g.newCritical} new critical, ${g.newHigh} new high**` : ""));
+      (regFailed ? ` — **${newCritical} new critical, ${newHigh} new high**` : ""));
     for (const f of regression.newFindings) {
       lines.push(`- NEW ${SEV_ICON[f.severity] || ""} ${f.severity}: ${f.title} (${f.screen ?? "—"})`);
     }
   } else if (gate.policy === "gate") {
     lines.push("");
     lines.push("### Baseline — 🟡 not active yet");
-    lines.push("No baseline was supplied, so this run used the blocked/inconclusive fallback. Save this report as a baseline—or run the GitHub Action on the default branch—to activate new-regression gating.");
+    lines.push("No baseline was supplied. This gate still enforces absolute blockers and reviewed suite failures, but it cannot identify new regressions until a baseline is saved.");
   }
   if (prPlan) {
     lines.push("");
@@ -444,15 +476,23 @@ function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan,
     }
   }
   lines.push("");
-  lines.push(`**Gate (${gate.policy}): ${gate.failed ? "🔴 FAIL" : "🟢 PASS"}**${gate.reasons.length ? " — " + gate.reasons.join("; ") : ""}`);
+  const badge = GATE_BADGE[gate.outcome] || (gate.failed ? "🔴 FAIL" : "🟢 PASS");
+  lines.push(`**Gate (${gate.policy}): ${badge}**${gate.reasons.length ? " — " + gate.reasons.join("; ") : ""}`);
+  // 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";
+  lines.push(`_target: ${gate.target || "—"} · revision: ${rev} · policy: ${gate.policy} v${gate.policyVersion || "?"}_`);
+  if (Array.isArray(gate.checked) && gate.checked.length) lines.push(`_Checked: ${gate.checked.join(" · ")}_`);
+  if (Array.isArray(gate.notChecked) && gate.notChecked.length) lines.push(`_Not checked: ${gate.notChecked.join(" · ")}_`);
   return lines.join("\n");
 }
 
 const args = parseArgs(process.argv.slice(2));
-const report = buildQaReport(args.markers, { platform: args.platform || "ios" });
+const report = buildQaReport(args.markers, { platform: args.platform || "ios", target: args.label || null });
 if (!report) {
-  console.error(`No OCQA markers found at ${args.markers} — the exploration did not run.`);
-  process.exit(1);
+  // Required evidence could not be obtained — this is inconclusive (fails closed), not a gate FAIL
+  // and not a usage error. See the outcome model in report.js (GATE_EXIT).
+  console.error(`No OCQA markers found at ${args.markers} — the exploration did not run (inconclusive).`);
+  process.exit(GATE_EXIT.inconclusive);
 }
 let currentUiMap = null;
 if (args.htmlDir) {
@@ -491,18 +531,12 @@ if (collapsed.length) {
   report.findings.push(...collapsed);
   report.findingCounts.high += collapsed.length;
   report.findingCounts.total += collapsed.length;
-  report.verdictFindingCounts.high += collapsed.length;
-  report.verdictFindingCounts.total += collapsed.length;
-  // Keep native scoring compatible. Exploratory web deliberately has no scalar; deterministic
-  // baseline regressions still raise its verdict directly.
-  if (Number.isFinite(report.confidence)) {
-    report.confidence = Math.max(0, report.confidence - collapsed.length * 10);
-    report.releaseScore = report.confidence;
-  }
-  if (report.verdict === "ready") {
-    report.verdict = Number.isFinite(report.confidence) && report.confidence < 50 ? "blocked" : "caution";
-  }
-  report.headline = `Proceed with caution — ${collapsed.length} screen(s) regressed vs. baseline (content collapsed or became unreachable).`;
+  report.deterministicFindingCounts.high += collapsed.length;
+  report.deterministicFindingCounts.total += collapsed.length;
+  // Collapsed/unreachable screens are deterministic regressions: they raise the deterministic finding
+  // counts (so findingsBlock sees them) and count as new-vs-baseline (so the gate fails on them).
+  // No score/verdict to mutate — exploration is scoreless; the gate renders the outcome.
+  report.headline = `${collapsed.length} screen(s) regressed vs. baseline (content collapsed or became unreachable).`;
 }
 const regression = computeRegression(report.findings, baseline?.findings ?? null);
 const runs = args.flowLogs.map(parseFlowLog);
@@ -519,34 +553,19 @@ try {
   process.exit(2);
 }
 
-const reasons = [];
-const failedFlows = flows.filter((f) => !f.passed);
-if (failedFlows.length) reasons.push(`${failedFlows.length} flow(s) failed`);
-const failedScenarios = scenarios.filter((scenario) => !scenario.passed);
-if (failedScenarios.length) reasons.push(`${failedScenarios.length} multi-actor scenario(s) failed`);
-const failedContracts = contracts.filter((contract) => !contract.passed);
-if (failedContracts.length) reasons.push(`${failedContracts.length} release contract(s) failed`);
-if (prPlan?.execution.notRun) reasons.push(`${prPlan.execution.notRun} selected release contract(s) did not run`);
-if (prPlan?.execution.explorationFailed) reasons.push(`${prPlan.execution.explorationFailed} planned PR exploration target(s) failed or were not reached`);
-if (args.failOn === "any") {
-  if (report.findingCounts.total > 0) reasons.push(`${report.findingCounts.total} finding(s) (fail-on: any)`);
-} else if (args.failOn === "blocked" || (args.failOn === "gate" && !regression)) {
-  if (report.verdict === "blocked") reasons.push("verdict is blocked");
-  if (report.inconclusive) reasons.push("run was inconclusive (coverage floor not met)");
-} else {
-  if (regression?.gate.failed) {
-    reasons.push(`${regression.gate.newCritical} new critical + ${regression.gate.newHigh} new high vs. baseline`);
-  }
-  // A regression gate must also catch regressions in EXPLORABILITY, not just in findings:
-  // a change that makes the app crash at launch (or reintroduces a login wall) produces an
-  // inconclusive run with zero new findings — that must never pass. (Found via corpus
-  // bug-seeding: a seeded crash-at-startup sailed through on the findings diff alone.)
-  if (report.verdict === "blocked") reasons.push("verdict is blocked");
-  if (report.inconclusive && !baseline.inconclusive) {
-    reasons.push("run became inconclusive vs. baseline (app may no longer launch/explore)");
-  }
-}
-const gate = { policy: args.failOn, failed: reasons.length > 0, reasons };
+// The gate decision now lives in a pure, unit-tested evaluator (report.js). A regression gate
+// must catch regressions in EXPLORABILITY, not just findings: a change that makes the app crash at
+// launch (or reintroduces a login wall) produces an inconclusive run with zero new findings — that
+// must never pass (found via corpus bug-seeding). evaluateGate encodes that as an `inconclusive`
+// outcome (exit 3), distinct from a deterministic `fail` (exit 1).
+const decision = evaluateGate({ report, regression, flows, scenarios, contracts, prPlan, baseline, failOn: args.failOn });
+const gate = {
+  ...decision,
+  target: args.targetKey || report.target || null,
+  revision: gitRevision(args.projectDir),
+  checked: report.checkedFor,
+  notChecked: report.notChecked,
+};
 
 const md = renderMarkdown(report, regression, flows, scenarios, contracts, prPlan, gate);
 console.log(md);
@@ -563,4 +582,7 @@ if (args.htmlDir) {
   const html = writeHtmlReport(args.htmlDir, { report, label: args.label || "CI run" });
   if (html) console.log(`\nEvidence report: ${html}`);
 }
-process.exit(gate.failed ? 1 : 0);
+// Outcome → exit code (ADR-0005): pass 0 · fail 1 · error 2 · inconclusive 3. fail and inconclusive
+// both block a merge; distinct codes let CI tell "a regression was observed" from "we couldn't be
+// sure" and keep infra/usage errors (2) separate.
+process.exit(gate.exitCode);