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

package/dist/tool-server.cjs

@@ -709,15 +709,12 @@ var init_failure_codes = __esm({
       NATIVE_PROFILER_SESSION_TORN_DOWN: "NATIVE_PROFILER_SESSION_TORN_DOWN",
       NATIVE_PROFILER_APP_PROCESS_NOT_FOUND: "NATIVE_PROFILER_APP_PROCESS_NOT_FOUND",
       NATIVE_PROFILER_NO_EXPORTED_TRACE: "NATIVE_PROFILER_NO_EXPORTED_TRACE",
-      // Android perfetto start-failure modes — mirror the iOS xctrace set so a
-      // failed recording start is classified rather than falling through to the
-      // generic tool-execution bucket.
+      // Android perfetto start failures, mirroring the iOS xctrace set above.
       NATIVE_PROFILER_PERFETTO_PROCESS_ERROR: "NATIVE_PROFILER_PERFETTO_PROCESS_ERROR",
       NATIVE_PROFILER_PERFETTO_READY_TIMEOUT: "NATIVE_PROFILER_PERFETTO_READY_TIMEOUT",
       NATIVE_PROFILER_PERFETTO_READY_EXITED: "NATIVE_PROFILER_PERFETTO_READY_EXITED",
-      // screen-recording-start / screen-recording-stop. One capture path for every
-      // platform (simulator-server's frame stream into ffmpeg), so the stages name
-      // the step that failed rather than the device family.
+      // iOS and Android share one capture path (simulator-server frames into
+      // ffmpeg), so these name the failing stage, not the device family.
       SCREEN_RECORDING_FACTORY_OPTIONS_MISSING: "SCREEN_RECORDING_FACTORY_OPTIONS_MISSING",
       SCREEN_RECORDING_WRONG_PLATFORM: "SCREEN_RECORDING_WRONG_PLATFORM",
       SCREEN_RECORDING_ALREADY_ACTIVE: "SCREEN_RECORDING_ALREADY_ACTIVE",
@@ -16086,22 +16083,19 @@ var init_registry = __esm({
     init_zod_to_json_schema();
     import_node_crypto2 = require("node:crypto");
     Registry = class {
-      /** Single map: URN -> ServiceNode (all instances). */
       services = /* @__PURE__ */ new Map();
       blueprints = /* @__PURE__ */ new Map();
       tools = /* @__PURE__ */ new Map();
       /**
-       * Predicate that decides whether a feature-flagged tool is currently enabled.
-       * Injected (rather than importing `@argent/cli` here) so the registry stays
-       * free of a CLI dependency. The default treats every flag as enabled, so
-       * existing `new Registry()` call sites (tests, non-flag deployments) keep
-       * their previous behavior. The tool-server wires the real `isFlagEnabled`.
+       * Injected so the registry needs no dependency on the flag store; the
+       * tool-server wires the real check. The default enables every flag, so a
+       * plain `new Registry()` (tests, non-flag deployments) gates nothing.
        */
       isFlagEnabled;
       /**
-       * Host files produced by tools, registered during `execute` and served by the
-       * `/artifacts/:id` route. Owned here (one per registry/process) so the tool
-       * path and the HTTP route resolve the same instance — no module singleton.
+       * Host files produced by tools, served by the tool-server's `/artifacts/:id`
+       * route. Owned per registry rather than as a module singleton, so the tool
+       * path and the HTTP route see the same store.
        */
       artifacts = new ArtifactStore();
       events = new TypedEventEmitter();
@@ -16122,8 +16116,8 @@ var init_registry = __esm({
         return this.tools.get(id)?.definition;
       }
       /**
-       * Resolve a service by URN. JIT-instantiates from blueprint if not yet created.
-       * Optional options are passed to the blueprint's factory (e.g. token for SimulatorServer).
+       * Resolve a service by URN, JIT-instantiating from its blueprint on first use.
+       * `options` reach the blueprint factory only on that first instantiation.
        */
       resolveService(urn, options) {
         return this._resolve(urn, [], options);
@@ -16240,14 +16234,10 @@ var init_registry = __esm({
         };
       }
       /**
-       * After a tool failed, ask each service it resolved whether the error means
-       * that service's instance is dead (`blueprint.recoverable(error)`). Dispose
-       * every one that says yes so the next `resolveService` re-creates it, and
-       * report whether anything was disposed (i.e. whether a retry is worthwhile).
-       *
-       * Only currently-RUNNING nodes are considered: a service that already
-       * errored/torn down during resolution needs no recovery here, and a URN this
-       * tool never resolved must not be touched.
+       * Dispose every service in `refs` whose blueprint calls `error` recoverable, so
+       * the next `resolveService` re-creates it; returns whether anything was
+       * disposed, i.e. whether retrying the tool is worthwhile. Only RUNNING nodes
+       * qualify — one that already errored or tore down needs no recovery.
        */
       async _recoverFailedServices(refs, error52) {
         let recoveredAny = false;
@@ -16263,10 +16253,7 @@ var init_registry = __esm({
         }
         return recoveredAny;
       }
-      /**
-       * Tear down a single service by URN (and cascade to its dependents).
-       * After disposal the service returns to IDLE and can be re-resolved.
-       */
+      /** Tear down a service and its dependents; it returns to IDLE and can be re-resolved. */
       async disposeService(urn) {
         const node = this.services.get(urn);
         if (!node) throw new ServiceNotFoundError(urn);
@@ -16279,7 +16266,6 @@ var init_registry = __esm({
           }
         }
       }
-      // ── Private: Resolution ──
       _resolve(urn, resolutionPath, options) {
         let node = this.services.get(urn);
         if (!node) {
@@ -69928,16 +69914,12 @@ function androidRoots() {
 function defaultAndroidRoots() {
   const home = (0, import_node_os2.homedir)();
   const roots = [
-    // Android Studio defaults (the big ones — cover the majority of user
-    // installs that arrive without any env-var setup).
     (0, import_node_path3.join)(home, "Library", "Android", "sdk"),
     // macOS Android Studio default
     (0, import_node_path3.join)(home, "Android", "Sdk"),
     // Linux Android Studio default
-    // Common manual install convention. Not picked by any installer but used
-    // often enough in tutorials and Dockerfiles that probing it costs little.
     (0, import_node_path3.join)(home, "android-sdk"),
-    // System-wide locations (Linux package managers, Homebrew on macOS).
+    // manual-install convention; no installer picks it
     "/opt/android-sdk",
     "/usr/lib/android-sdk",
     // Debian/Ubuntu `android-sdk` apt package
@@ -72072,9 +72054,7 @@ var require_min_release_age = __commonJS({
     var PROBE_TIMEOUT_MS = 3e3;
     var OVERRIDE_ENV = "ARGENT_MIN_RELEASE_AGE_DAYS";
     var PM_PROBES = {
-      // npm flattens `min-release-age` to an effective `before` cutoff, and some
-      // npm 11.x builds report `min-release-age=null` even while the policy is
-      // active. Probe `before`, which is what the resolver actually uses.
+      // Probe `before`: that is the effective cutoff npm's resolver applies.
       npm: { command: "npm config get before", parse: config_parse_1.parseBeforeAgeMs },
       pnpm: {
         command: "pnpm config get minimumReleaseAge",
@@ -92085,14 +92065,12 @@ var CONFIG_SCHEMA = [
     description: "Whether anonymous opt-out telemetry is enabled (on by default; environment opt-outs like DO_NOT_TRACK are not reflected here \u2014 `argent telemetry status` shows effective consent).",
     scopes: ["global"],
     parse: asBoolean,
-    // A committed project file must never re-enable telemetry a user disabled
-    // globally, so the more-restrictive (opt-out) value always wins.
     merge: "prioritize-restrictive",
-    // Telemetry is opt-out: with nothing stored, consent.ts treats it as
-    // enabled, and the config surface must report the same instead of "(unset)".
+    // Opt-out: consent.ts reads an unstored value as enabled, so the config
+    // surface must show the same rather than "(unset)".
     default: true,
-    // Read-only under `argent config`: opt-in/out goes through the dedicated
-    // command so the live client is drained/reset, not just the file rewritten.
+    // Opt-in/out goes through the dedicated command so the live client is
+    // drained/reset, not just the file rewritten.
     manageCommand: "argent telemetry"
   },
   {
@@ -92100,8 +92078,6 @@ var CONFIG_SCHEMA = [
     description: "Coding-agent id remembered by `argent lens` to skip the picker.",
     scopes: ["project", "global"],
     parse: asString,
-    // A repo can pin the agent its screenshots should use; falls back to the
-    // user's global remembered choice.
     merge: "prioritize-local",
     example: "claude"
   },
@@ -92110,11 +92086,9 @@ var CONFIG_SCHEMA = [
     description: "Additional CoreSimulator device-set directories whose simulators argent should see alongside the default set. Absolute paths (or ~/\u2026); relative entries resolve against the project root (project scope) or home (global scope).",
     scopes: ["project", "global"],
     parse: asStringArray,
-    // Additive: the scopes extend each other rather than shadow — a repo's
-    // committed device sets are appended to the user's global ones (global
-    // baseline first, project extras after, deduplicated). Note that
-    // `getAdditionalIosDeviceSets` re-implements this union (path resolution
-    // must precede dedup) and guards on the preset staying "union".
+    // Additive rather than shadowing: global baseline first, project extras
+    // after, deduplicated. `getAdditionalIosDeviceSets` re-implements this union
+    // (path resolution must precede dedup) and guards on the preset staying "union".
     merge: "union",
     example: '["~/DeviceSets/ci"]'
   },
@@ -92123,10 +92097,8 @@ var CONFIG_SCHEMA = [
     description: "Directory where finished screen recordings (mp4) are saved on the client host. Absolute, `~`-prefixed, or relative to the project root (home dir when not in a project). Unset \u21D2 `.argent/recordings` under the project root.",
     scopes: ["project", "global"],
     parse: asString,
-    // A repo can pin where its recordings land; falls back to the user's global
-    // preference. Resolution happens on the client (the machine the mp4 is
-    // persisted to), so with a remote `argent link` tool-server it is the
-    // *client's* config that decides.
+    // Resolved on the client (the machine the mp4 is persisted to), so with a
+    // remote `argent link` tool-server it is the *client's* config that decides.
     merge: "prioritize-local",
     example: "~/Movies/argent"
   }
@@ -94853,17 +94825,16 @@ function createExporter(config2) {
       // The exporter bounds a request with `req.setTimeout()`, which Node only
       // arms once the socket is CONNECTED — so a collector whose address drops
       // packets (corporate egress filter, dead host behind a firewall) leaves a
-      // socket stuck in the connecting state that no export deadline can reach,
-      // holding the process open for the OS connect timeout (~75s on macOS)
-      // after shutdown() has already resolved. The agent's socket timeout is
-      // armed when the socket is CREATED, so it also covers connect: it fires,
-      // the request emits 'timeout', and the exporter's handler destroys it.
+      // socket stuck connecting that no export deadline can reach, holding the
+      // process open for the OS connect timeout after shutdown() has resolved.
+      // The agent's socket timeout is armed when the socket is CREATED, so it
+      // covers connect too: it fires, the request emits 'timeout', and the
+      // exporter's handler destroys it.
       //
       // keepAlive is restated because supplying httpAgentOptions at all
-      // replaces the agent the SDK would otherwise build, and its default is
-      // keepAlive: true. Without it the long-lived tool-server pays a fresh
-      // TCP+TLS handshake for every 10s batch — measured as one socket per
-      // request against a loopback collector, versus one socket shared.
+      // replaces the agent the SDK would otherwise build, whose default is
+      // keepAlive: true; without it the long-lived tool-server pays a fresh
+      // TCP+TLS handshake for every batch.
       httpAgentOptions: { timeout: EXPORT_TIMEOUT_MS, keepAlive: true }
     });
   } finally {
@@ -95082,7 +95053,6 @@ var ALLOWED = {
     install_mode: INSTALL_MODE
   },
   "installation:global_install_decision": {
-    // `from_tar` is intentionally absent; the installer skips that dev path.
     decision: oneOf(["install", "cancel", "already_installed"])
   },
   "installation:update_decision": {
@@ -95161,9 +95131,8 @@ var ALLOWED = {
     tool_invocation_id: UUID,
     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.
+    // Emit side sends only names declared in the tool's zod shape, capped at 16
+    // because arrayOf voids the whole array once it is longer.
     invalid_params: arrayOf(matches(/^[a-z][a-z0-9_]{0,63}$/i, 64), 16),
     ...FAILURE_SIGNAL2,
     ...AI_TELEMETRY
@@ -95695,7 +95664,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.22.1-next.2";
+    return "0.22.1-next.4";
   }
   return "0.0.0";
 }
@@ -96097,15 +96066,11 @@ function resolveHostFingerprint() {
     const out = (0, import_node_child_process.execFileSync)(simulatorServerBinaryPath(), ["fingerprint"], {
       encoding: "utf8",
       timeout: FINGERPRINT_TIMEOUT_MS,
-      // Reap with SIGKILL, not the default SIGTERM: a binary that ignores SIGTERM
-      // would otherwise block the (synchronous) event loop past the cap forever.
-      // SIGKILL can't be trapped, so the timeout is a genuine bound here.
+      // SIGKILL, not the default SIGTERM: a binary that ignores SIGTERM would
+      // otherwise block the (synchronous) event loop past the cap forever.
       killSignal: "SIGKILL",
-      // Cap captured stdout (same limit as the async variant): a binary streaming
-      // output is SIGKILL'd at this cap rather than filling Node's 1 MiB default.
       maxBuffer: FINGERPRINT_MAX_BUFFER,
-      // Ignore stderr so a binary that logs diagnostics doesn't pollute the
-      // caller's stderr; stdout (index 1) is captured as the return value.
+      // Ignore stderr so the binary's diagnostics don't pollute the caller's.
       stdio: ["ignore", "pipe", "ignore"]
     }).trim();
     return out.length > 0 ? out : null;
@@ -96754,11 +96719,10 @@ function describeVegaFailure(args, err, kindOverride) {
     error_code: FAILURE_CODES.VEGA_CLI_COMMAND_FAILED,
     failure_stage: "vega_cli_command",
     failure_area: "tool_server",
-    // A timeout/overflow reap shapes the error with killed=true so the message reads
-    // correctly, but only a genuine *timeout* should classify as `error_kind:
-    // "timeout"` — listVegaDevices keys its skip-the-recovery-call decision off that,
-    // so an overflow (or other forced kill) must NOT masquerade as a wedged-agent
-    // timeout. Those callers pass an explicit kind; everything else uses the heuristic.
+    // A forced reap shapes the error with killed=true so the message reads correctly, but
+    // only a genuine *timeout* may classify as `error_kind: "timeout"` — listVegaDevices
+    // keys its skip-the-recovery-call decision off that, so an overflow must not
+    // masquerade as a wedged agent. Those callers pass an explicit kind.
     error_kind: kindOverride ?? (e.killed || e.signal ? "timeout" : "subprocess"),
     ...subprocessFailureMetadata(err, "vega")
   };
@@ -96803,7 +96767,7 @@ async function runVega(args, options = {}) {
     };
     const rejectTimeout = () => (
       // Shape like an execFile timeout rejection (killed=true) so it classifies as a
-      // timeout downstream — listVegaDevices keys its skip-the-recovery decision off it.
+      // timeout downstream.
       settle(
         () => reject(
           describeVegaFailure(
@@ -96826,9 +96790,9 @@ async function runVega(args, options = {}) {
             new Error(`vega ${args.join(" ")} output exceeded ${maxOutputBytes} bytes`),
             { killed: true, signal: VEGA_KILL_SIGNAL, stdout, stderr }
           ),
-          // Force "subprocess": an overflow is a misbehaving child, not a wedged
-          // agent. Without this the killed=true shape would classify as "timeout"
-          // and wrongly suppress the listVegaDevices recovery call.
+          // Force "subprocess": an overflow is a misbehaving child, not a wedged agent.
+          // The killed=true shape would otherwise classify as "timeout" and wrongly
+          // suppress the listVegaDevices recovery call.
           "subprocess"
         )
       )
@@ -97455,7 +97419,6 @@ async function run(args, options) {
       timeout: options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
       maxBuffer: 16 * 1024 * 1024,
       encoding: "utf8",
-      // sim-remote pipes stdin through to pbcopy etc.
       input: options?.stdin
     });
     return { stdout: typeof stdout === "string" ? stdout : stdout.toString("utf8") };
@@ -97747,9 +97710,9 @@ async function readProcessLaunchState(pid) {
     ({ stdout } = await execFileAsync8(PS_BIN, ["eww", "-p", String(pid), "-o", "etime=,command="], {
       encoding: "utf8",
       timeout: PS_PROBE_TIMEOUT_MS,
-      // Matches the other `ps` probes (vega-process.ts). An environment can run
+      // Matches the other `ps` probes (vega-process.ts): an environment can run
       // to `kern.argmax` (1 MiB), exactly Node's default cap, so the default
-      // would ENOBUFS on a maximal one instead of reading it.
+      // would ENOBUFS on a maximal one.
       maxBuffer: 16 * 1024 * 1024
     }));
   } catch (err) {
@@ -97845,17 +97808,16 @@ var remoteIosHost = {
     const { stdout } = await simctlSpawn(udid, { args: ["launchctl", "list"] });
     return parseUIKitApplicationBundleIds(stdout);
   },
-  // App processes live on the orchestrator, so the local process table says
-  // nothing about how they were launched. Only running-ness is answerable; the
-  // null process keeps callers on their no-evidence path.
+  // App processes live on the orchestrator, out of reach of the local process
+  // table, so only running-ness is answerable; the null process keeps callers on
+  // their no-evidence path.
   async inspectRunningApp(udid, bundleId) {
     const { stdout } = await simctlSpawn(udid, { args: ["launchctl", "list"] });
     return { running: parseUIKitApplicationJobs(stdout).has(bundleId), process: null };
   },
-  // Apply the accessibility defaults the tool-server needs (the local host does
-  // this via `defaults write`; here we run the same writes through the remote
-  // generic spawn). The entitlement-bypass plist is assumed active on cloud
-  // sims; if it isn't, describe will still surface a useful error.
+  // The same accessibility `defaults write`s the local host performs, routed
+  // through the remote generic spawn. The entitlement-bypass plist is assumed
+  // active on cloud sims.
   async bootstrapAx(udid) {
     for (const flag of ACCESSIBILITY_DEFAULT_FLAGS) {
       await simctlSpawn(udid, {
@@ -98266,13 +98228,11 @@ var NotImplementedOnPlatformError = class extends Error {
 };
 var InvalidToolInputError = class extends Error {
   /**
-   * @param signal Optional telemetry-signal overrides. The HTTP 400 mapping keys
-   *   off the error *class* (see http.ts), not the `error_code`, so a caller can
-   *   pass a more granular `error_code` / `failure_stage` / `error_kind` — e.g.
-   *   the keyboard backends' `KEYBOARD_KEY_UNSUPPORTED` /
-   *   `KEYBOARD_CHARACTER_UNSUPPORTED` / `VEGA_TEXT_INVALID` classifications
-   *   (from #420) — and keep both the granular telemetry bucket AND the 400
-   *   status. Defaults to the generic `TOOL_INPUT_INVALID` / validation signal.
+   * @param signal Telemetry-signal overrides. The HTTP 400 mapping keys off the
+   *   error *class* (see http.ts), not the `error_code`, so a caller can pass a
+   *   more granular code (e.g. the keyboard backends'
+   *   `KEYBOARD_CHARACTER_UNSUPPORTED`) and keep both the granular telemetry
+   *   bucket and the 400 status.
    */
   constructor(message, signal) {
     super(message);
@@ -108489,21 +108449,13 @@ var simulatorServerBlueprint = {
     return `${SIMULATOR_SERVER_NAMESPACE}:${device.id}`;
   },
   /**
-   * A cached simulator-server handle can outlive the thing it points at: when a
-   * simulator is un-booted (or the native server crashes) the child process may
-   * stay alive but stop listening on its API port, so every subsequent request
-   * fails with `ECONNREFUSED` against the now-dead port — the exact "worked once,
-   * then every call times out" symptom, unrecoverable until a human runs
-   * `stop-simulator-server`. The process never emitting `exit` means the
-   * registry's normal teardown (wired to `proc.on("exit")`) never fires.
-   *
-   * Treat a connection-refused failure as proof the instance is dead so the
-   * registry disposes it (killing the wedged process) and re-spawns a fresh
-   * simulator-server on the next call. Scoped to connection-refused only:
-   * ECONNREFUSED means the request never reached the server, so retrying can't
-   * double-apply a gesture. Timeouts and resets are deliberately excluded — the
-   * request there may have taken effect, and a hung-but-listening server is a
-   * different failure that respawning wouldn't fix.
+   * A wedged simulator-server (sim un-booted, native server crashed) can keep its
+   * process alive while no longer listening, so it never emits `exit`, the
+   * registry's teardown never fires, and every later call gets `ECONNREFUSED`
+   * until a human runs `stop-simulator-server`. Calling that recoverable makes
+   * the registry dispose the instance and re-spawn. Scoped to connection-refused
+   * only: the request provably never reached the server, so a retry can't
+   * double-apply a gesture, whereas a timeout or reset may have taken effect.
    */
   recoverable(error52) {
     return getFailureSignal(error52)?.network_failure === "connection_refused";
@@ -108782,17 +108734,10 @@ var CDPClient = class {
     });
   }
   /**
-   * Re-point this client at a different CDP WebSocket target (e.g. switching
-   * the active browser tab) WITHOUT emitting `disconnected`.
-   *
-   * Object identity is preserved, so existing references to this client
-   * (`server.cdp`, `api.cdp`, and every closure that captured it) automatically
-   * target the new tab after the swap — no rewiring needed. Callers that wire
-   * `disconnected` to teardown/termination therefore do not see a tab switch as
-   * a device loss.
-   *
-   * In-flight requests are rejected and per-connection state (enabled domains,
-   * parsed scripts) is reset — the new target starts fresh, so the caller must
+   * Re-point this client at another CDP target (e.g. a new browser tab) without
+   * emitting `disconnected`, which callers treat as a device loss. Object
+   * identity is preserved, so existing references need no rewiring. In-flight
+   * requests are rejected and per-connection state is reset, so the caller must
    * re-enable any domains it needs.
    */
   async reconnect(newWsUrl) {
@@ -108828,10 +108773,9 @@ var CDPClient = class {
       const timer = setTimeout(() => {
         this.pending.delete(id);
         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).
+          // The message carries its own recovery guidance: agents otherwise read
+          // this state as transient and retry-loop, each pass waiting out the
+          // 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.`,
             {
@@ -108878,8 +108822,8 @@ var CDPClient = class {
     this.bindingUnavailable = probe3 === "undefined";
   }
   /**
-   * Inject a script that will push a result via the binding using a unique requestId.
-   * Returns the parsed payload when the matching binding call arrives.
+   * Inject a script that pushes its result over the binding tagged with a
+   * requestId; resolves with the payload of the matching binding call.
    */
   evaluateWithBinding(expression, requestId, options) {
     const id = requestId ?? crypto3.randomUUID();
@@ -109077,9 +109021,8 @@ async function browserWebSocketUrl(port, signal) {
     throw new FailureError(
       `Chromium CDP on port ${port} did not report a browser webSocketDebuggerUrl in /json/version.`,
       {
-        // The endpoint responded but its payload was incomplete — a malformed
-        // response, not an unreachable port. Distinct code so telemetry doesn't
-        // conflate "reached but malformed" with a genuinely down debug port.
+        // Reached but malformed — telemetry must not conflate this with a
+        // genuinely down debug port.
         error_code: FAILURE_CODES.CHROMIUM_CDP_INVALID_RESPONSE,
         failure_stage: "chromium_cdp_browser_ws",
         failure_area: "tool_server",
@@ -109434,19 +109377,14 @@ var ScreencastManager = class {
   fps;
   activeCount = 0;
   currentOpts = null;
-  // The in-flight Page.startScreencast promise for the first subscriber, shared
-  // so concurrent joiners await the SAME start instead of assuming a live
-  // session (and stranding themselves on a frame-less stream if it fails). Null
-  // when no start is in flight (idle, or a live session already running).
+  // The first subscriber's in-flight Page.startScreencast, published so joiners
+  // await the SAME start instead of assuming a live session and stranding
+  // themselves on a frame-less stream if it fails.
   startInFlight = null;
   lastFrame = null;
   cdpListenerInstalled = false;
-  /**
-   * Most-recently-received frame, or null if no screencast is active /
-   * Chromium hasn't pushed a frame yet. Exposed so single-shot consumers
-   * (preview overlay, snapshot debug tool) can grab the last frame without
-   * starting their own session.
-   */
+  /** Never cleared on stop, so single-shot consumers can read a frame without
+   * starting their own session. */
   getLastFrame() {
     return this.lastFrame;
   }
@@ -109574,7 +109512,7 @@ function warnSharpMissingOnce(reason) {
 var DOWNSCALER_TO_KERNEL = {
   lanczos3: "lanczos3",
   box: "mitchell",
-  // sharp doesn't expose a true box kernel; mitchell is the closest fast alternative
+  // sharp has no box kernel
   bilinear: "lanczos2",
   nearest: "nearest"
 };
@@ -109789,12 +109727,8 @@ function createTabsManager(deps) {
           error_code: FAILURE_CODES.CHROMIUM_TAB_OPEN_FAILED,
           failure_stage: "chromium_tab_open",
           failure_area: "tool_server",
-          // The CDP command round-tripped but its response was missing the
-          // expected targetId — a malformed payload from a source we don't own,
-          // classified `unknown` like the other CDP-command failures in this
-          // server (CHROMIUM_SCREENSHOT_FAILED, the viewport/storage evals).
-          // `network`/`invalid_response` is reserved for the HTTP /json
-          // discovery layer, which has a genuine fetch transport.
+          // A malformed CDP response, not a transport failure:
+          // `network`/`invalid_response` is reserved for the HTTP /json layer.
           error_kind: "unknown"
         });
       return out.targetId;
@@ -109888,9 +109822,8 @@ function createNetworkManager(deps) {
         rec.resourceType = params.type ?? rec.resourceType;
         break;
       }
-      // The *ExtraInfo events carry the actual on-the-wire headers (Authorization,
-      // Set-Cookie, …) that the base events omit. Merge them in; they may arrive
-      // before the base event, so `record()` creates the entry if needed.
+      // The *ExtraInfo events carry on-the-wire headers (Authorization, Set-Cookie, …)
+      // the base events omit, and may arrive before them — hence `record()`, not `get()`.
       case "Network.requestWillBeSentExtraInfo": {
         const h = params.headers;
         if (h) {
@@ -110557,11 +110490,9 @@ Booted/ready devices are listed first. Platforms whose CLI is unavailable are si
       withDeadline(listIosSimulators(), [], "ios"),
       withDeadline(listRemoteIosSimulators(), [], "ios-remote"),
       withDeadline(
-        // Opt into runtimeKind enrichment (list-devices surfaces TV vs mobile to
-        // the agent, so the extra feature probe per device is warranted here — the
-        // boot-loop poller deliberately omits it), and pass the tight `adb devices`
-        // bound (NOT boot-device's 30s default) so the Android branch self-bounds
-        // under BRANCH_DEADLINE_MS — see ADB_DEVICES_TIMEOUT_MS.
+        // list-devices is the one caller that surfaces TV vs mobile, so it pays for
+        // runtimeKind's extra per-device probe. The explicit `adb devices` bound
+        // (not runAdb's 30s default) keeps this branch under BRANCH_DEADLINE_MS.
         listAndroidDevices({ runtimeKind: true, devicesTimeoutMs: ADB_DEVICES_TIMEOUT_MS }).catch(
           () => []
         ),
@@ -110620,39 +110551,33 @@ var VariantProposalStore = class {
   consumed = false;
   globalComment = "";
   /**
-   * Device the variants target (last non-empty udid an agent passed to
-   * `propose_variant`). Persists across rounds — the agent works on one device
-   * — so it is intentionally NOT cleared by `reset()`.
+   * Last non-empty udid an agent passed to `propose_variant`. One device spans
+   * many rounds, so `reset()` intentionally does NOT clear it.
    */
   device = null;
   /**
-   * True while an `argent lens` CLI session owns the window. Set via
-   * `setCliSession`; deliberately NOT cleared by `reset()` — a CLI session spans
-   * many propose→submit rounds, like `device`.
+   * True while an `argent lens` CLI session owns the window. A session spans many
+   * propose→submit rounds, so `reset()` deliberately does NOT clear it.
    */
   cliSession = false;
   /**
    * The agent choices a CLI Lens session offers (when more than one is
-   * installed) and the one the human picked in the window. The `argent lens`
-   * bridge passes the choices in on begin and polls `lensAgentChoice` to learn
-   * which agent to spawn. Empty / null outside an unresolved pick. Like
-   * `cliSession`, deliberately NOT cleared by `reset()`.
+   * installed) and the one the human picked. `argent lens` passes the choices in
+   * on begin and learns the pick over `/preview/lens-stream`. Like `cliSession`,
+   * deliberately NOT cleared by `reset()`.
    */
   lensAgents = [];
   lensAgentChoice = null;
   /**
-   * Whether the human asked to REMEMBER the agent pick (the picker's "Remember
-   * this choice" checkbox). The `argent lens` process reads this alongside the
-   * choice and persists it to `~/.argent/config.json` so later runs skip the
-   * picker. Tied to `lensAgentChoice`; reset with it.
+   * Whether the human ticked the picker's "Remember this choice". `argent lens`
+   * reads it alongside the pick and persists it to `~/.argent/config.json` so
+   * later runs skip the picker. Tied to `lensAgentChoice`; reset with it.
    */
   lensAgentRemember = false;
   /**
-   * Devices (iOS udid / Android serial) that Lens BOOTED itself — i.e. the
-   * `POST /preview/boot` route started them because they were not already
-   * running. Tracked so the tool-server can shut them down when the CLI Lens
-   * session ends (`takeOwnedDevices`), without ever touching a device the user
-   * had already booted. Like `cliSession`, NOT cleared by `reset()`.
+   * Devices `POST /preview/boot` started because they were not already running,
+   * so session-end teardown (`takeOwnedDevices`) shuts down only those and never
+   * one the user had booted. Like `cliSession`, NOT cleared by `reset()`.
    */
   ownedDevices = /* @__PURE__ */ new Set();
   submitted = [];
@@ -110663,15 +110588,12 @@ var VariantProposalStore = class {
   /** Frozen result of the current round once the user submits. */
   lastOutcome = null;
   /**
-   * Completed outcomes that finished with no `await_user_selection` parked to
-   * receive them directly (submitSelection's "no waiter" branch), queued in
-   * completion order. `autoRollIfCompleted` rolls into a fresh round on the
-   * very next `propose_variant` regardless of whether the outcome was ever
-   * retrieved — so this queue, unlike `lastOutcome`/`completed`/`consumed`
-   * (which describe only the CURRENT round), survives `reset()` and is
-   * drained first by `awaitSelection`, oldest first. Without it, a human's
-   * already-submitted selection is destroyed the moment the next
-   * `propose_variant` call rolls the round out from under it.
+   * Completed outcomes that finished with no await parked to receive them, in
+   * completion order. `autoRollIfCompleted` rolls on the next `propose_variant`
+   * whether or not the outcome was retrieved, so this queue — unlike
+   * `lastOutcome`/`completed`/`consumed`, which describe only the CURRENT round —
+   * survives `reset()` and is drained first by `awaitSelection`. Without it a
+   * roll destroys a human's already-submitted selection.
    */
   pendingOutcomes = [];
   /** Begin a fresh round, discarding the previous one's proposals/selections. */
@@ -110707,15 +110629,12 @@ var VariantProposalStore = class {
     this.events.emit("changed");
   }
   /**
-   * Emit the drop-off signal for a round still staged (proposals present, not
-   * completed) at process shutdown — "the server died mid-review". The
-   * tool-server calls this on its shutdown path, before the final telemetry
-   * drain, so a round the human never got to submit is counted as an abandonment
-   * instead of vanishing into the unattributable opens-minus-completions
-   * residue. Routes through reset() — the single abandonment choke point, guarded
-   * so a completed or empty round is a no-op — which also settles any await still
-   * parked on the dying round rather than letting it hang. Returns whether an
-   * abandonment was emitted (for the caller's logging / tests).
+   * Emit the drop-off signal for a round still staged at process shutdown — "the
+   * server died mid-review" — so it is counted instead of vanishing into the
+   * unattributable opens-minus-completions residue. The tool-server calls this
+   * before its final telemetry drain. Routes through reset(), the single
+   * abandonment choke point, which also settles any await parked on the dying
+   * round. Returns whether an abandonment was emitted.
    */
   flushAbandonedRound() {
     if (this.completed || this.proposals.length === 0) return false;
@@ -110728,13 +110647,12 @@ var VariantProposalStore = class {
     return p?.variants.find((v) => v.id === variantId) ?? null;
   }
   /**
-   * Called when the native preview window could not be launched (e.g. the
-   * optional `electron` dependency is absent on a headless/CI host). Settles
-   * every currently-parked, unsettled waiter with a `pending` outcome whose
-   * message points the agent at the browser fallback URL, rather than letting
-   * the await park for the full timeout with no window and no feedback. The
-   * proposals stay live, so the agent can relay the URL and re-await. No-ops
-   * when nothing is parked.
+   * Settle every parked waiter with a `pending` outcome pointing at the browser
+   * fallback URL when the native preview window could not launch (e.g. the
+   * optional `electron` dependency is absent on a headless/CI host), rather than
+   * letting the await run its full timeout with no window and no feedback. The
+   * proposals stay live, so the agent can relay the URL and re-await. No-ops when
+   * nothing is parked.
    */
   notifyWindowUnavailable(reason, url2) {
     const toSettle = this.waitersList.filter((w) => !w.settled);
@@ -110815,10 +110733,10 @@ var VariantProposalStore = class {
   }
   /**
    * Begin or end a CLI-driven Lens session (`argent lens`), optionally offering
-   * a set of agent choices for the window's picker. `cliSessionChanged` fires
-   * only on an actual begin/end transition (so the window opens/closes once),
-   * but the agent choices are always refreshed on a begin call — a re-begin from
-   * a fresh `argent lens` must replace any stale choices.
+   * agent choices for the window's picker. `cliSessionChanged` fires only on an
+   * actual begin/end transition (so the window opens/closes once), but the
+   * choices are refreshed on every begin — a re-begin from a fresh `argent lens`
+   * must replace stale ones.
    */
   setCliSession(active, agents = []) {
     const transitioned = this.cliSession !== active;
@@ -110836,8 +110754,7 @@ var VariantProposalStore = class {
     }
     this.events.emit("changed");
   }
-  /** Record the agent the human picked in the window's picker, and whether they
-   * asked to remember it. */
+  /** Record the agent the human picked, and whether they asked to remember it. */
   setLensAgentChoice(id, remember = false) {
     this.lensAgentChoice = id;
     this.lensAgentRemember = remember;
@@ -110860,18 +110777,16 @@ var VariantProposalStore = class {
     if (id.trim()) this.ownedDevices.add(id.trim());
   }
   /**
-   * Whether Lens booted this device itself (and is therefore responsible for
-   * it). Test-only accessor: production code manages ownership through
-   * `markDeviceOwned` / `releaseDevice` / `takeOwnedDevices` and never needs to
-   * read a single device's ownership. Kept as a non-mutating way for tests to
-   * assert ownership without draining it via `takeOwnedDevices`.
+   * Whether Lens booted this device itself. Test-only: production manages
+   * ownership through `markDeviceOwned` / `releaseDevice` / `takeOwnedDevices`,
+   * so this exists as a non-mutating way to assert it without draining the set.
    */
   isDeviceOwned(id) {
     return this.ownedDevices.has(id.trim());
   }
   /**
-   * Drop a single owned device — e.g. the user shut it down manually via the
-   * preview window, so session-end teardown must not try to kill it again.
+   * Drop a single owned device — e.g. the user shut it down from the preview
+   * window, so session-end teardown must not try to kill it again.
    */
   releaseDevice(id) {
     this.ownedDevices.delete(id.trim());
@@ -110884,22 +110799,21 @@ var VariantProposalStore = class {
   }
   /**
    * The frozen outcome of the last submitted round, or null if nothing has been
-   * submitted since the last reset. Read by `GET /preview/outcome` so the
-   * `argent lens` watcher can format the user's feedback and type it into the
-   * spawned `claude` terminal. Cleared (to null) when a new round begins.
+   * submitted since the last reset. Served over `/preview/outcome` and
+   * `/preview/lens-stream` so the `argent lens` watcher can format the user's
+   * feedback and type it into the spawned agent terminal.
    */
   getLastOutcome() {
     return this.lastOutcome;
   }
-  /** Called by the preview UI when the human presses "Complete selection". */
+  /** Called by the preview UI when the human submits their picks. */
   submitSelection(input) {
     if (typeof input.round === "number" && input.round !== this.round) {
       return { ok: true, round: this.round, resolved: 0, stale: true };
     }
     const cleanAnnotations = (input.annotations ?? []).filter((a) => a && typeof a.comment === "string" && a.comment.trim()).slice(0, MAX_ANNOTATIONS).map((a) => ({
       target: String(a.target ?? "").slice(0, 200) || "(element)",
-      // Cap the matcher value too — it is caller-supplied and, unlike the
-      // comment, was previously ingested uncapped.
+      // Caller-supplied and, unlike the comment, otherwise ingested uncapped.
       match: {
         by: a.match?.by ?? "text",
         value: String(a.match?.value ?? "").slice(0, MAX_MATCH_VALUE_LENGTH)
@@ -111015,14 +110929,12 @@ var VariantProposalStore = class {
     };
   }
   /**
-   * Block until the user submits a selection for the current round.
-   *
-   * Resolves immediately if a selection is already waiting to be consumed.
-   * On `timeoutMs` elapse returns a `pending` outcome (so the agent — or the
-   * MCP client wrapping it — can re-await without losing the live proposals).
-   * Honors `signal`: a client disconnect rejects with an AbortError. Every
-   * await parked on a round is resolved when that round is submitted (or the
-   * round is superseded), so concurrent / re-entrant awaits never strand.
+   * Block until the user submits a selection for the current round, resolving
+   * immediately if one is already waiting to be consumed. On `timeoutMs` returns
+   * a `pending` outcome so the caller can re-await without losing the live
+   * proposals; a `signal` abort rejects with an AbortError. Every await parked on
+   * a round is resolved when that round is submitted or superseded, so concurrent
+   * / re-entrant awaits never strand.
    */
   awaitSelection(opts) {
     if (opts.signal?.aborted) {
@@ -112074,9 +111986,8 @@ function deriveUiAutomatorRole(className) {
   return short || "View";
 }
 var NOISY_CLASSES = /* @__PURE__ */ new Set([
-  // React Native Skia/SVG icon internals: never tappable, parent already
-  // carries the icon's content-desc, and a single icon can balloon a dump by
-  // 40+ leaf nodes. Drop the entire subtree.
+  // react-native-svg icon internals: never tappable, and the parent already
+  // carries the icon's content-desc.
   "com.horcrux.svg.PathView",
   "com.horcrux.svg.GroupView",
   "com.horcrux.svg.SvgView"
@@ -112085,10 +111996,8 @@ function isNoisyUiAutomatorClass(className) {
   return NOISY_CLASSES.has(className);
 }
 var SYSTEM_PACKAGES = /* @__PURE__ */ new Set([
-  // Status bar / nav bar / quick settings — these exist on every dump but
-  // rarely matter for app-level navigation. Note we deliberately do NOT drop
-  // the foreground-app's own package even when the foreground IS a system app
-  // (settings, permission dialog), so permission prompts still surface.
+  // Status bar / nav bar / quick settings. Only systemui is listed on purpose:
+  // a foreground system app (settings, permission dialog) must still surface.
   "com.android.systemui"
 ]);
 var SYSTEM_RID_PREFIXES = [
@@ -112103,8 +112012,8 @@ var LAYOUT_CONTAINERS = /* @__PURE__ */ new Set([
   "androidx.constraintlayout.widget.ConstraintLayout",
   "androidx.coordinatorlayout.widget.CoordinatorLayout",
   "android.view.ViewGroup",
-  // Bare android.view.View is what Compose emits when a semantics node has
-  // no widget mapping; treat it as a scaffold and walk through.
+  // Compose emits bare android.view.View for semantics nodes with no widget
+  // mapping.
   "android.view.View"
 ]);
 function isUiAutomatorLayoutContainer(className) {
@@ -112442,8 +112351,7 @@ function resolveTraceProcessorAssets() {
 }
 function patchGlueForNode(src) {
   const edits = [
-    // Force memory32: skip the memory64 feature probe entirely (avoids the
-    // memory64 __syscall_mprotect path; no global WebAssembly wrapper).
+    // Force memory32: skip the memory64 probe and its __syscall_mprotect path.
     ["this.useMemory64 = hasMemory64Support();", "this.useMemory64 = false;"],
     // Hand the wasm bytes straight to emscripten -> it never calls readBinary/XHR.
     ["locateFile: (s) => s,", "locateFile: (s) => s, wasmBinary: globalThis.__TP_WASM_BYTES,"],
@@ -113222,10 +113130,8 @@ async function describeAndroid(registry2, serial, _bundleId, isTv) {
     throw new FailureError(
       `uiautomator could not capture the screen: ${trimmed}. Common causes: device locked / keyguard, DRM or secure overlay, Play Integrity screen. Unlock the device or take a screenshot as a fallback.`,
       {
-        // The adb wrapper exits 0, but the uiautomator tool it ran reported an
-        // in-band `ERROR:` line — a functional failure of the uiautomator
-        // subprocess. Classified `subprocess` to match the sibling
-        // ANDROID_UIAUTOMATOR_PARSE_FAILED (also adb-exit-0, unusable output).
+        // adb exits 0, but uiautomator reported an in-band `ERROR:` line — same
+        // adb-exit-0/unusable-output shape as ANDROID_UIAUTOMATOR_PARSE_FAILED.
         error_code: FAILURE_CODES.ANDROID_UIAUTOMATOR_CAPTURE_FAILED,
         failure_stage: "android_uiautomator_capture",
         failure_area: "tool_server",
@@ -113270,10 +113176,9 @@ function createPreviewRouter(registry2) {
       element_count: snap.proposals.length,
       variant_count: snap.proposals.reduce((n, p) => n + p.variants.length, 0),
       is_cli_session: snap.cliSession,
-      // Report platform ONLY for a round that actually staged proposals: the
-      // store's `device` deliberately survives reset(), so a CLI up-front open
-      // (element_count 0, no device bound THIS round) would otherwise inherit a
-      // prior flow's platform — a stale value next to a zero-count open.
+      // `device` deliberately survives the store's reset(), so a CLI up-front
+      // open (no proposals staged yet) would otherwise report a prior flow's
+      // platform.
       platform: snap.proposals.length > 0 && snap.device ? classifyDeviceForTelemetry(snap.device) : void 0
     });
   };
@@ -113539,16 +113444,16 @@ data: ${JSON.stringify(data)}
     }
     try {
       const result = variantProposalStore.submitSelection({
-        // The round the UI built this submit against (if it sent one). The store
-        // rejects it as stale when the round has since rolled, so a click from a
-        // tab whose round already completed/rolled can't mint a phantom completion.
+        // The round the UI built this submit against, if it sent one. The store
+        // rejects it once the round has rolled, so a click from a stale tab can't
+        // mint a phantom completion.
         round: typeof body.round === "number" ? body.round : void 0,
         selections,
         annotations,
         globalComment: typeof body.globalComment === "string" ? body.globalComment : void 0,
-        // Privacy-safe UI usage signals for `lens:round_completed`. Coerced to
-        // strict booleans so a malformed/absent field from the unauthenticated
-        // route can never carry anything but true/false into telemetry.
+        // UI usage signals for `lens:round_completed`. Coerced to strict booleans
+        // so a malformed field from this unauthenticated route can't carry
+        // anything else into telemetry.
         inspectorUsed: body.inspectorUsed === true,
         offscreenRevealed: body.offscreenRevealed === true
       });
@@ -115065,7 +114970,7 @@ var SourceMapsRegistry = class {
   }
   /**
    * Begin fetching and registering a source map from a Debugger.scriptParsed event.
-   * Returns immediately; use `waitForPending()` to block until all maps are loaded.
+   * Returns immediately; `waitForPending()` blocks until all maps are loaded.
    */
   registerFromScriptParsed(scriptUrl, scriptId, sourceMapURL) {
     if (!sourceMapURL) return;
@@ -115079,10 +114984,8 @@ var SourceMapsRegistry = class {
   /**
    * Resolve an original source file + line to its generated position in the bundle.
    *
-   * `filePath` can be:
-   *   - relative to project root, e.g. "App.tsx" or "src/components/Foo.tsx"
-   *   - absolute, e.g. "/Users/.../App.tsx"
-   *   - aliased, e.g. "/[metro-project]/App.tsx"
+   * `filePath` may be project-relative ("src/Foo.tsx"), absolute, or aliased
+   * ("/[metro-project]/App.tsx").
    */
   toGeneratedPosition(filePath, line1Based, column0Based = 0) {
     const candidates = this.buildSourceCandidates(filePath);
@@ -115110,10 +115013,7 @@ var SourceMapsRegistry = class {
     }
     return null;
   }
-  /**
-   * Find which source map source path matches the given file path.
-   * Returns the matched source string or null.
-   */
+  /** Matching entry in a registered map's `sources`, or null. */
   findMatchingSource(filePath) {
     const candidates = this.buildSourceCandidates(filePath);
     for (const map2 of this.maps) {
@@ -115456,22 +115356,12 @@ 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.)
+  // Deliberately NO recoverable(): the registry's self-heal disposes the node
+  // before retrying, and dispose unlinks the captured console log. It would
+  // also buy nothing — the only failure window while this node and ChromiumCdp
+  // both stay RUNNING is a tab switch, where CDPClient.reconnect() re-points
+  // the same client object and the cached node heals itself; a genuinely dead
+  // socket arrives instead as ChromiumCdp's terminated cascade.
   async factory(deps, payload, options) {
     const opts = options;
     const device = opts?.device;
@@ -115527,14 +115417,13 @@ var chromiumJsRuntimeDebuggerBlueprint = {
     const sourceResolver = makeStubSourceResolver();
     const api = {
       port,
-      // Chromium apps have no Metro project root. Empty string keeps the
-      // contract type-clean; callers that care (only inspect-element via the
-      // source resolver) are gated out before they ever touch this field.
+      // No Metro project root on Chromium; debugger-connect and debugger-status
+      // document the field as empty here.
       projectRoot: "",
       deviceName: device.name ?? "Chromium",
       appName: "Chromium",
       logicalDeviceId: device.id,
-      // Chromium always speaks the new CDP — there is no Hermes-legacy mode.
+      // No legacy RN inspector on Chromium.
       isNewDebugger: true,
       cdp,
       sourceResolver,
@@ -115913,14 +115802,11 @@ var ANDROID_NAMED_KEYCODES = {
   "esc": 111,
   // alias of escape
   "backspace": 67,
-  // KEYCODE_DEL (backspace: deletes the char before the cursor)
-  // `delete` aliases backspace, not forward-delete: the shared HID vocabulary in
-  // key-codes.ts (NAMED_KEYS) maps both `backspace` and `delete` to usage 42
-  // (Keyboard DELETE/Backspace), so iOS types `delete` as a backspace. A named
-  // key must mean the same thing on every platform, so map it to KEYCODE_DEL (67)
-  // here too rather than KEYCODE_FORWARD_DEL (112).
+  // KEYCODE_DEL
+  // KEYCODE_DEL, not KEYCODE_FORWARD_DEL (112): the shared HID vocabulary in
+  // key-codes.ts maps both `backspace` and `delete` to usage 42, and a named key
+  // must mean the same thing on every platform.
   "delete": 67,
-  // KEYCODE_DEL (alias of backspace — see note above)
   "tab": 61,
   // KEYCODE_TAB
   "space": 62,
@@ -115933,7 +115819,7 @@ var ANDROID_NAMED_KEYCODES = {
   // KEYCODE_DPAD_LEFT
   "arrow-right": 22,
   // KEYCODE_DPAD_RIGHT
-  // F1..F12 are KEYCODE_F1 (131) .. KEYCODE_F12 (142), contiguous.
+  // KEYCODE_F1 (131) .. KEYCODE_F12 (142) are contiguous.
   ...Object.fromEntries(Array.from({ length: 12 }, (_, i) => [`f${i + 1}`, 131 + i]))
 };
 var ANDROID_BUTTON_KEYCODES = {
@@ -115953,9 +115839,8 @@ var ANDROID_BUTTON_KEYCODES = {
 function assertTypeableAndroidText(text) {
   if (/[\n\r]/.test(text)) {
     throw new InvalidToolInputError(
-      // Advice must hold on every path sharing this guard: named keys work on
-      // phones/tablets but are rejected on a TV target (typeTv), where the
-      // equivalent is the tv-remote select press.
+      // The advice must also hold on the TV path (typeTv), which rejects named
+      // keys in favour of tv-remote select.
       'keyboard text must not contain a newline on Android; press enter separately instead (key: "enter" on a phone or tablet, tv-remote select on a TV)',
       {
         error_code: FAILURE_CODES.KEYBOARD_CHARACTER_UNSUPPORTED,
@@ -116181,15 +116066,13 @@ var androidTvControlBlueprint = {
           await injectAndroidText(serial, words[i]);
         }
       },
-      // Android TV reads the live hierarchy on every describe (no cached
-      // daemon), so there is no stale-cache class of bug to recover from.
+      // Android TV reads the live hierarchy on every describe — no cache to drop.
       async recycleAx() {
       }
     };
     const instance = {
       api,
-      // Stateless: every method is a fresh adb shell-out, so there is nothing to
-      // tear down. Present to satisfy the ServiceInstance contract.
+      // Stateless: every call is a fresh adb shell-out, so nothing to tear down.
       dispose: async () => {
       },
       events
@@ -116216,9 +116099,8 @@ var nativeDevtoolsStatusTool = {
   },
   capability: { apple: { simulator: true, device: true }, appleRemote: { simulator: true } },
   // The "injectable is false" recovery sentence inlines NON_INJECTABLE_RECOVERY
-  // verbatim: the description must stay a plain literal so scripts/extract-tools.mjs
-  // can read it statically for the spidershield scan. The verbatim match is pinned
-  // by native-devtools-status.test.ts.
+  // verbatim (pinned by native-devtools-status.test.ts): the description must stay
+  // a plain literal for scripts/extract-tools.mjs to read statically.
   description: `Check whether native devtools are connected to a specific app and whether the next launch is prepared for injection.
 Use when you need to verify native devtools readiness before calling native-full-hierarchy, native-describe-screen, or native-network-logs.
 
@@ -116297,13 +116179,13 @@ Fails if the simulator server is not running for the given UDID.`,
       // fresh process fixes — `indeterminate` among them, since an uninspectable
       // host (ios-remote) supports no finer reading. Both already carry a live
       // process (the settling above rewrote an empty `indeterminate` to
-      // `not_running`), so an `appRunning` conjunct would only restate the state.
+      // `not_running`), so an `appRunning` conjunct would restate the state.
       requiresRestart: state3 === "stale_process" || state3 === "indeterminate",
       state: state3,
       // The booleans cannot express "one restart, then stop" — the shape
       // `indeterminate` needs, and the only one ios-remote can report for a
-      // running app. Carrying the same prose as every other consumer keeps that
-      // escape off the agent having read this tool's description.
+      // running app. The shared prose puts that escape in front of an agent who
+      // never read this tool's description.
       ...state3 === "connected" ? {} : { message: buildAppStateMessage(params.bundleId, state3) },
       nextLaunchWillBeInjected: envSetup,
       injectable: true
@@ -117181,22 +117063,11 @@ 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.
+  // Only the send() guard's DEBUGGER_CDP_NOT_CONNECTED proves the request never
+  // left the host, so only it is safe to retry. CONNECTION_CLOSED and
+  // REQUEST_TIMEOUT reject requests that were delivered and may have taken
+  // effect; Metro discovery and target-selection codes throw before the node is
+  // RUNNING, where the registry never consults this.
   recoverable(error52) {
     return getFailureSignal(error52)?.error_code === FAILURE_CODES.DEBUGGER_CDP_NOT_CONNECTED;
   },
@@ -118367,11 +118238,8 @@ async function waitForAdbDevice(serial, timeoutMs) {
           error_code: FAILURE_CODES.VEGA_DEVICE_NOT_REGISTERED,
           failure_stage: "vega_adb_register",
           failure_area: "tool_server",
-          // We polled until the deadline and adb never enumerated the transport,
-          // so the failure is structurally a timeout. The distinct error_code
-          // (vs VEGA_BOOT_TIMEOUT, the VVD never starting) already carries the
-          // "registered vs started" distinction — error_kind reflects the true
-          // nature (deadline expiry) rather than double-encoding that.
+          // Deadline expiry, hence `timeout`; the error_code already separates this
+          // from VEGA_BOOT_TIMEOUT (the VVD never starting).
           error_kind: "timeout"
         }
       );
@@ -118671,11 +118539,9 @@ async function bootElectronApp(options) {
     child = (0, import_node_child_process17.spawn)(launcher.command, args, {
       detached: true,
       stdio: ["ignore", "pipe", "pipe"],
-      // Strip ELECTRON_RUN_AS_NODE (see electronGuiChildEnv): if the tool-server
-      // inherited it from an Electron-based MCP host, the Electron binary would
-      // run in Node mode with no CDP endpoint — so boot-device fails below (the
-      // child exits early, or the readiness probe times out) instead of the app
-      // coming up.
+      // Strip ELECTRON_RUN_AS_NODE (see electronGuiChildEnv): inherited from an
+      // Electron-based MCP host it would boot the binary in Node mode with no
+      // CDP endpoint, failing boot-device instead of bringing the app up.
       env: electronGuiChildEnv({ ELECTRON_ENABLE_LOGGING: "1" })
     });
   } catch (err) {
@@ -118838,11 +118704,9 @@ var STAGE_BUDGET = {
   pmReady: 45e3,
   // pm path android answers (retried; non-fatal on the final attempt)
   firstRealFrame: 9e4,
-  // screencap returns ≥1 non-zero pixel after cold boot
   firstRealFrameHot: 8e3
-  // tighter budget for snapshot-restore composite —
-  // the broken state is sticky (per assertScreencapAlive's docstring), so a
-  // few seconds is enough to discriminate transient blanks from genuine wedge.
+  // the sticky-blank state never clears on its own, so a
+  // few seconds is enough to tell it from a transient blank.
 };
 var VALID_GPU_MODES = /* @__PURE__ */ new Set([
   "auto",
@@ -119361,14 +119225,13 @@ async function bootAndroidImpl(params) {
           emulatorArgs: hotArgs,
           attemptDeadline: hotAttemptDeadline,
           serialsBefore,
-          // Snapshot restores register with adb within a couple of seconds;
-          // a minute-long register wait on the hot path would mask the
-          // scenario where load fails and the child silently cold-boots.
+          // Snapshot restores register with adb within seconds; a minute-long
+          // wait here would mask a failed load that silently cold-boots.
           adbRegisterBudgetMs: 3e4,
           deviceReadyBudgetMs: 3e4,
           bootCompletedBudgetMs: 3e4,
-          // Keep the hot path tight: a single ~10 s PM window, and tear down on
-          // failure so we fall through to the cold boot below.
+          // Keep the hot path tight: one ~10 s PM window, tear down on failure so
+          // we fall through to the cold boot below.
           pmProbeBudgetMs: 1e4,
           tearDownIfUnready: true
         });
@@ -119409,9 +119272,9 @@ async function bootAndroidImpl(params) {
       adbRegisterBudgetMs: STAGE_BUDGET.adbRegister,
       deviceReadyBudgetMs: STAGE_BUDGET.deviceReady,
       bootCompletedBudgetMs: STAGE_BUDGET.bootCompleted,
-      // Final attempt: retry PM for longer, and do NOT tear the emulator down
-      // if it stays slow — a guest that reached boot_completed is usable, and
-      // there is no further fallback to justify destroying it.
+      // Final attempt: retry PM for longer and don't tear the emulator down if
+      // it stays slow — a guest that reached boot_completed is usable, and there
+      // is no further fallback to justify destroying it.
       pmProbeBudgetMs: STAGE_BUDGET.pmReady,
       tearDownIfUnready: false
     });
@@ -119899,11 +119762,8 @@ Common Android packages: com.android.settings, com.android.chrome, com.google.an
     searchHint: "open start app bundle id package simulator emulator chromium vega launch tvos apple tv fire tv",
     zodSchema: zodSchema10,
     capability: capability2,
-    // Chromium declares an eager CDP service; ios-remote declares an eager
-    // native-devtools service (its handler shares the local iOS launch path,
-    // which reads `services.nativeDevtools`). Local iOS resolves native-devtools
-    // lazily in its handler so a tvOS udid never spins up the iOS-only injection
-    // (see header comment); Android and Vega need no service.
+    // ios-remote's handler reads `services.nativeDevtools`; local iOS resolves
+    // it lazily instead (see header comment).
     services: (params) => {
       const device = resolveDevice(params.udid);
       if (device.platform === "ios-remote") return { nativeDevtools: nativeDevtoolsRef(device) };
@@ -120084,11 +119944,8 @@ Returns { restarted, bundleId }. Fails if the app is not installed.`,
     searchHint: "terminate relaunch restart reset app bundle id package simulator emulator vega tvos fire tv",
     zodSchema: zodSchema11,
     capability: capability3,
-    // ios-remote declares an eager native-devtools service (its handler shares
-    // the local iOS relaunch path, which reads `services.nativeDevtools`). Local
-    // iOS resolves native-devtools lazily in its handler so a tvOS udid never
-    // spins up the iOS-only injection (see header comment); Android and Vega
-    // need no service.
+    // Only ios-remote's handler reads `services.nativeDevtools`, so only it
+    // needs an eager declaration.
     services: (params) => {
       const device = resolveDevice(params.udid);
       if (device.platform === "ios-remote") return { nativeDevtools: nativeDevtoolsRef(device) };
@@ -120381,8 +120238,8 @@ function buildIosHandler(backend) {
             failure_stage: "ios_settings_permission_simctl_privacy",
             failure_area: "tool_server",
             error_kind: "subprocess",
-            // Both backends run the `simctl privacy` verb (local via xcrun,
-            // remote via sim-remote), so it's the same subprocess for telemetry.
+            // Both backends run the same `simctl privacy` verb, so telemetry
+            // uses one subprocess name.
             ...subprocessFailureMetadata(err, "xcrun_simctl")
           },
           { cause: err instanceof Error ? err : new Error(String(err)) }
@@ -120562,12 +120419,11 @@ var permissionAction = {
   reset: { started: "Resetting", completed: "Reset" }
 };
 var capability5 = {
-  // `simctl privacy` edits the simulator's TCC store — physical iPhones have no
-  // equivalent host-side switch, so no `device: true` on apple.
+  // `simctl privacy` edits the simulator's TCC store; physical iPhones have no
+  // equivalent host-side switch, hence no `device: true`.
   apple: { simulator: true },
-  // sim-remote runs the same `simctl privacy` verb on a remote simulator, so a
-  // sim-remote setup can pre-set permissions too — matching the rest of the
-  // launch-app / restart-app / reinstall-app / open-url family.
+  // sim-remote exposes the same `simctl privacy` verb, so remote sims can
+  // pre-set permissions too.
   appleRemote: { simulator: true },
   android: { emulator: true, device: true, unknown: true }
 };
@@ -121218,9 +121074,9 @@ Fails if the simulator-server / emulator backend / Chromium CDP is not reachable
     zodSchema: zodSchema15,
     outputHint: "image",
     capability: capability7,
-    // No eager service: a tvOS udid classifies as iOS by shape, and declaring
-    // simulator-server here would spawn it for the tvOS device (which it cannot
-    // drive) and hang on the ready timeout. Resolve the backend lazily instead.
+    // No eager service: a tvOS udid classifies as iOS by shape, so declaring
+    // simulator-server here would spawn it for a device it cannot drive and hang
+    // on the ready timeout. Resolve the backend lazily instead.
     services: () => ({}),
     async execute(_services, params, ctx) {
       const signal = ctx?.signal ?? AbortSignal.timeout(16e3);
@@ -121908,15 +121764,12 @@ var zodSchema23 = external_exports.object({
 });
 var BUTTONS_BY_PLATFORM = {
   "ios": /* @__PURE__ */ new Set(["home", "power", "volumeUp", "volumeDown", "appSwitch", "actionButton"]),
-  // Remote iOS sims expose the same hardware buttons as local iOS.
   "ios-remote": /* @__PURE__ */ new Set(["home", "power", "volumeUp", "volumeDown", "appSwitch", "actionButton"]),
   "android": /* @__PURE__ */ new Set(["home", "back", "power", "volumeUp", "volumeDown", "appSwitch"]),
-  // Chromium apps have no hardware buttons; the capability gate already
-  // excludes them, the empty set keeps the lookup total if one slips through.
+  // The capability gate excludes chromium; the empty set keeps the lookup total.
   "chromium": /* @__PURE__ */ new Set([]),
-  // Vega is remote-driven: hardware buttons / D-pad go through the dedicated
-  // `tv-remote` tool, and this tool's capability omits `vega` so a Vega device is
-  // rejected before this map is consulted. Empty set keeps the record total.
+  // Vega buttons / D-pad go through the `tv-remote` tool; the capability omits
+  // `vega`, so this entry only keeps the record total.
   "vega": /* @__PURE__ */ new Set([])
 };
 var capability15 = {
@@ -121938,12 +121791,9 @@ Returns { pressed: buttonName }.
 Fails if the device backend is not reachable \u2014 the simulator-server for iOS, or \`adb\` for Android (Android presses are injected with \`adb shell input keyevent\`).`,
   zodSchema: zodSchema23,
   capability: capability15,
-  // Android presses go over `adb shell input keyevent` (see execute), not the
-  // simulator-server's HID transport, so declaring the service for an Android
-  // target would needlessly resolve + spawn a sim-server the tool never uses (up
-  // to a 30s ready-wait) and could throw ServiceInitializationError before the
-  // adb path even runs. Declare it only for the iOS / ios-remote path that
-  // actually consumes it (mirrors the sibling `keyboard` tool's lazy services).
+  // The Android path uses `adb`, so declaring the service for an Android target
+  // would spawn a sim-server the tool never uses (up to a 30s ready-wait) and
+  // could throw ServiceInitializationError before the adb path even runs.
   services: (params) => {
     const device = resolveDevice(params.udid);
     return device.platform === "android" ? {} : { simulatorServer: simulatorServerRef(device) };
@@ -122223,12 +122073,9 @@ async function typeAndroidPhone(device, params) {
 }
 function makeAndroidImpl(registry2) {
   return {
-    // Both sub-paths shell out to `adb`: the `isAndroidTv` probe up front, then
-    // `adb input` either way (TV via the focus daemon, phone via `input text` /
-    // `input keyevent`). Declare it so `dispatchByPlatform` preflights adb and a
-    // missing binary fails with the clean 424 install hint rather than surfacing
-    // from deeper in the probe. Matches the android branch of `describe` and
-    // `tv-remote`.
+    // Both sub-paths shell out to `adb` (the `isAndroidTv` probe, then `input`
+    // either way), so declaring it makes a missing binary fail with
+    // `dispatchByPlatform`'s 424 install hint instead of from inside the probe.
     requires: ["adb"],
     handler: async (_services, params, device) => await isAndroidTv(device.id) ? typeTv(registry2, device, params) : typeAndroidPhone(device, params)
   };
@@ -122399,11 +122246,9 @@ var REMOTE_BUTTONS = Object.keys(REMOTE_KEYCODES);
 var NAMED_KEYCODES = {
   "enter": "KEY_ENTER",
   "return": "KEY_ENTER",
-  // alias of enter (matches iOS/Android/Chromium)
   // Back is the TV analog of Escape; KEY_ESC is inert for the focus engine.
   "escape": "KEY_BACK",
   "esc": "KEY_BACK",
-  // alias of escape
   "backspace": "KEY_BACKSPACE",
   "delete": "KEY_DELETE",
   "tab": "KEY_TAB",
@@ -122412,8 +122257,7 @@ var NAMED_KEYCODES = {
   "arrow-down": "KEY_DOWN",
   "arrow-left": "KEY_LEFT",
   "arrow-right": "KEY_RIGHT",
-  // Vega names function keys KEY_FN_F<n> (not KEY_F<n>); KEY_FN_F1..F12 all exist
-  // in the device key-name table (verified against system.ext4, SDK 0.22.6759).
+  // Vega names function keys KEY_FN_F<n>, not KEY_F<n> (SDK 0.22.6759 key table).
   ...Object.fromEntries(Array.from({ length: 12 }, (_, i) => [`f${i + 1}`, `KEY_FN_F${i + 1}`]))
 };
 var SETTLE_BETWEEN_PRESSES_S = 0.3;
@@ -122524,16 +122368,13 @@ function createKeyboardTool(registry2) {
   return {
     id: "keyboard",
     interaction: {
-      // Treat both text and key as sensitive. `key` is an unrestricted string at
-      // this boundary, so a value must not reach the event log before execution
-      // validates whether it is a supported named key.
+      // Never quote the parameters: `text` may hold a plaintext credential and
+      // `key` is an unvalidated free string here, yet these messages reach the
+      // event log before `execute` runs.
       //
-      // `startedMsg` still words a text+key request because it renders BEFORE
-      // `execute` rejects the combination — and likewise words `{ key: "" }` as
-      // a key press, which `execute` also rejects. `completedMsg` runs only
-      // after a call that succeeded, so it sees neither. Each formatter
-      // therefore has to word a different set of shapes, and the empty
-      // request — neither parameter, a documented no-op — reaches both.
+      // That ordering also makes `startedMsg` word requests `execute` then
+      // rejects (text+key, `{ key: "" }`), while `completedMsg` runs only after
+      // a success and sees neither. Both see the empty request, a no-op.
       startedMsg: ({ params }) => {
         if (params.text === void 0) return "Pressing a key";
         if (params.key === void 0) return "Entering text";
@@ -122553,29 +122394,21 @@ One call does one action: pass text OR key, never both. To type and then press a
     zodSchema: zodSchema24,
     capability: capability16,
     searchHint: "type text keyboard input named key enter escape arrow tv vega fire tv search field hid leanback",
-    // No eager service: each branch resolves its backend lazily (TV control,
-    // simulator-server, CDP, or Vega adb), since distinguishing a TV target is
-    // async and a tvOS udid must never resolve simulator-server.
     services: () => ({}),
     execute: async (services, params, options) => {
       if (params.text !== void 0 && params.key !== void 0) {
         throw new InvalidToolInputError(
           // Says what did NOT happen, so the caller retries instead of first
-          // inspecting the field — and spells the retry out with a literal
-          // example rather than an ellipsis the Android backend can't type.
+          // inspecting the field. The example is literal because an ellipsis is
+          // non-ASCII and the Android backend rejects it.
           //
-          // The TV caveat is carried statically rather than by probing the
-          // target: this guard runs above the dispatch precisely so a combined
-          // request reaches no device, and distinguishing a TV kind is an async
-          // probe. Without it the prescribed `{ key: "enter" }` is a retry that
-          // cannot succeed on a TV, where `key` is rejected outright
-          // (platforms/tv.ts) — which is the diagnosis this guard would
-          // otherwise pre-empt.
-          'keyboard takes `text` or `key`, not both \u2014 nothing was typed. To type and then press a key, send two `keyboard` steps in one `run-sequence`: { text: "hello" } followed by { key: "enter" }. On a TV target (Apple TV / Android TV) `key` is not supported at all \u2014 type with `text` and move focus with `tv-remote` (up/down/left/right/select).' + // The one-`run-sequence` form and two bare calls are NOT equivalent
-          // once the text carries a placeholder, and this message is where an
-          // agent converts a combined secret call — the tool description's
-          // caveat is read long before that moment, if at all. The check is
-          // syntactic (the same `.includes` flow-utils.ts uses), so the guard
+          // The TV caveat is static, not probed: this guard runs above the
+          // dispatch, so the target kind is unknown here — yet without it the
+          // prescribed `{ key: "enter" }` is a retry that cannot succeed on a
+          // TV, where `key` is rejected outright (platforms/tv.ts).
+          'keyboard takes `text` or `key`, not both \u2014 nothing was typed. To type and then press a key, send two `keyboard` steps in one `run-sequence`: { text: "hello" } followed by { key: "enter" }. On a TV target (Apple TV / Android TV) `key` is not supported at all \u2014 type with `text` and move focus with `tv-remote` (up/down/left/right/select).' + // One `run-sequence` and two bare calls are NOT equivalent once the
+          // text carries a placeholder, and this message is where an agent
+          // converts a combined secret call. Syntactic check, so the guard
           // still resolves nothing.
           (params.text.includes(SECRET_PLACEHOLDER_MARKER) ? " This `text` carries a `" + SECRET_PLACEHOLDER_MARKER + '...}}` placeholder, so keep both steps in that ONE `run-sequence` rather than splitting them into two bare calls: the auto-screenshot skip is decided per tool call from the whole request, and a separate { key: "enter" } call carries no placeholder \u2014 its screenshot is taken after the key lands and can capture the still-visible secret.' : ""),
           {
@@ -122586,12 +122419,12 @@ One call does one action: pass text OR key, never both. To type and then press a
       }
       if (params.key === "") {
         throw new InvalidToolInputError(
-          // Names the omission as the alternative, because a caller that sent an
-          // empty string usually built the value from something absent.
+          // Names the omission as the alternative: a caller that sent an empty
+          // string usually built the value from something absent.
           "`key` is an empty string, which names no key \u2014 nothing was pressed. Pass a named key (enter, escape, backspace, tab, space, arrow-up, arrow-down, arrow-left, arrow-right, f1\u2013f12), or omit `key` if there is nothing to press.",
           {
-            // The same code an unknown name gets, because that is what this is:
-            // one telemetry bucket for every unusable `key` value.
+            // The same code an unknown name gets: one telemetry bucket for
+            // every unusable `key` value.
             error_code: FAILURE_CODES.KEYBOARD_KEY_UNSUPPORTED,
             failure_stage: "keyboard_named_key_empty",
             error_kind: "unsupported"
@@ -122648,8 +122481,8 @@ async function pasteSimulator(api, text) {
 }
 function makeIosImpl4(registry2) {
   return {
-    // `isTvOsSimulator` shells out to `simctl`; the simulator-server itself is
-    // resolved through the blueprint.
+    // `xcrun` is for the `isTvOsSimulator` probe; simulator-server comes from
+    // the blueprint.
     requires: ["xcrun"],
     async handler(_services, params, device) {
       if (await isTvOsSimulator(device.id)) rejectTv(device);
@@ -122702,21 +122535,16 @@ function makeAndroidImpl2(registry2) {
 
 // ../tool-server/src/tools/paste/index.ts
 var capability17 = {
-  // Simulators only. A physical iPhone's pasteboard is reachable through the
-  // same simulator-server endpoint, but the paste keystroke is not verified
-  // over the CoreDevice HID path, so `device` stays off until it is.
   apple: { simulator: true },
-  // A remote simulator pastes through the MoQ transport's existing paste
-  // primitive (device pasteboard + ⌘V on the remote host).
+  // A remote sim pastes over the MoQ transport (`simctl pbcopy` + ⌘V); the HTTP
+  // clipboard route does not exist there.
   appleRemote: { simulator: true },
-  // Emulators only: the clipboard is set through the emulator's gRPC
-  // endpoint, which a physical phone does not have. `unknown` is admitted
-  // because an unresolved serial may still be an emulator — the
-  // simulator-server refuses a phone either way.
+  // Emulators only: the clipboard is set through the emulator's gRPC endpoint,
+  // which a physical phone does not have. `unknown` is admitted because an
+  // unresolved serial may still be an emulator.
   android: { emulator: true, unknown: true }
-  // No `chromium`: the renderer can only reach the HOST clipboard, so a paste
-  // there would overwrite whatever the user has copied. No `vega`: no
-  // clipboard API is exposed by the VVD tooling.
+  // No `chromium`: its only clipboard is the HOST one, so a paste would
+  // overwrite what the user copied. No `vega`: VVD exposes no clipboard API.
   //
   // TV targets are not separate platforms (an Apple TV simulator is
   // `ios`/`simulator`, an Android TV emulator `android`/`emulator`), so each
@@ -123045,9 +122873,8 @@ function shakeFailure(udid, detail, cause) {
       failure_stage: "ios_shake_notifyutil",
       failure_area: "tool_server",
       error_kind: "subprocess",
-      // Only a thrown subprocess error carries the syscall/exit metadata. The
-      // remote backend reports a non-zero child in its JSON payload instead of
-      // throwing, so there is no error object to mine there.
+      // Only a thrown subprocess error carries the syscall/exit metadata; the
+      // remote backend reports a failed child in its JSON payload instead.
       ...cause ? subprocessFailureMetadata(cause, "xcrun_simctl") : {}
     },
     cause ? { cause } : void 0
@@ -123229,26 +123056,22 @@ var androidImpl6 = {
 
 // ../tool-server/src/tools/shake/index.ts
 var capability19 = {
-  // Simulator only. A physical iPhone's motion comes from real hardware; there
-  // is no host-side hook to fake it, so `device` stays false and a paired phone
-  // gets a clean 400 instead of a silent no-op.
+  // Simulator only: a physical iPhone's motion is real hardware, with no
+  // host-side hook to fake it.
   apple: { simulator: true },
-  // A remote simulator is still a simulator: `sim-remote spawn` runs the same
-  // in-simulator `notifyutil` argv the local path does.
+  // `sim-remote spawn` runs the same in-simulator `notifyutil` argv the local
+  // path does.
   appleRemote: { simulator: true },
-  // Android emulators only, for the same reason as iOS: a physical phone's
-  // accelerometer can't be driven from the host. `unknown` is allowed through
-  // because a serial that didn't resolve may still be an emulator; the handler
-  // re-checks and rejects a non-emulator serial explicitly.
+  // Emulators only, for the same reason as iOS. `unknown` is let through and
+  // the handler rejects a serial with no emulator console.
   android: { emulator: true, unknown: true }
-  // No `vega`: a Fire TV is rejected here, by the absent block.
+  // No `vega` block, so a Fire TV is rejected by the capability gate.
   //
-  // TV targets that are NOT separate platforms cannot be excluded here. An
-  // Apple TV simulator is `ios`/`simulator` and an Android TV emulator is
-  // `android`/`emulator` — identical to a phone by id shape and device kind, so
-  // the matrix admits them and each platform handler probes the runtime and
-  // rejects a TV. `supports` can't do it: it is synchronous, while the runtime
-  // kind is an async `simctl list` / `adb` probe.
+  // A TV that is not a separate platform can't be excluded here: an Apple TV
+  // simulator is `ios`/`simulator` and an Android TV emulator is
+  // `android`/`emulator`. Each platform handler probes the runtime and rejects
+  // a TV instead; `supports` can't, being synchronous while the probe is an
+  // async `simctl list` / `adb` call.
 };
 var shakeTool = {
   id: "shake",
@@ -123267,8 +123090,8 @@ Only phone/tablet simulators and emulators are supported.`,
   searchHint: "shake motion accelerometer undo typing dev menu gesture",
   zodSchema: shakeZodSchema,
   capability: capability19,
-  // Talks to `simctl` / `adb` directly, so no simulator-server is resolved —
-  // avoids spawning one (and its ready-wait) for a tool that never uses it.
+  // No simulator-server is resolved: `simctl`/`adb` are called directly, so a
+  // tool that never uses one doesn't spawn it or wait for it to be ready.
   services: () => ({}),
   execute: dispatchByPlatform({
     toolId: "shake",
@@ -123395,10 +123218,8 @@ Multi-step navigation: pass a path as { button: ["up","right","right","select"]
 Read the screen with \`describe\` before and after to see where focus landed.
 Returns { pressed, count }.`,
     alwaysLoad: true,
-    // A path (≤64 buttons) × repeat (≤50) flattens to thousands of presses that
-    // settle apart in one held device session — minutes of wall-clock. Mark
-    // long-running so the MCP adapter doesn't abort it at its per-request fetch
-    // timeout and the idle-shutdown timer is kept warm for the call's duration.
+    // A path (≤64 buttons) × repeat (≤50) flattens to thousands of presses, sent
+    // one round-trip at a time on the Apple/Android path — minutes of wall-clock.
     longRunning: true,
     searchHint: "tv remote dpad d-pad navigate focus up down left right select ok back home menu play pause rewind fast forward sequence path apple tv tvos android tv leanback vega fire tv",
     zodSchema: zodSchema26,
@@ -129777,16 +129598,13 @@ var ALLOWED_TOOLS = /* @__PURE__ */ new Set([
   "gesture-rotate",
   "button",
   "keyboard",
-  // `paste` belongs in a sequence for the same reason `keyboard` does: the
-  // focus tap, the paste and the submit are one user action.
+  // Sequenceable for the same reason `keyboard` is: the focus tap, the paste
+  // and the submit are one user action.
   "paste",
   "rotate",
-  // Sequencing matters for shake: the interesting cases are races (shake while
-  // a sheet is dismissing, shake right after typing), which need the steps
-  // dispatched back-to-back rather than across separate round-trips.
+  // Shake's interesting cases are races (shake while a sheet is dismissing,
+  // shake right after typing), which need back-to-back dispatch.
   "shake",
-  // `tv-remote` drives the D-pad on a TV target (Apple TV / Android TV / Vega);
-  // `keyboard` types into the focused field there.
   "tv-remote",
   AWAIT_UI_ELEMENT_TOOL_ID
 ]);
@@ -129812,9 +129630,8 @@ var capability22 = {
   android: { emulator: true, device: true, unknown: true },
   chromium: { app: true },
   // Vega (Fire TV) is a valid target: its `tv-remote` / `keyboard` steps are
-  // supported, and the description advertises it. Without this key the outer
-  // capability gate (HTTP layer's assertSupported) would reject a Vega udid
-  // before any step runs — each step's own capability is still enforced below.
+  // supported. Without this key the HTTP layer's `assertSupported` would reject
+  // a Vega udid before any step runs.
   vega: { vvd: true }
 };
 function createRunSequenceTool(registry2) {
@@ -129888,15 +129705,10 @@ Stops on the first error (or unmet await-ui-element condition) and returns parti
     searchHint: "batch sequence multiple gesture steps sequentially",
     zodSchema: zodSchema28,
     capability: capability22,
-    // No eagerly-declared service: each step resolves its own services through
-    // `invokeSubTool` below (simulator-server for iOS/Android, CDP for
-    // Chromium), so run-sequence itself needs none. An eager resolver can't be
-    // used here because a tvOS udid shape-classifies as `ios` (there is no
-    // `tvos` platform) — declaring simulator-server for it would spawn a
-    // controller it can't drive and hang on the ready timeout before any tv-*
-    // step could run. The sub-tool invocations still pay only their own
-    // first-step spawn cost, and `ctx` is threaded through so nested steps keep
-    // the outer request's telemetry attribution.
+    // Each step resolves its own services. An eager resolver can't be used
+    // because a tvOS udid shape-classifies as `ios` (there is no `tvos`
+    // platform), so declaring simulator-server would spawn a controller it
+    // can't drive and hang on the ready timeout before any tv-remote step runs.
     services: () => ({}),
     async execute(_services, params, ctx) {
       const { udid, steps } = params;
@@ -130044,16 +129856,15 @@ var NOT_CONNECTED_CODE_MAP = {
   [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).
+  // Raised by the connect pipeline's enable/binding sends when the target
+  // accepts the socket but its JS runtime never answers. A post-connect hang
+  // differs: the OPEN socket still reports status "connected" (see the
+  // socket-state gate 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.
+  // Reached but not CDP: a squatter on the debug port, an HTTP error status, or
+  // a non-JSON body — the same precondition class as the Metro arm's non-Metro
+  // occupant, 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"
@@ -130122,7 +129933,7 @@ Use when you need to verify connectivity before using other debugger tools. Neve
     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.
+    // structured result instead of a tool failure.
     services: () => ({}),
     async execute(_services, params, ctx) {
       try {
@@ -130245,11 +130056,8 @@ var debuggerReloadMetroTool = {
   description: `Restart the Metro JS bundle in the connected React Native app without restarting the native process.
 Use when you want to apply code changes or reset JS state. Returns { reloaded, port, method, deviceName, appName, logicalDeviceId } indicating which reload path was used and which device/app was targeted. Fails if Metro is not running on the given port.`,
   zodSchema: zodSchema32,
-  // Metro-only: Chromium loads from disk, not from a bundler. The closest
-  // analog (Page.reload against the renderer) would behave differently enough
-  // — preserving the URL but re-fetching index.html, blowing away in-memory
-  // app state — that calling it under the same tool name would mislead. If we
-  // want that on Chromium later, it deserves its own tool.
+  // RN-only: reloading a Chromium page is a different operation from restarting
+  // the Metro bundle, so it would need its own tool.
   capability: RN_ONLY_TOOL_CAPABILITY,
   services: (params) => ({
     debugger: `JsRuntimeDebugger:${params.port}:${canonicalDeviceId(params.device_id)}`
@@ -131094,9 +130902,8 @@ Use when you need tap coordinates for a React Native UI element. Returns a compa
   alwaysLoad: true,
   searchHint: "react native component tree discovery tap coordinates",
   zodSchema: zodSchema33,
-  // RN-only: depends on the React DevTools backend that ships with the JS
-  // bundle in dev builds. Chromium has no equivalent — use `describe` instead
-  // for DOM-tree discovery on Chromium.
+  // RN-only: needs the React DevTools backend from the dev JS bundle. Chromium has
+  // no equivalent — use `describe` there.
   capability: RN_ONLY_TOOL_CAPABILITY,
   services: (params) => ({
     debugger: `JsRuntimeDebugger:${params.port}:${canonicalDeviceId(params.device_id)}`
@@ -131464,7 +131271,6 @@ var SKIP_SET = /* @__PURE__ */ new Set([
   "TextInputLabel",
   "ThemeContext",
   "BaseHTMLEngineProvider",
-  // Fabric / cross-app entries
   "VScrollViewNativeComponent",
   "InnerScreen",
   "ScreenStackItem",
@@ -131603,10 +131409,8 @@ Set resolveSourceMaps to false to skip symbolication and get raw bundled locatio
 Set includeSkipped=true to see filtered items annotated with skip reasons.
 Use when you need the source file and line for a component at a tap coordinate. Fails if the app is not connected or the coordinate is outside the screen.`,
   zodSchema: zodSchema34,
-  // RN-only: uses React Native's internal getInspectorDataForViewAtPoint and
-  // Metro's /symbolicate endpoint. Chromium's CDP has DOM.getNodeForLocation
-  // for "what's here?" but the source-map flow would need a complete rewrite —
-  // out of scope for this port.
+  // RN-only: needs React Native's internal getInspectorDataForViewAtPoint and
+  // Metro's /symbolicate; the Chromium session has no source resolver.
   capability: RN_ONLY_TOOL_CAPABILITY,
   services: (params) => ({
     debugger: `JsRuntimeDebugger:${params.port}:${canonicalDeviceId(params.device_id)}`
@@ -131846,8 +131650,6 @@ On React Native (iOS / Android / Vega) interception is injected into the JS runt
 Use when inspecting outbound HTTP traffic or debugging API calls in the running app.
 Fails if the app is not connected (RN) or the device is not reachable (Chromium).`,
   zodSchema: zodSchema36,
-  // Works on RN (Metro-injected interceptor) and Chromium (native CDP Network
-  // domain), dispatched on the device id in `services` / `execute`.
   capability: DEBUGGER_TOOL_CAPABILITY,
   services: (params) => {
     const device = resolveDevice(params.device_id);
@@ -131936,8 +131738,6 @@ Returns request/response headers (sensitive headers redacted), status, timing, a
 Large response bodies are truncated. Use when you need headers, body, or timing for a specific request after listing logs.
 Returns an error message string if the requestId is not found \u2014 use view-network-logs to get valid requestId values.`,
   zodSchema: zodSchema37,
-  // Companion to view-network-logs: RN via the injected interceptor, Chromium
-  // via the native CDP Network recording. Dispatched on the device id.
   capability: DEBUGGER_TOOL_CAPABILITY,
   services: (params) => {
     const device = resolveDevice(params.device_id);
@@ -132048,10 +131848,9 @@ init_zod();
 
 // ../tool-server/src/tools/describe/format-tree.ts
 var CONTENT_ROLES = /* @__PURE__ */ new Set([
-  // iOS AX traits surfaced by mapNativeTraitsToDescribeRole. AXGroup is
-  // deliberately excluded: it's the catch-all wrapper, so requiring it to
-  // carry its own label/value before we emit a line keeps decorative
-  // groupings out of the output.
+  // The roles mapNativeTraitsToDescribeRole can return. AXGroup is excluded on
+  // purpose: as its catch-all fallback, requiring it to carry its own
+  // label/value before we emit a line keeps decorative groupings out.
   "AXButton",
   "AXStaticText",
   "AXImage",
@@ -132280,10 +132079,9 @@ function makeDescribeExecute(registry2) {
       )
     },
     iosRemote: {
-      // describeIos already handles both ax-service (TCP) and native-devtools
-      // fallback — both blueprints route through sim-remote when the device is
-      // ios-remote. Only the preflight dep differs. Remote sims are iOS-only
-      // (never tvOS), so the isTvOs verdict is always false.
+      // Both the ax-service and native-devtools blueprints route through
+      // sim-remote for an ios-remote device, so only the preflight dep differs
+      // from the ios branch.
       requires: ["sim-remote"],
       handler: async (_services, params, device) => withDescription(
         withBootCaveatOncePerDevice(
@@ -132295,9 +132093,8 @@ function makeDescribeExecute(registry2) {
     android: {
       requires: androidRequires,
       handler: async (_services, params, device) => (
-        // Resolve the form factor once and route on it: a TV goes to the
-        // focus-driven describe, a phone to the uiautomator tree — and pass the
-        // known `isTv: false` through so describeAndroid doesn't re-probe.
+        // Resolve the form factor once and thread the known `isTv: false`
+        // through so describeAndroid doesn't re-probe.
         await isAndroidTv(device.id) ? describeTv(registry2, device) : withDescription(await describeAndroid(registry2, params.udid, params.bundleId, false))
       )
     },
@@ -132553,9 +132350,6 @@ After starting, ask the user to perform the interaction to profile, then call re
 Returns { started_at, startedAtEpochMs, hermes_version, detected_architecture } on success, or the already_running payload described above.
 Fails if the Hermes runtime is not reachable or the Metro CDP connection cannot be established.`,
     zodSchema: zodSchema40,
-    // RN-only: bootstraps the React DevTools backend and uses Hermes'
-    // Profiler.start. A CDP-direct CPU profile for Chromium is tracked as a
-    // follow-up; the React commit recording has no Chromium analog.
     capability: RN_ONLY_TOOL_CAPABILITY,
     services: () => ({}),
     async execute(_services, params) {
@@ -132700,8 +132494,8 @@ Fails if the Hermes runtime is not reachable or the Metro CDP connection cannot
       const sessionId = crypto6.randomUUID();
       const ownerPayload = {
         sessionId,
-        // startedAtEpochMs/lastHeartbeatEpochMs set inside the script using
-        // the wrapper-captured value to eliminate clock skew.
+        // Set inside the start script from the wrapper-captured clock, to
+        // eliminate skew.
         startedAtEpochMs: 0,
         lastHeartbeatEpochMs: 0
       };
@@ -132915,7 +132709,6 @@ Returns { duration_ms, sample_count, fiber_renders_captured, total_react_commits
 When any commit had fibers whose display name could not be resolved at stop time (typically transient components like modals/tooltips/animations that unmounted before stop), the response also includes { unattributed_ms, unattributed_fiber_count, unattributed_commit_count } \u2014 these quantify how much work is not accounted for in the per-component breakdown (the per-commit duration itself remains correct).
 Fails if no active profiling session exists or the CDP connection was lost during recording.`,
     zodSchema: zodSchema41,
-    // RN-only: companion to react-profiler-start.
     capability: RN_ONLY_TOOL_CAPABILITY,
     services: () => ({}),
     async execute(_services, params) {
@@ -132954,10 +132747,8 @@ Fails if no active profiling session exists or the CDP connection was lost durin
             error_code: FAILURE_CODES.REACT_PROFILER_NO_ACTIVE_SESSION,
             failure_stage: "react_profiler_stop_inactive",
             failure_area: "tool_server",
-            // Internal session-state (start never reached the sampler), not caller
-            // input — matches the sibling session-lookup site above and the
-            // native NATIVE_PROFILER_NO_ACTIVE_SESSION so this code carries one
-            // consistent kind rather than splitting by which guard tripped.
+            // Internal session-state, not caller input — matches the session-lookup
+            // site above and the native NATIVE_PROFILER_NO_ACTIVE_SESSION twin.
             error_kind: "not_found"
           }
         );
@@ -134066,7 +133857,7 @@ async function runPipeline(input, options) {
     allClear: input.sessionMeta.allClear ?? false,
     maxCommitMs: input.sessionMeta.maxCommitMs,
     anyRuntimeCompilerDetected: tagOutput.anyRuntimeCompilerDetected,
-    // Use stored total from react-profiler-stop when available (all-clear path has no commits to count)
+    // The all-clear path keeps no commits, so tagOutput.reactCommits is 0
     reactCommits: input.sessionMeta.totalReactCommits ?? tagOutput.reactCommits,
     fiberRenders: tagOutput.fiberRenders,
     totalFirstMounts: tagOutput.totalFirstMounts,
@@ -134805,8 +134596,8 @@ is returned by react-profiler-start.
 Use when the profiling session is complete and you need to interpret the collected data.
 Fails if react-profiler-stop has not been called or no profiling data is stored.`,
   zodSchema: zodSchema43,
-  // RN-only: operates on profiler trace files captured via the React DevTools
-  // backend's commit recording, which is not present on Chromium.
+  // RN-only: reads commit data captured via the React DevTools backend, which
+  // Chromium does not have.
   capability: RN_ONLY_TOOL_CAPABILITY,
   services: () => ({}),
   async execute(_services, params, ctx) {
@@ -134960,12 +134751,9 @@ Call this per-finding after react-profiler-analyze to inspect source before prop
 Returns found: false if the component is not found in user-owned code (e.g. lives in node_modules).
 When several files define a component with the same name (e.g. platform variants like List.tsx and List.web.tsx), returns the primary match and lists the rest under otherMatches[] (file/line/col) \u2014 check it before assuming the returned file is the one you meant.`,
   zodSchema: zodSchema44,
-  // Companion to react-profiler-analyze. Carries the same RN-only capability
-  // declaration as the rest of react-profiler-* for intent-clarity, even
-  // though the HTTP gate is a no-op here (the tool takes no device_id, so
-  // there's nothing for the gate to inspect). An LLM agent reading the tool
-  // catalogue should see this is paired with the other react-profiler tools
-  // and not reach for it on a Chromium app.
+  // Declared so the tool catalogue groups this with the other react-profiler-*
+  // tools; the HTTP gate itself is a no-op here, as there is no device arg to
+  // inspect.
   capability: RN_ONLY_TOOL_CAPABILITY,
   fileInputs,
   services: () => ({}),
@@ -134999,8 +134787,8 @@ When several files define a component with the same name (e.g. platform variants
     }
     return {
       found: true,
-      // The key that actually matched, so the caller can tell which name hit
-      // when a wrapped name resolved through to a bare source identifier.
+      // The key that matched, so the caller sees when a wrapped name resolved
+      // through to a bare source identifier.
       component: matchedKey ?? params.component_name,
       requested: params.component_name,
       file: entry.file,
@@ -135101,9 +134889,7 @@ Call react-profiler-stop first. Reads directly from the stored cpuProfile.
 Returns a markdown table of the top hotspot functions with self-time, total-time, and location.
 Fails if react-profiler-stop has not been called or no CPU profile is stored.`,
   zodSchema: zodSchema45,
-  // RN-only: reads a Hermes CPU profile captured via the React profiler
-  // session. Chromium's V8 Profiler emits a different sample format — see the
-  // PR description for the follow-up scope.
+  // RN-only: reads a Hermes CPU profile; Chromium's V8 sample format differs.
   capability: RN_ONLY_TOOL_CAPABILITY,
   services: () => ({}),
   async execute(_services, params) {
@@ -135812,11 +135598,8 @@ async function execFileAsyncWithTimeout(file2, args, options = {}) {
   const { stdout, stderr } = await execFileAsync25(file2, args, {
     encoding: "utf-8",
     ...options,
-    // The timeout and maxBuffer are this wrapper's whole purpose (the
-    // event-loop-freeze and ENOBUFS guards documented above), so they are
-    // applied AFTER ...options — a caller can never silently weaken them by
-    // passing its own. maxBuffer stays a floor: a caller may raise it for an
-    // even larger capture, but never drop below the 256 MiB guard.
+    // Applied after ...options so a caller cannot weaken the guards; maxBuffer
+    // is a floor, so a caller may still raise it for a larger capture.
     timeout: DEFAULT_EXEC_TIMEOUT_MS,
     maxBuffer: Math.max(options.maxBuffer ?? 0, DEFAULT_EXEC_MAX_BUFFER)
   });
@@ -136369,8 +136152,7 @@ function aggregateCpuHotspots(rows, options) {
       duringHang,
       timeRangeMs: { first: firstMs, last: lastMs },
       burstWindows,
-      // Only emit when present (Android). Omitting the key on iOS keeps the iOS
-      // hotspot object shape byte-identical to before this change.
+      // Omit the key on iOS rather than emitting `dominantMapping: undefined`.
       ...acc.dominantMapping !== void 0 ? { dominantMapping: acc.dominantMapping } : {}
     });
   }
@@ -136784,17 +136566,16 @@ var SYSTEM_FRAME_PATTERNS = [
   /gfxstream/i,
   /rcCreateSync/,
   /_enc\b/,
-  // gl*Enc / rc*_enc emulator encoder trampolines
+  // emulator GL/Vulkan encoder trampolines
   // Linux kernel syscall entry + mm/vfs internals (no app symbol to act on).
   // x86-64 entry path:
   /\bdo_syscall_64\b/,
   /\bentry_SYSCALL/,
   /\b__x64_sys_/,
   /\bx64_sys_call\b/,
-  // arm64 (aarch64) entry path — the emulator/device the Android profiler runs
-  // on is arm64, so these are the leaves actually seen there. The names differ
-  // entirely from x86: the EL0 synchronous-exception vector dispatches to the
-  // SVC (syscall) handler, which calls invoke_syscall → __arm64_sys_<name>.
+  // arm64 entry path, named nothing like the x86 one: the EL0
+  // synchronous-exception vector dispatches to the SVC (syscall) handler, which
+  // calls invoke_syscall → __arm64_sys_<name>.
   // arch/arm64/kernel/{entry.S,entry-common.c,syscall.c}.
   /\b__arm64_sys_/,
   /\bel0t_64_sync(_handler)?\b/,
@@ -136804,9 +136585,9 @@ var SYSTEM_FRAME_PATTERNS = [
   /\bdo_el0_svc\b/,
   /\binvoke_syscall\b/,
   /\bel0_(da|ia)\b/,
-  // data / instruction abort handlers (page-fault leaves)
+  // data / instruction abort (page-fault) handlers
   /\b__arch_copy_(from|to)_user\b/,
-  // arm64 uaccess copy helpers (copy_{from,to}_user.S)
+  // arm64 uaccess copy helpers
   /\bksys_/,
   /\bvfs_(read|write|fsync)\b/,
   /\bgup_/,
@@ -137331,8 +137112,8 @@ function resolveDefaultTemplatePath() {
 ${candidates.map((c) => `  - ${c}`).join("\n")}
 Pass template_path explicitly, or rebuild so the template is copied into place.`,
     {
-      // A required bundled asset is absent — a packaging/build problem, not a
-      // device or subprocess failure — so dependency_missing with no command.
+      // A missing bundled asset is a packaging/build problem, not a device or
+      // subprocess failure.
       error_code: FAILURE_CODES.NATIVE_PROFILER_TRACE_TEMPLATE_MISSING,
       failure_stage: "ios_native_profiler_template_resolve",
       failure_area: "tool_server",
@@ -137869,8 +137650,7 @@ async function stopNativeProfilerIos(api) {
         failure_stage: "native_profiler_stop_session_state",
         failure_area: "tool_server",
         // Internal session-state, not caller input — matches the react twin
-        // REACT_PROFILER_NO_ACTIVE_SESSION (not_found) and the Android site so the
-        // "no active session" family carries one consistent kind.
+        // REACT_PROFILER_NO_ACTIVE_SESSION and the Android site.
         error_kind: "not_found"
       }
     );
@@ -137946,13 +137726,12 @@ async function analyzeNativeProfilerIos(api) {
     uiHangs,
     cpuHotspots,
     memoryLeaks,
-    // Freeze the exports' capture mode with the parsed data so drill-down
-    // consumers (leak_stacks, combined report) stay paired with it even after
-    // a newer capture re-stamps the session fields.
+    // Freeze the capture mode with the parsed data so drill-down consumers
+    // (leak_stacks, combined report) stay paired with it after a newer capture
+    // re-stamps the session fields.
     mallocStackLogging: api.mallocStackLogging,
-    // Freeze the recording's start time too — the combined report anchors these
-    // hangs to wall-clock time, and must use THIS capture's start, not whatever
-    // a later native-profiler-start re-stamps onto the live session field.
+    // Freeze the start time too — the combined report anchors these hangs to
+    // wall-clock time and must use THIS capture's start, not a later one's.
     wallClockStartMs: api.wallClockStartMs
   };
   const exportErrors = {};
@@ -137981,21 +137760,17 @@ async function analyzeNativeProfilerIos(api) {
     payload,
     traceFile: api.traceFile,
     exportErrors,
-    // wallClockStartMs is the recording's start time, stamped in-memory at
-    // native-profiler-start. A large gap to "now" means analyze is reusing a
-    // trace from an earlier capture in this same process run, not a fresh one.
+    // A large gap between the in-memory start time and "now" means analyze is reusing
+    // a trace from an earlier capture in this same process run, not a fresh one.
     //
-    // Limitation (iOS): unlike Android, iOS has no on-disk metadata sidecar, so
-    // profiler-load (which restores only the raw_*.xml) cannot recover the start
-    // time — wallClockStartMs is null for a loaded session and this note stays
-    // off. The note therefore fires only for a live in-process session, never
-    // for one restored from disk. Restoring iOS start-time across loads needs an
-    // iOS sidecar this Android-scoped change does not add; formatTraceFreshness
-    // degrades cleanly to null in that case. See test/ios-instruments/load-freshness.test.ts.
+    // iOS, unlike Android, has no on-disk metadata sidecar, so profiler-load (raw_*.xml
+    // only) cannot recover the start time: wallClockStartMs is null for a loaded
+    // session, formatTraceFreshness returns null, and the note stays off. See
+    // test/ios-instruments/load-freshness.test.ts.
     freshnessNote: formatTraceFreshness(api.wallClockStartMs, Date.now()) ?? void 0,
     // Same live-session-only caveat as wallClockStartMs: profiler-load has no
     // capture-mode sidecar, so a restored session renders with null (the
-    // unattributed-leaks note then falls back to inferring the mode).
+    // unattributed-leaks note then goes by the attributed-leak count instead).
     mallocStackLogging: api.mallocStackLogging
   });
 }
@@ -138843,20 +138618,18 @@ function cpuRowsToAggregatorRows(rows, traceStartNs) {
     const thread = normaliseAndroidThread(row.thread_name, row.is_main_thread === 1);
     out.push({
       dominantFunction: dominant,
-      // Mapping of the leaf frame (from cpu-hotspots.sql's MIN(spm.name)) —
-      // threaded through so classifyNativeFrame can recognise `/kernel` leaves.
+      // Threaded through so classifyNativeFrame can recognise `/kernel` leaves.
       ...row.leaf_mapping != null ? { dominantMapping: row.leaf_mapping } : {},
       thread,
       weightNs: row.sample_count * SAMPLE_PERIOD_NS,
-      // Android ships SQL-precomputed bursts, no raw timestamps. Empty array
-      // keeps the aggregator's duringHang check false (Android never passes hangSampleTimestamps).
+      // Bursts are precomputed in SQL, so no raw timestamps ship; the aggregator's
+      // duringHang stays false (Android never passes hangSampleTimestamps).
       timestampsNs: [],
       callChains: [{ chain: [dominant], count: row.sample_count }],
       precomputedBursts: parseBurstWindows(row.burst_windows, traceStartMs),
-      // first/last_ts_ns are absolute CLOCK_MONOTONIC ns: they exceed 2^53 after
-      // ~104 days of device uptime, so the WASM decoder hands them back as bigint
-      // (see readCell). traceStartNs is already a plain Number, so coerce here to
-      // avoid "Cannot mix BigInt and other types" — values stay integral.
+      // Absolute CLOCK_MONOTONIC ns passes 2^53 after ~104 days of uptime and
+      // readCell hands those back as bigint — coerce before mixing with the
+      // plain-Number traceStartNs.
       firstMs: Math.round((Number(row.first_ts_ns) - traceStartNs) / 1e6),
       lastMs: Math.round((Number(row.last_ts_ns) - traceStartNs) / 1e6),
       sampleCount: row.sample_count
@@ -139078,8 +138851,8 @@ async function stopNativeProfilerAndroid(api) {
         failure_stage: "android_native_profiler_stop",
         failure_area: "tool_server",
         // Internal session-state, not caller input — matches the react twin
-        // REACT_PROFILER_NO_ACTIVE_SESSION (not_found) so the "no active session"
-        // family carries one consistent kind across React/native/iOS/Android.
+        // REACT_PROFILER_NO_ACTIVE_SESSION so the "no active session" family
+        // carries one consistent kind.
         error_kind: "not_found"
       }
     );
@@ -139173,9 +138946,8 @@ async function analyzeNativeProfilerAndroid(api) {
     payload,
     traceFile: hostTracePath,
     exportErrors: pipelineResult.exportErrors,
-    // wallClockStartMs is the recording's start time (set at start, persisted in
-    // the metadata sidecar, restored by profiler-load). A large gap to "now"
-    // means we're analyzing a trace from an earlier session, not a fresh capture.
+    // Recording start time, persisted in the metadata sidecar and restored by
+    // profiler-load, so a large gap to "now" means an earlier session's trace.
     freshnessNote: formatTraceFreshness(api.wallClockStartMs, Date.now()) ?? void 0,
     // Explains an absent CPU section when samples exist but carry no stacks.
     cpuDiagnostic: pipelineResult.cpuDiagnostic
@@ -139274,7 +139046,7 @@ var nativeProfilerStopTool = {
     failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to stop native profiler: ${failureSignal2.error_code}`
   },
   capability: capability26,
-  // Packaging plus the export passes routinely exceed the 30s fetch timeout.
+  // Packaging plus the export passes routinely exceed the 30s MCP fetch timeout.
   longRunning: true,
   description: `Stop native profiling and export trace data.
 iOS: sends SIGINT to xctrace, waits for packaging, then exports CPU, hangs, and leaks XML.
@@ -139777,8 +139549,7 @@ function assertStoppableSession(api, stage) {
         error_code: reaped2 ? FAILURE_CODES.SCREEN_RECORDING_SERVER_SHUTTING_DOWN : FAILURE_CODES.SCREEN_RECORDING_NO_ACTIVE_SESSION,
         failure_stage: stage,
         failure_area: "tool_server",
-        // Session-state, not caller input — matches the profiler family's
-        // "no active session" kind.
+        // Session-state, not caller input — matches the profiler family's kind.
         error_kind: "not_found"
       }
     );
@@ -139926,7 +139697,7 @@ function ffmpegArgs(opts) {
     "-loglevel",
     "warning",
     // The pump feeds whole JPEGs at a fixed cadence, so the input timeline is
-    // exactly OUTPUT_FPS — no timestamp guessing, no variable-framerate stutter.
+    // exactly OUTPUT_FPS — no timestamp guessing.
     "-f",
     "image2pipe",
     "-framerate",
@@ -140354,10 +140125,9 @@ Returns { status: "recording", timeLimitSeconds, outputFile } \u2014 the video i
 Fails if a recording is already running on the device, the device is not booted, ffmpeg is not installed, or the platform cannot be recorded (tvOS, Chromium, Vega and remote simulators are unsupported).`,
     searchHint: "record video screen capture movie mp4 start filming screencast",
     zodSchema: zodSchema51,
-    // simulator-server is resolved inside execute, not declared here: a tvOS
-    // udid classifies as iOS by shape, and an eager service would spawn
-    // simulator-server for a device it cannot drive and hang on its ready
-    // timeout (same reasoning as `screenshot`).
+    // Resolved inside execute, not declared eagerly: a tvOS udid classifies as
+    // iOS by shape, so an eager service would spawn simulator-server for a
+    // device it cannot drive and hang on its ready timeout (as in `screenshot`).
     services: (params) => ({
       session: screenRecordingSessionRef(resolveDevice(params.udid))
     }),
@@ -140471,8 +140241,7 @@ Fails if no recording (running or finished-but-unretrieved) exists for the given
       hostPath: stopped.outputFile,
       kind: "screen-recording",
       mimeType: "video/mp4",
-      // Drop the internal `argent-` temp prefix so the saved file reads cleanly
-      // as `.argent/recordings/screen-recording-<device>-<ts>.mp4`.
+      // Drop the internal `argent-` temp-file prefix from the saved name.
       filename: (0, import_node_path20.basename)(stopped.outputFile).replace(/^argent-/, ""),
       saveDir: RECORDINGS_DIR
     });
@@ -140786,8 +140555,7 @@ Use when investigating JS CPU hotspots or correlating CPU cost with specific com
 Returns a markdown table of CPU hotspots, call tree, or per-component CPU breakdown.
 Fails if no CPU profile is stored \u2014 run react-profiler-stop first.`,
   zodSchema: zodSchema53,
-  // RN-only: reads Hermes-format CPU profiles. Chromium's V8 sample format is
-  // different — see the PR description for the follow-up scope.
+  // RN-only: reads Hermes-format CPU profiles; Chromium's V8 sample format differs.
   capability: RN_ONLY_TOOL_CAPABILITY,
   services: () => ({}),
   async execute(_services, params) {
@@ -141146,7 +140914,7 @@ Use when drilling into specific components or time windows after react-profiler-
 Returns a markdown table or tree of commit data matching the requested mode.
 Fails if react-profiler-stop has not been called or no commit data is stored.`,
   zodSchema: zodSchema54,
-  // RN-only: reads React commit data captured via the React DevTools backend.
+  // Reads React commit data captured via the React DevTools backend.
   capability: RN_ONLY_TOOL_CAPABILITY,
   services: () => ({}),
   async execute(_services, params) {
@@ -141534,9 +141302,7 @@ Use when drilling into native hang stacks, thread CPU breakdown, or memory leaks
 Returns a markdown report with native call stacks, thread weights, or leak details for the selected mode.
 Fails if native-profiler-analyze has not been run or no parsed trace data is in memory.`,
   zodSchema: zodSchema55,
-  // iOS: reads xctrace output. Android: queries the Perfetto .pftrace via the
-  // in-process trace-processor engine (see executeAndroid). Chromium has no
-  // native trace capture.
+  // No chromium entry: it has no native trace capture.
   capability: {
     apple: { simulator: true, device: true },
     android: { emulator: true, device: true, unknown: true }
@@ -141618,9 +141384,8 @@ Call this tool when both profilers were run in parallel on the same session.
 Returns a markdown report correlating hangs with React commits, memory leaks, and investigation hints.
 Fails if either react-profiler-analyze or native-profiler-analyze has not been called first.`,
   zodSchema: zodSchema56,
-  // Combines React (Hermes) + native traces. iOS reads xctrace output;
-  // Android re-queries the Perfetto .pftrace via loadAndroidCombinedData. The
-  // capture half exists on neither platform's Chromium.
+  // iOS reads xctrace output; Android re-queries the Perfetto .pftrace via
+  // loadAndroidCombinedData. Chromium has no native trace capture.
   capability: {
     apple: { simulator: true, device: true },
     android: { emulator: true, device: true, unknown: true }
@@ -141867,7 +141632,7 @@ Fails if either react-profiler-analyze or native-profiler-analyze has not been c
           memoryLeaks,
           mountComponents,
           // From parsedData, not the live session field: a recording started
-          // after the analyze must not re-label the data being rendered here.
+          // after analyze must not re-label the data rendered here.
           nativeApi.parsedData?.mallocStackLogging ?? null
         )
       );
@@ -142234,10 +141999,8 @@ async function loadNativeSession(debugDir, sessionId, api, appProcessOverride) {
         error_code: FAILURE_CODES.PROFILER_NATIVE_TRACE_MISSING,
         failure_stage: "profiler_load_native_session",
         failure_area: "tool_server",
-        // A trace file missing on disk is a not_found condition — same kind as
-        // the Android .pftrace-missing site above, so this shared code isn't
-        // split into two kinds by platform (validation stays for the
-        // analyze-before-stop guard, NATIVE_PROFILER_NO_EXPORTED_TRACE).
+        // A trace missing on disk is not_found; validation stays for the
+        // analyze-before-stop guard (NATIVE_PROFILER_NO_EXPORTED_TRACE).
         error_kind: "not_found"
       }
     );
@@ -142303,9 +142066,8 @@ Modes:
 Returns a summary of the loaded session or a session list for the list mode.
 Fails if the session_id is not found or required XML files are missing from disk.`,
   zodSchema: zodSchema57,
-  // Loads Hermes-format React traces or iOS xctrace XML — neither maps onto
-  // Chromium yet. The gate keeps the error close to the call site instead of
-  // letting it surface from inside the trace parser.
+  // The Hermes, xctrace and perfetto formats this loads have no Chromium
+  // equivalent; the gate fails at the call site, not inside the trace parser.
   capability: RN_ONLY_TOOL_CAPABILITY,
   services: (params) => {
     const svcs = {};
@@ -142367,12 +142129,9 @@ init_src();
 var URN_SUFFIXES = ["", ":tcp"];
 var PORT_KEYED_NAMESPACES = [
   JS_RUNTIME_DEBUGGER_NAMESPACE,
-  // Both declare `getDependencies -> JsRuntimeDebugger:<payload>`, so neither
-  // can be in a snapshot without it and neither adds any ownership the debugger
-  // entry does not already establish. They are listed for what `stopped`
-  // reports: a session that had a network inspector or a React profiler open is
-  // told those went away by name, rather than inferring it from the debugger
-  // line.
+  // Both depend on `JsRuntimeDebugger:<payload>`, so a cascade already reaps
+  // them; listed so `stopped` names them instead of leaving the caller to infer
+  // them from the debugger line.
   NETWORK_INSPECTOR_NAMESPACE,
   REACT_PROFILER_SESSION_NAMESPACE
 ];
@@ -142478,8 +142237,7 @@ function createStopAllSimulatorServersTool(registry2) {
     id: "stop-all-simulator-servers",
     interaction: {
       // "all" only holds for the unscoped sweep; a scoped call touches just the
-      // ids it was given, and saying otherwise would misreport a teardown that
-      // deliberately left another agent's devices running.
+      // ids it was given.
       startedMsg: ({ params }) => {
         const devices = params?.devices;
         return devices ? `Stopping simulator servers for ${devices.length} ${devices.length === 1 ? "device" : "devices"}` : "Stopping all simulator servers";
@@ -142575,9 +142333,8 @@ function listeningPids(port) {
     const output2 = (0, import_node_child_process28.execFileSync)("netstat", ["-ano"], {
       encoding: "utf-8",
       timeout: 5e3,
-      // `netstat -ano` dumps every socket on the host; a busy box easily
-      // exceeds Node's default 1 MiB maxBuffer, and the resulting ENOBUFS
-      // throw would misread as "port is free" (stopped:false).
+      // `netstat -ano` dumps every socket on the host; overflowing Node's
+      // default 1 MiB throws, which this tool would misread as "port is free".
       maxBuffer: 16 * 1024 * 1024
     });
     return parseNetstatListeningPids(output2, port);
@@ -144346,8 +144103,8 @@ var fileInputs2 = [
 var flowStartRecordingTool = {
   id: "flow-start-recording",
   interaction: {
-    // Name the flow: recordings are concurrent, so several of these lines can
-    // interleave in one log and "flow recording" would not identify which.
+    // Name the flow: concurrent recordings interleave in one log, and "flow
+    // recording" would not say which.
     startedMsg: ({ params }) => `Starting recording of flow ${params.name}`,
     completedMsg: ({ params, result }) => {
       if (!result.restarted) return `Started recording flow ${params.name}`;
@@ -144710,7 +144467,7 @@ function projectIosNode(node, screenW, screenH) {
     children: node.children ?? [],
     // Text hoists only from on-screen nodes (frame is null when the view is
     // scrolled off or zero-area) — otherwise a text assert against an ancestor
-    // would pass on content the screen doesn't show. Every labelled node is
+    // would pass on content the screen doesn't show. A label makes a node
     // leaf-eligible, so `frame` was computed for any node with text.
     ownText: frame ? node.label ?? "" : "",
     leaf,
@@ -144751,8 +144508,8 @@ var FULL_HIERARCHY_FIELDS = [
   "windowFrame",
   "hidden",
   "alpha",
-  // The type directive's focus wait; an older injected framework ignores the
-  // request, which just leaves the wait's poll unconfirmed.
+  // Read by the type directive's focus wait; an injected framework that omits
+  // it just leaves that wait's poll unconfirmed.
   "firstResponder"
 ];
 async function unreadableHierarchyReason(nativeApi, bundleId) {
@@ -144880,18 +144637,17 @@ function projectAndroidNode(node, screenW, screenH) {
   return {
     skip: skip2,
     children: childNodes(node),
-    // Text hoists only from on-screen nodes (frame is null when the bounds clip
-    // to zero area) — otherwise a text assert against an ancestor would pass on
-    // content the screen doesn't show. Every text-carrying node is
-    // leaf-eligible (its label is non-empty), so `frame` was computed for it.
+    // Off-screen text must not hoist, or an ancestor text assert would pass on
+    // content the screen doesn't show. Any node with text is leaf-eligible (its
+    // label is non-empty), so `frame` was computed for it.
     ownText: frame ? ownText2 : "",
     leaf,
-    // A password node shields its placeholder text like any identified node —
-    // even if it somehow lacks an id — so the secret can never bubble upward.
+    // A password field shields even when it carries no id, so nothing from it
+    // bubbles into an ancestor's hoisted text.
     shield: Boolean(identifier) || isPassword,
-    // Scroll-clip inputs (see `flattenHoisting`): a scrolling container's raw
-    // bounds clip its subtree, so a row it has scrolled out of view — still
-    // on the device screen — is dropped, matching the describe path's prune.
+    // Scroll-clip inputs (see `flattenHoisting`): a scroller's raw bounds clip
+    // its subtree, so a row scrolled out of view — but still on the device
+    // screen — is dropped, matching the describe path's prune.
     rect,
     scrolls: isUiAutomatorScrollable(attrs)
   };
@@ -144954,9 +144710,9 @@ function projectChromiumNode(node) {
   return {
     skip: false,
     children: node.children,
-    // Text hoists only from on-screen nodes — otherwise a text assert against
-    // an ancestor would pass on content the screen doesn't show. A password
-    // field's text never bubbles up (the walker already withholds its value).
+    // Off-screen text must not hoist, or a text assert against an ancestor
+    // would pass on content the screen doesn't show. A password's text never
+    // bubbles up.
     ownText: onScreen && !node.password ? nodeText(node) : "",
     leaf,
     shield: Boolean(node.identifier) || node.password === true
@@ -144987,8 +144743,8 @@ function projectVegaNode(node) {
   return {
     skip: false,
     children: node.children,
-    // Text hoists only from on-screen nodes — otherwise a text assert against
-    // an ancestor would pass on content the screen doesn't show.
+    // Off-screen text must not hoist, or a text assert against an ancestor
+    // would pass on content the screen doesn't show.
     ownText: onScreen ? nodeText(node) : "",
     leaf: { ...node, children: [] },
     shield: isAuthoredVegaTestId(node.identifier)
@@ -145826,10 +145582,9 @@ async function waitForIdle(env, step) {
     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.
+    // (relaunch the app) is the wrong repair for the commonest cause here: the
+    // app is simply not in the foreground, which reads exactly the same from the
+    // tree source. Name that first.
     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 = () => ({
@@ -145976,13 +145731,12 @@ function anchoredWarnings(session, steps) {
 var flowFinishRecordingTool = {
   id: "flow-finish-recording",
   interaction: {
-    // Name the flow: other recordings stay live across this call, so an
-    // unqualified "Finishing flow recording" would not identify which one.
+    // Name the flow: other recordings stay live, so an unqualified message would
+    // not identify which one.
     startedMsg: ({ params }) => `Finishing recording of flow ${params.name}`,
-    // `params.name` rather than the basename of `result.path`: the two are the
-    // same string on every branch — `assertSafeFlowName` admits no dots or
-    // separators, so `getFlowPath` produces `<name>.yaml` and nothing else —
-    // and this spelling matches the two formatters either side of it.
+    // `params.name` equals the basename of `result.path` on every branch
+    // (`assertSafeFlowName` admits no dots or separators), and matches the two
+    // formatters either side.
     completedMsg: ({ params }) => `Saved recorded flow ${params.name}`,
     failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to finish recording of flow ${params.name}: ${failureSignal2.error_code}`
   },
@@ -146417,7 +146171,7 @@ function createFlowAddStepTool(registry2) {
     id: "flow-add-step",
     interaction: {
       // Name the flow: recordings are concurrent, so several of these lines can
-      // interleave in one log and "the recorded flow" would not identify which.
+      // interleave in one log and "the recorded flow" would not say which.
       startedMsg: ({ params }) => `Adding ${params.command} step to flow ${params.name}`,
       completedMsg: ({ params }) => `Added ${params.command} step to flow ${params.name}`,
       failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to add ${params.command} step to flow ${params.name}: ${failureSignal2.error_code}`
@@ -146497,9 +146251,6 @@ If a step was recorded by mistake, remove it from the .yaml after \`flow-finish-
         toolResult,
         stepCount,
         recorded: summarizeStep(step, stepCount),
-        // Host mode: a path. Client mode: the directive that carries the YAML
-        // to the client, which IS the persistence mechanism there — the one
-        // place the full file still has to travel per step.
         savedTo
       };
     }
@@ -146518,8 +146269,7 @@ var zodSchema64 = external_exports.object({
 var flowInsertEchoTool = {
   id: "flow-add-echo",
   interaction: {
-    // Name the flow: recordings are concurrent, so several of these lines can
-    // interleave in one log and "the recorded flow" would not identify which.
+    // Name the flow: recordings are concurrent, so an unqualified message is ambiguous.
     startedMsg: ({ params }) => `Adding note to flow ${params.name}`,
     completedMsg: ({ params }) => `Added note to flow ${params.name}`,
     failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to add note to flow ${params.name}: ${failureSignal2.error_code}`
@@ -148834,12 +148584,11 @@ async function runSnapshot(env, opts) {
         baselinePath,
         currentPath,
         outputDir,
-        // A crop compares EVERY pixel of the element's region — no masking,
-        // wherever the crop sits. Masking a crop's overlap with the screen's
-        // top status-bar band would degenerate into comparing nothing for an
-        // element inside the band (a vacuous pass); a crop overlapping the
-        // band leans on best-effort pinStatusBar until frame resolution
-        // asserts the element clears it.
+        // A crop compares EVERY pixel of the element's region, wherever it
+        // sits. Masking a crop's overlap with the screen's top status-bar band
+        // would degenerate into comparing nothing for an element inside the
+        // band (a vacuous pass); a crop overlapping the band leans on the run's
+        // best-effort pinStatusBar instead.
         topMask: cropFrame === void 0 ? "status-bar" : "none",
         // Crop dimensions track the element — size drift must hard-fail below
         // instead of being resampled away like a full-screen scale difference.
@@ -149434,8 +149183,8 @@ Pass exactly one flow source: name for a saved flow under project_root, or flow_
         // One holder per ExecState, shared by nested `run:` flows: `deviceEnv`
         // spreads the reference, so what one step's settle learns about the
         // tree source the next one already has. A `tool: flow-execute` builds
-        // its own instead, which is why that step spends this verdict rather
-        // than inheriting whatever the sub-run proved.
+        // its own, which is why that step spends this verdict rather than
+        // inheriting whatever the sub-run proved.
         treeOutage: {},
         flowsDir,
         viaUpload,
@@ -149626,8 +149375,7 @@ function summarize(flowName, deviceId, executionPrerequisite, steps, aborted2) {
     // A cancelled run must never read as PASS — it may contain skips alone
     // (no fail/error report), so the verdict folds the abort in directly. A
     // skip by itself is NOT a failure: an unmet `when:` guard skips its block
-    // as a successful omission, and a hard stop already carries its own
-    // fail/error report.
+    // as a successful omission.
     ok: failed === 0 && errored === 0 && !aborted2,
     ...aborted2 ? { aborted: true } : {},
     passed,
@@ -151222,11 +150970,10 @@ var awaitUserSelectionTool = {
     failedMsg: ({ failureSignal: failureSignal2 }) => `Failed while waiting for variant selection: ${failureSignal2.error_code}`
   },
   featureFlag: "argent-lens",
-  // Hidden entirely while an `argent lens` CLI session owns the preview window:
-  // there, the user's picks are relayed into the agent's terminal as a normal
-  // message (see `argent-cli/src/lens.ts`), so the agent never blocks on a pick.
-  // Hiding the tool (rather than telling the agent "don't call it") keeps the
-  // CLI-relay surface honest — propose_variant then end the turn.
+  // Hidden while an `argent lens` CLI session owns the preview window: there the
+  // user's picks are relayed into the agent's terminal as a normal message (see
+  // `argent-cli/src/lens.ts`), so the agent ends its turn after propose_variant
+  // instead of blocking.
   hideWhen: () => variantProposalStore.isCliSession(),
   description: `Block until the human finishes picking among the variants you proposed (the ONE blocking call).
 
@@ -151901,10 +151648,8 @@ function createPreviewWindowManager(opts = {}) {
     const launchBin = wrapperBin ?? electronBin;
     const launchArgs = wrapperBin ? ["--no-sandbox", mainScript] : [mainScript];
     const next = (0, import_node_child_process33.spawn)(launchBin, launchArgs, {
-      // Strip ELECTRON_RUN_AS_NODE so the child boots as a GUI Electron app, not
-      // a bare Node runtime (see electronGuiChildEnv). An Electron-based MCP
-      // host puts it in our env, and inheriting it makes main.cjs crash at
-      // app.setName() with `app` undefined — the window never opens.
+      // Strips ELECTRON_RUN_AS_NODE, which an Electron-based MCP host leaves in
+      // our env, so the child boots as a GUI app instead of bare Node.
       env: electronGuiChildEnv({ ARGENT_PREVIEW_URL: url2 }),
       stdio: ["pipe", "ignore", "pipe"]
     });
@@ -152053,11 +151798,10 @@ function start() {
   const { stop: stopWatcher, ready: watcherReady } = startSimulatorWatcher(registry2);
   let server = null;
   const previewWindow = createPreviewWindowManager({
-    // If Electron can't launch (it's an optionalDependency — absent on
-    // headless/CI hosts), fail fast: unblock any parked await_user_selection
-    // with the browser fallback URL instead of stranding it for the full
-    // timeout. `previewWindowBaseUrl` (declared just below) is only read when
-    // this fires at runtime, long after module init.
+    // Electron is an optionalDependency (absent on headless/CI hosts); on a launch
+    // failure unblock any parked await with the browser fallback URL rather than
+    // stranding it for the full timeout. `previewWindowBaseUrl` is declared below
+    // but only called at runtime.
     onLaunchFailure: (err) => variantProposalStore.notifyWindowUnavailable(err.message, previewWindowBaseUrl())
   });
   const previewWindowBaseUrl = () => {