@exodus/xqa 1.9.0 → 1.11.0

package/dist/xqa.cjs

@@ -1194,8 +1194,8 @@ var require_command = __commonJS({
   "../../node_modules/.pnpm/commander@14.0.3/node_modules/commander/lib/command.js"(exports2) {
     var EventEmitter = require("node:events").EventEmitter;
     var childProcess = require("node:child_process");
-    var path23 = require("node:path");
-    var fs3 = require("node:fs");
+    var path24 = require("node:path");
+    var fs4 = require("node:fs");
     var process6 = require("node:process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
@@ -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 = (err20) => {
+            if (err20.code !== "commander.executeSubCommandAsync") {
+              throw err20;
             } 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 (err20) {
+          if (err20.code === "commander.invalidArgument") {
+            const message = `${invalidArgumentMessage} ${err20.message}`;
+            this.error(message, { exitCode: err20.exitCode, code: err20.code });
           }
-          throw err18;
+          throw err20;
         }
       }
       /**
@@ -2189,7 +2189,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} subcommandName
        */
       _checkForMissingExecutable(executableFile, executableDir, subcommandName) {
-        if (fs3.existsSync(executableFile)) return;
+        if (fs4.existsSync(executableFile)) return;
         const executableDirMessage = executableDir ? `searched for local subcommand relative to directory '${executableDir}'` : "no directory for search for local subcommand, use .executableDir() to supply a custom directory";
         const executableMissing = `'${executableFile}' does not exist
  - if '${subcommandName}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead
@@ -2207,11 +2207,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let launchWithNode = false;
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
-          const localBin = path23.resolve(baseDir, baseName);
-          if (fs3.existsSync(localBin)) return localBin;
-          if (sourceExt.includes(path23.extname(baseName))) return void 0;
+          const localBin = path24.resolve(baseDir, baseName);
+          if (fs4.existsSync(localBin)) return localBin;
+          if (sourceExt.includes(path24.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
-            (ext) => fs3.existsSync(`${localBin}${ext}`)
+            (ext) => fs4.existsSync(`${localBin}${ext}`)
           );
           if (foundExt) return `${localBin}${foundExt}`;
           return void 0;
@@ -2223,21 +2223,21 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._scriptPath) {
           let resolvedScriptPath;
           try {
-            resolvedScriptPath = fs3.realpathSync(this._scriptPath);
+            resolvedScriptPath = fs4.realpathSync(this._scriptPath);
           } catch {
             resolvedScriptPath = this._scriptPath;
           }
-          executableDir = path23.resolve(
-            path23.dirname(resolvedScriptPath),
+          executableDir = path24.resolve(
+            path24.dirname(resolvedScriptPath),
             executableDir
           );
         }
         if (executableDir) {
           let localFile = findFile(executableDir, executableFile);
           if (!localFile && !subcommand._executableFile && this._scriptPath) {
-            const legacyName = path23.basename(
+            const legacyName = path24.basename(
               this._scriptPath,
-              path23.extname(this._scriptPath)
+              path24.extname(this._scriptPath)
             );
             if (legacyName !== this._name) {
               localFile = findFile(
@@ -2248,7 +2248,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           }
           executableFile = localFile || executableFile;
         }
-        launchWithNode = sourceExt.includes(path23.extname(executableFile));
+        launchWithNode = sourceExt.includes(path24.extname(executableFile));
         let proc;
         if (process6.platform !== "win32") {
           if (launchWithNode) {
@@ -2293,14 +2293,14 @@ Expecting one of '${allowedValues.join("', '")}'`);
             );
           }
         });
