@yoqa/runner 0.3.26 → 0.3.28

package/dist/index.js

@@ -16444,6 +16444,7 @@ var apps = sqliteTable("apps", {
   name: text("name").notNull(),
   prefix: text("prefix").notNull().default(""),
   context: text("context").notNull().default(""),
+  knowledge: text("knowledge").notNull().default(""),
   iosBundleId: text("ios_bundle_id").notNull().default(""),
   iosAppStoreId: text("ios_app_store_id").notNull().default(""),
   androidApplicationId: text("android_application_id").notNull().default(""),
@@ -16500,6 +16501,7 @@ var runs = sqliteTable("runs", {
   buildId: text("build_id"),
   status: text("status").notNull(),
   executionMode: text("execution_mode").notNull().default("auto"),
+  screenMode: text("screen_mode").notNull().default("tree"),
   error: text("error"),
   createdAt: integer("created_at").notNull(),
   startedAt: integer("started_at"),
@@ -16524,6 +16526,7 @@ var runSteps = sqliteTable("run_steps", {
   screenshotUri: text("screenshot_uri"),
   ok: integer("ok").notNull().default(0),
   latencyMs: integer("latency_ms").notNull().default(0),
+  phasesJson: text("phases_json"),
   detail: text("detail"),
   command: text("command"),
   createdAt: integer("created_at").notNull()
@@ -16543,6 +16546,7 @@ function ensureSchema(sqlite) {
 			name TEXT NOT NULL,
 			prefix TEXT NOT NULL DEFAULT '',
 			context TEXT NOT NULL DEFAULT '',
+			knowledge TEXT NOT NULL DEFAULT '',
 			ios_bundle_id TEXT NOT NULL DEFAULT '',
 			ios_app_store_id TEXT NOT NULL DEFAULT '',
 			android_application_id TEXT NOT NULL DEFAULT '',
@@ -16626,6 +16630,7 @@ function ensureSchema(sqlite) {
 			build_id TEXT,
 			status TEXT NOT NULL,
 			execution_mode TEXT NOT NULL DEFAULT 'auto',
+			screen_mode TEXT NOT NULL DEFAULT 'tree',
 			error TEXT,
 			created_at INTEGER NOT NULL,
 			started_at INTEGER,
@@ -16652,6 +16657,7 @@ function ensureSchema(sqlite) {
 			screenshot_uri TEXT,
 			ok INTEGER NOT NULL DEFAULT 0,
 			latency_ms INTEGER NOT NULL DEFAULT 0,
+			phases_json TEXT,
 			detail TEXT,
 			command TEXT,
 			created_at INTEGER NOT NULL
@@ -16670,9 +16676,12 @@ function ensureSchema(sqlite) {
 	`);
   migrateProvidersTable(sqlite);
   migrateAppsPrefix(sqlite);
+  migrateAppsKnowledge(sqlite);
   migrateCaseScripts(sqlite);
   migrateRunExecutionMode(sqlite);
+  migrateRunScreenMode(sqlite);
   migrateRunCommands(sqlite);
+  migrateRunStepPhases(sqlite);
 }
 function tableColumns(sqlite, table) {
   const rows = sqlite.query(`PRAGMA table_info(${table})`).all();
@@ -16701,6 +16710,12 @@ function migrateRunExecutionMode(sqlite) {
     addColumnIfMissing(sqlite, "run_tests", "execution_mode", "execution_mode TEXT", testCols);
   }
 }
+function migrateRunScreenMode(sqlite) {
+  const runCols = tableColumns(sqlite, "runs");
+  if (runCols.size > 0) {
+    addColumnIfMissing(sqlite, "runs", "screen_mode", "screen_mode TEXT NOT NULL DEFAULT 'tree'", runCols);
+  }
+}
 function migrateRunCommands(sqlite) {
   const testCols = tableColumns(sqlite, "run_tests");
   if (testCols.size > 0) {
@@ -16711,6 +16726,12 @@ function migrateRunCommands(sqlite) {
     addColumnIfMissing(sqlite, "run_steps", "command", "command TEXT", stepCols);
   }
 }
+function migrateRunStepPhases(sqlite) {
+  const stepCols = tableColumns(sqlite, "run_steps");
+  if (stepCols.size === 0)
+    return;
+  addColumnIfMissing(sqlite, "run_steps", "phases_json", "phases_json TEXT", stepCols);
+}
 function migrateProvidersTable(sqlite) {
   const existing = tableColumns(sqlite, "providers");
   if (existing.size === 0)
@@ -16793,6 +16814,12 @@ function migrateAppsPrefix(sqlite) {
     sqlite.run("UPDATE apps SET prefix = ? WHERE id = ?", [candidate, row.id]);
   }
 }
+function migrateAppsKnowledge(sqlite) {
+  const existing = tableColumns(sqlite, "apps");
+  if (existing.size === 0)
+    return;
+  addColumnIfMissing(sqlite, "apps", "knowledge", "knowledge TEXT NOT NULL DEFAULT ''", existing);
+}
 function getCatalogDbPath() {
   return process.env.YOQA_DB_PATH ?? DEFAULT_DB_PATH;
 }
@@ -16816,7 +16843,7 @@ function getCatalogDb() {
 // package.json
 var package_default = {
   name: "@yoqa/runner",
-  version: "0.3.26",
+  version: "0.3.28",
   description: "Yoqa local runner \u2014 Appium + catalog HTTP API (Bun). Start with yoqa serve or the yoqa-runner bin.",
   license: "UNLICENSED",
   type: "module",
@@ -16836,7 +16863,7 @@ var package_default = {
     url: "git+https://github.com/Aris-ngoy/qa-agent.git",
     directory: "services/runner"
   },
-  homepage: "https://yoqa.mintlify.app/docs/cli",
+  homepage: "https://yoqa.arisn.dev/docs/cli",
   bugs: {
     url: "https://github.com/Aris-ngoy/qa-agent/issues"
   },
@@ -16912,8 +16939,8 @@ function abortAllMjpegProxies() {
 // src/domains/devices/session.ts
 import { mkdir as mkdir3 } from "fs/promises";
 import { createServer as createServer2 } from "net";
-import { homedir as homedir6 } from "os";
-import { join as join7 } from "path";
+import { homedir as homedir7 } from "os";
+import { join as join8 } from "path";
 import { remote } from "webdriverio";
 
 // src/domains/devices/android-gestures.ts
@@ -17596,10 +17623,13 @@ function isUnsupportedCommandError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return /unknown command|unknown method|not (yet )?(been )?implemented|not (yet )?supported|does not support/i.test(message);
 }
+var W3C_RETURN_KEY = "\uE007";
 function w3cKeyActions(text2) {
   const actions = [];
   for (const ch of text2) {
-    actions.push({ type: "keyDown", value: ch }, { type: "keyUp", value: ch });
+    const value = ch === `
+` || ch === "\r" ? W3C_RETURN_KEY : ch;
+    actions.push({ type: "keyDown", value }, { type: "keyUp", value });
   }
   return [{ type: "key", id: "keyboard", actions }];
 }
@@ -17623,10 +17653,60 @@ async function typeText(browser, text2) {
   return "w3c";
 }
 
+// src/domains/devices/screenshot-retention.ts
+import { readdir as readdir2, stat as stat2, unlink } from "fs/promises";
+import { homedir as homedir6 } from "os";
+import { join as join7 } from "path";
+var SCREENSHOT_DIR = join7(homedir6(), ".yoqa", "runs", "screenshots");
+var SHOT_FILE_RE = /^shot_\d+_[0-9a-f-]+\.png$/i;
+var DEFAULT_RETENTION_DAYS = 7;
+var DAY_MS = 24 * 60 * 60 * 1000;
+function selectScreenshotsForPruning(entries, options) {
+  if (options.maxAgeMs <= 0)
+    return [];
+  const cutoff = options.now - options.maxAgeMs;
+  return entries.filter((entry) => SHOT_FILE_RE.test(entry.name) && entry.mtimeMs < cutoff).map((entry) => entry.name);
+}
+function resolveScreenshotRetentionMs(env = process.env) {
+  const raw = env.YOQA_SCREENSHOT_RETENTION_DAYS;
+  if (raw === undefined)
+    return DEFAULT_RETENTION_DAYS * DAY_MS;
+  const days = Number(raw);
+  if (!Number.isFinite(days))
+    return DEFAULT_RETENTION_DAYS * DAY_MS;
+  return days * DAY_MS;
+}
+async function pruneOldRunScreenshots(options = {}) {
+  const maxAgeMs = options.maxAgeMs ?? resolveScreenshotRetentionMs();
+  if (maxAgeMs <= 0)
+    return { removed: 0 };
+  const dir = options.dir ?? SCREENSHOT_DIR;
+  try {
+    const names = (await readdir2(dir)).filter((name) => SHOT_FILE_RE.test(name));
+    const entries = [];
+    for (const name of names) {
+      const info = await stat2(join7(dir, name));
+      entries.push({ name, mtimeMs: info.mtimeMs });
+    }
+    let removed = 0;
+    for (const name of selectScreenshotsForPruning(entries, {
+      maxAgeMs,
+      now: options.now ?? Date.now()
+    })) {
+      try {
+        await unlink(join7(dir, name));
+        removed += 1;
+      } catch {}
+    }
+    return { removed };
+  } catch {
+    return { removed: 0 };
+  }
+}
+
 // src/domains/devices/session.ts
-var YOQA_ROOT4 = join7(homedir6(), ".yoqa");
+var YOQA_ROOT4 = join8(homedir7(), ".yoqa");
 var DEFAULT_MJPEG_PORT = Number(process.env.YOQA_MJPEG_PORT ?? "9100");
-var SCREENSHOT_DIR = join7(YOQA_ROOT4, "runs", "screenshots");
 var MJPEG_SETTINGS_BASE = {
   mjpegServerScreenshotQuality: 35,
   mjpegScalingFactor: 50
@@ -17744,7 +17824,7 @@ function looksLikePhysicalIosUdid(udid) {
 }
 var PHYSICAL_IOS_SESSION_TIMEOUT_MS = 60000;
 var SIMULATOR_WDA_SESSION_TIMEOUT_MS = 600000;
-var SIMULATOR_WDA_DERIVED_DATA = join7(YOQA_ROOT4, "wda-sim");
+var SIMULATOR_WDA_DERIVED_DATA = join8(YOQA_ROOT4, "wda-sim");
 function iosSessionCreateTimeoutMs(deviceId) {
   return looksLikePhysicalIosUdid(deviceId) ? PHYSICAL_IOS_SESSION_TIMEOUT_MS : SIMULATOR_WDA_SESSION_TIMEOUT_MS;
 }
@@ -18089,7 +18169,7 @@ async function createDeviceSession(options) {
   const screenshot = async () => {
     await mkdir3(SCREENSHOT_DIR, { recursive: true });
     const frame = await captureFrame();
-    const path = join7(SCREENSHOT_DIR, `shot_${Date.now()}_${crypto.randomUUID()}.png`);
+    const path = join8(SCREENSHOT_DIR, `shot_${Date.now()}_${crypto.randomUUID()}.png`);
     await Bun.write(path, Uint8Array.from(Buffer.from(frame.base64, "base64")));
     return { path, base64: frame.base64 };
   };
@@ -24284,6 +24364,7 @@ var catalogAppSchema = exports_external.object({
   name: exports_external.string().min(1),
   prefix: exports_external.string().min(1),
   context: exports_external.string(),
+  knowledge: exports_external.string(),
   iosBundleId: exports_external.string(),
   iosAppStoreId: exports_external.string(),
   androidApplicationId: exports_external.string(),
@@ -24299,6 +24380,7 @@ var updateAppRequestSchema = exports_external.object({
   name: exports_external.string().min(1).optional(),
   prefix: exports_external.string().min(1).optional(),
   context: exports_external.string().optional(),
+  knowledge: exports_external.string().optional(),
   iosBundleId: exports_external.string().optional(),
   iosAppStoreId: exports_external.string().optional(),
   androidApplicationId: exports_external.string().optional(),
@@ -24612,7 +24694,8 @@ var probeProviderResponseSchema = exports_external.object({
 var providerModelSchema = exports_external.object({
   id: exports_external.string().min(1),
   name: exports_external.string().min(1),
-  provider: exports_external.string().min(1).optional()
+  provider: exports_external.string().min(1).optional(),
+  vision: exports_external.boolean().optional()
 });
 var listProviderModelsResponseSchema = exports_external.object({
   models: exports_external.array(providerModelSchema),
@@ -24641,6 +24724,7 @@ var runExecutionModeSchema = exports_external.union([
   exports_external.literal("script"),
   exports_external.literal("agent")
 ]);
+var runScreenModeSchema = exports_external.union([exports_external.literal("vision"), exports_external.literal("tree")]);
 var createRunRequestSchema = exports_external.object({
   appId: exports_external.string().min(1),
   caseIds: exports_external.array(exports_external.string().min(1)).min(1),
@@ -24648,7 +24732,17 @@ var createRunRequestSchema = exports_external.object({
   platform: devicePlatformSchema,
   buildId: exports_external.string().min(1).optional(),
   buildPath: exports_external.string().min(1).optional(),
-  executionMode: runExecutionModeSchema.optional()
+  executionMode: runExecutionModeSchema.optional(),
+  screenMode: runScreenModeSchema.optional()
+});
+var stepPhasesSchema = exports_external.object({
+  captureMs: exports_external.number().nonnegative(),
+  screenMs: exports_external.number().nonnegative(),
+  prepareMs: exports_external.number().nonnegative(),
+  decideMs: exports_external.number().nonnegative(),
+  actionMs: exports_external.number().nonnegative(),
+  settleMs: exports_external.number().nonnegative(),
+  decideRetries: exports_external.number().int().nonnegative()
 });
 var runStepSchema = exports_external.object({
   id: exports_external.string().min(1),
@@ -24658,6 +24752,7 @@ var runStepSchema = exports_external.object({
   screenshotUri: exports_external.string().nullable(),
   ok: exports_external.boolean(),
   latencyMs: exports_external.number().nonnegative(),
+  phases: stepPhasesSchema.nullable().optional(),
   detail: exports_external.string().nullable(),
   command: exports_external.string().nullable().optional(),
   createdAt: exports_external.number().int().nonnegative()
@@ -24682,6 +24777,7 @@ var runSchema = exports_external.object({
   buildId: exports_external.string().nullable(),
   status: runStatusSchema,
   executionMode: runExecutionModeSchema,
+  screenMode: runScreenModeSchema.optional(),
   error: exports_external.string().nullable(),
   createdAt: exports_external.number().int().nonnegative(),
   startedAt: exports_external.number().int().nonnegative().nullable(),
@@ -24768,7 +24864,16 @@ var actionRequestSchema = exports_external.object({
   appId: exports_external.string().optional(),
   url: exports_external.string().optional(),
   alertAction: exports_external.union([exports_external.literal("accept"), exports_external.literal("dismiss")]).optional(),
-  seconds: exports_external.number().optional()
+  seconds: exports_external.number().optional(),
+  screenshot: exports_external.boolean().optional(),
+  settleMs: exports_external.number().int().min(0).max(1e4).optional()
+});
+var actionResultScreenshotSchema = exports_external.object({
+  path: exports_external.string().min(1),
+  annotatedPath: exports_external.string().min(1).optional(),
+  settled: exports_external.boolean(),
+  waitedMs: exports_external.number(),
+  changed: exports_external.boolean().nullable()
 });
 var actionResponseSchema = exports_external.object({
   ok: exports_external.literal(true),
@@ -24776,7 +24881,8 @@ var actionResponseSchema = exports_external.object({
   resolved: exports_external.object({
     x: exports_external.number().optional(),
     y: exports_external.number().optional()
-  }).optional()
+  }).optional(),
+  screenshot: actionResultScreenshotSchema.optional()
 });
 var yoqaStatusResponseSchema = exports_external.object({
   runner: exports_external.object({
@@ -25350,9 +25456,9 @@ function normalizeVisionJson(value) {
 
 // src/domains/providers/vision-model.ts
 import { mkdtemp as mkdtemp3, readFile as readFile2, rm as rm3, writeFile as writeFile3 } from "fs/promises";
-import { homedir as homedir7 } from "os";
+import { homedir as homedir8 } from "os";
 import { tmpdir as tmpdir3 } from "os";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 
 // ../../node_modules/@ai-sdk/gateway/node_modules/@ai-sdk/provider/dist/index.js
 var marker = "vercel.ai.error";
@@ -48024,9 +48130,9 @@ async function prepareVisionImage(pngBase64) {
   if (process.platform !== "darwin") {
     return { base64: pngBase64, mediaType: "image/png" };
   }
-  const dir = await mkdtemp3(join8(tmpdir3(), "yoqa-vision-"));
-  const inPath = join8(dir, "shot.png");
-  const outPath = join8(dir, "shot.jpg");
+  const dir = await mkdtemp3(join9(tmpdir3(), "yoqa-vision-"));
+  const inPath = join9(dir, "shot.png");
+  const outPath = join9(dir, "shot.jpg");
   try {
     await writeFile3(inPath, new Uint8Array(bytes));
     const proc = Bun.spawn([
@@ -48080,6 +48186,9 @@ function formatProviderHttpError(label, status, body) {
   if (label === "OpenCode" && status >= 500 && (body.includes("Internal server error") || body.includes('"type":"error"'))) {
     return `OpenCode Zen returned an internal error for this vision request. Many free models reject screenshots. In Settings \u2192 Provider, set the default model to ${EXAMPLE_OPENCODE_VISION_MODEL} (or another vision-capable model).`;
   }
+  if (label === "Groq" && status === 400 && (body.includes("invalid JSON schema for response_format") || body.includes("required") && body.includes("every key in properties"))) {
+    return "Groq rejected strict JSON schema mode for this model (response_format requires every key in properties). The runner already compensates with prompt JSON \u2014 retry the run; if it persists, pick a different Groq model in Settings \u2192 Provider.";
+  }
   return `${label} request failed (${status}): ${body.slice(0, 400)}`;
 }
 function isJsonRepairableError(error40) {
@@ -48134,7 +48243,7 @@ async function completeWithAiSdk(input) {
         model: input.model,
         schema: input.schema,
         system: input.system,
-        maxOutputTokens: VISION_MAX_TOKENS,
+        maxOutputTokens: input.maxOutputTokens ?? VISION_MAX_TOKENS,
         experimental_repairText: async ({ text: text3 }) => salvageAgentJsonText(text3),
         messages: [
           {
@@ -48172,6 +48281,7 @@ async function completeWithAiSdk(input) {
     if (!(error40 instanceof AgentProviderError) || !isJsonRepairableError(error40)) {
       throw error40;
     }
+    input.onDecideRetry?.();
     return run(`${input.prompt}
 
 ${JSON_REPAIR_PROMPT}`);
@@ -48181,7 +48291,7 @@ function createSdkVisionPort(opts) {
   return {
     async completeObject(input) {
       const modelId = input.auth.defaultModel?.trim() || opts.defaultModel;
-      const image = await prepareVisionImage(input.imageBase64);
+      const image = input.image ?? await prepareVisionImage(input.imageBase64);
       const model = await opts.createModel(input.auth, modelId);
       return completeWithAiSdk({
         label: opts.label,
@@ -48189,7 +48299,9 @@ function createSdkVisionPort(opts) {
         schema: input.schema,
         system: input.system,
         prompt: input.prompt,
-        image
+        image,
+        onDecideRetry: input.onDecideRetry,
+        maxOutputTokens: opts.maxOutputTokens
       });
     }
   };
@@ -48201,8 +48313,8 @@ function openCodeAuthPaths() {
   const paths = [];
   const xdg = process.env.XDG_DATA_HOME?.trim();
   if (xdg)
-    paths.push(join8(xdg, "opencode", "auth.json"));
-  paths.push(join8(homedir7(), ".local", "share", "opencode", "auth.json"));
+    paths.push(join9(xdg, "opencode", "auth.json"));
+  paths.push(join9(homedir8(), ".local", "share", "opencode", "auth.json"));
   return paths;
 }
 function apiKeyFromOpenCodeAuthEntry(value) {
@@ -48295,6 +48407,64 @@ function resolveGoogleKey(auth) {
 function resolveVertexApiKey(auth) {
   return auth.apiKey?.trim() || auth.env.GOOGLE_VERTEX_API_KEY?.trim() || process.env.GOOGLE_VERTEX_API_KEY?.trim() || null;
 }
+function isSparseResponseFormatBody(parsedBody) {
+  const format = parsedBody.response_format;
+  if (!format || typeof format !== "object" || Array.isArray(format))
+    return false;
+  const jsonSchema3 = format.json_schema;
+  if (!jsonSchema3 || typeof jsonSchema3 !== "object" || Array.isArray(jsonSchema3)) {
+    return false;
+  }
+  const schema = jsonSchema3.schema;
+  if (!schema || typeof schema !== "object" || Array.isArray(schema))
+    return false;
+  const properties = schema.properties;
+  if (!properties || typeof properties !== "object" || Array.isArray(properties)) {
+    return false;
+  }
+  const keys = Object.keys(properties);
+  if (keys.length === 0)
+    return false;
+  const required2 = schema.required;
+  if (!Array.isArray(required2))
+    return true;
+  const requiredSet = new Set(required2.filter((entry) => typeof entry === "string"));
+  return keys.some((key) => !requiredSet.has(key));
+}
+var GROQ_REASONING_MODEL_RE = /qwen3/i;
+function rewriteGroqRequestBody(rawBody) {
+  try {
+    const parsed = JSON.parse(rawBody);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return null;
+    const parsedBody = { ...parsed };
+    let mutated = false;
+    if (typeof parsedBody.model === "string" && GROQ_REASONING_MODEL_RE.test(parsedBody.model)) {
+      parsedBody.reasoning_effort = "none";
+      mutated = true;
+    }
+    if (isSparseResponseFormatBody(parsedBody)) {
+      const { response_format: _responseFormat, ...withoutFormat } = parsedBody;
+      return JSON.stringify(withoutFormat);
+    }
+    return mutated ? JSON.stringify(parsedBody) : null;
+  } catch {
+    return null;
+  }
+}
+function withGroqRequestHooks(opts) {
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  return async (input, init) => {
+    const headers = new Headers(init?.headers);
+    const requestInit = { ...init, headers };
+    if (typeof init?.body === "string") {
+      const rewrittenBody = rewriteGroqRequestBody(init.body);
+      if (rewrittenBody !== null)
+        requestInit.body = rewrittenBody;
+    }
+    return fetchImpl(input, requestInit);
+  };
+}
 function withOpenCodeRequestHooks(opts) {
   const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
   return async (input, init) => {
@@ -57355,8 +57525,8 @@ var anthropic = createAnthropic();
 // src/domains/providers/drivers/probe.ts
 import { constants } from "fs";
 import { access } from "fs/promises";
-import { homedir as homedir8 } from "os";
-import { isAbsolute, join as join9 } from "path";
+import { homedir as homedir9 } from "os";
+import { isAbsolute, join as join10 } from "path";
 async function pathExists3(path) {
   try {
     await access(path, constants.F_OK);
@@ -57381,13 +57551,13 @@ async function which2(binary) {
 `)[0]?.trim();
   return resolved || null;
 }
-function knownHomeBinCandidates(binaryName, home = homedir8()) {
+function knownHomeBinCandidates(binaryName, home = homedir9()) {
   return [
-    join9(home, ".opencode", "bin", binaryName),
-    join9(home, ".grok", "bin", binaryName),
-    join9(home, ".antigravity", "antigravity", "bin", binaryName),
-    join9(home, ".local", "bin", binaryName),
-    join9(home, ".bun", "bin", binaryName),
+    join10(home, ".opencode", "bin", binaryName),
+    join10(home, ".grok", "bin", binaryName),
+    join10(home, ".antigravity", "antigravity", "bin", binaryName),
+    join10(home, ".local", "bin", binaryName),
+    join10(home, ".bun", "bin", binaryName),
     `/opt/homebrew/bin/${binaryName}`,
     `/usr/local/bin/${binaryName}`
   ];
@@ -57620,7 +57790,7 @@ var anthropicDriver = {
 // src/domains/providers/drivers/antigravity-vision.ts
 import { mkdtemp as mkdtemp4, rm as rm4, writeFile as writeFile4 } from "fs/promises";
 import { tmpdir as tmpdir4 } from "os";
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 
 // ../../node_modules/@ai-sdk/google/node_modules/@ai-sdk/provider/dist/index.js
 var marker29 = "vercel.ai.error";
@@ -67093,11 +67263,11 @@ async function completeWithAgyCli(input, repairHint) {
   if (!resolved.path) {
     throw new AgentProviderError(resolved.detail || "Antigravity CLI (`agy`) not found. Install it or paste a Google AI Studio API key.");
   }
-  const image = await prepareVisionImage(input.imageBase64);
+  const image = input.image ?? await prepareVisionImage(input.imageBase64);
   const model = input.auth.defaultModel?.trim() || ANTIGRAVITY_DEFAULT_VISION_MODEL;
   const ext = image.mediaType === "image/jpeg" ? "jpg" : "png";
-  const dir = await mkdtemp4(join10(tmpdir4(), "yoqa-agy-"));
-  const shotPath = join10(dir, `shot.${ext}`);
+  const dir = await mkdtemp4(join11(tmpdir4(), "yoqa-agy-"));
+  const shotPath = join11(dir, `shot.${ext}`);
   try {
     await writeFile4(shotPath, new Uint8Array(Buffer.from(image.base64, "base64")));
     const userText = [
@@ -67148,7 +67318,7 @@ var antigravityVision = {
     if (apiKey) {
       const requested = input.auth.defaultModel?.trim() || ANTIGRAVITY_DEFAULT_VISION_MODEL;
       const googleModelId = requested.startsWith("gemini-1.") || requested.startsWith("gemini-2.") ? requested : "gemini-2.5-flash";
-      const image = await prepareVisionImage(input.imageBase64);
+      const image = input.image ?? await prepareVisionImage(input.imageBase64);
       const provider = createGoogle({ apiKey });
       return completeWithAiSdk({
         label: "Antigravity",
@@ -67156,7 +67326,8 @@ var antigravityVision = {
         schema: input.schema,
         system: input.system,
         prompt: input.prompt,
-        image
+        image,
+        onDecideRetry: input.onDecideRetry
       });
     }
     try {
@@ -67165,6 +67336,7 @@ var antigravityVision = {
       if (!(error40 instanceof AgentProviderError) || !isJsonRepairableError(error40)) {
         throw error40;
       }
+      input.onDecideRetry?.();
       return completeWithAgyCli(input, JSON_REPAIR_PROMPT2);
     }
   }
@@ -75611,7 +75783,7 @@ ${result.stderr}`.toLowerCase();
 // src/domains/providers/drivers/cursor-vision.ts
 import { mkdtemp as mkdtemp5, rm as rm5, writeFile as writeFile5 } from "fs/promises";
 import { tmpdir as tmpdir5 } from "os";
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 var CURSOR_DEFAULT_VISION_MODEL = "auto";
 var JSON_REPAIR_PROMPT3 = "Your previous reply was not valid JSON for this task. Reply again with ONLY one strict JSON object using double quotes for every key and string (no single quotes, no markdown, no prose).";
 function resolveCursorApiKey(auth) {
@@ -75624,8 +75796,8 @@ async function invokeCursorPrint(input) {
   }
   const model = input.auth.defaultModel?.trim() || CURSOR_DEFAULT_VISION_MODEL;
   const ext = input.mediaType === "image/jpeg" ? "jpg" : "png";
-  const dir = await mkdtemp5(join11(tmpdir5(), "yoqa-cursor-"));
-  const shotPath = join11(dir, `shot.${ext}`);
+  const dir = await mkdtemp5(join12(tmpdir5(), "yoqa-cursor-"));
+  const shotPath = join12(dir, `shot.${ext}`);
   const apiKey = resolveCursorApiKey(input.auth);
   try {
     await writeFile5(shotPath, new Uint8Array(Buffer.from(input.imageBase64, "base64")));
@@ -75668,7 +75840,7 @@ ${result.stderr}`.trim();
   }
 }
 async function completeOnce(input, repairHint) {
-  const image = await prepareVisionImage(input.imageBase64);
+  const image = input.image ?? await prepareVisionImage(input.imageBase64);
   const ext = image.mediaType === "image/jpeg" ? "jpg" : "png";
   const shotName = `shot.${ext}`;
   const userText = [
@@ -75707,6 +75879,7 @@ var cursorVision = {
       if (!(error40 instanceof AgentProviderError) || !isJsonRepairableError(error40)) {
         throw error40;
       }
+      input.onDecideRetry?.();
       return completeOnce(input, JSON_REPAIR_PROMPT3);
     }
   }
@@ -95598,6 +95771,18 @@ var groq = createGroq();
 
 // src/domains/providers/drivers/groq.ts
 var DEFAULT_BASE2 = "https://api.groq.com/openai/v1";
+var GROQ_VISION_MODEL_RE = /llama-4-(scout|maverick)/i;
+var GROQ_TEXT_ONLY_MODEL_RE = /^(qwen|deepseek|llama-3|gemma|mixtral|whisper|openai\/gpt-oss|compound-beta)/i;
+function groqModelVision(modelId) {
+  const id = modelId.trim();
+  if (!id)
+    return;
+  if (GROQ_VISION_MODEL_RE.test(id))
+    return true;
+  if (GROQ_TEXT_ONLY_MODEL_RE.test(id))
+    return false;
+  return;
+}
 var groqDriver = {
   kind: "groq",
   label: "Groq",
@@ -95610,13 +95795,14 @@ var groqDriver = {
   vision: createSdkVisionPort({
     label: "Groq",
     defaultModel: "meta-llama/llama-4-scout-17b-16e-instruct",
+    maxOutputTokens: 2048,
     createModel: (auth, modelId) => {
       const apiKey = resolveGroqKey(auth);
       if (!apiKey) {
         throw new AgentProviderError("Groq provider has no API key");
       }
       const baseURL = auth.baseUrl?.trim().replace(/\/$/, "") || DEFAULT_BASE2;
-      return createGroq({ apiKey, baseURL })(modelId);
+      return createGroq({ apiKey, baseURL, fetch: withGroqRequestHooks({}) })(modelId);
     }
   }),
   async probe() {
@@ -95657,7 +95843,10 @@ var groqDriver = {
       label: "Groq"
     });
     return {
-      models: (result.models ?? []).map((id) => ({ id, name: id })),
+      models: (result.models ?? []).map((id) => {
+        const vision = groqModelVision(id);
+        return { id, name: id, ...vision === undefined ? {} : { vision } };
+      }),
       message: result.ok ? `${result.models?.length ?? 0} models available` : result.message
     };
   }
@@ -95733,8 +95922,8 @@ var openaiDriver = {
 };
 
 // src/domains/providers/drivers/opencode-config.ts
-import { homedir as homedir9 } from "os";
-import { join as join12 } from "path";
+import { homedir as homedir10 } from "os";
+import { join as join13 } from "path";
 var OPENAI_COMPATIBLE_PACKAGES = new Set([
   "@ai-sdk/openai-compatible",
   "@ai-sdk/openai",
@@ -95762,8 +95951,8 @@ function openCodeConfigPaths() {
   const paths = [];
   const xdg = process.env.XDG_CONFIG_HOME?.trim();
   if (xdg)
-    paths.push(join12(xdg, "opencode", "opencode.json"));
-  paths.push(join12(homedir9(), ".config", "opencode", "opencode.json"));
+    paths.push(join13(xdg, "opencode", "opencode.json"));
+  paths.push(join13(homedir10(), ".config", "opencode", "opencode.json"));
   return paths;
 }
 function parseOpenCodeCompatibleProvider(config2, providerId) {
@@ -96221,6 +96410,348 @@ async function completeVision(auth, input) {
   return resolveVision(auth).completeObject({ ...input, auth });
 }
 
+// src/domains/runs/coord-grid.ts
+import { crc32, deflateSync, inflateSync } from "zlib";
+var PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+function pngChunk(type, data) {
+  const typeAndData = Buffer.concat([Buffer.from(type), data]);
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(typeAndData) >>> 0);
+  return Buffer.concat([length, typeAndData, crc]);
+}
+function encodeRgbaPng(image) {
+  const { width, height, rgba } = image;
+  const stride = width * 4;
+  const raw2 = Buffer.alloc(height * (1 + stride));
+  for (let y = 0;y < height; y++) {
+    const row = y * (1 + stride);
+    raw2[row] = 0;
+    Buffer.from(rgba.buffer, rgba.byteOffset + y * stride, stride).copy(raw2, row + 1);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  return Buffer.concat([
+    PNG_SIGNATURE,
+    pngChunk("IHDR", ihdr),
+    pngChunk("IDAT", deflateSync(raw2)),
+    pngChunk("IEND", Buffer.alloc(0))
+  ]);
+}
+function paeth(left, up, upLeft) {
+  const estimate = left + up - upLeft;
+  const leftDist = Math.abs(estimate - left);
+  const upDist = Math.abs(estimate - up);
+  const upLeftDist = Math.abs(estimate - upLeft);
+  if (leftDist <= upDist && leftDist <= upLeftDist)
+    return left;
+  if (upDist <= upLeftDist)
+    return up;
+  return upLeft;
+}
+function unfilter(raw2, height, stride, bpp) {
+  const out = Buffer.alloc(height * stride);
+  for (let y = 0;y < height; y++) {
+    const filter8 = raw2[y * (1 + stride)];
+    if (filter8 === undefined || filter8 > 4)
+      return null;
+    const src = y * (1 + stride) + 1;
+    const dst = y * stride;
+    for (let x = 0;x < stride; x++) {
+      const value = raw2[src + x] ?? 0;
+      const left = x >= bpp ? out[dst + x - bpp] ?? 0 : 0;
+      const up = y > 0 ? out[dst - stride + x] ?? 0 : 0;
+      const upLeft = y > 0 && x >= bpp ? out[dst - stride + x - bpp] ?? 0 : 0;
+      let recon = value;
+      if (filter8 === 1)
+        recon = value + left;
+      else if (filter8 === 2)
+        recon = value + up;
+      else if (filter8 === 3)
+        recon = value + Math.floor((left + up) / 2);
+      else if (filter8 === 4)
+        recon = value + paeth(left, up, upLeft);
+      out[dst + x] = recon & 255;
+    }
+  }
+  return out;
+}
+function decodePng(bytes) {
+  if (bytes.length < 8 || !bytes.subarray(0, 8).equals(PNG_SIGNATURE))
+    return null;
+  let width = 0;
+  let height = 0;
+  let colorType = -1;
+  const idat = [];
+  let offset = 8;
+  while (offset + 8 <= bytes.length) {
+    const length = bytes.readUInt32BE(offset);
+    const type = bytes.toString("ascii", offset + 4, offset + 8);
+    const start = offset + 8;
+    const end = start + length;
+    if (end + 4 > bytes.length)
+      return null;
+    const data = bytes.subarray(start, end);
+    if (type === "IHDR") {
+      if (data.length < 13)
+        return null;
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      if (data[8] !== 8 || data[12] !== 0)
+        return null;
+      colorType = data[9] ?? -1;
+    } else if (type === "IDAT") {
+      idat.push(Buffer.from(data));
+    } else if (type === "IEND") {
+      break;
+    }
+    offset = end + 4;
+  }
+  if (width < 1 || height < 1 || width > 8192 || height > 8192)
+    return null;
+  const bpp = colorType === 6 ? 4 : colorType === 2 ? 3 : 0;
+  if (bpp === 0)
+    return null;
+  let inflated;
+  try {
+    inflated = inflateSync(Buffer.concat(idat));
+  } catch {
+    return null;
+  }
+  const stride = width * bpp;
+  if (inflated.length < height * (1 + stride))
+    return null;
+  const raw2 = unfilter(inflated, height, stride, bpp);
+  if (!raw2)
+    return null;
+  const rgba = new Uint8Array(width * height * 4);
+  if (bpp === 4) {
+    rgba.set(raw2.subarray(0, rgba.length));
+  } else {
+    for (let i = 0;i < width * height; i++) {
+      rgba[i * 4] = raw2[i * 3] ?? 0;
+      rgba[i * 4 + 1] = raw2[i * 3 + 1] ?? 0;
+      rgba[i * 4 + 2] = raw2[i * 3 + 2] ?? 0;
+      rgba[i * 4 + 3] = 255;
+    }
+  }
+  return { width, height, rgba };
+}
+function paintMagenta(rgba, index) {
+  rgba[index] = 255;
+  rgba[index + 1] = 0;
+  rgba[index + 2] = 255;
+  rgba[index + 3] = 255;
+}
+var GLYPHS = {
+  "0": ["01110", "10001", "10001", "10001", "10001", "10001", "01110"],
+  "1": ["00100", "01100", "00100", "00100", "00100", "00100", "01110"],
+  "2": ["01110", "10001", "00001", "00110", "01000", "10000", "11111"],
+  "3": ["11110", "00001", "00001", "01110", "00001", "00001", "11110"],
+  "4": ["00010", "00110", "01010", "10010", "11111", "00010", "00010"],
+  "5": ["11111", "10000", "11110", "00001", "00001", "10001", "01110"],
+  "6": ["01110", "10000", "11110", "10001", "10001", "10001", "01110"],
+  "7": ["11111", "00001", "00010", "00100", "01000", "01000", "01000"],
+  "8": ["01110", "10001", "10001", "01110", "10001", "10001", "01110"],
+  "9": ["01110", "10001", "10001", "01111", "00001", "00001", "01110"],
+  "-": ["00000", "00000", "00000", "11111", "00000", "00000", "00000"]
+};
+var GRID_SLOT = [5, 15, 25, 35, 45, 55, 65, 75, 85, 95];
+function clampCell(value, max2) {
+  if (!Number.isFinite(value))
+    return 0;
+  return Math.min(max2, Math.max(0, Math.round(value)));
+}
+function pointFromGridCell(cell) {
+  const slot = (value) => {
+    if (value == null || !Number.isFinite(value))
+      return 50;
+    const rounded = Math.round(value);
+    if (rounded < 0 || rounded > 9)
+      return 50;
+    return GRID_SLOT[rounded] ?? 50;
+  };
+  const qx = slot(cell.qx);
+  const qy = slot(cell.qy);
+  return {
+    x: clampCell(cell.col, 9) * 100 + qx,
+    y: clampCell(cell.row, 9) * 100 + qy
+  };
+}
+function fillRect(rgba, width, height, x, y, w, h, color) {
+  const xEnd = Math.min(width, x + w);
+  const yEnd = Math.min(height, y + h);
+  for (let py = Math.max(0, y);py < yEnd; py++) {
+    for (let px = Math.max(0, x);px < xEnd; px++) {
+      const index = (py * width + px) * 4;
+      rgba[index] = color[0];
+      rgba[index + 1] = color[1];
+      rgba[index + 2] = color[2];
+      rgba[index + 3] = 255;
+    }
+  }
+}
+function paintGlyph(rgba, width, height, glyph, originX, originY, scale) {
+  for (let row = 0;row < glyph.length; row++) {
+    const bits = glyph[row] ?? "";
+    for (let col = 0;col < bits.length; col++) {
+      if (bits[col] !== "1")
+        continue;
+      for (let sy = 0;sy < scale; sy++) {
+        for (let sx = 0;sx < scale; sx++) {
+          const px = originX + col * scale + sx;
+          const py = originY + row * scale + sy;
+          if (px < 0 || py < 0 || px >= width || py >= height)
+            continue;
+          const index = (py * width + px) * 4;
+          rgba[index] = 255;
+          rgba[index + 1] = 255;
+          rgba[index + 2] = 255;
+          rgba[index + 3] = 255;
+        }
+      }
+    }
+  }
+}
+function paintCellLabels(image) {
+  const { width, height, rgba } = image;
+  const stroke = Math.max(2, Math.round(Math.min(width, height) / 200));
+  for (let col = 0;col < 10; col++) {
+    for (let row = 0;row < 10; row++) {
+      const x0 = Math.round(col / 10 * (width - 1));
+      const y0 = Math.round(row / 10 * (height - 1));
+      const x1 = Math.round((col + 1) / 10 * (width - 1));
+      const y1 = Math.round((row + 1) / 10 * (height - 1));
+      const scale = Math.floor(Math.min(x1 - x0, y1 - y0) / 24);
+      if (scale < 1)
+        continue;
+      const text3 = `${col}-${row}`;
+      const textW = text3.length * 5 + (text3.length - 1);
+      const boxW = (textW + 2) * scale;
+      const boxH = 9 * scale;
+      if (x0 + stroke + boxW >= x1 || y0 + stroke + boxH >= y1)
+        continue;
+      const originX = x0 + stroke;
+      const originY = y0 + stroke;
+      fillRect(rgba, width, height, originX, originY, boxW, boxH, [0, 0, 0]);
+      let cursor = originX + scale;
+      for (const char of text3) {
+        const glyph = GLYPHS[char];
+        if (glyph)
+          paintGlyph(rgba, width, height, glyph, cursor, originY + scale, scale);
+        cursor += 6 * scale;
+      }
+    }
+  }
+}
+function paintNormGrid(image) {
+  const { width, height, rgba } = image;
+  const stroke = Math.max(2, Math.round(Math.min(width, height) / 200));
+  const half = Math.floor(stroke / 2);
+  const paintColumn = (x) => {
+    for (let dx = -half;dx < stroke - half; dx++) {
+      const px = x + dx;
+      if (px < 0 || px >= width)
+        continue;
+      for (let y = 0;y < height; y++)
+        paintMagenta(rgba, (y * width + px) * 4);
+    }
+  };
+  const paintRow = (y) => {
+    for (let dy = -half;dy < stroke - half; dy++) {
+      const py = y + dy;
+      if (py < 0 || py >= height)
+        continue;
+      for (let x = 0;x < width; x++)
+        paintMagenta(rgba, (py * width + x) * 4);
+    }
+  };
+  for (let step = 1;step <= 9; step++) {
+    paintColumn(Math.round(step / 10 * (width - 1)));
+    paintRow(Math.round(step / 10 * (height - 1)));
+  }
+}
+function overlayCoordGrid(pngBase64) {
+  const bytes = Buffer.from(pngBase64, "base64");
+  const image = decodePng(bytes);
+  if (!image)
+    return null;
+  paintNormGrid(image);
+  paintCellLabels(image);
+  return encodeRgbaPng(image).toString("base64");
+}
+var MARK_RED = [255, 32, 32];
+var MARK_WHITE = [255, 255, 255];
+var MARK_GREEN = [0, 200, 80];
+function normToPx(norm, size) {
+  const clamped = Math.min(1000, Math.max(0, Number.isFinite(norm) ? norm : 0));
+  return Math.round(clamped / 1000 * (size - 1));
+}
+function paintRing(image, cx, cy, inner, outer, color) {
+  const { width, height, rgba } = image;
+  const outerSq = outer * outer;
+  const innerSq = inner * inner;
+  const reach = Math.ceil(outer);
+  for (let py = Math.max(0, cy - reach);py <= Math.min(height - 1, cy + reach); py++) {
+    for (let px = Math.max(0, cx - reach);px <= Math.min(width - 1, cx + reach); px++) {
+      const distSq = (px - cx) ** 2 + (py - cy) ** 2;
+      if (distSq > outerSq || distSq < innerSq)
+        continue;
+      const index = (py * width + px) * 4;
+      rgba[index] = color[0];
+      rgba[index + 1] = color[1];
+      rgba[index + 2] = color[2];
+      rgba[index + 3] = 255;
+    }
+  }
+}
+function paintThickLine(image, x0, y0, x1, y1, thickness, color) {
+  const steps = Math.max(Math.abs(x1 - x0), Math.abs(y1 - y0), 1);
+  const radius = Math.max(1, Math.floor(thickness / 2));
+  for (let step = 0;step <= steps; step++) {
+    const cx = Math.round(x0 + (x1 - x0) * step / steps);
+    const cy = Math.round(y0 + (y1 - y0) * step / steps);
+    paintRing(image, cx, cy, 0, radius, color);
+  }
+}
+function paintLandingMark(image, cx, cy, unit) {
+  const radius = unit * 4;
+  paintRing(image, cx, cy, radius, radius + unit * 2, MARK_WHITE);
+  paintRing(image, cx, cy, radius + unit * 0.5, radius + unit * 1.5, MARK_RED);
+  paintRing(image, cx, cy, 0, unit * 1.5, MARK_RED);
+}
+function paintActionMarks(image, marks) {
+  const unit = Math.max(2, Math.round(Math.min(image.width, image.height) / 200));
+  for (const mark of marks) {
+    const cx = normToPx(mark.x, image.width);
+    const cy = normToPx(mark.y, image.height);
+    if (mark.kind === "tap") {
+      paintLandingMark(image, cx, cy, unit);
+      continue;
+    }
+    const ex = normToPx(mark.x2, image.width);
+    const ey = normToPx(mark.y2, image.height);
+    paintThickLine(image, cx, cy, ex, ey, unit * 3, MARK_WHITE);
+    paintThickLine(image, cx, cy, ex, ey, unit, MARK_RED);
+    paintRing(image, cx, cy, 0, unit * 3, MARK_WHITE);
+    paintRing(image, cx, cy, 0, unit * 2, MARK_GREEN);
+    paintLandingMark(image, ex, ey, unit);
+  }
+}
+function overlayActionMarks(pngBase64, marks) {
+  if (marks.length === 0)
+    return null;
+  const image = decodePng(Buffer.from(pngBase64, "base64"));
+  if (!image)
+    return null;
+  paintActionMarks(image, marks);
+  return encodeRgbaPng(image).toString("base64");
+}
+
 // src/domains/runs/agent.ts
 var swipeDirectionSchema = exports_external.union([
   exports_external.literal("up"),
@@ -96251,6 +96782,14 @@ var agentDecisionSchema = exports_external.object({
   y: exports_external.number().optional(),
   x2: exports_external.number().optional(),
   y2: exports_external.number().optional(),
+  col: exports_external.number().optional(),
+  row: exports_external.number().optional(),
+  qx: exports_external.number().optional(),
+  qy: exports_external.number().optional(),
+  col2: exports_external.number().optional(),
+  row2: exports_external.number().optional(),
+  qx2: exports_external.number().optional(),
+  qy2: exports_external.number().optional(),
   direction: swipeDirectionSchema.optional(),
   durationMs: exports_external.number().optional(),
   double: exports_external.boolean().optional(),
@@ -96313,12 +96852,174 @@ var MAX_SCREEN_SNAPSHOT_ROWS = 80;
 function padNorm(n) {
   return String(Math.round(n)).padStart(4, " ");
 }
+function isFullBleedElement(element) {
+  return element.width >= 900 && element.height >= 900;
+}
+var GAME_APP_RE = /\b(this is a game|is a game|game app|mobile game|video game|unity|unreal|gameplay)\b/i;
+function isGameApp(appContext, appKnowledge) {
+  return GAME_APP_RE.test(`${appContext}
+${appKnowledge ?? ""}`);
+}
+var NO_TREE_SNAPSHOT = "(screenshot only \u2014 no accessibility tree is attached. Name the centre of the control on the screenshot.)";
+function isGameSurface(elements) {
+  if (elements.length === 0 || !elements.some((element) => isFullBleedElement(element))) {
+    return false;
+  }
+  return !elements.some((element) => {
+    if (isFullBleedElement(element))
+      return false;
+    return element.label.trim().length > 0 || Boolean(element.id?.trim());
+  });
+}
+function isCanvasScreen(elements) {
+  const namedSmall = elements.filter((element) => {
+    if (isFullBleedElement(element))
+      return false;
+    const named = element.label.trim().length > 0 || Boolean(element.id?.trim());
+    return named && element.width <= 800 && element.height <= 400;
+  });
+  return namedSmall.length < 3;
+}
+function releaseCanvasPoint(decision, elements) {
+  if (decision.x == null || decision.y == null || !decision.id)
+    return decision;
+  if (decision.type !== "tap" && decision.type !== "type" && decision.type !== "input") {
+    return decision;
+  }
+  const match2 = elements.find((element) => element.id === decision.id);
+  if (!match2 || !isFullBleedElement(match2))
+    return decision;
+  const { id: _fullBleedId, ...point } = decision;
+  return point;
+}
+var SNAP_RADIUS = 100;
+var TAPPABLE_ROLE_RE = /button|link|cell|switch|checkbox|radio|tab|toggle|textfield|searchfield|segment|menuitem|stepper|slider|picker/i;
+function isTappableElement(element) {
+  if (isFullBleedElement(element))
+    return false;
+  if (element.enabled === false || element.visible === false)
+    return false;
+  if (!element.label.trim() && !element.id?.trim())
+    return false;
+  return TAPPABLE_ROLE_RE.test(element.type);
+}
+function distanceToElement(element, x, y) {
+  const dx = Math.max(element.x - x, 0, x - (element.x + element.width));
+  const dy = Math.max(element.y - y, 0, y - (element.y + element.height));
+  return Math.hypot(dx, dy);
+}
+function snapTapToElement(decision, elements) {
+  const none = { decision, element: null };
+  if (decision.type !== "tap" || decision.x == null || decision.y == null)
+    return none;
+  if (decision.id || decision.label || decision.description)
+    return none;
+  let best = null;
+  for (const element2 of elements) {
+    if (!isTappableElement(element2))
+      continue;
+    const distance = distanceToElement(element2, decision.x, decision.y);
+    if (distance > SNAP_RADIUS)
+      continue;
+    const smaller = best != null && distance === best.distance && element2.width * element2.height < best.element.width * best.element.height;
+    if (best == null || distance < best.distance || smaller)
+      best = { element: element2, distance };
+  }
+  if (!best)
+    return none;
+  const { element } = best;
+  const id = element.id?.trim();
+  if (id && elements.filter((other) => other.id === element.id).length === 1) {
+    return { decision: { ...decision, id, label: element.label.trim() || undefined }, element };
+  }
+  return {
+    decision: {
+      ...decision,
+      x: Math.round(element.x + element.width / 2),
+      y: Math.round(element.y + element.height / 2)
+    },
+    element
+  };
+}
+function forceScreenshotTap(decision) {
+  if (decision.type !== "tap" && decision.type !== "type" && decision.type !== "input") {
+    return decision;
+  }
+  if (isSystemPermissionLabel(decision.label))
+    return decision;
+  const { id: _treeId, label: _treeLabel, ...point } = decision;
+  return point;
+}
+var SCREENSHOT_POINT_RETRY = "Send x and y (0\u20131000) for the centre of the control on the attached screenshot. Do not send id or label.";
+function screenshotPointMissing(decision) {
+  if (decision.type !== "tap")
+    return false;
+  if (isSystemPermissionLabel(decision.label))
+    return false;
+  if (decision.description)
+    return false;
+  return decision.x == null || decision.y == null;
+}
+function repeatTapHint(x, y, taps, mode) {
+  const where = `${Math.round(x)},${Math.round(y)}`;
+  const advice = mode === "tree" ? "A screen snapshot is attached this time: if it lists the control, tap it by its id instead of guessing a point. If it does not, trust the screenshot." : mode === "grid" ? "The control probably sits near the edge of the cell: pick the neighbouring cell, or qx/qy 0\u20131 or 8\u20139, so the point moves toward it." : "Re-read the screenshot and aim at the exact centre of the control; a small control such as a close X is easy to miss by a few percent.";
+  return `You tapped ${where} ${taps} times and the screen did not change, so that point is not on the control. Do not tap it again. ${advice}`;
+}
+function stuckWaitHint(waits) {
+  return `The screen has not changed after ${waits} waits. Stop waiting and act on what is visible in the screenshot; a system sheet or dialog may be waiting for a tap.`;
+}
+function namedGridIndex(value, max2) {
+  if (value == null || !Number.isFinite(value))
+    return null;
+  const rounded = Math.round(value);
+  if (rounded < 0 || rounded > max2)
+    return null;
+  return rounded;
+}
+var GRID_CELL_RETRY = "Send col and row (0\u20139) of the labeled cell that contains the centre of the control, and qx and qy (0\u20139) for where inside that cell it sits, in tenths of the cell. Do not send x or y.";
+function gridPointMissing(decision) {
+  if (decision.type !== "tap" && decision.type !== "type" && decision.type !== "input" && decision.type !== "drag") {
+    return false;
+  }
+  if (isSystemPermissionLabel(decision.label))
+    return false;
+  if (namedGridIndex(decision.col, 9) == null || namedGridIndex(decision.row, 9) == null) {
+    return true;
+  }
+  if (decision.type === "drag") {
+    return namedGridIndex(decision.col2, 9) == null || namedGridIndex(decision.row2, 9) == null;
+  }
+  return false;
+}
+function applyGridPoint(decision) {
+  if (decision.type !== "tap" && decision.type !== "type" && decision.type !== "input" && decision.type !== "drag" && decision.type !== "swipe") {
+    return decision;
+  }
+  const col = namedGridIndex(decision.col, 9);
+  const row = namedGridIndex(decision.row, 9);
+  if (col == null || row == null)
+    return decision;
+  const start = pointFromGridCell({ col, row, qx: decision.qx, qy: decision.qy });
+  const next = { ...decision, x: start.x, y: start.y };
+  const col2 = namedGridIndex(decision.col2, 9);
+  const row2 = namedGridIndex(decision.row2, 9);
+  if (col2 != null && row2 != null) {
+    const end = pointFromGridCell({ col: col2, row: row2, qx: decision.qx2, qy: decision.qy2 });
+    next.x2 = end.x;
+    next.y2 = end.y;
+  }
+  return next;
+}
 function formatScreenSnapshot(elements) {
   if (elements == null)
     return "(screen tree unavailable)";
   if (elements.length === 0)
     return "(empty tree)";
-  const ordered = [...elements].sort((a, b) => a.y - b.y || a.x - b.x);
+  const usable = elements.filter((element) => !isFullBleedElement(element));
+  if (usable.length === 0) {
+    return "(empty tree \u2014 full-screen canvas or game surface only. Ignore it. Use screenshot x,y for the centre of the control.)";
+  }
+  const ordered = [...usable].sort((a, b) => a.y - b.y || a.x - b.x);
   const shown = ordered.slice(0, MAX_SCREEN_SNAPSHOT_ROWS);
   const lines = shown.map((element) => {
     const id = element.id?.trim() ? ` id=${element.id.trim()}` : "";
@@ -96498,13 +97199,44 @@ function prefersScreenshotTap(decision) {
     return false;
   return decision.x != null && decision.y != null;
 }
-var SYSTEM_PROMPT = `You are a mobile QA agent controlling an app via screenshots.
-A screenshot of the current device screen is ALWAYS attached to the user message as an image. You can see it. Never claim that no screenshot was provided, missing, blank, or unavailable.
-
-Your entire reply MUST be a single strict JSON object (double quotes only \u2014 never single quotes) and nothing else \u2014 no markdown fences, no commentary before or after.
+var REPLY_FORMAT = `Your entire reply MUST be a single strict JSON object (double quotes only \u2014 never single quotes) and nothing else \u2014 no markdown fences, no commentary before or after.
 Every action MUST include:
 - "reason": one short sentence summarizing the action choice
-- "thoughts": 2\u20134 sentences describing what you see on screen and how that led to this action
+- "thoughts": 2\u20134 sentences describing what you see on screen and how that led to this action`;
+var APP_LIFECYCLE_SHAPES = `{"type":"activate-app","appId":"com.example.app","reason":"...","thoughts":"..."}
+{"type":"terminate-app","appId":"com.example.app","reason":"...","thoughts":"..."}
+{"type":"restart-app","appId":"com.example.app","reason":"...","thoughts":"..."}
+{"type":"background-app","seconds":3,"reason":"...","thoughts":"..."}
+{"type":"open-url","url":"https://example.com","reason":"...","thoughts":"..."}
+{"type":"assert","assertion":"visible|not-visible","text":"...","reason":"...","thoughts":"..."}
+{"type":"wait","ms":500-3000,"reason":"...","thoughts":"..."}
+{"type":"verify","reason":"...","thoughts":"..."}
+{"type":"done","reason":"...","thoughts":"..."}
+{"type":"fail","reason":"...","thoughts":"..."}`;
+var KEYBOARD_GUIDANCE = `Textfield input and keyboard handling:
+- Typing into a textfield brings up the virtual soft keyboard on the bottom of the screen (typically covering y ~ 550\u20131000), which may obscure buttons (like Submit, Login, Next) or lower inputs.
+- When typing inside a textfield or when the keyboard is open:
+  1. Dismiss keyboard by tapping away: Emit a tap on an empty, neutral background area outside textfields and above the keyboard (e.g. tap neutral header space or empty background) to dismiss the keyboard.
+  2. Nextline / Return on keyboard: Tap the Return / Done / Next / Search key on the virtual keyboard itself (using its x,y coordinates), or append "\\n" to your input text.
+  3. Dismiss then use app buttons: If an app button you need is obscured or covered by the soft keyboard, dismiss the keyboard first (by tapping away or pressing Return) so the button is revealed, then tap the app button on the subsequent step.`;
+var SWIPE_GUIDANCE = `Swipe direction is the FINGER movement (same as Inspector):
+- "down" (finger down, y 200\u2192800): scroll UP \u2014 reveal content above
+- "up" (finger up, y 800\u2192200): scroll DOWN \u2014 reveal content below / to the bottom
+- "left" / "right": horizontal paging
+When the case says "scroll up", emit direction "down". When it says "scroll down" or "to the bottom", emit direction "up". Never tap to scroll. Never emit wait as a stand-in for scrolling.`;
+var SHARED_RULES = `- activate-app / terminate-app / restart-app / open-url / background-app match yoqa action. Omit appId to use the catalog app id provided in the user message.
+- To scroll a list or page, emit swipe \u2014 never a tap in the middle of the screen as a stand-in for scrolling.
+- "Scroll until you cannot scroll anymore" / "to the bottom": keep emitting swipe (direction "up") until a later screenshot shows the same content. Then verify. Unchanged screens after taps do not count \u2014 taps do not scroll.
+- You are given ONE current instruction. Complete only that instruction, then return verify or done. Later instructions are hidden on purpose \u2014 do not invent, skip ahead, or combine them. Earlier finished instructions may be omitted \u2014 do not reconstruct them.
+- Do not open unrelated tabs or screens (Wallet, Profile, \u2026) unless the current instruction says to. If the current target is not visible, scroll THIS screen to find it. If it cannot be found, fail with what you see.
+- When THIS instruction's expected result is already visible, return verify or done. That finishes this instruction only, not the whole case. Otherwise return the next action. A separate verify check looks at the same screenshot after you decide.
+- Splash / loading / blank screens: return wait (do not tap imaginary tabs).
+- Do not repeat the same tap target from Recent actions unless the screenshot still shows you are on the wrong screen.
+- On fail, say what you see (e.g. "splash logo only, no bottom tabs") \u2014 never "no screenshot".`;
+var SYSTEM_PROMPT = `You are a mobile QA agent controlling an app using BOTH visual screenshots and screen snapshots (accessibility tree).
+A screenshot of the current device screen is ALWAYS attached to the user message as an image. You can see it. Never claim that no screenshot was provided, missing, blank, or unavailable.
+
+${REPLY_FORMAT}
 
 Valid shapes:
 {"type":"tap","label":"Allow","reason":"...","thoughts":"..."}
@@ -96519,45 +97251,63 @@ Valid shapes:
 {"type":"type","text":"...","x":0-1000,"y":0-1000,"reason":"...","thoughts":"..."}
 {"type":"input","text":"...","id":"email_field","reason":"...","thoughts":"..."}
 {"type":"alert","alertAction":"accept","reason":"...","thoughts":"..."}
-{"type":"activate-app","appId":"com.example.app","reason":"...","thoughts":"..."}
-{"type":"terminate-app","appId":"com.example.app","reason":"...","thoughts":"..."}
-{"type":"restart-app","appId":"com.example.app","reason":"...","thoughts":"..."}
-{"type":"background-app","seconds":3,"reason":"...","thoughts":"..."}
-{"type":"open-url","url":"https://example.com","reason":"...","thoughts":"..."}
-{"type":"assert","assertion":"visible|not-visible","text":"...","reason":"...","thoughts":"..."}
-{"type":"wait","ms":500-3000,"reason":"...","thoughts":"..."}
-{"type":"verify","reason":"...","thoughts":"..."}
-{"type":"done","reason":"...","thoughts":"..."}
-{"type":"fail","reason":"...","thoughts":"..."}
+${APP_LIFECYCLE_SHAPES}
 
 Coordinates use a 0\u20131000 normalized grid (0,0 top-left of the attached screenshot). The user message also includes a screen snapshot (cleaned accessibility tree) with the same grid \u2014 x,y is each element's TOP-LEFT, not centre. Centre = x + width/2, y + height/2.
 
 Use BOTH the screenshot and the screen snapshot:
-- Prefer snapshot "id=\u2026" when present (same as yoqa action tap --id).
+- Visual context (screenshot): Observe visual layout, colors, icons, canvas controls, modal overlays, and soft keyboard visibility.
+- Structural context (screen snapshot): Inspect accessibility ids ("id=..."), element boundaries, and text labels.
+- Decide whether to target by "id" or "x,y":
+  * Use "id" when the snapshot provides a clean, unique, and unambiguous identifier for the element.
+  * Use "x,y" coordinates (centre of the control on the screenshot grid) when controls lack IDs, are custom-drawn icons/canvas, or when coordinates are more direct and reliable than broad container IDs.
 - System permission / notification dialogs: {"type":"tap","label":"Allow"} or {"type":"alert","alertAction":"accept"}. Never guess coordinates for these.
-- For other in-app controls, tap screenshot x,y of the visible control if there is no id.
-- If the snapshot is empty or the control is only drawn (no label/id), use the screenshot.
 - If a previous action failed (see Last action error), pick a different target from the snapshot + screenshot \u2014 do not repeat the same id/label/point.
 
-Swipe direction is the FINGER movement (same as Inspector):
-- "down" (finger down, y 200\u2192800): scroll UP \u2014 reveal content above
-- "up" (finger up, y 800\u2192200): scroll DOWN \u2014 reveal content below / to the bottom
-- "left" / "right": horizontal paging
-When the case says "scroll up", emit direction "down". When it says "scroll down" or "to the bottom", emit direction "up". Never tap to scroll. Never emit wait as a stand-in for scrolling.
+${KEYBOARD_GUIDANCE}
+
+${SWIPE_GUIDANCE}
 
 Rules:
 - Look at the attached screenshot AND the screen snapshot before deciding.
 - Double-tap: {"type":"tap","double":true,...}. Long-press: {"type":"tap","durationMs":2000,...}. Drag a slider/chip with type drag, not swipe.
-- activate-app / terminate-app / restart-app / open-url / background-app match yoqa action. Omit appId to use the catalog app id provided in the user message.
 - Assert text on the tree with {"type":"assert","assertion":"visible","text":"\u2026"}.
-- To scroll a list or page, emit swipe \u2014 never a tap in the middle of the screen as a stand-in for scrolling.
-- "Scroll until you cannot scroll anymore" / "to the bottom": keep emitting swipe (direction "up") until a later screenshot shows the same content. Then verify. Unchanged screens after taps do not count \u2014 taps do not scroll.
-- You are given ONE current instruction. Complete only that instruction, then return verify or done. Later instructions are hidden on purpose \u2014 do not invent, skip ahead, or combine them.
-- Do not open unrelated tabs or screens (Wallet, Profile, \u2026) unless the current instruction says to. If the current target is not visible, scroll THIS screen to find it. If it cannot be found, fail with what you see.
-- When THIS instruction's expected result is visible (or the action is done and the UI has updated), return verify or done. That finishes this instruction only, not the whole case.
-- Splash / loading / blank screens: return wait (do not tap imaginary tabs).
-- Do not repeat the same tap target from Recent actions unless the screenshot still shows you are on the wrong screen.
-- On fail, say what you see (e.g. "splash logo only, no bottom tabs") \u2014 never "no screenshot".`;
+${SHARED_RULES}`;
+var VISION_SYSTEM_PROMPT = `You are a mobile QA agent controlling an app by looking at screenshots.
+A screenshot of the current device screen is ALWAYS attached to the user message as an image. You can see it. Never claim that no screenshot was provided, missing, blank, or unavailable. No accessibility tree is provided \u2014 decide from the screenshot alone.
+
+${REPLY_FORMAT}
+
+Valid shapes:
+{"type":"tap","x":0-1000,"y":0-1000,"reason":"...","thoughts":"..."}
+{"type":"tap","x":0-1000,"y":0-1000,"double":true,"reason":"...","thoughts":"..."}
+{"type":"tap","x":0-1000,"y":0-1000,"durationMs":2000,"reason":"...","thoughts":"..."}
+{"type":"tap","label":"Allow","reason":"...","thoughts":"..."}
+{"type":"swipe","direction":"up|down|left|right","reason":"...","thoughts":"..."}
+{"type":"swipe","x":0-1000,"y":0-1000,"x2":0-1000,"y2":0-1000,"reason":"...","thoughts":"..."}
+{"type":"drag","x":0-1000,"y":0-1000,"x2":0-1000,"y2":0-1000,"reason":"...","thoughts":"..."}
+{"type":"type","text":"...","x":0-1000,"y":0-1000,"reason":"...","thoughts":"..."}
+{"type":"alert","alertAction":"accept","reason":"...","thoughts":"..."}
+${APP_LIFECYCLE_SHAPES}
+
+Coordinates use a 0\u20131000 normalized grid over the attached screenshot (0,0 is the top-left corner, 1000,1000 the bottom-right). Send x,y for the CENTRE of the control you want to hit. Read it off the screenshot: a control's centre is halfway between its left and right edges, and halfway between its top and bottom edges.
+
+Targeting:
+- Tap with "x,y" on the screenshot. Do not send id \u2014 no ids are available. Do not send description.
+- System permission / notification dialogs: {"type":"tap","label":"Allow"} or {"type":"alert","alertAction":"accept"}. Never guess coordinates for these.
+- Visual context is all you have: read layout, colors, icons, canvas controls, modal overlays, and soft keyboard visibility from the screenshot.
+- If a previous action failed (see Last action error), pick a different point on the screenshot \u2014 do not repeat the same point.
+- If a magenta grid is drawn on the screenshot, each cell is labeled column-row in its top-left (0-0 through 9-9). Then send col, row, qx, and qy for the centre of the control, and do not send x or y. qx and qy are 0\u20139, tenths of the cell from its left and top (4 or 5 is the middle). A small control near a cell edge needs qx or qy near 0 or 9, so do not default to the middle. The tap point is computed from that cell.
+
+${KEYBOARD_GUIDANCE}
+
+${SWIPE_GUIDANCE}
+
+Rules:
+- Look at the attached screenshot before deciding.
+- Double-tap: {"type":"tap","double":true,...}. Long-press: {"type":"tap","durationMs":2000,...}. Drag a slider/chip with type drag, not swipe.
+- To check that text is on screen, emit {"type":"assert","assertion":"visible","text":"\u2026"} with the exact visible text.
+${SHARED_RULES}`;
 function formatRecentActions(actions) {
   if (actions.length === 0)
     return "(none \u2014 first step)";
@@ -96604,6 +97354,11 @@ function formatRecentActions(actions) {
 `);
 }
 var LIST_ITEM_START_RE = /^(?:\d+[.)]|\d+\s*[-\u2013]|[-*\u2022])\s+/;
+function continuesInstruction(rawLine, line) {
+  if (/^\s/.test(rawLine))
+    return true;
+  return /^[a-z]/.test(line);
+}
 function splitInstructionSteps(instructions) {
   const trimmed = instructions.replace(/\r\n/g, `
 `).trim();
@@ -96613,7 +97368,7 @@ function splitInstructionSteps(instructions) {
 `);
   const items = [];
   let current = [];
-  let sawList = false;
+  let sawSteps = false;
   const pushCurrent = () => {
     const text3 = current.join(" ").replace(/\s+/g, " ").trim();
     if (text3)
@@ -96622,12 +97377,21 @@ function splitInstructionSteps(instructions) {
   };
   for (const rawLine of lines) {
     const line = rawLine.trim();
-    if (!line)
+    if (!line) {
+      if (current.length > 0) {
+        sawSteps = true;
+        pushCurrent();
+      }
       continue;
+    }
     if (LIST_ITEM_START_RE.test(line)) {
-      sawList = true;
+      sawSteps = true;
       pushCurrent();
       current = [line.replace(LIST_ITEM_START_RE, "").trim()];
+    } else if (current.length > 0 && !continuesInstruction(rawLine, line)) {
+      sawSteps = true;
+      pushCurrent();
+      current = [line];
     } else if (current.length > 0) {
       current.push(line);
     } else {
@@ -96635,7 +97399,7 @@ function splitInstructionSteps(instructions) {
     }
   }
   pushCurrent();
-  if (!sawList)
+  if (!sawSteps)
     return [trimmed];
   return items.length > 0 ? items : [trimmed];
 }
@@ -96654,11 +97418,29 @@ function flattenCaseInstructions(flows2) {
   }
   return queue.length > 0 ? queue : [{ instructions: "", expectedResult: "" }];
 }
+var MAX_COMPLETED_IN_PROMPT = 3;
 function formatCompletedInstructions(completed) {
   if (completed.length === 0)
     return "(none \u2014 this is the first instruction)";
-  return completed.map((text3, index) => `${index + 1}. ${text3}`).join(`
+  const omitted = Math.max(0, completed.length - MAX_COMPLETED_IN_PROMPT);
+  const tail2 = completed.slice(-MAX_COMPLETED_IN_PROMPT);
+  const lines = tail2.map((text3, index) => `${omitted + index + 1}. ${text3}`);
+  if (omitted === 0)
+    return lines.join(`
 `);
+  return `${omitted} earlier instructions already done (omitted \u2014 do not reconstruct or repeat them).
+${lines.join(`
+`)}`;
+}
+var MAX_APP_KNOWLEDGE_CHARS = 2048;
+function formatAppKnowledge(knowledge) {
+  const trimmed = (knowledge ?? "").trim();
+  if (!trimmed)
+    return null;
+  if (trimmed.length <= MAX_APP_KNOWLEDGE_CHARS)
+    return trimmed;
+  return `${trimmed.slice(0, MAX_APP_KNOWLEDGE_CHARS)}
+\u2026 (app knowledge truncated at ${MAX_APP_KNOWLEDGE_CHARS} characters)`;
 }
 function formatDecidePrompt(input) {
   const ordinal = input.instructionOrdinal ?? input.stepIndex + 1;
@@ -96667,8 +97449,13 @@ function formatDecidePrompt(input) {
   const expected = input.expectedResult.trim() ? input.expectedResult : "(none for this instruction \u2014 return verify once you have performed it and the UI has updated)";
   const progress = total > 0 ? `Instruction ${ordinal} of ${total} \u2014 do ONLY this instruction${remaining > 0 ? `; ${remaining} remain after it` : " (last instruction)"}` : `Step ${input.stepIndex + 1}`;
   const later = remaining > 0 ? `Later instructions exist (${remaining}) but are hidden. Do not invent or perform them. Do not open unrelated screens to skip ahead.` : "This is the last instruction of the case.";
+  const appKnowledge = formatAppKnowledge(input.appKnowledge);
   return [
     `App context: ${input.appContext || "(none)"}`,
+    ...appKnowledge ? [
+      `App knowledge (notes your team keeps about this app \u2014 trust these over guesses):
+${appKnowledge}`
+    ] : [],
     `Test case: ${input.caseTitle}`,
     progress,
     "Completed instructions (already done \u2014 do not repeat):",
@@ -96680,9 +97467,19 @@ function formatDecidePrompt(input) {
     `Recent actions:
 ${formatRecentActions(input.recentActions ?? [])}`,
     `Last action error: ${input.lastError || "(none)"}`,
-    "Screen snapshot (cleaned accessibility tree, 0\u20131000 grid, x,y is top-left):",
-    input.screenSnapshot || "(unavailable)",
-    "Look at the attached screenshot image AND the screen snapshot and decide the next action. A screenshot is attached.",
+    ...input.screenshotOnly ? [
+      "No accessibility tree is attached. The attached screenshot was taken first and is all you have.",
+      "Name the centre of the control on that screenshot as x,y (0\u20131000). Do not send id. Send label only for a system permission or notification button."
+    ] : [
+      "The screenshot is the ground truth. The tree below can miss a system sheet or dialog that covers the app, and can describe the screen underneath it. If they disagree, trust the screenshot.",
+      "Screen snapshot (cleaned accessibility tree, 0\u20131000 grid, x,y is top-left):",
+      input.screenSnapshot || "(unavailable)",
+      "Look at the attached screenshot image AND the screen snapshot and decide the next action. Decide whether to use x,y coordinates or an id based on both sources. A screenshot is attached."
+    ],
+    ...input.coordGrid ? [
+      "A magenta grid is drawn on the screenshot. Each cell is labeled in its top-left corner as column-row (0-0 is the top-left cell, 9-9 is the bottom-right). Do not send x or y. Send col and row (0\u20139) of the cell that contains the centre of the control, and qx and qy (0\u20139) for where inside that cell the centre sits, in tenths of the cell: 0 is the left or top edge, 4 or 5 is the middle, 9 is the right or bottom edge. A small control near a cell edge needs qx or qy near 0 or 9, so do not default to the middle. The tap point is computed from those values. For a drag, also send col2, row2, qx2, and qy2 for the end."
+    ] : [],
+    `Again, do ONLY this: ${input.instructions || "(none)"}`,
     'Reply with ONLY the JSON action object, including non-empty "reason" and "thoughts".'
   ].join(`
 `);
@@ -96693,12 +97490,51 @@ function isAbsurdNoScreenshotFail(decision) {
   const text3 = `${decision.reason} ${decision.thoughts}`.toLowerCase();
   return text3.includes("no screenshot") || text3.includes("screenshot provided") || text3.includes("screenshot was not") || text3.includes("without a screenshot") || text3.includes("missing screenshot") || text3.includes("screenshot unavailable") || text3.includes("cannot see the screen") || text3.includes("no image");
 }
+var VERIFY_PROMPT = `You check whether ONE mobile test instruction is already satisfied.
+A screenshot of the device AFTER the last action is attached. You can see it.
+Reply with ONLY one JSON object: {"type":"verify"|"continue"|"fail","reason":"...","thoughts":"..."}
+- verify: the current instruction's expected result is visible, or the instruction has clearly been performed.
+- continue: the instruction is not finished. Do not invent the next tap.
+- fail: the instruction cannot be completed from what is on screen.
+Do not propose coordinates. Do not skip ahead to later instructions.`;
+function formatVerifyPrompt(input) {
+  const ordinal = input.instructionOrdinal ?? 1;
+  const total = input.instructionCount ?? 0;
+  const progress = total > 0 ? `Instruction ${ordinal} of ${total}.` : "";
+  const expected = input.expectedResult.trim() ? input.expectedResult : "(none \u2014 verify once this instruction has been performed and the UI has updated)";
+  return [
+    `Test case: ${input.caseTitle}`,
+    progress,
+    `Instruction to verify: ${input.instructions || "(none)"}`,
+    `Expected result: ${expected}`,
+    "Look at the attached screenshot. Is this instruction satisfied now?"
+  ].filter((line) => line.length > 0).join(`
+`);
+}
+async function verifyInstruction(input) {
+  const verdictSchema = exports_external.object({
+    type: exports_external.union([exports_external.literal("verify"), exports_external.literal("continue"), exports_external.literal("fail")]),
+    reason: exports_external.string().min(1),
+    thoughts: exports_external.string().min(1)
+  });
+  const object3 = await completeVision(input.auth, {
+    schema: verdictSchema,
+    system: VERIFY_PROMPT,
+    prompt: formatVerifyPrompt(input),
+    imageBase64: input.imageBase64,
+    image: input.image,
+    onDecideRetry: input.onDecideRetry
+  });
+  return object3;
+}
 async function decideNextAction(input) {
   return completeVision(input.auth, {
     schema: agentDecisionSchema,
-    system: SYSTEM_PROMPT,
+    system: input.screenshotOnly ? VISION_SYSTEM_PROMPT : SYSTEM_PROMPT,
     prompt: formatDecidePrompt(input),
-    imageBase64: input.imageBase64
+    imageBase64: input.imageBase64,
+    image: input.image,
+    onDecideRetry: input.onDecideRetry
   });
 }
 
@@ -96865,6 +97701,7 @@ function mapApp(row) {
     name: row.name,
     prefix: row.prefix || row.id,
     context: row.context,
+    knowledge: row.knowledge,
     iosBundleId: row.iosBundleId,
     iosAppStoreId: row.iosAppStoreId,
     androidApplicationId: row.androidApplicationId,
@@ -97050,6 +97887,7 @@ async function createApp(input) {
     name: name30,
     prefix,
     context: "",
+    knowledge: "",
     iosBundleId: "",
     iosAppStoreId: "",
     androidApplicationId: "",
@@ -97063,6 +97901,7 @@ async function createApp(input) {
   }
   return created;
 }
+var MAX_APP_KNOWLEDGE_CHARS2 = 2048;
 async function updateApp(appId, input) {
   const db = getCatalogDb();
   const existing = await db.query.apps.findFirst({ where: eq(apps.id, appId) });
@@ -97073,11 +97912,15 @@ async function updateApp(appId, input) {
   if (!name30) {
     throw new CatalogValidationError("Application name is required");
   }
+  if (input.knowledge !== undefined && input.knowledge.length > MAX_APP_KNOWLEDGE_CHARS2) {
+    throw new CatalogValidationError(`App knowledge must be at most ${MAX_APP_KNOWLEDGE_CHARS2} characters`);
+  }
   const prefix = input.prefix !== undefined ? await allocatePrefix(input.prefix.trim() || name30, appId) : existing.prefix || await allocatePrefix(name30, appId);
   await db.update(apps).set({
     name: name30,
     prefix,
     context: input.context ?? existing.context,
+    knowledge: input.knowledge ?? existing.knowledge,
     iosBundleId: input.iosBundleId ?? existing.iosBundleId,
     iosAppStoreId: input.iosAppStoreId ?? existing.iosAppStoreId,
     androidApplicationId: input.androidApplicationId ?? existing.androidApplicationId,
@@ -97607,8 +98450,8 @@ function createDevicesRoutes() {
 }
 
 // src/domains/doctor/application.ts
-import { homedir as homedir10 } from "os";
-import { join as join13 } from "path";
+import { homedir as homedir11 } from "os";
+import { join as join14 } from "path";
 async function runCommand5(command, options) {
   ensureHostToolPath();
   try {
@@ -97694,7 +98537,7 @@ async function probeJava() {
   let detail = javaBin ?? "java not on PATH";
   if (javaHome)
     detail = `JAVA_HOME=${javaHome}`;
-  else if (await Bun.file(join13(studioJbr, "bin/java")).exists()) {
+  else if (await Bun.file(join14(studioJbr, "bin/java")).exists()) {
     detail = `Android Studio JBR available at ${studioJbr} (JAVA_HOME unset)`;
   }
   const ok = Boolean(javaBin || javaHome);
@@ -97725,7 +98568,7 @@ async function probeXcodeSelect() {
   };
 }
 async function probeAdbDevices() {
-  const adb = await which3("adb") ?? join13(homedir10(), "Library/Android/sdk/platform-tools/adb");
+  const adb = await which3("adb") ?? join14(homedir11(), "Library/Android/sdk/platform-tools/adb");
   if (!await Bun.file(adb).exists() && !await which3("adb")) {
     return {
       id: "adb-devices",
@@ -97926,10 +98769,10 @@ import {
   randomBytes
 } from "crypto";
 import { chmodSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, writeFileSync } from "fs";
-import { homedir as homedir11 } from "os";
-import { dirname as dirname3, join as join14 } from "path";
-var YOQA_ROOT5 = join14(homedir11(), ".yoqa");
-var KEY_PATH = join14(YOQA_ROOT5, ".provider-key");
+import { homedir as homedir12 } from "os";
+import { dirname as dirname3, join as join15 } from "path";
+var YOQA_ROOT5 = join15(homedir12(), ".yoqa");
+var KEY_PATH = join15(YOQA_ROOT5, ".provider-key");
 var ALGORITHM = "aes-256-gcm";
 var IV_LENGTH = 12;
 var KEY_LENGTH = 32;
@@ -98721,13 +99564,12 @@ class ActionNotFoundError extends Error {
     this.name = "ActionNotFoundError";
   }
 }
-async function performAction(session, body) {
+async function performAction(session, body, options) {
   const locatorTap = Boolean((body.id || body.label) && (body.kind === "tap" || body.kind === "input"));
   let x = body.x;
   let y = body.y;
   if (locatorTap) {
-    const screen = await getScreen(session, { full: false });
-    const elements = screen.elements ?? [];
+    const elements = options?.screenElements ?? (await getScreen(session, { full: false })).elements ?? [];
     const match2 = body.id ? findElementById(elements, body.id) : findElementByLabel(elements, body.label ?? "");
     if (!match2) {
       throw new ActionNotFoundError(body.id ? `No element matching id: ${body.id}` : `No element matching label: ${body.label}`);
@@ -98827,6 +99669,11 @@ async function performAction(session, body) {
 // src/domains/runs/case-executor.ts
 var MAX_STEPS_PER_CASE = 25;
 var POST_ACTION_SETTLE_MS = 800;
+var GRID_ESCALATION_TAPS = 4;
+var TREE_ASSIST_ACTIONS = 2;
+var STUCK_WAITS = 3;
+var REPEAT_TAPS = 2;
+var REPEAT_TAP_RADIUS = 30;
 var defaultClock = {
   sleep: (ms) => new Promise((resolve7) => setTimeout(resolve7, ms)),
   now: () => Date.now()
@@ -98873,6 +99720,12 @@ async function runTextAssert(input) {
     await input.clock.sleep(400);
   }
 }
+function isPointTap(decision) {
+  return decision.type === "tap" && decision.x != null && decision.y != null && !isSystemPermissionLabel(decision.label);
+}
+function isDeviceDecision(decision) {
+  return decision.type !== "verify" && decision.type !== "done" && decision.type !== "fail";
+}
 function commandForDecision(decision, defaultAppId) {
   if (decision.type === "verify" || decision.type === "done" || decision.type === "fail") {
     return null;
@@ -99249,25 +100102,49 @@ async function executeAgentCase(deps) {
   let caseError = null;
   let lastScreenshotUri = null;
   const recordedDecisions = [];
+  let inFlightPhases = null;
+  let inFlightLatencyMs = 0;
   const decideOnce = async (input) => {
     const payload = {
       auth: deps.auth,
       appContext: deps.appContext,
+      appKnowledge: deps.appKnowledge,
       caseTitle: deps.catalogCase.name,
       instructions: input.flow.instructions,
       expectedResult: input.flow.expectedResult,
       stepIndex: stepIdx,
       imageBase64: input.imageBase64,
+      image: input.image,
       recentActions: input.recentActions,
       screenSnapshot: input.screenSnapshot,
       lastError: input.lastError,
       defaultAppId: deps.defaultAppId,
       completedInstructions: [...input.completedInstructions],
       instructionOrdinal: input.instructionOrdinal,
-      instructionCount: input.instructionCount
+      instructionCount: input.instructionCount,
+      coordGrid: input.coordGrid,
+      screenshotOnly: input.screenshotOnly,
+      onDecideRetry: input.onDecideRetry
+    };
+    const finish = (raw2) => {
+      let next = coerceScrollIntentToSwipe(raw2);
+      next = continueScrollingInsteadOfComplete({
+        decision: next,
+        instructions: input.flow.instructions,
+        expectedResult: input.flow.expectedResult,
+        recentActions: input.recentActions,
+        lastSwipeMovedScreen: input.lastSwipeMovedScreen
+      });
+      next = releaseCanvasPoint(next, input.screenElements);
+      if (input.screenshotOnly)
+        next = forceScreenshotTap(next);
+      if (input.coordGrid)
+        next = applyGridPoint(next);
+      return next;
     };
     let decision = await decide(payload);
     if (isAbsurdNoScreenshotFail(decision)) {
+      input.onDecideRetry?.();
       decision = await decide(payload);
       if (isAbsurdNoScreenshotFail(decision)) {
         decision = {
@@ -99277,23 +100154,29 @@ async function executeAgentCase(deps) {
         };
       }
     }
-    decision = coerceScrollIntentToSwipe(decision);
-    decision = continueScrollingInsteadOfComplete({
-      decision,
-      instructions: input.flow.instructions,
-      expectedResult: input.flow.expectedResult,
-      recentActions: input.recentActions,
-      lastSwipeMovedScreen: input.lastSwipeMovedScreen
-    });
+    decision = finish(decision);
+    if (input.coordGrid && gridPointMissing(decision)) {
+      input.onDecideRetry?.();
+      const retried = await decide({ ...payload, lastError: GRID_CELL_RETRY });
+      if (!isAbsurdNoScreenshotFail(retried))
+        decision = finish(retried);
+    } else if (input.screenshotOnly && !input.coordGrid && screenshotPointMissing(decision)) {
+      input.onDecideRetry?.();
+      const retried = await decide({ ...payload, lastError: SCREENSHOT_POINT_RETRY });
+      if (!isAbsurdNoScreenshotFail(retried))
+        decision = finish(retried);
+    }
     if ((decision.type === "activate-app" || decision.type === "terminate-app" || decision.type === "restart-app") && !decision.appId && deps.defaultAppId) {
       decision = { ...decision, appId: deps.defaultAppId };
     }
     return decision;
   };
-  const applyDecision = async (decision) => {
+  const applyDecision = async (decision, phases, screenElements) => {
     if (decision.type === "wait") {
       const waitMs = Math.min(3000, Math.max(500, decision.ms ?? 1500));
+      const waitStarted = clock.now();
       await clock.sleep(waitMs);
+      phases.actionMs += clock.now() - waitStarted;
       return "continue";
     }
     if (decision.type === "verify" || decision.type === "done") {
@@ -99305,6 +100188,7 @@ async function executeAgentCase(deps) {
     if (decision.type === "assert") {
       const assertion = decision.assertion === "not-visible" ? "not-visible" : "visible";
       const timeoutMs = Math.min(60000, Math.max(1000, decision.timeoutMs ?? 5000));
+      const assertStarted = clock.now();
       await runTextAssert({
         session: deps.session,
         readScreen: readScreen2,
@@ -99314,14 +100198,18 @@ async function executeAgentCase(deps) {
         text: decision.text ?? "",
         timeoutMs
       });
+      phases.actionMs += clock.now() - assertStarted;
       return "continue";
     }
     const body = decisionToActionRequest(decision, { defaultAppId: deps.defaultAppId });
     if (!body) {
       throw new Error(`${decision.type} is missing required fields`);
     }
+    const actionStarted = clock.now();
     try {
-      await perform(deps.session, body);
+      await perform(deps.session, body, {
+        screenElements: screenElements.length > 0 ? screenElements : undefined
+      });
     } catch (error40) {
       if (error40 instanceof ActionNotFoundError && (body.id || body.label) && decision.x != null && decision.y != null) {
         await perform(deps.session, {
@@ -99335,8 +100223,12 @@ async function executeAgentCase(deps) {
       } else {
         throw error40;
       }
+    } finally {
+      phases.actionMs += clock.now() - actionStarted;
     }
+    const settleStarted = clock.now();
     await clock.sleep(settleMs);
+    phases.settleMs += clock.now() - settleStarted;
     return "continue";
   };
   try {
@@ -99344,6 +100236,65 @@ async function executeAgentCase(deps) {
     const recentActions = [];
     const completedInstructions = [];
     let prevFingerprint = null;
+    let lastVision = null;
+    const screenMode = deps.screenMode ?? "vision";
+    const gameApp = isGameApp(deps.appContext, deps.appKnowledge);
+    let gridMode = gameApp;
+    let unchangedActions = 0;
+    let unchangedPointTaps = 0;
+    let unchangedWaits = 0;
+    let repeatTaps = 0;
+    let lastTapPoint = null;
+    const omitsTree = () => screenMode === "vision" || gridMode;
+    const verdictForDecision = async (decision, input) => {
+      if (decision.type === "fail") {
+        return { type: "fail", reason: decision.reason, thoughts: decision.thoughts };
+      }
+      if (decision.type === "verify" || decision.type === "done") {
+        return { type: "verify", reason: decision.reason, thoughts: decision.thoughts };
+      }
+      if (deps.verify) {
+        return deps.verify({
+          auth: deps.auth,
+          appContext: deps.appContext,
+          appKnowledge: deps.appKnowledge,
+          caseTitle: deps.catalogCase.name,
+          instructions: input.flow.instructions,
+          expectedResult: input.flow.expectedResult,
+          stepIndex: stepIdx,
+          imageBase64: input.imageBase64,
+          image: input.image,
+          recentActions: input.recentActions,
+          screenSnapshot: input.screenSnapshot,
+          lastError: input.lastError,
+          defaultAppId: deps.defaultAppId,
+          completedInstructions: [...input.completedInstructions],
+          instructionOrdinal: input.instructionOrdinal,
+          instructionCount: input.instructionCount,
+          coordGrid: input.coordGrid,
+          screenshotOnly: input.screenshotOnly,
+          onDecideRetry: input.onDecideRetry
+        });
+      }
+      if (deps.decide) {
+        return {
+          type: "continue",
+          reason: "Instruction still in progress",
+          thoughts: decision.thoughts
+        };
+      }
+      return verifyInstruction({
+        auth: deps.auth,
+        caseTitle: deps.catalogCase.name,
+        instructions: input.flow.instructions,
+        expectedResult: input.flow.expectedResult,
+        imageBase64: input.imageBase64,
+        image: input.image,
+        instructionOrdinal: input.instructionOrdinal,
+        instructionCount: input.instructionCount,
+        onDecideRetry: input.onDecideRetry
+      });
+    };
     for (let instructionIndex = 0;instructionIndex < instructionQueue.length; instructionIndex++) {
       const instruction = instructionQueue[instructionIndex];
       if (!instruction)
@@ -99353,17 +100304,158 @@ async function executeAgentCase(deps) {
         break;
       }
       let instructionDone = false;
+      let pending = null;
+      let pendingElements = [];
       for (let attempt = 0;attempt < maxSteps && !instructionDone; attempt++) {
         if (deps.isAborted()) {
           caseStatus = "cancelled";
           instructionDone = true;
           break;
         }
-        const shotStarted = clock.now();
+        const phases = {
+          captureMs: 0,
+          screenMs: 0,
+          prepareMs: 0,
+          decideMs: 0,
+          actionMs: 0,
+          settleMs: 0,
+          decideRetries: 0
+        };
+        let performed = null;
+        if (pending && isDeviceDecision(pending)) {
+          const command2 = commandForDecision(pending, deps.defaultAppId);
+          try {
+            await withCurrentCommand(setCurrentCommand, command2, async () => {
+              await applyDecision(pending, phases, pendingElements);
+            });
+            performed = pending;
+          } catch (error40) {
+            if (!isRetriableActionError(error40) || deps.isAborted())
+              throw error40;
+            const failed = pending;
+            const retryStarted = clock.now();
+            pending = await decideOnce({
+              flow: instruction,
+              imageBase64: lastVision?.imageBase64 ?? "",
+              image: lastVision?.image ?? { base64: "", mediaType: "image/png" },
+              recentActions: [...recentActions, failed],
+              screenSnapshot: lastVision?.screenSnapshot ?? "",
+              lastError: error40 instanceof Error ? error40.message : String(error40),
+              lastSwipeMovedScreen: false,
+              completedInstructions,
+              instructionOrdinal: instructionIndex + 1,
+              instructionCount: instructionQueue.length,
+              screenElements: pendingElements,
+              coordGrid: lastVision?.coordGrid ?? false,
+              screenshotOnly: lastVision?.screenshotOnly ?? omitsTree(),
+              onDecideRetry: () => {
+                phases.decideRetries += 1;
+              }
+            });
+            phases.decideMs += clock.now() - retryStarted;
+            if (!isDeviceDecision(pending)) {
+              performed = null;
+              const terminal = pending;
+              pending = null;
+              const outcome2 = terminal.type === "fail" ? "fail" : "done";
+              recentActions.push(terminal);
+              recordedDecisions.push(terminal);
+              await deps.appendStep({
+                idx: stepIdx,
+                action: {
+                  ...terminal,
+                  cycle: {
+                    action: failed,
+                    decision: terminal,
+                    verify: {
+                      type: outcome2 === "fail" ? "fail" : "verify",
+                      reason: terminal.reason,
+                      thoughts: terminal.thoughts
+                    }
+                  }
+                },
+                screenshotUri: lastScreenshotUri,
+                ok: outcome2 !== "fail",
+                latencyMs: clock.now() - retryStarted,
+                phases,
+                detail: terminal.reason,
+                command: commandForDecision(failed, deps.defaultAppId)
+              });
+              stepIdx += 1;
+              if (outcome2 === "fail") {
+                caseStatus = "errored";
+                caseError = terminal.reason ?? "Agent marked the instruction as failed";
+              } else {
+                completedInstructions.push(instruction.instructions);
+              }
+              instructionDone = true;
+              break;
+            }
+            const retryCommand = commandForDecision(pending, deps.defaultAppId);
+            await withCurrentCommand(setCurrentCommand, retryCommand, async () => {
+              await applyDecision(pending, phases, pendingElements);
+            });
+            recentActions.push(pending);
+            performed = pending;
+          }
+        }
+        let phaseStartedAt = clock.now();
+        const shotStarted = phaseStartedAt;
+        inFlightPhases = phases;
         const shot = await deps.session.screenshot();
         lastScreenshotUri = shot.path;
-        const tree = await readCleanedTree(readScreen2, deps.session);
+        const advance = (phase) => {
+          const now = clock.now();
+          phases[phase] = now - phaseStartedAt;
+          phaseStartedAt = now;
+        };
+        advance("captureMs");
         const fingerprint = screenshotFingerprint(shot.base64);
+        let escalatedToGrid = false;
+        if (screenMode === "vision" && !gridMode && performed) {
+          if (isPointTap(performed) && prevFingerprint != null && fingerprint === prevFingerprint) {
+            unchangedPointTaps += 1;
+          } else {
+            unchangedPointTaps = 0;
+          }
+          if (unchangedPointTaps >= GRID_ESCALATION_TAPS) {
+            gridMode = true;
+            escalatedToGrid = true;
+          }
+        }
+        if (performed && performed.type !== "wait") {
+          unchangedActions = prevFingerprint != null && fingerprint === prevFingerprint ? unchangedActions + 1 : 0;
+        }
+        const treeAssist = screenMode === "vision" && !gameApp && unchangedActions >= TREE_ASSIST_ACTIONS;
+        if (performed?.type === "wait") {
+          unchangedWaits = prevFingerprint != null && fingerprint === prevFingerprint ? unchangedWaits + 1 : 0;
+        } else if (performed) {
+          unchangedWaits = 0;
+        }
+        if (performed && isPointTap(performed)) {
+          const point = { x: performed.x, y: performed.y };
+          const unchanged = prevFingerprint != null && fingerprint === prevFingerprint;
+          const sameSpot = lastTapPoint != null && Math.hypot(point.x - lastTapPoint.x, point.y - lastTapPoint.y) <= REPEAT_TAP_RADIUS;
+          repeatTaps = unchanged ? sameSpot ? repeatTaps + 1 : 1 : 0;
+          lastTapPoint = point;
+        } else if (performed) {
+          repeatTaps = 0;
+          lastTapPoint = null;
+        }
+        let tree = omitsTree() && !treeAssist ? { snapshot: NO_TREE_SNAPSHOT, elements: [] } : await readCleanedTree(readScreen2, deps.session);
+        advance("screenMs");
+        const canvas = !omitsTree() && isCanvasScreen(tree.elements);
+        if ((!omitsTree() || treeAssist) && isGameSurface(tree.elements)) {
+          gridMode = true;
+          tree = { snapshot: NO_TREE_SNAPSHOT, elements: [] };
+        }
+        const assisted = treeAssist && tree.elements.length > 0;
+        const screenshotOnly = omitsTree() && !assisted;
+        const gridded = gridMode && !assisted || canvas ? overlayCoordGrid(shot.base64) : null;
+        const stallHint = unchangedWaits >= STUCK_WAITS ? stuckWaitHint(unchangedWaits) : repeatTaps >= REPEAT_TAPS && lastTapPoint ? repeatTapHint(lastTapPoint.x, lastTapPoint.y, repeatTaps, assisted ? "tree" : gridMode ? "grid" : "vision") : undefined;
+        const visionBase64 = gridded ?? shot.base64;
+        const image = await prepareVisionImage(visionBase64);
+        advance("prepareMs");
         const lastAction = recentActions.at(-1);
         const lastSwipeMovedScreen = lastAction?.type === "swipe" && prevFingerprint != null && fingerprint !== prevFingerprint;
         if (deps.isAborted()) {
@@ -99373,69 +100465,106 @@ async function executeAgentCase(deps) {
         }
         const decideInput = {
           flow: instruction,
-          imageBase64: shot.base64,
+          imageBase64: visionBase64,
+          image,
           recentActions,
           screenSnapshot: tree.snapshot,
+          lastError: stallHint,
           lastSwipeMovedScreen,
           completedInstructions,
           instructionOrdinal: instructionIndex + 1,
-          instructionCount: instructionQueue.length
+          instructionCount: instructionQueue.length,
+          screenElements: tree.elements,
+          coordGrid: gridded != null,
+          screenshotOnly,
+          onDecideRetry: () => {
+            phases.decideRetries += 1;
+          }
+        };
+        lastVision = {
+          imageBase64: visionBase64,
+          image,
+          screenSnapshot: tree.snapshot,
+          coordGrid: gridded != null,
+          screenshotOnly
         };
         let decision = await decideOnce(decideInput);
         prevFingerprint = fingerprint;
-        const latencyMs = clock.now() - shotStarted;
+        let snappedTo = null;
+        if (assisted) {
+          const snapped = snapTapToElement(decision, tree.elements);
+          decision = snapped.decision;
+          snappedTo = snapped.element;
+        }
+        let verdict = await verdictForDecision(decision, decideInput);
+        const guarded = continueScrollingInsteadOfComplete({
+          decision: {
+            type: "verify",
+            reason: verdict.reason,
+            thoughts: verdict.thoughts
+          },
+          instructions: instruction.instructions,
+          expectedResult: instruction.expectedResult,
+          recentActions,
+          lastSwipeMovedScreen
+        });
+        if (verdict.type === "verify" && guarded.type !== "verify" && guarded.type !== "done") {
+          verdict = {
+            type: "continue",
+            reason: guarded.reason,
+            thoughts: guarded.thoughts
+          };
+          if (!isDeviceDecision(decision))
+            decision = guarded;
+        }
+        advance("decideMs");
+        const latencyMs = phaseStartedAt - shotStarted;
+        inFlightLatencyMs = latencyMs;
         if (deps.isAborted()) {
           caseStatus = "cancelled";
           instructionDone = true;
           break;
         }
-        const applyWithRetry = async () => {
-          try {
-            return await applyDecision(decision);
-          } catch (error40) {
-            if (!isRetriableActionError(error40) || deps.isAborted())
-              throw error40;
-            const failed = decision;
-            decision = await decideOnce({
-              ...decideInput,
-              recentActions: [...recentActions, failed],
-              lastError: error40 instanceof Error ? error40.message : String(error40)
-            });
-            const retryCommand = commandForDecision(decision, deps.defaultAppId);
-            await setCurrentCommand(retryCommand);
-            return await applyDecision(decision);
-          }
-        };
-        const recordStep = async (command, outcome2) => {
-          recentActions.push(decision);
-          recordedDecisions.push(decision);
-          await deps.appendStep({
-            idx: stepIdx,
-            action: decision,
-            screenshotUri: shot.path,
-            ok: outcome2 !== "fail",
-            latencyMs,
-            detail: decision.type === "wait" ? decision.reason ?? `wait ${Math.min(3000, Math.max(500, decision.ms ?? 1500))}ms` : decision.reason ?? (outcome2 === "fail" ? "Agent failed the step" : null),
-            command
-          });
-        };
-        const initialCommand = commandForDecision(decision, deps.defaultAppId);
-        const outcome = initialCommand ? await withCurrentCommand(setCurrentCommand, initialCommand, async () => {
-          const result = await applyWithRetry();
-          await recordStep(commandForDecision(decision, deps.defaultAppId), result);
-          return result;
-        }) : await (async () => {
-          const result = await applyWithRetry();
-          await recordStep(null, result);
-          return result;
-        })();
+        const outcome = verdict.type === "fail" ? "fail" : verdict.type === "verify" ? "done" : "continue";
+        const command = commandForDecision(performed ?? decision, deps.defaultAppId);
+        recentActions.push(decision);
+        recordedDecisions.push(decision);
+        await deps.appendStep({
+          idx: stepIdx,
+          action: {
+            ...decision,
+            ...escalatedToGrid ? { escalatedToGrid: true } : {},
+            ...assisted ? { treeAssist: true } : {},
+            ...snappedTo ? { snappedTo: snappedTo.id?.trim() || snappedTo.label } : {},
+            cycle: {
+              action: performed,
+              decision,
+              verify: {
+                type: verdict.type,
+                reason: verdict.reason,
+                thoughts: verdict.thoughts
+              }
+            }
+          },
+          screenshotUri: shot.path,
+          ok: outcome !== "fail",
+          latencyMs,
+          phases,
+          detail: verdict.reason || (decision.type === "wait" ? decision.reason ?? `wait ${Math.min(3000, Math.max(500, decision.ms ?? 1500))}ms` : decision.reason ?? (outcome === "fail" ? "Agent failed the step" : null)),
+          command
+        });
         if (outcome === "done") {
           instructionDone = true;
           completedInstructions.push(instruction.instructions);
+          pending = null;
         } else if (outcome === "fail") {
           caseStatus = "errored";
-          caseError = decision.reason ?? "Agent marked the instruction as failed";
+          caseError = verdict.reason || decision.reason || "Agent marked the instruction as failed";
           instructionDone = true;
+          pending = null;
+        } else {
+          pending = isDeviceDecision(decision) ? decision : null;
+          pendingElements = tree.elements;
         }
         stepIdx += 1;
       }
@@ -99462,7 +100591,8 @@ async function executeAgentCase(deps) {
         },
         screenshotUri: lastScreenshotUri,
         ok: false,
-        latencyMs: 0,
+        latencyMs: inFlightLatencyMs,
+        phases: inFlightPhases,
         detail: caseError,
         command: null
       });
@@ -99504,6 +100634,15 @@ function parseAction(raw2) {
     return {};
   }
 }
+function parsePhases(raw2) {
+  if (!raw2)
+    return null;
+  try {
+    return stepPhasesSchema.parse(JSON.parse(raw2));
+  } catch {
+    return null;
+  }
+}
 function isAborted2(runId) {
   return runControls.get(runId)?.aborted === true;
 }
@@ -99523,6 +100662,9 @@ function parseRunExecutionMode(value) {
     return value;
   return "auto";
 }
+function parseRunScreenMode(value) {
+  return value === "vision" ? "vision" : "tree";
+}
 function resolveCaseExecutionMode(runMode, hasScript) {
   if (runMode === "agent")
     return "agent";
@@ -99547,6 +100689,7 @@ async function loadRun(runId) {
       screenshotUri: step.screenshotUri,
       ok: step.ok === 1,
       latencyMs: step.latencyMs,
+      phases: parsePhases(step.phasesJson),
       detail: step.detail,
       command: step.command ?? null,
       createdAt: step.createdAt
@@ -99573,6 +100716,7 @@ async function loadRun(runId) {
     buildId: runRow.buildId,
     status: runRow.status,
     executionMode: parseRunExecutionMode(runRow.executionMode),
+    screenMode: parseRunScreenMode(runRow.screenMode),
     error: runRow.error,
     createdAt: runRow.createdAt,
     startedAt: runRow.startedAt,
@@ -99590,6 +100734,7 @@ async function appendStep(input) {
     screenshotUri: input.screenshotUri,
     ok: input.ok ? 1 : 0,
     latencyMs: Math.max(0, Math.round(input.latencyMs)),
+    phasesJson: input.phases ? JSON.stringify(input.phases) : null,
     detail: input.detail,
     command: input.command,
     createdAt: Date.now()
@@ -99656,6 +100801,7 @@ async function executeAgentCase2(input) {
   return executeAgentCase({
     catalogCase,
     appContext: input.appContext,
+    appKnowledge: input.appKnowledge,
     auth: input.auth,
     session: input.session,
     isAborted: () => isAborted2(input.runId),
@@ -99669,6 +100815,7 @@ async function executeAgentCase2(input) {
       await setCurrentCommand(input.runTestId, command);
     },
     decide: decideNextAction,
+    screenMode: input.screenMode,
     clock: { sleep, now: () => Date.now() },
     defaultAppId: input.defaultAppId
   });
@@ -99710,8 +100857,10 @@ async function executeCase(input) {
       runTestId: input.runTestId,
       caseId: input.caseId,
       appContext: input.appContext,
+      appKnowledge: input.appKnowledge,
       session: input.session,
       auth: input.auth,
+      screenMode: input.screenMode,
       defaultAppId: input.defaultAppId
     });
     caseStatus = result.status;
@@ -99752,6 +100901,7 @@ async function executeRun(runId) {
     }
     const startedAt = Date.now();
     await db.update(runs).set({ status: "running", startedAt, error: null }).where(eq(runs.id, runId));
+    pruneOldRunScreenshots();
     if (isAborted2(runId)) {
       await persistCancelled(runId);
       return;
@@ -99822,9 +100972,11 @@ async function executeRun(runId) {
         runTestId: test.id,
         caseId: test.caseId,
         appContext: app.context,
+        appKnowledge: app.knowledge,
         session,
         auth,
         caseMode,
+        screenMode: run.screenMode ?? "tree",
         defaultAppId: run.platform === "ios" ? app.iosBundleId || undefined : app.androidApplicationId || undefined
       });
       if (status === "cancelled" || isAborted2(runId)) {
@@ -99889,6 +101041,7 @@ async function createRun(input) {
     throw new RunValidationError("App not found");
   }
   const executionMode = input.executionMode ?? "auto";
+  const screenMode = input.screenMode ?? "vision";
   const catalogCases = [];
   for (const caseId of uniqueCaseIds) {
     const catalogCase = await getCase(caseId);
@@ -99930,6 +101083,7 @@ async function createRun(input) {
     buildId,
     status: "queued",
     executionMode,
+    screenMode,
     error: null,
     createdAt: now,
     startedAt: null,
@@ -99999,6 +101153,7 @@ async function listRuns(appId) {
     buildId: runRow.buildId,
     status: runRow.status,
     executionMode: parseRunExecutionMode(runRow.executionMode),
+    screenMode: parseRunScreenMode(runRow.screenMode),
     error: runRow.error,
     createdAt: runRow.createdAt,
     startedAt: runRow.startedAt,
@@ -100233,8 +101388,84 @@ function createServersRoutes() {
 }
 
 // src/interfaces/http/session.ts
-import { mkdir as mkdir4, rename as rename2 } from "fs/promises";
+import { mkdir as mkdir5, rename as rename2 } from "fs/promises";
 import { dirname as dirname4 } from "path";
+
+// src/domains/devices/action-result.ts
+import { mkdir as mkdir4 } from "fs/promises";
+import { join as join16 } from "path";
+var DEFAULT_SETTLE_CAP_MS = 1500;
+var SETTLE_POLL_MS = 250;
+var realClock = { now: () => Date.now(), sleep: (ms) => Bun.sleep(ms) };
+function frameHash(base643) {
+  return String(Bun.hash(base643));
+}
+async function settleScreen(capture, options = {}) {
+  const capMs = options.capMs ?? DEFAULT_SETTLE_CAP_MS;
+  const pollMs = options.pollMs ?? SETTLE_POLL_MS;
+  const clock = options.clock ?? realClock;
+  const started = clock.now();
+  let latest;
+  let previousHash;
+  for (;; ) {
+    const elapsed = clock.now() - started;
+    if (latest !== undefined && elapsed >= capMs) {
+      return { base64: latest, settled: false, waitedMs: elapsed };
+    }
+    await clock.sleep(Math.max(0, Math.min(pollMs, capMs - elapsed)));
+    latest = (await capture()).base64;
+    const hash = frameHash(latest);
+    if (previousHash === hash) {
+      return { base64: latest, settled: true, waitedMs: clock.now() - started };
+    }
+    previousHash = hash;
+  }
+}
+function actionMarks(body, resolved) {
+  const x = resolved?.x ?? body.x;
+  const y = resolved?.y ?? body.y;
+  if (x == null || y == null)
+    return [];
+  if ((body.kind === "swipe" || body.kind === "drag") && body.x2 != null && body.y2 != null) {
+    return [{ kind: "path", x, y, x2: body.x2, y2: body.y2 }];
+  }
+  if (body.kind === "tap" || body.kind === "input")
+    return [{ kind: "tap", x, y }];
+  return [];
+}
+async function writePng(dir, base643, label) {
+  await mkdir4(dir, { recursive: true });
+  const path = join16(dir, `${label}_${Date.now()}_${crypto.randomUUID()}.png`);
+  await Bun.write(path, Uint8Array.from(Buffer.from(base643, "base64")));
+  return path;
+}
+async function performActionWithScreenshot(session, body, deps = {}) {
+  const perform = deps.perform ?? performAction;
+  const before = await session.captureFrame().then((frame) => frame.base64, () => {
+    return;
+  });
+  const response = await perform(session, body);
+  const settle = await settleScreen(() => session.captureFrame(), {
+    capMs: body.settleMs,
+    pollMs: deps.pollMs,
+    clock: deps.clock
+  });
+  const dir = deps.dir ?? SCREENSHOT_DIR;
+  const path = await writePng(dir, settle.base64, "result");
+  const marks = actionMarks(body, response.resolved);
+  const annotated = overlayActionMarks(settle.base64, marks);
+  const annotatedPath = annotated ? await writePng(dir, annotated, "result_marked") : undefined;
+  const screenshot = {
+    path,
+    ...annotatedPath ? { annotatedPath } : {},
+    settled: settle.settled,
+    waitedMs: settle.waitedMs,
+    changed: settle.settled && before !== undefined ? frameHash(before) !== frameHash(settle.base64) : null
+  };
+  return { ...response, screenshot };
+}
+
+// src/interfaces/http/session.ts
 function sessionErrorResponse(error40) {
   const message = error40 instanceof Error ? error40.message : String(error40);
   if (error40 instanceof SessionBusyError) {
@@ -100333,7 +101564,7 @@ function createSessionRoutes() {
       const shot = await session.screenshot();
       let path = shot.path;
       if (parsed.data.path) {
-        await mkdir4(dirname4(parsed.data.path), { recursive: true });
+        await mkdir5(dirname4(parsed.data.path), { recursive: true });
         await rename2(shot.path, parsed.data.path);
         path = parsed.data.path;
       }
@@ -100427,7 +101658,7 @@ function createSessionRoutes() {
           error: "A run is using this device session. Cancel the run to interact manually."
         }, 409);
       }
-      const result = await performAction(session, parsed.data);
+      const result = parsed.data.screenshot ? await performActionWithScreenshot(session, parsed.data) : await performAction(session, parsed.data);
       return c.json(actionResponseSchema.parse(result));
     } catch (error40) {
       const gone = sessionErrorResponse(error40);