@swmansion/argent 0.20.1-next.8 → 0.21.0

package/dist/tool-server.cjs

@@ -758,6 +758,7 @@ var init_failure_codes = __esm({
       CHROMIUM_ELECTRON_EXITED_BEFORE_READY: "CHROMIUM_ELECTRON_EXITED_BEFORE_READY",
       KEYBOARD_KEY_UNSUPPORTED: "KEYBOARD_KEY_UNSUPPORTED",
       KEYBOARD_CHARACTER_UNSUPPORTED: "KEYBOARD_CHARACTER_UNSUPPORTED",
+      KEYBOARD_TEXT_AND_KEY_COMBINED: "KEYBOARD_TEXT_AND_KEY_COMBINED",
       SECRET_PLACEHOLDER_UNKNOWN: "SECRET_PLACEHOLDER_UNKNOWN",
       SCREENSHOT_DIFF_INPUT_INVALID: "SCREENSHOT_DIFF_INPUT_INVALID",
       BOOT_DEVICE_TARGET_SELECTION_INVALID: "BOOT_DEVICE_TARGET_SELECTION_INVALID",
@@ -85070,7 +85071,7 @@ var require_log = __commonJS({
       if (logLevel === "debug")
         console.log(...messages);
     }
-    function warn(logLevel, warning) {
+    function warn2(logLevel, warning) {
       if (logLevel === "debug" || logLevel === "warn") {
         if (typeof node_process.emitWarning === "function")
           node_process.emitWarning(warning);
@@ -85079,7 +85080,7 @@ var require_log = __commonJS({
       }
     }
     exports2.debug = debug;
-    exports2.warn = warn;
+    exports2.warn = warn2;
   }
 });
 
@@ -90785,6 +90786,10 @@ var FLAG_REGISTRY = [
     name: "tool-server-event-log",
     description: "Write structured tool-server lifecycle events to a JSONL file."
   },
+  {
+    name: "microinteractions",
+    description: "Amplify device actions with matching animations of the host window, so what happens on the guest is also visible on the desktop. Purely cosmetic, macOS only, and never affects whether the underlying action succeeds. Off by default."
+  },
   {
     name: "video-watermark",
     description: "Overlay the argent corner watermark on recorded screen videos. On by default; turn it off with `argent disable video-watermark`.",
@@ -96800,7 +96805,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.20.0";
+    return "0.21.0";
   }
   return "0.0.0";
 }
@@ -98188,7 +98193,7 @@ var import_node_path5 = __toESM(require("node:path"));
 var import_semver = __toESM(require_semver2());
 
 // ../tool-server/package.json
-var version3 = "0.20.0";
+var version3 = "0.21.0";
 
 // ../tool-server/src/utils/update-checker.ts
 var import_update_core = __toESM(require_dist4());
@@ -99604,9 +99609,9 @@ ${debugInfo}`);
     this.#dispose.length = 0;
     if (this.#async.length > 0) {
       try {
-        let warn;
+        let warn2;
         const timeout = new Promise((resolve11) => {
-          warn = setTimeout(() => {
+          warn2 = setTimeout(() => {
             if (DEV) {
               console.warn("spawn is still running after 5s; continuing anyway", this.#stack);
             }
@@ -99614,8 +99619,8 @@ ${debugInfo}`);
           }, 5e3);
         });
         await Promise.race([Promise.all(this.#async), timeout]);
-        if (warn)
-          clearTimeout(warn);
+        if (warn2)
+          clearTimeout(warn2);
         this.#async.length = 0;
       } catch (error52) {
         console.error("async effect error", error52);
@@ -119222,6 +119227,18 @@ function readMb(config2, key2) {
   return (m[2] || "M").toLowerCase().startsWith("g") ? n * 1024 : n;
 }
 
+// ../tool-server/src/utils/no-window-env.ts
+var TRUTHY = /* @__PURE__ */ new Set(["1", "true", "yes"]);
+function truthyEnv(name) {
+  return TRUTHY.has((process.env[name] ?? "").trim().toLowerCase());
+}
+function iosHeadlessFromEnv() {
+  return truthyEnv("ARGENT_SIMULATOR_NO_WINDOW");
+}
+function androidHeadlessFromEnv() {
+  return truthyEnv("ARGENT_EMULATOR_NO_WINDOW");
+}
+
 // ../tool-server/src/utils/vega-vvd.ts
 init_src();
 init_adb();
@@ -119764,14 +119781,6 @@ function selectGpuMode() {
   }
   return process.platform === "linux" ? "swiftshader" : "auto";
 }
-function selectExtraEmulatorArgs() {
-  const trimmed = (process.env.ARGENT_EMULATOR_NO_WINDOW ?? "").trim().toLowerCase();
-  return ["1", "true", "yes"].includes(trimmed) ? ["-no-window"] : [];
-}
-function iosHeadlessFromEnv() {
-  const trimmed = (process.env.ARGENT_SIMULATOR_NO_WINDOW ?? "").trim().toLowerCase();
-  return ["1", "true", "yes"].includes(trimmed);
-}
 var BOOT_POLL_INTERVALS_MS = {
   serialByAvd: 1500,
   // findSerialByAvdName: re-scan when >1 new emulator appeared
@@ -120155,7 +120164,7 @@ async function bootAndroidImpl(params) {
   await ensureDep("adb");
   await ensureDep("emulator");
   const gpuMode = selectGpuMode();
-  const extraEmulatorArgs = selectExtraEmulatorArgs();
+  const extraEmulatorArgs = androidHeadlessFromEnv() ? ["-no-window"] : [];
   for (const msg of linuxBootDiagnostics(params.avdName) ?? []) {
     console.warn(`[boot-device:linux] ${msg}`);
   }
@@ -122653,6 +122662,7 @@ Fails if the device backend is not reachable \u2014 the simulator-server for iOS
 
 // ../tool-server/src/tools/keyboard/index.ts
 init_zod();
+init_src();
 
 // ../tool-server/src/utils/secrets.ts
 init_src();
@@ -122813,21 +122823,6 @@ async function typeSimulatorServer(registry2, device, params) {
     }
     keysPressed++;
   };
-  let namedKeyCode;
-  if (params.key) {
-    const lower = params.key.toLowerCase();
-    namedKeyCode = Object.hasOwn(NAMED_KEYS, lower) ? NAMED_KEYS[lower] : void 0;
-    if (namedKeyCode == null) {
-      throw new InvalidToolInputError(
-        `Unknown key "${params.key}". Supported: ${Object.keys(NAMED_KEYS).join(", ")}`,
-        {
-          error_code: FAILURE_CODES.KEYBOARD_KEY_UNSUPPORTED,
-          failure_stage: "keyboard_named_key_simulator",
-          error_kind: "unsupported"
-        }
-      );
-    }
-  }
   if (params.text) {
     for (const char of params.text) {
       const press = charToKeyPress(char);
@@ -122841,7 +122836,19 @@ async function typeSimulatorServer(registry2, device, params) {
       await sleep8(delay2);
     }
   }
-  if (namedKeyCode != null) {
+  if (params.key) {
+    const lower = params.key.toLowerCase();
+    const namedKeyCode = Object.hasOwn(NAMED_KEYS, lower) ? NAMED_KEYS[lower] : void 0;
+    if (namedKeyCode == null) {
+      throw new InvalidToolInputError(
+        `Unknown key "${params.key}". Supported: ${Object.keys(NAMED_KEYS).join(", ")}`,
+        {
+          error_code: FAILURE_CODES.KEYBOARD_KEY_UNSUPPORTED,
+          failure_stage: "keyboard_named_key_simulator",
+          error_kind: "unsupported"
+        }
+      );
+    }
     await pressKeyCode(namedKeyCode);
   }
   return { typed: params.text ?? params.key ?? "", keys: keysPressed };
@@ -122890,15 +122897,14 @@ function makeIosRemoteImpl(registry2) {
 init_adb();
 async function typeAndroidPhone(device, params) {
   let keysPressed = 0;
-  if (params.text) assertTypeableAndroidText(params.text);
-  if (params.key) {
-    await injectAndroidNamedKey(device.id, params.key);
-    keysPressed++;
-  }
   if (params.text) {
     await injectAndroidText(device.id, params.text);
     keysPressed += params.text.length;
   }
+  if (params.key) {
+    await injectAndroidNamedKey(device.id, params.key);
+    keysPressed++;
+  }
   return { typed: params.text ?? params.key ?? "", keys: keysPressed };
 }
 function makeAndroidImpl(registry2) {
@@ -122987,21 +122993,6 @@ var sleep9 = (ms) => new Promise((r) => setTimeout(r, ms));
 async function runChromium(api, params) {
   const delay2 = params.delayMs ?? 50;
   let keysPressed = 0;
-  let named;
-  if (params.key) {
-    const lower = params.key.toLowerCase();
-    named = Object.hasOwn(CHROMIUM_NAMED_KEYS, lower) ? CHROMIUM_NAMED_KEYS[lower] : void 0;
-    if (!named) {
-      throw new InvalidToolInputError(
-        `Unknown key "${params.key}". Supported: ${Object.keys(CHROMIUM_NAMED_KEYS).join(", ")}`,
-        {
-          error_code: FAILURE_CODES.KEYBOARD_KEY_UNSUPPORTED,
-          failure_stage: "keyboard_named_key_chromium",
-          error_kind: "unsupported"
-        }
-      );
-    }
-  }
   if (params.text) {
     for (const char of params.text) {
       const desc = charToChromiumKey(char);
@@ -123029,7 +123020,19 @@ async function runChromium(api, params) {
       await sleep9(delay2);
     }
   }
-  if (named) {
+  if (params.key) {
+    const lower = params.key.toLowerCase();
+    const named = Object.hasOwn(CHROMIUM_NAMED_KEYS, lower) ? CHROMIUM_NAMED_KEYS[lower] : void 0;
+    if (!named) {
+      throw new InvalidToolInputError(
+        `Unknown key "${params.key}". Supported: ${Object.keys(CHROMIUM_NAMED_KEYS).join(", ")}`,
+        {
+          error_code: FAILURE_CODES.KEYBOARD_KEY_UNSUPPORTED,
+          failure_stage: "keyboard_named_key_chromium",
+          error_kind: "unsupported"
+        }
+      );
+    }
     await api.dispatchKeyEvent({
       type: "keyDown",
       key: named.key,
@@ -123128,7 +123131,7 @@ async function injectViaInputd(subcommands) {
 async function injectVegaButtons(buttons) {
   await injectViaInputd(remoteButtonsToKeycodes(buttons).map((code) => `button_press ${code}`));
 }
-function resolveVegaNamedKeycode(name) {
+async function injectVegaNamedKey(name) {
   const lower = name.toLowerCase();
   const code = Object.hasOwn(NAMED_KEYCODES, lower) ? NAMED_KEYCODES[lower] : void 0;
   if (!code) {
@@ -123141,10 +123144,7 @@ function resolveVegaNamedKeycode(name) {
       }
     );
   }
-  return code;
-}
-async function injectVegaNamedKey(name) {
-  await injectViaInputd([`button_press ${resolveVegaNamedKeycode(name)}`]);
+  await injectViaInputd([`button_press ${code}`]);
 }
 async function injectVegaText(text) {
   if (/[\n\r]/.test(text)) {
@@ -123160,7 +123160,6 @@ async function injectVegaText(text) {
 // ../tool-server/src/tools/keyboard/platforms/vega.ts
 async function runVega2(params) {
   let keysPressed = 0;
-  if (params.key) resolveVegaNamedKeycode(params.key);
   if (params.text) {
     await injectVegaText(params.text);
     keysPressed += [...params.text].length;
@@ -123182,10 +123181,10 @@ var zodSchema24 = external_exports.object({
     "Target device id from `list-devices` (iOS UDID, Android serial, Vega serial, or Chromium id)."
   ),
   text: external_exports.string().optional().describe(
-    'Text to type character by character. Handles uppercase and common punctuation. To type a credential without its plaintext ever entering your context, use a secret placeholder: `{{secret:<NAME>}}` \u2014 e.g. text: "{{secret:APP_PASSWORD}}". The value is resolved on the machine running the tool-server, from the first source that defines the name: the `ARGENT_SECRET_<NAME>` environment variable, `.argent/secrets.env` in the project, the project\'s `.env.local` / `.env` (only their `ARGENT_SECRET_`-prefixed keys), then `~/.argent/secrets.env`. Nothing else on the host is reachable. Placeholders can be embedded in longer text and are never echoed back resolved. If the secret you need is not set, the failure lists the available names and every source it looked in \u2014 ask the user to add it to one of them (a secrets file applies immediately; an env var needs a restart), NEVER ask the user to paste the secret value into the conversation.'
+    'Text to type character by character. Cannot be combined with `key` in one call \u2014 one call per action; to type and then press a key, put two `keyboard` steps in one `run-sequence`. Handles uppercase and common punctuation. To type a credential without its plaintext ever entering your context, use a secret placeholder: `{{secret:<NAME>}}` \u2014 e.g. text: "{{secret:APP_PASSWORD}}". The value is resolved on the machine running the tool-server, from the first source that defines the name: the `ARGENT_SECRET_<NAME>` environment variable, `.argent/secrets.env` in the project, the project\'s `.env.local` / `.env` (only their `ARGENT_SECRET_`-prefixed keys), then `~/.argent/secrets.env`. Nothing else on the host is reachable. Placeholders can be embedded in longer text and are never echoed back resolved. If the secret you need is not set, the failure lists the available names and every source it looked in \u2014 ask the user to add it to one of them (a secrets file applies immediately; an env var needs a restart), NEVER ask the user to paste the secret value into the conversation.'
   ),
   key: external_exports.string().optional().describe(
-    "Named key to press: enter, escape, backspace, tab, space, arrow-up, arrow-down, arrow-left, arrow-right, f1\u2013f12. When combined with `text`, the key is pressed AFTER the text is typed (so text + enter types and submits). Not supported on TV targets \u2014 move focus with `tv-remote` (up/down/left/right) instead."
+    "Named key to press: enter, escape, backspace, tab, space, arrow-up, arrow-down, arrow-left, arrow-right, f1\u2013f12. Cannot be combined with `text` in one call \u2014 one call per action; to type and then press a key, put two `keyboard` steps in one `run-sequence`. Not supported on TV targets \u2014 move focus with `tv-remote` (up/down/left/right) instead."
   ),
   delayMs: external_exports.number().optional().describe(
     "Delay in ms between key presses (default 50). Ignored on Android phones/tablets (typed via `adb input text`, which has no per-key cadence), on Vega (text/keys injected in a single shot), and on TV targets (Apple TV / Android TV type the whole string at the daemon's own cadence)."
@@ -123214,25 +123213,29 @@ function createKeyboardTool(registry2) {
       // 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.
+      //
+      // `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.
       startedMsg: ({ params }) => {
         if (params.text === void 0) return "Pressing a key";
         if (params.key === void 0) return "Entering text";
         return "Entering text and pressing a key";
       },
-      completedMsg: ({ params }) => {
-        if (params.text === void 0) return "Pressed a key";
-        if (params.key === void 0) return "Entered text";
-        return "Entered text and pressed a key";
-      },
+      completedMsg: ({ params }) => params.text === void 0 ? "Pressed a key" : "Entered text",
       failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to use keyboard: ${failureSignal2.error_code}`
     },
     description: `Type text or press special keys on the device (iOS simulator, Android emulator or device, Chromium app, Vega Virtual Device, or Apple TV / Android TV) using keyboard events.
 Use when you need to enter text or trigger a named key such as enter, escape, or arrow keys. On Vega and Apple TV / Android TV, prefer the remote tools for D-pad navigation; use keyboard to type into a focused text field (e.g. a search or login box).
-Returns { typed: string, keys: number }. Fails if an unsupported key name is provided or the device's input backend is not reachable.
-- text: types a string (supports uppercase, digits, common punctuation). To type a credential, use \`{{secret:<NAME>}}\` \u2014 resolved server-side from the \`ARGENT_SECRET_<NAME>\` env var or an argent secrets file (\`.argent/secrets.env\` in the project, \`~/.argent/secrets.env\`, or an \`ARGENT_SECRET_\`-prefixed key in the project's \`.env\`/\`.env.local\`), so the plaintext never enters agent context; the result echoes the placeholder, not the value, and the after-typing auto-screenshot is skipped.
+Returns { typed: string, keys: number }. Fails if text and key are both given in one call (rejected before anything is typed), if an unsupported key name is provided, or if the device's input backend is not reachable.
+A failure is not rolled back. An unsupported key name is always rejected before anything is sent. Un-typeable text is not: the iOS simulator and Chromium reject it mid-string and leave the characters before it in the field (Android, Vega and TV targets check the whole string up front). A transport failure partway also leaves the text already sent. On a retry, read the field's actual contents \u2014 do not assume it is unchanged.
+- text: types a string (supports uppercase, digits, common punctuation). To type a credential, use \`{{secret:<NAME>}}\` \u2014 resolved server-side from the \`ARGENT_SECRET_<NAME>\` env var or an argent secrets file (\`.argent/secrets.env\` in the project, \`~/.argent/secrets.env\`, or an \`ARGENT_SECRET_\`-prefixed key in the project's \`.env\`/\`.env.local\`), so the plaintext never enters agent context; the result echoes the placeholder, not the value, and the after-typing auto-screenshot is skipped. To submit after typing a secret, put both steps in ONE \`run-sequence\` \u2014 that keeps the skip covering the Enter, which a second bare \`keyboard\` call would not.
 - key: presses a single named key (enter, escape, backspace, tab, arrow-up/down/left/right, f1\u2013f12) \u2014 NOT supported on TV targets; move focus with \`tv-remote\` instead.
 On a TV target (runtimeKind 'tv') only \`text\` applies \u2014 focus a text field first (with \`tv-remote\`), then type into it (injected HID keyboard on Apple TV, \`adb input text\` on Android TV).
-Provide text, key, or both \u2014 when both are given, the text is typed first and the key is pressed after it (text + key:"enter" types and submits).`,
+One call does one action: pass text OR key, never both. To type and then press a key, send two \`keyboard\` steps in one \`run-sequence\` \u2014 { text: "hello" } then { key: "enter" } \u2014 which also keeps it to a single round-trip.`,
     zodSchema: zodSchema24,
     capability: capability16,
     searchHint: "type text keyboard input named key enter escape arrow tv vega fire tv search field hid leanback",
@@ -123241,6 +123244,46 @@ Provide text, key, or both \u2014 when both are given, the text is typed first a
     // 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.
+          //
+          // 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
+          // 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.' : ""),
+          {
+            error_code: FAILURE_CODES.KEYBOARD_TEXT_AND_KEY_COMBINED,
+            failure_stage: "keyboard_text_and_key_combined"
+          }
+        );
+      }
+      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.
+          "`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.
+            error_code: FAILURE_CODES.KEYBOARD_KEY_UNSUPPORTED,
+            failure_stage: "keyboard_named_key_empty",
+            error_kind: "unsupported"
+          }
+        );
+      }
       if (params.text === void 0) return dispatch(services, params, options);
       const { text, secrets } = resolveSecretPlaceholders(params.text);
       if (secrets.length === 0) return dispatch(services, params, options);
@@ -123300,10 +123343,211 @@ var shakeZodSchema = external_exports.object({
 });
 
 // ../tool-server/src/tools/shake/platforms/ios.ts
-var import_node_child_process26 = require("node:child_process");
+var import_node_child_process27 = require("node:child_process");
 var import_node_util20 = require("node:util");
 init_src();
-var execFileAsync20 = (0, import_node_util20.promisify)(import_node_child_process26.execFile);
+
+// ../tool-server/src/utils/window-shake.ts
+var import_node_child_process26 = require("node:child_process");
+var MICROINTERACTIONS_FLAG = "microinteractions";
+var AMPLITUDE = 22;
+var STEPS = 60;
+var OSASCRIPT_TIMEOUT_MS = 5e3;
+var ORIGIN_MARKER = "ARGENT_WINDOW_ORIGIN:";
+function warn(detail) {
+  process.stderr.write(`[shake:window] skipped the window animation: ${detail}
+`);
+}
+function asStringLiteral(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function titleMatchLookup(procNamesExpr, needles) {
+  return `
+	set win to missing value
+	set needles to {${needles.map(asStringLiteral).join(", ")}}
+	set procNames to ${procNamesExpr}
+	repeat with procRef in procNames
+		set procName to contents of procRef
+		set winTitles to {}
+		try
+			tell process procName to set winTitles to name of every window
+		end try
+		repeat with idx from 1 to (count of winTitles)
+			set winTitle to item idx of winTitles
+			-- A GUI app can carry an unnamed helper window alongside the real one.
+			if winTitle is not missing value then
+				repeat with needle in needles
+					if winTitle contains (contents of needle) then
+						set win to window idx of process procName
+						exit repeat
+					end if
+				end repeat
+			end if
+			if win is not missing value then exit repeat
+		end repeat
+		if win is not missing value then exit repeat
+	end repeat`;
+}
+function windowLookup(needles) {
+  if (needles.length === 0) {
+    return `
+	set win to missing value
+	repeat with procRef in {"Simulator", "Device Hub"}
+		-- A repeat variable is a reference into the list and "process <ref>"
+		-- will not coerce one, so without "contents of" the lookup misses.
+		set procName to contents of procRef
+		if exists (process procName) then
+			tell process procName
+				if (count of windows) > 0 then set win to window 1
+			end tell
+		end if
+		if win is not missing value then exit repeat
+	end repeat`;
+  }
+  return titleMatchLookup(
+    `name of every process whose name is "Simulator" or name is "Device Hub"`,
+    needles
+  );
+}
+var WOBBLE_OFFSETS = Array.from(
+  { length: STEPS + 1 },
+  (_, i) => {
+    const t = i / STEPS;
+    const decay = Math.exp(-4 * t);
+    const phase = 2 * Math.PI * 3.5 * t;
+    return [
+      Math.round(AMPLITUDE * decay * Math.sin(phase)),
+      Math.round(AMPLITUDE / 3 * decay * Math.sin(2 * phase))
+    ];
+  }
+);
+var OFFSETS_LITERAL = WOBBLE_OFFSETS.map(([dx, dy]) => `{${dx}, ${dy}}`).join(", ");
+function animationScript(needles) {
+  return `on run
+	tell application "System Events"${windowLookup(needles)}
+		if win is missing value then error "no matching window"
+		set origin to position of win
+		set ox to item 1 of origin
+		set oy to item 2 of origin
+		log "${ORIGIN_MARKER}" & ox & "," & oy
+
+		set offsets to {${OFFSETS_LITERAL}}
+		repeat with pair in offsets
+			set position of win to {ox + (item 1 of pair), oy + (item 2 of pair)}
+		end repeat
+
+		set position of win to {ox, oy}
+		delay 0.05
+		set position of win to {ox, oy}
+	end tell
+end run
+`;
+}
+function restoreScript(needles, ox, oy) {
+  return `on run
+	tell application "System Events"${windowLookup(needles)}
+		if win is missing value then error "no matching window"
+		set position of win to {${ox}, ${oy}}
+	end tell
+end run
+`;
+}
+function runOsascript(script) {
+  return new Promise((resolve11, reject) => {
+    const child = (0, import_node_child_process26.execFile)(
+      "/usr/bin/osascript",
+      ["-"],
+      { timeout: OSASCRIPT_TIMEOUT_MS },
+      (err, _stdout, stderr) => {
+        if (err) {
+          const raw = String(stderr ?? "");
+          const detail = raw.split("\n").filter((line) => !line.includes(ORIGIN_MARKER)).join("\n").trim() || err.message || "osascript failed";
+          const failure = new Error(detail);
+          failure.wasKilled = Boolean(
+            err.killed || err.signal
+          );
+          failure.rawStderr = raw;
+          reject(failure);
+          return;
+        }
+        resolve11();
+      }
+    );
+    child.on("error", (err) => reject(err));
+    child.stdin?.on("error", () => {
+    });
+    child.stdin?.end(script);
+  });
+}
+async function restoreOriginAfterKill(needles, rawStderr) {
+  const match = rawStderr.match(new RegExp(`${ORIGIN_MARKER}\\s*(-?\\d+)\\s*,\\s*(-?\\d+)`));
+  if (!match) return;
+  try {
+    await runOsascript(restoreScript(needles, Number(match[1]), Number(match[2])));
+  } catch {
+  }
+}
+async function prepareHostWindowShake(target) {
+  const inert = { begin: () => {
+  }, settle: () => Promise.resolve() };
+  try {
+    if (!isFeatureEnabled(MICROINTERACTIONS_FLAG)) return inert;
+    if (process.platform !== "darwin") return inert;
+    if (iosHeadlessFromEnv()) return inert;
+    let deviceSet = null;
+    try {
+      deviceSet = await deviceSetForUdid(target.udid);
+    } catch {
+    }
+    if (deviceSet !== null) return inert;
+    const needles = target.name ? [target.name] : [];
+    const script = animationScript(needles);
+    let inFlight = null;
+    let dead = false;
+    let warned2 = false;
+    const warnOnce = (detail) => {
+      if (warned2) return;
+      warned2 = true;
+      warn(detail);
+    };
+    return {
+      begin() {
+        if (dead || inFlight !== null) return;
+        let run2;
+        try {
+          run2 = runOsascript(script);
+        } catch (err) {
+          dead = true;
+          warnOnce(err instanceof Error ? err.message : String(err));
+          return;
+        }
+        inFlight = run2.then(
+          () => {
+            inFlight = null;
+          },
+          async (err) => {
+            dead = true;
+            const failure = err;
+            if (failure.wasKilled && typeof failure.rawStderr === "string") {
+              await restoreOriginAfterKill(needles, failure.rawStderr);
+            }
+            warnOnce(err instanceof Error ? err.message : String(err));
+            inFlight = null;
+          }
+        );
+      },
+      settle() {
+        return inFlight ?? Promise.resolve();
+      }
+    };
+  } catch (err) {
+    warn(err instanceof Error ? err.message : String(err));
+    return inert;
+  }
+}
+
+// ../tool-server/src/tools/shake/platforms/ios.ts
+var execFileAsync20 = (0, import_node_util20.promisify)(import_node_child_process27.execFile);
 var SHAKE_NOTIFICATION = "com.apple.UIKit.SimulatorShake";
 var SHAKE_INTERVAL_MS = 400;
 var sleep10 = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -123339,8 +123583,10 @@ var iosImpl4 = {
     const count2 = params.count ?? 1;
     if (await isTvOsSimulator(udid)) rejectTv("shake", device);
     const args = await simctlArgsForUdid(udid, ["spawn", udid, ...NOTIFYUTIL_ARGV]);
+    const shaker = await prepareHostWindowShake({ kind: "ios", udid, name: device.name });
     for (let i = 0; i < count2; i++) {
       if (i > 0) await sleep10(SHAKE_INTERVAL_MS);
+      shaker.begin();
       try {
         await execFileAsync20("xcrun", args, { timeout: 15e3 });
       } catch (err) {
@@ -123348,6 +123594,7 @@ var iosImpl4 = {
         throw shakeFailure(udid, error52.message, error52);
       }
     }
+    await shaker.settle();
     return { shaken: true, count: count2 };
   }
 };
@@ -130065,7 +130312,8 @@ function createRunSequenceTool(registry2) {
 Use when you need sequential actions and do NOT need to observe the screen between them
 (e.g. scrolling multiple times, typing then pressing enter, rotating back and forth).
 Returns { completed, total, steps } with per-step results. Fails if an unrecognised tool name is used in a step (error returned at that step, execution stops).
-No screenshot is captured automatically \u2014 call screenshot separately after the sequence if needed.
+One screenshot is captured automatically after the whole sequence (not per step) \u2014 call screenshot separately only for a baseline BEFORE it, or to observe an intermediate step.
+That single capture is also why a secret belongs in this call rather than in two bare ones: the skip is decided from the whole request, so a \`{{secret:...}}\` in any step suppresses the capture that would otherwise follow the submit.
 
 ONLY use this when every step is known in advance. If any step depends on the
 result of a previous one (e.g. tapping a menu item that only appears after
@@ -130081,7 +130329,7 @@ Allowed tools and their args (udid is auto-injected, do NOT include it in args):
   gesture-pinch:  { centerX: number, centerY: number, startDistance: number, endDistance: number, endCenterX?: number, endCenterY?: number, angle?: number, durationMs?: number }  [ios/android]
   gesture-rotate: { centerX: number, centerY: number, radius?: number, radiusX?: number, radiusY?: number, startAngle: number, endAngle: number, durationMs?: number }  [ios/android]
   button:         { button: "home"|"back"|"power"|"volumeUp"|"volumeDown"|"appSwitch"|"actionButton" }                  [ios/android]
-  keyboard:       { text?: string, key?: string, delayMs?: number }  (key pressed after text; TV: text only)            [ios/android/chromium/vega/tv]
+  keyboard:       { text?: string, key?: string, delayMs?: number }  (text OR key per step, never both; TV: text only)  [ios/android/chromium/vega/tv]
                   text supports {{secret:<NAME>}} placeholders, resolved server-side from ARGENT_SECRET_<NAME> env vars or an argent secrets file \u2014 credentials never enter agent context
   rotate:         { orientation: "Portrait"|"LandscapeLeft"|"LandscapeRight"|"PortraitUpsideDown" }                     [ios/android]
   shake:          { count?: number }                                                                                    [ios sim/android emu]
@@ -130096,9 +130344,10 @@ Example \u2014 scroll down three times (use gesture-scroll with positive deltaY
     { "tool": "gesture-swipe", "args": { "fromX": 0.5, "fromY": 0.7, "toX": 0.5, "toY": 0.3 } }
   ]}
 
-Example \u2014 type text and submit (one step: the key is pressed after the text is typed):
+Example \u2014 type text and submit (two keyboard steps; one call cannot carry both):
   { "udid": "<UDID>", "steps": [
-    { "tool": "keyboard", "args": { "text": "hello world", "key": "enter" } }
+    { "tool": "keyboard", "args": { "text": "hello world" } },
+    { "tool": "keyboard", "args": { "key": "enter" } }
   ]}
 
 Example \u2014 TV: move focus right twice then activate (one tv-remote step with a path is cheaper):
@@ -133798,89 +134047,130 @@ var ARGENT_PROFILER_PREFIX = "__argent_";
 function isArgentProfilerFunction(name) {
   return name.startsWith(ARGENT_PROFILER_PREFIX);
 }
-function buildCpuSampleIndex(cpuProfile, firstCommitTimestampMs) {
+function buildCpuSampleIndex(cpuProfile) {
   const { nodes, samples, timeDeltas, startTime, endTime } = cpuProfile;
   const nodeMap = /* @__PURE__ */ new Map();
   for (const node of nodes) {
     nodeMap.set(node.id, node);
   }
-  const cpuStartMs = startTime / 1e3;
-  let clockOffsetMs = 0;
-  if (firstCommitTimestampMs !== null && firstCommitTimestampMs > 0) {
-    const diff = firstCommitTimestampMs - cpuStartMs;
-    if (Math.abs(diff) > 1e3) {
-      clockOffsetMs = diff;
-    }
-  }
   const timestampsMs = new Float64Array(samples.length);
-  let accumulatedUs = startTime;
+  const intervalStartsMs = new Float64Array(samples.length);
+  let accumulatedUs = 0;
   for (let i = 0; i < samples.length; i++) {
-    accumulatedUs += timeDeltas[i] ?? 0;
-    timestampsMs[i] = accumulatedUs / 1e3 + clockOffsetMs;
+    const raw = timeDeltas[i];
+    const delta = Number.isFinite(raw) && (raw ?? 0) >= 0 ? raw : 0;
+    intervalStartsMs[i] = accumulatedUs / 1e3;
+    accumulatedUs += delta;
+    timestampsMs[i] = accumulatedUs / 1e3;
   }
   return {
+    childToParent: buildChildToParent(nodeMap),
     timestampsMs,
+    intervalStartsMs,
     sampleNodeIds: samples,
     nodeMap,
     durationMs: (endTime - startTime) / 1e3
   };
 }
+var IDLE_FRAME_NAMES = /* @__PURE__ */ new Set(["(idle)", "(program)", "(root)", "[idle]", "[root]"]);
+function isIdleFrame(name) {
+  return !name || IDLE_FRAME_NAMES.has(name);
+}
 function queryCpuWindow(index, startMs, endMs, topN2 = 5) {
-  const { timestampsMs, sampleNodeIds, nodeMap } = index;
+  const { timestampsMs, intervalStartsMs, sampleNodeIds, nodeMap } = index;
+  const n = timestampsMs.length;
+  const sampleRangeMs = {
+    start: n > 0 ? intervalStartsMs[0] : 0,
+    end: n > 0 ? timestampsMs[n - 1] : 0
+  };
+  const empty2 = {
+    hotspots: [],
+    samplesInWindow: 0,
+    coveredMs: 0,
+    idleMs: 0,
+    sampleRangeMs,
+    medianIntervalMs: 0,
+    maxIntervalMs: 0
+  };
+  if (n === 0) return empty2;
   let lo = 0;
-  let hi = timestampsMs.length;
+  let hi = n;
   while (lo < hi) {
     const mid = lo + hi >>> 1;
     if (timestampsMs[mid] < startMs) lo = mid + 1;
     else hi = mid;
   }
-  const selfHits = /* @__PURE__ */ new Map();
-  let totalSamples = 0;
-  for (let i = lo; i < timestampsMs.length; i++) {
-    if (timestampsMs[i] > endMs) break;
+  const selfMsByNode = /* @__PURE__ */ new Map();
+  const intervals = [];
+  let samplesInWindow = 0;
+  let coveredMs = 0;
+  let idleMs = 0;
+  let maxIntervalMs = 0;
+  for (let i = lo; i < n; i++) {
+    const from2 = intervalStartsMs[i];
+    if (from2 > endMs) break;
+    const overlap = Math.min(endMs, timestampsMs[i]) - Math.max(startMs, from2);
+    if (overlap <= 0) continue;
+    samplesInWindow++;
+    coveredMs += overlap;
+    intervals.push(timestampsMs[i] - from2);
+    if (timestampsMs[i] - from2 > maxIntervalMs) maxIntervalMs = timestampsMs[i] - from2;
     const nodeId = sampleNodeIds[i];
-    selfHits.set(nodeId, (selfHits.get(nodeId) ?? 0) + 1);
-    totalSamples++;
-  }
-  if (totalSamples === 0) return [];
-  const windowDurationMs = endMs - startMs;
-  const avgIntervalMs = totalSamples > 1 ? windowDurationMs / totalSamples : 1;
-  const childToParent = /* @__PURE__ */ new Map();
-  for (const node of nodeMap.values()) {
-    for (const childId of node.children ?? []) {
-      childToParent.set(childId, node.id);
+    const node = nodeMap.get(nodeId);
+    if (isIdleFrame(node?.callFrame.functionName)) {
+      idleMs += overlap;
+      continue;
     }
+    selfMsByNode.set(nodeId, (selfMsByNode.get(nodeId) ?? 0) + overlap);
   }
-  const totalHits = /* @__PURE__ */ new Map();
-  for (const [nodeId, hits] of selfHits) {
-    totalHits.set(nodeId, (totalHits.get(nodeId) ?? 0) + hits);
+  if (samplesInWindow === 0) return { ...empty2, sampleRangeMs };
+  intervals.sort((a, b) => a - b);
+  const medianIntervalMs = intervals[Math.floor(intervals.length / 2)] ?? 0;
+  const childToParent = index.childToParent ?? buildChildToParent(nodeMap);
+  const totalMsByNode = /* @__PURE__ */ new Map();
+  for (const [nodeId, ms] of selfMsByNode) {
+    totalMsByNode.set(nodeId, (totalMsByNode.get(nodeId) ?? 0) + ms);
     let current = nodeId;
+    const seen = /* @__PURE__ */ new Set([current]);
     while (childToParent.has(current)) {
       const parent = childToParent.get(current);
-      totalHits.set(parent, (totalHits.get(parent) ?? 0) + hits);
+      if (seen.has(parent)) break;
+      seen.add(parent);
+      totalMsByNode.set(parent, (totalMsByNode.get(parent) ?? 0) + ms);
       current = parent;
     }
   }
   const entries = [];
-  for (const [nodeId, hits] of selfHits) {
+  for (const [nodeId, ms] of selfMsByNode) {
     const node = nodeMap.get(nodeId);
     if (!node) continue;
     const name = node.callFrame.functionName;
-    if (!name || name === "(idle)" || name === "(program)" || name === "(root)" || name === "[idle]" || name === "[root]")
-      continue;
     if (isArgentProfilerFunction(name)) continue;
-    const selfMs = Math.round(hits * avgIntervalMs * 100) / 100;
-    const totalMs = Math.round((totalHits.get(nodeId) ?? hits) * avgIntervalMs * 100) / 100;
     entries.push({
       name,
-      selfMs,
-      totalMs,
+      selfMs: Math.round(ms * 100) / 100,
+      totalMs: Math.round((totalMsByNode.get(nodeId) ?? ms) * 100) / 100,
       url: node.callFrame.url || void 0,
       lineNumber: node.callFrame.lineNumber >= 0 ? node.callFrame.lineNumber : void 0
     });
   }
   entries.sort((a, b) => b.selfMs - a.selfMs);
-  return entries.slice(0, topN2);
+  return {
+    hotspots: entries.slice(0, topN2),
+    samplesInWindow,
+    coveredMs,
+    idleMs,
+    sampleRangeMs,
+    medianIntervalMs,
+    maxIntervalMs
+  };
+}
+function buildChildToParent(nodeMap) {
+  const childToParent = /* @__PURE__ */ new Map();
+  for (const node of nodeMap.values()) {
+    for (const childId of node.children ?? []) childToParent.set(childId, node.id);
+  }
+  return childToParent;
 }
 function correlateCpuWithCommits(summaries, index, topNPerCommit = 5) {
   if (!index) return summaries;
@@ -133888,28 +134178,35 @@ function correlateCpuWithCommits(summaries, index, topNPerCommit = 5) {
     if (summary.isMargin) return summary;
     const startMs = summary.timestampMs;
     const endMs = summary.timestampMs + summary.totalRenderMs;
-    const hotspots = queryCpuWindow(index, startMs, endMs, topNPerCommit);
+    const { hotspots } = queryCpuWindow(index, startMs, endMs, topNPerCommit);
     if (hotspots.length === 0) return summary;
     return { ...summary, cpuHotspots: hotspots };
   });
 }
 function serializeCpuSampleIndex(index) {
   return {
+    version: 2,
     timestampsMs: Array.from(index.timestampsMs),
+    intervalStartsMs: Array.from(index.intervalStartsMs),
     sampleNodeIds: index.sampleNodeIds,
     nodes: [...index.nodeMap.values()],
     durationMs: index.durationMs
   };
 }
 function deserializeCpuSampleIndex(raw) {
+  if (raw?.version !== 2 || !Array.isArray(raw.timestampsMs) || !Array.isArray(raw.nodes)) {
+    throw new Error("unsupported CPU sample index format");
+  }
   const nodeMap = /* @__PURE__ */ new Map();
   for (const node of raw.nodes) {
     nodeMap.set(node.id, node);
   }
   return {
     timestampsMs: new Float64Array(raw.timestampsMs),
+    intervalStartsMs: new Float64Array(raw.intervalStartsMs ?? []),
     sampleNodeIds: raw.sampleNodeIds,
     nodeMap,
+    childToParent: buildChildToParent(nodeMap),
     durationMs: raw.durationMs
   };
 }
@@ -134212,8 +134509,7 @@ async function runPipeline(input, options) {
     hotCommitIndices,
     input.sessionMeta.unattributedByCommit
   );
-  const firstCommitTs = preprocessed.length > 0 ? preprocessed[0].timestamp : null;
-  const cpuSampleIndex = input.flamegraph ? buildCpuSampleIndex(input.flamegraph, firstCommitTs) : null;
+  const cpuSampleIndex = input.flamegraph ? buildCpuSampleIndex(input.flamegraph) : null;
   const hotCommitSummaries = correlateCpuWithCommits(rawHotCommitSummaries, cpuSampleIndex);
   const preprocessedCommitTree = { ...input.commitTree, commits: preprocessed };
   const reduceOutput = reduce(
@@ -140619,8 +140915,12 @@ init_zod();
 init_src();
 var import_fs18 = require("fs");
 var timeWindowSchema = external_exports.object({
-  start: external_exports.coerce.number().describe("Start of window in ms (performance.now clock)"),
-  end: external_exports.coerce.number().describe("End of window in ms (performance.now clock)")
+  start: external_exports.coerce.number().describe(
+    "Start of window in ms since profiling started \u2014 the same clock profiler-commit-query prints"
+  ),
+  end: external_exports.coerce.number().describe(
+    "End of window in ms since profiling started \u2014 the same clock profiler-commit-query prints"
+  )
 });
 var zodSchema53 = external_exports.object({
   port: external_exports.coerce.number().default(8081).describe("Metro server port"),
@@ -140630,7 +140930,9 @@ var zodSchema53 = external_exports.object({
   mode: external_exports.enum(["top_functions", "time_window", "call_tree", "component_cpu"]).describe(
     "Query mode: top_functions (global hotspots), time_window (CPU in a time range), call_tree (callers/callees of a function), component_cpu (CPU during a component's commits)"
   ),
-  time_window_ms: timeWindowSchema.optional().describe("Time window filter for time_window mode (ms, performance.now clock)"),
+  time_window_ms: timeWindowSchema.optional().describe(
+    "Time window filter for time_window mode (ms since profiling started \u2014 the same clock profiler-commit-query prints)"
+  ),
   component_name: external_exports.string().optional().describe("Component name for component_cpu mode"),
   function_name: external_exports.string().optional().describe("Function name for call_tree mode"),
   top_n: external_exports.coerce.number().int().positive().default(15).describe("Number of results to return (default 15)"),
@@ -140663,31 +140965,60 @@ async function getIndex(sessionPaths) {
   }
   const cpuProfile = await readCpuProfile(sessionPaths.cpuProfilePath);
   let commitTree = null;
-  let firstCommitTs = null;
   if (sessionPaths.commitsPath) {
     const onDisk = await readCommitTree(sessionPaths.commitsPath);
     commitTree = { commits: onDisk.commits };
-    firstCommitTs = onDisk.commits[0]?.timestamp ?? null;
   }
-  return { index: buildCpuSampleIndex(cpuProfile, firstCommitTs), commitTree };
+  return { index: buildCpuSampleIndex(cpuProfile), commitTree };
+}
+function explainEmptyWindow(res, startMs, endMs) {
+  const range = `${res.sampleRangeMs.start.toFixed(1)}\u2013${res.sampleRangeMs.end.toFixed(1)}ms`;
+  const window2 = `${startMs.toFixed(1)}\u2013${endMs.toFixed(1)}ms`;
+  if (res.sampleRangeMs.end === 0 && res.samplesInWindow === 0) {
+    return "_The CPU profile contains no samples. Sampling produced no data for this session \u2014 that is a capture failure, not a measurement of idleness._";
+  }
+  if (endMs < res.sampleRangeMs.start || startMs > res.sampleRangeMs.end) {
+    return `_No CPU samples exist in ${window2} \u2014 that is outside the recorded sample range (${range}). This is a coverage gap, not a measurement: nothing can be concluded about CPU cost here. Sample times are ms since profiling started, the same clock \`profiler-commit-query\` prints._`;
+  }
+  if (res.samplesInWindow > 0) {
+    return `_${res.samplesInWindow} sample(s) covering ${res.coveredMs.toFixed(1)}ms fell inside ${window2}, and all of them were idle \u2014 the JS thread was not executing during this window. Native or UI-thread work would not appear here; use \`native-profiler-start\` for that._`;
+  }
+  return `_No CPU samples fell inside ${window2} (${(endMs - startMs).toFixed(1)}ms wide), although it lies within the recorded range (${range}). The sampler runs roughly every ${res.medianIntervalMs > 0 ? res.medianIntervalMs.toFixed(1) : "13"}ms, so a window this narrow can contain none at all. **Absence of samples is not evidence that this commit was cheap.** Widen the window, or use \`mode=component_cpu\`._`;
+}
+function coverageNote(res, startMs, endMs) {
+  const widthMs = endMs - startMs;
+  const lines = [
+    `**Window:** ${startMs.toFixed(1)}ms \u2192 ${endMs.toFixed(1)}ms (${widthMs.toFixed(1)}ms)`,
+    `**Samples:** ${res.samplesInWindow} covering ${res.coveredMs.toFixed(1)}ms` + (res.idleMs > 0 ? `, of which ${res.idleMs.toFixed(1)}ms idle` : "") + ` \u2014 sampling interval ~${res.medianIntervalMs.toFixed(1)}ms. Self-times sum to sampled coverage, not to the window width.`
+  ];
+  if (widthMs > 0 && widthMs < 3 * res.medianIntervalMs) {
+    lines.push(
+      `> This window is narrower than ~3 sampling intervals, so every figure carries \xB11 sample (\u2248${res.medianIntervalMs.toFixed(1)}ms).`
+    );
+  }
+  if (res.maxIntervalMs > 50 && res.maxIntervalMs > 5 * res.medianIntervalMs) {
+    lines.push(
+      `> The sampler stalled for ${res.maxIntervalMs.toFixed(1)}ms inside this window; that whole gap is attributed to whichever function was caught by the sample that ended it.`
+    );
+  }
+  return lines.join("\n\n");
 }
 function renderTopFunctions(index, topN2, startMs, endMs) {
-  const windowStart = startMs ?? index.timestampsMs[0];
-  const windowEnd = endMs ?? index.timestampsMs[index.timestampsMs.length - 1];
-  const hotspots = queryCpuWindow(index, windowStart, windowEnd, topN2);
-  if (hotspots.length === 0) return "_No CPU hotspots found in the specified range._";
+  const windowStart = startMs ?? index.intervalStartsMs[0] ?? 0;
+  const windowEnd = endMs ?? index.timestampsMs[index.timestampsMs.length - 1] ?? 0;
+  const res = queryCpuWindow(index, windowStart, windowEnd, topN2);
+  if (res.hotspots.length === 0) return explainEmptyWindow(res, windowStart, windowEnd);
   const header = "| Function | Self (ms) | Total (ms) | Location |";
   const sep7 = "|---|---|---|---|";
-  const rows = hotspots.map((hs) => {
+  const rows = res.hotspots.map((hs) => {
     const loc = hs.url ? `${shortenUrl(hs.url)}${hs.lineNumber != null ? `:${hs.lineNumber}` : ""}` : "\u2014";
     return `| \`${hs.name}\` | ${hs.selfMs} | ${hs.totalMs} | ${loc} |`;
   });
-  const rangeNote = startMs != null ? `**Window:** ${startMs.toFixed(1)}ms \u2192 ${endMs.toFixed(1)}ms
-
-` : "";
   return `## CPU Hotspots
 
-${rangeNote}${header}
+${coverageNote(res, windowStart, windowEnd)}
+
+${header}
 ${sep7}
 ${rows.join("\n")}`;
 }
@@ -140817,7 +141148,7 @@ function renderComponentCpu(index, commitTree, componentName, topN2) {
   }
   const aggregated = /* @__PURE__ */ new Map();
   for (const window2 of commitWindows.values()) {
-    const hotspots = queryCpuWindow(index, window2.start, window2.end, 50);
+    const { hotspots } = queryCpuWindow(index, window2.start, window2.end, 50);
     for (const hs of hotspots) {
       const existing = aggregated.get(hs.name);
       if (existing) {
@@ -140871,6 +141202,10 @@ Requires react-profiler-stop (and ideally react-profiler-analyze) to have been c
 Modes:
 - top_functions: Global CPU hotspots ranked by self-time. Optional time_window_ms to filter.
 - time_window: CPU breakdown for a specific time range (e.g. during a slow commit or hang).
+
+Self-times are the summed sampling intervals of the samples that landed in the window, so they
+measure sampled coverage rather than the window's width and do not change if you widen the query.
+Every table states how many samples it covers and how much of that was idle.
 - call_tree: For a given function_name, show its callees and optionally callers.
 - component_cpu: For a given component_name, aggregate CPU activity across all its commits.
 Use when investigating JS CPU hotspots or correlating CPU cost with specific components.
@@ -140956,8 +141291,12 @@ Fails if no CPU profile is stored \u2014 run react-profiler-stop first.`,
 init_zod();
 init_src();
 var timeRangeSchema = external_exports.object({
-  start: external_exports.coerce.number().describe("Start of range in ms (performance.now clock)"),
-  end: external_exports.coerce.number().describe("End of range in ms (performance.now clock)")
+  start: external_exports.coerce.number().describe(
+    "Start of range in ms since profiling started \u2014 the same clock profiler-commit-query prints"
+  ),
+  end: external_exports.coerce.number().describe(
+    "End of range in ms since profiling started \u2014 the same clock profiler-commit-query prints"
+  )
 });
 var zodSchema54 = external_exports.object({
   port: external_exports.coerce.number().default(8081).describe("Metro server port"),
@@ -142643,7 +142982,7 @@ Returns { stopped } - the URNs of the services that were actually live and got s
 
 // ../tool-server/src/tools/simulator/stop-metro.ts
 init_zod();
-var import_node_child_process27 = require("node:child_process");
+var import_node_child_process28 = require("node:child_process");
 function parseNetstatListeningPids(netstatOutput, port) {
   const pids = /* @__PURE__ */ new Set();
   for (const line of netstatOutput.split(/\r?\n/)) {
@@ -142659,7 +142998,7 @@ function parseNetstatListeningPids(netstatOutput, port) {
 }
 function listeningPids(port) {
   if (process.platform === "win32") {
-    const output2 = (0, import_node_child_process27.execFileSync)("netstat", ["-ano"], {
+    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
@@ -142669,7 +143008,7 @@ function listeningPids(port) {
     });
     return parseNetstatListeningPids(output2, port);
   }
-  const output = (0, import_node_child_process27.execFileSync)("lsof", ["-ti", `tcp:${port}`, "-sTCP:LISTEN"], {
+  const output = (0, import_node_child_process28.execFileSync)("lsof", ["-ti", `tcp:${port}`, "-sTCP:LISTEN"], {
     encoding: "utf-8",
     timeout: 5e3
   }).trim();
@@ -148670,10 +149009,10 @@ async function runSnapshot(env, opts) {
 }
 
 // ../tool-server/src/utils/status-bar.ts
-var import_node_child_process28 = require("node:child_process");
+var import_node_child_process29 = require("node:child_process");
 var import_node_util21 = require("node:util");
 init_adb();
-var execFileAsync23 = (0, import_node_util21.promisify)(import_node_child_process28.execFile);
+var execFileAsync23 = (0, import_node_util21.promisify)(import_node_child_process29.execFile);
 var DEMO_BROADCAST = "am broadcast -a com.android.systemui.demo";
 async function pinStatusBar(device) {
   try {
@@ -150025,7 +150364,7 @@ init_zod();
 // ../tool-server/src/utils/workspace-reader.ts
 var import_promises12 = require("node:fs/promises");
 var import_node_path21 = require("node:path");
-var import_node_child_process29 = require("node:child_process");
+var import_node_child_process30 = require("node:child_process");
 var import_dotenv2 = __toESM(require_main());
 async function exists(path40) {
   try {
@@ -150069,7 +150408,7 @@ async function listDir(path40) {
 var COMMAND_TIMEOUT_MS = 3e3;
 function runVersionCommand(cmd, args, cwd) {
   return new Promise((resolve11) => {
-    const child = (0, import_node_child_process29.execFile)(cmd, args, { cwd, timeout: COMMAND_TIMEOUT_MS }, (err, stdout) => {
+    const child = (0, import_node_child_process30.execFile)(cmd, args, { cwd, timeout: COMMAND_TIMEOUT_MS }, (err, stdout) => {
       if (err) {
         resolve11(null);
         return;
@@ -150358,7 +150697,7 @@ Fails if the workspacePath is not an absolute path or the directory cannot be ac
 };
 
 // ../tool-server/src/tools/system/update-argent.ts
-var import_node_child_process30 = require("node:child_process");
+var import_node_child_process31 = require("node:child_process");
 var fs51 = __toESM(require("node:fs"));
 var path36 = __toESM(require("node:path"));
 init_zod();
@@ -150493,7 +150832,7 @@ var updateArgentTool = {
       if (spawnRoot) updateArgs.push("--project-root", spawnRoot);
       const cmd = cliEntry ? process.execPath : "argent";
       const args = cliEntry ? [cliEntry, ...updateArgs] : updateArgs;
-      const child = (0, import_node_child_process30.spawn)(cmd, args, {
+      const child = (0, import_node_child_process31.spawn)(cmd, args, {
         detached: true,
         stdio: "ignore",
         env: { ...process.env, ARGENT_UPDATE_TRIGGER: "mcp_update" }
@@ -150633,6 +150972,14 @@ async function resolveOutputDir(params, options) {
   if (params.outputDir && (probe3 === void 0 || probe3.presentOnHost)) {
     return params.outputDir;
   }
+  if (params.outputDir) {
+    try {
+      await import_promises13.default.mkdir(params.outputDir);
+      return params.outputDir;
+    } catch (err) {
+      if (err.code === "EEXIST") return params.outputDir;
+    }
+  }
   const dir = import_path10.default.join(
     import_node_os13.default.tmpdir(),
     "argent-screenshot-diff",
@@ -151411,9 +151758,9 @@ function probeArgentToolServer(host, port, timeoutMs = 500) {
 
 // ../tool-server/src/utils/simulator-watcher.ts
 var fs53 = __toESM(require("node:fs"));
-var import_node_child_process31 = require("node:child_process");
+var import_node_child_process32 = require("node:child_process");
 var import_node_util22 = require("node:util");
-var execFileAsync24 = (0, import_node_util22.promisify)(import_node_child_process31.execFile);
+var execFileAsync24 = (0, import_node_util22.promisify)(import_node_child_process32.execFile);
 var POLL_INTERVAL_MS2 = 1e4;
 async function getBootedUdidsInSet(deviceSet) {
   const { stdout } = await execFileAsync24("xcrun", [
@@ -151489,7 +151836,7 @@ function startSimulatorWatcher(registry2) {
 }
 
 // ../tool-server/src/utils/preview-window.ts
-var import_node_child_process32 = require("node:child_process");
+var import_node_child_process33 = require("node:child_process");
 var fs54 = __toESM(require("node:fs"));
 var os14 = __toESM(require("node:os"));
 var path38 = __toESM(require("node:path"));
@@ -151521,10 +151868,10 @@ function ensureLensAppBundle(electronBin) {
     fs54.copyFileSync(path38.join(realContents, "Info.plist"), plist);
     const setPlist = (entry, value) => {
       try {
-        (0, import_node_child_process32.execFileSync)("/usr/libexec/PlistBuddy", ["-c", `Set :${entry} ${value}`, plist]);
+        (0, import_node_child_process33.execFileSync)("/usr/libexec/PlistBuddy", ["-c", `Set :${entry} ${value}`, plist]);
       } catch {
         try {
-          (0, import_node_child_process32.execFileSync)("/usr/libexec/PlistBuddy", ["-c", `Add :${entry} string ${value}`, plist]);
+          (0, import_node_child_process33.execFileSync)("/usr/libexec/PlistBuddy", ["-c", `Add :${entry} string ${value}`, plist]);
         } catch {
         }
       }
@@ -151583,7 +151930,7 @@ function createPreviewWindowManager(opts = {}) {
     const wrapperBin = ensureLensAppBundle(electronBin);
     const launchBin = wrapperBin ?? electronBin;
     const launchArgs = wrapperBin ? ["--no-sandbox", mainScript] : [mainScript];
-    const next = (0, import_node_child_process32.spawn)(launchBin, launchArgs, {
+    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