@exodus/xqa 1.9.0 → 1.10.0

package/dist/xqa.cjs

@@ -1621,9 +1621,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (fn) {
           this._exitCallback = fn;
         } else {
-          this._exitCallback = (err18) => {
-            if (err18.code !== "commander.executeSubCommandAsync") {
-              throw err18;
+          this._exitCallback = (err19) => {
+            if (err19.code !== "commander.executeSubCommandAsync") {
+              throw err19;
             } else {
             }
           };
@@ -1699,12 +1699,12 @@ Expecting one of '${allowedValues.join("', '")}'`);
       _callParseArg(target, value, previous, invalidArgumentMessage) {
         try {
           return target.parseArg(value, previous);
-        } catch (err18) {
-          if (err18.code === "commander.invalidArgument") {
-            const message = `${invalidArgumentMessage} ${err18.message}`;
-            this.error(message, { exitCode: err18.exitCode, code: err18.code });
+        } catch (err19) {
+          if (err19.code === "commander.invalidArgument") {
+            const message = `${invalidArgumentMessage} ${err19.message}`;
+            this.error(message, { exitCode: err19.exitCode, code: err19.code });
           }
-          throw err18;
+          throw err19;
         }
       }
       /**
@@ -2293,14 +2293,14 @@ Expecting one of '${allowedValues.join("', '")}'`);
             );
           }
         });
