@aarwitz/tapp 0.17.0-rc.8 → 0.17.0

package/mcp-server/src/index.js

@@ -9,6 +9,8 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 
@@ -17,7 +19,15 @@ import { existingProjectArtifactPath, projectArtifactDirectory } from "./project
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+// `repoRoot` is the installed Tapp package root: scripts and bundled harness assets live here.
+// Repository-facing MCP operations must use `workspaceRoot` instead. In an npm/Claude-plugin
+// installation those are different directories, even though source-repo tests historically made
+// them look identical.
 const repoRoot = path.resolve(__dirname, "../..");
+const workspaceRoot = (() => {
+  try { return fs.realpathSync(process.cwd()); }
+  catch { return path.resolve(process.cwd()); }
+})();
 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.
@@ -35,8 +45,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) {
@@ -320,6 +335,9 @@ export function findXcodeContainer(startDir) {
 }
 
 export async function buildAppForSim({ dir, container, scheme, configuration = "Debug" } = {}) {
+  const { storagePreflight } = await import("./environment-preflight.js");
+  const storage = storagePreflight(path.join(tappHome || os.tmpdir(), "app-builds"));
+  if (!storage.ok) return { error: storage.message, details: { environment: "storage", storage } };
   const target = container || findXcodeContainer(dir || process.cwd());
   if (!target) return { error: `No Xcode project or workspace found under ${dir || process.cwd()}` };
   const isWorkspace = target.endsWith(".xcworkspace");
@@ -700,6 +718,28 @@ function templateValue(text) {
   return text;
 }
 
+export function isStableFlowCheckpoint(value) {
+  const text = String(value || "").replace(/\s+/g, " ").trim();
+  if (!text || /^(loading|fetching|please wait|preparing|connecting|syncing|signing in)(?:[.…!]*|\s.*)$/i.test(text)) return false;
+  if (/^(?:mon|tues?|wed(?:nes)?|thu(?:rs)?|fri|sat(?:ur)?|sun)(?:day)?\b/i.test(text)) return false;
+  if (/^(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|jul(?:y)?|aug(?:ust)?|sep(?:tember)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)\s+\d{1,2}(?:,\s+\d{4})?$/i.test(text)) return false;
+  if (/^\d{4}-\d{2}-\d{2}(?:[ T].*)?$/.test(text)) return false;
+  return true;
+}
+
+export function semanticTargetAtPoint(elements, x, y) {
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return "";
+  return (elements || [])
+    .filter((element) => {
+      const frame = element.frame || {};
+      return element.hittable !== false && Number.isFinite(frame.x) && Number.isFinite(frame.y) && Number.isFinite(frame.width) && Number.isFinite(frame.height)
+        && x >= frame.x && y >= frame.y && x <= frame.x + frame.width && y <= frame.y + frame.height
+        && String(element.id || element.identifier || element.label || "").trim();
+    })
+    .sort((a, b) => (a.frame.width * a.frame.height) - (b.frame.width * b.frame.height))
+    .map((element) => String(element.id || element.identifier || element.label || "").trim())[0] || "";
+}
+
 /** Append a Flow step for an act (record-by-doing). Inserts wait_for on screen change for
  *  deterministic replay. Inspection acts (tree/screenshot/wait) are not recorded. */
 function recordStep(cmd, result) {
@@ -710,7 +750,7 @@ function recordStep(cmd, result) {
     case "tap": {
       const target = cmd.id || cmd.label || (typeof cmd.x === "number" ? `${cmd.x},${cmd.y}` : "");
       if (target) activeSession.recording.push({ tap: target });
-      if (changed) activeSession.recording.push({ wait_for: newScreen });
+      if (changed && isStableFlowCheckpoint(newScreen)) activeSession.recording.push({ wait_for: newScreen });
       break;
     }
     case "type": {
@@ -719,12 +759,16 @@ function recordStep(cmd, result) {
       activeSession.recording.push({ type: step });
       break;
     }
+    case "login":
+      activeSession.recording.push({ login: { email: "$TEST_EMAIL", password: "$TEST_PASSWORD" } });
+      if (changed && isStableFlowCheckpoint(newScreen)) activeSession.recording.push({ wait_for: newScreen });
+      break;
     case "swipe":
       activeSession.recording.push({ swipe: cmd.direction || "up" });
       break;
     case "back":
       activeSession.recording.push({ back: true });
-      if (changed) activeSession.recording.push({ wait_for: newScreen });
+      if (changed && isStableFlowCheckpoint(newScreen)) activeSession.recording.push({ wait_for: newScreen });
       break;
     default:
       break; // tree / screenshot / wait are inspection, not test steps
@@ -733,7 +777,17 @@ function recordStep(cmd, result) {
 }
 
 async function sessionAct(cmd) {
-  if (!activeSession || activeSession.ended) return { error: "No active session. Call tapp_session_start first." };
+  const startedAt = Date.now();
+  const done = (result) => ({ ...result, durationMs: Date.now() - startedAt });
+  if (!activeSession || activeSession.ended) return done({ error: "No active session. Call tapp_session_start first." });
+  let coordinateResolvedTarget = "";
+  if (cmd.action === "tap" && !cmd.id && Number.isFinite(cmd.x) && Number.isFinite(cmd.y)) {
+    coordinateResolvedTarget = semanticTargetAtPoint(activeSession.latestTree?.elements, cmd.x, cmd.y);
+    if (coordinateResolvedTarget) {
+      const { x: _x, y: _y, ...semanticCommand } = cmd;
+      cmd = { ...semanticCommand, id: coordinateResolvedTarget };
+    }
+  }
   if (activeSession.platform === "web") {
     const session = activeSession;
     let status = "ok";
@@ -741,9 +795,13 @@ async function sessionAct(cmd) {
     let typedInto = null;
     try {
       if (cmd.action === "tap") {
-        const locator = await firstVisibleWebLocator(session.page, cmd.id || cmd.label || "");
-        if (!locator) { status = "not_found"; detail = "No visible web control matched the semantic target"; }
-        else await locator.click({ timeout:10_000 });
+        const target = cmd.id || cmd.label || "";
+        if (!target && Number.isFinite(cmd.x) && Number.isFinite(cmd.y)) await session.page.mouse.click(cmd.x, cmd.y);
+        else {
+          const locator = await firstVisibleWebLocator(session.page, target);
+          if (!locator) { status = "not_found"; detail = "No visible web control matched the semantic target"; }
+          else await locator.click({ timeout:10_000 });
+        }
       } else if (cmd.action === "type") {
         const locator = await firstVisibleWebLocator(session.page, cmd.id || cmd.label || "", { input:true });
         if (!locator) { status = "not_found"; detail = "No visible web field matched the semantic target"; }
@@ -756,6 +814,28 @@ async function sessionAct(cmd) {
           if (!locator) await session.page.waitForTimeout(120);
         }
         if (!locator) { status = "timeout"; detail = `Timed out waiting for ${cmd.id || cmd.text || "target"}`; }
+      } else if (cmd.action === "login") {
+        const emailValue = cmd.email || session.creds.email || "";
+        const passwordValue = cmd.password || session.creds.password || "";
+        if (!emailValue || !passwordValue) { status = "missing_credentials"; detail = "Email and password are required"; }
+        else {
+          const email = await firstVisibleWebLocator(session.page, "Email", { input:true })
+            || session.page.locator("input[type=email], input[name*=mail i], input[name*=user i], input[id*=mail i], input[id*=user i]").first();
+          const password = session.page.locator("input[type=password]").first();
+          if (!(await email.isVisible().catch(() => false)) || !(await password.isVisible().catch(() => false))) {
+            status = "not_found"; detail = "Could not identify email and password fields";
+          } else {
+            await email.fill(emailValue);
+            await password.fill(passwordValue);
+            const submit = session.page.getByRole("button", { name:/sign in|log in|login|continue|submit/i }).first();
+            if (!(await submit.isVisible().catch(() => false))) { status = "not_found"; detail = "Could not identify a sign-in control"; }
+            else {
+              await submit.click();
+              await session.page.waitForTimeout(500);
+              if (await password.isVisible().catch(() => false)) { status = "still_on_login"; detail = "Submit left the app on the login screen"; }
+            }
+          }
+        }
       } else if (cmd.action === "back") {
         await session.page.goBack({ waitUntil:"domcontentloaded", timeout:10_000 }).catch(() => {});
       } else if (cmd.action === "swipe") {
@@ -774,7 +854,7 @@ async function sessionAct(cmd) {
     }
     const snapshot = treeSnapshot();
     if (status === "ok") recordStep(cmd, snapshot);
-    return { status, typedInto, detail, ...snapshot, recordedSteps:session.recording.length, url:session.latestTree?.url || "" };
+    return done({ status, typedInto, detail, ...snapshot, recordedSteps:session.recording.length, url:session.latestTree?.url || "", ...(coordinateResolvedTarget ? { coordinateResolvedTarget } : {}) });
   }
   if (activeSession.platform === "android") {
     const s = activeSession;
@@ -830,7 +910,7 @@ async function sessionAct(cmd) {
     s.treeVersion += 1;
     const snap = treeSnapshot();
     if (status === "ok") recordStep(cmd, snap);
-    return { status, typedInto, detail, ...snap, recordedSteps: s.recording.length };
+    return done({ status, typedInto, detail, ...snap, recordedSteps: s.recording.length, ...(coordinateResolvedTarget ? { coordinateResolvedTarget } : {}) });
   }
   activeSession.seq += 1;
   const seq = activeSession.seq;
@@ -859,7 +939,7 @@ async function sessionAct(cmd) {
   while (activeSession.treeVersion === beforeVer && Date.now() < td && !activeSession.ended) await sleep(150);
   const snap = treeSnapshot();
   if (status === "ok") recordStep(cmd, snap); // record only successful acts
-  return { status, typedInto, detail, ...snap, recordedSteps: activeSession ? activeSession.recording.length : 0 };
+  return done({ status, typedInto, detail, ...snap, recordedSteps: activeSession ? activeSession.recording.length : 0, ...(coordinateResolvedTarget ? { coordinateResolvedTarget } : {}) });
 }
 
 async function endSession() {
@@ -904,7 +984,7 @@ export async function saveInteractiveSessionFlow({ projectDir, name, addFinalAss
   if (!projectDir || !fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error("A valid repository root is required to save a Flow");
   const steps = [...(activeSession.recording || [])];
   if (steps.length === 0) throw new Error("Nothing recorded yet — perform some live-session actions first.");
-  if (addFinalAssertion && activeSession.lastScreen) {
+  if (addFinalAssertion && activeSession.lastScreen && isStableFlowCheckpoint(activeSession.lastScreen)) {
     const last = steps[steps.length - 1] || {};
     if (!("assert_screen" in last)) steps.push({ assert_screen: activeSession.lastScreen });
   }
@@ -1229,6 +1309,7 @@ export function explorationEnvFromArgs(args) {
   const env = {};
   if (isNonEmptyString(args.testEmail)) env.OCQA_TEST_EMAIL = args.testEmail;
   if (isNonEmptyString(args.testPassword)) env.OCQA_TEST_PASSWORD = args.testPassword;
+  if (isNonEmptyString(args.testEmail) || isNonEmptyString(args.testPassword)) env.OCQA_CREDENTIALS_EXPLICIT = "1";
   if (Array.isArray(args.appLaunchArgs)) {
     const a = args.appLaunchArgs.filter((s) => typeof s === "string" && s.length > 0);
     if (a.length) env.OCQA_APP_LAUNCH_ARGS_JSON = JSON.stringify(a);
@@ -1320,9 +1401,9 @@ function fmtDuration(ms) {
 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 compare a fix (then `tapp ci` to gate it)");
-    next.push("replay a committed journey with `tapp flow run <file>`");
+    if (report?.findings?.length) next.push("inspect the evidence with `npx -y @aarwitz/tapp@latest report latest`");
+    next.push("save this run with `--json <report.json>`, then re-run with `--baseline <report.json>` to compare a fix (`tapp ci` gates it)");
+    next.push("replay a committed journey with `npx -y @aarwitz/tapp@latest flow run <file>`");
     return next;
   }
   const next = [];
@@ -1344,6 +1425,7 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
   L.push(`### 🔭 Exploration complete — ${badge} · ${observationSummary(report)}${bundleId ? `\n\`${bundleId}\`` : ""}`);
   L.push("");
   L.push(report.headline);
+  if (report.credentialWarning) L.push("", `> ⚠️ ${report.credentialWarning}`);
   L.push("");
   L.push(`**Coverage** — ${report.screensExplored} screens · ${report.actionsPerformed} actions${timedOut ? " · ⏱️ hit time limit" : ""}`);
   if (report.platform === "web") {
@@ -1358,7 +1440,7 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
     L.push("");
     L.push("**Findings**");
     for (const f of report.findings.slice(0, 12)) {
-      L.push(`- ${SEV[f.severity] || "•"} \`${f.severity}\` ${f.title}${f.screen ? ` — on *${f.screen}*` : ""}`);
+      L.push(`- ${SEV[f.severity] || "•"} \`${f.severity}\` ${f.title}${f.screen ? ` — on *${f.screen}*` : ""}${f.url ? ` — ${f.url}` : ""}`);
       if (f.aiAnalysis) L.push(`  - why: ${String(f.aiAnalysis).slice(0, 200)}`);
       if (f.suggestedFix) L.push(`  - fix: ${String(f.suggestedFix).slice(0, 200)}`);
     }
@@ -1375,7 +1457,7 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
     // 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 (comparison only — run \`tapp ci\` to gate)`
+      `**Since last run** — +${regression.counts.new} new · ${regression.counts.persisting} persisting · ${regression.counts.resolved} resolved (comparison only — run \`npx -y @aarwitz/tapp@latest ci\` to gate)`
     );
   }
   if (inputHint) {
@@ -1458,7 +1540,10 @@ export function formatScreen(screenTitle, elements) {
 // `tapp` CLI verbs in bin/tapp.js — same pattern as report.js. Keep orchestration HERE so
 // the surfaces can't drift.)
 
-export async function runQaWeb({ url, maxActions, timeout, testEmail, testPassword, baselineFindings, seedRoutes = [], seedTargets = [], surface = "mcp", onProgress = () => {} }) {
+export async function runQaWeb({ url, maxActions, timeout, testEmail, testPassword, baselineFindings, seedRoutes = [], seedTargets = [], watch = false, surface = "mcp", onProgress = () => {} }) {
+  const { storagePreflight } = await import("./environment-preflight.js");
+  const storage = storagePreflight(capturesDir);
+  if (!storage.ok) return { error: storage.message, details: { environment: "storage", storage } };
   const actions = Math.max(1, Math.min(1000, asInteger(maxActions, 60)));
   const timeoutSec = Math.max(30, Math.min(3600, asInteger(timeout, 600)));
   const id = "web-" + new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14).replace(/^(\d{8})/, "$1-");
@@ -1475,6 +1560,7 @@ export async function runQaWeb({ url, maxActions, timeout, testEmail, testPasswo
       testPassword: isNonEmptyString(testPassword) ? testPassword.trim() : "",
       seedRoutes,
       seedTargets,
+      watch: watch === true,
       onProgress,
     });
   } catch (err) {
@@ -1500,6 +1586,9 @@ export async function runQaWeb({ url, maxActions, timeout, testEmail, testPasswo
 }
 
 export async function runQaAndroid({ appId, apkPath, serial, maxActions, timeout, testEmail, testPassword, baselineFindings, clearData = true, seedTargets = [], surface = "mcp", onProgress = () => {} }) {
+  const { storagePreflight } = await import("./environment-preflight.js");
+  const storage = storagePreflight(capturesDir);
+  if (!storage.ok) return { error: storage.message, details: { environment: "storage", storage } };
   const actions = Math.max(1, Math.min(1000, asInteger(maxActions, 60)));
   const timeoutSec = Math.max(30, Math.min(3600, asInteger(timeout, 600)));
   const id = "android-" + new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14).replace(/^(\d{8})/, "$1-");
@@ -1543,6 +1632,9 @@ export async function runQaAndroid({ appId, apkPath, serial, maxActions, timeout
 }
 
 export async function runQaIos({ bundleId, maxActions, timeout, args = {}, surface = "mcp", onProgress = () => {} }) {
+  const { storagePreflight } = await import("./environment-preflight.js");
+  const storage = storagePreflight(capturesDir);
+  if (!storage.ok) return { error: storage.message, details: { environment: "storage", storage } };
   const captureScript = path.join(scriptsDir, "quick-capture.sh");
   if (!fs.existsSync(captureScript)) return { error: "Capture script not found", details: { captureScript } };
 
@@ -1635,6 +1727,7 @@ export async function runInitExploration({
   timeout,
   testEmail,
   testPassword,
+  watch = false,
   onProgress = () => {},
   onStatus = () => {},
 } = {}) {
@@ -1650,17 +1743,18 @@ export async function runInitExploration({
   let targetResolution = null;
   let qa;
   let managedRuntime = null;
+  if (watch && selected !== "web") return { error: "Watch mode is currently available for web exploration only." };
   if (selected === "web") {
     if (/^https?:\/\//i.test(String(url))) {
       resolvedTarget = String(url).trim();
-      qa = await runQaWeb({ url: resolvedTarget, maxActions, timeout, testEmail, testPassword, onProgress });
+      qa = await runQaWeb({ url: resolvedTarget, maxActions, timeout, testEmail, testPassword, watch, onProgress });
     } else {
       const started = await startManagedWebTarget({ root, requestedTarget: target, timeout, onStatus });
       if (started.error) return started;
       managedRuntime = started;
       resolvedTarget = started.url;
       try {
-        qa = await runQaWeb({ url: resolvedTarget, maxActions, timeout, testEmail, testPassword, onProgress });
+        qa = await runQaWeb({ url: resolvedTarget, maxActions, timeout, testEmail, testPassword, watch, onProgress });
       } finally {
         await stopManagedWebTarget(started);
       }
@@ -1772,6 +1866,7 @@ export async function runExploreTarget({
   appLaunchArgs,
   appLaunchEnv,
   baselineFindings,
+  watch = false,
   surface = "cli",
   onProgress = () => {},
   onStatus = () => {},
@@ -1782,7 +1877,7 @@ export async function runExploreTarget({
 
   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)." };
+    return { error: "No application model found — call `tapp_init` or run `npx -y @aarwitz/tapp@latest 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")); }
@@ -1794,6 +1889,8 @@ export async function runExploreTarget({
   catch (error) { return { error: error.message || String(error) }; }
   const selectedPlatform = selected.platform;
 
+  if (watch && selectedPlatform !== "web") return { error: "Watch mode is currently available for web exploration only." };
+
   if (selectedPlatform !== "ios" && ((Array.isArray(appLaunchArgs) && appLaunchArgs.length) || (appLaunchEnv && Object.keys(appLaunchEnv).length))) {
     return { error: "appLaunchArgs/appLaunchEnv apply only to iOS targets." };
   }
@@ -1802,14 +1899,14 @@ export async function runExploreTarget({
     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 });
+      return runQaWeb({ url: ownedUrl, maxActions, timeout, testEmail, testPassword, baselineFindings, watch, 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 });
+      return await runQaWeb({ url: started.url, maxActions, timeout, testEmail, testPassword, baselineFindings, watch, surface, onProgress });
     } finally {
       await stopManagedWebTarget(started);
       onStatus("Stopped the managed web runtime.");
@@ -1818,7 +1915,7 @@ export async function runExploreTarget({
 
   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.` };
+    if (!appId) return { error: `The Android target '${selected.name}' has no confirmed application id — confirm it and call \`tapp_init\` or rerun \`npx -y @aarwitz/tapp@latest init\`, or pass --app-id.` };
     const task = selected.build?.task || "assembleDebug";
     onStatus(`Building the Android APK (${task})…`);
     const built = await buildAndroidApp({
@@ -1856,6 +1953,22 @@ function openLocalPort() {
   });
 }
 
+function localPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once("error", () => resolve(false));
+    server.listen(port, "127.0.0.1", () => server.close(() => resolve(true)));
+  });
+}
+
+export function managedWebDefaultPort(dependencies = {}) {
+  if (dependencies.vite) return 5173;
+  if (dependencies.next) return 3000;
+  if (dependencies["react-scripts"]) return 3000;
+  return 0;
+}
+
 function managedInstallSpec(command) {
   const known = {
     "npm ci": ["npm", ["ci"]],
@@ -1940,7 +2053,9 @@ export async function startManagedWebTarget({ root, requestedTarget = "", timeou
   const pkg = (() => { try { return JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8")); } catch { return {}; } })();
   const dependencies = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
   const declaredPort = startMatch ? declaredPortFromStartScript(pkg.scripts?.[startMatch[1]]) : 0;
-  const port = declaredPort || await openLocalPort();
+  const frameworkPort = declaredPort ? 0 : managedWebDefaultPort(dependencies);
+  const port = declaredPort || (frameworkPort && await localPortAvailable(frameworkPort) ? frameworkPort : await openLocalPort());
+  const portBasis = declaredPort ? "repository-declared" : port === frameworkPort ? "framework-default" : "available-ephemeral";
   let command = "npm";
   let startArgs;
   let startDir = projectDir;
@@ -1967,13 +2082,13 @@ export async function startManagedWebTarget({ root, requestedTarget = "", timeou
   const append = (chunk) => fs.appendFileSync(logPath, String(chunk));
   child.stdout.on("data", append);
   child.stderr.on("data", append);
-  onStatus(`Managed web runtime: ${command === process.execPath ? "Tapp static server" : `npm ${startArgs.join(" ")}`} → http://127.0.0.1:${port}`);
+  onStatus(`Managed web runtime: ${command === process.execPath ? "Tapp static server" : `npm ${startArgs.join(" ")}`} → http://127.0.0.1:${port} (${portBasis} port)`);
   const ready = await waitForOwnedUrl(`http://127.0.0.1:${port}`, child, Math.min(budgetMs, 60_000), logPath);
   if (ready.error) {
     await stopManagedWebTarget({ child, detached: process.platform !== "win32" });
     return ready;
   }
-  return { child, detached: process.platform !== "win32", url: `http://127.0.0.1:${port}`, logPath, install, build, start: { command, args: startArgs, cwd: startDir } };
+  return { child, detached: process.platform !== "win32", url: `http://127.0.0.1:${port}`, logPath, install, build, start: { command, args: startArgs, cwd: startDir, portBasis } };
 }
 
 export async function stopManagedWebTarget(runtime) {
@@ -2032,11 +2147,61 @@ const server = new Server(
   },
   {
     capabilities: {
+      prompts: {},
       tools: {},
     },
   }
 );
 
+const testAppPrompt = {
+  name: "test-app",
+  title: "Test this app with Tapp",
+  description: "Use Tapp's real app surfaces to inspect, drive, or explore this repository and report evidence honestly.",
+  arguments: [
+    {
+      name: "goal",
+      description: "What to verify, such as finding bugs or exercising checkout",
+      required: false,
+    },
+    {
+      name: "target",
+      description: "Optional repo target, bundle/app id, APK path, or owned URL",
+      required: false,
+    },
+  ],
+};
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [testAppPrompt] }));
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  if (request.params.name !== testAppPrompt.name) {
+    throw new Error(`Unknown prompt: ${request.params.name}`);
+  }
+  const goal = isNonEmptyString(request.params.arguments?.goal)
+    ? request.params.arguments.goal.trim()
+    : "Test the app and find important bugs";
+  const target = isNonEmptyString(request.params.arguments?.target)
+    ? ` Use this target: ${request.params.arguments.target.trim()}.`
+    : "";
+  return {
+    description: testAppPrompt.description,
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text:
+            `${goal}.${target} Use the connected Tapp tools on the real UI surface. ` +
+            "Use the smallest operation that satisfies the request; initialize/explore the source repo only for a general repository test. " +
+            "If Tapp returns multiple target choices, ask me to select one instead of guessing. " +
+            "Read visual evidence before describing it. Report findings, coverage, authority, inconclusive state, and checked/not-checked scope; " +
+            "never turn exploration into a score or ship verdict. Do not edit the app unless I ask for a fix.",
+        },
+      },
+    ],
+  };
+});
+
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
@@ -2208,6 +2373,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           androidSerial: { type: "string", description: "Android: optional adb device serial; defaults to the first authorized device." },
           clearData: { type: "boolean", default: true, description: "Android: clear app data before launch for a repeatable starting state." },
           url: { type: "string", description: "Web (beta): URL of the app to explore in a real browser (same-origin only; your own app/staging). Provide exactly one of appBundleId | url." },
+          watch: { type: "boolean", default: false, description: "Web only: open Tapp's controlled Chromium window and show a cursor/HUD for each exploration action. Evidence screenshots exclude the overlay." },
           maxActions: { type: "integer", minimum: 1, maximum: 1000, default: 60, description: "Exploration action budget" },
           timeout: { type: "integer", minimum: 30, maximum: 3600, default: 600, description: "Max wall-clock seconds" },
           testEmail: { type: "string", description: "Email for the login preamble, if the app has a sign-in" },
@@ -2250,7 +2416,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
               "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 " +
+              "run `npx -y @aarwitz/tapp@latest ci` (or the GitHub Action): it applies the deterministic policy and returns the " +
               "pass/fail/inconclusive outcome.",
           },
         },
@@ -2278,6 +2444,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           timeout: { type: "integer", minimum: 30, maximum: 3600, default: 600 },
           testEmail: { type: "string", description: "Explore: actor/login email; never persisted in the model" },
           testPassword: { type: "string", description: "Explore: actor/login password; never persisted in the model" },
+          watch: { type: "boolean", default: false, description: "Web explore only: show the controlled browser and Tapp's actions" },
           maxContracts: { type: "integer", minimum: 1, maximum: 50, default: 15 },
           outDir: { type: "string", description: "Repo-relative artifact directory; default .tapp" },
         },
@@ -2731,45 +2898,62 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args = {} } = request.params;
 
   if (name === "tapp_health") {
-    const checks = [];
-
-    checks.push({
-      check: "repoRoot",
-      ok: fs.existsSync(path.join(repoRoot, "Tapp.xcodeproj")),
-      value: repoRoot,
+    const coreChecks = [];
+    coreChecks.push({
+      check: "workspace",
+      ok: fs.existsSync(workspaceRoot) && fs.statSync(workspaceRoot).isDirectory(),
+      value: workspaceRoot,
+      required: true,
     });
 
     const nodeVersion = await runCommand("node", ["-v"]);
-    checks.push({
+    coreChecks.push({
       check: "node",
       ok: nodeVersion.code === 0,
       value: nodeVersion.stdout.trim() || nodeVersion.stderr.trim(),
+      required: true,
     });
 
     const xcodebuildVersion = await runCommand("xcodebuild", ["-version"]);
-    checks.push({
-      check: "xcodebuild",
-      ok: xcodebuildVersion.code === 0,
-      value: (xcodebuildVersion.stdout || xcodebuildVersion.stderr).trim().split("\n")[0] || "not found",
-    });
-
-    const simctl = await runCommand("xcrun", ["simctl", "list", "devices", "booted"]);
-    checks.push({
-      check: "bootedSimulator",
-      ok: simctl.code === 0,
-      value: (simctl.stdout || simctl.stderr).trim(),
-    });
-
-    const allOk = checks.every((c) => c.ok);
+    const simctl = xcodebuildVersion.code === 0
+      ? await runCommand("xcrun", ["simctl", "list", "devices", "booted"])
+      : { code: 1, stdout: "", stderr: "Xcode not found" };
     const bootedLine = (simctl.stdout || "").split("\n").find((l) => /\(Booted\)/.test(l));
     const bootedName = bootedLine ? bootedLine.trim().replace(/\s*\(.*$/, "") : null;
-    const L = [`### ${allOk ? "🩺 Tapp ready" : "⚠️ Tapp not fully ready"}`, ""];
+    const adb = await runCommand("adb", ["devices"]);
+    const androidDevice = adb.code === 0
+      ? (adb.stdout || "").split("\n").find((line) => /\tdevice\s*$/.test(line))
+      : null;
+    let web = { ok: false, value: "Playwright or Chromium not installed" };
+    try {
+      const { chromium } = await import("playwright");
+      const executable = chromium.executablePath();
+      web = { ok: fs.existsSync(executable), value: fs.existsSync(executable) ? executable : "Chromium not installed" };
+    } catch { /* optional dependency may be intentionally absent */ }
+    const platformChecks = [
+      {
+        check: "iOS",
+        ok: xcodebuildVersion.code === 0 && !!bootedName,
+        value: bootedName ? `${bootedName} booted` : xcodebuildVersion.code === 0 ? "Xcode available; no simulator booted" : "Xcode not found",
+        required: false,
+      },
+      {
+        check: "Android",
+        ok: !!androidDevice,
+        value: androidDevice ? `${androidDevice.split("\t")[0]} connected` : adb.code === 0 ? "adb available; no authorized device" : "adb not found",
+        required: false,
+      },
+      { check: "web", ok: web.ok, value: web.value, required: false },
+    ];
+    const checks = [...coreChecks, ...platformChecks];
+    const ready = coreChecks.every((check) => check.ok) && platformChecks.some((check) => check.ok);
+    const L = [`### ${ready ? "🩺 Tapp ready" : "⚠️ Tapp needs a platform runtime"}`, ""];
     for (const c of checks) {
-      L.push(`- ${c.ok ? "✅" : "❌"} **${c.check}** — ${String(c.value).split("\n")[0] || "—"}`);
+      const icon = c.ok ? "✅" : c.required ? "❌" : "⚪️";
+      L.push(`- ${icon} **${c.check}** — ${String(c.value).split("\n")[0] || "—"}`);
     }
-    L.push("");
-    L.push(bootedName ? `📱 Simulator booted: **${bootedName}**` : "📱 No simulator booted — run `tapp_boot_simulator` first.");
-    return richResult(L.join("\n"), { ok: allOk, checks });
+    if (!ready) L.push("", "Run `npx -y @aarwitz/tapp@latest doctor` in the application repository for exact remediation.");
+    return richResult(L.join("\n"), { ok: ready, workspaceRoot, checks, platforms: Object.fromEntries(platformChecks.map((check) => [check.check.toLowerCase(), check.ok])) });
   }
 
   if (name === "tapp_build") {
@@ -2788,11 +2972,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (inst.error) return errorResult(inst.error);
       bundleId = inst.bundleId;
     }
+    let modelRefresh = null;
+    let modelRefreshWarning = "";
+    if (bundleId) {
+      try {
+        const { persistIosBuildValidation } = await import("./application-model.js");
+        modelRefresh = await persistIosBuildValidation({ projectDir: dir, bundleId, container: built.container, scheme: built.scheme, configuration: built.configuration });
+      } catch (error) {
+        modelRefreshWarning = error.message || String(error);
+      }
+    }
     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_explore\` with \`appBundleId: "${bundleId || "<install it first>"}"\`.`;
-    return richResult(text, { ok: true, appPath: built.appPath, scheme: built.scheme, container: built.container, bundleId });
+    return richResult(text + (modelRefresh ? `\nApplication model refreshed: \`${modelRefresh.modelPath}\`.` : modelRefreshWarning ? `\n⚠️ Application model refresh failed: ${modelRefreshWarning}` : ""), { ok: true, appPath: built.appPath, scheme: built.scheme, container: built.container, bundleId, modelRefreshed: !!modelRefresh, ...(modelRefreshWarning ? { modelRefreshWarning } : {}) });
   }
 
   if (name === "tapp_capture") {
@@ -2966,6 +3160,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (targets !== 1) {
       return errorResult("Provide exactly one of appBundleId (iOS), androidAppId (Android), or url (web beta)");
     }
+    if (args.watch === true && !wantsWeb) return errorResult("watch is currently available for web exploration only");
 
     // Both branches call the shared engine (runQaWeb/runQaIos) — the handler only adds
     // MCP concerns: auth, arg validation, and progress notifications.
@@ -2987,6 +3182,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         testEmail: args.testEmail,
         testPassword: args.testPassword,
         baselineFindings: args.baselineFindings,
+        watch: args.watch === true,
         onProgress: notifyProgress("pages reached"),
       });
       if (r.error) return errorResult(r.error, r.details || {});
@@ -3031,8 +3227,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "inspect").toLowerCase();
     if (!["inspect", "write", "refresh", "explore"].includes(operation)) return errorResult("operation must be inspect|write|refresh|explore");
-    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-    if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the repo");
+    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+    if (!isInsideDir(workspaceRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the workspace");
     const maxContracts = asInteger(args.maxContracts, 15);
     if (maxContracts < 1 || maxContracts > 50) return errorResult("maxContracts must be between 1 and 50");
     const { initializeProductProject } = await import("./product-operations.js");
@@ -3042,32 +3238,42 @@ 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,
         serial: isNonEmptyString(args.androidSerial) ? args.androidSerial.trim() : undefined,
         maxActions: args.maxActions, timeout: args.timeout, maxContracts,
         testEmail: args.testEmail, testPassword: args.testPassword,
+        watch: args.watch === true,
         runExploration: runInitExploration,
         onProgress: (progress) => {
           if (progressToken === undefined) return;
           server.notification({ method: "notifications/progress", params: { progressToken, progress: progress.action || 0, total: progress.max || budget, message: `Import exploration · ${progress.states} state(s) reached` } }).catch(() => {});
         },
       });
-      const { model, plan, written, exploration } = result;
-      const blocking = model.requirements.filter((item) => item.severity === "blocking");
+      const { model, plan, written, exploration, selectedTarget, requirementScope } = result;
+      const blocking = (requirementScope?.active || model.requirements).filter((item) => item.severity === "blocking");
+      const deferredBlocking = (requirementScope?.deferred || []).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.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) }); }
+      const selectedLabel = selectedTarget ? ` for ${selectedTarget.platform}:${selectedTarget.name}` : "";
+      const deferredLabel = deferredBlocking.length ? ` · ${deferredBlocking.length} setup gap(s) on unselected target(s)` : "";
+      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)${selectedLabel}${deferredLabel}${exploration ? ` · real ${exploration.platform} exploration: ${(exploration.findings || []).length} finding(s)${exploration.inconclusive ? " (inconclusive)" : ""}` : ""}`;
+      return richResult(summary, { model, plan, selectedTarget, requirementScope, written: written ? { modelPath: written.modelPath, planPath: written.planPath } : null, exploration });
+    } 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") {
@@ -3078,8 +3284,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const allowedArguments = new Set(["authToken", "operation", "projectDir", "name", "role", "session", "provisioning", "credentialBindings", "replace"]);
     const unexpectedArguments = Object.keys(args).filter((key) => !allowedArguments.has(key));
     if (unexpectedArguments.length) return errorResult("Unsupported actor configuration fields; credential values are never accepted", { fields: unexpectedArguments });
-    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-    if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) return errorResult("projectDir must be an existing directory inside the repo");
+    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+    if (!isInsideDir(workspaceRoot, projectDir) || !fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) return errorResult("projectDir must be an existing directory inside the workspace");
     const { configureActor, readProjectConfig } = await import("./project-config.js");
     if (operation === "read") {
       const loaded = readProjectConfig(projectDir);
@@ -3099,7 +3305,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         credentials,
         replace: asBoolean(args.replace),
       });
-      return richResult(`✅ Actor '${args.name.trim()}' configured with ${Object.keys(result.actor.credentials).length} environment binding(s); no credential values were accepted or written`, { path: result.path, actor: result.actor, next: "Run tapp_init refresh to update the application model and release plan." });
+      const { refreshExistingInitArtifacts } = await import("./application-model.js");
+      let refreshed = null;
+      let refreshWarning = "";
+      try { refreshed = await refreshExistingInitArtifacts({ projectDir }); }
+      catch (error) { refreshWarning = error.message || String(error); }
+      return richResult(
+        `✅ Actor '${args.name.trim()}' configured with ${Object.keys(result.actor.credentials).length} environment binding(s); no credential values were accepted or written${refreshed ? " · application model refreshed" : ""}${refreshWarning ? `\n⚠️ Application model refresh failed: ${refreshWarning}` : ""}`,
+        { path: result.path, actor: result.actor, modelRefreshed: !!refreshed, ...(refreshed ? { modelPath: refreshed.modelPath, planPath: refreshed.planPath } : {}), ...(refreshWarning ? { refreshWarning } : {}) },
+      );
     } catch (error) { return errorResult("Actor not configured", { detail: error.message || String(error) }); }
   }
 
@@ -3108,8 +3322,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "read").toLowerCase();
     if (!["read", "review", "generate", "validate", "promote"].includes(operation)) return errorResult("operation must be read|review|generate|validate|promote");
-    const planPath = isNonEmptyString(args.planPath) ? path.resolve(repoRoot, args.planPath.trim()) : existingProjectArtifactPath(repoRoot, "release-plan.json");
-    if (!isInsideDir(repoRoot, planPath)) return errorResult("planPath must be inside the repo");
+    const planPath = isNonEmptyString(args.planPath) ? path.resolve(workspaceRoot, args.planPath.trim()) : existingProjectArtifactPath(workspaceRoot, "release-plan.json");
+    if (!isInsideDir(workspaceRoot, planPath)) return errorResult("planPath must be inside the workspace");
     if (!fs.existsSync(planPath)) return errorResult("Release plan not found", { planPath });
     let plan;
     try { plan = JSON.parse(fs.readFileSync(planPath, "utf8")); }
@@ -3119,11 +3333,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (![...decisions.approve, ...decisions.reject, ...decisions.defer].length) return errorResult("review requires at least one approve, reject, or defer item");
       const { reviewProductPlan } = await import("./product-operations.js");
       try {
-        plan = reviewProductPlan({ projectDir: repoRoot, planPath, ...decisions }).plan;
+        plan = reviewProductPlan({ projectDir: workspaceRoot, planPath, ...decisions }).plan;
       } catch (error) { return errorResult("Could not review release plan", { detail: error.message || String(error) }); }
     } else if (operation === "generate") {
-      const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-      if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the repo");
+      const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+      if (!isInsideDir(workspaceRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the workspace");
       const { generateProductPlan } = await import("./product-operations.js");
       try {
         const result = await generateProductPlan({ projectDir, planPath });
@@ -3131,8 +3345,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return richResult(`🧩 Proposal drafts — ${result.generatedTasks.length} UI-Map-grounded Task(s) · ${result.generated.length} compile-checked/untrusted contract(s) · ${result.blocked.length} blocked; deterministic real-surface replay remains required`, { plan, planPath, generatedTasks: result.generatedTasks, generated: result.generated, blocked: result.blocked });
       } catch (error) { return errorResult("Could not generate contract drafts", { detail: error.message || String(error) }); }
     } else if (operation === "validate") {
-      const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-      if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the repo");
+      const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+      if (!isInsideDir(workspaceRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the workspace");
       let apkPath = "";
       if (isNonEmptyString(args.apkPath)) {
         apkPath = path.resolve(projectDir, args.apkPath.trim());
@@ -3164,8 +3378,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return richResult(`🔎 Generated contract validation passed — ${result.results.length}/${result.results.length} on ${result.platform}`, { ...result, planPath });
       } catch (error) { return errorResult("Generated contract validation failed", { detail: error.message || String(error), plan, planPath }); }
     } else if (operation === "promote") {
-      const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-      if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the repo");
+      const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+      if (!isInsideDir(workspaceRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the workspace");
       const { promoteProductPlan } = await import("./product-operations.js");
       try {
         const result = await promoteProductPlan({ projectDir, planPath, items: Array.isArray(args.items) ? args.items : [] });
@@ -3181,9 +3395,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "inspect").toLowerCase();
     if (!["inspect", "install", "baseline"].includes(operation)) return errorResult("operation must be inspect|install|baseline");
-    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-    if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) return errorResult("projectDir must be an existing directory inside the repo");
-    const modelPath = isNonEmptyString(args.modelPath) ? path.resolve(repoRoot, args.modelPath.trim()) : existingProjectArtifactPath(projectDir, "application-model.json");
+    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+    if (!isInsideDir(workspaceRoot, projectDir) || !fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) return errorResult("projectDir must be an existing directory inside the workspace");
+    const modelPath = isNonEmptyString(args.modelPath) ? path.resolve(workspaceRoot, args.modelPath.trim()) : existingProjectArtifactPath(projectDir, "application-model.json");
     if (!isInsideDir(projectDir, modelPath) || !fs.existsSync(modelPath)) return errorResult("Application model not found inside projectDir; run tapp_init first", { modelPath });
     let model;
     try { model = JSON.parse(fs.readFileSync(modelPath, "utf8")); }
@@ -3191,8 +3405,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { createProductBaseline, installProductCi, prepareProductCi } = await import("./product-operations.js");
     if (operation === "baseline") {
       if (!isNonEmptyString(args.reportPath)) return errorResult("baseline requires reportPath from a successful portable gate");
-      const reportPath = path.resolve(repoRoot, args.reportPath.trim());
-      if (!isInsideDir(repoRoot, reportPath) || !fs.existsSync(reportPath)) return errorResult("reportPath must be an existing JSON file inside the repo");
+      const reportPath = path.resolve(workspaceRoot, args.reportPath.trim());
+      if (!isInsideDir(workspaceRoot, reportPath) || !fs.existsSync(reportPath)) return errorResult("reportPath must be an existing JSON file inside the workspace");
       let report;
       try { report = JSON.parse(fs.readFileSync(reportPath, "utf8")); }
       catch (error) { return errorResult("Gate report is invalid JSON", { detail: error.message || String(error) }); }
@@ -3217,8 +3431,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "read").toLowerCase();
     const resolveRepoFile = (value, fallback = "") => {
-      const resolved = path.resolve(repoRoot, isNonEmptyString(value) ? value.trim() : fallback);
-      return isInsideDir(repoRoot, resolved) ? resolved : null;
+      const resolved = path.resolve(workspaceRoot, isNonEmptyString(value) ? value.trim() : fallback);
+      return isInsideDir(workspaceRoot, resolved) ? resolved : null;
     };
     const capture = isNonEmptyString(args.captureId) ? listCaptureRuns(200).find((run) => run.id === args.captureId.trim()) : null;
     if (isNonEmptyString(args.captureId) && !capture) return errorResult("Capture not found", { captureId: args.captureId });
@@ -3238,18 +3452,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const markersPath = capture ? path.join(capture.path, "ocqa-markers.txt") : resolveRepoFile(args.markersPath);
       if (!markersPath) return errorResult("markersPath must be inside the repo, or provide captureId");
       if (!fs.existsSync(markersPath)) return errorResult("OCQA markers not found", { markersPath });
-      const outPath = isNonEmptyString(args.mapPath) ? resolveRepoFile(args.mapPath) : existingProjectArtifactPath(repoRoot, "ui-map.json");
+      const outPath = isNonEmptyString(args.mapPath) ? resolveRepoFile(args.mapPath) : existingProjectArtifactPath(workspaceRoot, "ui-map.json");
       if (!outPath) return errorResult("mapPath must be inside the repo");
       try {
         const observed = buildUiMapFromMarkers({ markersPath, platform: args.platform || "ios", target: args.target || "", runId: capture?.id || "" });
         const map = fs.existsSync(outPath) && args.replace !== true ? mergeUiMaps(JSON.parse(fs.readFileSync(outPath, "utf8")), observed) : observed;
         writeUiMap(outPath, map);
         const controls = map.nodes.reduce((total, node) => total + node.controls.length, 0);
-        return richResult(`🗺️ UI Map updated — ${map.nodes.length} states · ${map.edges.length} transitions · ${controls} semantic controls\n${path.relative(repoRoot, outPath)}`, { map, path: outPath });
+        return richResult(`🗺️ UI Map updated — ${map.nodes.length} states · ${map.edges.length} transitions · ${controls} semantic controls\n${path.relative(workspaceRoot, outPath)}`, { map, path: outPath });
       } catch (error) { return errorResult("Could not build UI Map", { detail: error.message || String(error) }); }
     }
     if (operation !== "read") return errorResult("operation must be read|build|diff");
-    const mapPath = capture ? path.join(capture.path, "ui-map.json") : isNonEmptyString(args.mapPath) ? resolveRepoFile(args.mapPath) : existingProjectArtifactPath(repoRoot, "ui-map.json");
+    const mapPath = capture ? path.join(capture.path, "ui-map.json") : isNonEmptyString(args.mapPath) ? resolveRepoFile(args.mapPath) : existingProjectArtifactPath(workspaceRoot, "ui-map.json");
     if (!mapPath) return errorResult("mapPath must be inside the repo");
     if (!fs.existsSync(mapPath)) return errorResult("UI Map not found; run QA or operation=build first", { mapPath });
     try {
@@ -3266,8 +3480,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "validate").toLowerCase();
     if (!["read", "validate", "compile"].includes(operation)) return errorResult("operation must be read|validate|compile");
-    const taskPath = isNonEmptyString(args.taskPath) ? path.resolve(repoRoot, args.taskPath.trim()) : null;
-    if (!taskPath || !isInsideDir(repoRoot, taskPath)) return errorResult("taskPath must be inside the repo");
+    const taskPath = isNonEmptyString(args.taskPath) ? path.resolve(workspaceRoot, args.taskPath.trim()) : null;
+    if (!taskPath || !isInsideDir(workspaceRoot, taskPath)) return errorResult("taskPath must be inside the workspace");
     if (!fs.existsSync(taskPath)) return errorResult("Task file not found", { taskPath: args.taskPath });
     const { applyTaskCoverage, compileTaskSteps, loadTaskFile, loadTaskRegistry, validateTaskAgainstUiMap } = await import("./task-runtime.js");
     let task;
@@ -3278,8 +3492,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     let groundingMap = null;
     let groundingMapPath = null;
     if (isNonEmptyString(args.mapPath)) {
-      const mapPath = path.resolve(repoRoot, args.mapPath.trim());
-      if (!isInsideDir(repoRoot, mapPath)) return errorResult("mapPath must be inside the repo");
+      const mapPath = path.resolve(workspaceRoot, args.mapPath.trim());
+      if (!isInsideDir(workspaceRoot, mapPath)) return errorResult("mapPath must be inside the workspace");
       if (!fs.existsSync(mapPath)) return errorResult("UI Map not found", { mapPath: args.mapPath });
       groundingMapPath = mapPath;
       try {
@@ -3309,12 +3523,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const flow = { name: `Task: ${task.name}`, kind: "flow", platform: args.platform || "", vars: compiled.vars, steps: compiled.steps, taskPlan: compiled.plan };
     let outPath = null;
     if (isNonEmptyString(args.outPath)) {
-      outPath = path.resolve(repoRoot, args.outPath.trim());
-      if (!isInsideDir(repoRoot, outPath)) return errorResult("outPath must be inside the repo");
+      outPath = path.resolve(workspaceRoot, args.outPath.trim());
+      if (!isInsideDir(workspaceRoot, outPath)) return errorResult("outPath must be inside the workspace");
       fs.mkdirSync(path.dirname(outPath), { recursive: true });
       fs.writeFileSync(outPath, JSON.stringify(flow, null, 2) + "\n");
     }
-    return richResult(`🧩 Compiled ${task.name} into ${flow.steps.length} deterministic Flow steps${outPath ? `\n${path.relative(repoRoot, outPath)}` : ""}`, { flow, grounding, path: outPath });
+    return richResult(`🧩 Compiled ${task.name} into ${flow.steps.length} deterministic Flow steps${outPath ? `\n${path.relative(workspaceRoot, outPath)}` : ""}`, { flow, grounding, path: outPath });
   }
 
   if (name === "tapp_release_contract") {
@@ -3322,8 +3536,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "validate").toLowerCase();
     if (!["read", "validate", "compile", "run"].includes(operation)) return errorResult("operation must be read|validate|compile|run");
-    const contractPath = isNonEmptyString(args.contractPath) ? path.resolve(repoRoot, args.contractPath.trim()) : null;
-    if (!contractPath || !isInsideDir(repoRoot, contractPath)) return errorResult("contractPath must be inside the repo");
+    const contractPath = isNonEmptyString(args.contractPath) ? path.resolve(workspaceRoot, args.contractPath.trim()) : null;
+    if (!contractPath || !isInsideDir(workspaceRoot, contractPath)) return errorResult("contractPath must be inside the workspace");
     const {
       applyReleaseContractCoverage,
       compileReleaseContract,
@@ -3338,8 +3552,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     let groundingMap = null;
     let groundingMapPath = null;
     if (isNonEmptyString(args.mapPath)) {
-      groundingMapPath = path.resolve(repoRoot, args.mapPath.trim());
-      if (!isInsideDir(repoRoot, groundingMapPath)) return errorResult("mapPath must be inside the repo");
+      groundingMapPath = path.resolve(workspaceRoot, args.mapPath.trim());
+      if (!isInsideDir(workspaceRoot, groundingMapPath)) return errorResult("mapPath must be inside the workspace");
       if (!fs.existsSync(groundingMapPath)) return errorResult("UI Map not found", { mapPath: args.mapPath });
       try {
         groundingMap = JSON.parse(fs.readFileSync(groundingMapPath, "utf8"));
@@ -3360,8 +3574,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     catch (error) { return errorResult("Could not compile Release Contract", { detail: error.message || String(error) }); }
     let outPath = null;
     if (isNonEmptyString(args.outPath)) {
-      outPath = path.resolve(repoRoot, args.outPath.trim());
-      if (!isInsideDir(repoRoot, outPath)) return errorResult("outPath must be inside the repo");
+      outPath = path.resolve(workspaceRoot, args.outPath.trim());
+      if (!isInsideDir(workspaceRoot, outPath)) return errorResult("outPath must be inside the workspace");
       fs.mkdirSync(path.dirname(outPath), { recursive: true });
       fs.writeFileSync(outPath, JSON.stringify(execution, null, 2) + "\n");
     }
@@ -3408,12 +3622,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = isNonEmptyString(args.operation) ? args.operation.trim().toLowerCase() : "plan";
     if (!['plan', 'adopt'].includes(operation)) return errorResult("operation must be plan|adopt");
-    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-    if (!isInsideDir(repoRoot, projectDir)) return errorResult("projectDir must be inside the repo");
+    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+    if (!isInsideDir(workspaceRoot, projectDir)) return errorResult("projectDir must be inside the workspace");
     if (operation === "adopt") {
       if (!isNonEmptyString(args.prPlanPath) || !isNonEmptyString(args.item)) return errorResult("adopt requires prPlanPath and item");
       const prPlanPath = path.resolve(projectDir, args.prPlanPath.trim());
-      if (!isInsideDir(repoRoot, prPlanPath)) return errorResult("prPlanPath must be inside the repo");
+      if (!isInsideDir(workspaceRoot, prPlanPath)) return errorResult("prPlanPath must be inside the workspace");
       const { adoptPrCoverageProposal } = await import("./pr-selection.js");
       try {
         const adopted = adoptPrCoverageProposal({
@@ -3457,8 +3671,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       fs.writeFileSync(flowFile, JSON.stringify(args.flow));
       parsedFlow = args.flow;
     } else if (isNonEmptyString(args.flowPath)) {
-      const p = path.resolve(repoRoot, args.flowPath.trim());
-      if (!isInsideDir(repoRoot, p)) return errorResult("flowPath must be inside the repo");
+      const p = path.resolve(workspaceRoot, args.flowPath.trim());
+      if (!isInsideDir(workspaceRoot, p)) return errorResult("flowPath must be inside the workspace");
       if (!fs.existsSync(p)) return errorResult("Flow file not found", { flowPath: args.flowPath });
       flowFile = p;
     } else {
@@ -3540,8 +3754,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (args.scenario && typeof args.scenario === "object") {
       scenario = args.scenario;
     } else if (isNonEmptyString(args.scenarioPath)) {
-      const scenarioFile = path.resolve(repoRoot, args.scenarioPath.trim());
-      if (!isInsideDir(repoRoot, scenarioFile)) return errorResult("scenarioPath must be inside the repo");
+      const scenarioFile = path.resolve(workspaceRoot, args.scenarioPath.trim());
+      if (!isInsideDir(workspaceRoot, scenarioFile)) return errorResult("scenarioPath must be inside the workspace");
       if (!fs.existsSync(scenarioFile)) return errorResult("Scenario file not found", { scenarioPath: args.scenarioPath });
       try {
         const { loadScenarioFile } = await import("./scenario-runtime.js");
@@ -3611,7 +3825,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     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", "proposals", "flows");
+    const dir = path.join(workspaceRoot, ".tapp", "proposals", "flows");
     fs.mkdirSync(dir, { recursive: true });
     const outPath = path.join(dir, `${slug}.yml`);
     const promotedPath = path.join(".tapp", "flows", `${slug}.yml`);
@@ -3619,7 +3833,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     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 rel = path.relative(workspaceRoot, outPath);
 
     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."}`);
@@ -3867,14 +4081,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const detailNote = !ok && r.detail ? ` — ${r.detail}` : "";
     const head = `${did} — ${ok ? "ok" : `⚠️ ${r.status}${detailNote}`} → now on **${r.screenTitle || "Unknown"}**`;
     const rec = typeof r.recordedSteps === "number" ? `\n\n🔴 Recording — ${r.recordedSteps} step(s). \`tapp_flow_save\` to keep it as a test.` : "";
-    return richResult(head + "\n\n" + formatScreen(r.screenTitle, r.elements) + rec, r);
+    const result = richResult(head + "\n\n" + formatScreen(r.screenTitle, r.elements) + rec, r);
+    if (!ok) result.isError = true;
+    return result;
   }
 
   if (name === "tapp_flow_save") {
     const unauthorized = ensureAuthorized(args);
     if (unauthorized) return unauthorized;
     try {
-      const saved = await saveInteractiveSessionFlow({ projectDir:repoRoot, name:args.name, addFinalAssertion:args.addFinalAssertion !== false, replace:args.replace === true });
+      const saved = await saveInteractiveSessionFlow({ projectDir:workspaceRoot, name:args.name, addFinalAssertion:args.addFinalAssertion !== false, replace:args.replace === true });
       const text = `💾 Saved flow **${saved.flow.name}** → \`${saved.path}\` (${saved.flow.steps.length} steps)\n\n\`\`\`yaml\n${saved.yaml}\n\`\`\`\n\nReplay it anytime: \`tapp_flow_run\` with \`flowPath: "${saved.path}"\`.`;
       return richResult(text, { path:saved.path, flow:saved.flow });
     } catch (error) {