-        proc.on("error", (err18) => {
-          if (err18.code === "ENOENT") {
+        proc.on("error", (err20) => {
+          if (err20.code === "ENOENT") {
             this._checkForMissingExecutable(
               executableFile,
               executableDir,
               subcommand._name
             );
-          } else if (err18.code === "EACCES") {
+          } else if (err20.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 = err20;
             exitCallback(wrappedError);
           }
         });
@@ -3163,7 +3163,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @return {Command}
        */
       nameFromFilename(filename) {
-        this._name = path23.basename(filename, path23.extname(filename));
+        this._name = path24.basename(filename, path24.extname(filename));
         return this;
       }
       /**
@@ -3177,9 +3177,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} [path]
        * @return {(string|null|Command)}
        */
-      executableDir(path24) {
-        if (path24 === void 0) return this._executableDir;
-        this._executableDir = path24;
+      executableDir(path25) {
+        if (path25 === void 0) return this._executableDir;
+        this._executableDir = path25;
         return this;
       }
       /**
@@ -3539,11 +3539,11 @@ var require_index_cjs = __commonJS({
         try {
           step(g3[n3](v2));
         } catch (e3) {
-          settle(q4[0][3], e3);
+          settle2(q4[0][3], e3);
         }
       }
       function step(r3) {
-        r3.value instanceof __await2 ? Promise.resolve(r3.value.v).then(fulfill, reject) : settle(q4[0][2], r3);
+        r3.value instanceof __await2 ? Promise.resolve(r3.value.v).then(fulfill, reject) : settle2(q4[0][2], r3);
       }
       function fulfill(value) {
         resume("next", value);
@@ -3551,7 +3551,7 @@ var require_index_cjs = __commonJS({
       function reject(value) {
         resume("throw", value);
       }
-      function settle(f6, v2) {
+      function settle2(f6, v2) {
         if (f6(v2), q4.shift(), q4.length) resume(q4[0][0], q4[0][1]);
       }
     }
@@ -3577,17 +3577,17 @@ var require_index_cjs = __commonJS({
       function verb(n3) {
         i3[n3] = o3[n3] && function(v2) {
           return new Promise(function(resolve, reject) {
-            v2 = o3[n3](v2), settle(resolve, reject, v2.done, v2.value);
+            v2 = o3[n3](v2), settle2(resolve, reject, v2.done, v2.value);
           });
         };
       }
-      function settle(resolve, reject, d, v2) {
+      function settle2(resolve, reject, d, v2) {
         Promise.resolve(v2).then(function(v3) {
           resolve({ value: v3, done: d });
         }, reject);
       }
     }
-    var ResultAsync12 = class _ResultAsync {
+    var ResultAsync14 = class _ResultAsync {
       constructor(res) {
         this._promise = res;
       }
@@ -3688,8 +3688,8 @@ var require_index_cjs = __commonJS({
           return new Ok(res.value);
         })));
       }
-      match(ok20, _err) {
-        return this._promise.then((res) => res.match(ok20, _err));
+      match(ok24, _err) {
+        return this._promise.then((res) => res.match(ok24, _err));
       }
       unwrapOr(t) {
         return this._promise.then((res) => res.unwrapOr(t));
@@ -3726,19 +3726,19 @@ var require_index_cjs = __commonJS({
       }
     };
     function okAsync8(value) {
-      return new ResultAsync12(Promise.resolve(new Ok(value)));
+      return new ResultAsync14(Promise.resolve(new Ok(value)));
     }
-    function errAsync8(err19) {
-      return new ResultAsync12(Promise.resolve(new Err(err19)));
+    function errAsync8(err21) {
+      return new ResultAsync14(Promise.resolve(new Err(err21)));
     }
-    var fromPromise = ResultAsync12.fromPromise;
-    var fromSafePromise2 = ResultAsync12.fromSafePromise;
-    var fromAsyncThrowable10 = ResultAsync12.fromThrowable;
+    var fromPromise = ResultAsync14.fromPromise;
+    var fromSafePromise2 = ResultAsync14.fromSafePromise;
+    var fromAsyncThrowable10 = ResultAsync14.fromThrowable;
     var combineResultList = (resultList) => {
-      let acc = ok19([]);
+      let acc = ok21([]);
       for (const result of resultList) {
         if (result.isErr()) {
-          acc = err18(result.error);
+          acc = err20(result.error);
           break;
         } else {
           acc.map((list) => list.push(result.value));
@@ -3746,34 +3746,34 @@ var require_index_cjs = __commonJS({
       }
       return acc;
     };
-    var combineResultAsyncList = (asyncResultList) => ResultAsync12.fromSafePromise(Promise.all(asyncResultList)).andThen(combineResultList);
+    var combineResultAsyncList = (asyncResultList) => ResultAsync14.fromSafePromise(Promise.all(asyncResultList)).andThen(combineResultList);
     var combineResultListWithAllErrors = (resultList) => {
-      let acc = ok19([]);
+      let acc = ok21([]);
       for (const result of resultList) {
         if (result.isErr() && acc.isErr()) {
           acc.error.push(result.error);
         } else if (result.isErr() && acc.isOk()) {
-          acc = err18([result.error]);
+          acc = err20([result.error]);
         } else if (result.isOk() && acc.isOk()) {
           acc.value.push(result.value);
         }
       }
       return acc;
     };
-    var combineResultAsyncListWithAllErrors = (asyncResultList) => ResultAsync12.fromSafePromise(Promise.all(asyncResultList)).andThen(combineResultListWithAllErrors);
+    var combineResultAsyncListWithAllErrors = (asyncResultList) => ResultAsync14.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);
+            return ok21(result);
           } catch (e3) {
-            return err18(errorFn ? errorFn(e3) : e3);
+            return err20(errorFn ? errorFn(e3) : e3);
           }
         };
       }
-      Result3.fromThrowable = fromThrowable14;
+      Result3.fromThrowable = fromThrowable16;
       function combine(resultList) {
         return combineResultList(resultList);
       }
@@ -3783,16 +3783,16 @@ var require_index_cjs = __commonJS({
       }
       Result3.combineWithAllErrors = combineWithAllErrors;
     })(exports2.Result || (exports2.Result = {}));
-    function ok19(value) {
+    function ok21(value) {
       return new Ok(value);
     }
-    function err18(err19) {
-      return new Err(err19);
+    function err20(err21) {
+      return new Err(err21);
     }
     function safeTry(body) {
       const n3 = body().next();
       if (n3 instanceof Promise) {
-        return new ResultAsync12(n3.then((r3) => r3.value));
+        return new ResultAsync14(n3.then((r3) => r3.value));
       }
       return n3.value;
     }
@@ -3807,11 +3807,11 @@ var require_index_cjs = __commonJS({
         return !this.isOk();
       }
       map(f6) {
-        return ok19(f6(this.value));
+        return ok21(f6(this.value));
       }
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
       mapErr(_f) {
-        return ok19(this.value);
+        return ok21(this.value);
       }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types
       andThen(f6) {
@@ -3826,14 +3826,14 @@ var require_index_cjs = __commonJS({
           f6(this.value);
         } catch (e3) {
         }
-        return ok19(this.value);
+        return ok21(this.value);
       }
       orTee(_f) {
-        return ok19(this.value);
+        return ok21(this.value);
       }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types
       orElse(_f) {
-        return ok19(this.value);
+        return ok21(this.value);
       }
       asyncAndThen(f6) {
         return f6(this.value);
@@ -3843,15 +3843,15 @@ var require_index_cjs = __commonJS({
         return f6(this.value).map(() => this.value);
       }
       asyncMap(f6) {
-        return ResultAsync12.fromSafePromise(f6(this.value));
+        return ResultAsync14.fromSafePromise(f6(this.value));
       }
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
       unwrapOr(_v) {
         return this.value;
       }
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      match(ok20, _err) {
-        return ok20(this.value);
+      match(ok24, _err) {
+        return ok24(this.value);
       }
       safeUnwrap() {
         const value = this.value;
@@ -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 err20(this.error);
       }
       mapErr(f6) {
-        return err18(f6(this.error));
+        return err20(f6(this.error));
       }
       andThrough(_f) {
-        return err18(this.error);
+        return err20(this.error);
       }
       andTee(_f) {
-        return err18(this.error);
+        return err20(this.error);
       }
       orTee(f6) {
         try {
           f6(this.error);
         } catch (e3) {
         }
-        return err18(this.error);
+        return err20(this.error);
       }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types
       andThen(_f) {
-        return err18(this.error);
+        return err20(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, err21) {
+        return err21(this.error);
       }
       safeUnwrap() {
         const error48 = this.error;
         return (function* () {
-          yield err18(error48);
+          yield err20(error48);
           throw new Error("Do not use this generator out of `safeTry`");
         })();
       }
@@ -3944,17 +3944,17 @@ 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.ResultAsync = ResultAsync14;
+    exports2.err = err20;
     exports2.errAsync = errAsync8;
     exports2.fromAsyncThrowable = fromAsyncThrowable10;
     exports2.fromPromise = fromPromise;
     exports2.fromSafePromise = fromSafePromise2;
-    exports2.fromThrowable = fromThrowable13;
-    exports2.ok = ok19;
+    exports2.fromThrowable = fromThrowable15;
+    exports2.ok = ok21;
     exports2.okAsync = okAsync8;
     exports2.safeTry = safeTry;
   }
@@ -5052,15 +5052,15 @@ var require_route = __commonJS({
       };
     }
     function wrapConversion(toModel, graph) {
-      const path23 = [graph[toModel].parent, toModel];
+      const path24 = [graph[toModel].parent, toModel];
       let fn = conversions[graph[toModel].parent][toModel];
       let cur = graph[toModel].parent;
       while (graph[cur].parent) {
-        path23.unshift(graph[cur].parent);
+        path24.unshift(graph[cur].parent);
         fn = link(conversions[graph[cur].parent][cur], fn);
         cur = graph[cur].parent;
       }
-      fn.conversion = path23;
+      fn.conversion = path24;
       return fn;
     }
     module2.exports = function(fromModel) {
@@ -11116,13 +11116,13 @@ var require_lib2 = __commonJS({
     exports2.analyse = analyse;
     var detectFile = (filepath, opts = {}) => new Promise((resolve, reject) => {
       let fd;
-      const fs3 = (0, node_1.default)();
-      const handler = (err18, buffer) => {
+      const fs4 = (0, node_1.default)();
+      const handler = (err20, buffer) => {
         if (fd) {
-          fs3.closeSync(fd);
+          fs4.closeSync(fd);
         }
-        if (err18) {
-          reject(err18);
+        if (err20) {
+          reject(err20);
         } else if (buffer) {
           resolve((0, exports2.detect)(buffer));
         } else {
@@ -11131,11 +11131,11 @@ var require_lib2 = __commonJS({
       };
       const sampleSize = (opts === null || opts === void 0 ? void 0 : opts.sampleSize) || 0;
       if (sampleSize > 0) {
-        fd = fs3.openSync(filepath, "r");
+        fd = fs4.openSync(filepath, "r");
         let sample = Buffer.allocUnsafe(sampleSize);
-        fs3.read(fd, sample, 0, sampleSize, opts.offset, (err18, bytesRead) => {
-          if (err18) {
-            handler(err18, null);
+        fs4.read(fd, sample, 0, sampleSize, opts.offset, (err20, bytesRead) => {
+          if (err20) {
+            handler(err20, null);
           } else {
             if (bytesRead < sampleSize) {
               sample = sample.subarray(0, bytesRead);
@@ -11145,22 +11145,22 @@ var require_lib2 = __commonJS({
         });
         return;
       }
-      fs3.readFile(filepath, handler);
+      fs4.readFile(filepath, handler);
     });
     exports2.detectFile = detectFile;
     var detectFileSync = (filepath, opts = {}) => {
-      const fs3 = (0, node_1.default)();
+      const fs4 = (0, node_1.default)();
       if (opts && opts.sampleSize) {
-        const fd = fs3.openSync(filepath, "r");
+        const fd = fs4.openSync(filepath, "r");
         let sample = Buffer.allocUnsafe(opts.sampleSize);
-        const bytesRead = fs3.readSync(fd, sample, 0, opts.sampleSize, opts.offset);
+        const bytesRead = fs4.readSync(fd, sample, 0, opts.sampleSize, opts.offset);
         if (bytesRead < opts.sampleSize) {
           sample = sample.subarray(0, bytesRead);
         }
-        fs3.closeSync(fd);
+        fs4.closeSync(fd);
         return (0, exports2.detect)(sample);
       }
-      return (0, exports2.detect)(fs3.readFileSync(filepath));
+      return (0, exports2.detect)(fs4.readFileSync(filepath));
     };
     exports2.detectFileSync = detectFileSync;
     exports2.default = {
@@ -15025,8 +15025,8 @@ var require_package = __commonJS({
 // ../../node_modules/.pnpm/dotenv@16.6.1/node_modules/dotenv/lib/main.js
 var require_main = __commonJS({
   "../../node_modules/.pnpm/dotenv@16.6.1/node_modules/dotenv/lib/main.js"(exports2, module2) {
-    var fs3 = require("fs");
-    var path23 = require("path");
+    var fs4 = require("fs");
+    var path24 = require("path");
     var os4 = require("os");
     var crypto = require("crypto");
     var packageJson = require_package();
@@ -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 err20 = new Error(`MISSING_DATA: Cannot parse ${vaultPath} for an unknown reason`);
+        err20.code = "MISSING_DATA";
+        throw err20;
       }
       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 err20 = new Error("INVALID_DOTENV_KEY: Wrong format. Must be in valid uri format like dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=development");
+          err20.code = "INVALID_DOTENV_KEY";
+          throw err20;
         }
         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 err20 = new Error("INVALID_DOTENV_KEY: Missing key part");
+        err20.code = "INVALID_DOTENV_KEY";
+        throw err20;
       }
       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 err20 = new Error("INVALID_DOTENV_KEY: Missing environment part");
+        err20.code = "INVALID_DOTENV_KEY";
+        throw err20;
       }
       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 err20 = new Error(`NOT_FOUND_DOTENV_ENVIRONMENT: Cannot locate environment ${environmentKey} in your .env.vault file.`);
+        err20.code = "NOT_FOUND_DOTENV_ENVIRONMENT";
+        throw err20;
       }
       return { ciphertext, key };
     }
@@ -15134,7 +15134,7 @@ var require_main = __commonJS({
       if (options && options.path && options.path.length > 0) {
         if (Array.isArray(options.path)) {
           for (const filepath of options.path) {
-            if (fs3.existsSync(filepath)) {
+            if (fs4.existsSync(filepath)) {
               possibleVaultPath = filepath.endsWith(".vault") ? filepath : `${filepath}.vault`;
             }
           }
@@ -15142,15 +15142,15 @@ var require_main = __commonJS({
           possibleVaultPath = options.path.endsWith(".vault") ? options.path : `${options.path}.vault`;
         }
       } else {
-        possibleVaultPath = path23.resolve(process.cwd(), ".env.vault");
+        possibleVaultPath = path24.resolve(process.cwd(), ".env.vault");
       }
-      if (fs3.existsSync(possibleVaultPath)) {
+      if (fs4.existsSync(possibleVaultPath)) {
         return possibleVaultPath;
       }
       return null;
     }
     function _resolveHome(envPath) {
-      return envPath[0] === "~" ? path23.join(os4.homedir(), envPath.slice(1)) : envPath;
+      return envPath[0] === "~" ? path24.join(os4.homedir(), envPath.slice(1)) : envPath;
     }
     function _configVault(options) {
       const debug = Boolean(options && options.debug);
@@ -15167,7 +15167,7 @@ var require_main = __commonJS({
       return { parsed };
     }
     function configDotenv(options) {
-      const dotenvPath = path23.resolve(process.cwd(), ".env");
+      const dotenvPath = path24.resolve(process.cwd(), ".env");
       let encoding = "utf8";
       const debug = Boolean(options && options.debug);
       const quiet = options && "quiet" in options ? options.quiet : true;
@@ -15191,13 +15191,13 @@ var require_main = __commonJS({
       }
       let lastError;
       const parsedAll = {};
-      for (const path24 of optionPaths) {
+      for (const path25 of optionPaths) {
         try {
-          const parsed = DotenvModule.parse(fs3.readFileSync(path24, { encoding }));
+          const parsed = DotenvModule.parse(fs4.readFileSync(path25, { encoding }));
           DotenvModule.populate(parsedAll, parsed, options);
         } catch (e3) {
           if (debug) {
-            _debug(`Failed to load ${path24} ${e3.message}`);
+            _debug(`Failed to load ${path25} ${e3.message}`);
           }
           lastError = e3;
         }
@@ -15212,7 +15212,7 @@ var require_main = __commonJS({
         const shortPaths = [];
         for (const filePath of optionPaths) {
           try {
-            const relative = path23.relative(process.cwd(), filePath);
+            const relative = path24.relative(process.cwd(), filePath);
             shortPaths.push(relative);
           } catch (e3) {
             if (debug) {
@@ -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 err20 = new Error("INVALID_DOTENV_KEY: It must be 64 characters long (or more)");
+          err20.code = "INVALID_DOTENV_KEY";
+          throw err20;
         } else if (decryptionFailed) {
-          const err18 = new Error("DECRYPTION_FAILED: Please check your DOTENV_KEY");
-          err18.code = "DECRYPTION_FAILED";
-          throw err18;
+          const err20 = new Error("DECRYPTION_FAILED: Please check your DOTENV_KEY");
+          err20.code = "DECRYPTION_FAILED";
+          throw err20;
         } 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 err20 = new Error("OBJECT_REQUIRED: Please check the processEnv argument being passed to populate");
+        err20.code = "OBJECT_REQUIRED";
+        throw err20;
       }
       for (const key of Object.keys(parsed)) {
         if (Object.prototype.hasOwnProperty.call(processEnv, key)) {
@@ -15384,7 +15384,7 @@ var require_path = __commonJS({
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.convertPosixPathToPattern = exports2.convertWindowsPathToPattern = exports2.convertPathToPattern = exports2.escapePosixPath = exports2.escapeWindowsPath = exports2.escape = exports2.removeLeadingDotSegment = exports2.makeAbsolute = exports2.unixify = void 0;
     var os4 = require("os");
-    var path23 = require("path");
+    var path24 = require("path");
     var IS_WINDOWS_PLATFORM = os4.platform() === "win32";
     var LEADING_DOT_SEGMENT_CHARACTERS_COUNT = 2;
     var POSIX_UNESCAPED_GLOB_SYMBOLS_RE = /(\\?)([()*?[\]{|}]|^!|[!+@](?=\()|\\(?![!()*+?@[\]{|}]))/g;
@@ -15396,7 +15396,7 @@ var require_path = __commonJS({
     }
     exports2.unixify = unixify;
     function makeAbsolute(cwd, filepath) {
-      return path23.resolve(cwd, filepath);
+      return path24.resolve(cwd, filepath);
     }
     exports2.makeAbsolute = makeAbsolute;
     function removeLeadingDotSegment(entry) {
@@ -16693,7 +16693,7 @@ var require_braces = __commonJS({
 var require_constants2 = __commonJS({
   "../../node_modules/.pnpm/picomatch@2.3.2/node_modules/picomatch/lib/constants.js"(exports2, module2) {
     "use strict";
-    var path23 = require("path");
+    var path24 = require("path");
     var WIN_SLASH = "\\\\/";
     var WIN_NO_SLASH = `[^${WIN_SLASH}]`;
     var DEFAULT_MAX_EXTGLOB_RECURSION = 0;
@@ -16867,7 +16867,7 @@ var require_constants2 = __commonJS({
       /* | */
       CHAR_ZERO_WIDTH_NOBREAK_SPACE: 65279,
       /* \uFEFF */
-      SEP: path23.sep,
+      SEP: path24.sep,
       /**
        * Create EXTGLOB_CHARS
        */
@@ -16894,7 +16894,7 @@ var require_constants2 = __commonJS({
 var require_utils3 = __commonJS({
   "../../node_modules/.pnpm/picomatch@2.3.2/node_modules/picomatch/lib/utils.js"(exports2) {
     "use strict";
-    var path23 = require("path");
+    var path24 = require("path");
     var win32 = process.platform === "win32";
     var {
       REGEX_BACKSLASH,
@@ -16923,7 +16923,7 @@ var require_utils3 = __commonJS({
       if (options && typeof options.windows === "boolean") {
         return options.windows;
       }
-      return win32 === true || path23.sep === "\\";
+      return win32 === true || path24.sep === "\\";
     };
     exports2.escapeLast = (input, char, lastIdx) => {
       const idx = input.lastIndexOf(char, lastIdx);
@@ -18287,7 +18287,7 @@ var require_parse2 = __commonJS({
 var require_picomatch = __commonJS({
   "../../node_modules/.pnpm/picomatch@2.3.2/node_modules/picomatch/lib/picomatch.js"(exports2, module2) {
     "use strict";
-    var path23 = require("path");
+    var path24 = require("path");
     var scan = require_scan();
     var parse3 = require_parse2();
     var utils = require_utils3();
@@ -18372,7 +18372,7 @@ var require_picomatch = __commonJS({
     };
     picomatch.matchBase = (input, glob, options, posix = utils.isWindows(options)) => {
       const regex = glob instanceof RegExp ? glob : picomatch.makeRe(glob, options);
-      return regex.test(path23.basename(input));
+      return regex.test(path24.basename(input));
     };
     picomatch.isMatch = (str2, patterns, options) => picomatch(patterns, options)(str2);
     picomatch.parse = (pattern, options) => {
@@ -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 (err20) {
+        if (options && options.debug === true) throw err20;
         return /$^/;
       }
     };
@@ -18599,7 +18599,7 @@ var require_pattern = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.isAbsolute = exports2.partitionAbsoluteAndRelative = exports2.removeDuplicateSlashes = exports2.matchAny = exports2.convertPatternsToRe = exports2.makeRe = exports2.getPatternParts = exports2.expandBraceExpansion = exports2.expandPatternsWithBraceExpansion = exports2.isAffectDepthOfReadingPattern = exports2.endsWithSlashGlobStar = exports2.hasGlobStar = exports2.getBaseDirectory = exports2.isPatternRelatedToParentDirectory = exports2.getPatternsOutsideCurrentDirectory = exports2.getPatternsInsideCurrentDirectory = exports2.getPositivePatterns = exports2.getNegativePatterns = exports2.isPositivePattern = exports2.isNegativePattern = exports2.convertToNegativePattern = exports2.convertToPositivePattern = exports2.isDynamicPattern = exports2.isStaticPattern = void 0;
-    var path23 = require("path");
+    var path24 = require("path");
     var globParent = require_glob_parent();
     var micromatch = require_micromatch();
     var GLOBSTAR = "**";
@@ -18694,7 +18694,7 @@ var require_pattern = __commonJS({
     }
     exports2.endsWithSlashGlobStar = endsWithSlashGlobStar;
     function isAffectDepthOfReadingPattern(pattern) {
-      const basename = path23.basename(pattern);
+      const basename = path24.basename(pattern);
       return endsWithSlashGlobStar(pattern) || isStaticPattern(basename);
     }
     exports2.isAffectDepthOfReadingPattern = isAffectDepthOfReadingPattern;
@@ -18752,7 +18752,7 @@ var require_pattern = __commonJS({
     }
     exports2.partitionAbsoluteAndRelative = partitionAbsoluteAndRelative;
     function isAbsolute(pattern) {
-      return path23.isAbsolute(pattern);
+      return path24.isAbsolute(pattern);
     }
     exports2.isAbsolute = isAbsolute;
   }
@@ -18822,8 +18822,8 @@ var require_merge2 = __commonJS({
             }
             next();
           }
-          function onerror(err18) {
-            mergedStream.emit("error", err18);
+          function onerror(err20) {
+            mergedStream.emit("error", err20);
           }
           if (stream._readableState.endEmitted) {
             return next();
@@ -18927,10 +18927,10 @@ var require_utils4 = __commonJS({
     exports2.array = array2;
     var errno = require_errno();
     exports2.errno = errno;
-    var fs3 = require_fs();
-    exports2.fs = fs3;
-    var path23 = require_path();
-    exports2.path = path23;
+    var fs4 = require_fs();
+    exports2.fs = fs4;
+    var path24 = require_path();
+    exports2.path = path24;
     var pattern = require_pattern();
     exports2.pattern = pattern;
     var stream = require_stream();
@@ -19042,8 +19042,8 @@ var require_async = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.read = void 0;
-    function read(path23, settings, callback) {
-      settings.fs.lstat(path23, (lstatError, lstat) => {
+    function read(path24, settings, callback) {
+      settings.fs.lstat(path24, (lstatError, lstat) => {
         if (lstatError !== null) {
           callFailureCallback(callback, lstatError);
           return;
@@ -19052,7 +19052,7 @@ var require_async = __commonJS({
           callSuccessCallback(callback, lstat);
           return;
         }
-        settings.fs.stat(path23, (statError, stat2) => {
+        settings.fs.stat(path24, (statError, stat2) => {
           if (statError !== null) {
             if (settings.throwErrorOnBrokenSymbolicLink) {
               callFailureCallback(callback, statError);
@@ -19084,13 +19084,13 @@ var require_sync = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.read = void 0;
-    function read(path23, settings) {
-      const lstat = settings.fs.lstatSync(path23);
+    function read(path24, settings) {
+      const lstat = settings.fs.lstatSync(path24);
       if (!lstat.isSymbolicLink() || !settings.followSymbolicLink) {
         return lstat;
       }
       try {
-        const stat2 = settings.fs.statSync(path23);
+        const stat2 = settings.fs.statSync(path24);
         if (settings.markSymbolicLink) {
           stat2.isSymbolicLink = () => true;
         }
@@ -19112,12 +19112,12 @@ var require_fs2 = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.createFileSystemAdapter = exports2.FILE_SYSTEM_ADAPTER = void 0;
-    var fs3 = require("fs");
+    var fs4 = require("fs");
     exports2.FILE_SYSTEM_ADAPTER = {
-      lstat: fs3.lstat,
-      stat: fs3.stat,
-      lstatSync: fs3.lstatSync,
-      statSync: fs3.statSync
+      lstat: fs4.lstat,
+      stat: fs4.stat,
+      lstatSync: fs4.lstatSync,
+      statSync: fs4.statSync
     };
     function createFileSystemAdapter(fsMethods) {
       if (fsMethods === void 0) {
@@ -19134,12 +19134,12 @@ var require_settings = __commonJS({
   "../../node_modules/.pnpm/@nodelib+fs.stat@2.0.5/node_modules/@nodelib/fs.stat/out/settings.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    var fs3 = require_fs2();
+    var fs4 = require_fs2();
     var Settings = class {
       constructor(_options = {}) {
         this._options = _options;
         this.followSymbolicLink = this._getValue(this._options.followSymbolicLink, true);
-        this.fs = fs3.createFileSystemAdapter(this._options.fs);
+        this.fs = fs4.createFileSystemAdapter(this._options.fs);
         this.markSymbolicLink = this._getValue(this._options.markSymbolicLink, false);
         this.throwErrorOnBrokenSymbolicLink = this._getValue(this._options.throwErrorOnBrokenSymbolicLink, true);
       }
@@ -19161,17 +19161,17 @@ var require_out = __commonJS({
     var sync = require_sync();
     var settings_1 = require_settings();
     exports2.Settings = settings_1.default;
-    function stat2(path23, optionsOrSettingsOrCallback, callback) {
+    function stat2(path24, optionsOrSettingsOrCallback, callback) {
       if (typeof optionsOrSettingsOrCallback === "function") {
-        async.read(path23, getSettings(), optionsOrSettingsOrCallback);
+        async.read(path24, getSettings(), optionsOrSettingsOrCallback);
         return;
       }
-      async.read(path23, getSettings(optionsOrSettingsOrCallback), callback);
+      async.read(path24, getSettings(optionsOrSettingsOrCallback), callback);
     }
     exports2.stat = stat2;
-    function statSync2(path23, optionsOrSettings) {
+    function statSync2(path24, optionsOrSettings) {
       const settings = getSettings(optionsOrSettings);
-      return sync.read(path23, settings);
+      return sync.read(path24, settings);
     }
     exports2.statSync = statSync2;
     function getSettings(settingsOrOptions = {}) {
@@ -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((err20) => setTimeout(() => {
+      throw err20;
     }, 0));
   }
 });
@@ -19209,32 +19209,32 @@ var require_run_parallel = __commonJS({
         results = {};
         pending = keys.length;
       }
-      function done(err18) {
+      function done(err20) {
         function end() {
-          if (cb2) cb2(err18, results);
+          if (cb2) cb2(err20, results);
           cb2 = null;
         }
         if (isSync) queueMicrotask2(end);
         else end();
       }
-      function each(i3, err18, result) {
+      function each(i3, err20, result) {
         results[i3] = result;
-        if (--pending === 0 || err18) {
-          done(err18);
+        if (--pending === 0 || err20) {
+          done(err20);
         }
       }
       if (!pending) {
         done(null);
       } else if (keys) {
         keys.forEach(function(key) {
-          tasks[key](function(err18, result) {
-            each(key, err18, result);
+          tasks[key](function(err20, result) {
+            each(key, err20, result);
           });
         });
       } else {
         tasks.forEach(function(task, i3) {
-          task(function(err18, result) {
-            each(i3, err18, result);
+          task(function(err20, result) {
+            each(i3, err20, result);
           });
         });
       }
@@ -19294,8 +19294,8 @@ var require_utils5 = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.fs = void 0;
-    var fs3 = require_fs3();
-    exports2.fs = fs3;
+    var fs4 = require_fs3();
+    exports2.fs = fs4;
   }
 });
 
@@ -19387,16 +19387,16 @@ var require_async2 = __commonJS({
           return;
         }
         const tasks = names.map((name) => {
-          const path23 = common3.joinPathSegments(directory, name, settings.pathSegmentSeparator);
+          const path24 = common3.joinPathSegments(directory, name, settings.pathSegmentSeparator);
           return (done) => {
-            fsStat.stat(path23, settings.fsStatSettings, (error48, stats) => {
+            fsStat.stat(path24, settings.fsStatSettings, (error48, stats) => {
               if (error48 !== null) {
                 done(error48);
                 return;
               }
               const entry = {
                 name,
-                path: path23,
+                path: path24,
                 dirent: utils.fs.createDirentFromStats(name, stats)
               };
               if (settings.stats) {
@@ -19490,14 +19490,14 @@ var require_fs4 = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.createFileSystemAdapter = exports2.FILE_SYSTEM_ADAPTER = void 0;
-    var fs3 = require("fs");
+    var fs4 = require("fs");
     exports2.FILE_SYSTEM_ADAPTER = {
-      lstat: fs3.lstat,
-      stat: fs3.stat,
-      lstatSync: fs3.lstatSync,
-      statSync: fs3.statSync,
-      readdir: fs3.readdir,
-      readdirSync: fs3.readdirSync
+      lstat: fs4.lstat,
+      stat: fs4.stat,
+      lstatSync: fs4.lstatSync,
+      statSync: fs4.statSync,
+      readdir: fs4.readdir,
+      readdirSync: fs4.readdirSync
     };
     function createFileSystemAdapter(fsMethods) {
       if (fsMethods === void 0) {
@@ -19514,15 +19514,15 @@ var require_settings2 = __commonJS({
   "../../node_modules/.pnpm/@nodelib+fs.scandir@2.1.5/node_modules/@nodelib/fs.scandir/out/settings.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    var path23 = require("path");
+    var path24 = require("path");
     var fsStat = require_out();
-    var fs3 = require_fs4();
+    var fs4 = require_fs4();
     var Settings = class {
       constructor(_options = {}) {
         this._options = _options;
         this.followSymbolicLinks = this._getValue(this._options.followSymbolicLinks, false);
-        this.fs = fs3.createFileSystemAdapter(this._options.fs);
-        this.pathSegmentSeparator = this._getValue(this._options.pathSegmentSeparator, path23.sep);
+        this.fs = fs4.createFileSystemAdapter(this._options.fs);
+        this.pathSegmentSeparator = this._getValue(this._options.pathSegmentSeparator, path24.sep);
         this.stats = this._getValue(this._options.stats, false);
         this.throwErrorOnBrokenSymbolicLink = this._getValue(this._options.throwErrorOnBrokenSymbolicLink, true);
         this.fsStatSettings = new fsStat.Settings({
@@ -19549,17 +19549,17 @@ var require_out2 = __commonJS({
     var sync = require_sync2();
     var settings_1 = require_settings2();
     exports2.Settings = settings_1.default;
-    function scandir(path23, optionsOrSettingsOrCallback, callback) {
+    function scandir(path24, optionsOrSettingsOrCallback, callback) {
       if (typeof optionsOrSettingsOrCallback === "function") {
-        async.read(path23, getSettings(), optionsOrSettingsOrCallback);
+        async.read(path24, getSettings(), optionsOrSettingsOrCallback);
         return;
       }
-      async.read(path23, getSettings(optionsOrSettingsOrCallback), callback);
+      async.read(path24, getSettings(optionsOrSettingsOrCallback), callback);
     }
     exports2.scandir = scandir;
-    function scandirSync(path23, optionsOrSettings) {
+    function scandirSync(path24, optionsOrSettings) {
       const settings = getSettings(optionsOrSettings);
-      return sync.read(path23, settings);
+      return sync.read(path24, settings);
     }
     exports2.scandirSync = scandirSync;
     function getSettings(settingsOrOptions = {}) {
@@ -19623,8 +19623,8 @@ var require_queue = __commonJS({
       var errorHandler = null;
       var self2 = {
         push,
-        drain: noop2,
-        saturated: noop2,
+        drain: noop3,
+        saturated: noop3,
         pause,
         paused: false,
         get concurrency() {
@@ -19647,7 +19647,7 @@ var require_queue = __commonJS({
         length,
         getQueue,
         unshift,
-        empty: noop2,
+        empty: noop3,
         kill,
         killAndDrain,
         error: error48,
@@ -19699,7 +19699,7 @@ var require_queue = __commonJS({
         current.context = context;
         current.release = release;
         current.value = value;
-        current.callback = done || noop2;
+        current.callback = done || noop3;
         current.errorHandler = errorHandler;
         if (_running >= _concurrency || self2.paused) {
           if (queueTail) {
@@ -19720,7 +19720,7 @@ var require_queue = __commonJS({
         current.context = context;
         current.release = release;
         current.value = value;
-        current.callback = done || noop2;
+        current.callback = done || noop3;
         current.errorHandler = errorHandler;
         if (_running >= _concurrency || self2.paused) {
           if (queueHead) {
@@ -19762,13 +19762,13 @@ var require_queue = __commonJS({
       function kill() {
         queueHead = null;
         queueTail = null;
-        self2.drain = noop2;
+        self2.drain = noop3;
       }
       function killAndDrain() {
         queueHead = null;
         queueTail = null;
         self2.drain();
-        self2.drain = noop2;
+        self2.drain = noop3;
       }
       function abort() {
         var current = queueHead;
@@ -19781,7 +19781,7 @@ var require_queue = __commonJS({
           var val = current.value;
           var context2 = current.context;
           current.value = null;
-          current.callback = noop2;
+          current.callback = noop3;
           current.errorHandler = null;
           if (errorHandler2) {
             errorHandler2(new Error("abort"), val);
@@ -19790,32 +19790,32 @@ var require_queue = __commonJS({
           current.release(current);
           current = next;
         }
-        self2.drain = noop2;
+        self2.drain = noop3;
       }
       function error48(handler) {
         errorHandler = handler;
       }
     }
-    function noop2() {
+    function noop3() {
     }
     function Task3() {
       this.value = null;
-      this.callback = noop2;
+      this.callback = noop3;
       this.next = null;
-      this.release = noop2;
+      this.release = noop3;
       this.context = null;
       this.errorHandler = null;
       var self2 = this;
-      this.worked = function worked(err18, result) {
+      this.worked = function worked(err20, result) {
         var callback = self2.callback;
         var errorHandler = self2.errorHandler;
         var val = self2.value;
         self2.value = null;
-        self2.callback = noop2;
+        self2.callback = noop3;
         if (self2.errorHandler) {
-          errorHandler(err18, val);
+          errorHandler(err20, val);
         }
-        callback.call(self2.context, err18, result);
+        callback.call(self2.context, err20, result);
         self2.release(self2);
       };
     }
@@ -19839,28 +19839,28 @@ 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(err20, result) {
+            if (err20) {
+              reject(err20);
               return;
             }
             resolve(result);
           });
         });
-        p.catch(noop2);
+        p.catch(noop3);
         return p;
       }
       function unshift(value) {
         var p = new Promise(function(resolve, reject) {
-          unshiftCb(value, function(err18, result) {
-            if (err18) {
-              reject(err18);
+          unshiftCb(value, function(err20, result) {
+            if (err20) {
+              reject(err20);
               return;
             }
             resolve(result);
           });
         });
-        p.catch(noop2);
+        p.catch(noop3);
         return p;
       }
       function drained() {
@@ -20206,7 +20206,7 @@ var require_settings3 = __commonJS({
   "../../node_modules/.pnpm/@nodelib+fs.walk@1.2.8/node_modules/@nodelib/fs.walk/out/settings.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    var path23 = require("path");
+    var path24 = require("path");
     var fsScandir = require_out2();
     var Settings = class {
       constructor(_options = {}) {
@@ -20216,7 +20216,7 @@ var require_settings3 = __commonJS({
         this.deepFilter = this._getValue(this._options.deepFilter, null);
         this.entryFilter = this._getValue(this._options.entryFilter, null);
         this.errorFilter = this._getValue(this._options.errorFilter, null);
-        this.pathSegmentSeparator = this._getValue(this._options.pathSegmentSeparator, path23.sep);
+        this.pathSegmentSeparator = this._getValue(this._options.pathSegmentSeparator, path24.sep);
         this.fsScandirSettings = new fsScandir.Settings({
           followSymbolicLinks: this._options.followSymbolicLinks,
           fs: this._options.fs,
@@ -20278,7 +20278,7 @@ var require_reader2 = __commonJS({
   "../../node_modules/.pnpm/fast-glob@3.3.3/node_modules/fast-glob/out/readers/reader.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    var path23 = require("path");
+    var path24 = require("path");
     var fsStat = require_out();
     var utils = require_utils4();
     var Reader = class {
@@ -20291,7 +20291,7 @@ var require_reader2 = __commonJS({
         });
       }
       _getFullEntryPath(filepath) {
-        return path23.resolve(this._settings.cwd, filepath);
+        return path24.resolve(this._settings.cwd, filepath);
       }
       _makeEntry(stats, pattern) {
         const entry = {
@@ -20707,7 +20707,7 @@ var require_provider = __commonJS({
   "../../node_modules/.pnpm/fast-glob@3.3.3/node_modules/fast-glob/out/providers/provider.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    var path23 = require("path");
+    var path24 = require("path");
     var deep_1 = require_deep();
     var entry_1 = require_entry();
     var error_1 = require_error2();
@@ -20721,7 +20721,7 @@ var require_provider = __commonJS({
         this.entryTransformer = new entry_2.default(this._settings);
       }
       _getRootDirectory(task) {
-        return path23.resolve(this._settings.cwd, task.base);
+        return path24.resolve(this._settings.cwd, task.base);
       }
       _getReaderOptions(task) {
         const basePath = task.base === "." ? "" : task.base;
@@ -20902,16 +20902,16 @@ var require_settings4 = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.DEFAULT_FILE_SYSTEM_ADAPTER = void 0;
-    var fs3 = require("fs");
+    var fs4 = require("fs");
     var os4 = require("os");
     var CPU_COUNT = Math.max(os4.cpus().length, 1);
     exports2.DEFAULT_FILE_SYSTEM_ADAPTER = {
-      lstat: fs3.lstat,
-      lstatSync: fs3.lstatSync,
-      stat: fs3.stat,
-      statSync: fs3.statSync,
-      readdir: fs3.readdir,
-      readdirSync: fs3.readdirSync
+      lstat: fs4.lstat,
+      lstatSync: fs4.lstatSync,
+      stat: fs4.stat,
+      statSync: fs4.statSync,
+      readdir: fs4.readdir,
+      readdirSync: fs4.readdirSync
     };
     var Settings = class {
       constructor(_options = {}) {
@@ -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");
@@ -24368,9 +24368,9 @@ var tq = k((oq) => {
 });
 var sq = k((aq) => {
   Object.defineProperty(aq, "__esModule", { value: true });
-  var ok19 = Q$(), tk = { keyword: "not", schemaType: ["object", "boolean"], trackErrors: true, code($) {
+  var ok21 = Q$(), tk = { keyword: "not", schemaType: ["object", "boolean"], trackErrors: true, code($) {
     let { gen: X, schema: J, it: Q } = $;
-    if ((0, ok19.alwaysValidSchema)(Q, J)) {
+    if ((0, ok21.alwaysValidSchema)(Q, J)) {
       $.fail();
       return;
     }
@@ -38981,10 +38981,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema2) {
   return mergeDefs(schema2._zod.def);
 }
-function getElementAtPath(obj, path23) {
-  if (!path23)
+function getElementAtPath(obj, path24) {
+  if (!path24)
     return obj;
-  return path23.reduce((acc, key) => acc?.[key], obj);
+  return path24.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -39367,11 +39367,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path23, issues) {
+function prefixIssues(path24, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path23);
+    iss.path.unshift(path24);
     return iss;
   });
 }
@@ -39554,7 +39554,7 @@ function formatError(error48, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error48, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error49, path23 = []) => {
+  const processError = (error49, path24 = []) => {
     var _a3, _b2;
     for (const issue2 of error49.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
@@ -39564,7 +39564,7 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
       } else if (issue2.code === "invalid_element") {
         processError({ issues: issue2.issues }, issue2.path);
       } else {
-        const fullpath = [...path23, ...issue2.path];
+        const fullpath = [...path24, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -39596,8 +39596,8 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path23 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path23) {
+  const path24 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path24) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -51574,13 +51574,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path23 = ref.slice(1).split("/").filter(Boolean);
-  if (path23.length === 0) {
+  const path24 = ref.slice(1).split("/").filter(Boolean);
+  if (path24.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path23[0] === defsKey) {
-    const key = path23[1];
+  if (path24[0] === defsKey) {
+    const key = path24[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -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);
     }
-    previous = current;
+    const signature = structuralSignature(parsed.value);
+    if (signature === previousSignature) {
+      return (0, import_neverthrow.ok)(raw);
+    }
+    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));
@@ -52578,18 +52604,54 @@ function captureScreenshot(udid = "booted") {
   );
 }
 function createScreenshotTool(udid = "booted") {
-  return _x("screenshot", "Take a screenshot of the current screen.", {}, async () => {
-    const result = await captureScreenshot(udid);
-    if (result.isErr()) {
-      return {
-        content: [{ type: "text", text: String(result.error.cause) }],
-        isError: true
-      };
+  return _x(
+    "screenshot",
+    "Capture a screenshot of the current screen. Use for passive visual verification \u2014 confirming a screen transition occurred, loading finished, or an expected visual outcome is present \u2014 when you do not need element labels, tap coordinates, or accessibility attributes. Does not return a <screen_id>; cannot be used for stuck-loop detection or element-targeted assertions. Do not call this immediately before or after `view_ui` for the same state.",
+    {},
+    async () => {
+      const result = await captureScreenshot(udid);
+      if (result.isErr()) {
+        return {
+          content: [{ type: "text", text: String(result.error.cause) }],
+          isError: true
+        };
+      }
+      return { content: [{ type: "image", data: result.value, mimeType: "image/png" }] };
     }
-    return { content: [{ type: "image", data: result.value, mimeType: "image/png" }] };
-  });
+  );
 }
 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 +52806,7 @@ function createMobileIosServer(udid = "booted", extraTools = []) {
       createLaunchAppTool(udid),
       createTerminateAppTool(udid),
       createListAppsTool(udid),
+      createWaitSecondsTool(),
       ...extraTools
     ]
   });
@@ -52765,7 +52828,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 +52873,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 +53702,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 +54540,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 +54743,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 err20 = e3;
+  if (err20.name === "AbortError") {
+    err20 = new GoogleGenerativeAIAbortError(`Request aborted when fetching ${url2.toString()}: ${e3.message}`);
+    err20.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;
+    err20 = new GoogleGenerativeAIError(`Error fetching from ${url2.toString()}: ${e3.message}`);
+    err20.stack = e3.stack;
   }
-  throw err18;
+  throw err20;
 }
 async function handleResponseNotOk(response, url2) {
   let message = "";
@@ -54854,11 +54917,11 @@ function __asyncGenerator(thisArg, _arguments, generator) {
     try {
       step(g3[n3](v2));
     } catch (e3) {
-      settle(q4[0][3], e3);
+      settle2(q4[0][3], e3);
     }
   }
   function step(r3) {
-    r3.value instanceof __await ? Promise.resolve(r3.value.v).then(fulfill, reject) : settle(q4[0][2], r3);
+    r3.value instanceof __await ? Promise.resolve(r3.value.v).then(fulfill, reject) : settle2(q4[0][2], r3);
   }
   function fulfill(value) {
     resume("next", value);
@@ -54866,7 +54929,7 @@ function __asyncGenerator(thisArg, _arguments, generator) {
   function reject(value) {
     resume("throw", value);
   }
-  function settle(f6, v2) {
+  function settle2(f6, v2) {
     if (f6(v2), q4.shift(), q4.length) resume(q4[0][0], q4[0][1]);
   }
 }
@@ -54935,14 +54998,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 err20 = e3;
+          err20.stack = e3.stack;
+          if (err20.name === "AbortError") {
+            err20 = new GoogleGenerativeAIAbortError("Request aborted when reading from the stream");
           } else {
-            err18 = new GoogleGenerativeAIError("Error reading from the stream");
+            err20 = new GoogleGenerativeAIError("Error reading from the stream");
           }
-          throw err18;
+          throw err20;
         });
       }
     }
@@ -55538,15 +55601,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 err20 = e3;
+  if (err20.name === "AbortError") {
+    err20 = new GoogleGenerativeAIAbortError2(`Request aborted when fetching ${url2.toString()}: ${e3.message}`);
+    err20.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;
+    err20 = new GoogleGenerativeAIError2(`Error fetching from ${url2.toString()}: ${e3.message}`);
+    err20.stack = e3.stack;
   }
-  throw err18;
+  throw err20;
 }
 async function handleResponseNotOk2(response, url2) {
   let message = "";
@@ -55585,8 +55648,8 @@ var ServerRequestUrl = class {
     this.apiKey = apiKey;
     this.requestOptions = requestOptions;
   }
-  appendPath(path23) {
-    this._url.pathname = this._url.pathname + `/${path23}`;
+  appendPath(path24) {
+    this._url.pathname = this._url.pathname + `/${path24}`;
   }
   appendParam(key, value) {
     this._url.searchParams.append(key, value);
@@ -55906,7 +55969,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 +56099,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 +56205,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(err20) {
+  return typeof err20 === "object" && err20 !== null && // Spec-compliant fetch implementations
+  ("name" in err20 && err20.name === "AbortError" || // Expo fetch
+  "message" in err20 && String(err20.message).includes("FetchRequestCanceledException"));
+}
+var castToError = (err20) => {
+  if (err20 instanceof Error)
+    return err20;
+  if (typeof err20 === "object" && err20 !== 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(err20) === "[object Error]") {
+        const error48 = new Error(err20.message, err20.cause ? { cause: err20.cause } : {});
+        if (err20.stack)
+          error48.stack = err20.stack;
+        if (err20.cause && !error48.cause)
+          error48.cause = err20.cause;
+        if (err20.name)
+          error48.name = err20.name;
         return error48;
       }
     } catch {
     }
     try {
-      return new Error(JSON.stringify(err18));
+      return new Error(JSON.stringify(err20));
     } catch {
     }
   }
-  return new Error(err18);
+  return new Error(err20);
 };
 
 // ../../node_modules/.pnpm/@anthropic-ai+sdk@0.87.0_zod@4.3.6/node_modules/@anthropic-ai/sdk/core/error.mjs
@@ -56299,13 +56362,13 @@ var validatePositiveInteger = (name, n3) => {
 var safeJSON = (text) => {
   try {
     return JSON.parse(text);
-  } catch (err18) {
+  } catch (err20) {
     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 +56926,8 @@ var Stream = class _Stream {
             return ctrl.close();
           const bytes = encodeUTF8(JSON.stringify(value) + "\n");
           ctrl.enqueue(bytes);
-        } catch (err18) {
-          ctrl.error(err18);
+        } catch (err20) {
+          ctrl.error(err20);
         }
       },
       async cancel() {
@@ -57412,12 +57475,12 @@ function encodeURIPath(str2) {
   return str2.replace(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/g, encodeURIComponent);
 }
 var EMPTY = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.create(null));
-var createPathTagFunction = (pathEncoder = encodeURIPath) => function path23(statics, ...params) {
+var createPathTagFunction = (pathEncoder = encodeURIPath) => function path24(statics, ...params) {
   if (statics.length === 1)
     return statics[0];
   let postPath = false;
   const invalidSegments = [];
-  const path24 = statics.reduce((previousValue, currentValue, index) => {
+  const path25 = statics.reduce((previousValue, currentValue, index) => {
     if (/[?#]/.test(currentValue)) {
       postPath = true;
     }
@@ -57434,7 +57497,7 @@ var createPathTagFunction = (pathEncoder = encodeURIPath) => function path23(sta
     }
     return previousValue + currentValue + (index === params.length ? "" : encoded);
   }, "");
-  const pathOnly = path24.split(/[?#]/, 1)[0];
+  const pathOnly = path25.split(/[?#]/, 1)[0];
   const invalidSegmentPattern = /(?<=^|\/)(?:\.|%2e){1,2}(?=\/|$)/gi;
   let match;
   while ((match = invalidSegmentPattern.exec(pathOnly)) !== null) {
@@ -57455,10 +57518,10 @@ var createPathTagFunction = (pathEncoder = encodeURIPath) => function path23(sta
     }, "");
     throw new AnthropicError(`Path parameters result in path with invalid segments:
 ${invalidSegments.map((e3) => e3.error).join("\n")}
-${path24}
+${path25}
 ${underline}`);
   }
-  return path24;
+  return path25;
 };
 var path4 = /* @__PURE__ */ createPathTagFunction(encodeURIPath);
 
@@ -58771,8 +58834,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 (err20) {
+                  const error48 = new AnthropicError(`Unable to parse tool parameter JSON from model. Please retry your request or adjust your prompt. Error: ${err20}. JSON: ${jsonBuf}`);
                   __classPrivateFieldGet(this, _BetaMessageStream_handleError, "f").call(this, error48);
                 }
               }
@@ -58834,17 +58897,17 @@ var BetaMessageStream = class _BetaMessageStream {
       }
       readQueue.length = 0;
     });
-    this.on("abort", (err18) => {
+    this.on("abort", (err20) => {
       done = true;
       for (const reader of readQueue) {
-        reader.reject(err18);
+        reader.reject(err20);
       }
       readQueue.length = 0;
     });
-    this.on("error", (err18) => {
+    this.on("error", (err20) => {
       done = true;
       for (const reader of readQueue) {
-        reader.reject(err18);
+        reader.reject(err20);
       }
       readQueue.length = 0;
     });
@@ -61087,17 +61150,17 @@ var MessageStream = class _MessageStream {
       }
       readQueue.length = 0;
     });
-    this.on("abort", (err18) => {
+    this.on("abort", (err20) => {
       done = true;
       for (const reader of readQueue) {
-        reader.reject(err18);
+        reader.reject(err20);
       }
       readQueue.length = 0;
     });
-    this.on("error", (err18) => {
+    this.on("error", (err20) => {
       done = true;
       for (const reader of readQueue) {
-        reader.reject(err18);
+        reader.reject(err20);
       }
       readQueue.length = 0;
     });
@@ -61546,9 +61609,9 @@ var BaseAnthropic = class {
   makeStatusError(status, error48, message, headers) {
     return APIError.generate(status, error48, message, headers);
   }
-  buildURL(path23, query, defaultBaseURL) {
+  buildURL(path24, query, defaultBaseURL) {
     const baseURL = !__classPrivateFieldGet(this, _BaseAnthropic_instances, "m", _BaseAnthropic_baseURLOverridden).call(this) && defaultBaseURL || this.baseURL;
-    const url2 = isAbsoluteURL(path23) ? new URL(path23) : new URL(baseURL + (baseURL.endsWith("/") && path23.startsWith("/") ? path23.slice(1) : path23));
+    const url2 = isAbsoluteURL(path24) ? new URL(path24) : new URL(baseURL + (baseURL.endsWith("/") && path24.startsWith("/") ? path24.slice(1) : path24));
     const defaultQuery = this.defaultQuery();
     const pathQuery = Object.fromEntries(url2.searchParams);
     if (!isEmptyObj(defaultQuery) || !isEmptyObj(pathQuery)) {
@@ -61580,24 +61643,24 @@ var BaseAnthropic = class {
    */
   async prepareRequest(request, { url: url2, options }) {
   }
-  get(path23, opts) {
-    return this.methodRequest("get", path23, opts);
+  get(path24, opts) {
+    return this.methodRequest("get", path24, opts);
   }
-  post(path23, opts) {
-    return this.methodRequest("post", path23, opts);
+  post(path24, opts) {
+    return this.methodRequest("post", path24, opts);
   }
-  patch(path23, opts) {
-    return this.methodRequest("patch", path23, opts);
+  patch(path24, opts) {
+    return this.methodRequest("patch", path24, opts);
   }
-  put(path23, opts) {
-    return this.methodRequest("put", path23, opts);
+  put(path24, opts) {
+    return this.methodRequest("put", path24, opts);
   }
-  delete(path23, opts) {
-    return this.methodRequest("delete", path23, opts);
+  delete(path24, opts) {
+    return this.methodRequest("delete", path24, opts);
   }
-  methodRequest(method, path23, opts) {
+  methodRequest(method, path24, opts) {
     return this.request(Promise.resolve(opts).then((opts2) => {
-      return { method, path: path23, ...opts2 };
+      return { method, path: path24, ...opts2 };
     }));
   }
   request(options, remainingRetries = null) {
@@ -61677,7 +61740,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((err21) => castToError(err21).message);
       const errJSON = safeJSON(errText);
       const errMessage = errJSON ? void 0 : errText;
       loggerFor(this).debug(`[${requestLogID}] response error (${retryMessage})`, formatRequestDetails({
@@ -61688,8 +61751,8 @@ var BaseAnthropic = class {
         message: errMessage,
         durationMs: Date.now() - startTime
       }));
-      const err18 = this.makeStatusError(response.status, errJSON, errMessage, response.headers);
-      throw err18;
+      const err20 = this.makeStatusError(response.status, errJSON, errMessage, response.headers);
+      throw err20;
     }
     loggerFor(this).info(responseInfo);
     loggerFor(this).debug(`[${requestLogID}] response start`, formatRequestDetails({
@@ -61701,8 +61764,8 @@ var BaseAnthropic = class {
     }));
     return { response, options, controller: controller2, requestLogID, retryOfRequestLogID, startTime };
   }
-  getAPIList(path23, Page2, opts) {
-    return this.requestAPIList(Page2, opts && "then" in opts ? opts.then((opts2) => ({ method: "get", path: path23, ...opts2 })) : { method: "get", path: path23, ...opts });
+  getAPIList(path24, Page2, opts) {
+    return this.requestAPIList(Page2, opts && "then" in opts ? opts.then((opts2) => ({ method: "get", path: path24, ...opts2 })) : { method: "get", path: path24, ...opts });
   }
   requestAPIList(Page2, options) {
     const request = this.makeRequest(options, null, void 0);
@@ -61768,7 +61831,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) {
@@ -61790,8 +61853,8 @@ var BaseAnthropic = class {
   }
   async buildRequest(inputOptions, { retryCount = 0 } = {}) {
     const options = { ...inputOptions };
-    const { method, path: path23, query, defaultBaseURL } = options;
-    const url2 = this.buildURL(path23, query, defaultBaseURL);
+    const { method, path: path24, query, defaultBaseURL } = options;
+    const url2 = this.buildURL(path24, query, defaultBaseURL);
     if ("timeout" in options)
       validatePositiveInteger("timeout", options.timeout);
     options.timeout = options.timeout ?? this.timeout;
@@ -62132,25 +62195,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_) {
@@ -62166,7 +62229,7 @@ async function runFfmpeg(arguments_) {
 }
 function spawnRecorder(outputPath) {
   const safeMkdirSync = (0, import_neverthrow15.fromThrowable)(import_node_fs.mkdirSync, (cause) => cause);
-  const safeSpawn = (0, import_neverthrow15.fromThrowable)(
+  const safeSpawn2 = (0, import_neverthrow15.fromThrowable)(
     (command, arguments_) => (0, import_node_child_process3.spawn)(command, arguments_),
     (cause) => cause
   );
@@ -62174,7 +62237,7 @@ function spawnRecorder(outputPath) {
   if (mkdirResult.isErr()) {
     return mkdirResult.error;
   }
-  const spawnResult = safeSpawn("xcrun", [
+  const spawnResult = safeSpawn2("xcrun", [
     "simctl",
     "io",
     "booted",
@@ -62251,9 +62314,11 @@ function speedUpVideo({
   );
 }
 var VIEW_UI_TOOL_NAME = "mcp__mobile-ios__view_ui";
-var VIEW_UI_DESCRIPTION = `Capture the current screen state: accessibility snapshot (element list with positions) and screenshot. Call this after every action to observe the result.
+var VIEW_UI_DESCRIPTION = `Capture current screen state: accessibility tree (element labels, positions, attributes) and screenshot in one call. Use when you need to tap an element, assert element presence or labels, check attributes, or track screen identity via <screen_id>.
+
+The result begins with a <screen_id> tag containing the current screen identifier. Use this to detect screen changes and track navigation history.
 
-The result begins with a <screen_id> tag containing the current screen identifier. Use this to track which screen you are on.
+Do not call \`screenshot\` immediately before or after this tool for the same state \u2014 this tool already includes the screenshot.
 
 IMPORTANT: Snapshot coordinates and screenshot pixels are in the same logical point space. Do not apply any scaling factor (no 2x retina adjustment).`;
 function deriveScreenLabel(tree, stepIndex) {
@@ -62266,7 +62331,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 +62396,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`);
@@ -62578,32 +62643,11 @@ function spawnDetached(options) {
     off: child.off.bind(child)
   };
 }
-var cachedAllTools;
-async function fetchAllTools() {
-  if (cachedAllTools !== void 0) {
-    return cachedAllTools;
-  }
-  const probe = Qs({ prompt: "", options: { settingSources: ["user"] } });
-  for await (const message of probe) {
-    if (message.type === "system" && message.subtype === "init") {
-      probe.close();
-      cachedAllTools = message.tools;
-      return cachedAllTools;
-    }
-  }
-  return [];
-}
-async function resolveDisallowedTools(allowedTools) {
-  const allTools = await fetchAllTools();
-  const allowedSet = new Set(allowedTools);
-  return allTools.filter((tool2) => !allowedSet.has(tool2));
-}
 function buildQueryOptions({
   config: config3,
   outputTools,
   mobileIosServer,
-  allowedTools,
-  disallowedTools
+  allowedTools
 }) {
   const base = {
     mcpServers: {
@@ -62612,8 +62656,9 @@ function buildQueryOptions({
       output: outputTools.server
     },
     allowedTools,
-    disallowedTools,
-    settingSources: ["user"],
+    tools: [],
+    permissionMode: "bypassPermissions",
+    allowDangerouslySkipPermissions: true,
     spawnClaudeCodeProcess: spawnDetached,
     ...config3.cwd ? { cwd: config3.cwd } : {}
   };
@@ -62664,13 +62709,13 @@ function buildMobileIosServer(config3, state) {
   });
   return createMobileIosServer(config3.udid ?? "booted", [viewUiTool]);
 }
-async function setupQuery(config3, outputTools) {
+function setupQuery(config3, outputTools) {
   const allowedTools = [
     ...config3.allowedTools ?? [],
     ...outputTools.allowedToolNames,
-    VIEW_UI_TOOL_NAME
-  ];
-  const disallowedTools = await resolveDisallowedTools(allowedTools);
+    VIEW_UI_TOOL_NAME,
+    WAIT_SECONDS_TOOL_NAME
+  ].filter((tool2) => typeof tool2 === "string");
   const inputQueue = new MessageQueue();
   const state = buildAgentState({ config: config3, outputTools, inputQueue });
   const mobileIosServer = buildMobileIosServer(config3, state);
@@ -62678,8 +62723,7 @@ async function setupQuery(config3, outputTools) {
     config: config3,
     outputTools,
     mobileIosServer,
-    allowedTools,
-    disallowedTools
+    allowedTools
   });
   return { inputQueue, state, options, linkedController };
 }
@@ -62744,7 +62788,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,
@@ -62795,16 +62839,16 @@ function startQueryTimers(config3, context) {
     inputQueue.close();
   };
 }
-function awaitMessagesAndResolve({ queryRunner, state }, { cleanup: cleanup2, getOutput }) {
+function awaitMessagesAndResolve({ queryRunner, state }, { cleanup: cleanup3, getOutput }) {
   const messagesPromise = processMessages(queryRunner, state);
   return import_neverthrow16.ResultAsync.fromPromise(messagesPromise, String).andThen((innerResult) => {
-    cleanup2();
+    cleanup3();
     if (innerResult.isErr()) {
       return (0, import_neverthrow16.err)(innerResult.error);
     }
     return (0, import_neverthrow16.ok)(getOutput());
   }).orElse((sdkError) => {
-    cleanup2();
+    cleanup3();
     if (!state.timedOut.value && !state.aborted.value) {
       return (0, import_neverthrow16.err)(sdkError);
     }
@@ -62827,21 +62871,19 @@ function executeQuery({
     return (0, import_neverthrow16.errAsync)(queryRunnerResult.error);
   }
   const queryRunner = queryRunnerResult.value;
-  const cleanup2 = startQueryTimers(config3, { state, queryRunner, inputQueue, linkedController });
+  const cleanup3 = startQueryTimers(config3, { state, queryRunner, inputQueue, linkedController });
   const getOutput = () => ({
     findings: (outputTools.getOutput()?.findings ?? []).map(
       (raw) => stampExplorerAgent(raw)
     ),
     snapshots: state.snapshots
   });
-  return awaitMessagesAndResolve({ queryRunner, state }, { cleanup: cleanup2, getOutput });
+  return awaitMessagesAndResolve({ queryRunner, state }, { cleanup: cleanup3, getOutput });
 }
 function runQuery(prompt, config3) {
   const outputTools = createOutputTool({ findings: external_exports.array(EXPLORER_FINDING_SCHEMA) });
-  const setupPromise = setupQuery(config3, outputTools);
-  return import_neverthrow16.ResultAsync.fromPromise(setupPromise, String).andThen(
-    (setup) => executeQuery({ prompt, config: config3, outputTools, setup })
-  );
+  const setup = setupQuery(config3, outputTools);
+  return executeQuery({ prompt, config: config3, outputTools, setup });
 }
 function collectAgentOutput(prompt, config3) {
   return runQuery(prompt, config3).mapErr((cause) => ({ type: "QUERY_FAILED", cause }));
@@ -62893,6 +62935,12 @@ function startAndRun(params) {
     }).andThen((result) => applySpeedUpVariants({ result, params, toRecordingError }));
   });
 }
+var TOOL_SELECTION_SECTION = `## Tool Selection
+
+- \`view_ui\` \u2014 returns accessibility tree (element labels, positions, attributes) AND screenshot; use when you need to tap, assert element presence, or read labels
+- \`screenshot\` \u2014 returns screenshot only; use for passive visual verification (confirm transition occurred, loading finished, outcome visible) when you do not need element data
+- Never call \`screenshot\` immediately before or after \`view_ui\` for the same state \u2014 \`view_ui\` already includes the screenshot
+- \`screenshot\` calls do not emit a \`<screen_id>\` and do not advance the stuck-loop counter; if screen identity tracking matters, use \`view_ui\``;
 var DEV_ENVIRONMENT_SECTION = `## Environment
 
 This is a development build. Debug overlays and internal messages are expected artifacts \u2014 do not report them as findings.`;
@@ -62904,9 +62952,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 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 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, then confirm you returned to the expected parent in PATH \u2014 use \`screenshot\` if the parent screen is visually unambiguous, \`view_ui\` if you need element labels or coordinates to verify or to act next \u2014 if confirmation fails, 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_id>\` across 3 or more consecutive \`view_ui\` calls, (2) the same element has been tapped more than twice with no screen change confirmed by \`view_ui\`, (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 \u2014 note: \`screenshot\`-only calls do not update the stuck-loop counter; only \`view_ui\` calls count`;
+var LOADING_STATE_RULE = `Transient loading state: when the screen shows spinners, skeleton screens, progress bars, "Loading..." text, or placeholder content NOT described in spec or app context \u2014 use \`screenshot\` to poll for resolution (up to 3 retries); switch to \`view_ui\` only on the final check or when you need element data to act \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 call \`view_ui\` 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
 
@@ -62948,7 +62998,7 @@ Each step has this shape:
   <intent> [\u2192 <outcome>] [hint: <advisory>]
 
 - The intent phrase is your goal. Achieve it by any reasonable UI path.
-- If an outcome state is present, it is your verification target. After acting, call \`view_ui\` and confirm the outcome is met before marking the step complete. If no outcome is given, proceed when the action succeeds.
+- If an outcome state is present, it is your verification target. After acting, confirm the outcome is met before marking the step complete \u2014 use \`screenshot\` when the outcome is purely visual (screen transition visible, element gone, content appeared); use \`view_ui\` when the outcome requires asserting element labels, attributes, or coordinates. If no outcome is given, proceed when the action succeeds.
 - A hint is advisory only. Prefer an element matching the hint, but if no literal match exists, use intent and visual context to select the best candidate. Never fail a step solely because a hint label is absent.
 - Infer element role (primary action, secondary action, dismissal) from visual hierarchy, position, and hint text. Authors do not specify role.
 - If no element satisfies the intent after exhausting visible UI, emit a \`spec-deviation\` finding and halt that step.`;
@@ -62980,25 +63030,30 @@ ${initialState2}` : void 0,
 }
 var SPEC_RULES_SECTION = `## Rules
 
-- ALWAYS call \`view_ui\` after every action before deciding what to do next \u2014 it is your only way to observe the screen
+- ${SESSION_START_RULE}
+- After any action, observe the screen before deciding next step \u2014 use \`screenshot\` when confirming a purely visual outcome (transition occurred, element disappeared, content appeared, loading finished); use \`view_ui\` when you need element labels, tap coordinates, or accessibility attributes
+- Never call both \`screenshot\` and \`view_ui\` back-to-back for the same observation \u2014 \`view_ui\` includes a screenshot; if you need both tree and image, one \`view_ui\` call suffices
 - ${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
+- Each item in \`**Assertions**\` is a mandatory pass/fail check \u2014 verify using \`view_ui\` when the assertion targets an element attribute, label, or presence in the tree; use \`screenshot\` when the assertion is purely visual; if neither can 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`;
 function buildSpecModeBody({
   specContent,
   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.
 
 ${contextBlock}
 
+${TOOL_SELECTION_SECTION}
+
 ${SPEC_RULES_SECTION}
 
 ## Execution Strategy
@@ -63034,17 +63089,22 @@ 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}
 
+${TOOL_SELECTION_SECTION}
+
 ## Rules
 
-- ALWAYS call \`view_ui\` after every action before deciding what to do next \u2014 it is your only way to observe the screen
+- ${SESSION_START_RULE}
+- After any action, observe the screen before deciding next step \u2014 use \`screenshot\` when confirming a purely visual outcome (transition occurred, element disappeared, content appeared, loading finished); use \`view_ui\` when you need element labels, tap coordinates, or accessibility attributes
+- Never call both \`screenshot\` and \`view_ui\` back-to-back for the same observation \u2014 \`view_ui\` includes a screenshot; if you need both tree and image, one \`view_ui\` call suffices
 - ${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 +63319,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 +63333,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 +63458,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 +63467,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 +64440,7 @@ var directiveHandlers = {
     }
     try {
       prefix = decodeURIComponent(prefix);
-    } catch (err18) {
+    } catch (err20) {
       throwError(state, "tag prefix is malformed: " + prefix);
     }
     state.tagMap[handle] = prefix;
@@ -65061,7 +65121,7 @@ function readTagProperty(state) {
   }
   try {
     tagName = decodeURIComponent(tagName);
-  } catch (err18) {
+  } catch (err20) {
     throwError(state, "tag name is malformed: " + tagName);
   }
   if (isVerbatim) {
@@ -66730,7 +66790,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 +66885,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 +66916,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 +66931,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 +66989,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 +67178,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 +67338,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 +67373,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 +67679,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 +67700,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 +67735,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 +67756,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 +67865,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 +67902,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 +67924,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 +67936,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 +67952,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 +67964,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 +67976,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 +68013,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 +68114,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 +68267,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 = []) => (
@@ -69051,7 +69389,7 @@ function createPrompt(view) {
         effectScheduler.clearAll();
         throw error48;
       }).finally(() => {
-        cleanups.forEach((cleanup2) => cleanup2());
+        cleanups.forEach((cleanup3) => cleanup3());
         screen.done({ clearContent: Boolean(context.clearPromptOnDone) });
         output.end();
       }).then(() => promise2), { cancel });
@@ -69311,9 +69649,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((err20, result) => {
+    if (err20) {
+      setImmediate(callback, err20, void 0);
     } else {
       try {
         editor.cleanup();
@@ -70334,7 +70672,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 +70825,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 +70850,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 +70929,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 +70942,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 +71018,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 +71073,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 +71143,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 +71202,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 +71268,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 = {};
@@ -71408,8 +71748,8 @@ function getErrorMap2() {
 
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path23, errorMaps, issueData } = params;
-  const fullPath = [...path23, ...issueData.path || []];
+  const { data, path: path24, errorMaps, issueData } = params;
+  const fullPath = [...path24, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -71525,11 +71865,11 @@ var errorUtil;
 
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path23, key) {
+  constructor(parent, value, path24, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path23;
+    this._path = path24;
     this._key = key;
   }
   get path() {
@@ -71668,8 +72008,8 @@ var ZodType2 = class {
         } : {
           issues: ctx.common.issues
         };
-      } catch (err18) {
-        if (err18?.message?.toLowerCase()?.includes("encountered")) {
+      } catch (err20) {
+        if (err20?.message?.toLowerCase()?.includes("encountered")) {
           this["~standard"].async = true;
         }
         ctx.common = {
@@ -74989,10 +75329,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 +75365,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 +75374,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,51 +75440,40 @@ 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_node_path22 = __toESM(require("node:path"), 1);
+var import_promises21 = __toESM(require("node:fs/promises"), 1);
+var import_node_path23 = __toESM(require("node:path"), 1);
 var import_fast_glob = __toESM(require_out4(), 1);
-var import_neverthrow51 = __toESM(require_index_cjs(), 1);
-
-// src/suite/core/run-id.ts
-var RUN_ID_PAD_LENGTH2 = 4;
-function toNumeric(name) {
-  const parsed = Number(name);
-  return Number.isInteger(parsed) && parsed > 0 ? parsed : void 0;
-}
-function highestNumeric(directories) {
-  let highest = 0;
-  for (const name of directories) {
-    const numeric = toNumeric(name);
-    if (numeric !== void 0 && numeric > highest) {
-      highest = numeric;
-    }
-  }
-  return highest;
-}
-function computeNextRunId(existingDirectories) {
-  return String(highestNumeric(existingDirectories) + 1).padStart(RUN_ID_PAD_LENGTH2, "0");
-}
+var import_neverthrow55 = __toESM(require_index_cjs(), 1);
 
 // 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 RESERVED_HOOK_ENV_KEYS = [
+  "XQA_SIM_UDID",
+  "XQA_ITEM_ID",
+  "XQA_ITEM_TYPE",
+  "XQA_ITEM_NAME",
+  "XQA_SPEC_PATH",
+  "XQA_SUITE"
+];
+var reservedKeySet = new Set(RESERVED_HOOK_ENV_KEYS);
 var freestyleEntrySchema = external_exports2.object({
   prompt: external_exports2.string().optional(),
   timeoutSeconds: external_exports2.number().int().positive()
@@ -75159,24 +75488,80 @@ var freestyleSchema = external_exports2.union([external_exports2.number().int().
   }
   return value;
 });
+var hookConfigSchema = external_exports2.object({
+  script: external_exports2.string().min(1),
+  env: external_exports2.record(external_exports2.string(), external_exports2.string()).optional(),
+  timeoutSeconds: external_exports2.number().int().positive().optional()
+}).superRefine((data, context) => {
+  if (data.env === void 0) {
+    return;
+  }
+  for (const key of Object.keys(data.env)) {
+    if (reservedKeySet.has(key)) {
+      context.addIssue({
+        code: external_exports2.ZodIssueCode.custom,
+        path: ["env", key],
+        message: `Reserved xqa-owned key: ${key}`
+      });
+    }
+  }
+});
+var suiteHooksSchema = external_exports2.object({
+  beforeEach: hookConfigSchema.optional()
+});
 var suiteConfigSchema = external_exports2.object({
   specs: external_exports2.array(external_exports2.string()).nonempty(),
-  freestyle: freestyleSchema
+  freestyle: freestyleSchema,
+  hooks: suiteHooksSchema.optional()
 });
-var safeJsonParse4 = (0, import_neverthrow47.fromThrowable)(
+var safeJsonParse4 = (0, import_neverthrow48.fromThrowable)(
   JSON.parse,
   (cause) => ({
     type: "INVALID_SUITE_CONFIG",
     cause
   })
 );
+function buildHookConfig(parsed) {
+  const { script, env: env2, timeoutSeconds } = parsed;
+  if (env2 !== void 0 && timeoutSeconds !== void 0) {
+    return { script, env: env2, timeoutSeconds };
+  }
+  if (env2 !== void 0) {
+    return { script, env: env2 };
+  }
+  if (timeoutSeconds !== void 0) {
+    return { script, timeoutSeconds };
+  }
+  return { script };
+}
+function normalizeHooks(hooks) {
+  if (hooks === void 0) {
+    return void 0;
+  }
+  const { beforeEach } = hooks;
+  if (beforeEach === void 0) {
+    return {};
+  }
+  return { beforeEach: buildHookConfig(beforeEach) };
+}
 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 });
+    const hooks = normalizeHooks(parsed.data.hooks);
+    if (hooks === void 0) {
+      return (0, import_neverthrow49.ok)({
+        specs: parsed.data.specs,
+        freestyle: parsed.data.freestyle
+      });
+    }
+    return (0, import_neverthrow49.ok)({
+      specs: parsed.data.specs,
+      freestyle: parsed.data.freestyle,
+      hooks
+    });
   });
 }
 
@@ -75189,17 +75574,6 @@ function buildSuiteFindings(input) {
   return base;
 }
 
-// src/suite/core/suite-id.ts
-function slugify2(glob) {
-  return glob.replaceAll(/[^a-zA-Z0-9]+/g, "-").replaceAll(/-+/g, "-").replaceAll(/^-|-$/g, "");
-}
-function deriveSuiteId(input) {
-  if (input.mode === "suite") {
-    return input.name;
-  }
-  return input.globs.toSorted().map((glob) => slugify2(glob)).join("+");
-}
-
 // src/suite/core/work-item-builder.ts
 var DEFAULT_FREESTYLE_TIMEOUT_SECONDS = 300;
 function deriveSpecName(filePath) {
@@ -75240,9 +75614,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 +75628,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 +75641,29 @@ function writeSuiteFindings(findings, options) {
 }
 
 // src/suite/shell/worker-pool.ts
-var import_neverthrow50 = __toESM(require_index_cjs(), 1);
+var import_neverthrow53 = __toESM(require_index_cjs(), 1);
+
+// src/suite/core/priority-queue.ts
+var PriorityQueue = class {
+  entries = [];
+  get size() {
+    return this.entries.length;
+  }
+  get isEmpty() {
+    return this.entries.length === 0;
+  }
+  enqueue(item, priority) {
+    const insertIndex = this.entries.findIndex((entry) => entry.priority > priority);
+    if (insertIndex === -1) {
+      this.entries.push({ item, priority });
+    } else {
+      this.entries.splice(insertIndex, 0, { item, priority });
+    }
+  }
+  dequeue() {
+    return this.entries.shift()?.item;
+  }
+};
 
 // src/suite/shell/item-result-builder.ts
 function getErrorMessage(cause) {
@@ -75341,33 +75737,7 @@ function buildAbortedItem(item, simulatorUdid) {
   };
 }
 
-// src/suite/core/priority-queue.ts
-var PriorityQueue = class {
-  entries = [];
-  get size() {
-    return this.entries.length;
-  }
-  get isEmpty() {
-    return this.entries.length === 0;
-  }
-  enqueue(item, priority) {
-    const insertIndex = this.entries.findIndex((entry) => entry.priority > priority);
-    if (insertIndex === -1) {
-      this.entries.push({ item, priority });
-    } else {
-      this.entries.splice(insertIndex, 0, { item, priority });
-    }
-  }
-  dequeue() {
-    return this.entries.shift()?.item;
-  }
-};
-
-// src/suite/shell/worker-pool.ts
-var CONSECUTIVE_FAILURES_THRESHOLD = 2;
-function isTimeoutError(error48) {
-  return error48.type.toUpperCase().includes("TIMEOUT");
-}
+// src/suite/shell/item-result-recorder.ts
 function buildNotifyBase(itemContext) {
   return {
     itemId: itemContext.item.id,
@@ -75376,6 +75746,9 @@ function buildNotifyBase(itemContext) {
     at: Date.now()
   };
 }
+function isTimeoutError(error48) {
+  return error48.type.toUpperCase().includes("TIMEOUT");
+}
 function notifyItemResult(context, observer) {
   const base = buildNotifyBase(context.itemContext);
   if (context.result.isOk()) {
@@ -75396,12 +75769,12 @@ function notifyItemResult(context, observer) {
     error: getErrorMessage(context.result.error.cause)
   });
 }
-function recordItemResult(context, workerContext) {
+function recordItemResult(input) {
+  const { context, results, observer } = input;
   const { itemContext, result } = context;
-  const { results, config: config3 } = workerContext;
   if (result.isOk()) {
     results.push(buildCompletedItem(itemContext, result.value));
-    notifyItemResult(context, config3.observer);
+    notifyItemResult(context, observer);
     return 0;
   }
   if (isTimeoutError(result.error)) {
@@ -75409,9 +75782,202 @@ function recordItemResult(context, workerContext) {
   } else {
     results.push(buildFailedItem(itemContext, getErrorMessage(result.error.cause)));
   }
-  notifyItemResult(context, config3.observer);
+  notifyItemResult(context, observer);
+  return 1;
+}
+
+// src/suite/shell/hook-failure-recorder.ts
+function formatHookError(error48) {
+  switch (error48.type) {
+    case "HOOK_SPAWN_FAILED": {
+      return `Hook spawn failed: ${getErrorMessage(error48.cause)}`;
+    }
+    case "HOOK_EXIT_NONZERO": {
+      return `Hook exited with code ${String(error48.code)}: ${error48.stderr.trim()}`;
+    }
+    case "HOOK_TIMEOUT": {
+      return `Hook timed out after ${String(error48.timeoutMs)}ms`;
+    }
+    case "HOOK_ABORTED": {
+      return "Hook aborted";
+    }
+  }
+}
+function emitHookTimeout(input) {
+  const base = buildNotifyBase(input.itemContext);
+  input.results.push(buildTimedOutItem(input.itemContext));
+  const event = { type: "ITEM_TIMEOUT", ...base };
+  input.observer(event);
+}
+function emitHookFailed(input, message) {
+  const base = buildNotifyBase(input.itemContext);
+  input.results.push(buildFailedItem(input.itemContext, message));
+  const event = { type: "ITEM_FAILED", ...base, error: message };
+  input.observer(event);
+}
+function recordHookFailure(input) {
+  if (input.error.type === "HOOK_TIMEOUT") {
+    emitHookTimeout(input);
+    return 1;
+  }
+  emitHookFailed(input, formatHookError(input.error));
   return 1;
 }
+
+// src/suite/shell/hook-invoker.ts
+var import_neverthrow52 = __toESM(require_index_cjs(), 1);
+
+// src/suite/core/hook-env-builder.ts
+function buildReservedKeys(input) {
+  const { item, simulatorUdid, suiteName } = input;
+  const base = {
+    XQA_SIM_UDID: simulatorUdid,
+    XQA_ITEM_ID: item.id,
+    XQA_ITEM_TYPE: item.type,
+    XQA_ITEM_NAME: item.name,
+    XQA_SUITE: suiteName
+  };
+  if (item.type === "spec") {
+    return { ...base, XQA_SPEC_PATH: item.specPath };
+  }
+  return base;
+}
+function buildHookEnv(input) {
+  const reserved = buildReservedKeys(input);
+  if (input.suiteEnv === void 0) {
+    return reserved;
+  }
+  return { ...input.suiteEnv, ...reserved };
+}
+
+// src/suite/shell/hook-runner.ts
+var import_node_child_process7 = require("node:child_process");
+var import_neverthrow51 = __toESM(require_index_cjs(), 1);
+var noop2 = () => void 0;
+function cleanup2(context) {
+  clearTimeout(context.timeoutHandle);
+  context.signal.removeEventListener("abort", context.onAbort);
+}
+function settle(context, outcome) {
+  if (context.settled.value) {
+    return;
+  }
+  context.settled.value = true;
+  cleanup2(context);
+  context.deferred.resolve(outcome);
+}
+function makeDeferred() {
+  const raw = Promise.withResolvers();
+  return { promise: raw.promise, resolve: raw.resolve };
+}
+function collectStderr(child, stderrReference) {
+  if (child.stderr === null) {
+    return;
+  }
+  child.stderr.on("data", (chunk) => {
+    stderrReference.value += chunk.toString();
+  });
+}
+function buildOnAbort(context) {
+  return () => {
+    context.child.kill("SIGTERM");
+    settle(context, (0, import_neverthrow51.err)({ type: "HOOK_ABORTED" }));
+  };
+}
+function attachChildListeners(context) {
+  const { child, stderrReference } = context;
+  child.on("error", (cause) => {
+    settle(context, (0, import_neverthrow51.err)({ type: "HOOK_SPAWN_FAILED", cause }));
+  });
+  child.on("exit", (code) => {
+    if (code === 0) {
+      settle(context, (0, import_neverthrow51.ok)());
+      return;
+    }
+    settle(
+      context,
+      (0, import_neverthrow51.err)({
+        type: "HOOK_EXIT_NONZERO",
+        code: code ?? -1,
+        stderr: stderrReference.value
+      })
+    );
+  });
+}
+function attachTimeout(context, timeoutMs) {
+  clearTimeout(context.timeoutHandle);
+  context.timeoutHandle = setTimeout(() => {
+    context.child.kill("SIGTERM");
+    settle(context, (0, import_neverthrow51.err)({ type: "HOOK_TIMEOUT", timeoutMs }));
+  }, timeoutMs);
+}
+function buildContext2(options) {
+  const { script, cwd, env: env2, baseEnv, nodeExecPath } = options;
+  const deferred = makeDeferred();
+  const stderrReference = { value: "" };
+  const child = (0, import_node_child_process7.spawn)(nodeExecPath, [script], {
+    cwd,
+    env: { ...baseEnv, ...env2 },
+    stdio: ["ignore", "inherit", "pipe"]
+  });
+  collectStderr(child, stderrReference);
+  return {
+    child,
+    signal: options.signal,
+    timeoutHandle: setTimeout(noop2, 0),
+    onAbort: noop2,
+    deferred,
+    stderrReference,
+    settled: { value: false }
+  };
+}
+async function spawnHook(options) {
+  const context = buildContext2(options);
+  attachTimeout(context, options.timeoutMs);
+  context.onAbort = buildOnAbort(context);
+  if (options.signal.aborted) {
+    context.onAbort();
+    return context.deferred.promise;
+  }
+  options.signal.addEventListener("abort", context.onAbort, { once: true });
+  attachChildListeners(context);
+  return context.deferred.promise;
+}
+var safeSpawn = import_neverthrow51.ResultAsync.fromThrowable(
+  spawnHook,
+  (cause) => ({ type: "HOOK_SPAWN_FAILED", cause })
+);
+function runHook(options) {
+  return safeSpawn(options).andThen((outcome) => outcome);
+}
+
+// src/suite/shell/hook-invoker.ts
+var DEFAULT_HOOK_TIMEOUT_SECONDS = 120;
+var MS_PER_SECOND5 = 1e3;
+async function invokeHook(input) {
+  const { hook, item, simulatorUdid, suiteName, hookCwd, hookBaseEnv, hookNodeExecPath, signal } = input;
+  const env2 = buildHookEnv({ item, simulatorUdid, suiteName, suiteEnv: hook.env });
+  const timeoutSeconds = hook.timeoutSeconds ?? DEFAULT_HOOK_TIMEOUT_SECONDS;
+  return runHook({
+    script: hook.script,
+    cwd: hookCwd,
+    env: env2,
+    baseEnv: hookBaseEnv,
+    nodeExecPath: hookNodeExecPath,
+    timeoutMs: timeoutSeconds * MS_PER_SECOND5,
+    signal
+  });
+}
+async function maybeInvokeHook(input) {
+  const { hook } = input;
+  if (hook === void 0) {
+    return (0, import_neverthrow52.ok)();
+  }
+  return invokeHook({ ...input, hook });
+}
+
+// src/suite/shell/worker-pool.ts
+var CONSECUTIVE_FAILURES_THRESHOLD = 2;
 function buildExecuteOptions(workerContext, item) {
   const { simulatorUdid, config: config3 } = workerContext;
   const base = { item, simulatorUdid, signal: config3.signal };
@@ -75421,21 +75987,70 @@ function buildExecuteOptions(workerContext, item) {
   }
   return base;
 }
-async function processItem(workerContext, item) {
-  const { simulatorUdid, config: config3 } = workerContext;
-  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const startMs = Date.now();
-  config3.observer({
+function buildHookInvokeInput(workerContext, item) {
+  const { config: config3, simulatorUdid } = workerContext;
+  return {
+    hook: config3.hook,
+    item,
+    simulatorUdid,
+    suiteName: config3.suiteName,
+    hookCwd: config3.hookCwd,
+    hookBaseEnv: config3.hookBaseEnv,
+    hookNodeExecPath: config3.hookNodeExecPath,
+    signal: config3.signal
+  };
+}
+function emitItemStarted(state) {
+  const { workerContext, item, startMs } = state;
+  workerContext.config.observer({
     type: "ITEM_STARTED",
     itemId: item.id,
     itemName: item.name,
-    simulatorUdid,
+    simulatorUdid: workerContext.simulatorUdid,
     at: startMs
   });
-  const result = await config3.executeItem(buildExecuteOptions(workerContext, item));
+}
+async function runAndRecordItem(state) {
+  const { workerContext, item, startedAt, startMs } = state;
+  const { simulatorUdid } = workerContext;
+  const result = await workerContext.config.executeItem(buildExecuteOptions(workerContext, item));
   const durationMs = Date.now() - startMs;
   const itemContext = { item, simulatorUdid, startedAt, durationMs };
-  return recordItemResult({ itemContext, result }, workerContext);
+  return recordItemResult({
+    context: { itemContext, result },
+    results: workerContext.results,
+    observer: workerContext.config.observer
+  });
+}
+function handleHookFailure(state, error48) {
+  const { workerContext, item, startedAt, startMs } = state;
+  const durationMs = Date.now() - startMs;
+  const itemContext = {
+    item,
+    simulatorUdid: workerContext.simulatorUdid,
+    startedAt,
+    durationMs
+  };
+  return recordHookFailure({
+    itemContext,
+    error: error48,
+    results: workerContext.results,
+    observer: workerContext.config.observer
+  });
+}
+async function processItem(workerContext, item) {
+  const state = {
+    workerContext,
+    item,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    startMs: Date.now()
+  };
+  emitItemStarted(state);
+  const hookOutcome = await maybeInvokeHook(buildHookInvokeInput(workerContext, item));
+  if (hookOutcome.isErr()) {
+    return handleHookFailure(state, hookOutcome.error);
+  }
+  return runAndRecordItem(state);
 }
 async function runWorker(workerContext) {
   const { simulatorUdid, queue, config: config3 } = workerContext;
@@ -75495,7 +76110,7 @@ function runWorkerPool(config3) {
   const queue = setupQueue(config3);
   const results = [];
   const suiteStartMs = Date.now();
-  const safeRun = import_neverthrow50.ResultAsync.fromThrowable(
+  const safeRun = import_neverthrow53.ResultAsync.fromThrowable(
     async () => runAllWorkers({ config: config3, queue, results, suiteStartMs }),
     (cause) => ({ type: "WORKER_POOL_FAILED", cause })
   );
@@ -75535,7 +76150,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),
@@ -75580,30 +76195,88 @@ function makeExecuteItem(context) {
   };
 }
 
-// src/suite/commands/run-command.ts
+// src/suite/commands/suite-run-context.ts
+var import_promises20 = __toESM(require("node:fs/promises"), 1);
+var import_node_path22 = __toESM(require("node:path"), 1);
+var import_neverthrow54 = __toESM(require_index_cjs(), 1);
+
+// src/suite/core/run-id.ts
+var RUN_ID_PAD_LENGTH2 = 4;
+function toNumeric(name) {
+  const parsed = Number(name);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : void 0;
+}
+function highestNumeric(directories) {
+  let highest = 0;
+  for (const name of directories) {
+    const numeric = toNumeric(name);
+    if (numeric !== void 0 && numeric > highest) {
+      highest = numeric;
+    }
+  }
+  return highest;
+}
+function computeNextRunId(existingDirectories) {
+  return String(highestNumeric(existingDirectories) + 1).padStart(RUN_ID_PAD_LENGTH2, "0");
+}
+
+// src/suite/core/suite-id.ts
+function slugify2(glob) {
+  return glob.replaceAll(/[^a-zA-Z0-9]+/g, "-").replaceAll(/-+/g, "-").replaceAll(/^-|-$/g, "");
+}
+function deriveSuiteId(input) {
+  if (input.mode === "suite") {
+    return input.name;
+  }
+  return input.globs.toSorted().map((glob) => slugify2(glob)).join("+");
+}
+
+// src/suite/commands/suite-run-context.ts
 var ISO_DATE_LENGTH3 = 10;
-var safeReaddir2 = import_neverthrow51.ResultAsync.fromThrowable(
+var safeReaddir2 = import_neverthrow54.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"),
-  () => "READ_FAILED"
-);
 async function listRunDirectories(input) {
   const { outputDirectory, suiteId, date: date5 } = input;
   const directoryPath = import_node_path22.default.join(outputDirectory, "suite", suiteId, date5);
   const result = await safeReaddir2(directoryPath);
   return result.unwrapOr([]);
 }
+function deriveSuiteIdFromMode(mode) {
+  if (mode.type === "suite") {
+    return deriveSuiteId({ mode: "suite", name: mode.name });
+  }
+  return deriveSuiteId({ mode: "spec", globs: mode.globs });
+}
+async function buildSuiteRunContext(input) {
+  const suiteId = deriveSuiteIdFromMode(input.mode);
+  const date5 = (/* @__PURE__ */ new Date()).toISOString().slice(0, ISO_DATE_LENGTH3);
+  const outputDirectory = import_node_path22.default.join(input.xqaDirectory, "output");
+  const existingDirectories = await listRunDirectories({ outputDirectory, suiteId, date: date5 });
+  const runId = computeNextRunId(existingDirectories);
+  const context = {
+    config: input.config,
+    xqaDirectory: input.xqaDirectory,
+    runId,
+    date: date5
+  };
+  return { suiteId, date: date5, outputDirectory, runId, context };
+}
+
+// src/suite/commands/run-command.ts
+var safeReadFile5 = import_neverthrow55.ResultAsync.fromThrowable(
+  async (filePath) => import_promises21.default.readFile(filePath, "utf8"),
+  () => "READ_FAILED"
+);
 async function resolveGlobs(input) {
   return (0, import_fast_glob.default)(input.globs, { cwd: input.cwd, absolute: true });
 }
 async function loadSuiteConfig(xqaDirectory, name) {
-  const suitePath = import_node_path22.default.join(xqaDirectory, "suites", `${name}.suite.json`);
+  const suitePath = import_node_path23.default.join(xqaDirectory, "suites", `${name}.suite.json`);
   const contentResult = await safeReadFile5(suitePath);
   if (contentResult.isErr()) {
     return;
@@ -75626,7 +76299,10 @@ async function resolveSuiteModeItems(input) {
     process.stderr.write("No spec files matched\n");
     return;
   }
-  return [...buildSpecItems(specPaths), ...buildFreestyleItems(suiteConfig.freestyle)];
+  return {
+    items: [...buildSpecItems(specPaths), ...buildFreestyleItems(suiteConfig.freestyle)],
+    hook: suiteConfig.hooks?.beforeEach
+  };
 }
 async function resolveSpecModeItems(input) {
   const specPaths = await resolveGlobs({ globs: input.mode.globs, cwd: input.xqaDirectory });
@@ -75634,7 +76310,7 @@ async function resolveSpecModeItems(input) {
     process.stderr.write("No spec files matched\n");
     return;
   }
-  return buildSpecItems(specPaths);
+  return { items: buildSpecItems(specPaths), hook: void 0 };
 }
 async function resolveWorkItems(input) {
   if (input.mode.type === "suite") {
@@ -75642,12 +76318,6 @@ async function resolveWorkItems(input) {
   }
   return resolveSpecModeItems({ ...input, mode: input.mode });
 }
-function deriveSuiteIdFromMode(mode) {
-  if (mode.type === "suite") {
-    return deriveSuiteId({ mode: "suite", name: mode.name });
-  }
-  return deriveSuiteId({ mode: "spec", globs: mode.globs });
-}
 async function discoverSimulators() {
   const result = await discoverBootedSimulators();
   if (result.isErr()) {
@@ -75661,21 +76331,34 @@ async function discoverSimulators() {
   }
   return { simulators: result.value, exitCode: 0 };
 }
-async function runPool(input) {
-  const { context, items, simulatorUdids, signal } = input;
-  const display = createSuiteDisplay();
-  const poolResult = await runWorkerPool({
+function buildPoolConfig(input, display) {
+  const { context, items, simulatorUdids, debug, signal, suiteName, hookCwd } = input;
+  const debugLogger = createDebugLogger({ enabled: debug });
+  const baseObserver = (event) => {
+    display.onEvent(event);
+  };
+  const observer = debugLogger.wrapSuiteHandler(baseObserver);
+  const onEvent = (itemId) => debugLogger.wrapAgentHandler((event) => {
+    display.onEvent({ ...event, itemId });
+  }, itemId);
+  return {
     items,
     simulatorUdids,
-    observer: (event) => {
-      display.onEvent(event);
-    },
-    onEvent: (itemId) => (event) => {
-      display.onEvent({ ...event, itemId });
-    },
+    observer,
+    onEvent,
     executeItem: makeExecuteItem(context),
-    signal
-  });
+    signal,
+    suiteName,
+    hookCwd,
+    hookBaseEnv: process.env,
+    hookNodeExecPath: process.execPath
+  };
+}
+async function runPool(input) {
+  const { hook } = input;
+  const display = createSuiteDisplay();
+  const poolConfig = buildPoolConfig(input, display);
+  const poolResult = hook === void 0 ? await runWorkerPool(poolConfig) : await runWorkerPool({ ...poolConfig, hook });
   display.cleanup();
   return poolResult;
 }
@@ -75696,36 +76379,37 @@ async function writeAndReport(input) {
   const hasFindings = items.some((item) => item.findings.length > 0);
   return hasFindings ? 1 : 0;
 }
-async function buildSuiteRunContext(input) {
-  const suiteId = deriveSuiteIdFromMode(input.mode);
-  const date5 = (/* @__PURE__ */ new Date()).toISOString().slice(0, ISO_DATE_LENGTH3);
-  const outputDirectory = import_node_path22.default.join(input.xqaDirectory, "output");
-  const existingDirectories = await listRunDirectories({ outputDirectory, suiteId, date: date5 });
-  const runId = computeNextRunId(existingDirectories);
-  const context = {
-    config: input.config,
-    xqaDirectory: input.xqaDirectory,
-    runId,
-    date: date5
+function derivePoolInput(input, context) {
+  const suiteName = input.mode.type === "suite" ? input.mode.name : "specs";
+  return {
+    context,
+    items: input.items,
+    simulatorUdids: input.simulatorUdids,
+    debug: input.debug,
+    signal: input.signal,
+    suiteName,
+    hook: input.hook,
+    hookCwd: input.xqaDirectory
   };
-  return { suiteId, date: date5, outputDirectory, runId, context };
+}
+async function executePool(input, runContext) {
+  return runPool(derivePoolInput(input, runContext.context));
 }
 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) {
@@ -75733,8 +76417,8 @@ async function runSuiteCommand(input) {
   if (preflightExit !== void 0) {
     return preflightExit;
   }
-  const items = await resolveWorkItems(input);
-  if (items === void 0) {
+  const resolved = await resolveWorkItems(input);
+  if (resolved === void 0) {
     return 1;
   }
   const simulatorResolution = await discoverSimulators();
@@ -75748,8 +76432,9 @@ async function runSuiteCommand(input) {
   }
   return runSuite({
     ...input,
-    items,
-    simulatorUdids: simulators.map((sim) => sim.udid)
+    items: resolved.items,
+    simulatorUdids: simulators.map((sim) => sim.udid),
+    hook: resolved.hook
   });
 }
 
@@ -75771,7 +76456,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.11.0"}${false ? ` (dev build +${"1f9f698"})` : ""}`);
 program2.command("init").description("Initialize a new xqa project in the current directory").action(() => {
   runInitCommand();
 });
@@ -75786,20 +76471,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 +76500,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 +76523,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);