-        proc.on("error", (err18) => {
-          if (err18.code === "ENOENT") {
+        proc.on("error", (err19) => {
+          if (err19.code === "ENOENT") {
             this._checkForMissingExecutable(
               executableFile,
               executableDir,
               subcommand._name
             );
-          } else if (err18.code === "EACCES") {
+          } else if (err19.code === "EACCES") {
             throw new Error(`'${executableFile}' not executable`);
           }
           if (!exitCallback) {
@@ -2311,7 +2311,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
               "commander.executeSubCommandAsync",
               "(error)"
             );
-            wrappedError.nestedError = err18;
+            wrappedError.nestedError = err19;
             exitCallback(wrappedError);
           }
         });
@@ -3728,8 +3728,8 @@ var require_index_cjs = __commonJS({
     function okAsync8(value) {
       return new ResultAsync12(Promise.resolve(new Ok(value)));
     }
-    function errAsync8(err19) {
-      return new ResultAsync12(Promise.resolve(new Err(err19)));
+    function errAsync8(err20) {
+      return new ResultAsync12(Promise.resolve(new Err(err20)));
     }
     var fromPromise = ResultAsync12.fromPromise;
     var fromSafePromise2 = ResultAsync12.fromSafePromise;
@@ -3738,7 +3738,7 @@ var require_index_cjs = __commonJS({
       let acc = ok19([]);
       for (const result of resultList) {
         if (result.isErr()) {
-          acc = err18(result.error);
+          acc = err19(result.error);
           break;
         } else {
           acc.map((list) => list.push(result.value));
@@ -3753,7 +3753,7 @@ var require_index_cjs = __commonJS({
         if (result.isErr() && acc.isErr()) {
           acc.error.push(result.error);
         } else if (result.isErr() && acc.isOk()) {
-          acc = err18([result.error]);
+          acc = err19([result.error]);
         } else if (result.isOk() && acc.isOk()) {
           acc.value.push(result.value);
         }
@@ -3763,17 +3763,17 @@ var require_index_cjs = __commonJS({
     var combineResultAsyncListWithAllErrors = (asyncResultList) => ResultAsync12.fromSafePromise(Promise.all(asyncResultList)).andThen(combineResultListWithAllErrors);
     exports2.Result = void 0;
     (function(Result3) {
-      function fromThrowable14(fn, errorFn) {
+      function fromThrowable16(fn, errorFn) {
         return (...args) => {
           try {
             const result = fn(...args);
             return ok19(result);
           } catch (e3) {
-            return err18(errorFn ? errorFn(e3) : e3);
+            return err19(errorFn ? errorFn(e3) : e3);
           }
         };
       }
-      Result3.fromThrowable = fromThrowable14;
+      Result3.fromThrowable = fromThrowable16;
       function combine(resultList) {
         return combineResultList(resultList);
       }
@@ -3786,8 +3786,8 @@ var require_index_cjs = __commonJS({
     function ok19(value) {
       return new Ok(value);
     }
-    function err18(err19) {
-      return new Err(err19);
+    function err19(err20) {
+      return new Err(err20);
     }
     function safeTry(body) {
       const n3 = body().next();
@@ -3882,27 +3882,27 @@ var require_index_cjs = __commonJS({
       }
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
       map(_f) {
-        return err18(this.error);
+        return err19(this.error);
       }
       mapErr(f6) {
-        return err18(f6(this.error));
+        return err19(f6(this.error));
       }
       andThrough(_f) {
-        return err18(this.error);
+        return err19(this.error);
       }
       andTee(_f) {
-        return err18(this.error);
+        return err19(this.error);
       }
       orTee(f6) {
         try {
           f6(this.error);
         } catch (e3) {
         }
-        return err18(this.error);
+        return err19(this.error);
       }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types
       andThen(_f) {
-        return err18(this.error);
+        return err19(this.error);
       }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types
       orElse(f6) {
@@ -3922,13 +3922,13 @@ var require_index_cjs = __commonJS({
       unwrapOr(v2) {
         return v2;
       }
-      match(_ok, err19) {
-        return err19(this.error);
+      match(_ok, err20) {
+        return err20(this.error);
       }
       safeUnwrap() {
         const error48 = this.error;
         return (function* () {
-          yield err18(error48);
+          yield err19(error48);
           throw new Error("Do not use this generator out of `safeTry`");
         })();
       }
@@ -3944,16 +3944,16 @@ var require_index_cjs = __commonJS({
         return self2;
       }
     };
-    var fromThrowable13 = exports2.Result.fromThrowable;
+    var fromThrowable15 = exports2.Result.fromThrowable;
     exports2.Err = Err;
     exports2.Ok = Ok;
     exports2.ResultAsync = ResultAsync12;
-    exports2.err = err18;
+    exports2.err = err19;
     exports2.errAsync = errAsync8;
     exports2.fromAsyncThrowable = fromAsyncThrowable10;
     exports2.fromPromise = fromPromise;
     exports2.fromSafePromise = fromSafePromise2;
-    exports2.fromThrowable = fromThrowable13;
+    exports2.fromThrowable = fromThrowable15;
     exports2.ok = ok19;
     exports2.okAsync = okAsync8;
     exports2.safeTry = safeTry;
@@ -11117,12 +11117,12 @@ var require_lib2 = __commonJS({
     var detectFile = (filepath, opts = {}) => new Promise((resolve, reject) => {
       let fd;
       const fs3 = (0, node_1.default)();
-      const handler = (err18, buffer) => {
+      const handler = (err19, buffer) => {
         if (fd) {
           fs3.closeSync(fd);
         }
-        if (err18) {
-          reject(err18);
+        if (err19) {
+          reject(err19);
         } else if (buffer) {
           resolve((0, exports2.detect)(buffer));
         } else {
@@ -11133,9 +11133,9 @@ var require_lib2 = __commonJS({
       if (sampleSize > 0) {
         fd = fs3.openSync(filepath, "r");
         let sample = Buffer.allocUnsafe(sampleSize);
-        fs3.read(fd, sample, 0, sampleSize, opts.offset, (err18, bytesRead) => {
-          if (err18) {
-            handler(err18, null);
+        fs3.read(fd, sample, 0, sampleSize, opts.offset, (err19, bytesRead) => {
+          if (err19) {
+            handler(err19, null);
           } else {
             if (bytesRead < sampleSize) {
               sample = sample.subarray(0, bytesRead);
@@ -15057,9 +15057,9 @@ var require_main = __commonJS({
       options.path = vaultPath;
       const result = DotenvModule.configDotenv(options);
       if (!result.parsed) {
-        const err18 = new Error(`MISSING_DATA: Cannot parse ${vaultPath} for an unknown reason`);
-        err18.code = "MISSING_DATA";
-        throw err18;
+        const err19 = new Error(`MISSING_DATA: Cannot parse ${vaultPath} for an unknown reason`);
+        err19.code = "MISSING_DATA";
+        throw err19;
       }
       const keys = _dotenvKey(options).split(",");
       const length = keys.length;
@@ -15102,30 +15102,30 @@ var require_main = __commonJS({
         uri = new URL(dotenvKey);
       } catch (error48) {
         if (error48.code === "ERR_INVALID_URL") {
-          const err18 = new Error("INVALID_DOTENV_KEY: Wrong format. Must be in valid uri format like dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=development");
-          err18.code = "INVALID_DOTENV_KEY";
-          throw err18;
+          const err19 = new Error("INVALID_DOTENV_KEY: Wrong format. Must be in valid uri format like dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=development");
+          err19.code = "INVALID_DOTENV_KEY";
+          throw err19;
         }
         throw error48;
       }
       const key = uri.password;
       if (!key) {
-        const err18 = new Error("INVALID_DOTENV_KEY: Missing key part");
-        err18.code = "INVALID_DOTENV_KEY";
-        throw err18;
+        const err19 = new Error("INVALID_DOTENV_KEY: Missing key part");
+        err19.code = "INVALID_DOTENV_KEY";
+        throw err19;
       }
       const environment = uri.searchParams.get("environment");
       if (!environment) {
-        const err18 = new Error("INVALID_DOTENV_KEY: Missing environment part");
-        err18.code = "INVALID_DOTENV_KEY";
-        throw err18;
+        const err19 = new Error("INVALID_DOTENV_KEY: Missing environment part");
+        err19.code = "INVALID_DOTENV_KEY";
+        throw err19;
       }
       const environmentKey = `DOTENV_VAULT_${environment.toUpperCase()}`;
       const ciphertext = result.parsed[environmentKey];
       if (!ciphertext) {
-        const err18 = new Error(`NOT_FOUND_DOTENV_ENVIRONMENT: Cannot locate environment ${environmentKey} in your .env.vault file.`);
-        err18.code = "NOT_FOUND_DOTENV_ENVIRONMENT";
-        throw err18;
+        const err19 = new Error(`NOT_FOUND_DOTENV_ENVIRONMENT: Cannot locate environment ${environmentKey} in your .env.vault file.`);
+        err19.code = "NOT_FOUND_DOTENV_ENVIRONMENT";
+        throw err19;
       }
       return { ciphertext, key };
     }
@@ -15255,13 +15255,13 @@ var require_main = __commonJS({
         const invalidKeyLength = error48.message === "Invalid key length";
         const decryptionFailed = error48.message === "Unsupported state or unable to authenticate data";
         if (isRange || invalidKeyLength) {
-          const err18 = new Error("INVALID_DOTENV_KEY: It must be 64 characters long (or more)");
-          err18.code = "INVALID_DOTENV_KEY";
-          throw err18;
+          const err19 = new Error("INVALID_DOTENV_KEY: It must be 64 characters long (or more)");
+          err19.code = "INVALID_DOTENV_KEY";
+          throw err19;
         } else if (decryptionFailed) {
-          const err18 = new Error("DECRYPTION_FAILED: Please check your DOTENV_KEY");
-          err18.code = "DECRYPTION_FAILED";
-          throw err18;
+          const err19 = new Error("DECRYPTION_FAILED: Please check your DOTENV_KEY");
+          err19.code = "DECRYPTION_FAILED";
+          throw err19;
         } else {
           throw error48;
         }
@@ -15271,9 +15271,9 @@ var require_main = __commonJS({
       const debug = Boolean(options && options.debug);
       const override = Boolean(options && options.override);
       if (typeof parsed !== "object") {
-        const err18 = new Error("OBJECT_REQUIRED: Please check the processEnv argument being passed to populate");
-        err18.code = "OBJECT_REQUIRED";
-        throw err18;
+        const err19 = new Error("OBJECT_REQUIRED: Please check the processEnv argument being passed to populate");
+        err19.code = "OBJECT_REQUIRED";
+        throw err19;
       }
       for (const key of Object.keys(parsed)) {
         if (Object.prototype.hasOwnProperty.call(processEnv, key)) {
@@ -18414,8 +18414,8 @@ var require_picomatch = __commonJS({
       try {
         const opts = options || {};
         return new RegExp(source, opts.flags || (opts.nocase ? "i" : ""));
-      } catch (err18) {
-        if (options && options.debug === true) throw err18;
+      } catch (err19) {
+        if (options && options.debug === true) throw err19;
         return /$^/;
       }
     };
@@ -18822,8 +18822,8 @@ var require_merge2 = __commonJS({
             }
             next();
           }
-          function onerror(err18) {
-            mergedStream.emit("error", err18);
+          function onerror(err19) {
+            mergedStream.emit("error", err19);
           }
           if (stream._readableState.endEmitted) {
             return next();
@@ -19187,8 +19187,8 @@ var require_out = __commonJS({
 var require_queue_microtask = __commonJS({
   "../../node_modules/.pnpm/queue-microtask@1.2.3/node_modules/queue-microtask/index.js"(exports2, module2) {
     var promise2;
-    module2.exports = typeof queueMicrotask === "function" ? queueMicrotask.bind(typeof window !== "undefined" ? window : global) : (cb2) => (promise2 || (promise2 = Promise.resolve())).then(cb2).catch((err18) => setTimeout(() => {
-      throw err18;
+    module2.exports = typeof queueMicrotask === "function" ? queueMicrotask.bind(typeof window !== "undefined" ? window : global) : (cb2) => (promise2 || (promise2 = Promise.resolve())).then(cb2).catch((err19) => setTimeout(() => {
+      throw err19;
     }, 0));
   }
 });
@@ -19209,32 +19209,32 @@ var require_run_parallel = __commonJS({
         results = {};
         pending = keys.length;
       }
-      function done(err18) {
+      function done(err19) {
         function end() {
-          if (cb2) cb2(err18, results);
+          if (cb2) cb2(err19, results);
           cb2 = null;
         }
         if (isSync) queueMicrotask2(end);
         else end();
       }
-      function each(i3, err18, result) {
+      function each(i3, err19, result) {
         results[i3] = result;
-        if (--pending === 0 || err18) {
-          done(err18);
+        if (--pending === 0 || err19) {
+          done(err19);
         }
       }
       if (!pending) {
         done(null);
       } else if (keys) {
         keys.forEach(function(key) {
-          tasks[key](function(err18, result) {
-            each(key, err18, result);
+          tasks[key](function(err19, result) {
+            each(key, err19, result);
           });
         });
       } else {
         tasks.forEach(function(task, i3) {
-          task(function(err18, result) {
-            each(i3, err18, result);
+          task(function(err19, result) {
+            each(i3, err19, result);
           });
         });
       }
@@ -19806,16 +19806,16 @@ var require_queue = __commonJS({
       this.context = null;
       this.errorHandler = null;
       var self2 = this;
-      this.worked = function worked(err18, result) {
+      this.worked = function worked(err19, result) {
         var callback = self2.callback;
         var errorHandler = self2.errorHandler;
         var val = self2.value;
         self2.value = null;
         self2.callback = noop2;
         if (self2.errorHandler) {
-          errorHandler(err18, val);
+          errorHandler(err19, val);
         }
-        callback.call(self2.context, err18, result);
+        callback.call(self2.context, err19, result);
         self2.release(self2);
       };
     }
@@ -19839,9 +19839,9 @@ var require_queue = __commonJS({
       return queue;
       function push(value) {
         var p = new Promise(function(resolve, reject) {
-          pushCb(value, function(err18, result) {
-            if (err18) {
-              reject(err18);
+          pushCb(value, function(err19, result) {
+            if (err19) {
+              reject(err19);
               return;
             }
             resolve(result);
@@ -19852,9 +19852,9 @@ var require_queue = __commonJS({
       }
       function unshift(value) {
         var p = new Promise(function(resolve, reject) {
-          unshiftCb(value, function(err18, result) {
-            if (err18) {
-              reject(err18);
+          unshiftCb(value, function(err19, result) {
+            if (err19) {
+              reject(err19);
               return;
             }
             resolve(result);
@@ -21075,7 +21075,7 @@ var {
 } = import_index.default;
 
 // src/commands/analyse-command.ts
-var import_promises16 = require("node:fs/promises");
+var import_promises17 = require("node:fs/promises");
 
 // ../../packages/pipeline/dist/index.js
 var import_node_fs2 = require("node:fs");
@@ -51989,6 +51989,7 @@ var import_node_path = __toESM(require("node:path"), 1);
 var import_neverthrow5 = __toESM(require_index_cjs(), 1);
 var import_sharp = __toESM(require("sharp"), 1);
 var import_neverthrow6 = __toESM(require_index_cjs(), 1);
+var import_promises6 = require("node:timers/promises");
 var import_node_crypto = require("node:crypto");
 var import_node_child_process2 = require("node:child_process");
 var import_node_events = require("node:events");
@@ -52052,11 +52053,33 @@ function resolveUdid(udid) {
     return (0, import_neverthrow3.err)(result);
   });
 }
+var parseIdbTree = (0, import_neverthrow.fromThrowable)(
+  (raw) => JSON.parse(raw),
+  (cause) => ({ type: "SNAPSHOT_PARSE_FAILED", cause })
+);
 var FULLSCREEN_THRESHOLD = 0.9;
 var DEFAULT_SCREEN_WIDTH = 375;
 var DEFAULT_SCREEN_HEIGHT = 812;
-var STABILITY_POLL_ATTEMPTS = 5;
-var STABILITY_POLL_DELAY_MS = 300;
+var STABILITY_POLL_ATTEMPTS = 10;
+var STABILITY_POLL_DELAY_MS = 500;
+function structuralSignature(elements) {
+  const lines = [];
+  const walk = (nodes) => {
+    for (const element of nodes) {
+      const frame = element.frame ?? { x: 0, y: 0, width: 0, height: 0 };
+      const type2 = element.type ?? "unknown";
+      const childCount = (element.children ?? []).length;
+      lines.push(
+        `${type2}|${String(frame.x)},${String(frame.y)},${String(frame.width)},${String(frame.height)}|${String(childCount)}`
+      );
+      if (element.children) {
+        walk(element.children);
+      }
+    }
+  };
+  walk(elements);
+  return lines.join("\n");
+}
 function isInViewport(frame, screen) {
   return frame.width > 0 && frame.height > 0 && frame.x + frame.width > 0 && frame.x < screen.width && frame.y + frame.height > 0 && frame.y < screen.height;
 }
@@ -52168,36 +52191,39 @@ function formatAccessibilityElements(elements) {
 
 ${elementList}` : elementList;
 }
+function fetchSnapshot(udid) {
+  return runCommand("idb", ["ui", "describe-all", "--udid", udid, "--json", "--nested"]);
+}
 async function pollUntilStable(udid) {
-  let previous;
+  let previousSignature;
+  let previousRaw = "";
   for (let index = 0; index < STABILITY_POLL_ATTEMPTS; index++) {
-    const result = await runCommand("idb", [
-      "ui",
-      "describe-all",
-      "--udid",
-      udid,
-      "--json",
-      "--nested"
-    ]);
+    const result = await fetchSnapshot(udid);
     if (result.isErr()) {
       return result;
     }
-    const current = result.value;
-    if (current === previous) {
-      return (0, import_neverthrow.ok)(current);
+    const raw = result.value;
+    const parsed = parseIdbTree(raw);
+    if (parsed.isErr()) {
+      return (0, import_neverthrow.err)(parsed.error);
+    }
+    const signature = structuralSignature(parsed.value);
+    if (signature === previousSignature) {
+      return (0, import_neverthrow.ok)(raw);
     }
-    previous = current;
+    previousSignature = signature;
+    previousRaw = raw;
     if (index < STABILITY_POLL_ATTEMPTS - 1) {
       await (0, import_promises4.setTimeout)(STABILITY_POLL_DELAY_MS);
     }
   }
-  return (0, import_neverthrow.ok)(previous ?? "");
+  return (0, import_neverthrow.ok)(previousRaw);
 }
 function waitForStableSnapshot(udid) {
   return new import_neverthrow.ResultAsync(pollUntilStable(udid));
 }
 function captureAccessibilityTree(udid = "booted") {
-  return resolveUdid(udid).andThen((resolvedUdid) => waitForStableSnapshot(resolvedUdid)).map((raw) => JSON.parse(raw));
+  return resolveUdid(udid).andThen((resolvedUdid) => waitForStableSnapshot(resolvedUdid)).andThen((raw) => parseIdbTree(raw));
 }
 function captureAccessibilitySnapshot(udid = "booted") {
   return captureAccessibilityTree(udid).map((elements) => formatAccessibilityElements(elements));
@@ -52590,6 +52616,37 @@ function createScreenshotTool(udid = "booted") {
   });
 }
 var screenshotTool = createScreenshotTool();
+var MIN_WAIT_SECONDS = 1;
+var MAX_WAIT_SECONDS = 10;
+var MS_PER_SECOND2 = 1e3;
+var SECONDS_SCHEMA = external_exports.number().int().min(MIN_WAIT_SECONDS).max(MAX_WAIT_SECONDS);
+var WAIT_SCHEMA = {
+  seconds: SECONDS_SCHEMA
+};
+function createWaitSecondsTool() {
+  return _x(
+    "wait_seconds",
+    "Pause for N seconds (1-10) when expected UI content may still be loading silently. Call view_ui again after waiting.",
+    WAIT_SCHEMA,
+    async ({ seconds }) => {
+      const parsed = SECONDS_SCHEMA.safeParse(seconds);
+      if (!parsed.success) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `wait_seconds expected an integer between ${String(MIN_WAIT_SECONDS)} and ${String(MAX_WAIT_SECONDS)}, got ${String(seconds)}`
+            }
+          ],
+          isError: true
+        };
+      }
+      await (0, import_promises6.setTimeout)(parsed.data * MS_PER_SECOND2);
+      return { content: [{ type: "text", text: `Waited ${String(parsed.data)}s` }] };
+    }
+  );
+}
+var WAIT_SECONDS_TOOL_NAME = "mcp__mobile-ios__wait_seconds";
 var LABEL_SET_CAP = 50;
 var MID_DEPTH_THRESHOLD = 5;
 var DEFAULT_SCREEN_HEIGHT2 = 812;
@@ -52744,6 +52801,7 @@ function createMobileIosServer(udid = "booted", extraTools = []) {
       createLaunchAppTool(udid),
       createTerminateAppTool(udid),
       createListAppsTool(udid),
+      createWaitSecondsTool(),
       ...extraTools
     ]
   });
@@ -52765,7 +52823,7 @@ var findingSchema = external_exports.object({
     "motion-regression",
     "interaction-regression",
     "continuity-regression",
-    "step-skipped"
+    "missing-content"
   ]),
   flow: external_exports.string(),
   steps: external_exports.array(external_exports.string()),
@@ -52810,10 +52868,10 @@ function dismissalsPath(baseDirectory, override) {
 
 // ../../packages/pipeline/dist/index.js
 var import_neverthrow30 = __toESM(require_index_cjs(), 1);
-var import_promises14 = require("node:timers/promises");
+var import_promises15 = require("node:timers/promises");
 
 // ../../agents/analyser/dist/index.js
-var import_promises6 = require("node:fs/promises");
+var import_promises7 = require("node:fs/promises");
 
 // ../../node_modules/.pnpm/chalk@5.6.2/node_modules/chalk/source/vendor/ansi-styles/index.js
 var ANSI_BACKGROUND_OFFSET = 10;
@@ -53639,9 +53697,9 @@ function render(state, previous) {
 function dashboardEqual(left, right) {
   return JSON.stringify(left) === JSON.stringify(right);
 }
-var MS_PER_SECOND2 = 1e3;
+var MS_PER_SECOND3 = 1e3;
 function formatDuration(ms) {
-  return `${String(Math.round(ms / MS_PER_SECOND2))}s`;
+  return `${String(Math.round(ms / MS_PER_SECOND3))}s`;
 }
 function normalizeItemQueued(event) {
   return [{ kind: "text", style: "default", text: `[${event.item.name}] QUEUED` }];
@@ -54477,7 +54535,7 @@ function safeHandler(handler) {
 
 // ../../agents/analyser/dist/index.js
 var import_neverthrow10 = __toESM(require_index_cjs(), 1);
-var import_promises7 = require("node:timers/promises");
+var import_promises8 = require("node:timers/promises");
 
 // ../../node_modules/.pnpm/@google+generative-ai@0.24.1/node_modules/@google/generative-ai/dist/index.mjs
 var SchemaType;
@@ -54680,15 +54738,15 @@ async function makeRequest(url2, fetchOptions, fetchFn = fetch) {
   return response;
 }
 function handleResponseError(e3, url2) {
-  let err18 = e3;
-  if (err18.name === "AbortError") {
-    err18 = new GoogleGenerativeAIAbortError(`Request aborted when fetching ${url2.toString()}: ${e3.message}`);
-    err18.stack = e3.stack;
+  let err19 = e3;
+  if (err19.name === "AbortError") {
+    err19 = new GoogleGenerativeAIAbortError(`Request aborted when fetching ${url2.toString()}: ${e3.message}`);
+    err19.stack = e3.stack;
   } else if (!(e3 instanceof GoogleGenerativeAIFetchError || e3 instanceof GoogleGenerativeAIRequestInputError)) {
-    err18 = new GoogleGenerativeAIError(`Error fetching from ${url2.toString()}: ${e3.message}`);
-    err18.stack = e3.stack;
+    err19 = new GoogleGenerativeAIError(`Error fetching from ${url2.toString()}: ${e3.message}`);
+    err19.stack = e3.stack;
   }
-  throw err18;
+  throw err19;
 }
 async function handleResponseNotOk(response, url2) {
   let message = "";
@@ -54935,14 +54993,14 @@ function getResponseStream(inputStream) {
           }
           return pump();
         }).catch((e3) => {
-          let err18 = e3;
-          err18.stack = e3.stack;
-          if (err18.name === "AbortError") {
-            err18 = new GoogleGenerativeAIAbortError("Request aborted when reading from the stream");
+          let err19 = e3;
+          err19.stack = e3.stack;
+          if (err19.name === "AbortError") {
+            err19 = new GoogleGenerativeAIAbortError("Request aborted when reading from the stream");
           } else {
-            err18 = new GoogleGenerativeAIError("Error reading from the stream");
+            err19 = new GoogleGenerativeAIError("Error reading from the stream");
           }
-          throw err18;
+          throw err19;
         });
       }
     }
@@ -55538,15 +55596,15 @@ async function makeRequest2(url2, fetchOptions, fetchFn = fetch) {
   return response;
 }
 function handleResponseError2(e3, url2) {
-  let err18 = e3;
-  if (err18.name === "AbortError") {
-    err18 = new GoogleGenerativeAIAbortError2(`Request aborted when fetching ${url2.toString()}: ${e3.message}`);
-    err18.stack = e3.stack;
+  let err19 = e3;
+  if (err19.name === "AbortError") {
+    err19 = new GoogleGenerativeAIAbortError2(`Request aborted when fetching ${url2.toString()}: ${e3.message}`);
+    err19.stack = e3.stack;
   } else if (!(e3 instanceof GoogleGenerativeAIFetchError2 || e3 instanceof GoogleGenerativeAIRequestInputError2)) {
-    err18 = new GoogleGenerativeAIError2(`Error fetching from ${url2.toString()}: ${e3.message}`);
-    err18.stack = e3.stack;
+    err19 = new GoogleGenerativeAIError2(`Error fetching from ${url2.toString()}: ${e3.message}`);
+    err19.stack = e3.stack;
   }
-  throw err18;
+  throw err19;
 }
 async function handleResponseNotOk2(response, url2) {
   let message = "";
@@ -55906,7 +55964,7 @@ async function runPollLoop(checkState, onTick) {
     if (state === FileState.FAILED) {
       return "failed";
     }
-    await (0, import_promises7.setTimeout)(POLL_INTERVAL_MS);
+    await (0, import_promises8.setTimeout)(POLL_INTERVAL_MS);
   }
   return "timeout";
 }
@@ -56036,7 +56094,7 @@ var DEFAULT_MODEL = "gemini-2.5-pro";
 var BYTES_PER_MB = 1048576;
 var MAX_POLL_ATTEMPTS2 = 30;
 async function getFileSize(filePath) {
-  const fileStats = await (0, import_promises6.stat)(filePath);
+  const fileStats = await (0, import_promises7.stat)(filePath);
   return fileStats.size;
 }
 function emitStageEnd(onEvent, start) {
@@ -56142,34 +56200,34 @@ var uuid42 = function() {
 };
 
 // ../../node_modules/.pnpm/@anthropic-ai+sdk@0.87.0_zod@4.3.6/node_modules/@anthropic-ai/sdk/internal/errors.mjs
-function isAbortError(err18) {
-  return typeof err18 === "object" && err18 !== null && // Spec-compliant fetch implementations
-  ("name" in err18 && err18.name === "AbortError" || // Expo fetch
-  "message" in err18 && String(err18.message).includes("FetchRequestCanceledException"));
-}
-var castToError = (err18) => {
-  if (err18 instanceof Error)
-    return err18;
-  if (typeof err18 === "object" && err18 !== null) {
+function isAbortError(err19) {
+  return typeof err19 === "object" && err19 !== null && // Spec-compliant fetch implementations
+  ("name" in err19 && err19.name === "AbortError" || // Expo fetch
+  "message" in err19 && String(err19.message).includes("FetchRequestCanceledException"));
+}
+var castToError = (err19) => {
+  if (err19 instanceof Error)
+    return err19;
+  if (typeof err19 === "object" && err19 !== null) {
     try {
-      if (Object.prototype.toString.call(err18) === "[object Error]") {
-        const error48 = new Error(err18.message, err18.cause ? { cause: err18.cause } : {});
-        if (err18.stack)
-          error48.stack = err18.stack;
-        if (err18.cause && !error48.cause)
-          error48.cause = err18.cause;
-        if (err18.name)
-          error48.name = err18.name;
+      if (Object.prototype.toString.call(err19) === "[object Error]") {
+        const error48 = new Error(err19.message, err19.cause ? { cause: err19.cause } : {});
+        if (err19.stack)
+          error48.stack = err19.stack;
+        if (err19.cause && !error48.cause)
+          error48.cause = err19.cause;
+        if (err19.name)
+          error48.name = err19.name;
         return error48;
       }
     } catch {
     }
     try {
-      return new Error(JSON.stringify(err18));
+      return new Error(JSON.stringify(err19));
     } catch {
     }
   }
-  return new Error(err18);
+  return new Error(err19);
 };
 
 // ../../node_modules/.pnpm/@anthropic-ai+sdk@0.87.0_zod@4.3.6/node_modules/@anthropic-ai/sdk/core/error.mjs
@@ -56299,13 +56357,13 @@ var validatePositiveInteger = (name, n3) => {
 var safeJSON = (text) => {
   try {
     return JSON.parse(text);
-  } catch (err18) {
+  } catch (err19) {
     return void 0;
   }
 };
 
 // ../../node_modules/.pnpm/@anthropic-ai+sdk@0.87.0_zod@4.3.6/node_modules/@anthropic-ai/sdk/internal/utils/sleep.mjs
-var sleep3 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var sleep4 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 // ../../node_modules/.pnpm/@anthropic-ai+sdk@0.87.0_zod@4.3.6/node_modules/@anthropic-ai/sdk/version.mjs
 var VERSION = "0.87.0";
@@ -56863,8 +56921,8 @@ var Stream = class _Stream {
             return ctrl.close();
           const bytes = encodeUTF8(JSON.stringify(value) + "\n");
           ctrl.enqueue(bytes);
-        } catch (err18) {
-          ctrl.error(err18);
+        } catch (err19) {
+          ctrl.error(err19);
         }
       },
       async cancel() {
@@ -58771,8 +58829,8 @@ var BetaMessageStream = class _BetaMessageStream {
               if (jsonBuf) {
                 try {
                   newContent.input = partialParse(jsonBuf);
-                } catch (err18) {
-                  const error48 = new AnthropicError(`Unable to parse tool parameter JSON from model. Please retry your request or adjust your prompt. Error: ${err18}. JSON: ${jsonBuf}`);
+                } catch (err19) {
+                  const error48 = new AnthropicError(`Unable to parse tool parameter JSON from model. Please retry your request or adjust your prompt. Error: ${err19}. JSON: ${jsonBuf}`);
                   __classPrivateFieldGet(this, _BetaMessageStream_handleError, "f").call(this, error48);
                 }
               }
@@ -58834,17 +58892,17 @@ var BetaMessageStream = class _BetaMessageStream {
       }
       readQueue.length = 0;
     });
-    this.on("abort", (err18) => {
+    this.on("abort", (err19) => {
       done = true;
       for (const reader of readQueue) {
-        reader.reject(err18);
+        reader.reject(err19);
       }
       readQueue.length = 0;
     });
-    this.on("error", (err18) => {
+    this.on("error", (err19) => {
       done = true;
       for (const reader of readQueue) {
-        reader.reject(err18);
+        reader.reject(err19);
       }
       readQueue.length = 0;
     });
@@ -61087,17 +61145,17 @@ var MessageStream = class _MessageStream {
       }
       readQueue.length = 0;
     });
-    this.on("abort", (err18) => {
+    this.on("abort", (err19) => {
       done = true;
       for (const reader of readQueue) {
-        reader.reject(err18);
+        reader.reject(err19);
       }
       readQueue.length = 0;
     });
-    this.on("error", (err18) => {
+    this.on("error", (err19) => {
       done = true;
       for (const reader of readQueue) {
-        reader.reject(err18);
+        reader.reject(err19);
       }
       readQueue.length = 0;
     });
@@ -61677,7 +61735,7 @@ var BaseAnthropic = class {
       }
       const retryMessage = shouldRetry ? `error; no more retries left` : `error; not retryable`;
       loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
-      const errText = await response.text().catch((err19) => castToError(err19).message);
+      const errText = await response.text().catch((err20) => castToError(err20).message);
       const errJSON = safeJSON(errText);
       const errMessage = errJSON ? void 0 : errText;
       loggerFor(this).debug(`[${requestLogID}] response error (${retryMessage})`, formatRequestDetails({
@@ -61688,8 +61746,8 @@ var BaseAnthropic = class {
         message: errMessage,
         durationMs: Date.now() - startTime
       }));
-      const err18 = this.makeStatusError(response.status, errJSON, errMessage, response.headers);
-      throw err18;
+      const err19 = this.makeStatusError(response.status, errJSON, errMessage, response.headers);
+      throw err19;
     }
     loggerFor(this).info(responseInfo);
     loggerFor(this).debug(`[${requestLogID}] response start`, formatRequestDetails({
@@ -61768,7 +61826,7 @@ var BaseAnthropic = class {
       const maxRetries = options.maxRetries ?? this.maxRetries;
       timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
     }
-    await sleep3(timeoutMillis);
+    await sleep4(timeoutMillis);
     return this.makeRequest(options, retriesRemaining - 1, requestLogID);
   }
   calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries) {
@@ -62132,25 +62190,25 @@ var import_neverthrow31 = __toESM(require_index_cjs(), 1);
 var import_neverthrow32 = __toESM(require_index_cjs(), 1);
 var import_node_fs3 = require("node:fs");
 var import_neverthrow33 = __toESM(require_index_cjs(), 1);
-var import_promises15 = require("node:timers/promises");
+var import_promises16 = require("node:timers/promises");
 
 // ../../agents/explorer/dist/index.js
 var import_node_child_process3 = require("node:child_process");
 var import_node_fs = require("node:fs");
 var import_node_path4 = __toESM(require("node:path"), 1);
 var import_neverthrow15 = __toESM(require_index_cjs(), 1);
-var import_promises8 = require("node:timers/promises");
+var import_promises9 = require("node:timers/promises");
 var import_neverthrow16 = __toESM(require_index_cjs(), 1);
 var import_neverthrow17 = __toESM(require_index_cjs(), 1);
-var import_promises9 = require("node:fs/promises");
+var import_promises10 = require("node:fs/promises");
 var import_node_path5 = __toESM(require("node:path"), 1);
 var import_neverthrow18 = __toESM(require_index_cjs(), 1);
 var import_node_child_process4 = require("node:child_process");
-var import_promises10 = require("node:fs/promises");
+var import_promises11 = require("node:fs/promises");
 var import_neverthrow19 = __toESM(require_index_cjs(), 1);
 var import_neverthrow20 = __toESM(require_index_cjs(), 1);
 var import_neverthrow21 = __toESM(require_index_cjs(), 1);
-var import_promises11 = require("node:fs/promises");
+var import_promises12 = require("node:fs/promises");
 var import_node_path6 = __toESM(require("node:path"), 1);
 var import_neverthrow22 = __toESM(require_index_cjs(), 1);
 async function runFfmpeg(arguments_) {
@@ -62266,7 +62324,7 @@ function deriveScreenLabel(tree, stepIndex) {
 async function persistScreenshot(params) {
   const screenshotPath = import_node_path5.default.join(params.screenshotsDirectory, `${params.screenLabel}.png`);
   const safeWriteFile = (0, import_neverthrow18.fromAsyncThrowable)(
-    import_promises9.writeFile,
+    import_promises10.writeFile,
     (cause) => ({ type: "WRITE_FAILED", cause })
   );
   const writeResult = safeWriteFile(screenshotPath, Buffer.from(params.data, "base64"));
@@ -62331,7 +62389,7 @@ function buildSnapshotRecord(rawElements, { stepIndex, context }) {
 async function handleScreenshotData(data, params) {
   if (params.context.screenshotsDir !== void 0) {
     const safeWrite2 = (0, import_neverthrow18.fromAsyncThrowable)(
-      import_promises9.writeFile,
+      import_promises10.writeFile,
       (cause) => ({ type: "WRITE_FAILED", cause })
     );
     const snapshotPath = import_node_path5.default.join(params.context.screenshotsDir, `${params.screenLabel}.txt`);
@@ -62668,7 +62726,8 @@ async function setupQuery(config3, outputTools) {
   const allowedTools = [
     ...config3.allowedTools ?? [],
     ...outputTools.allowedToolNames,
-    VIEW_UI_TOOL_NAME
+    VIEW_UI_TOOL_NAME,
+    WAIT_SECONDS_TOOL_NAME
   ];
   const disallowedTools = await resolveDisallowedTools(allowedTools);
   const inputQueue = new MessageQueue();
@@ -62744,7 +62803,7 @@ function startTimeout(timeoutMs, context) {
 var EXPLORER_FINDING_SCHEMA = findingSchema.omit({ agent: true });
 var INTERRUPT_DRAIN_TIMEOUT_MS = 1e4;
 async function interruptOrTimeout(queryRunner) {
-  await Promise.race([queryRunner.interrupt(), (0, import_promises8.setTimeout)(INTERRUPT_DRAIN_TIMEOUT_MS)]);
+  await Promise.race([queryRunner.interrupt(), (0, import_promises9.setTimeout)(INTERRUPT_DRAIN_TIMEOUT_MS)]);
 }
 var safeInterruptOrTimeout = import_neverthrow16.ResultAsync.fromThrowable(
   interruptOrTimeout,
@@ -62904,9 +62963,11 @@ At every reasoning step, maintain a mental ledger:
 - PATH: your current navigation stack from root (e.g. Home > Settings > Privacy)
 
 Consult the ledger before every action. Always prefer navigating to a QUEUE screen over a VISITED one.`;
+var SESSION_START_RULE = `Before taking any other action \u2014 including initializing the Working State ledger or emitting findings \u2014 call \`view_ui\` once to observe the starting screen`;
 var BACK_NAV_RULE = `After navigating forward to any new screen: tap back, call \`view_ui\`, confirm you returned to the expected parent in PATH \u2014 if not, emit a \`back-nav-failure\` finding, then navigate forward again to continue`;
 var STUCK_LOOP_RULE = `Stuck loop: emit a \`stuck-loop\` finding when any of these occur: (1) \`view_ui\` returns the same screen state 3 or more consecutive steps, (2) the same element has been tapped more than twice with no screen change, (3) PATH shows the same screen at two non-adjacent positions \u2014 before emitting, try one alternative action (scroll, long-press, swipe) to rule out a gesture mismatch`;
 var LOADING_STATE_RULE = `Transient loading state: when \`view_ui\` reveals spinners, skeleton screens, progress bars, "Loading..." text, or placeholder content NOT described in spec or app context, wait and retry \`view_ui\` up to 3 times before treating screen as final \u2014 if loading persists after 3 retries, proceed with what is visible; if spec or app context explicitly describes a loading screen as a step, do not retry \u2014 inspect and assert normally`;
+var EXPECTED_CONTENT_MISSING_RULE = `Expected content missing: when \`view_ui\` shows no loading indicator yet omits an element named or strongly implied by spec or app context \u2014 and its absence is not semantically consistent with the current screen \u2014 call \`wait_seconds\` with 2\u20135 seconds and retry \`view_ui\` up to 2 times; if element remains absent, emit a \`missing-content\` finding stating what was expected and what was observed`;
 var CLIPPED_ELEMENT_RULE = `Never tap an element tagged \`[clipped-top]\`, \`[clipped-bottom]\`, \`[clipped-left]\`, or \`[clipped-right]\` \u2014 scroll to fully reveal it first, then re-call \`view_ui\` before tapping`;
 var WHAT_TO_TEST_SECTION = `## What to Test
 
@@ -62980,11 +63041,13 @@ ${initialState2}` : void 0,
 }
 var SPEC_RULES_SECTION = `## Rules
 
+- ${SESSION_START_RULE}
 - ALWAYS call \`view_ui\` after every action before deciding what to do next \u2014 it is your only way to observe the screen
 - ${BACK_NAV_RULE}
 - Before selecting any action, prefer navigating to a QUEUE screen over re-exploring a VISITED one
 - ${STUCK_LOOP_RULE}
 - ${LOADING_STATE_RULE}
+- ${EXPECTED_CONTENT_MISSING_RULE}
 - ${CLIPPED_ELEMENT_RULE}
 - Each item in \`**Assertions**\` is a mandatory pass/fail check \u2014 verify using \`view_ui\`; if the accessibility tree cannot confirm, emit a \`spec-deviation\` finding based on what is observable
 - Flag crash dialogs, unexpected system errors, or navigation failures that occur as a direct result of executing a spec step; if you observe a visibly broken element in passing while navigating, note it without interacting with it`;
@@ -62993,7 +63056,7 @@ function buildSpecModeBody({
   contextBlock,
   environmentSection
 }) {
-  return `You are a spec execution agent. Your role is to follow the provided spec exactly \u2014 execute each step in sequence, verify each assertion, and report deviations. Observe and flag obvious breakage encountered in transit, but do not explore or interact with anything outside the spec.
+  return `You are a spec execution agent. Your first action MUST be a \`view_ui\` call. Your role is to follow the provided spec exactly \u2014 execute each step in sequence, verify each assertion, and report deviations. Observe and flag obvious breakage encountered in transit, but do not explore or interact with anything outside the spec.
 
 Verify app against specs below.
 
@@ -63034,17 +63097,19 @@ var FREESTYLE_TEMPLATE = (options) => {
   const environmentSection = buildEnv === "dev" ? `
 
 ${DEV_ENVIRONMENT_SECTION}` : "";
-  return `You are a navigation and interaction testing agent. Your role is to find broken navigation flows and non-functional interactive elements. Do not report content bugs, copy errors, or visual style issues unless they directly prevent a navigation action from completing.
+  return `You are a navigation and interaction testing agent. Your first action MUST be a \`view_ui\` call. Your role is to find broken navigation flows and non-functional interactive elements. Do not report content bugs, copy errors, or visual style issues unless they directly prevent a navigation action from completing.
 
 ${contextBlock}
 
 ## Rules
 
+- ${SESSION_START_RULE}
 - ALWAYS call \`view_ui\` after every action before deciding what to do next \u2014 it is your only way to observe the screen
 - ${BACK_NAV_RULE}
 - Before selecting any action, prefer navigating to a QUEUE screen over re-exploring a VISITED one
 - ${STUCK_LOOP_RULE}
 - ${LOADING_STATE_RULE}
+- ${EXPECTED_CONTENT_MISSING_RULE}
 - ${CLIPPED_ELEMENT_RULE}
 
 ## Exploration Strategy
@@ -63259,7 +63324,7 @@ function direntToSpecEntry(directory, entry) {
 }
 function scanDirectory(directory) {
   const safeReaddir3 = (0, import_neverthrow22.fromAsyncThrowable)(
-    async () => (0, import_promises11.readdir)(directory, { withFileTypes: true }),
+    async () => (0, import_promises12.readdir)(directory, { withFileTypes: true }),
     (cause) => ({ type: "DIR_READ_FAILED", dir: directory, cause })
   );
   return safeReaddir3().orElse((error48) => isNotFound(error48.cause) ? (0, import_neverthrow22.okAsync)([]) : (0, import_neverthrow22.errAsync)(error48)).map(
@@ -63273,7 +63338,7 @@ function readEntries(entries) {
 }
 function readEntry(entry) {
   const safeReadFile6 = (0, import_neverthrow22.fromAsyncThrowable)(
-    async () => (0, import_promises11.readFile)(entry.path, "utf8"),
+    async () => (0, import_promises12.readFile)(entry.path, "utf8"),
     (cause) => ({ type: "FILE_READ_FAILED", path: entry.path, cause })
   );
   return safeReadFile6().map((content) => [{ name: entry.name, content }]).orElse((error48) => entry.required ? (0, import_neverthrow22.errAsync)(error48) : (0, import_neverthrow22.okAsync)([]));
@@ -63398,7 +63463,7 @@ function runExplorer(config3) {
   };
   safeConfig.onEvent?.({ type: "STAGE_START", agent: "explorer" });
   return import_neverthrow19.ResultAsync.fromSafePromise(
-    (0, import_promises10.mkdir)(runPaths.screenshotsDir, { recursive: true }).catch(() => null)
+    (0, import_promises11.mkdir)(runPaths.screenshotsDir, { recursive: true }).catch(() => null)
   ).andThen(() => runPipeline({ safeConfig, runPaths, start }));
 }
 
@@ -63407,14 +63472,14 @@ var import_neverthrow34 = __toESM(require_index_cjs(), 1);
 
 // ../../agents/inspector/dist/index.js
 var import_neverthrow23 = __toESM(require_index_cjs(), 1);
-var import_promises12 = require("node:fs/promises");
+var import_promises13 = require("node:fs/promises");
 var import_neverthrow24 = __toESM(require_index_cjs(), 1);
 var import_neverthrow25 = __toESM(require_index_cjs(), 1);
 var import_neverthrow26 = __toESM(require_index_cjs(), 1);
 var import_neverthrow27 = __toESM(require_index_cjs(), 1);
 var import_sharp2 = __toESM(require("sharp"), 1);
 var import_neverthrow28 = __toESM(require_index_cjs(), 1);
-var import_promises13 = require("node:fs/promises");
+var import_promises14 = require("node:fs/promises");
 var import_node_path7 = __toESM(require("node:path"), 1);
 
 // ../../node_modules/.pnpm/js-yaml@4.1.1/node_modules/js-yaml/dist/js-yaml.mjs
@@ -64380,7 +64445,7 @@ var directiveHandlers = {
     }
     try {
       prefix = decodeURIComponent(prefix);
-    } catch (err18) {
+    } catch (err19) {
       throwError(state, "tag prefix is malformed: " + prefix);
     }
     state.tagMap[handle] = prefix;
@@ -65061,7 +65126,7 @@ function readTagProperty(state) {
   }
   try {
     tagName = decodeURIComponent(tagName);
-  } catch (err18) {
+  } catch (err19) {
     throwError(state, "tag name is malformed: " + tagName);
   }
   if (isVerbatim) {
@@ -66730,7 +66795,7 @@ async function initArtboardNames({ designStore, config: config3, state }) {
 }
 function readScreenshot(screenshotPath, stepIndex) {
   return import_neverthrow24.ResultAsync.fromThrowable(
-    import_promises12.readFile,
+    import_promises13.readFile,
     (cause) => ({ type: "SCREENSHOT_READ_FAILED", stepIndex, cause })
   )(screenshotPath);
 }
@@ -66825,7 +66890,7 @@ function parseMeta(raw) {
   return {};
 }
 async function readAndParseSidecar(sidecarPath) {
-  const raw = await (0, import_promises13.readFile)(sidecarPath, "utf8");
+  const raw = await (0, import_promises14.readFile)(sidecarPath, "utf8");
   return parseMeta(raw);
 }
 function readSidecarFile(sidecarPath) {
@@ -66856,7 +66921,7 @@ var FsDesignStore = class {
   }
   listArtboards() {
     return (0, import_neverthrow29.fromAsyncThrowable)(
-      import_promises13.readdir,
+      import_promises14.readdir,
       wrapFsError
     )(this.designsDirectory).orElse((fsError) => {
       if (fsError.type === "FS_ERROR" && isEnoent(fsError.cause)) {
@@ -66871,7 +66936,7 @@ var FsDesignStore = class {
     const pngPath = import_node_path7.default.join(this.designsDirectory, `${filename}.png`);
     const sidecarPath = import_node_path7.default.join(this.designsDirectory, `${filename}.meta.yaml`);
     return (0, import_neverthrow29.fromAsyncThrowable)(
-      import_promises13.readFile,
+      import_promises14.readFile,
       wrapFsError
     )(pngPath).orElse((fsError) => {
       if (fsError.type === "FS_ERROR" && isEnoent(fsError.cause)) {
@@ -66929,7 +66994,7 @@ function runAnalyserWithRetry(params) {
     ),
     {
       config: { maxAttempts: RETRY_MAX_ATTEMPTS, baseDelayMs: RETRY_BASE_DELAY_MS },
-      delayFunction: import_promises14.setTimeout,
+      delayFunction: import_promises15.setTimeout,
       onRetry: ({ attempt, maxAttempts, delayMs, error: error48 }) => {
         onEvent?.({
           type: "AGENT_RETRY",
@@ -67118,7 +67183,7 @@ function runExplorerWithRetry(options) {
   const { explorerConfig, udid, onEvent } = options;
   return withRetry(() => runExplorerWithTeardown(explorerConfig, udid), {
     config: { maxAttempts: RETRY_MAX_ATTEMPTS, baseDelayMs: RETRY_BASE_DELAY_MS },
-    delayFunction: import_promises15.setTimeout,
+    delayFunction: import_promises16.setTimeout,
     onRetry: ({ attempt, maxAttempts, delayMs, error: error48 }) => {
       onEvent?.({
         type: "AGENT_RETRY",
@@ -67278,7 +67343,7 @@ function runPipeline2(config3) {
 }
 
 // src/commands/analyse-command.ts
-var import_neverthrow35 = __toESM(require_index_cjs(), 1);
+var import_neverthrow36 = __toESM(require_index_cjs(), 1);
 
 // src/commands/item-events.ts
 function emitItemStart(identity, at) {
@@ -67313,6 +67378,272 @@ function emitItemFailed(input) {
   });
 }
 
+// src/shell/debug-agent-events.ts
+var import_neverthrow35 = __toESM(require_index_cjs(), 1);
+
+// src/constants.ts
+var MOBILE_IOS_TOOLS = [
+  "mcp__mobile-ios__tap",
+  "mcp__mobile-ios__double_tap",
+  "mcp__mobile-ios__long_press",
+  "mcp__mobile-ios__swipe",
+  "mcp__mobile-ios__type_text",
+  "mcp__mobile-ios__press_button",
+  "mcp__mobile-ios__launch_app",
+  "mcp__mobile-ios__terminate_app",
+  "mcp__mobile-ios__list_apps",
+  "mcp__mobile-ios__screenshot",
+  "mcp__mobile-ios__accessibility_snapshot"
+];
+var ALLOWED_TOOLS = [...MOBILE_IOS_TOOLS];
+var MS_PER_SECOND4 = 1e3;
+var DEFAULT_ABORT_EXIT_CODE = 130;
+var IDB_INSTALL_MESSAGE = "idb is not installed. Run:\n  brew install idb-companion\n  pipx install fb-idb\n";
+var FFMPEG_INSTALL_MESSAGE = "ffmpeg is not installed. Run:\n  brew install ffmpeg\n";
+
+// src/shell/debug-logger-core.ts
+var ELAPSED_PAD = 8;
+function formatElapsed(elapsedMs) {
+  const seconds = (elapsedMs / MS_PER_SECOND4).toFixed(2);
+  return `+${seconds}s`.padStart(ELAPSED_PAD, " ");
+}
+function createCallTracker() {
+  const starts = /* @__PURE__ */ new Map();
+  return {
+    mark: (key, at) => {
+      const queue = starts.get(key) ?? [];
+      queue.push(at);
+      starts.set(key, queue);
+    },
+    pop: (key) => {
+      const queue = starts.get(key);
+      const start = queue?.shift();
+      if (queue?.length === 0) {
+        starts.delete(key);
+      }
+      return start;
+    }
+  };
+}
+function buildLogger(options) {
+  const now = options.now ?? Date.now;
+  const write = options.write ?? ((line) => process.stderr.write(line));
+  const startedAt = now();
+  const tracker = createCallTracker();
+  return {
+    log: (tag, detail) => {
+      const elapsed = now() - startedAt;
+      write(`[debug] ${formatElapsed(elapsed)} ${tag} ${detail}
+`);
+    },
+    markCall: (key) => {
+      tracker.mark(key, now());
+    },
+    elapsedSince: (key) => {
+      const start = tracker.pop(key);
+      return start === void 0 ? void 0 : now() - start;
+    }
+  };
+}
+function formatDurationSuffix(duration3) {
+  if (duration3 === void 0) {
+    return "";
+  }
+  return ` duration=${String(duration3)}ms`;
+}
+function formatOptionalNumber(value) {
+  return value === void 0 ? "?" : String(value);
+}
+
+// src/shell/debug-agent-events.ts
+var TOOL_INPUT_MAX = 120;
+var TOOL_ERROR_MAX = 120;
+var UNSERIALIZABLE = "[unserializable]";
+function tryStringify(value) {
+  const result = JSON.stringify(value);
+  return result ?? UNSERIALIZABLE;
+}
+var safeStringify = (0, import_neverthrow35.fromThrowable)(tryStringify, () => ({
+  type: "STRINGIFY_FAILED"
+}));
+function toolKey(scope, event) {
+  const prefix = scope === void 0 ? "" : `${scope}:`;
+  return `${prefix}${event.agent}:${event.toolName}`;
+}
+function stringifyToolInput(input) {
+  if (input === void 0 || input === null) {
+    return "";
+  }
+  if (typeof input === "string") {
+    return input;
+  }
+  return safeStringify(input).unwrapOr(UNSERIALIZABLE);
+}
+function truncate(value, max) {
+  return value.length > max ? `${value.slice(0, max)}\u2026` : value;
+}
+function handleStageStart(context, event) {
+  context.logger.log(
+    "STAGE_START",
+    `${event.agent} steps=${formatOptionalNumber(event.totalSteps)}`
+  );
+}
+function handleStageEnd(context, event) {
+  context.logger.log("STAGE_END", `${event.agent} duration=${String(event.durationMs)}ms`);
+}
+function handleToolCall(context, event) {
+  context.logger.markCall(toolKey(context.scope, event));
+  const input = truncate(stringifyToolInput(event.input), TOOL_INPUT_MAX);
+  context.logger.log("TOOL_CALL", `${event.agent} ${event.toolName} ${input}`);
+}
+function handleToolResult(context, event) {
+  const suffix = formatDurationSuffix(context.logger.elapsedSince(toolKey(context.scope, event)));
+  context.logger.log("TOOL_RESULT", `${event.agent} ${event.toolName}${suffix}`);
+}
+function handleToolError(context, event) {
+  const suffix = formatDurationSuffix(context.logger.elapsedSince(toolKey(context.scope, event)));
+  const error48 = truncate(event.error, TOOL_ERROR_MAX);
+  context.logger.log("TOOL_ERROR", `${event.agent} ${event.toolName}${suffix} ${error48}`);
+}
+function handleAgentRetry(context, event) {
+  context.logger.log(
+    "AGENT_RETRY",
+    `${event.agent} attempt=${String(event.attempt)}/${String(event.maxAttempts)} delay=${String(event.delayMs)}ms`
+  );
+}
+function handleAgentFailed(context, event) {
+  context.logger.log(
+    "AGENT_FAILED_NON_CRITICAL",
+    `${event.agent} attempts=${String(event.attempts)}`
+  );
+}
+function handleTimeoutGrace(context, event) {
+  context.logger.log(
+    "TIMEOUT_GRACE_ENTERED",
+    `${event.agent} grace=${String(event.gracePeriodMs)}ms`
+  );
+}
+function handleInspectorStepStart(context, event) {
+  context.logger.log(
+    "INSPECTOR_STEP_START",
+    `step=${String(event.stepIndex)}/${formatOptionalNumber(event.totalSteps)} screen=${event.screenLabel}`
+  );
+}
+function handleInspectorStep(context, event) {
+  context.logger.log(
+    "INSPECTOR_STEP",
+    `step=${String(event.stepIndex)} screen=${event.screenLabel} outcome=${event.outcome}`
+  );
+}
+function handleVisualStep(context, event) {
+  context.logger.log("VISUAL_STEP", `step=${String(event.stepIndex)} screen=${event.screenLabel}`);
+}
+function handleError(context, event) {
+  context.logger.log("ERROR", `${event.agent} ${event.message}`);
+}
+var AGENT_EVENT_HANDLERS = {
+  STAGE_START: handleStageStart,
+  STAGE_END: handleStageEnd,
+  TOOL_CALL: handleToolCall,
+  TOOL_RESULT: handleToolResult,
+  TOOL_ERROR: handleToolError,
+  AGENT_RETRY: handleAgentRetry,
+  AGENT_FAILED_NON_CRITICAL: handleAgentFailed,
+  TIMEOUT_GRACE_ENTERED: handleTimeoutGrace,
+  INSPECTOR_STEP_START: handleInspectorStepStart,
+  INSPECTOR_STEP: handleInspectorStep,
+  VISUAL_STEP: handleVisualStep,
+  ERROR: handleError
+};
+function handleAgentEvent(context, event) {
+  const handler = AGENT_EVENT_HANDLERS[event.type];
+  if (handler === void 0) {
+    return;
+  }
+  handler(context, event);
+}
+
+// src/shell/debug-suite-events.ts
+function handleItemQueued(logger, event) {
+  logger.log("ITEM_QUEUED", `id=${event.item.id} name=${event.item.name}`);
+}
+function handleItemStarted(logger, event) {
+  logger.log(
+    "ITEM_STARTED",
+    `id=${event.itemId} name=${event.itemName} sim=${event.simulatorUdid}`
+  );
+}
+function handleItemCompleted(logger, event) {
+  logger.log(
+    "ITEM_COMPLETED",
+    `id=${event.itemId} findings=${String(event.findingsCount)} duration=${String(event.durationMs)}ms`
+  );
+}
+function handleItemFailed(logger, event) {
+  logger.log(
+    "ITEM_FAILED",
+    `id=${event.itemId} error=${event.error} duration=${String(event.durationMs)}ms`
+  );
+}
+function handleItemTimeout(logger, event) {
+  logger.log("ITEM_TIMEOUT", `id=${event.itemId} duration=${String(event.durationMs)}ms`);
+}
+function handleSimulatorUnhealthy(logger, event) {
+  logger.log(
+    "SIMULATOR_UNHEALTHY",
+    `sim=${event.simulatorUdid} failures=${String(event.consecutiveFailures)}`
+  );
+}
+function handleSuiteCompleted(logger, event) {
+  logger.log(
+    "SUITE_COMPLETED",
+    `items=${String(event.totalItems)} findings=${String(event.totalFindings)} duration=${String(event.durationMs)}ms aborted=${String(event.aborted)}`
+  );
+}
+var SUITE_EVENT_HANDLERS = {
+  ITEM_QUEUED: handleItemQueued,
+  ITEM_STARTED: handleItemStarted,
+  ITEM_COMPLETED: handleItemCompleted,
+  ITEM_FAILED: handleItemFailed,
+  ITEM_TIMEOUT: handleItemTimeout,
+  SIMULATOR_UNHEALTHY: handleSimulatorUnhealthy,
+  SUITE_COMPLETED: handleSuiteCompleted
+};
+function handleSuiteEvent(logger, event) {
+  const handler = SUITE_EVENT_HANDLERS[event.type];
+  if (handler === void 0) {
+    return;
+  }
+  handler(logger, event);
+}
+
+// src/shell/debug-logger.ts
+function passthroughAgent(handler) {
+  return handler;
+}
+function passthroughSuite(handler) {
+  return handler;
+}
+function createDebugLogger(options) {
+  if (options.enabled !== true) {
+    return {
+      wrapAgentHandler: passthroughAgent,
+      wrapSuiteHandler: passthroughSuite
+    };
+  }
+  const logger = buildLogger(options);
+  return {
+    wrapAgentHandler: (handler, scope) => (event) => {
+      handleAgentEvent({ logger, scope }, event);
+      handler(event);
+    },
+    wrapSuiteHandler: (handler) => (event) => {
+      handleSuiteEvent(logger, event);
+      handler(event);
+    }
+  };
+}
+
 // src/shell/trigger-abort.ts
 function triggerAbort() {
   process.kill(process.pid, "SIGINT");
@@ -67353,7 +67684,7 @@ function buildArtifacts(videoPath) {
   return { videoPath, videoPath2x: "", videoPath4x: videoPath, findings: [], snapshots: [] };
 }
 async function checkVideoPathExists(videoPath) {
-  const safeAccess = (0, import_neverthrow35.fromAsyncThrowable)(import_promises16.access, () => ({ type: "FILE_NOT_FOUND" }));
+  const safeAccess = (0, import_neverthrow36.fromAsyncThrowable)(import_promises17.access, () => ({ type: "FILE_NOT_FOUND" }));
   const result = await safeAccess(videoPath);
   return result.isOk();
 }
@@ -67374,20 +67705,32 @@ function handleAnalyseError(state, errorType) {
 `);
   process.exit(1);
 }
-async function runAnalysisAndExit(artifacts, apiKey) {
-  const identity = {
+function buildAnalyseIdentity() {
+  return {
     display: createSoloDisplay(),
     itemId: ITEM_ID,
     itemName: ITEM_NAME,
     simulatorUdid: ""
   };
-  const startedAt = Date.now();
-  emitItemStart(identity, startedAt);
-  const onEvent = (event) => {
+}
+function buildAnalyseEventHandler(identity, debug) {
+  const debugLogger = createDebugLogger({ enabled: debug });
+  const baseHandler = (event) => {
     identity.display.onEvent({ ...event, itemId: ITEM_ID });
   };
+  return debugLogger.wrapAgentHandler(baseHandler);
+}
+async function runAnalysisAndExit(input) {
+  const identity = buildAnalyseIdentity();
+  const startedAt = Date.now();
+  emitItemStart(identity, startedAt);
+  const onEvent = buildAnalyseEventHandler(identity, input.debug);
   const state = { identity, startedAt };
-  const result = await runAnalysis(artifacts, { apiKey, videoVariant: "1x", onEvent });
+  const result = await runAnalysis(input.artifacts, {
+    apiKey: input.apiKey,
+    videoVariant: "1x",
+    onEvent
+  });
   result.match(
     (findings) => {
       handleAnalyseSuccess(state, findings);
@@ -67397,13 +67740,16 @@ async function runAnalysisAndExit(artifacts, apiKey) {
     }
   );
 }
-async function runAnalyseCommand(videoPath, config3) {
+function ensureApiKey(config3) {
   const apiKey = config3.GOOGLE_GENERATIVE_AI_API_KEY ?? "";
   if (!apiKey) {
     process.stderr.write("GOOGLE_GENERATIVE_AI_API_KEY is not set\n");
     process.exit(1);
     return;
   }
+  return apiKey;
+}
+async function resolveVideoPath2(videoPath) {
   if (videoPath === void 0) {
     process.stderr.write('A video path is required. Pass the path printed by "xqa explore".\n');
     process.exit(1);
@@ -67415,11 +67761,26 @@ async function runAnalyseCommand(videoPath, config3) {
     process.exit(1);
     return;
   }
-  await runAnalysisAndExit(buildArtifacts(videoPath), apiKey);
+  return videoPath;
+}
+async function runAnalyseCommand(input) {
+  const apiKey = ensureApiKey(input.config);
+  if (apiKey === void 0) {
+    return;
+  }
+  const videoPath = await resolveVideoPath2(input.videoPath);
+  if (videoPath === void 0) {
+    return;
+  }
+  await runAnalysisAndExit({
+    artifacts: buildArtifacts(videoPath),
+    apiKey,
+    debug: input.debug
+  });
 }
 
 // src/core/completion-generator.ts
-var import_neverthrow36 = __toESM(require_index_cjs(), 1);
+var import_neverthrow37 = __toESM(require_index_cjs(), 1);
 function extractLongFlags(flags) {
   return flags.split(/[\s,]+/).filter((token) => token.startsWith("--"));
 }
@@ -67509,9 +67870,9 @@ complete -F _xqa_completion xqa`;
 }
 function generateCompletion(commands, shell) {
   if (shell !== "bash" && shell !== "zsh") {
-    return (0, import_neverthrow36.err)({ type: "UNSUPPORTED_SHELL", shell });
+    return (0, import_neverthrow37.err)({ type: "UNSUPPORTED_SHELL", shell });
   }
-  return (0, import_neverthrow36.ok)(shell === "zsh" ? generateZshCompletion(commands) : generateBashCompletion(commands));
+  return (0, import_neverthrow37.ok)(shell === "zsh" ? generateZshCompletion(commands) : generateBashCompletion(commands));
 }
 
 // src/commands/completion-command.ts
@@ -67546,39 +67907,19 @@ function runCompletionCommand(program3, shell) {
 // src/commands/explore-command.ts
 var import_node_path10 = __toESM(require("node:path"), 1);
 
-// src/constants.ts
-var MOBILE_IOS_TOOLS = [
-  "mcp__mobile-ios__tap",
-  "mcp__mobile-ios__double_tap",
-  "mcp__mobile-ios__long_press",
-  "mcp__mobile-ios__swipe",
-  "mcp__mobile-ios__type_text",
-  "mcp__mobile-ios__press_button",
-  "mcp__mobile-ios__launch_app",
-  "mcp__mobile-ios__terminate_app",
-  "mcp__mobile-ios__list_apps",
-  "mcp__mobile-ios__screenshot",
-  "mcp__mobile-ios__accessibility_snapshot"
-];
-var ALLOWED_TOOLS = [...MOBILE_IOS_TOOLS];
-var MS_PER_SECOND3 = 1e3;
-var DEFAULT_ABORT_EXIT_CODE = 130;
-var IDB_INSTALL_MESSAGE = "idb is not installed. Run:\n  brew install idb-companion\n  pipx install fb-idb\n";
-var FFMPEG_INSTALL_MESSAGE = "ffmpeg is not installed. Run:\n  brew install ffmpeg\n";
-
 // src/core/last-path.ts
 var import_node_fs4 = require("node:fs");
 var import_node_path8 = __toESM(require("node:path"), 1);
-var import_neverthrow37 = __toESM(require_index_cjs(), 1);
+var import_neverthrow38 = __toESM(require_index_cjs(), 1);
 function resolveLastPath(argument, stateContent) {
   if (argument !== void 0) {
-    return (0, import_neverthrow37.ok)(argument);
+    return (0, import_neverthrow38.ok)(argument);
   }
   const trimmed = stateContent?.trim();
   if (trimmed) {
-    return (0, import_neverthrow37.ok)(trimmed);
+    return (0, import_neverthrow38.ok)(trimmed);
   }
-  return (0, import_neverthrow37.err)({ type: "NO_ARG_AND_NO_STATE" });
+  return (0, import_neverthrow38.err)({ type: "NO_ARG_AND_NO_STATE" });
 }
 function lastPathFilePath(xqaDirectoryectory) {
   return import_node_path8.default.join(xqaDirectoryectory, "last-findings-path");
@@ -67588,9 +67929,9 @@ function writeLastPath(xqaDirectory, findingsPath) {
 }
 
 // src/shell/app-context.ts
-var import_promises17 = require("node:fs/promises");
+var import_promises18 = require("node:fs/promises");
 var import_node_path9 = __toESM(require("node:path"), 1);
-var import_neverthrow38 = __toESM(require_index_cjs(), 1);
+var import_neverthrow39 = __toESM(require_index_cjs(), 1);
 var HTML_COMMENT_PATTERN = /<!--[\s\S]*?-->/g;
 function isEnoentError(value) {
   return value !== null && typeof value === "object" && "code" in value && value.code === "ENOENT";
@@ -67600,10 +67941,10 @@ function toAppContextError(cause) {
 }
 function absentContext() {
   const absent = void 0;
-  return (0, import_neverthrow38.ok)(absent);
+  return (0, import_neverthrow39.ok)(absent);
 }
-var safeReadFile2 = import_neverthrow38.ResultAsync.fromThrowable(
-  async (filePath) => (0, import_promises17.readFile)(filePath, "utf8"),
+var safeReadFile2 = import_neverthrow39.ResultAsync.fromThrowable(
+  async (filePath) => (0, import_promises18.readFile)(filePath, "utf8"),
   toAppContextError
 );
 function stripAndNormalize(content) {
@@ -67616,7 +67957,7 @@ function readContextFile(xqaDirectory, filename) {
     if (isEnoentError(error48.cause)) {
       return absentContext();
     }
-    return (0, import_neverthrow38.err)(error48);
+    return (0, import_neverthrow39.err)(error48);
   });
 }
 function readAppContext(xqaDirectory) {
@@ -67628,7 +67969,7 @@ function readExploreContext(xqaDirectory) {
 
 // src/shell/ffmpeg-check.ts
 var import_node_child_process5 = require("node:child_process");
-var import_neverthrow39 = __toESM(require_index_cjs(), 1);
+var import_neverthrow40 = __toESM(require_index_cjs(), 1);
 async function whichFfmpeg() {
   const { promise: promise2, resolve, reject } = Promise.withResolvers();
   (0, import_node_child_process5.execFile)("which", ["ffmpeg"], (error48, stdout) => {
@@ -67640,7 +67981,7 @@ async function whichFfmpeg() {
   });
   return promise2;
 }
-var safeWhichFfmpeg = (0, import_neverthrow39.fromAsyncThrowable)(
+var safeWhichFfmpeg = (0, import_neverthrow40.fromAsyncThrowable)(
   whichFfmpeg,
   () => ({ type: "FFMPEG_NOT_FOUND" })
 );
@@ -67677,7 +68018,7 @@ function buildExplorerConfig2({
     mode: "freestyle",
     mcpServers: createDefaultMcpServers(),
     allowedTools: ALLOWED_TOOLS,
-    timeoutMs: timeoutSeconds === void 0 ? void 0 : timeoutSeconds * MS_PER_SECOND3,
+    timeoutMs: timeoutSeconds === void 0 ? void 0 : timeoutSeconds * MS_PER_SECOND4,
     appContext,
     initialState: resolvedStartingState,
     buildEnv: config3.QA_BUILD_ENV
@@ -67778,9 +68119,11 @@ function buildExploreRunState({
   simulatorUdid
 }) {
   const { config: config3, xqaDirectory } = options;
-  const onEvent = (event) => {
+  const debugLogger = createDebugLogger({ enabled: input.debug ?? false });
+  const baseHandler = (event) => {
     identity.display.onEvent({ ...event, itemId: ITEM_ID2 });
   };
+  const onEvent = debugLogger.wrapAgentHandler(baseHandler);
   const onSuccess = buildSuccessHandler({ input, xqaDirectory, identity, startedAt });
   const onError = buildErrorHandler(identity, startedAt);
   return { input, config: config3, xqaDirectory, onEvent, onSuccess, onError, simulatorUdid };
@@ -67929,7 +68272,7 @@ function runInitCommand() {
 // src/commands/review-command.ts
 var import_node_fs7 = require("node:fs");
 var import_node_path14 = __toESM(require("node:path"), 1);
-var import_neverthrow41 = __toESM(require_index_cjs(), 1);
+var import_neverthrow42 = __toESM(require_index_cjs(), 1);
 
 // ../../node_modules/.pnpm/@inquirer+core@10.3.2_@types+node@22.19.15/node_modules/@inquirer/core/dist/esm/lib/key.js
 var isUpKey = (key, keybindings = []) => (
@@ -69311,9 +69654,9 @@ var RemoveFileError = class extends Error {
 // ../../node_modules/.pnpm/@inquirer+external-editor@1.0.3_@types+node@22.19.15/node_modules/@inquirer/external-editor/dist/esm/index.js
 function editAsync(text = "", callback, fileOptions) {
   const editor = new ExternalEditor(text, fileOptions);
-  editor.runAsync((err18, result) => {
-    if (err18) {
-      setImmediate(callback, err18, void 0);
+  editor.runAsync((err19, result) => {
+    if (err19) {
+      setImmediate(callback, err19, void 0);
     } else {
       try {
         editor.cleanup();
@@ -70334,7 +70677,7 @@ var esm_default11 = createPrompt((config3, done) => {
 });
 
 // src/review-session.ts
-var import_neverthrow40 = __toESM(require_index_cjs(), 1);
+var import_neverthrow41 = __toESM(require_index_cjs(), 1);
 var CONFIDENCE_PERCENT = 100;
 var FLOW_COL_WIDTH = 35;
 var TRIGGER_COL_WIDTH = 16;
@@ -70487,15 +70830,15 @@ async function runInteractiveLoop(findings, existing) {
   }
   return { staged: state.staged, undoneKeys: state.undoneKeys };
 }
-var safeRunInteractiveLoop = (0, import_neverthrow40.fromAsyncThrowable)(
+var safeRunInteractiveLoop = (0, import_neverthrow41.fromAsyncThrowable)(
   runInteractiveLoop,
   (error48) => error48 instanceof Error && error48.name === "ExitPromptError" ? "exit-prompt" : "unexpected"
 );
 
 // src/commands/review-command.ts
-var safeReadFile3 = (0, import_neverthrow41.fromThrowable)((filePath) => (0, import_node_fs7.readFileSync)(filePath, "utf8"));
-var safeParseJson3 = (0, import_neverthrow41.fromThrowable)(JSON.parse);
-var safeWrite = (0, import_neverthrow41.fromThrowable)((filePath, content) => {
+var safeReadFile3 = (0, import_neverthrow42.fromThrowable)((filePath) => (0, import_node_fs7.readFileSync)(filePath, "utf8"));
+var safeParseJson3 = (0, import_neverthrow42.fromThrowable)(JSON.parse);
+var safeWrite = (0, import_neverthrow42.fromThrowable)((filePath, content) => {
   (0, import_node_fs7.writeFileSync)(filePath, content);
 });
 function readLastPath(xqaDirectory) {
@@ -70512,13 +70855,13 @@ function isPipelineOutput(data) {
 function readFindings(filePath) {
   const readResult = safeReadFile3(filePath);
   if (readResult.isErr()) {
-    return (0, import_neverthrow41.err)("not-found");
+    return (0, import_neverthrow42.err)("not-found");
   }
   return safeParseJson3(readResult.value).mapErr(() => "invalid").andThen((data) => {
     if (!isPipelineOutput(data)) {
-      return (0, import_neverthrow41.err)("invalid");
+      return (0, import_neverthrow42.err)("invalid");
     }
-    return (0, import_neverthrow41.ok)(data);
+    return (0, import_neverthrow42.ok)(data);
   });
 }
 function loadExistingDismissals(filePath) {
@@ -70591,7 +70934,7 @@ function resolveAndReadFindings(findingsPath, xqaDirectory) {
       "No findings path provided and no last path found. Run: xqa review <findings-path>\n"
     );
     process.exit(1);
-    return (0, import_neverthrow41.err)();
+    return (0, import_neverthrow42.err)();
   }
   const resolvedPath = resolvedPathResult.value;
   const findingsResult = readFindings(resolvedPath);
@@ -70604,9 +70947,9 @@ function resolveAndReadFindings(findingsPath, xqaDirectory) {
 `);
     }
     process.exit(1);
-    return (0, import_neverthrow41.err)();
+    return (0, import_neverthrow42.err)();
   }
-  return (0, import_neverthrow41.ok)({ resolvedPath, output: findingsResult.value });
+  return (0, import_neverthrow42.ok)({ resolvedPath, output: findingsResult.value });
 }
 async function runReviewLoop({
   findings,
@@ -70680,40 +71023,40 @@ function stripExtensions(filename) {
 // src/commands/spec-resolver.ts
 var import_node_fs8 = require("node:fs");
 var import_node_path16 = __toESM(require("node:path"), 1);
-var import_neverthrow43 = __toESM(require_index_cjs(), 1);
+var import_neverthrow44 = __toESM(require_index_cjs(), 1);
 
 // src/spec-frontmatter.ts
-var import_neverthrow42 = __toESM(require_index_cjs(), 1);
+var import_neverthrow43 = __toESM(require_index_cjs(), 1);
 var FRONTMATTER_OPEN_LEN = 4;
 var FRONTMATTER_MARKER_LEN = 3;
 function extractFrontmatterBlock(content) {
   const normalized = content.replaceAll("\r\n", "\n");
   if (!normalized.startsWith("---")) {
-    return (0, import_neverthrow42.err)({ type: "MISSING_FRONTMATTER" });
+    return (0, import_neverthrow43.err)({ type: "MISSING_FRONTMATTER" });
   }
   const end = normalized.indexOf("\n---", FRONTMATTER_MARKER_LEN);
   if (end === -1) {
-    return (0, import_neverthrow42.err)({ type: "MISSING_FRONTMATTER" });
+    return (0, import_neverthrow43.err)({ type: "MISSING_FRONTMATTER" });
   }
-  return (0, import_neverthrow42.ok)(normalized.slice(FRONTMATTER_OPEN_LEN, end));
+  return (0, import_neverthrow43.ok)(normalized.slice(FRONTMATTER_OPEN_LEN, end));
 }
 function parseTimeout(fields) {
   const raw = fields.get("timeout");
   if (raw === void 0) {
-    return (0, import_neverthrow42.ok)(raw);
+    return (0, import_neverthrow43.ok)(raw);
   }
   const parsed = Number(raw);
   if (Number.isNaN(parsed) || parsed <= 0) {
-    return (0, import_neverthrow42.err)({ type: "PARSE_ERROR", cause: `invalid timeout: ${raw}` });
+    return (0, import_neverthrow43.err)({ type: "PARSE_ERROR", cause: `invalid timeout: ${raw}` });
   }
-  return (0, import_neverthrow42.ok)(parsed);
+  return (0, import_neverthrow43.ok)(parsed);
 }
 function parseSpecFrontmatter(content) {
   return extractFrontmatterBlock(content).andThen((block) => {
     const fields = parseYamlFields(block);
     const feature = fields.get("feature");
     if (feature === void 0) {
-      return (0, import_neverthrow42.err)({ type: "MISSING_FIELD", field: "feature" });
+      return (0, import_neverthrow43.err)({ type: "MISSING_FIELD", field: "feature" });
     }
     return parseTimeout(fields).map((timeout) => ({ feature, timeout }));
   });
@@ -70735,12 +71078,12 @@ function parseYamlFields(block) {
 }
 
 // src/commands/spec-resolver.ts
-var safeReadFile4 = (0, import_neverthrow43.fromThrowable)((filePath) => (0, import_node_fs8.readFileSync)(filePath, "utf8"));
-var safeReaddir = (0, import_neverthrow43.fromThrowable)(
+var safeReadFile4 = (0, import_neverthrow44.fromThrowable)((filePath) => (0, import_node_fs8.readFileSync)(filePath, "utf8"));
+var safeReaddir = (0, import_neverthrow44.fromThrowable)(
   (directory) => (0, import_node_fs8.readdirSync)(directory, { recursive: true, encoding: "utf8" })
 );
 var CANCEL = "xqa:cancel";
-var safeSelect = import_neverthrow43.ResultAsync.fromThrowable(
+var safeSelect = import_neverthrow44.ResultAsync.fromThrowable(
   esm_default11,
   (error48) => error48 instanceof Error && error48.name === "ExitPromptError" ? "cancelled" : "failed"
 );
@@ -70805,7 +71148,7 @@ function buildSpecExplorer(input, context) {
     specFiles: [context.absolutePath],
     mcpServers: createDefaultMcpServers(),
     allowedTools: ALLOWED_TOOLS,
-    timeoutMs: context.timeout === void 0 ? void 0 : context.timeout * MS_PER_SECOND3,
+    timeoutMs: context.timeout === void 0 ? void 0 : context.timeout * MS_PER_SECOND4,
     appContext: context.appContext,
     buildEnv: context.config.QA_BUILD_ENV
   };
@@ -70864,9 +71207,11 @@ async function executeSpec(input, context) {
   };
   const startedAt = Date.now();
   emitItemStart(identity, startedAt);
-  const onEvent = (event) => {
+  const debugLogger = createDebugLogger({ enabled: input.debug ?? false });
+  const baseHandler = (event) => {
     identity.display.onEvent({ ...event, itemId: identity.itemId });
   };
+  const onEvent = debugLogger.wrapAgentHandler(baseHandler);
   const { onSuccess, onError } = handleSpecResult({ identity, startedAt }, context);
   const result = await runPipeline2(buildPipelineConfig2({ input, context, onEvent }));
   result.match(onSuccess, onError);
@@ -70928,7 +71273,7 @@ function runUpdateCommand() {
 var import_node_path18 = __toESM(require("node:path"), 1);
 var import_node_url2 = require("node:url");
 var import_dotenv = __toESM(require_main(), 1);
-var import_neverthrow44 = __toESM(require_index_cjs(), 1);
+var import_neverthrow45 = __toESM(require_index_cjs(), 1);
 
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/external.js
 var external_exports2 = {};
@@ -71668,8 +72013,8 @@ var ZodType2 = class {
         } : {
           issues: ctx.common.issues
         };
-      } catch (err18) {
-        if (err18?.message?.toLowerCase()?.includes("encountered")) {
+      } catch (err19) {
+        if (err19?.message?.toLowerCase()?.includes("encountered")) {
           this["~standard"].async = true;
         }
         ctx.common = {
@@ -74989,10 +75334,10 @@ function loadConfig() {
     const messages = result.error.issues.map(
       (issue2) => `  - ${issue2.path.join(".")}: ${issue2.message}`
     );
-    return (0, import_neverthrow44.err)({ type: "INVALID_CONFIG", message: `Configuration error:
+    return (0, import_neverthrow45.err)({ type: "INVALID_CONFIG", message: `Configuration error:
 ${messages.join("\n")}` });
   }
-  return (0, import_neverthrow44.ok)(result.data);
+  return (0, import_neverthrow45.ok)(result.data);
 }
 
 // src/core/parse-timeout-seconds.ts
@@ -75025,7 +75370,7 @@ function parseVerboseOption(value) {
 
 // src/pid-lock.ts
 var import_node_fs9 = require("node:fs");
-var import_neverthrow45 = __toESM(require_index_cjs(), 1);
+var import_neverthrow46 = __toESM(require_index_cjs(), 1);
 var PID_FILE = "/tmp/xqa.pid";
 var SIGINT_EXIT_CODE = 130;
 var SIGTERM_EXIT_CODE = 143;
@@ -75034,7 +75379,7 @@ var HARD_TIMEOUT_MS = 1e4;
 var cleanup = () => {
   (0, import_node_fs9.rmSync)(PID_FILE, { force: true });
 };
-var checkProcessRunning = (0, import_neverthrow45.fromThrowable)(
+var checkProcessRunning = (0, import_neverthrow46.fromThrowable)(
   (pid) => {
     process.kill(pid, 0);
     return true;
@@ -75100,27 +75445,27 @@ function acquireLock() {
 // src/shell/xqa-directory.ts
 var import_node_fs10 = require("node:fs");
 var import_node_path19 = __toESM(require("node:path"), 1);
-var import_neverthrow46 = __toESM(require_index_cjs(), 1);
+var import_neverthrow47 = __toESM(require_index_cjs(), 1);
 function findXqaDirectory(startDirectory) {
   let current = startDirectory;
   for (; ; ) {
     const candidate = import_node_path19.default.join(current, ".xqa");
     if ((0, import_node_fs10.existsSync)(candidate)) {
-      return (0, import_neverthrow46.ok)(candidate);
+      return (0, import_neverthrow47.ok)(candidate);
     }
     const parent = import_node_path19.default.dirname(current);
     if (parent === current) {
-      return (0, import_neverthrow46.err)({ type: "XQA_NOT_INITIALIZED" });
+      return (0, import_neverthrow47.err)({ type: "XQA_NOT_INITIALIZED" });
     }
     current = parent;
   }
 }
 
 // src/suite/commands/run-command.ts
-var import_promises19 = __toESM(require("node:fs/promises"), 1);
+var import_promises20 = __toESM(require("node:fs/promises"), 1);
 var import_node_path22 = __toESM(require("node:path"), 1);
 var import_fast_glob = __toESM(require_out4(), 1);
-var import_neverthrow51 = __toESM(require_index_cjs(), 1);
+var import_neverthrow52 = __toESM(require_index_cjs(), 1);
 
 // src/suite/core/run-id.ts
 var RUN_ID_PAD_LENGTH2 = 4;
@@ -75143,8 +75488,8 @@ function computeNextRunId(existingDirectories) {
 }
 
 // src/suite/core/suite-config-parser.ts
-var import_neverthrow47 = __toESM(require_index_cjs(), 1);
 var import_neverthrow48 = __toESM(require_index_cjs(), 1);
+var import_neverthrow49 = __toESM(require_index_cjs(), 1);
 var freestyleEntrySchema = external_exports2.object({
   prompt: external_exports2.string().optional(),
   timeoutSeconds: external_exports2.number().int().positive()
@@ -75163,7 +75508,7 @@ var suiteConfigSchema = external_exports2.object({
   specs: external_exports2.array(external_exports2.string()).nonempty(),
   freestyle: freestyleSchema
 });
-var safeJsonParse4 = (0, import_neverthrow47.fromThrowable)(
+var safeJsonParse4 = (0, import_neverthrow48.fromThrowable)(
   JSON.parse,
   (cause) => ({
     type: "INVALID_SUITE_CONFIG",
@@ -75174,9 +75519,9 @@ function parseSuiteConfig(raw) {
   return safeJsonParse4(raw).andThen((data) => {
     const parsed = suiteConfigSchema.safeParse(data);
     if (!parsed.success) {
-      return (0, import_neverthrow48.err)({ type: "INVALID_SUITE_CONFIG", cause: parsed.error });
+      return (0, import_neverthrow49.err)({ type: "INVALID_SUITE_CONFIG", cause: parsed.error });
     }
-    return (0, import_neverthrow48.ok)({ specs: parsed.data.specs, freestyle: parsed.data.freestyle });
+    return (0, import_neverthrow49.ok)({ specs: parsed.data.specs, freestyle: parsed.data.freestyle });
   });
 }
 
@@ -75240,9 +75585,9 @@ function buildFreestyleItems(entries) {
 }
 
 // src/suite/shell/suite-findings-writer.ts
-var import_promises18 = __toESM(require("node:fs/promises"), 1);
+var import_promises19 = __toESM(require("node:fs/promises"), 1);
 var import_node_path20 = __toESM(require("node:path"), 1);
-var import_neverthrow49 = __toESM(require_index_cjs(), 1);
+var import_neverthrow50 = __toESM(require_index_cjs(), 1);
 var INDENT_SPACES = 2;
 function writeSuiteFindings(findings, options) {
   const directory = import_node_path20.default.join(
@@ -75254,11 +75599,11 @@ function writeSuiteFindings(findings, options) {
   );
   const finalPath = import_node_path20.default.join(directory, "findings.json");
   const temporaryPath = `${finalPath}.tmp`;
-  const safeWriteAtomically = import_neverthrow49.ResultAsync.fromThrowable(
+  const safeWriteAtomically = import_neverthrow50.ResultAsync.fromThrowable(
     async () => {
-      await import_promises18.default.mkdir(directory, { recursive: true });
-      await import_promises18.default.writeFile(temporaryPath, JSON.stringify(findings, void 0, INDENT_SPACES));
-      await import_promises18.default.rename(temporaryPath, finalPath);
+      await import_promises19.default.mkdir(directory, { recursive: true });
+      await import_promises19.default.writeFile(temporaryPath, JSON.stringify(findings, void 0, INDENT_SPACES));
+      await import_promises19.default.rename(temporaryPath, finalPath);
       return finalPath;
     },
     (cause) => ({ type: "FINDINGS_WRITE_FAILED", cause })
@@ -75267,7 +75612,7 @@ function writeSuiteFindings(findings, options) {
 }
 
 // src/suite/shell/worker-pool.ts
-var import_neverthrow50 = __toESM(require_index_cjs(), 1);
+var import_neverthrow51 = __toESM(require_index_cjs(), 1);
 
 // src/suite/shell/item-result-builder.ts
 function getErrorMessage(cause) {
@@ -75495,7 +75840,7 @@ function runWorkerPool(config3) {
   const queue = setupQueue(config3);
   const results = [];
   const suiteStartMs = Date.now();
-  const safeRun = import_neverthrow50.ResultAsync.fromThrowable(
+  const safeRun = import_neverthrow51.ResultAsync.fromThrowable(
     async () => runAllWorkers({ config: config3, queue, results, suiteStartMs }),
     (cause) => ({ type: "WORKER_POOL_FAILED", cause })
   );
@@ -75535,7 +75880,7 @@ function buildFreestylePipelineConfig(input) {
       date: date5,
       mcpServers: createDefaultMcpServers(simulatorUdid),
       allowedTools: ALLOWED_TOOLS,
-      timeoutMs: resolveFreestyleTimeout(item, config3) * MS_PER_SECOND3,
+      timeoutMs: resolveFreestyleTimeout(item, config3) * MS_PER_SECOND4,
       appContext: item.prompt ? `${buildDeviceInstruction(simulatorUdid)}
 
 ${item.prompt}` : buildDeviceInstruction(simulatorUdid),
@@ -75582,15 +75927,15 @@ function makeExecuteItem(context) {
 
 // src/suite/commands/run-command.ts
 var ISO_DATE_LENGTH3 = 10;
-var safeReaddir2 = import_neverthrow51.ResultAsync.fromThrowable(
+var safeReaddir2 = import_neverthrow52.ResultAsync.fromThrowable(
   async (directoryPath) => {
-    const entries = await import_promises19.default.readdir(directoryPath, { withFileTypes: true });
+    const entries = await import_promises20.default.readdir(directoryPath, { withFileTypes: true });
     return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
   },
   () => "READDIR_FAILED"
 );
-var safeReadFile5 = import_neverthrow51.ResultAsync.fromThrowable(
-  async (filePath) => import_promises19.default.readFile(filePath, "utf8"),
+var safeReadFile5 = import_neverthrow52.ResultAsync.fromThrowable(
+  async (filePath) => import_promises20.default.readFile(filePath, "utf8"),
   () => "READ_FAILED"
 );
 async function listRunDirectories(input) {
@@ -75662,17 +76007,21 @@ async function discoverSimulators() {
   return { simulators: result.value, exitCode: 0 };
 }
 async function runPool(input) {
-  const { context, items, simulatorUdids, signal } = input;
+  const { context, items, simulatorUdids, debug, signal } = input;
   const display = createSuiteDisplay();
+  const debugLogger = createDebugLogger({ enabled: debug });
+  const baseObserver = (event) => {
+    display.onEvent(event);
+  };
+  const observer = debugLogger.wrapSuiteHandler(baseObserver);
+  const buildItemHandler = (itemId) => debugLogger.wrapAgentHandler((event) => {
+    display.onEvent({ ...event, itemId });
+  }, itemId);
   const poolResult = await runWorkerPool({
     items,
     simulatorUdids,
-    observer: (event) => {
-      display.onEvent(event);
-    },
-    onEvent: (itemId) => (event) => {
-      display.onEvent({ ...event, itemId });
-    },
+    observer,
+    onEvent: buildItemHandler,
     executeItem: makeExecuteItem(context),
     signal
   });
@@ -75710,22 +76059,31 @@ async function buildSuiteRunContext(input) {
   };
   return { suiteId, date: date5, outputDirectory, runId, context };
 }
+async function executePool(input, runContext) {
+  const { items, simulatorUdids, debug, signal } = input;
+  return runPool({
+    context: runContext.context,
+    items,
+    simulatorUdids,
+    debug,
+    signal
+  });
+}
 async function runSuite(input) {
-  const { items, simulatorUdids, signal } = input;
-  const { suiteId, date: date5, outputDirectory, runId, context } = await buildSuiteRunContext(input);
-  const poolResult = await runPool({ context, items, simulatorUdids, signal });
+  const runContext = await buildSuiteRunContext(input);
+  const poolResult = await executePool(input, runContext);
   if (poolResult.isErr()) {
     process.stderr.write(`Suite runner failed: ${String(poolResult.error.cause)}
 `);
     return 1;
   }
   return writeAndReport({
-    suiteId,
-    runId,
-    outputDirectory,
-    date: date5,
+    suiteId: runContext.suiteId,
+    runId: runContext.runId,
+    outputDirectory: runContext.outputDirectory,
+    date: runContext.date,
     items: poolResult.value,
-    aborted: signal.aborted
+    aborted: input.signal.aborted
   });
 }
 async function runSuiteCommand(input) {
@@ -75771,7 +76129,7 @@ function resolveXqaDirectory() {
   return result.value;
 }
 var program2 = new Command();
-program2.name("xqa").description("AI-powered QA agent CLI").version(`${"1.9.0"}${false ? ` (dev build +${"0938687"})` : ""}`);
+program2.name("xqa").description("AI-powered QA agent CLI").version(`${"1.10.0"}${false ? ` (dev build +${"e25bb70"})` : ""}`);
 program2.command("init").description("Initialize a new xqa project in the current directory").action(() => {
   runInitCommand();
 });
@@ -75786,20 +76144,23 @@ program2.command("explore").description("Run the explorer agent; omit prompt for
   "-t, --timeout <seconds>",
   "Explorer timeout in seconds (overrides QA_EXPLORE_TIMEOUT_SECONDS)",
   parseTimeoutSeconds
-).action((prompt, options) => {
-  const xqaDirectory = resolveXqaDirectory();
-  runExploreCommand(
-    {
-      prompt,
-      verbose: options.verbose,
-      timeoutSeconds: options.timeout,
-      signal: controller.signal
-    },
-    { config: config2, xqaDirectory }
-  );
-});
-program2.command("analyse").description("Analyse a session recording with Gemini").argument("[video-path]", "Path to video file").action((videoPath) => {
-  void runAnalyseCommand(videoPath, config2);
+).option("--debug", "Log timing and event details to stderr").action(
+  (prompt, options) => {
+    const xqaDirectory = resolveXqaDirectory();
+    runExploreCommand(
+      {
+        prompt,
+        verbose: options.verbose,
+        timeoutSeconds: options.timeout,
+        debug: options.debug ?? false,
+        signal: controller.signal
+      },
+      { config: config2, xqaDirectory }
+    );
+  }
+);
+program2.command("analyse").description("Analyse a session recording with Gemini").argument("[video-path]", "Path to video file").option("--debug", "Log timing and event details to stderr").action((videoPath, options) => {
+  void runAnalyseCommand({ videoPath, config: config2, debug: options.debug ?? false });
 });
 program2.command("completion").description("Output shell completion script").argument("<shell>", "Shell to generate completion for (bash, zsh)").action((shell) => {
   runCompletionCommand(program2, shell);
@@ -75812,14 +76173,19 @@ program2.command("spec").description("Run the explorer agent against a spec file
   "-v, --verbose [categories]",
   "Verbose output [prompt,tools,screen,memory] (default: all)",
   parseVerboseOption
-).action((specFile, options) => {
+).option("--debug", "Log timing and event details to stderr").action((specFile, options) => {
   const xqaDirectory = resolveXqaDirectory();
   void runSpecCommand(
-    { specFile, verbose: options.verbose, signal: controller.signal },
+    {
+      specFile,
+      verbose: options.verbose,
+      debug: options.debug ?? false,
+      signal: controller.signal
+    },
     { config: config2, xqaDirectory }
   );
 });
-program2.command("run").description("Run a test suite or a set of spec files").option("--suite <name>", "Name of the suite to run").option("--spec <globs...>", "Glob patterns matching spec files to run").action(async (options) => {
+program2.command("run").description("Run a test suite or a set of spec files").option("--suite <name>", "Name of the suite to run").option("--spec <globs...>", "Glob patterns matching spec files to run").option("--debug", "Log timing and event details to stderr").action(async (options) => {
   if (options.suite === void 0 === (options.spec === void 0)) {
     process.stderr.write("Exactly one of --suite or --spec must be provided\n");
     process.exit(1);
@@ -75830,6 +76196,7 @@ program2.command("run").description("Run a test suite or a set of spec files").o
     mode,
     xqaDirectory,
     config: config2,
+    debug: options.debug ?? false,
     signal: controller.signal
   });
   process.exit(exitCode);