@aarwitz/tapp 0.17.0-rc.8 → 0.17.0

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

@@ -410,7 +410,7 @@ export function adoptPrCoverageProposal({ projectDir, prPlanPath, item, releaseP
   if (!prPlanPath || !fs.existsSync(source)) throw new Error(`PR plan not found: ${source || "(missing path)"}`);
   const targetPath = releasePlanPath === ".tapp/release-plan.json" ? existingProjectArtifactPath(root, "release-plan.json") : path.resolve(root, releasePlanPath);
   if (!inside(root, targetPath)) throw new Error("Release plan path must stay inside the project directory");
-  if (!fs.existsSync(targetPath)) throw new Error(`Release plan not found: ${targetPath}; run tapp init first`);
+  if (!fs.existsSync(targetPath)) throw new Error(`Release plan not found: ${targetPath}; run npx -y @aarwitz/tapp@latest init first`);
   const prPlan = JSON.parse(fs.readFileSync(source, "utf8"));
   if (prPlan?.schemaVersion !== 1 || !Array.isArray(prPlan.explorationTargets)) throw new Error("PR plan must be an executed Tapp PR plan v1");
   const matches = prPlan.explorationTargets.filter((target) => target.id === item);
@@ -428,7 +428,7 @@ 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");
-  const refreshAdvice = "refresh the persistent UI Map with `tapp init --explore --refresh`, rerun `tapp pr gate`, then retry `tapp pr adopt`";
+  const refreshAdvice = "refresh the persistent UI Map with `npx -y @aarwitz/tapp@latest init --explore --refresh`, rerun `npx -y @aarwitz/tapp@latest pr gate`, then retry `npx -y @aarwitz/tapp@latest 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}; ${refreshAdvice}`);

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

@@ -64,6 +64,90 @@ function artifactPaths(root, outDir = ".tapp") {
   };
 }
 
+function normalizedInitTarget(root, target) {
+  const requested = String(target || "").trim();
+  if (!requested) return "";
+  let absolute;
+  try { absolute = fs.realpathSync(path.resolve(root, requested)); }
+  catch { absolute = path.resolve(root, requested); }
+  if (absolute === root) return "";
+  if (inside(root, absolute)) return path.relative(root, absolute).replaceAll(path.sep, "/");
+  return requested;
+}
+
+function initTargetChoices(model, platform = "") {
+  const candidates = (model.targets || []).filter((target) => !platform || target.platform === platform);
+  return candidates.map((target) => ({
+    target,
+    command: `npx -y @aarwitz/tapp@latest init . --explore --platform ${target.platform} --target ${target.sourcePath === "." ? JSON.stringify(target.name) : JSON.stringify(target.sourcePath)}`,
+  }));
+}
+
+function selectInitExplorationTarget(model, {
+  root,
+  platform = "",
+  target = "",
+  appId = "",
+} = {}) {
+  const selectedPlatform = String(platform || "").trim().toLowerCase();
+  if (selectedPlatform && !["ios", "android", "web"].includes(selectedPlatform)) throw new Error("platform must be ios|android|web");
+  let requested = normalizedInitTarget(root, target);
+  if (!requested && appId) {
+    const androidMatch = (model.targets || []).find((candidate) => candidate.platform === "android" && candidate.runtime?.applicationId === appId);
+    if (androidMatch) requested = androidMatch.id;
+  }
+  try {
+    return selectApplicationTarget(model, {
+      platform: selectedPlatform,
+      target: requested,
+      // `init --explore` is the explicit onboarding/refresh operation: it asks whenever several
+      // targets are plausible. Only a later bare `tapp explore` consumes the recorded default.
+      useDefault: false,
+    });
+  } catch (error) {
+    const choices = initTargetChoices(model, selectedPlatform);
+    if (choices.length > 1 && !requested) {
+      const selection = new Error(
+        `Multiple application targets were detected; Tapp will not guess which one you mean:\n` +
+        choices.map(({ target: choice }) => `  - ${choice.platform}:${choice.name} (${choice.sourcePath})`).join("\n") +
+        `\nRerun with one of:\n` + choices.map(({ command }) => `  ${command}`).join("\n")
+      );
+      selection.code = "TAPP_TARGET_SELECTION_REQUIRED";
+      selection.details = {
+        reason: "target-selection-required",
+        choices: choices.map(({ target: choice, command }) => ({
+          id: choice.id,
+          platform: choice.platform,
+          name: choice.name,
+          sourcePath: choice.sourcePath,
+          selector: choice.sourcePath === "." ? choice.name : choice.sourcePath,
+          command,
+        })),
+      };
+      throw selection;
+    }
+    throw error;
+  }
+}
+
+export function scopeProductRequirements(model, { selectedTargetId = "" } = {}) {
+  const targets = Array.isArray(model?.targets) ? model.targets : [];
+  const requirements = Array.isArray(model?.requirements) ? model.requirements : [];
+  const selected = String(selectedTargetId || "").trim();
+  const enriched = requirements.map((requirement) => {
+    const target = targets.find((candidate) => requirement.targetId === candidate.id || String(requirement.id || "").startsWith(`${candidate.id}:`));
+    return target
+      ? { ...requirement, targetId: target.id, targetPlatform: target.platform, targetName: target.name }
+      : { ...requirement };
+  });
+  if (!selected) return { selectedTargetId: "", active: enriched, deferred: [] };
+  return {
+    selectedTargetId: selected,
+    active: enriched.filter((requirement) => !requirement.targetId || requirement.targetId === selected),
+    deferred: enriched.filter((requirement) => requirement.targetId && requirement.targetId !== selected),
+  };
+}
+
 function productRunRoot(root) {
   const home = process.env.TAPP_HOME || path.join(os.homedir(), ".tapp");
   const identity = crypto.createHash("sha256").update(root).digest("hex").slice(0, 16);
@@ -279,6 +363,7 @@ export async function initializeProductProject({
   maxContracts = 15,
   testEmail,
   testPassword,
+  watch = false,
   runExploration,
   onProgress = () => {},
   onStatus = () => {},
@@ -287,22 +372,41 @@ export async function initializeProductProject({
   if (!["inspect", "write", "refresh", "explore"].includes(mode)) throw new Error("mode must be inspect|write|refresh|explore");
   if (!Number.isInteger(Number(maxContracts)) || Number(maxContracts) < 1 || Number(maxContracts) > 50) throw new Error("maxContracts must be between 1 and 50");
   const paths = artifactPaths(root, outDir);
+  const priorModel = readJson(paths.model);
   let exploration = null;
+  let selectedTarget = null;
   if (mode === "explore") {
     if (typeof runExploration !== "function") throw new Error("The selected adapter did not provide a platform exploration capability");
-    const selectedPlatform = String(platform || (ownedUrl ? "web" : appId || apkPath ? "android" : "ios")).toLowerCase();
+    const selectedPlatform = String(platform || (ownedUrl ? "web" : appId || apkPath ? "android" : "")).toLowerCase();
+    const inspected = await buildInitArtifacts({
+      projectDir: root,
+      ownedUrl,
+      outDir,
+      maxContracts: Number(maxContracts),
+      defaultTargetId: priorModel?.application?.defaultTargetId || "",
+    });
+    selectedTarget = selectInitExplorationTarget(inspected.model, {
+      root,
+      platform: selectedPlatform,
+      target,
+      appId,
+    });
+    const sourceTarget = selectedTarget.sourcePath === "." ? root : path.resolve(root, selectedTarget.sourcePath);
     exploration = await runExploration({
-      projectDir: root, platform: selectedPlatform, outDir, url: ownedUrl, target: target || root,
-      bundleId, appId, apkPath, serial, scheme, configuration, maxActions: Number(maxActions), timeout: Number(timeout),
-      testEmail, testPassword, onProgress, onStatus,
+      projectDir: root, platform: selectedTarget.platform, outDir, url: ownedUrl, target: sourceTarget,
+      bundleId, appId: appId || selectedTarget.runtime?.applicationId || "", apkPath, serial, scheme, configuration, maxActions: Number(maxActions), timeout: Number(timeout),
+      testEmail, testPassword, watch, onProgress: (progress) => onProgress({ ...progress, platform: selectedTarget.platform }), onStatus,
     });
     if (exploration?.error) throw Object.assign(new Error(exploration.error), { details: exploration.details || {} });
   }
   const built = await buildInitArtifacts({
     projectDir: root,
     ownedUrl: ownedUrl || (exploration?.platform === "web" && !exploration.managedRuntime ? exploration.target : ""),
-    platform: String(platform || "").toLowerCase(),
+    // Exploration chooses one runnable surface, but the repository model must retain every detected
+    // application target. Otherwise selecting web would silently erase the native app (and vice versa).
+    platform: mode === "explore" ? "" : String(platform || "").toLowerCase(),
     targetValidation: exploration?.targetValidation || null,
+    defaultTargetId: selectedTarget?.id || priorModel?.application?.defaultTargetId || "",
     outDir,
     maxContracts: Number(maxContracts),
   });
@@ -317,7 +421,8 @@ export async function initializeProductProject({
       invalidateValidation: mode === "explore",
     });
   }
-  return { operation: "initialize", mode, model: built.model, plan: written?.plan || built.plan, exploration, written, project: readProductProject({ projectDir: root, outDir }) };
+  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 }) };
 }
 
 function resolvePlan(root, outDir, planPath = "") {

package/mcp-server/src/report.js

@@ -146,6 +146,7 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
   const screenElementCounts = {}; // screen -> max elements observed (content-collapse detection)
   let anySecure = false;
   let loginAttempted = false;
+  let credentialsProvided = base.complete?.credentialsProvided === true;
   let actions = 0;
 
   for (const line of raw.split(/\r?\n/)) {
@@ -158,7 +159,8 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
         // `target` gives a finding its identity beyond type|screen — two dead buttons on the
         // same screen are two findings, and fixing one while breaking another is a regression.
         const target = (typeof o.control === "string" && o.control) || (typeof o.target === "string" && o.target) || null;
-        rawIssues.push({ type: o.type, severity: sev, title: o.title, screen: o.screen || null, target, step: o.step ?? null });
+        const url = typeof o.url === "string" && o.url.trim() ? o.url.trim() : null;
+        rawIssues.push({ type: o.type, severity: sev, title: o.title, screen: o.screen || null, target, url, step: o.step ?? null });
       } catch {
         /* ignore malformed */
       }
@@ -175,6 +177,8 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
       t === "OCQA_STATE:login_preamble_two_step_submitted"
     ) {
       loginAttempted = true;
+    } else if (t === "OCQA_STATE:credentials_supplied") {
+      credentialsProvided = true;
     } else if (t.startsWith("OCQA_STATE:{")) {
       try {
         const s = JSON.parse(t.slice("OCQA_STATE:".length));
@@ -273,9 +277,9 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
   const coverageFloorMet = platform === "web"
     ? screensExplored >= 1 && actionsPerformed >= 1
     : screensExplored >= 2 && actionsPerformed >= 3;
-  const credentiallessLoginWall = anySecure && !loginAttempted && screensExplored <= 1;
-  const inconclusive = !coverageFloorMet || credentiallessLoginWall || timeBudgetExhausted;
-  const stopReason = credentiallessLoginWall ? "login-wall-no-credentials"
+  const unexercisedLoginWall = anySecure && !loginAttempted && screensExplored <= 1;
+  const inconclusive = !coverageFloorMet || unexercisedLoginWall || timeBudgetExhausted;
+  const stopReason = unexercisedLoginWall ? (credentialsProvided ? "login-wall-credentials-unused" : "login-wall-no-credentials")
     : timeBudgetExhausted ? "time-budget-exhausted"
     : coverageFloorMet ? "completed" : "coverage-floor-not-met";
 
@@ -338,7 +342,9 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
   // "Failed sign-ins" is only a claim when credentials were actually submitted. Merely seeing a
   // password field proves that a login surface was reached, not that authentication was exercised.
   if (loginAttempted) checkedFor.splice(2, 0, "failed sign-ins");
+  else if (anySecure && credentialsProvided) notChecked.push("sign-in behavior (test credentials were supplied, but no sign-in attempt was observed)");
   else if (anySecure) notChecked.push("sign-in behavior (login form reached, no test credentials supplied)");
+  else if (credentialsProvided) conditionsNotReached.push("sign-in (test credentials were supplied but no login form was encountered, so they were not used)");
   else conditionsNotReached.push("sign-in (no login form encountered this run)");
   if (timeBudgetExhausted) notChecked.push("the full requested action budget (run reached its wall-clock timeout)");
 
@@ -385,6 +391,13 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
     screenElementCounts,
     inputFieldsEncountered,
     loginEncountered: anySecure,
+    credentialsProvided,
+    credentialsUsed: loginAttempted,
+    credentialWarning: credentialsProvided && !loginAttempted
+      ? anySecure
+        ? "Test credentials were supplied, but this run did not submit the login form. Authentication was not exercised."
+        : "Test credentials were supplied, but this run did not encounter a login form. They were not used."
+      : null,
     complete: base.complete,
     relativeMarkersFilePath: base.relativeMarkersFilePath,
   };

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

@@ -23,6 +23,7 @@ import { execFileSync } from "child_process";
 const CLICK_SETTLE_MS = 700;
 const NAV_TIMEOUT_MS = 15_000;
 const BUTTONS_PER_PAGE = 4;
+const WATCH_ACTION_DELAY_MS = 350;
 const ERROR_TEXT_RE = /\b(something went wrong|internal server error|an error occurred|failed to load|unhandled exception)\b/i;
 const STANDALONE_ERROR_TEXT_RE = /^(something went wrong|internal server error|an error occurred|failed to load|unhandled exception)(?:[.!:]|\s|$)/i;
 
@@ -249,13 +250,14 @@ export async function loadPlaywright() {
   );
 }
 
-export async function submitWebLogin(page) {
+export async function submitWebLogin(page, beforeClick = null) {
   const candidates = [
     page.locator("button[type=submit], input[type=submit], form button").first(),
     page.getByRole("button", { name: /sign ?in|log ?in|continue/i }).first(),
   ];
   for (const candidate of candidates) {
     if (await candidate.isVisible().catch(() => false)) {
+      if (beforeClick) await beforeClick(candidate);
       await candidate.click({ timeout: 3000 });
       return true;
     }
@@ -279,13 +281,14 @@ export function webTransitionOrigin(pendingNavigation, currentScreen) {
   return pendingNavigation?.fromScreen || currentScreen || null;
 }
 
-export function webBrowserLaunchOptions(environment = process.env) {
+export function webBrowserLaunchOptions(environment = process.env, { watch = false } = {}) {
   const browserProxy = String(environment.TAPP_BROWSER_PROXY_SERVER || "").trim();
   if (environment.TAPP_ENFORCE_PUBLIC_EGRESS === "1" && !/^http:\/\/127\.0\.0\.1:\d+$/.test(browserProxy)) {
     throw new Error("public egress policy proxy is required");
   }
   return {
-    headless: true,
+    headless: !watch,
+    ...(watch ? { slowMo: 200 } : {}),
     ...(browserProxy ? { proxy: { server: browserProxy, bypass: "<-loopback>" } } : {}),
     args: browserProxy ? [
       "--disable-quic",
@@ -296,6 +299,102 @@ export function webBrowserLaunchOptions(environment = process.env) {
   };
 }
 
+// A headed Playwright browser does not move the host OS pointer when locator.click() runs. In
+// explicit watch mode, draw a pointer inside the controlled page so a human can follow Tapp's
+// real actions. The UI lives in a closed shadow root, ignores pointer events, and is hidden from
+// evidence screenshots; it therefore cannot become an app control or alter detector input.
+async function installWebWatchUi(context) {
+  await context.addInitScript(() => {
+    const stateKey = Symbol.for("tapp.watchUi");
+    const ensure = () => {
+      if (window[stateKey]?.host?.isConnected) return window[stateKey];
+      const host = document.createElement("div");
+      host.setAttribute("data-tapp-watch-ui", "");
+      host.setAttribute("aria-hidden", "true");
+      Object.assign(host.style, {
+        position: "fixed",
+        inset: "0",
+        zIndex: "2147483647",
+        pointerEvents: "none",
+      });
+      const shadow = host.attachShadow({ mode: "closed" });
+      const style = document.createElement("style");
+      style.textContent = `
+        .cursor { position: fixed; left: 24px; top: 72px; width: 22px; height: 28px;
+          filter: drop-shadow(0 2px 2px rgba(0,0,0,.45)); transition: left 260ms ease, top 260ms ease;
+          transform: rotate(-8deg); }
+        .cursor::before { content: ""; display: block; width: 100%; height: 100%; background: #111827;
+          clip-path: polygon(0 0, 0 88%, 25% 67%, 39% 100%, 53% 93%, 39% 61%, 70% 61%); }
+        .cursor::after { content: ""; position: absolute; inset: 2px 3px 4px 2px; background: white;
+          clip-path: polygon(0 0, 0 79%, 25% 59%, 40% 91%, 46% 88%, 32% 55%, 60% 55%); }
+        .hud { position: fixed; top: 14px; right: 14px; max-width: min(420px, calc(100vw - 28px));
+          box-sizing: border-box; padding: 9px 12px; border-radius: 10px; color: white;
+          background: rgba(17,24,39,.92); box-shadow: 0 5px 18px rgba(0,0,0,.24);
+          font: 600 13px/1.35 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+        .brand { color: #93c5fd; margin-right: 6px; }
+      `;
+      const cursor = document.createElement("div");
+      cursor.className = "cursor";
+      const hud = document.createElement("div");
+      hud.className = "hud";
+      shadow.append(style, cursor, hud);
+      (document.documentElement || document).appendChild(host);
+      const state = { host, cursor, hud };
+      Object.defineProperty(window, stateKey, { value: state, configurable: true });
+      return state;
+    };
+    Object.defineProperty(window, "__tappShowWatchAction", {
+      configurable: true,
+      value: ({ x, y, action, target }) => {
+        const state = ensure();
+        state.host.style.display = "block";
+        if (Number.isFinite(x) && Number.isFinite(y)) {
+          state.cursor.style.left = `${Math.max(4, Math.min(window.innerWidth - 26, x))}px`;
+          state.cursor.style.top = `${Math.max(4, Math.min(window.innerHeight - 32, y))}px`;
+        }
+        state.hud.replaceChildren();
+        const brand = document.createElement("span");
+        brand.className = "brand";
+        brand.textContent = "Tapp";
+        state.hud.append(brand, document.createTextNode(`${action}${target ? ` · ${target}` : ""}`));
+      },
+    });
+    Object.defineProperty(window, "__tappSetWatchUiVisible", {
+      configurable: true,
+      value: (visible) => {
+        if (window[stateKey]?.host) window[stateKey].host.style.display = visible ? "block" : "none";
+      },
+    });
+  });
+}
+
+async function showWebWatchAction(page, { locator = null, action = "Exploring", target = "" } = {}) {
+  let x = 28;
+  let y = 76;
+  if (locator) {
+    await locator.scrollIntoViewIfNeeded().catch(() => {});
+    const box = await locator.boundingBox().catch(() => null);
+    if (box) {
+      x = box.x + box.width / 2;
+      y = box.y + box.height / 2;
+    }
+  }
+  await page.evaluate(({ x, y, action, target }) => {
+    window.__tappShowWatchAction?.({ x, y, action, target });
+  }, { x, y, action, target }).catch(() => {});
+  await page.waitForTimeout(WATCH_ACTION_DELAY_MS).catch(() => {});
+}
+
+async function screenshotWithoutWebWatchUi(page, options, watch) {
+  if (!watch) return page.screenshot(options);
+  await page.evaluate(() => window.__tappSetWatchUiVisible?.(false)).catch(() => {});
+  try {
+    return await page.screenshot(options);
+  } finally {
+    await page.evaluate(() => window.__tappSetWatchUiVisible?.(true)).catch(() => {});
+  }
+}
+
 // Focused one-screen inspection for the agent-facing `tapp open <url>` and `tapp tree <url>`
 // commands. This deliberately does no exploration or judgment; it opens exactly one page,
 // captures the visible semantic controls, and optionally takes one screenshot.
@@ -425,7 +524,7 @@ export function normalizeWebSeedTargets(seedTargets = [], limit = 5) {
   return result;
 }
 
-export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDir, testEmail = "", testPassword = "", seedRoutes = [], seedTargets = [], onProgress }) {
+export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDir, testEmail = "", testPassword = "", seedRoutes = [], seedTargets = [], watch = false, onProgress }) {
   const start = new URL(url);
   if (!/^https?:$/.test(start.protocol)) throw new Error("url must be http(s)");
   fs.mkdirSync(outDir, { recursive: true });
@@ -434,9 +533,10 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
   const emit = (kind, payload) => fs.writeSync(markersFd, `OCQA_${kind}:${JSON.stringify(payload)}\n`);
 
   const { chromium } = await loadPlaywright();
-  const browser = await chromium.launch(webBrowserLaunchOptions());
+  const browser = await chromium.launch(webBrowserLaunchOptions(process.env, { watch }));
   const context = await browser.newContext({ viewport: { width: 1280, height: 900 } });
   await installWebListenerTracking(context);
+  if (watch) await installWebWatchUi(context);
   const page = await context.newPage();
   page.setDefaultTimeout(NAV_TIMEOUT_MS);
 
@@ -444,7 +544,8 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
   const issues = []; // emitted immediately; kept for counting only
   const issue = (type, severity, title, screen, target) => {
     issues.push(type);
-    emit("ISSUE", { type, severity, title, screen, ...(target ? { target } : {}) });
+    const pageUrl = page.url();
+    emit("ISSUE", { type, severity, title, screen, ...(target ? { target } : {}), ...(pageUrl && pageUrl !== "about:blank" ? { url: pageUrl } : {}) });
   };
 
   // Async defect listeners: attribute to whatever screen is current when they fire.
@@ -604,7 +705,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
       if (existingKey && existingKey !== evidenceKey) screenshotFor.delete(existingKey);
       screenshotFor.set(evidenceKey, { path: screenshotPath, busy: info.busy, route: key });
       screenCount = screenshotFor.size;
-      await page.screenshot({ path: screenshotPath }).catch(() => {});
+      await screenshotWithoutWebWatchUi(page, { path: screenshotPath }, watch).catch(() => {});
       // Deterministic per-page detectors run once per distinct screen.
       if (webPageAppearsBlank(info)) issue("blank_screen", "high", "Page rendered no visible content", screen);
       else {
@@ -628,12 +729,19 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
     if (!(await pw.isVisible().catch(() => false))) return null;
     loginTried = true;
     const emailSel = "input[type=email], input[name*=mail i], input[name*=user i], input[id*=mail i], input[id*=user i]";
-    if (testEmail) await page.locator(emailSel).first().fill(testEmail).catch(() => {});
+    if (testEmail) {
+      const email = page.locator(emailSel).first();
+      if (watch) await showWebWatchAction(page, { locator: email, action: "Type", target: "Email" });
+      await email.fill(testEmail).catch(() => {});
+    }
+    if (watch) await showWebWatchAction(page, { locator: pw, action: "Type", target: "Password" });
     await pw.fill(testPassword).catch(() => {});
     lastActionTarget = "Sign in";
     emit("ACTION", { type: "login", target: "Sign in", screen, narrative: "Filled and submitted the sign-in form with the provided test credentials" });
     actions += 1;
-    await submitWebLogin(page).catch(() => false);
+    await submitWebLogin(page, watch
+      ? (locator) => showWebWatchAction(page, { locator, action: "Click", target: "Sign in" })
+      : null).catch(() => false);
     await waitForWebStability(page, { timeoutMs: Math.min(5_000, CLICK_SETTLE_MS * 6) });
     // Still on the login form after a submit = the sign-in failed — full stop. (A quiet
     // credential rejection often shows NO other symptom, so this must not be coupled to
@@ -688,6 +796,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
         progress();
         continue;
       }
+      if (watch) await showWebWatchAction(page, { action: "Open", target });
       await waitForWebStability(page);
       if (nav && typeof nav.status === "function" && nav.status() === 404) {
         issue("broken_link", "medium", `Broken link: ${target} → 404`, target);
@@ -708,6 +817,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
           emit("ACTION", { type: action.type, target: action.target, screen: beforeScreen, reason: "pr_ui_map_path", narrative: `Following observed UI Map path: ${action.type} ${action.target}` });
           let acted = false;
           if (action.type === "back") {
+            if (watch) await showWebWatchAction(page, { action: "Back", target: beforeScreen });
             await page.goBack({ waitUntil: "domcontentloaded", timeout: step.wait?.timeoutMs || NAV_TIMEOUT_MS }).catch(() => {});
             acted = true;
           } else {
@@ -721,6 +831,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
               else continue;
               if (await locator.isVisible().catch(() => false)) {
                 try {
+                  if (watch) await showWebWatchAction(page, { locator, action: "Click", target: action.target });
                   await locator.click({ timeout: Math.min(step.wait?.timeoutMs || NAV_TIMEOUT_MS, NAV_TIMEOUT_MS) });
                   acted = true;
                   break;
@@ -785,6 +896,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
         emit("ACTION", { type: "tap", target: label, screen: webActionScreen(ob), narrative: `Tapped "${label}"` });
         let clickSucceeded = false;
         try {
+          if (watch) await showWebWatchAction(page, { locator: b, action: "Click", target: label });
           await b.click({ timeout: 3000 });
           clickSucceeded = true;
         } catch {}
@@ -795,6 +907,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
         await waitForWebStability(page);
         if (page.url() !== beforeState.url) {
           await observe();
+          if (watch) await showWebWatchAction(page, { action: "Back", target: ob.screen });
           await page.goBack({ waitUntil: "domcontentloaded" }).catch(() => {});
           await waitForWebStability(page);
         } else {
@@ -813,7 +926,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
       progress();
     }
   } finally {
-    emit("COMPLETE", { actions, screens: screenCount });
+    emit("COMPLETE", { actions, screens: screenCount, credentialsProvided: !!(testEmail || testPassword), credentialsUsed: loginTried });
     fs.closeSync(markersFd);
     await browser.close().catch(() => {});
   }

package/mcp-server/src/web-flow.js

@@ -132,6 +132,22 @@ export async function executeWebFlowStep({ page, step, vars = {}, defaultTimeout
       const el = await locateWebElement(page, target);
       if (!el) throw new Error(`no field ‘${target}’ to type into`);
       await el.fill(value);
+    } else if (action === "login") {
+      const emailValue = substituteFlowValue(raw.params.email || "$TEST_EMAIL", vars);
+      const passwordValue = substituteFlowValue(raw.params.password || "$TEST_PASSWORD", vars);
+      const email = await firstVisible([
+        page.locator("input[type=email]"), page.locator("input[name*=mail i]"),
+        page.locator("input[name*=user i]"), page.getByLabel(/email|user/i),
+      ]);
+      const password = await firstVisible([page.locator("input[type=password]"), page.getByLabel(/password|passcode/i)]);
+      if (!email || !password) throw new Error("could not identify email and password fields");
+      await email.fill(emailValue);
+      await password.fill(passwordValue);
+      const submit = await firstVisible([page.getByRole("button", { name:/sign in|log in|login|continue|submit/i })]);
+      if (!submit) throw new Error("could not identify a sign-in control");
+      await submit.click();
+      await page.waitForTimeout(400);
+      if (await password.isVisible().catch(() => false)) throw new Error("submit left the app on the login screen");
     } else if (action === "swipe") {
       const dy = target.toLowerCase() === "down" ? -600 : 600;
       await page.evaluate((y) => window.scrollBy({ top: y, behavior: "instant" }), dy);
@@ -173,7 +189,7 @@ export async function executeWebFlowStep({ page, step, vars = {}, defaultTimeout
     status = "fail";
     detail = error.message || String(error);
   }
-  return { action, target: target || value, status, detail, task: raw.task };
+  return { action, target: action === "login" ? "sign-in form" : target || value, status, detail, task: raw.task };
 }
 
 export async function runWebFlow({ flow, url, logPath, screenshotDir, playwright }) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.0-rc.8",
+  "version": "0.17.0",
   "mcpName": "io.github.aarwitz/tapp",
-  "description": "Release contracts, autonomous QA, and evidence-backed CI gates for iOS, Android, and web.",
+  "description": "Agent-driven app testing for iOS, Android, and web—real screens, replayable flows, and deterministic CI gates.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -41,6 +41,8 @@
     "Harness/OCQAHarnessUITests/",
     "Harness/OCQAHarness.xcodeproj/",
     "Harness/generate-harness-xcodeproj.rb",
+    "skills/",
+    ".claude-plugin/",
     "AGENTS.md"
   ],
   "dependencies": {
@@ -57,7 +59,7 @@
     "type": "git",
     "url": "git+https://github.com/aarwitz/tapp.git"
   },
-  "homepage": "https://github.com/aarwitz/tapp#readme",
+  "homepage": "https://runtapp.com/",
   "bugs": {
     "url": "https://github.com/aarwitz/tapp/issues"
   },
@@ -87,7 +89,7 @@
     "mobile"
   ],
   "scripts": {
-    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/android-primitives-protocol.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/action.test.js tests/package-surface.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js",
+    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/android-primitives-protocol.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/mcp-workspace.test.js tests/action.test.js tests/package-surface.test.js tests/agent-surface.test.js tests/presentation-contract.test.js tests/landing-brand.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js vscode-extension/test/bridge.test.js",
     "test:browser-journey": "node --test tests/browser-journey.test.js",
     "test:browser-native": "TAPP_RUN_NATIVE_BROWSER=1 node --test tests/browser-native-journey.test.js"
   }

package/scripts/ci-gate.sh

@@ -86,6 +86,48 @@ TAPP_PROJECT_ARTIFACTS=""
 if [[ -n "$PROJECT_DIR" ]]; then
   [[ -d "$PROJECT_DIR/.tapp" ]] && TAPP_PROJECT_ARTIFACTS="$PROJECT_DIR/.tapp"
 fi
+
+# A repository-connected gate must retain the stable application-model target identity in its
+# report. Otherwise its first passing report cannot become a target-scoped baseline, even though
+# Tapp already knows exactly which application it built and exercised. Explicit --target-key still
+# wins (the composite Action supplies one); the CLI derives it only when the repository model makes
+# the selection conclusive. Multi-target repositories remain strict and print the available ids.
+if [[ -z "$TARGET_KEY" && -n "$TAPP_PROJECT_ARTIFACTS" && -f "$TAPP_PROJECT_ARTIFACTS/application-model.json" ]]; then
+  if ! TARGET_KEY="$(node - "$TAPP_PROJECT_ARTIFACTS/application-model.json" "$PLATFORM" "$WEB_TARGET" "$APP_ID" "$BUNDLE_ID" <<'NODE'
+const fs = require("fs");
+const [modelPath, platform, webTarget, appId, bundleId] = process.argv.slice(2);
+let model;
+try { model = JSON.parse(fs.readFileSync(modelPath, "utf8")); }
+catch (error) { console.error(`❌ Could not read application model ${modelPath}: ${error.message}`); process.exit(2); }
+if (model?.kind !== "tapp-application-model" || !Array.isArray(model.targets)) {
+  console.error("❌ Expected .tapp/application-model.json to contain a Tapp application model");
+  process.exit(2);
+}
+let candidates = model.targets.filter((target) => target.platform === platform);
+const requested = platform === "web" ? webTarget : platform === "android" ? appId : bundleId;
+if (requested) {
+  const normalized = requested.replaceAll("\\", "/").replace(/^\.\//, "");
+  candidates = candidates.filter((target) => {
+    const identities = [target.id, target.name, target.sourcePath];
+    if (platform === "android") identities.push(target.runtime?.applicationId);
+    if (platform === "ios") identities.push(target.runtime?.bundleId);
+    return identities.some((value) => String(value || "").replaceAll("\\", "/") === normalized);
+  });
+}
+if (candidates.length !== 1) {
+  const available = model.targets.filter((target) => target.platform === platform);
+  console.error(candidates.length
+    ? `❌ Multiple ${platform} targets match. Pass --target-key explicitly: ${candidates.map((target) => target.id).join(", ")}`
+    : `❌ Could not resolve one ${platform} target from the application model.${available.length ? ` Available target ids: ${available.map((target) => target.id).join(", ")}` : ""}`);
+  process.exit(2);
+}
+process.stdout.write(String(candidates[0].id));
+NODE
+  )"; then
+    exit 2
+  fi
+  echo "Target identity: $PLATFORM:$TARGET_KEY (from .tapp/application-model.json)"
+fi
 [[ -z "$FLOWS" && -n "$TAPP_PROJECT_ARTIFACTS" && -d "$TAPP_PROJECT_ARTIFACTS/flows" ]] && FLOWS="$TAPP_PROJECT_ARTIFACTS/flows/*.yml"
 [[ "$PLATFORM" == "web" && -z "$SCENARIOS" && -n "$TAPP_PROJECT_ARTIFACTS" && -d "$TAPP_PROJECT_ARTIFACTS/scenarios" ]] && SCENARIOS="$TAPP_PROJECT_ARTIFACTS/scenarios/*.yml"
 [[ -z "$CONTRACTS" && -n "$TAPP_PROJECT_ARTIFACTS" && -d "$TAPP_PROJECT_ARTIFACTS/contracts" ]] && CONTRACTS="$TAPP_PROJECT_ARTIFACTS/contracts/*.contract.ts"

package/scripts/flow_lib.py

@@ -102,7 +102,7 @@ def report(path, as_json=False):
         return 0 if passed else 1
 
     icon = {"pass": "✅", "fail": "❌", "skip": "⚪️"}
-    verb = {"tap": "👆 tap", "type": "⌨️  type", "swipe": "↔️  swipe", "back": "◀️  back",
+    verb = {"tap": "👆 tap", "type": "⌨️  type", "login": "🔐 sign in", "swipe": "↔️  swipe", "back": "◀️  back",
             "wait": "⏳ wait", "wait_for": "⏳ wait for", "assert_screen": "🔎 screen is",
             "assert_exists": "🔎 exists", "assert_absent": "🔎 absent", "assert_text": "🔎 text",
             "assert_ai": "🤖 ai"}

package/scripts/quick-capture.sh

@@ -23,9 +23,9 @@ TAPP_RUNTIME_HOME="${TAPP_HOME:-}"
 if [[ -n "${TAPP_CAPTURE_DIR:-}" ]]; then
   CAPTURE_DIR="$TAPP_CAPTURE_DIR"
 elif [[ -n "$TAPP_RUNTIME_HOME" ]]; then
-  CAPTURE_DIR="$TAPP_RUNTIME_HOME/captures/$(date +%Y%m%d-%H%M%S)"
+  CAPTURE_DIR="$TAPP_RUNTIME_HOME/captures/ios-$(date +%Y%m%d-%H%M%S)"
 else
-  CAPTURE_DIR="$PROJECT_ROOT/captures/$(date +%Y%m%d-%H%M%S)"
+  CAPTURE_DIR="$PROJECT_ROOT/captures/ios-$(date +%Y%m%d-%H%M%S)"
 fi
 if [[ -n "$TAPP_RUNTIME_HOME" ]]; then
   HARNESS_DERIVED="$TAPP_RUNTIME_HOME/harness-derived"