@swmansion/argent 0.19.1-next.2 → 0.19.1-next.4

package/dist/tool-server.cjs

@@ -45,7 +45,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // ../../node_modules/dotenv/lib/main.js
 var require_main = __commonJS({
   "../../node_modules/dotenv/lib/main.js"(exports2, module2) {
-    var fs54 = require("fs");
+    var fs55 = require("fs");
     var path40 = require("path");
     var os15 = require("os");
     var crypto8 = require("crypto");
@@ -177,7 +177,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 (fs54.existsSync(filepath)) {
+            if (fs55.existsSync(filepath)) {
               possibleVaultPath = filepath.endsWith(".vault") ? filepath : `${filepath}.vault`;
             }
           }
@@ -187,7 +187,7 @@ var require_main = __commonJS({
       } else {
         possibleVaultPath = path40.resolve(process.cwd(), ".env.vault");
       }
-      if (fs54.existsSync(possibleVaultPath)) {
+      if (fs55.existsSync(possibleVaultPath)) {
         return possibleVaultPath;
       }
       return null;
@@ -240,7 +240,7 @@ var require_main = __commonJS({
       const parsedAll = {};
       for (const path41 of optionPaths) {
         try {
-          const parsed = DotenvModule.parse(fs54.readFileSync(path41, { encoding }));
+          const parsed = DotenvModule.parse(fs55.readFileSync(path41, { encoding }));
           DotenvModule.populate(parsedAll, parsed, options);
         } catch (e) {
           if (debug) {
@@ -523,6 +523,7 @@ var init_failure_codes = __esm({
       REGISTRY_TOOL_NOT_FOUND: "REGISTRY_TOOL_NOT_FOUND",
       REGISTRY_TOOL_EXECUTION_FAILED: "REGISTRY_TOOL_EXECUTION_FAILED",
       REGISTRY_TOOL_FAILURE_UNCLASSIFIED: "REGISTRY_TOOL_FAILURE_UNCLASSIFIED",
+      REGISTRY_SERVICE_TERMINATING: "REGISTRY_SERVICE_TERMINATING",
       HTTP_TOOL_NOT_FOUND: "HTTP_TOOL_NOT_FOUND",
       HTTP_ZOD_VALIDATION_FAILED: "HTTP_ZOD_VALIDATION_FAILED",
       HTTP_CAPABILITY_UNSUPPORTED_OPERATION: "HTTP_CAPABILITY_UNSUPPORTED_OPERATION",
@@ -646,6 +647,13 @@ var init_failure_codes = __esm({
       DEBUGGER_CDP_BINDING_TIMEOUT: "DEBUGGER_CDP_BINDING_TIMEOUT",
       DEBUGGER_CDP_BINDING_UNAVAILABLE: "DEBUGGER_CDP_BINDING_UNAVAILABLE",
       DEBUGGER_CDP_PROTOCOL_ERROR: "DEBUGGER_CDP_PROTOCOL_ERROR",
+      DEBUGGER_CDP_CONNECT_FAILED: "DEBUGGER_CDP_CONNECT_FAILED",
+      DEBUGGER_CDP_SOCKET_CLOSED_BEFORE_OPEN: "DEBUGGER_CDP_SOCKET_CLOSED_BEFORE_OPEN",
+      DEBUGGER_CDP_NOT_CONNECTED: "DEBUGGER_CDP_NOT_CONNECTED",
+      DEBUGGER_CDP_REQUEST_TIMEOUT: "DEBUGGER_CDP_REQUEST_TIMEOUT",
+      DEBUGGER_CDP_CONNECTION_CLOSED: "DEBUGGER_CDP_CONNECTION_CLOSED",
+      DEBUGGER_TARGET_DEVICE_MISMATCH: "DEBUGGER_TARGET_DEVICE_MISMATCH",
+      DEBUGGER_EVALUATE_EXPRESSION_THREW: "DEBUGGER_EVALUATE_EXPRESSION_THREW",
       DEBUGGER_RELOAD_FAILED: "DEBUGGER_RELOAD_FAILED",
       JS_RUNTIME_CONSOLE_SERVER_BIND_FAILED: "JS_RUNTIME_CONSOLE_SERVER_BIND_FAILED",
       JS_RUNTIME_PAYLOAD_INVALID: "JS_RUNTIME_PAYLOAD_INVALID",
@@ -16042,6 +16050,14 @@ var init_zod_to_json_schema = __esm({
 });
 
 // ../registry/src/registry.ts
+function terminatingSignalCause(message) {
+  return new FailureError(message, {
+    error_code: FAILURE_CODES.REGISTRY_SERVICE_TERMINATING,
+    failure_stage: "registry_service_terminating",
+    failure_area: "registry",
+    error_kind: "unknown"
+  });
+}
 function formatInteractionMessage(format, fallback) {
   try {
     return format() ?? fallback;
@@ -16057,6 +16073,7 @@ var init_registry = __esm({
     init_types();
     init_artifacts();
     init_errors();
+    init_failure_codes();
     init_urn();
     init_zod_to_json_schema();
     import_node_crypto2 = require("node:crypto");
@@ -16142,7 +16159,7 @@ var init_registry = __esm({
             urn: typeof ref === "string" ? ref : ref.urn,
             options: typeof ref === "string" ? void 0 : ref.options
           }));
-          const ctx = { ...options, artifacts: this.artifacts };
+          const ctx = { ...options, toolInvocationId, artifacts: this.artifacts };
           const runOnce = async () => {
             const resolvedServices = {};
             for (const { alias, urn, options: resolveOptions } of refs) {
@@ -16288,7 +16305,9 @@ var init_registry = __esm({
         }
         if (node.state === "TERMINATING" /* TERMINATING */) {
           return Promise.reject(
-            new ServiceInitializationError(urn, "Service is currently terminating")
+            new ServiceInitializationError(urn, "Service is currently terminating", {
+              cause: terminatingSignalCause("Service is currently terminating")
+            })
           );
         }
         if (node.state === "RUNNING" /* RUNNING */ && node.instance) {
@@ -16320,7 +16339,9 @@ var init_registry = __esm({
             } catch {
             }
             node.initPromise = null;
-            throw new ServiceInitializationError(urn, "Service was terminated during initialization");
+            throw new ServiceInitializationError(urn, "Service was terminated during initialization", {
+              cause: terminatingSignalCause("Service was terminated during initialization")
+            });
           }
           this._transition(node, "RUNNING" /* RUNNING */);
           node.instance = instance;
@@ -35264,7 +35285,7 @@ var require_view = __commonJS({
     "use strict";
     var debug = require_src()("express:view");
     var path40 = require("node:path");
-    var fs54 = require("node:fs");
+    var fs55 = require("node:fs");
     var dirname15 = path40.dirname;
     var basename13 = path40.basename;
     var extname6 = path40.extname;
@@ -35344,7 +35365,7 @@ var require_view = __commonJS({
     function tryStat(path41) {
       debug('stat "%s"', path41);
       try {
-        return fs54.statSync(path41);
+        return fs55.statSync(path41);
       } catch (e) {
         return void 0;
       }
@@ -67649,7 +67670,7 @@ var require_send = __commonJS({
     var escapeHtml = require_escape_html();
     var etag = require_etag();
     var fresh = require_fresh();
-    var fs54 = require("fs");
+    var fs55 = require("fs");
     var mime = require_mime_types4();
     var ms = require_ms();
     var onFinished = require_on_finished();
@@ -67931,7 +67952,7 @@ var require_send = __commonJS({
       var i = 0;
       var self = this;
       debug('stat "%s"', path41);
-      fs54.stat(path41, function onstat(err, stat5) {
+      fs55.stat(path41, function onstat(err, stat5) {
         var pathEndsWithSep = path41[path41.length - 1] === sep7;
         if (err && err.code === "ENOENT" && !extname6(path41) && !pathEndsWithSep) {
           return next(err);
@@ -67948,7 +67969,7 @@ var require_send = __commonJS({
         }
         var p = path41 + "." + self._extensions[i++];
         debug('stat "%s"', p);
-        fs54.stat(p, function(err2, stat5) {
+        fs55.stat(p, function(err2, stat5) {
           if (err2) return next(err2);
           if (stat5.isDirectory()) return next();
           self.emit("file", p, stat5);
@@ -67966,7 +67987,7 @@ var require_send = __commonJS({
         }
         var p = join47(path41, self._index[i]);
         debug('stat "%s"', p);
-        fs54.stat(p, function(err2, stat5) {
+        fs55.stat(p, function(err2, stat5) {
           if (err2) return next(err2);
           if (stat5.isDirectory()) return next();
           self.emit("file", p, stat5);
@@ -67978,7 +67999,7 @@ var require_send = __commonJS({
     SendStream.prototype.stream = function stream(path41, options) {
       var self = this;
       var res = this.res;
-      var stream2 = fs54.createReadStream(path41, options);
+      var stream2 = fs55.createReadStream(path41, options);
       this.emit("stream", stream2);
       stream2.pipe(res);
       function cleanup() {
@@ -75469,10 +75490,10 @@ function avdRootCandidates() {
   return candidates.filter((p) => Boolean(p && (0, import_node_path6.isAbsolute)(p)));
 }
 async function resolveAvdPath(avdName) {
-  const { readFile: readFile12 } = await import("node:fs/promises");
+  const { readFile: readFile13 } = await import("node:fs/promises");
   for (const root of avdRootCandidates()) {
     try {
-      const content = await readFile12(`${root}/${avdName}.ini`, "utf-8");
+      const content = await readFile13(`${root}/${avdName}.ini`, "utf-8");
       const raw = (0, import_ini.parse)(content).path;
       if (typeof raw !== "string") continue;
       const trimmed = raw.trim();
@@ -75602,7 +75623,7 @@ var require_safe_json_stringify = __commonJS({
 // ../../node_modules/ncp/lib/ncp.js
 var require_ncp = __commonJS({
   "../../node_modules/ncp/lib/ncp.js"(exports2, module2) {
-    var fs54 = require("fs");
+    var fs55 = require("fs");
     var path40 = require("path");
     module2.exports = ncp;
     ncp.ncp = ncp;
@@ -75631,7 +75652,7 @@ var require_ncp = __commonJS({
         return getStats(source2);
       }
       function getStats(source2) {
-        var stat5 = dereference ? fs54.stat : fs54.lstat;
+        var stat5 = dereference ? fs55.stat : fs55.lstat;
         if (running >= limit) {
           return setImmediate(function() {
             getStats(source2);
@@ -75671,7 +75692,7 @@ var require_ncp = __commonJS({
             });
           }
           if (modified) {
-            var stat5 = dereference ? fs54.stat : fs54.lstat;
+            var stat5 = dereference ? fs55.stat : fs55.lstat;
             stat5(target, function(err, stats) {
               if (file2.mtime.getTime() > stats.mtime.getTime())
                 copyFile2(file2, target);
@@ -75683,7 +75704,7 @@ var require_ncp = __commonJS({
         });
       }
       function copyFile2(file2, target) {
-        var readStream = fs54.createReadStream(file2.name), writeStream = fs54.createWriteStream(target, { mode: file2.mode });
+        var readStream = fs55.createReadStream(file2.name), writeStream = fs55.createWriteStream(target, { mode: file2.mode });
         readStream.on("error", onError);
         writeStream.on("error", onError);
         if (transform2) {
@@ -75695,13 +75716,13 @@ var require_ncp = __commonJS({
         }
         writeStream.once("finish", function() {
           if (modified) {
-            fs54.utimesSync(target, file2.atime, file2.mtime);
+            fs55.utimesSync(target, file2.atime, file2.mtime);
             cb();
           } else cb();
         });
       }
       function rmFile(file2, done) {
-        fs54.unlink(file2, function(err) {
+        fs55.unlink(file2, function(err) {
           if (err) {
             return onError(err);
           }
@@ -75718,7 +75739,7 @@ var require_ncp = __commonJS({
         });
       }
       function mkDir(dir, target) {
-        fs54.mkdir(target, dir.mode, function(err) {
+        fs55.mkdir(target, dir.mode, function(err) {
           if (err) {
             return onError(err);
           }
@@ -75726,7 +75747,7 @@ var require_ncp = __commonJS({
         });
       }
       function copyDir(dir) {
-        fs54.readdir(dir, function(err, items) {
+        fs55.readdir(dir, function(err, items) {
           if (err) {
             return onError(err);
           }
@@ -75738,7 +75759,7 @@ var require_ncp = __commonJS({
       }
       function onLink(link) {
         var target = link.replace(currentPath, targetPath);
-        fs54.readlink(link, function(err, resolvedPath) {
+        fs55.readlink(link, function(err, resolvedPath) {
           if (err) {
             return onError(err);
           }
@@ -75753,7 +75774,7 @@ var require_ncp = __commonJS({
           if (writable) {
             return makeLink(resolvedPath, target);
           }
-          fs54.readlink(target, function(err, targetDest) {
+          fs55.readlink(target, function(err, targetDest) {
             if (err) {
               return onError(err);
             }
@@ -75770,7 +75791,7 @@ var require_ncp = __commonJS({
         });
       }
       function makeLink(linkPath, target) {
-        fs54.symlink(linkPath, target, function(err) {
+        fs55.symlink(linkPath, target, function(err) {
           if (err) {
             return onError(err);
           }
@@ -75778,7 +75799,7 @@ var require_ncp = __commonJS({
         });
       }
       function isWritable2(path41, done) {
-        fs54.lstat(path41, function(err) {
+        fs55.lstat(path41, function(err) {
           if (err) {
             if (err.code === "ENOENT") return done(true);
             return done(false);
@@ -75790,7 +75811,7 @@ var require_ncp = __commonJS({
         if (options.stopOnError) {
           return cback(err);
         } else if (!errs && options.errs) {
-          errs = fs54.createWriteStream(options.errs);
+          errs = fs55.createWriteStream(options.errs);
         } else if (!errs) {
           errs = [];
         }
@@ -76919,7 +76940,7 @@ var require_sync = __commonJS({
   "../../node_modules/glob/sync.js"(exports2, module2) {
     module2.exports = globSync;
     globSync.GlobSync = GlobSync;
-    var fs54 = require("fs");
+    var fs55 = require("fs");
     var minimatch = require_minimatch();
     var Minimatch = minimatch.Minimatch;
     var Glob = require_glob().Glob;
@@ -76964,7 +76985,7 @@ var require_sync = __commonJS({
           for (var p in matchset) {
             try {
               p = self._makeAbs(p);
-              var real = fs54.realpathSync(p, self.realpathCache);
+              var real = fs55.realpathSync(p, self.realpathCache);
               set2[real] = true;
             } catch (er) {
               if (er.syscall === "stat")
@@ -77091,7 +77112,7 @@ var require_sync = __commonJS({
       var lstat;
       var stat5;
       try {
-        lstat = fs54.lstatSync(abs);
+        lstat = fs55.lstatSync(abs);
       } catch (er) {
         return null;
       }
@@ -77115,7 +77136,7 @@ var require_sync = __commonJS({
           return c;
       }
       try {
-        return this._readdirEntries(abs, fs54.readdirSync(abs));
+        return this._readdirEntries(abs, fs55.readdirSync(abs));
       } catch (er) {
         this._readdirError(abs, er);
         return null;
@@ -77219,13 +77240,13 @@ var require_sync = __commonJS({
       if (!stat5) {
         var lstat;
         try {
-          lstat = fs54.lstatSync(abs);
+          lstat = fs55.lstatSync(abs);
         } catch (er) {
           return false;
         }
         if (lstat.isSymbolicLink()) {
           try {
-            stat5 = fs54.statSync(abs);
+            stat5 = fs55.statSync(abs);
           } catch (er) {
             stat5 = lstat;
           }
@@ -77299,7 +77320,7 @@ var require_inflight = __commonJS({
 var require_glob = __commonJS({
   "../../node_modules/glob/glob.js"(exports2, module2) {
     module2.exports = glob;
-    var fs54 = require("fs");
+    var fs55 = require("fs");
     var minimatch = require_minimatch();
     var Minimatch = minimatch.Minimatch;
     var inherits = require_inherits();
@@ -77436,7 +77457,7 @@ var require_glob = __commonJS({
       var set2 = this.matches[index] = /* @__PURE__ */ Object.create(null);
       found.forEach(function(p, i) {
         p = self._makeAbs(p);
-        fs54.realpath(p, self.realpathCache, function(er, real) {
+        fs55.realpath(p, self.realpathCache, function(er, real) {
           if (!er)
             set2[real] = true;
           else if (er.syscall === "stat")
@@ -77631,7 +77652,7 @@ var require_glob = __commonJS({
       var self = this;
       var lstatcb = inflight(lstatkey, lstatcb_);
       if (lstatcb)
-        fs54.lstat(abs, lstatcb);
+        fs55.lstat(abs, lstatcb);
       function lstatcb_(er, lstat) {
         if (er)
           return cb();
@@ -77660,7 +77681,7 @@ var require_glob = __commonJS({
           return cb(null, c);
       }
       var self = this;
-      fs54.readdir(abs, readdirCb(this, abs, cb));
+      fs55.readdir(abs, readdirCb(this, abs, cb));
     };
     function readdirCb(self, abs, cb) {
       return function(er, entries) {
@@ -77798,10 +77819,10 @@ var require_glob = __commonJS({
       var self = this;
       var statcb = inflight("stat\0" + abs, lstatcb_);
       if (statcb)
-        fs54.lstat(abs, statcb);
+        fs55.lstat(abs, statcb);
       function lstatcb_(er, lstat) {
         if (lstat && lstat.isSymbolicLink()) {
-          return fs54.stat(abs, function(er2, stat6) {
+          return fs55.stat(abs, function(er2, stat6) {
             if (er2)
               self._stat2(f, abs, null, lstat, cb);
             else
@@ -77837,7 +77858,7 @@ var require_rimraf = __commonJS({
     rimraf.sync = rimrafSync;
     var assert2 = require("assert");
     var path40 = require("path");
-    var fs54 = require("fs");
+    var fs55 = require("fs");
     var glob = require_glob();
     var globOpts = {
       nosort: true,
@@ -77857,9 +77878,9 @@ var require_rimraf = __commonJS({
         "readdir"
       ];
       methods.forEach(function(m) {
-        options[m] = options[m] || fs54[m];
+        options[m] = options[m] || fs55[m];
         m = m + "Sync";
-        options[m] = options[m] || fs54[m];
+        options[m] = options[m] || fs55[m];
       });
       options.maxBusyTries = options.maxBusyTries || 3;
       options.emfileWait = options.emfileWait || 1e3;
@@ -77881,7 +77902,7 @@ var require_rimraf = __commonJS({
       var n = 0;
       if (options.disableGlob || !glob.hasMagic(p))
         return afterGlob(null, [p]);
-      fs54.lstat(p, function(er, stat5) {
+      fs55.lstat(p, function(er, stat5) {
         if (!er)
           return afterGlob(null, [p]);
         glob(p, globOpts, afterGlob);
@@ -78038,7 +78059,7 @@ var require_rimraf = __commonJS({
         results = [p];
       } else {
         try {
-          fs54.lstatSync(p);
+          fs55.lstatSync(p);
           results = [p];
         } catch (er) {
           results = glob.sync(p, globOpts);
@@ -78101,7 +78122,7 @@ var require_rimraf = __commonJS({
 var require_mkdirp = __commonJS({
   "../../node_modules/mkdirp/index.js"(exports2, module2) {
     var path40 = require("path");
-    var fs54 = require("fs");
+    var fs55 = require("fs");
     var _0777 = parseInt("0777", 8);
     module2.exports = mkdirP.mkdirp = mkdirP.mkdirP = mkdirP;
     function mkdirP(p, opts, f, made) {
@@ -78112,7 +78133,7 @@ var require_mkdirp = __commonJS({
         opts = { mode: opts };
       }
       var mode = opts.mode;
-      var xfs = opts.fs || fs54;
+      var xfs = opts.fs || fs55;
       if (mode === void 0) {
         mode = _0777;
       }
@@ -78151,7 +78172,7 @@ var require_mkdirp = __commonJS({
         opts = { mode: opts };
       }
       var mode = opts.mode;
-      var xfs = opts.fs || fs54;
+      var xfs = opts.fs || fs55;
       if (mode === void 0) {
         mode = _0777;
       }
@@ -78188,7 +78209,7 @@ var require_mkdirp = __commonJS({
 // ../../node_modules/mv/index.js
 var require_mv = __commonJS({
   "../../node_modules/mv/index.js"(exports2, module2) {
-    var fs54 = require("fs");
+    var fs55 = require("fs");
     var ncp = require_ncp().ncp;
     var path40 = require("path");
     var rimraf = require_rimraf();
@@ -78215,13 +78236,13 @@ var require_mv = __commonJS({
       }
       function doRename() {
         if (clobber) {
-          fs54.rename(source, dest, function(err) {
+          fs55.rename(source, dest, function(err) {
             if (!err) return cb();
             if (err.code !== "EXDEV") return cb(err);
             moveFileAcrossDevice(source, dest, clobber, limit, cb);
           });
         } else {
-          fs54.link(source, dest, function(err) {
+          fs55.link(source, dest, function(err) {
             if (err) {
               if (err.code === "EXDEV") {
                 moveFileAcrossDevice(source, dest, clobber, limit, cb);
@@ -78234,15 +78255,15 @@ var require_mv = __commonJS({
               cb(err);
               return;
             }
-            fs54.unlink(source, cb);
+            fs55.unlink(source, cb);
           });
         }
       }
     }
     function moveFileAcrossDevice(source, dest, clobber, limit, cb) {
       var outFlags = clobber ? "w" : "wx";
-      var ins = fs54.createReadStream(source);
-      var outs = fs54.createWriteStream(dest, { flags: outFlags });
+      var ins = fs55.createReadStream(source);
+      var outs = fs55.createWriteStream(dest, { flags: outFlags });
       ins.on("error", function(err) {
         ins.destroy();
         outs.destroy();
@@ -78262,7 +78283,7 @@ var require_mv = __commonJS({
       outs.once("close", onClose);
       ins.pipe(outs);
       function onClose() {
-        fs54.unlink(source, cb);
+        fs55.unlink(source, cb);
       }
     }
     function moveDirAcrossDevice(source, dest, clobber, limit, cb) {
@@ -78317,7 +78338,7 @@ var require_bunyan = __commonJS({
       throw new Error("unknown runtime environment");
     }
     var os15;
-    var fs54;
+    var fs55;
     var dtrace;
     if (runtimeEnv === "browser") {
       os15 = {
@@ -78325,11 +78346,11 @@ var require_bunyan = __commonJS({
           return window.location.host;
         }
       };
-      fs54 = {};
+      fs55 = {};
       dtrace = null;
     } else {
       os15 = require("os");
-      fs54 = require("fs");
+      fs55 = require("fs");
       try {
         dtrace = require("dtrace-provider");
       } catch (e) {
@@ -78709,7 +78730,7 @@ var require_bunyan = __commonJS({
             s.reemitErrorEvents = true;
           }
           if (!s.stream) {
-            s.stream = fs54.createWriteStream(
+            s.stream = fs55.createWriteStream(
               s.path,
               { flags: "a", encoding: "utf8" }
             );
@@ -78779,7 +78800,7 @@ var require_bunyan = __commonJS({
             s.stream.destroySoon();
             delete s.stream;
           }
-          s.stream = fs54.createWriteStream(
+          s.stream = fs55.createWriteStream(
             s.path,
             { flags: "a", encoding: "utf8" }
           );
@@ -79121,7 +79142,7 @@ var require_bunyan = __commonJS({
         }
         var lastModified = null;
         try {
-          var fileInfo = fs54.statSync(this.path);
+          var fileInfo = fs55.statSync(this.path);
           lastModified = fileInfo.mtime.getTime();
         } catch (err) {
         }
@@ -79132,7 +79153,7 @@ var require_bunyan = __commonJS({
             rotateAfterOpen = true;
           }
         }
-        this.stream = fs54.createWriteStream(
+        this.stream = fs55.createWriteStream(
           this.path,
           { flags: "a", encoding: "utf8" }
         );
@@ -79299,7 +79320,7 @@ var require_bunyan = __commonJS({
           }
           n -= 1;
           self._debug("  rm %s", toDel);
-          fs54.unlink(toDel, function(delErr) {
+          fs55.unlink(toDel, function(delErr) {
             moves();
           });
         }
@@ -79313,7 +79334,7 @@ var require_bunyan = __commonJS({
             before += "." + String(n - 1);
           }
           n -= 1;
-          fs54.exists(before, function(exists2) {
+          fs55.exists(before, function(exists2) {
             if (!exists2) {
               moves();
             } else {
@@ -79331,7 +79352,7 @@ var require_bunyan = __commonJS({
         }
         function finish() {
           self._debug("  open %s", self.path);
-          self.stream = fs54.createWriteStream(
+          self.stream = fs55.createWriteStream(
             self.path,
             { flags: "a", encoding: "utf8" }
           );
@@ -83276,7 +83297,7 @@ var require_png = __commonJS({
     var Parser = require_parser_async();
     var Packer = require_packer_async();
     var PNGSync = require_png_sync();
-    var PNG4 = exports2.PNG = function(options) {
+    var PNG5 = exports2.PNG = function(options) {
       Stream2.call(this);
       options = options || {};
       this.width = options.width | 0;
@@ -83305,9 +83326,9 @@ var require_png = __commonJS({
       this._parser.on("close", this._handleClose.bind(this));
       this._packer.on("error", this.emit.bind(this, "error"));
     };
-    util.inherits(PNG4, Stream2);
-    PNG4.sync = PNGSync;
-    PNG4.prototype.pack = function() {
+    util.inherits(PNG5, Stream2);
+    PNG5.sync = PNGSync;
+    PNG5.prototype.pack = function() {
       if (!this.data || !this.data.length) {
         this.emit("error", "No data provided");
         return this;
@@ -83319,7 +83340,7 @@ var require_png = __commonJS({
       );
       return this;
     };
-    PNG4.prototype.parse = function(data, callback) {
+    PNG5.prototype.parse = function(data, callback) {
       if (callback) {
         let onParsed, onError;
         onParsed = function(parsedData) {
@@ -83337,27 +83358,27 @@ var require_png = __commonJS({
       this.end(data);
       return this;
     };
-    PNG4.prototype.write = function(data) {
+    PNG5.prototype.write = function(data) {
       this._parser.write(data);
       return true;
     };
-    PNG4.prototype.end = function(data) {
+    PNG5.prototype.end = function(data) {
       this._parser.end(data);
     };
-    PNG4.prototype._metadata = function(metadata) {
+    PNG5.prototype._metadata = function(metadata) {
       this.width = metadata.width;
       this.height = metadata.height;
       this.emit("metadata", metadata);
     };
-    PNG4.prototype._gamma = function(gamma) {
+    PNG5.prototype._gamma = function(gamma) {
       this.gamma = gamma;
     };
-    PNG4.prototype._handleClose = function() {
+    PNG5.prototype._handleClose = function() {
       if (!this._parser.writable && !this._packer.readable) {
         this.emit("close");
       }
     };
-    PNG4.bitblt = function(src, dst, srcX, srcY, width, height, deltaX, deltaY) {
+    PNG5.bitblt = function(src, dst, srcX, srcY, width, height, deltaX, deltaY) {
       srcX |= 0;
       srcY |= 0;
       width |= 0;
@@ -83379,11 +83400,11 @@ var require_png = __commonJS({
         );
       }
     };
-    PNG4.prototype.bitblt = function(dst, srcX, srcY, width, height, deltaX, deltaY) {
-      PNG4.bitblt(this, dst, srcX, srcY, width, height, deltaX, deltaY);
+    PNG5.prototype.bitblt = function(dst, srcX, srcY, width, height, deltaX, deltaY) {
+      PNG5.bitblt(this, dst, srcX, srcY, width, height, deltaX, deltaY);
       return this;
     };
-    PNG4.adjustGamma = function(src) {
+    PNG5.adjustGamma = function(src) {
       if (src.gamma) {
         for (let y = 0; y < src.height; y++) {
           for (let x = 0; x < src.width; x++) {
@@ -83398,8 +83419,8 @@ var require_png = __commonJS({
         src.gamma = 0;
       }
     };
-    PNG4.prototype.adjustGamma = function() {
-      PNG4.adjustGamma(this);
+    PNG5.prototype.adjustGamma = function() {
+      PNG5.adjustGamma(this);
     };
   }
 });
@@ -90282,14 +90303,14 @@ var require_parser2 = __commonJS({
             case "scalar":
             case "single-quoted-scalar":
             case "double-quoted-scalar": {
-              const fs54 = this.flowScalar(this.type);
+              const fs55 = this.flowScalar(this.type);
               if (atNextItem || it.value) {
-                map2.items.push({ start: start2, key: fs54, sep: [] });
+                map2.items.push({ start: start2, key: fs55, sep: [] });
                 this.onKeyLine = true;
               } else if (it.sep) {
-                this.stack.push(fs54);
+                this.stack.push(fs55);
               } else {
-                Object.assign(it, { key: fs54, sep: [] });
+                Object.assign(it, { key: fs55, sep: [] });
                 this.onKeyLine = true;
               }
               return;
@@ -90417,13 +90438,13 @@ var require_parser2 = __commonJS({
             case "scalar":
             case "single-quoted-scalar":
             case "double-quoted-scalar": {
-              const fs54 = this.flowScalar(this.type);
+              const fs55 = this.flowScalar(this.type);
               if (!it || it.value)
-                fc.items.push({ start: [], key: fs54, sep: [] });
+                fc.items.push({ start: [], key: fs55, sep: [] });
               else if (it.sep)
-                this.stack.push(fs54);
+                this.stack.push(fs55);
               else
-                Object.assign(it, { key: fs54, sep: [] });
+                Object.assign(it, { key: fs55, sep: [] });
               return;
             }
             case "flow-map-end":
@@ -96039,6 +96060,16 @@ var PLATFORMS = [
   "tvos",
   "android-tv"
 ];
+var DEBUGGER_NOT_CONNECTED_REASONS = [
+  "metro_not_running",
+  "no_app_connected",
+  "device_mismatch",
+  "cdp_unreachable",
+  "runtime_unresponsive",
+  "stale_connection",
+  "reconnecting"
+];
+var DEBUGGER_TOOL_OUTCOMES = ["connected", ...DEBUGGER_NOT_CONNECTED_REASONS];
 
 // ../telemetry/src/ai-identity.ts
 var AI_CLIENTS = [
@@ -96233,9 +96264,19 @@ var ALLOWED = {
     tool_invocation_id: UUID2,
     platform: PLATFORM,
     duration_ms: DURATION_MS,
+    // Schema-declared parameter names only (emit side filters against the tool's
+    // own zod shape and caps at 16 before this gate); the array validator also
+    // voids anything longer or with a non-identifier element.
+    invalid_params: arrayOf(matches(/^[a-z][a-z0-9_]{0,63}$/i, 64), 16),
     ...FAILURE_SIGNAL2,
     ...AI_TELEMETRY
   },
+  "debugger:tool_outcome": {
+    tool: oneOf(["debugger-status", "debugger-log-registry"]),
+    outcome: oneOf(DEBUGGER_TOOL_OUTCOMES),
+    platform: PLATFORM,
+    tool_invocation_id: UUID2
+  },
   "cli:run_fail": {
     tool: TOOL_NAME,
     duration_ms: DURATION_MS,
@@ -109729,11 +109770,29 @@ var CDPClient = class {
       };
       const onError = (err) => {
         cleanup();
-        reject(err);
+        reject(
+          new FailureError(
+            err.message,
+            {
+              error_code: FAILURE_CODES.DEBUGGER_CDP_CONNECT_FAILED,
+              failure_stage: "debugger_cdp_connect",
+              failure_area: "tool_server",
+              error_kind: "network"
+            },
+            { cause: err }
+          )
+        );
       };
       const onClose = () => {
         cleanup();
-        reject(new Error("WebSocket closed before open"));
+        reject(
+          new FailureError("WebSocket closed before open", {
+            error_code: FAILURE_CODES.DEBUGGER_CDP_SOCKET_CLOSED_BEFORE_OPEN,
+            failure_stage: "debugger_cdp_connect",
+            failure_area: "tool_server",
+            error_kind: "network"
+          })
+        );
       };
       const cleanup = () => {
         ws.removeListener("open", onOpen);
@@ -109798,12 +109857,33 @@ var CDPClient = class {
   send(method, params, timeout = DEFAULT_TIMEOUT_MS2) {
     return new Promise((resolve11, reject) => {
       if (!this.ws || this.ws.readyState !== wrapper_default.OPEN) {
-        return reject(new Error("CDP not connected"));
+        return reject(
+          new FailureError("CDP not connected", {
+            error_code: FAILURE_CODES.DEBUGGER_CDP_NOT_CONNECTED,
+            failure_stage: "debugger_cdp_send",
+            failure_area: "tool_server",
+            error_kind: "network"
+          })
+        );
       }
       const id = this.nextId++;
       const timer = setTimeout(() => {
         this.pending.delete(id);
-        reject(new Error(`CDP request ${method} (id=${id}) timed out`));
+        reject(
+          // The message carries its own recovery guidance so skills don't have
+          // to re-explain this state: the runtime is reachable but not
+          // answering, which agents otherwise read as a transient worth
+          // retry-looping (each loop iteration waits out this full timeout).
+          new FailureError(
+            `CDP request ${method} (id=${id}) timed out \u2014 the runtime accepted the connection but did not answer; it may be frozen, or paused at a breakpoint. debugger-status can still report "connected" in this state (the socket is open). Do not retry in a loop \u2014 restart the app, then reconnect and retry once.`,
+            {
+              error_code: FAILURE_CODES.DEBUGGER_CDP_REQUEST_TIMEOUT,
+              failure_stage: "debugger_cdp_send",
+              failure_area: "tool_server",
+              error_kind: "timeout"
+            }
+          )
+        );
       }, timeout);
       this.pending.set(id, {
         resolve: (result) => {
@@ -109971,14 +110051,20 @@ var CDPClient = class {
     else if (action === "disable") this.enabledDomains.delete(domain2);
   }
   cleanup() {
+    const connectionClosed = () => new FailureError("CDP connection closed", {
+      error_code: FAILURE_CODES.DEBUGGER_CDP_CONNECTION_CLOSED,
+      failure_stage: "debugger_cdp_lifecycle",
+      failure_area: "tool_server",
+      error_kind: "network"
+    });
     for (const [, req] of this.pending) {
       clearTimeout(req.timer);
-      req.reject(new Error("CDP connection closed"));
+      req.reject(connectionClosed());
     }
     this.pending.clear();
     for (const [, binding] of this.pendingBindings) {
       clearTimeout(binding.timer);
-      binding.reject(new Error("CDP connection closed"));
+      binding.reject(connectionClosed());
     }
     this.pendingBindings.clear();
     this.scripts.clear();
@@ -114838,6 +114924,45 @@ async function resolveFileInputs(def, body, lookupUpload) {
   return { args, fileInputs: resolved, cleanup };
 }
 
+// ../tool-server/src/utils/debugger/device-alias.ts
+var logicalIdToConnectId = /* @__PURE__ */ new Map();
+function rememberDeviceAlias(logicalDeviceId, connectDeviceId) {
+  if (!logicalDeviceId || logicalDeviceId === connectDeviceId) return;
+  logicalIdToConnectId.set(logicalDeviceId, connectDeviceId);
+}
+function canonicalDeviceId(deviceId) {
+  if (!deviceId) return deviceId;
+  return logicalIdToConnectId.get(deviceId) ?? deviceId;
+}
+function forgetDeviceAlias(logicalDeviceId) {
+  if (logicalDeviceId) logicalIdToConnectId.delete(logicalDeviceId);
+}
+var logicalKeyedConnectIds = /* @__PURE__ */ new Set();
+function rememberLogicalKeyedDevice(logicalDeviceId, connectDeviceId) {
+  if (logicalDeviceId && logicalDeviceId === connectDeviceId) {
+    logicalKeyedConnectIds.add(connectDeviceId.toLowerCase());
+  }
+}
+function isLogicalKeyedDevice(deviceId) {
+  return deviceId !== void 0 && logicalKeyedConnectIds.has(deviceId.toLowerCase());
+}
+function forgetLogicalKeyedDevice(connectDeviceId) {
+  logicalKeyedConnectIds.delete(connectDeviceId.toLowerCase());
+}
+
+// ../tool-server/src/utils/invalid-params.ts
+function deriveInvalidParams(error52, declared) {
+  const out = [];
+  for (const issue2 of error52.issues) {
+    const name = issue2.code === "unrecognized_keys" ? "unrecognized_keys" : String(issue2.path[0] ?? "");
+    if (!name) continue;
+    if (name !== "unrecognized_keys" && !declared.has(name)) continue;
+    if (!out.includes(name)) out.push(name);
+    if (out.length >= 16) break;
+  }
+  return out;
+}
+
 // ../tool-server/src/chromium-server/http-api.ts
 var import_express2 = __toESM(require_express2());
 init_wrapper();
@@ -115122,7 +115247,8 @@ function extractDeviceArg(data) {
 function inferPlatform(deviceId) {
   if (!deviceId) return null;
   try {
-    return refineTvPlatform(resolveDevice(deviceId).platform, deviceId);
+    const canonical = canonicalDeviceId(deviceId) ?? deviceId;
+    return refineTvPlatform(resolveDevice(canonical).platform, canonical);
   } catch {
     return null;
   }
@@ -115393,7 +115519,7 @@ function createHttpApp(registry2, options) {
       const name = req.params.name;
       const requestStartedAt = performance.now();
       const aiMeta = extractAiTelemetryMeta(req);
-      const emitHttpFailure = (signal, parsedDataForMeta = req.body) => {
+      const emitHttpFailure = (signal, parsedDataForMeta = req.body, extraMeta) => {
         if (!options?.recordFailure) return;
         const failedDeviceArg = extractDeviceArg(parsedDataForMeta);
         const platform = inferPlatform(failedDeviceArg);
@@ -115401,6 +115527,7 @@ function createHttpApp(registry2, options) {
           name,
           {
             ...platform ? { platform } : {},
+            ...extraMeta?.invalid_params?.length ? { invalid_params: extraMeta.invalid_params } : {},
             ...aiMeta
           },
           signal,
@@ -115444,6 +115571,7 @@ function createHttpApp(registry2, options) {
       if (def.zodSchema) {
         const parseResult = def.zodSchema.safeParse(bodyArgs);
         if (!parseResult.success) {
+          const declared = new Set(Object.keys(def.zodSchema.shape ?? {}));
           emitHttpFailure(
             {
               error_code: FAILURE_CODES.HTTP_ZOD_VALIDATION_FAILED,
@@ -115451,7 +115579,8 @@ function createHttpApp(registry2, options) {
               failure_area: "http",
               error_kind: "validation"
             },
-            req.body
+            req.body,
+            { invalid_params: deriveInvalidParams(parseResult.error, declared) }
           );
           res.status(400).json({ error: parseResult.error.message });
           return;
@@ -116258,6 +116387,22 @@ var chromiumJsRuntimeDebuggerBlueprint = {
   getDependencies(_payload) {
     return { chromium: `${CHROMIUM_CDP_NAMESPACE}:${_payload}` };
   },
+  // Deliberately NO recoverable() here. The registry's self-heal disposes the
+  // recovering node before it retries, and this blueprint's dispose closes the
+  // LogFileWriter — which UNLINKS the session's captured console log from disk
+  // (log-file-writer.ts) — so a recovery pass would destroy the logs whether or
+  // not the retry then succeeds. It would also buy nothing: the one window
+  // where a call fails while this node and its ChromiumCdp dependency stay
+  // RUNNING is a tab switch, where CDPClient.reconnect() rejects in-flight
+  // requests with CONNECTION_CLOSED (late sends with NOT_CONNECTED) but
+  // re-points the SAME client object at the new tab — the cached node heals
+  // itself for the next call without any dispose. The failing call surfaces a
+  // classified error that debugger-status maps to a structured "reconnecting"
+  // result with retry-once guidance. A genuinely dead Chromium socket instead
+  // fires ChromiumCdp's own terminated event, whose teardown cascades into this
+  // dependent — the node leaves RUNNING and the next call re-resolves fresh.
+  // (Same log-preservation reasoning as debugger-log-registry's missing socket
+  // gate — see that tool's comment.)
   async factory(deps, payload, options) {
     const opts = options;
     const device = opts?.device;
@@ -117460,7 +117605,7 @@ async function discoverMetro(port) {
     statusRes = await fetch(`http://localhost:${port}/status`);
   } catch (err) {
     throw new FailureError(
-      `Metro at port ${port} is not running (got: ${err instanceof Error ? err.message : String(err)})`,
+      `Metro at port ${port} is not running (got: ${err instanceof Error ? err.message : String(err)}). Do not retry in a loop \u2014 the result will not change until Metro is started. Start Metro (e.g. \`npx react-native start\` or \`npx expo start\`) or ask the user, wait for it to report ready, then retry once.`,
       {
         error_code: FAILURE_CODES.DEBUGGER_METRO_NOT_RUNNING,
         failure_stage: "debugger_discover_metro_status",
@@ -117469,10 +117614,24 @@ async function discoverMetro(port) {
       }
     );
   }
-  const statusText = await statusRes.text();
+  const notRunning = (stage, err) => new FailureError(
+    `Metro at port ${port} is not running (got: ${err instanceof Error ? err.message : String(err)}). Do not retry in a loop \u2014 the result will not change until Metro is started. Start Metro (e.g. \`npx react-native start\` or \`npx expo start\`) or ask the user, wait for it to report ready, then retry once.`,
+    {
+      error_code: FAILURE_CODES.DEBUGGER_METRO_NOT_RUNNING,
+      failure_stage: stage,
+      failure_area: "tool_server",
+      error_kind: "network"
+    }
+  );
+  let statusText;
+  try {
+    statusText = await statusRes.text();
+  } catch (err) {
+    throw notRunning("debugger_discover_metro_status_body", err);
+  }
   if (!statusText.includes("packager-status:running")) {
     throw new FailureError(
-      `Metro at port ${port} is not running (got: ${statusText.slice(0, 100)})`,
+      `Metro at port ${port} is not running (got: ${statusText.slice(0, 100)}). Something else is listening on this port \u2014 it did not answer like Metro. Do not retry in a loop; find the port Metro actually runs on (or start it), then retry once.`,
       {
         error_code: FAILURE_CODES.DEBUGGER_METRO_NOT_RUNNING,
         failure_stage: "debugger_discover_metro_status",
@@ -117482,14 +117641,19 @@ async function discoverMetro(port) {
     );
   }
   const projectRoot = statusRes.headers.get("X-React-Native-Project-Root") ?? "";
-  const listRes = await fetch(`http://localhost:${port}/json/list`);
+  let listRes;
+  try {
+    listRes = await fetch(`http://localhost:${port}/json/list`);
+  } catch (err) {
+    throw notRunning("debugger_discover_metro_list", err);
+  }
   const parsed = await listRes.json().catch(() => null);
   const targets = (Array.isArray(parsed) ? parsed : []).filter(
     (t) => t?.vm !== DECOY_VM
   );
   if (!targets.length) {
     throw new FailureError(
-      `Metro at port ${port} has no CDP targets \u2014 is a React Native app connected?`,
+      `Metro at port ${port} has no CDP targets \u2014 is a React Native app connected? Do not retry immediately \u2014 this will not change until an app attaches. Launch or restart the RN app on the target device (launch-app / restart-app), wait a few seconds for the bundle to load, then retry once. On Android, a missing port reverse-proxy is the most common cause (see the metro-debugger skill's Android prerequisites).`,
       {
         error_code: FAILURE_CODES.DEBUGGER_METRO_NO_TARGETS,
         failure_stage: "debugger_discover_metro_targets",
@@ -117502,6 +117666,7 @@ async function discoverMetro(port) {
 }
 
 // ../tool-server/src/utils/debugger/target-selection.ts
+init_src();
 function deviceKey(target) {
   const logicalId = target.reactNative?.logicalDeviceId;
   if (logicalId) return logicalId;
@@ -117535,8 +117700,14 @@ function selectTarget(targets, port, options) {
         const listed = [...distinctDevices.values()].map(
           (d) => d.logicalId ? `${d.name ?? "unknown"} (${d.logicalId})` : `${d.name ?? "unknown"} (legacy inspector \u2014 no logicalDeviceId)`
         ).join(", ");
-        throw new Error(
-          `No debugger target matches device_id "${deviceId}". ${distinctDevices.size} devices are connected to Metro on port ${port}: ${listed}. Re-target with the logicalDeviceId in parentheses \u2014 that is what debugger-connect returns and what subsequent debugger-* calls must pass. A legacy-inspector device (RN 0.72 / Vega) reports none and cannot be singled out of a shared Metro: give it its own Metro port.`
+        throw new FailureError(
+          `No debugger target matches device_id "${deviceId}". ${distinctDevices.size} devices are connected to Metro on port ${port}: ${listed}. Re-target with the logicalDeviceId in parentheses \u2014 that is what debugger-connect returns and what subsequent debugger-* calls must pass. A legacy-inspector device (RN 0.72 / Vega) reports none and cannot be singled out of a shared Metro: give it its own Metro port.`,
+          {
+            error_code: FAILURE_CODES.DEBUGGER_TARGET_DEVICE_MISMATCH,
+            failure_stage: "debugger_select_target",
+            failure_area: "tool_server",
+            error_kind: "not_found"
+          }
         );
       }
     }
@@ -117570,32 +117741,6 @@ function normalizeWsUrl(wsUrl, port) {
   return url2.toString();
 }
 
-// ../tool-server/src/utils/debugger/device-alias.ts
-var logicalIdToConnectId = /* @__PURE__ */ new Map();
-function rememberDeviceAlias(logicalDeviceId, connectDeviceId) {
-  if (!logicalDeviceId || logicalDeviceId === connectDeviceId) return;
-  logicalIdToConnectId.set(logicalDeviceId, connectDeviceId);
-}
-function canonicalDeviceId(deviceId) {
-  if (!deviceId) return deviceId;
-  return logicalIdToConnectId.get(deviceId) ?? deviceId;
-}
-function forgetDeviceAlias(logicalDeviceId) {
-  if (logicalDeviceId) logicalIdToConnectId.delete(logicalDeviceId);
-}
-var logicalKeyedConnectIds = /* @__PURE__ */ new Set();
-function rememberLogicalKeyedDevice(logicalDeviceId, connectDeviceId) {
-  if (logicalDeviceId && logicalDeviceId === connectDeviceId) {
-    logicalKeyedConnectIds.add(connectDeviceId.toLowerCase());
-  }
-}
-function isLogicalKeyedDevice(deviceId) {
-  return deviceId !== void 0 && logicalKeyedConnectIds.has(deviceId.toLowerCase());
-}
-function forgetLogicalKeyedDevice(connectDeviceId) {
-  logicalKeyedConnectIds.delete(connectDeviceId.toLowerCase());
-}
-
 // ../tool-server/src/utils/debugger/source-resolver.ts
 var fs22 = __toESM(require("node:fs/promises"));
 var path19 = __toESM(require("node:path"));
@@ -117911,6 +118056,25 @@ var jsRuntimeDebuggerBlueprint = {
   getURN(payload) {
     return `${JS_RUNTIME_DEBUGGER_NAMESPACE}:${payload}`;
   },
+  // Consulted by the registry's dispose-and-retry-once self-heal, and only for
+  // a node still in RUNNING state. On this blueprint a detected socket death
+  // tears the node down via the terminated cascade before the failing call's
+  // catch runs, so the only recoverable window is the send() guard rejecting
+  // while the WebSocket is CLOSING but the close event has not dispatched yet —
+  // there the request provably never left the host, making a retry safe.
+  // Deliberately NOT recoverable:
+  // - DEBUGGER_CDP_CONNECTION_CLOSED: the request was delivered and may have
+  //   taken effect (double-execution risk); on this path the node has also
+  //   already left RUNNING when it fires.
+  // - DEBUGGER_CDP_REQUEST_TIMEOUT: the request may have taken effect, and a
+  //   hung-but-open runtime (e.g. paused at a breakpoint) is not fixed by
+  //   reconnecting.
+  // - Metro discovery / target-selection codes: init-path failures — the node
+  //   never reaches RUNNING, so recovery is never consulted, and a retry would
+  //   be hopeless anyway.
+  recoverable(error52) {
+    return getFailureSignal(error52)?.error_code === FAILURE_CODES.DEBUGGER_CDP_NOT_CONNECTED;
+  },
   async factory(_deps, payload, options) {
     const colonIdx = payload.indexOf(":");
     if (colonIdx < 0) {
@@ -129807,46 +129971,158 @@ Use when starting a debug session or before calling other debugger-* tools. Fail
 
 // ../tool-server/src/tools/debugger/debugger-status.ts
 init_zod();
+
+// ../tool-server/src/tools/debugger/not-connected.ts
+init_src();
+var GUIDANCE = {
+  metro_not_running: "Metro is not running on this port. Do not retry in a loop \u2014 the result will not change until Metro is started. Start Metro (e.g. `npx react-native start` or `npx expo start`) or ask the user, wait for it to report ready, then retry once.",
+  no_app_connected: "Metro is running but no app is attached. Do not retry immediately \u2014 launch or restart the RN app on the target device (launch-app / restart-app), wait a few seconds for the bundle to load, then retry once.",
+  device_mismatch: "The device_id does not match any debugger target on this Metro. Re-target with the logicalDeviceId listed in the detail message, or give the device its own Metro port.",
+  cdp_unreachable: "The runtime's CDP endpoint could not be reached. Verify the app is running (launch-app), then call debugger-connect and retry once.",
+  runtime_unresponsive: "The runtime accepted the debugger connection but did not answer within the timeout \u2014 it is likely frozen, or paused at a breakpoint. Do not retry in a loop (each attempt waits out the full timeout). Check the app; if it is hung, restart it (restart-app), then retry once.",
+  stale_connection: "The cached debugger connection went stale; it has been discarded. Restart the app (restart-app) if it is not running, then call debugger-connect \u2014 the next call reconnects fresh.",
+  reconnecting: "The debugger connection is being re-established (the previous one was torn down or a tab switch is in progress). Wait a moment and retry once."
+};
+var NOT_CONNECTED_CODE_MAP = {
+  [FAILURE_CODES.DEBUGGER_METRO_NOT_RUNNING]: "metro_not_running",
+  [FAILURE_CODES.DEBUGGER_METRO_NO_TARGETS]: "no_app_connected",
+  [FAILURE_CODES.DEBUGGER_TARGET_DEVICE_MISMATCH]: "device_mismatch",
+  [FAILURE_CODES.DEBUGGER_CDP_CONNECT_FAILED]: "cdp_unreachable",
+  [FAILURE_CODES.DEBUGGER_CDP_SOCKET_CLOSED_BEFORE_OPEN]: "cdp_unreachable",
+  [FAILURE_CODES.DEBUGGER_CDP_NOT_CONNECTED]: "cdp_unreachable",
+  [FAILURE_CODES.DEBUGGER_CDP_CONNECTION_CLOSED]: "cdp_unreachable",
+  // Reachable from the connect pipeline's enable/binding sends when the target
+  // accepts the socket but its JS runtime never answers (frozen, or paused at a
+  // breakpoint). Post-connect hangs are different: an OPEN socket still reports
+  // status "connected" (see the socket-state gate comment in debugger-status).
+  [FAILURE_CODES.DEBUGGER_CDP_REQUEST_TIMEOUT]: "runtime_unresponsive",
+  [FAILURE_CODES.CHROMIUM_CDP_UNREACHABLE]: "cdp_unreachable",
+  // "Reached but not CDP / malformed answer" — a non-CDP server squatting the
+  // debug port, an HTTP error status, or a non-JSON body. Same precondition
+  // class as the Metro arm's non-Metro-port-occupant (detail names what
+  // actually answered), so it must not escape as a thrown tool failure.
+  [FAILURE_CODES.CHROMIUM_CDP_INVALID_RESPONSE]: "cdp_unreachable",
+  [FAILURE_CODES.CHROMIUM_CDP_NO_PAGE_TARGET]: "cdp_unreachable",
+  [FAILURE_CODES.REGISTRY_SERVICE_TERMINATING]: "reconnecting"
+};
+function classifyNotConnected(err) {
+  const code = getFailureSignal(err)?.error_code;
+  return code ? NOT_CONNECTED_CODE_MAP[code] : void 0;
+}
+var CHROMIUM_GUIDANCE = {
+  cdp_unreachable: "The app's CDP endpoint could not be reached (or did not answer like CDP \u2014 see detail). launch-app cannot start a Chromium app; make sure the app is running with --remote-debugging-port (for an Electron app, boot-device with electronAppPath relaunches it), then retry once.",
+  runtime_unresponsive: "The app accepted the debugger connection but did not answer within the timeout \u2014 it is likely frozen. Do not retry in a loop (each attempt waits out the full timeout). Restart the app (for an Electron app, boot-device with electronAppPath and force: true), then retry once."
+};
+function buildNotConnected(reason, err, params) {
+  const isChromium = params.device_id?.startsWith(CHROMIUM_ID_PREFIX) ?? false;
+  return {
+    status: "not_connected",
+    connected: false,
+    ...isChromium ? {} : { port: params.port },
+    reason,
+    detail: err instanceof Error ? err.message : String(err),
+    guidance: (isChromium ? CHROMIUM_GUIDANCE[reason] : void 0) ?? GUIDANCE[reason]
+  };
+}
+function trackDebuggerOutcome(tool, outcome, params, ctx) {
+  let platform;
+  try {
+    const deviceId = canonicalDeviceId(params.device_id);
+    platform = deviceId ? classifyDeviceForTelemetry(deviceId) : void 0;
+  } catch {
+    platform = void 0;
+  }
+  track("debugger:tool_outcome", {
+    tool,
+    outcome,
+    ...platform ? { platform } : {},
+    ...ctx?.toolInvocationId ? { tool_invocation_id: ctx.toolInvocationId } : {}
+  });
+}
+async function resolveDebuggerService(registry2, params) {
+  const ref = debuggerServiceRef(params);
+  return typeof ref === "string" ? registry2.resolveService(ref) : registry2.resolveService(ref.urn, ref.options);
+}
+function isDebuggerNotConnectedResult(toolId, result) {
+  return (toolId === "debugger-status" || toolId === "debugger-log-registry") && typeof result === "object" && result !== null && result.status === "not_connected";
+}
+
+// ../tool-server/src/tools/debugger/debugger-status.ts
 var zodSchema30 = external_exports.object({
   port: external_exports.coerce.number().default(8081).describe("Metro server port (ignored for Chromium)"),
   device_id: external_exports.string().describe(
     "Device id from list-devices \u2014 the SAME id you passed to debugger-connect (iOS simulator UDID, Android serial, Vega serial, or Chromium device id). The logicalDeviceId debugger-connect returns also resolves here, but prefer the stable list-devices id."
   )
 });
-var debuggerStatusTool = {
-  id: "debugger-status",
-  interaction: {
-    startedMsg: () => "Checking JavaScript debugger",
-    completedMsg: () => "Checked JavaScript debugger",
-    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to check JavaScript debugger: ${failureSignal2.error_code}`
-  },
-  description: `Get JS runtime debugger connection status and diagnostic info.
-Use when you need to verify connectivity before using other debugger tools. Returns port, projectRoot (empty on Chromium and on legacy Metro, e.g. Vega), deviceName, appName, logicalDeviceId (absent on Vega), isNewDebugger (false on the legacy inspector), connected flag, loadedScripts count, and sourceMapReady (always true \u2014 waits for pending source maps before returning; no-op on Chromium). Fails if the runtime is unreachable.`,
-  zodSchema: zodSchema30,
-  capability: DEBUGGER_TOOL_CAPABILITY,
-  services: (params) => ({
-    debugger: debuggerServiceRef(params)
-  }),
-  async execute(services) {
-    const api = services.debugger;
-    await api.sourceMaps.waitForPending();
-    return {
-      port: api.port,
-      projectRoot: api.projectRoot,
-      deviceName: api.deviceName,
-      appName: api.appName,
-      logicalDeviceId: api.logicalDeviceId,
-      isNewDebugger: api.isNewDebugger,
-      connected: api.cdp.isConnected(),
-      loadedScripts: api.cdp.getLoadedScripts().size,
-      enabledDomains: [...api.cdp.getEnabledDomains()],
-      sourceMapReady: true
-    };
-  }
-};
+function createDebuggerStatusTool(registry2) {
+  return {
+    id: "debugger-status",
+    interaction: {
+      startedMsg: () => "Checking JavaScript debugger",
+      completedMsg: ({ result }) => result.status === "connected" ? "Checked JavaScript debugger" : "JavaScript debugger is not connected",
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to check JavaScript debugger: ${failureSignal2.error_code}`
+    },
+    description: `Get JS runtime debugger connection status and diagnostic info.
+Use when you need to verify connectivity before using other debugger tools. Never fails when the runtime is simply unreachable \u2014 it returns a discriminated result instead:
+- { status: "connected", ... } with port, projectRoot (empty on Chromium and on legacy Metro, e.g. Vega), deviceName, appName, logicalDeviceId (absent on Vega), isNewDebugger (false on the legacy inspector), connected flag, loadedScripts count, and sourceMapReady (always true \u2014 waits for pending source maps before returning; no-op on Chromium).
+- { status: "not_connected", connected: false, reason, detail, guidance } (port omitted on Chromium) when Metro is not running (reason "metro_not_running"), no app is attached ("no_app_connected"), the device_id matches no target ("device_mismatch"), the CDP endpoint is unreachable or answered malformed ("cdp_unreachable"), the runtime accepted the connection but never answered ("runtime_unresponsive"), the cached connection went stale ("stale_connection"), or a reconnect is in flight ("reconnecting"). Follow the guidance field \u2014 do not retry in a loop.`,
+    zodSchema: zodSchema30,
+    capability: DEBUGGER_TOOL_CAPABILITY,
+    // Resolved manually in execute so a not-connected precondition becomes a
+    // structured result instead of a service-resolution tool failure.
+    services: () => ({}),
+    async execute(_services, params, ctx) {
+      try {
+        const api = await resolveDebuggerService(registry2, params);
+        await api.sourceMaps.waitForPending();
+        if (!api.cdp.isConnected()) {
+          const isChromium = params.device_id?.startsWith(CHROMIUM_ID_PREFIX) ?? false;
+          if (isChromium) {
+            const result = buildNotConnected(
+              "reconnecting",
+              new Error("CDP socket is reconnecting (tab switch in progress)"),
+              params
+            );
+            trackDebuggerOutcome("debugger-status", "reconnecting", params, ctx);
+            return result;
+          }
+          trackDebuggerOutcome("debugger-status", "stale_connection", params, ctx);
+          const ref = debuggerServiceRef(params);
+          await registry2.disposeService(typeof ref === "string" ? ref : ref.urn).catch(() => {
+          });
+          return buildNotConnected(
+            "stale_connection",
+            new Error("Cached debugger connection is no longer open"),
+            params
+          );
+        }
+        trackDebuggerOutcome("debugger-status", "connected", params, ctx);
+        return {
+          status: "connected",
+          port: api.port,
+          projectRoot: api.projectRoot,
+          deviceName: api.deviceName,
+          appName: api.appName,
+          logicalDeviceId: api.logicalDeviceId,
+          isNewDebugger: api.isNewDebugger,
+          connected: true,
+          loadedScripts: api.cdp.getLoadedScripts().size,
+          enabledDomains: [...api.cdp.getEnabledDomains()],
+          sourceMapReady: true
+        };
+      } catch (err) {
+        const reason = classifyNotConnected(err);
+        if (!reason) throw err;
+        trackDebuggerOutcome("debugger-status", reason, params, ctx);
+        return buildNotConnected(reason, err, params);
+      }
+    }
+  };
+}
 
 // ../tool-server/src/tools/debugger/debugger-evaluate.ts
 init_zod();
+init_src();
 var zodSchema31 = external_exports.object({
   port: external_exports.coerce.number().default(8081).describe("Metro server port (ignored for Chromium)"),
   device_id: external_exports.string().describe(
@@ -129870,7 +130146,24 @@ Returns the evaluation result as a JSON-serializable value, along with deviceNam
   }),
   async execute(services, params) {
     const api = services.debugger;
-    const result = await api.cdp.evaluate(params.expression);
+    let result;
+    try {
+      result = await api.cdp.evaluate(params.expression);
+    } catch (err) {
+      if (err instanceof Error && getFailureSignal(err)?.error_code === FAILURE_CODES.DEBUGGER_CDP_RUNTIME_EXCEPTION) {
+        throw new FailureError(
+          err.message,
+          {
+            error_code: FAILURE_CODES.DEBUGGER_EVALUATE_EXPRESSION_THREW,
+            failure_stage: "debugger_evaluate_expression",
+            failure_area: "tool_server",
+            error_kind: "unknown"
+          },
+          { cause: err }
+        );
+      }
+      throw err;
+    }
     return {
       result,
       deviceName: api.deviceName,
@@ -131363,48 +131656,60 @@ var zodSchema35 = external_exports.object({
     "Device id from list-devices \u2014 the SAME id you passed to debugger-connect (iOS simulator UDID, Android serial, Vega serial, or Chromium device id). The logicalDeviceId debugger-connect returns also resolves here, but prefer the stable list-devices id."
   )
 });
-var debuggerLogRegistryTool = {
-  id: "debugger-log-registry",
-  interaction: {
-    startedMsg: () => "Reading app logs",
-    completedMsg: () => "Read app logs",
-    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to read app logs: ${failureSignal2.error_code}`
-  },
-  description: `Get a summary of all console logs captured from the app's JS runtime.
+function createDebuggerLogRegistryTool(registry2) {
+  return {
+    id: "debugger-log-registry",
+    interaction: {
+      startedMsg: () => "Reading app logs",
+      completedMsg: ({ result }) => result.status === "connected" ? "Read app logs" : "JavaScript debugger is not connected \u2014 no logs captured",
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to read app logs: ${failureSignal2.error_code}`
+    },
+    description: `Get a summary of all console logs captured from the app's JS runtime.
 Returns the log file path, entry counts by level, and message clusters (grouped by similarity). Works against Hermes (iOS / Android / Vega) and V8 (Chromium).
-Use when investigating warnings, errors, or unexpected output \u2014 call this first for an overview, then read the returned file for details. Returns empty stats if no log data has been captured yet \u2014 but check { note }, which is present only when the stats are empty BECAUSE a stop-all-simulator-servers tore the previous debugger session down and deleted its log file. Absent that note, empty really does mean the app has logged nothing.`,
-  zodSchema: zodSchema35,
-  capability: DEBUGGER_TOOL_CAPABILITY,
-  services: (params) => ({
-    debugger: debuggerServiceRef(params)
-  }),
-  async execute(services, params) {
-    const api = services.debugger;
-    const stats = api.logWriter.getStats();
-    const clusters = api.logWriter.getClusters(20);
-    const response = {
-      ...stats,
-      clusters,
-      deviceName: api.deviceName,
-      appName: api.appName,
-      logicalDeviceId: api.logicalDeviceId
-    };
-    if (stats.totalEntries === 0) {
-      const aliases = [
-        canonicalDeviceId(params.device_id),
-        params.device_id,
-        api.logicalDeviceId
-      ].filter((id) => id !== void 0);
-      let reaped2;
-      for (const id of new Set(aliases)) {
-        const entry = takeReapedSession("js-runtime-debugger", id);
-        reaped2 ??= entry;
+Use when investigating warnings, errors, or unexpected output \u2014 call this first for an overview, then read the returned file for details. Returns empty stats if no log data has been captured yet \u2014 but check { note }, which is present only when the stats are empty BECAUSE a stop-all-simulator-servers tore the previous debugger session down and deleted its log file. Absent that note, empty really does mean the app has logged nothing.
+When the debugger cannot be reached, this tool does not fail: it returns { status: "not_connected", reason, detail, guidance } with NO log file \u2014 follow the guidance (do not retry in a loop, and do not try to read a log file from this state). A "connected" result's stats may come from a session whose socket has since died \u2014 use debugger-status, not this tool, to judge debugger health.`,
+    zodSchema: zodSchema35,
+    capability: DEBUGGER_TOOL_CAPABILITY,
+    // Resolved manually in execute so a not-connected precondition becomes a
+    // structured result instead of a service-resolution tool failure.
+    services: () => ({}),
+    async execute(_services, params, ctx) {
+      try {
+        const api = await resolveDebuggerService(registry2, params);
+        const stats = api.logWriter.getStats();
+        const clusters = api.logWriter.getClusters(20);
+        trackDebuggerOutcome("debugger-log-registry", "connected", params, ctx);
+        const response = {
+          status: "connected",
+          ...stats,
+          clusters,
+          deviceName: api.deviceName,
+          appName: api.appName,
+          logicalDeviceId: api.logicalDeviceId
+        };
+        if (stats.totalEntries === 0) {
+          const aliases = [
+            canonicalDeviceId(params.device_id),
+            params.device_id,
+            api.logicalDeviceId
+          ].filter((id) => id !== void 0);
+          let reaped2;
+          for (const id of new Set(aliases)) {
+            const entry = takeReapedSession("js-runtime-debugger", id);
+            reaped2 ??= entry;
+          }
+          if (reaped2) response.note = describeReapedSession(reaped2, "JS-runtime debugger session");
+        }
+        return response;
+      } catch (err) {
+        const reason = classifyNotConnected(err);
+        if (!reason) throw err;
+        trackDebuggerOutcome("debugger-log-registry", reason, params, ctx);
+        return buildNotConnected(reason, err, params);
       }
-      if (reaped2) response.note = describeReapedSession(reaped2, "JS-runtime debugger session");
     }
-    return response;
-  }
-};
+  };
+}
 
 // ../tool-server/src/tools/network/network-logs.ts
 init_zod();
@@ -135709,14 +136014,14 @@ function parseHangsXml(xml) {
 function parseLeaksXml(xml) {
   const leaks = [];
   const rowRe = /<row\s+([^>]*?)\/>/g;
-  let rm7;
-  while ((rm7 = rowRe.exec(xml)) !== null) {
-    const objectType = attr(rm7[0], "leaked-object") ?? "Unknown";
-    const sizeStr = attr(rm7[0], "size");
+  let rm8;
+  while ((rm8 = rowRe.exec(xml)) !== null) {
+    const objectType = attr(rm8[0], "leaked-object") ?? "Unknown";
+    const sizeStr = attr(rm8[0], "size");
     const sizeBytes = sizeStr ? parseInt(sizeStr, 10) : 0;
-    const responsibleFrame = attr(rm7[0], "responsible-frame") ?? "Unknown";
-    const responsibleLibrary = attr(rm7[0], "responsible-library") ?? "";
-    const countStr = attr(rm7[0], "count");
+    const responsibleFrame = attr(rm8[0], "responsible-frame") ?? "Unknown";
+    const responsibleLibrary = attr(rm8[0], "responsible-library") ?? "";
+    const countStr = attr(rm8[0], "count");
     const count2 = countStr ? parseInt(countStr, 10) : 1;
     leaks.push({
       objectType,
@@ -142440,10 +142745,18 @@ function waitToYaml(condition, selector, expectedText, textMatch, timeoutMs) {
   if (timeoutMs !== void 0) body.timeout = timeoutMs;
   return body;
 }
+function idleToYaml(step) {
+  const body = { idle: true };
+  if (step.stableFor !== void 0) body.stableFor = step.stableFor;
+  if (step.timeout !== void 0) body.timeout = step.timeout;
+  return { await: body };
+}
 function toYamlStep(step) {
   switch (step.kind) {
     case "echo":
       return { echo: step.message };
+    case "idle":
+      return idleToYaml(step);
     case "launch":
       return { launch: step.app };
     case "run":
@@ -142735,16 +143048,14 @@ var TEXT_MATCH_MODES = Object.keys({
 });
 var SCROLL_DIRECTIONS = ["up", "down", "left", "right"];
 function parseWaitFields(raw, kind) {
+  const legalKeys = kind === "await" ? [...WAIT_CONDITIONS, IDLE_CONDITION] : WAIT_CONDITIONS;
   if (raw === null || typeof raw !== "object") {
-    badEntry({ [kind]: raw }, `${kind} needs a condition (${WAIT_CONDITIONS.join(", ")})`);
+    badEntry({ [kind]: raw }, `${kind} needs a condition (${legalKeys.join(", ")})`);
   }
   const b = raw;
   const present = WAIT_CONDITIONS.filter((c) => c in b);
   if (present.length !== 1) {
-    badEntry(
-      { [kind]: b },
-      `${kind} needs exactly one condition key (${WAIT_CONDITIONS.join(", ")})`
-    );
+    badEntry({ [kind]: b }, `${kind} needs exactly one condition key (${legalKeys.join(", ")})`);
   }
   const condition = present[0];
   let timeout;
@@ -142755,13 +143066,7 @@ function parseWaitFields(raw, kind) {
         "assert has no timeout \u2014 it is an immediate check; use `await` for a timed wait"
       );
     }
-    if (typeof b.timeout !== "number" || !Number.isFinite(b.timeout) || b.timeout <= 0) {
-      badEntry(
-        { [kind]: b },
-        "await.timeout needs a positive number of milliseconds (e.g. `timeout: 10000`)"
-      );
-    }
-    timeout = b.timeout;
+    timeout = parseAwaitTimeout({ [kind]: b }, b.timeout);
   }
   rejectUnknownKeys(
     { [kind]: b },
@@ -142806,6 +143111,76 @@ function parseWaitFields(raw, kind) {
   }
   return { condition, selector: parseSelector(b[condition], `${kind}.${condition}`), timeout };
 }
+var IDLE_CONDITION = "idle";
+var IDLE_DEFAULT_TIMEOUT_MS = 7500;
+var IDLE_DEFAULT_STABLE_FOR_MS = 250;
+var IDLE_POLL_MS = 200;
+var IDLE_MIN_STILL_INTERVALS = 2;
+var IDLE_SETTLE_SPAN_MS = IDLE_MIN_STILL_INTERVALS * IDLE_POLL_MS;
+function idleMinimumTimeoutMs(stableFor) {
+  return Math.max(IDLE_SETTLE_SPAN_MS, stableFor) + IDLE_POLL_MS;
+}
+var IDLE_MAX_STABLE_FOR_MS = 6e5;
+function parseAwaitTimeout(entry, value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    badEntry(
+      entry,
+      "await.timeout needs a positive number of milliseconds (e.g. `timeout: 10000`)"
+    );
+  }
+  return value;
+}
+function parseBoundedMs(entry, value, where, max) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > max) {
+    badEntry(entry, `${where} needs an integer between 0 and ${max} (milliseconds)`);
+  }
+  return value;
+}
+function parseIdleFields(raw, kind) {
+  const entry = { [kind]: raw };
+  if (kind !== "await") {
+    const mixed = WAIT_CONDITIONS.filter((c) => c in raw);
+    badEntry(
+      entry,
+      "idle has no assert form \u2014 it waits for the screen to stop changing, which is an `await`" + (mixed.length > 0 ? `. Give it its own step as \`await: { idle: true }\` and leave \`${mixed.join(
+        "`, `"
+      )}\` in the assert \u2014 a step checks exactly one condition` : "")
+    );
+  }
+  rejectUnknownKeys(entry, raw, ["idle", "stableFor", "timeout"], kind);
+  if (raw.idle !== true) {
+    badEntry(entry, "idle takes only `true` (`await: { idle: true }`)");
+  }
+  const step = { kind: "idle" };
+  if ("timeout" in raw) step.timeout = parseAwaitTimeout(entry, raw.timeout);
+  if (raw.stableFor !== void 0) {
+    step.stableFor = parseBoundedMs(entry, raw.stableFor, "idle.stableFor", IDLE_MAX_STABLE_FOR_MS);
+  }
+  const timeoutMs = step.timeout ?? IDLE_DEFAULT_TIMEOUT_MS;
+  const stableFor = step.stableFor ?? IDLE_DEFAULT_STABLE_FOR_MS;
+  const needed = idleMinimumTimeoutMs(stableFor);
+  if (timeoutMs < needed) {
+    badEntry(
+      entry,
+      `idle needs a timeout of at least ${needed}ms to hold still for ${step.stableFor === void 0 ? `the default ` : ``}${stableFor}ms: a settle is ${IDLE_MIN_STILL_INTERVALS + 1} reads spanning ${IDLE_MIN_STILL_INTERVALS} ${IDLE_POLL_MS}ms polls, and the hold is counted across those polls rather than after them \u2014 so the wait has to contain whichever of the two is longer, plus the ${IDLE_POLL_MS}ms of budget the closing round has to have left to be allowed to start. Raise \`timeout\`${step.stableFor === void 0 ? "" : " or lower `stableFor`"}`
+    );
+  }
+  return step;
+}
+function isIdleCondition(raw, kind) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return false;
+  const body = raw;
+  if (!(IDLE_CONDITION in body)) return false;
+  if (kind === "assert") return true;
+  const selectorConditions = WAIT_CONDITIONS.filter((c) => c in body);
+  if (selectorConditions.length > 0) {
+    badEntry(
+      { [kind]: body },
+      `${kind} mixes \`${IDLE_CONDITION}\` with \`${selectorConditions.join("`, `")}\` \u2014 a step checks exactly one condition`
+    );
+  }
+  return true;
+}
 var LAUNCH_PLATFORMS = ["ios", "android", "chromium", "vega"];
 var LAUNCH_MAP_KEYS = ["native", ...LAUNCH_PLATFORMS];
 function parseChromiumLaunch(raw) {
@@ -143019,6 +143394,12 @@ function parseWhenCondition(raw) {
     badEntry({ when: raw }, `when needs exactly one condition key (${conditionKeys})`);
   }
   const b = raw;
+  if (IDLE_CONDITION in b) {
+    badEntry(
+      { when: raw },
+      "when has no idle form \u2014 stillness is a wait, and a guard asks what is on the screen now. Put `await: { idle: true }` before the block instead"
+    );
+  }
   const present = [...WAIT_CONDITIONS, "platform"].filter((c) => c in b);
   if (present.length !== 1) {
     badEntry({ when: raw }, `when needs exactly one condition key (${conditionKeys})`);
@@ -143128,6 +143509,9 @@ function fromYamlStep(raw, whenDepth = 0) {
   }
   const kinds = STEP_DIRECTIVE_KEYS.filter((k) => k in entry);
   if (kinds.length === 0) {
+    if (IDLE_CONDITION in entry) {
+      badEntry(raw, `idle is a condition, not a step kind \u2014 write it as \`await: { idle: true }\``);
+    }
     const hint = Object.keys(entry).map((k) => closestKey(k, STEP_DIRECTIVE_KEYS)).find((h) => h !== null);
     badEntry(raw, `unrecognized step kind${hint ? ` (did you mean \`${hint}\`?)` : ""}`);
   }
@@ -143175,10 +143559,18 @@ function fromYamlStep(raw, whenDepth = 0) {
     return step;
   }
   if ("await" in raw) {
-    return { kind: "await", ...parseWaitFields(raw.await, "await") };
+    const body = raw.await;
+    if (isIdleCondition(body, "await")) {
+      return parseIdleFields(body, "await");
+    }
+    return { kind: "await", ...parseWaitFields(body, "await") };
   }
   if ("assert" in raw) {
-    return { kind: "assert", ...parseWaitFields(raw.assert, "assert") };
+    const body = raw.assert;
+    if (isIdleCondition(body, "assert")) {
+      return parseIdleFields(body, "assert");
+    }
+    return { kind: "assert", ...parseWaitFields(body, "assert") };
   }
   if ("wait" in raw) {
     const ms = Number(raw.wait);
@@ -143709,6 +144101,7 @@ function stepRequiresDevice(registry2, step) {
     case "type":
     case "await":
     case "assert":
+    case "idle":
     case "scroll-to":
     case "pinch":
     case "rotate":
@@ -144563,6 +144956,8 @@ function summarizeSteps(flow) {
         return `${n}. rotate: by ${step.by}\xB0${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
       case "snapshot":
         return `${n}. snapshot: ${step.name}`;
+      case "idle":
+        return `${n}. await: screen idle`;
       case "tool":
       default:
         return `${n}. tool: ${step.name} ${renderToolArgs(step.args)}`;
@@ -144572,7 +144967,7 @@ function summarizeSteps(flow) {
 
 // ../tool-server/src/tools/flows/flow-run.ts
 init_zod();
-var fs48 = __toESM(require("node:fs/promises"));
+var fs49 = __toESM(require("node:fs/promises"));
 var path35 = __toESM(require("node:path"));
 init_src();
 
@@ -144644,6 +145039,122 @@ function nestedOrchestratorOutcome(tool, result) {
   return void 0;
 }
 
+// ../tool-server/src/tools/flows/flow-pixels.ts
+var fs46 = __toESM(require("node:fs/promises"));
+var import_pngjs2 = __toESM(require_png());
+init_adb();
+var CAPTURE_SCALE = 0.25;
+var PIXEL_THRESHOLD = 0.03;
+var MAX_RGB_DISTANCE_SQUARED = 255 * 255 * 3;
+var PIXEL_THRESHOLD_SQUARED = PIXEL_THRESHOLD * PIXEL_THRESHOLD * MAX_RGB_DISTANCE_SQUARED;
+var MOTION_FRACTION = 2e-3;
+var MOTION_MIN_PIXELS = 100;
+var MOTION_MIN_PIXELS_FRAME_SHARE = 0.1;
+var LOCALIZED_MOTION_MIN_PIXELS = 10;
+var STATUS_BAR_MASK_FRACTION = 0.06;
+async function statusBarMaskFraction(device) {
+  if (device.platform === "android") {
+    return await isAndroidTv(device.id) ? 0 : STATUS_BAR_MASK_FRACTION;
+  }
+  if (device.platform === "ios-remote") return STATUS_BAR_MASK_FRACTION;
+  if (device.platform !== "ios") return 0;
+  return await isTvOsSimulator(device.id) ? 0 : STATUS_BAR_MASK_FRACTION;
+}
+var FIRST_CAPTURE_COMPLETION_MARGIN_MS = 500;
+var FIRST_PIXEL_CAPTURE_TIMEOUT_MS = FIRST_FRAME_WAIT_MS + FIRST_CAPTURE_COMPLETION_MARGIN_MS;
+var PIXEL_CAPTURE_TIMEOUT_MS = 2e3;
+function pixelCaptureTimeoutMs(device, firstCapture) {
+  const warmFromTheStart = device.platform === "chromium" || device.platform === "vega";
+  return firstCapture && !warmFromTheStart ? FIRST_PIXEL_CAPTURE_TIMEOUT_MS : PIXEL_CAPTURE_TIMEOUT_MS;
+}
+async function captureChromiumPng(env) {
+  const ref = chromiumCdpRef(env.device);
+  const api = await env.registry.resolveService(ref.urn, ref.options);
+  const { width, height } = api.getViewport();
+  const { x, y } = await chromiumScrollOffset(api);
+  const shot = await api.cdp.send("Page.captureScreenshot", {
+    format: "png",
+    captureBeyondViewport: false,
+    clip: { x, y, width, height, scale: CAPTURE_SCALE }
+  });
+  if (!shot.data) throw new Error("Page.captureScreenshot returned no data");
+  return Buffer.from(shot.data, "base64");
+}
+async function chromiumScrollOffset(api) {
+  try {
+    const metrics = await api.cdp.send("Page.getLayoutMetrics");
+    const vp = metrics.cssVisualViewport ?? metrics.cssLayoutViewport ?? metrics.layoutViewport;
+    const x = vp?.pageX;
+    const y = vp?.pageY;
+    return {
+      x: typeof x === "number" && Number.isFinite(x) ? x : 0,
+      y: typeof y === "number" && Number.isFinite(y) ? y : 0
+    };
+  } catch {
+    return { x: 0, y: 0 };
+  }
+}
+async function captureFile(env, budgetMs) {
+  if (env.device.platform === "vega") {
+    return captureVegaScreenshotPng({ scale: CAPTURE_SCALE });
+  }
+  if (env.device.platform === "ios" && await isTvOsSimulator(env.device.id)) {
+    return tvScreenshot(env.device.id, CAPTURE_SCALE, captureAbortSignal(env, budgetMs));
+  }
+  const ref = simulatorServerRef(env.device);
+  const api = await env.registry.resolveService(ref.urn, ref.options);
+  const { path: path40 } = await httpScreenshot(api, void 0, void 0, CAPTURE_SCALE);
+  return path40;
+}
+async function capturePng(env, budgetMs) {
+  if (env.device.platform === "chromium") return captureChromiumPng(env);
+  const file2 = await captureFile(env, budgetMs);
+  try {
+    return await fs46.readFile(file2);
+  } finally {
+    await fs46.rm(file2, { force: true }).catch(() => {
+    });
+  }
+}
+async function capturePixels(env, budgetMs) {
+  try {
+    const png = import_pngjs2.PNG.sync.read(await capturePng(env, budgetMs));
+    return { width: png.width, height: png.height, data: png.data };
+  } catch {
+    return void 0;
+  }
+}
+async function capturePixelsWithin(env, deadline, firstCapture) {
+  const budget = Math.min(deadline - Date.now(), pixelCaptureTimeoutMs(env.device, firstCapture));
+  if (budget <= 0) return void 0;
+  const result = await settleWithin(capturePixels(env, budget), budget, env.signal);
+  return result.type === "value" ? result.value : void 0;
+}
+function captureAbortSignal(env, budgetMs) {
+  const bound = AbortSignal.timeout(budgetMs);
+  return env.signal ? AbortSignal.any([env.signal, bound]) : bound;
+}
+function comparePixels(a, b, maskTopFraction = 0) {
+  if (a.width !== b.width || a.height !== b.height) return "moving";
+  const maskedRows = Math.min(a.height, Math.floor(a.height * maskTopFraction));
+  const total = a.width * (a.height - maskedRows);
+  if (total <= 0) return "still";
+  const limit = Math.min(a.data.length, b.data.length);
+  let changed = 0;
+  for (let o = maskedRows * a.width * 4; o + 2 < limit; o += 4) {
+    const dr = a.data[o] - b.data[o];
+    const dg = a.data[o + 1] - b.data[o + 1];
+    const db = a.data[o + 2] - b.data[o + 2];
+    if (dr * dr + dg * dg + db * db > PIXEL_THRESHOLD_SQUARED) changed++;
+  }
+  const motionThreshold = Math.max(
+    total * MOTION_FRACTION,
+    Math.min(MOTION_MIN_PIXELS, total * MOTION_MIN_PIXELS_FRAME_SHARE)
+  );
+  if (changed > motionThreshold) return "moving";
+  return changed >= LOCALIZED_MOTION_MIN_PIXELS ? "localized" : "still";
+}
+
 // ../tool-server/src/tools/flows/flow-actions.ts
 var ABORTED_OUTCOME = {
   ok: false,
@@ -144889,6 +145400,8 @@ async function runDirective(env, step) {
       return waitForCondition(env, step, step.timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
     case "assert":
       return waitForCondition(env, step, DEFAULT_ASSERT_TIMEOUT_MS);
+    case "idle":
+      return waitForIdle(env, step);
     case "scroll-to": {
       const r = await scrollToVisible(env, step.target, step.direction, step.within);
       if (r.aborted) return ABORTED_OUTCOME;
@@ -145131,6 +145644,215 @@ async function waitForCondition(env, step, timeoutMs) {
     reason: assertReason(step.condition, step.selector, step.expectedText, step.textMatch, lastMatches) + blipNote
   };
 }
+var MIN_STILL_INTERVALS = IDLE_MIN_STILL_INTERVALS;
+var MIN_ROUND_BUDGET_MS = IDLE_POLL_MS;
+var LOCALIZED_MOTION_WARNING = `the screen settled, but a small part of it was still changing while it did \u2014 a spinner, a caret, a progress dot. If it is a loading spinner then the screen had not finished loading, and stillness cannot tell those apart: look at what is moving, and gate the next action on the element the loading produces rather than on this settle.`;
+var HUNG_TREE_READ_MS = 2e3;
+var IDLE_TOLERATED_DARK_READS = 1;
+function isBlindTreeRead(data) {
+  return data.tree.children.length === 0 && Boolean(data.hint || data.should_restart);
+}
+async function waitForIdle(env, step) {
+  const timeoutMs = step.timeout ?? IDLE_DEFAULT_TIMEOUT_MS;
+  const stableFor = step.stableFor ?? IDLE_DEFAULT_STABLE_FOR_MS;
+  const maskTopFraction = await statusBarMaskFraction(env.device);
+  const deadline = Date.now() + timeoutMs;
+  let treeSignature2;
+  let treeSince = 0;
+  let treeStillIntervals = 0;
+  let treeSettledAtLastRead = false;
+  let previousFrame;
+  let bothSince = 0;
+  let stillIntervals = 0;
+  let heldForMs = 0;
+  let localizedMotionDuringHold = false;
+  let readsSucceeded = 0;
+  let contentReads = 0;
+  let lastRead;
+  let treeErrorMessage;
+  let treeReadBlind = false;
+  let blindHint;
+  let darkReads = 0;
+  let treeReadHung = false;
+  let slowestAnsweredReadMs = 0;
+  let sawContent = false;
+  let pixelsEverMoved = false;
+  let comparedAPair = false;
+  let firstCapture = true;
+  for (; ; ) {
+    if (env.signal?.aborted) return ABORTED_OUTCOME;
+    const roundBudget = Math.max(1, deadline - Date.now());
+    const roundStartedAt = Date.now();
+    let answeredReadMs;
+    const [read, frame] = await Promise.all([
+      settleWithin(fetchFlowTree(env.registry, env.device), roundBudget, env.signal).then((r) => {
+        answeredReadMs = Date.now() - roundStartedAt;
+        return r;
+      }),
+      capturePixelsWithin(env, deadline, firstCapture)
+    ]);
+    firstCapture = false;
+    if (env.signal?.aborted || read.type === "aborted") return ABORTED_OUTCOME;
+    if (read.type !== "timeout" && answeredReadMs !== void 0) {
+      slowestAnsweredReadMs = Math.max(slowestAnsweredReadMs, answeredReadMs);
+    }
+    if (read.type === "timeout") {
+      lastRead = "timeout";
+      darkReads += 1;
+      if (roundBudget >= HUNG_TREE_READ_MS && roundBudget > slowestAnsweredReadMs + HUNG_TREE_READ_MS) {
+        treeReadHung = true;
+      }
+    } else if (read.type === "value" && isBlindTreeRead(read.value)) {
+      lastRead = "blind";
+      darkReads += 1;
+      treeReadBlind = true;
+      blindHint = read.value.hint;
+    } else if (read.type === "error") {
+      lastRead = "error";
+      darkReads += 1;
+      treeErrorMessage = read.error;
+      treeSignature2 = void 0;
+      previousFrame = void 0;
+      treeSince = 0;
+      treeStillIntervals = 0;
+      treeSettledAtLastRead = false;
+      bothSince = 0;
+      stillIntervals = 0;
+    } else {
+      lastRead = "value";
+      readsSucceeded += 1;
+      darkReads = 0;
+      treeErrorMessage = void 0;
+      treeReadBlind = false;
+      blindHint = void 0;
+      treeReadHung = false;
+      const tree = read.value.tree;
+      if (tree.children.length === 0) {
+        treeSignature2 = void 0;
+        previousFrame = void 0;
+        treeSince = 0;
+        treeStillIntervals = 0;
+        treeSettledAtLastRead = false;
+        bothSince = 0;
+        stillIntervals = 0;
+      } else {
+        sawContent = true;
+        contentReads += 1;
+        const signature = treeFingerprint(tree);
+        const now = Date.now();
+        const treeHeld = signature === treeSignature2;
+        treeSignature2 = signature;
+        if (!treeHeld) {
+          treeSince = now;
+          treeStillIntervals = 0;
+        } else {
+          treeStillIntervals += 1;
+        }
+        treeSettledAtLastRead = treeStillIntervals >= MIN_STILL_INTERVALS && now - treeSince >= stableFor;
+        let pixelsHeld;
+        let localizedThisInterval = false;
+        if (frame !== void 0) {
+          if (previousFrame !== void 0) {
+            comparedAPair = true;
+            const change = comparePixels(previousFrame, frame, maskTopFraction);
+            if (change === "moving") {
+              pixelsEverMoved = true;
+              pixelsHeld = false;
+            } else {
+              pixelsHeld = true;
+              localizedThisInterval = change === "localized";
+            }
+          }
+          previousFrame = frame;
+        }
+        if (!treeHeld || pixelsHeld === false) {
+          bothSince = now;
+          stillIntervals = 0;
+          heldForMs = 0;
+          localizedMotionDuringHold = false;
+        } else if (pixelsHeld === true) {
+          stillIntervals += 1;
+          heldForMs = now - bothSince;
+          if (localizedThisInterval) localizedMotionDuringHold = true;
+          if (stillIntervals >= MIN_STILL_INTERVALS && heldForMs >= stableFor) {
+            return localizedMotionDuringHold ? { ok: true, warning: LOCALIZED_MOTION_WARNING } : { ok: true };
+          }
+        }
+      }
+    }
+    if (env.signal?.aborted) return ABORTED_OUTCOME;
+    const left = deadline - Date.now();
+    if (left < MIN_ROUND_BUDGET_MS) break;
+    if (!await sleepOrAbort(Math.min(IDLE_POLL_MS, left), env.signal)) return ABORTED_OUTCOME;
+  }
+  const unreadable = (underlying) => ({
+    ok: false,
+    indeterminate: true,
+    // The underlying reader reports an instrumentation failure, whose remedy
+    // (relaunch the app) is the wrong repair for the commonest cause of it
+    // here: the app is simply not in the foreground, which reads exactly the
+    // same from the tree source. Name that first so the author checks it
+    // before relaunching anything.
+    reason: `could not read the UI tree while waiting for the screen to settle \u2014 check the app is still in the foreground (a backgrounded app reads the same as an uninstrumented one). Underlying error: ${underlying}`
+  });
+  const degraded = () => ({
+    ok: false,
+    indeterminate: true,
+    reason: `the UI tree read back empty and degraded while waiting for the screen to settle, so the screen was never observed \u2014 this is the reader reporting it could not see the app, not the app rendering nothing` + (blindHint === void 0 ? "" : `. ${blindHint}`)
+  });
+  if (readsSucceeded === 0) {
+    if (treeErrorMessage !== void 0) return unreadable(treeErrorMessage);
+    if (treeReadBlind) return degraded();
+    return {
+      ok: false,
+      indeterminate: true,
+      reason: `the tree source never answered within the step's ${timeoutMs}ms \u2014 raise this step's \`timeout:\` if it is merely slow (a tree read on a busy screen can take seconds), or repair it if it has stopped answering altogether`
+    };
+  }
+  if (treeErrorMessage !== void 0 && darkReads > IDLE_TOLERATED_DARK_READS) {
+    return unreadable(treeErrorMessage);
+  }
+  if (treeReadBlind && darkReads > IDLE_TOLERATED_DARK_READS) {
+    return degraded();
+  }
+  if (lastRead === "timeout" && treeReadHung) {
+    return {
+      ok: false,
+      indeterminate: true,
+      reason: `the UI tree source answered and then stopped: a read given at least ${HUNG_TREE_READ_MS}ms never came back, so the screen could not be observed for the rest of the wait \u2014 check the app is still in the foreground and responding (a wedged app reads the same as a backgrounded one)`
+    };
+  }
+  const blipNote = treeErrorMessage !== void 0 ? ` (the last read that came back failed: ${treeErrorMessage})` : "";
+  if (!sawContent) {
+    return {
+      ok: true,
+      warning: `the UI tree stayed empty for ${timeoutMs}ms \u2014 the screen never rendered content, so there was nothing to settle. If the screen is meant to render accessible content, this is where it did not; if it is a canvas or a video surface, it has none to read. Gate the next action on an element check either way.` + blipNote
+    };
+  }
+  if (contentReads <= MIN_STILL_INTERVALS) {
+    return {
+      ok: true,
+      warning: `the screen came back with content on ${contentReads} read${contentReads === 1 ? "" : "s"} in ${timeoutMs}ms, and a settle takes ${MIN_STILL_INTERVALS + 1} of them spanning ${MIN_STILL_INTERVALS} ${IDLE_POLL_MS}ms polls \u2014 so this step ended without ever being able to tell whether the screen was moving. Raise its \`timeout:\`, and gate the next action on a stable element rather than on stillness.` + blipNote
+    };
+  }
+  if (treeSettledAtLastRead && !pixelsEverMoved && !comparedAPair) {
+    return {
+      ok: true,
+      warning: `settled on the UI tree alone \u2014 this screen could not be screenshotted on enough polls to compare a pair of them, so animation that moves pixels without moving nodes (a push, a fade, a dismissing modal) was not waited out. Follow this with the element check the next step actually needs.`
+    };
+  }
+  if (stillIntervals > 0) {
+    const shortOf = stillIntervals < MIN_STILL_INTERVALS ? `a settle takes ${MIN_STILL_INTERVALS} consecutive ones \u2014 a single agreeing interval can be two samples either side of an animation's turning point` : `the hold asks for ${stableFor}ms of it`;
+    return {
+      ok: true,
+      warning: `the screen was still for the last ${heldForMs}ms of the ${timeoutMs}ms wait, over ${stillIntervals} ${IDLE_POLL_MS}ms interval${stillIntervals === 1 ? "" : "s"} \u2014 but ${shortOf}, so the wait ran out before the settle could be confirmed rather than because the screen never stopped. Raise this step's \`timeout:\`, and gate the next action on a stable element rather than on stillness.` + blipNote
+    };
+  }
+  return {
+    ok: true,
+    warning: `the screen never held still for ${MIN_STILL_INTERVALS} consecutive ${IDLE_POLL_MS}ms intervals${stableFor > 0 ? ` spanning ${stableFor}ms` : ""} within ${timeoutMs}ms, and was moving again on the last one, so this step went ahead without waiting it out. Either something on it never stops (a video, a looping animation, a carousel, live-updating text) or the screen never finished loading. Look at what is moving, and make sure the next action is gated on a stable element rather than on stillness.` + blipNote
+  };
+}
 function assertReason(condition, selector, expectedText, textMatch, matches2) {
   const sel = describeSelector(selector);
   switch (condition) {
@@ -145156,15 +145878,15 @@ function assertReason(condition, selector, expectedText, textMatch, matches2) {
 
 // ../tool-server/src/tools/flows/flow-visual.ts
 var import_node_crypto8 = require("node:crypto");
-var fs47 = __toESM(require("node:fs/promises"));
+var fs48 = __toESM(require("node:fs/promises"));
 var os12 = __toESM(require("node:os"));
 var path34 = __toESM(require("node:path"));
-var import_pngjs3 = __toESM(require_png());
+var import_pngjs4 = __toESM(require_png());
 
 // ../tool-server/src/tools/screenshot-diff/screenshot-diff.ts
 var import_promises11 = __toESM(require("fs/promises"));
 var import_path9 = __toESM(require("path"));
-var import_pngjs2 = __toESM(require_png());
+var import_pngjs3 = __toESM(require_png());
 
 // ../tool-server/src/tools/screenshot-diff/screenshot-diff-ocr.ts
 var import_child_process8 = require("child_process");
@@ -146709,7 +147431,7 @@ function formatPercentage(value) {
 }
 
 // ../tool-server/src/tools/screenshot-diff/screenshot-diff.ts
-var MAX_RGB_DISTANCE_SQUARED = 255 * 255 * 3;
+var MAX_RGB_DISTANCE_SQUARED2 = 255 * 255 * 3;
 var DEFAULT_THRESHOLD = 0.1;
 var DEFAULT_IGNORE_TOP_NORMALIZED_Y = 0.06;
 var DEFAULT_REGION_MERGE_DISTANCE = 8;
@@ -146795,7 +147517,7 @@ async function diffPngFiles(options) {
 }
 function resolveDiffSettings(topMask) {
   return {
-    thresholdSquared: DEFAULT_THRESHOLD * DEFAULT_THRESHOLD * MAX_RGB_DISTANCE_SQUARED,
+    thresholdSquared: DEFAULT_THRESHOLD * DEFAULT_THRESHOLD * MAX_RGB_DISTANCE_SQUARED2,
     ignoreTopNormalizedY: topMask === "none" ? 0 : DEFAULT_IGNORE_TOP_NORMALIZED_Y,
     joinGapPixels: DEFAULT_REGION_MERGE_DISTANCE,
     contextDiffScale: DEFAULT_CONTEXT_DIFF_SCALE
@@ -146900,7 +147622,7 @@ async function writeDiffArtifacts(params) {
 }
 async function decodePngFile(filePath) {
   const buffer = await import_promises11.default.readFile(filePath);
-  const png = import_pngjs2.PNG.sync.read(buffer);
+  const png = import_pngjs3.PNG.sync.read(buffer);
   return {
     width: png.width,
     height: png.height,
@@ -146919,7 +147641,7 @@ async function analyzeScreenshotTextChangesSafely(options) {
   }
 }
 function buildContextDiff(params) {
-  const output = new import_pngjs2.PNG({ width: params.current.width, height: params.current.height });
+  const output = new import_pngjs3.PNG({ width: params.current.width, height: params.current.height });
   for (let pixelIndex = 0; pixelIndex < params.mask.length; pixelIndex++) {
     const offset = pixelIndex * 4;
     if (params.mask[pixelIndex]) {
@@ -146944,7 +147666,7 @@ function luminanceFromOffset(data, offset) {
 }
 async function writePngFile(filePath, png) {
   await import_promises11.default.mkdir(import_path9.default.dirname(filePath), { recursive: true });
-  await import_promises11.default.writeFile(filePath, import_pngjs2.PNG.sync.write(png));
+  await import_promises11.default.writeFile(filePath, import_pngjs3.PNG.sync.write(png));
 }
 function downscalePng(source, scale) {
   const resized = resizeDecodedPng(
@@ -146952,7 +147674,7 @@ function downscalePng(source, scale) {
     source.width * scale,
     source.height * scale
   );
-  const target = new import_pngjs2.PNG({ width: resized.width, height: resized.height });
+  const target = new import_pngjs3.PNG({ width: resized.width, height: resized.height });
   resized.data.copy(target.data);
   return target;
 }
@@ -147217,7 +147939,7 @@ function roundToOne(value) {
 // ../tool-server/src/tools/flows/flow-visual.ts
 var DEFAULT_MAX_MISMATCH = 0.5;
 async function pngDimensions(file2) {
-  const fh = await fs47.open(file2, "r");
+  const fh = await fs48.open(file2, "r");
   try {
     const buf = Buffer.alloc(24);
     await fh.read(buf, 0, 24, 0);
@@ -147241,18 +147963,18 @@ function baselineDir(flowsDir, flowName) {
 async function cleanupDiffDir(dir, keep) {
   try {
     if (!keep) {
-      await fs47.rm(dir, { recursive: true, force: true });
+      await fs48.rm(dir, { recursive: true, force: true });
       return;
     }
-    for (const entry of await fs47.readdir(dir)) {
+    for (const entry of await fs48.readdir(dir)) {
       const entryPath = path34.join(dir, entry);
-      if (entryPath !== keep) await fs47.rm(entryPath, { recursive: true, force: true });
+      if (entryPath !== keep) await fs48.rm(entryPath, { recursive: true, force: true });
     }
   } catch {
   }
 }
 async function cropPngFile(src, dest, frame) {
-  const png = import_pngjs3.PNG.sync.read(await fs47.readFile(src));
+  const png = import_pngjs4.PNG.sync.read(await fs48.readFile(src));
   const left = Math.max(0, Math.round(frame.x * png.width));
   const top = Math.max(0, Math.round(frame.y * png.height));
   const right = Math.min(png.width, Math.round((frame.x + frame.width) * png.width));
@@ -147260,9 +147982,9 @@ async function cropPngFile(src, dest, frame) {
   const w = right - left;
   const h = bottom - top;
   if (w < 1 || h < 1) return null;
-  const out = new import_pngjs3.PNG({ width: w, height: h });
-  import_pngjs3.PNG.bitblt(png, out, left, top, w, h, 0, 0);
-  await fs47.writeFile(dest, import_pngjs3.PNG.sync.write(out));
+  const out = new import_pngjs4.PNG({ width: w, height: h });
+  import_pngjs4.PNG.bitblt(png, out, left, top, w, h, 0, 0);
+  await fs48.writeFile(dest, import_pngjs4.PNG.sync.write(out));
   return { w, h };
 }
 async function runSnapshot(env, opts) {
@@ -147319,7 +148041,7 @@ async function runSnapshot(env, opts) {
   };
   try {
     if (cropFrame !== void 0) {
-      cropDir = await fs47.mkdtemp(path34.join(os12.tmpdir(), "argent-flow-crop-"));
+      cropDir = await fs48.mkdtemp(path34.join(os12.tmpdir(), "argent-flow-crop-"));
       const croppedPath = path34.join(cropDir, key2);
       const cropped = await cropPngFile(shot.image.hostPath, croppedPath, cropFrame);
       if (cropped === null) {
@@ -147333,10 +148055,10 @@ async function runSnapshot(env, opts) {
       }
       currentPath = croppedPath;
     }
-    const exists2 = await fs47.access(baselinePath).then(() => true).catch(() => false);
+    const exists2 = await fs48.access(baselinePath).then(() => true).catch(() => false);
     if (opts.updateBaselines) {
-      await fs47.mkdir(dir, { recursive: true });
-      await fs47.copyFile(currentPath, baselinePath);
+      await fs48.mkdir(dir, { recursive: true });
+      await fs48.copyFile(currentPath, baselinePath);
       const baseline = await store.register(baselinePath, { mimeType: "image/png" });
       return {
         status: "pass",
@@ -147353,7 +148075,7 @@ async function runSnapshot(env, opts) {
         artifacts: { current: await currentArtifact() }
       };
     }
-    const outputDir = await fs47.mkdtemp(path34.join(os12.tmpdir(), "argent-flow-diff-"));
+    const outputDir = await fs48.mkdtemp(path34.join(os12.tmpdir(), "argent-flow-diff-"));
     let keepInOutputDir;
     try {
       const result = await diffPngFiles({
@@ -147819,7 +148541,13 @@ reads "inside card inside list", each container's frame inside the next);
 (\`pinch: { on?, scale }\` \u2014 scale > 1 in, < 1 out; screen center when \`on\` is omitted); \`rotate\` is the
 two-finger rotation gesture (\`rotate: { on?, by }\` \u2014 degrees, + clockwise, within \xB13000\xB0; screen center
 when \`on\` is omitted; distinct from the \`rotate\` tool, which changes device orientation); \`await\` waits
-for a UI condition; \`wait\` pauses for a fixed number of milliseconds; \`assert\` checks one now; \`snapshot\`
+for a UI condition, and additionally takes the one condition that has no selector: \`idle: true\` waits
+until the screen has content and stops moving in BOTH the UI tree and the rendered pixels (it never
+fails a run \u2014 a screen that never settles passes carrying a \`warning\`, which is what makes it safe to
+persist; the one outcome that does stop the run is an \`error\` for a tree source that could not be read
+at all \u2014 a broken window rather than a verdict about the app, which leaves the run not-ok and skips
+every later step; it says nothing about WHICH screen settled \u2014 a dropped tap leaves the source screen
+perfectly idle \u2014 so pair it with the element check that names the destination); \`wait\` pauses for a fixed number of milliseconds; \`assert\` checks one now; \`snapshot\`
 diffs a screenshot \u2014 or, with \`cropOn: <selector>\`, one element's cropped region \u2014 against a stored
 baseline (a missing baseline fails the step \u2014 set updateBaselines to adopt the current screen; a
 cropped element whose size drifted fails on dimensions); \`echo\` annotates; \`run\` executes another flow
@@ -147863,7 +148591,7 @@ returns a notice with the prerequisite instead of running.`,
       );
       const canonicalPath = await canonicalFlowPath2(filePath);
       const flowsDir = path35.dirname(canonicalPath);
-      const flow = parseFlow(await fs48.readFile(canonicalPath, "utf8"));
+      const flow = parseFlow(await fs49.readFile(canonicalPath, "utf8"));
       if (viaUpload) assertUploadSelfContained(flow);
       const rootEntry = { canonical: canonicalPath, display: flowName };
       if (flow.executionPrerequisite && !pinnedToChromium(params.device)) {
@@ -148007,7 +148735,7 @@ async function scanLeadingLaunch(flow, stack) {
       const supplied = path35.posix.basename(step.flow);
       const spelling = await classifyOnDiskSpelling(path35.dirname(spelled), supplied);
       if (spelling.state === "case_folded") return null;
-      nested = parseFlow(await fs48.readFile(canonical, "utf8"));
+      nested = parseFlow(await fs49.readFile(canonical, "utf8"));
     } catch {
       return null;
     }
@@ -148034,7 +148762,7 @@ function launchTargetPlatform(launch, platform) {
 async function resolveAppPath(specPath, flowDir) {
   const lexical = path35.resolve(flowDir, specPath);
   try {
-    return await fs48.realpath(lexical);
+    return await fs49.realpath(lexical);
   } catch {
     return lexical;
   }
@@ -148142,6 +148870,8 @@ function stepTarget(step) {
     case "await":
     case "assert":
       return conditionLabel(step, selectorLabel2);
+    case "idle":
+      return void 0;
     case "when":
       return step.condition.kind === "platform" ? `platform ${step.condition.platform}` : conditionLabel(step.condition, selectorLabel2);
     case "scroll-to": {
@@ -148320,10 +149050,10 @@ async function execWhenStep(state3, step, scope) {
 }
 async function canonicalFlowPath2(p) {
   try {
-    return await fs48.realpath(p);
+    return await fs49.realpath(p);
   } catch {
     try {
-      return path35.join(await fs48.realpath(path35.dirname(p)), path35.basename(p));
+      return path35.join(await fs49.realpath(path35.dirname(p)), path35.basename(p));
     } catch {
       return p;
     }
@@ -148371,7 +149101,7 @@ async function execRunStep(state3, step, scope) {
   }
   let fragment;
   try {
-    fragment = parseFlow(await fs48.readFile(canonical, "utf8"));
+    fragment = parseFlow(await fs49.readFile(canonical, "utf8"));
   } catch (err) {
     return fail(`could not load fragment "${target}": ${errMsg2(err)}`);
   }
@@ -148411,13 +149141,22 @@ async function execLeafStep(state3, step, index, scope) {
     case "type":
     case "await":
     case "assert":
+    case "idle":
     case "scroll-to":
     case "pinch":
     case "rotate": {
       try {
         const r = await runDirective(deviceEnv(state3), step);
         if (r.aborted) return { ...base, status: "skip", reason: r.reason };
-        return { ...base, status: r.ok ? "pass" : "fail", reason: r.reason };
+        if (!r.ok && r.indeterminate && step.kind === "idle") {
+          return { ...base, status: "error", reason: r.reason };
+        }
+        return {
+          ...base,
+          status: r.ok ? "pass" : "fail",
+          reason: r.reason,
+          ...r.warning !== void 0 ? { warning: r.warning } : {}
+        };
       } catch (err) {
         return { ...base, status: "error", reason: errMsg2(err) };
       }
@@ -148486,6 +149225,17 @@ async function execLeafStep(state3, step, index, scope) {
             args
           };
         }
+        if (isDebuggerNotConnectedResult(step.name, result)) {
+          return {
+            ...base,
+            status: "fail",
+            tool: step.name,
+            reason: `debugger not connected (${result.reason}): ${result.detail} \u2014 ${result.guidance}`,
+            result,
+            outputHint,
+            args
+          };
+        }
         return { ...base, status: "pass", tool: step.name, result, outputHint, args };
       } catch (err) {
         return { ...base, status: "error", tool: step.name, reason: errMsg2(err) };
@@ -148618,7 +149368,7 @@ async function resolveFlowSource(params, fileInput, flowPathInput) {
 
 // ../tool-server/src/tools/flows/flow-read-prerequisite.ts
 init_zod();
-var fs49 = __toESM(require("node:fs/promises"));
+var fs50 = __toESM(require("node:fs/promises"));
 init_src();
 var zodSchema66 = external_exports.object({
   name: external_exports.string().optional().describe(
@@ -148688,7 +149438,7 @@ Fails if the flow file does not exist.`,
       ctx?.fileInputs?.flow_file,
       ctx?.fileInputs?.flow_path
     );
-    const flow = parseFlow(await fs49.readFile(filePath, "utf8"));
+    const flow = parseFlow(await fs50.readFile(filePath, "utf8"));
     return {
       flow: flowName,
       executionPrerequisite: flow.executionPrerequisite
@@ -149036,13 +149786,13 @@ Fails if the workspacePath is not an absolute path or the directory cannot be ac
 
 // ../tool-server/src/tools/system/update-argent.ts
 var import_node_child_process29 = require("node:child_process");
-var fs50 = __toESM(require("node:fs"));
+var fs51 = __toESM(require("node:fs"));
 var path36 = __toESM(require("node:path"));
 init_zod();
 function resolveCliEntry() {
   try {
     const entry = path36.join(__dirname, "cli.js");
-    return fs50.existsSync(entry) ? entry : null;
+    return fs51.existsSync(entry) ? entry : null;
   } catch {
     return null;
   }
@@ -149056,14 +149806,14 @@ function classifyRunningInstall() {
   }
   let runningRoot;
   try {
-    runningRoot = fs50.realpathSync(path36.dirname(__dirname));
+    runningRoot = fs51.realpathSync(path36.dirname(__dirname));
   } catch {
     return { kind: "global", projectRoot: null };
   }
   let dir = process.cwd();
   while (true) {
     try {
-      const nmReal = fs50.realpathSync(path36.join(dir, "node_modules"));
+      const nmReal = fs51.realpathSync(path36.join(dir, "node_modules"));
       if (runningRoot === nmReal || runningRoot.startsWith(nmReal + path36.sep)) {
         return { kind: "local", projectRoot: dir };
       }
@@ -149078,14 +149828,14 @@ function classifyRunningInstall() {
 function findDeclaringProjectRoot(startDir) {
   let dir;
   try {
-    dir = fs50.realpathSync(startDir);
+    dir = fs51.realpathSync(startDir);
   } catch {
     return null;
   }
   while (true) {
-    if (fs50.existsSync(path36.join(dir, ".argent", "install.json"))) return dir;
+    if (fs51.existsSync(path36.join(dir, ".argent", "install.json"))) return dir;
     try {
-      const manifest = JSON.parse(fs50.readFileSync(path36.join(dir, "package.json"), "utf8"));
+      const manifest = JSON.parse(fs51.readFileSync(path36.join(dir, "package.json"), "utf8"));
       if (manifest.devDependencies?.[PACKAGE_NAME2] || manifest.dependencies?.[PACKAGE_NAME2] || manifest.optionalDependencies?.[PACKAGE_NAME2]) {
         return dir;
       }
@@ -149124,7 +149874,7 @@ var updateArgentTool = {
     let projectRoot = null;
     let effectiveTarget = resolved;
     if (resolved === "local" || resolved === "both") {
-      const recordedRoot = running.projectRoot && fs50.existsSync(running.projectRoot) ? running.projectRoot : null;
+      const recordedRoot = running.projectRoot && fs51.existsSync(running.projectRoot) ? running.projectRoot : null;
       projectRoot = recordedRoot ?? (running.kind === "local" ? findDeclaringProjectRoot(process.cwd()) : null);
       if (!projectRoot) {
         if (resolved === "local") {
@@ -149166,7 +149916,7 @@ var updateArgentTool = {
       if (targetsOnlyRunningInstall && installableVersion) {
         updateArgs.push("--version", installableVersion);
       }
-      const spawnRoot = projectRoot ?? (running.projectRoot && fs50.existsSync(running.projectRoot) ? running.projectRoot : null);
+      const spawnRoot = projectRoot ?? (running.projectRoot && fs51.existsSync(running.projectRoot) ? running.projectRoot : null);
       if (spawnRoot) updateArgs.push("--project-root", spawnRoot);
       const cmd = cliEntry ? process.execPath : "argent";
       const args = cliEntry ? [cliEntry, ...updateArgs] : updateArgs;
@@ -150011,12 +150761,12 @@ function createRegistry() {
   registry2.registerTool(createTvRemoteTool(registry2));
   registry2.registerTool(createRunSequenceTool(registry2));
   registry2.registerTool(debuggerConnectTool);
-  registry2.registerTool(debuggerStatusTool);
+  registry2.registerTool(createDebuggerStatusTool(registry2));
   registry2.registerTool(debuggerEvaluateTool);
   registry2.registerTool(debuggerReloadMetroTool);
   registry2.registerTool(debuggerComponentTreeTool);
   registry2.registerTool(debuggerInspectElementTool);
-  registry2.registerTool(debuggerLogRegistryTool);
+  registry2.registerTool(createDebuggerLogRegistryTool(registry2));
   registry2.registerTool(networkLogsTool);
   registry2.registerTool(networkRequestTool);
   registry2.registerTool(createDescribeTool(registry2));
@@ -150086,7 +150836,7 @@ function probeArgentToolServer(host, port, timeoutMs = 500) {
 }
 
 // ../tool-server/src/utils/simulator-watcher.ts
-var fs52 = __toESM(require("node:fs"));
+var fs53 = __toESM(require("node:fs"));
 var import_node_child_process30 = require("node:child_process");
 var import_node_util21 = require("node:util");
 var execFileAsync23 = (0, import_node_util21.promisify)(import_node_child_process30.execFile);
@@ -150113,7 +150863,7 @@ async function getBootedUdidsInSet(deviceSet) {
 async function getBootedUdids() {
   const sets = [
     null,
-    ...configuredAdditionalDeviceSets().filter((p) => fs52.existsSync(p))
+    ...configuredAdditionalDeviceSets().filter((p) => fs53.existsSync(p))
   ];
   const perSet = await Promise.all(sets.map(getBootedUdidsInSet));
   return new Set(perSet.flatMap((s) => [...s]));
@@ -150166,7 +150916,7 @@ function startSimulatorWatcher(registry2) {
 
 // ../tool-server/src/utils/preview-window.ts
 var import_node_child_process31 = require("node:child_process");
-var fs53 = __toESM(require("node:fs"));
+var fs54 = __toESM(require("node:fs"));
 var os14 = __toESM(require("node:os"));
 var path38 = __toESM(require("node:path"));
 function ensureLensAppBundle(electronBin) {
@@ -150183,18 +150933,18 @@ function ensureLensAppBundle(electronBin) {
     );
     const wrapperExec = path38.join(wrapperContents, "MacOS", "Electron");
     try {
-      if (fs53.realpathSync(wrapperExec) === fs53.realpathSync(electronBin)) return wrapperExec;
+      if (fs54.realpathSync(wrapperExec) === fs54.realpathSync(electronBin)) return wrapperExec;
     } catch {
     }
-    fs53.rmSync(path38.dirname(wrapperContents), { recursive: true, force: true });
-    fs53.mkdirSync(path38.join(wrapperContents, "MacOS"), { recursive: true });
-    fs53.symlinkSync(path38.join(realContents, "Frameworks"), path38.join(wrapperContents, "Frameworks"));
-    fs53.symlinkSync(path38.join(realContents, "Resources"), path38.join(wrapperContents, "Resources"));
-    fs53.symlinkSync(electronBin, wrapperExec);
+    fs54.rmSync(path38.dirname(wrapperContents), { recursive: true, force: true });
+    fs54.mkdirSync(path38.join(wrapperContents, "MacOS"), { recursive: true });
+    fs54.symlinkSync(path38.join(realContents, "Frameworks"), path38.join(wrapperContents, "Frameworks"));
+    fs54.symlinkSync(path38.join(realContents, "Resources"), path38.join(wrapperContents, "Resources"));
+    fs54.symlinkSync(electronBin, wrapperExec);
     const pkgInfo = path38.join(realContents, "PkgInfo");
-    if (fs53.existsSync(pkgInfo)) fs53.copyFileSync(pkgInfo, path38.join(wrapperContents, "PkgInfo"));
+    if (fs54.existsSync(pkgInfo)) fs54.copyFileSync(pkgInfo, path38.join(wrapperContents, "PkgInfo"));
     const plist = path38.join(wrapperContents, "Info.plist");
-    fs53.copyFileSync(path38.join(realContents, "Info.plist"), plist);
+    fs54.copyFileSync(path38.join(realContents, "Info.plist"), plist);
     const setPlist = (entry, value) => {
       try {
         (0, import_node_child_process31.execFileSync)("/usr/libexec/PlistBuddy", ["-c", `Set :${entry} ${value}`, plist]);
@@ -150236,7 +150986,7 @@ function createPreviewWindowManager(opts = {}) {
   const resolveMainScript = () => {
     if (opts.mainScript) return opts.mainScript;
     const bundled = path38.join(__dirname, "preview-window", "main.cjs");
-    if (fs53.existsSync(bundled)) return bundled;
+    if (fs54.existsSync(bundled)) return bundled;
     return require.resolve("@argent/preview-window/dist/main.js");
   };
   const isAlive = (c) => c !== null && c.exitCode === null && !c.killed;
@@ -150547,6 +151297,7 @@ function start() {
       track("tool:fail", {
         tool: toolId,
         ...meta3.platform ? { platform: meta3.platform } : {},
+        ...meta3.invalid_params?.length ? { invalid_params: meta3.invalid_params } : {},
         duration_ms: durationMs,
         ...signal,
         ...aiTelemetryFromMeta(meta3)