@mmerterden/multi-agent-toolkit-mcp 3.7.1 → 3.9.0

package/CHANGELOG.md

@@ -15,6 +15,112 @@ Releases before this file exists are recorded in the git tags and commit history
 
 ---
 
+## 3.9.0
+
+### Changed
+
+- **Inline screenshots are compact.** `ios_screenshot` and `android_screenshot`
+  without `path` returned the raw PNG as base64: on a 3x simulator that is
+  2.9 MB per capture, 3.86 million characters on the wire, and the model reads
+  every one of them. That was the sluggishness people felt in an agent loop,
+  not the capture itself (0.5 s). The inline result is now an 800 px JPEG at
+  quality 80 (63 KB, 84 K characters), resized through `sips` in 0.1 s; the
+  full-resolution PNG still lands on disk and its path is in the text. New
+  optional inputs `max_width`, `format` and `quality` are the escape hatch
+  (`format: "png"` with `max_width: 0` returns the original bytes). `path`
+  behaviour is unchanged: full-resolution PNG, nothing inline, which is what
+  design-check and visual diff read.
+- **The UI-tree dumper runs compiled.** `swift ui-tree-dumper.swift` was
+  re-interpreted on every call, about a second each. It is now compiled once
+  with `swiftc -O` into the user cache, keyed by the source hash and the
+  toolchain version, and runs in 55 ms. No `swiftc`, or a failed compile, falls
+  back to the interpreted script and stays there for the process lifetime.
+  `ios_get_ui_tree`, `ios_accessibility_audit` and `design_ui_geometry` share
+  the path.
+
+### Note
+
+The README gained a Performance section: read the tree before taking a
+picture, batch a scripted sequence through `agent_run_steps`, write bulk
+captures to files and look only at the ones that changed. The pipeline's
+`/multi-agent:test` flow (16.19.0) now does exactly that.
+
+## 3.8.0
+
+### Added
+
+- **`ios_swipe` declares `duration_ms`.** The handler had read it since the
+  tool existed; the schema never said so, so no host ever offered it.
+- **Gate 9c and gate 14b.** 9c validates every probed tool's structured result
+  against its own declared `outputSchema` with ajv. 14b scans every shell
+  template for a `${args.x}` interpolation that no sanitizer wraps, the shape
+  gate 14 could not see because it only knew the double-quoted form.
+- **The work directory is pruned.** `.xcresult` bundles, build logs, push
+  payloads and audit dumps accumulated under the screenshot directory with
+  nothing to remove them. It now keeps the newest 200 entries for 7 days, the
+  offload directory's own rule, and never removes a path a caller was just
+  promised.
+
+### Fixed
+
+- **`agent_run_steps` skipped schema validation.** Batched steps went straight
+  to the handlers, so an enum or type guard that lived only in the schema was
+  void inside a batch. Every step is validated now and a failed validation is a
+  step error. `ios_get_app_container` also passes its `container` value through
+  `token()`, so the enum is not the only thing standing between an argument and
+  the shell.
+- **`android_type_text` and `android_open_url` were command injection on the
+  device.** `shq()` protected the host shell, and `adb shell` hands the string
+  to the device shell unquoted, where it is parsed again. Both are quoted twice
+  now; a test evaluates the composed argument through `/bin/sh` and checks the
+  original bytes come back.
+- **`android_meminfo mode=diff` always threw.** The snapshot emitted `pss_kb`
+  and the diff read `pss`, so the tool's own output was never a valid baseline.
+  The diff accepts both shapes.
+- **Three `outputSchema`s contradicted their payloads,** which a conforming
+  client rejects: audit findings carry `status: "info"`, `ios_visual_diff`
+  returns `diff_image: null` on a clean compare, `android_launch_time` returns
+  `cold_start: null` below Android 10. The schemas now allow what the handlers
+  emit, and gate 9c keeps them honest.
+- **`ios_app_store_audit` with an unknown rule id reported PASS** after running
+  nothing. Unknown ids are an error that lists the valid ones, and an empty
+  selection is never a pass.
+- **`ios_accessibility_audit_deep` and `ios_leaks` ran through `execSync`**
+  with the default 1 MB buffer, so a normal `xcodebuild test` log killed the
+  child and the tool blamed the build; the event loop was blocked for the whole
+  run. Both use the async spawn path with a 64 MB cap and a timeout.
+- **`android_apk_audit`'s `aapt2 || aapt` fallback never fired,** because a
+  failed `run()` returns a truthy error string; with aapt2 absent the report
+  said "Not debuggable - OK" and on Linux `apk_size` was `NaN MB` with status
+  pass. Failures are detected, the missing-tool branch is reachable, size comes
+  from `statSync`.
+- **Capture tools returned a stale file as a fresh capture.** `ios_screenshot`,
+  `android_screenshot` and `android_get_ui_tree` decided success by whether the
+  path existed, so a second run against a dropped device returned the previous
+  image with the real error replaced by a generic one. The subprocess result is
+  checked first and a pre-existing file is discarded before capturing.
+- **`ios_set_locale` reported success unconditionally.** Each of its three
+  steps is checked.
+- **`ios_xcodebuild action:"test"` used the generic simulator destination,**
+  which xcodebuild refuses for testing. Test defaults to the booted simulator
+  or fails with a clear message.
+- **`android_launch_time` and `android_launch_app` disagreed on `activity`.**
+  Both build the component the same way and describe the field identically.
+- **Pure-JS iOS tools were refused without Xcode.** `ios_visual_diff`,
+  `ios_list_crashes` and `ios_xcresult` need no xcrun and run on a Linux box.
+- **`design_report` leaked a Chromium on a failed PDF render.** The browser is
+  closed in `finally`.
+- **`ios_archive_audit` reported an unsigned bundle as signed,** because the
+  `codesign` failure text never reached the check; and its size used the
+  macOS-only `stat -f`.
+- **Smaller ones.** `ios_leaks` accepts a numeric-string pid and matches the
+  bundle id as a whole token instead of a regex prefix; the UI-tree dumper's
+  remedy text reaches the caller; `ensureBrowser` closes a half-launched browser
+  and honours a changed engine; `exportIpa` picks the export it just made rather
+  than the first `.ipa` in the directory, and the export options plist is
+  XML-escaped; `agent_run_steps` declares the `result` / `error` fields it
+  emits.
+
 ## 3.7.1
 
 ### Fixed

package/README.md

@@ -293,6 +293,13 @@ Mock-mode vs Figma design audit. Generic and platform-agnostic - the heavy orche
 - **App Store screenshots** - Clean status bar + automated navigation
 - **Regression testing** - Tap through flows, verify behavior
 
+### Performance
+
+- **Inline captures are small.** `ios_screenshot` / `android_screenshot` without `path` return an 800 px JPEG, about 60 KB instead of the ~3 MB full-resolution PNG a simulator produces (which is ~4 MB as base64 on every capture). `max_width`, `format` and `quality` tune it; `format: "png"` with `max_width: 0` returns the original bytes. The full-resolution PNG stays on disk, and `path` writes it where you say.
+- **The iOS UI-tree dumper is compiled once.** `ui-tree-dumper.swift` is built with `swiftc -O` on first use and cached per source and toolchain, so a call drops from ~1 s to ~0.05 s. Without `swiftc` it runs interpreted as before.
+- **Batch a scripted sequence.** `agent_run_steps` runs tap, type, wait and screenshot steps in one round trip instead of one call per step.
+- **Read the tree when text is enough.** `ios_get_ui_tree` / `android_get_ui_tree` cost a fraction of a screenshot and return tappable coordinates.
+
 ### How It Works
 
 ```mermaid

package/README.tr.md

@@ -292,6 +292,13 @@ Mock-mode vs Figma tasarım denetimi. Jenerik ve platform-bağımsız - ağır o
 - **App Store screenshot'ları** - Temiz status bar + otomatik navigasyon
 - **Regresyon testi** - Akışlarda tap'le gez, davranışı doğrula
 
+### Performans
+
+- **Inline capture'lar küçük.** `path` verilmeyen `ios_screenshot` / `android_screenshot` 800 px JPEG döner: simülatörün ürettiği ~3 MB tam çözünürlüklü PNG (her capture'da base64 olarak ~4 MB) yerine yaklaşık 60 KB. `max_width`, `format` ve `quality` ile ayarlanır; `format: "png"` + `max_width: 0` orijinal byte'ları döner. Tam çözünürlüklü PNG diskte kalır, `path` onu istediğin yere yazar.
+- **iOS UI-tree dumper bir kez derlenir.** `ui-tree-dumper.swift` ilk kullanımda `swiftc -O` ile derlenir, kaynak + toolchain başına önbelleğe alınır; bir çağrı ~1 s'den ~0.05 s'ye iner. `swiftc` yoksa eskisi gibi yorumlanarak çalışır.
+- **Senaryoyu tek çağrıda koş.** `agent_run_steps` tap, type, wait ve screenshot adımlarını adım başına bir çağrı yerine tek round trip'te çalıştırır.
+- **Metin yetiyorsa tree oku.** `ios_get_ui_tree` / `android_get_ui_tree` bir screenshot'ın çok küçük bir maliyetiyle tap'lenebilir koordinatlar döner.
+
 ### Nasıl Çalışır
 
 ```mermaid

package/index.js

@@ -16,9 +16,10 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { execSync, exec, spawn } from "child_process";
-import { writeFileSync, readFileSync, mkdirSync, existsSync, readdirSync, statSync } from "fs";
+import { writeFileSync, readFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSync, renameSync } from "fs";
 import { join, dirname, basename, isAbsolute, resolve, sep } from "path";
-import { homedir } from "os";
+import { homedir, tmpdir } from "os";
+import { createHash } from "crypto";
 import { fileURLToPath } from "url";
 import { runAudit as runAppStoreAudit } from "./tools/ios-app-store-audit/index.js";
 import {
@@ -37,11 +38,16 @@ import {
   offloadLargeText,
   queryOffloadedOutput,
   offloadedErrorSummary,
+  pruneWorkDir,
 } from "./tools/offload/index.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SCREENSHOT_DIR = join(process.env.TMPDIR || "/tmp", "mobile-dev-mcp");
 if (!existsSync(SCREENSHOT_DIR)) mkdirSync(SCREENSHOT_DIR, { recursive: true });
+// Same retention as the offload dir: this directory collects screenshots, UI
+// dumps, push payloads, build logs and .xcresult bundles, and nothing else
+// ever removed them.
+pruneWorkDir(SCREENSHOT_DIR);
 
 // ── Helpers ──
 
@@ -80,6 +86,27 @@ function run(cmd, opts = {}) {
   }
 }
 
+// run() reports failure by returning a truthy marker string, so `run(a) || run(b)`
+// never falls back. This variant returns null on failure for exactly that shape.
+function runOrNull(cmd, opts = {}) {
+  const out = run(cmd, opts);
+  return isFailure(out) ? null : out;
+}
+
+// A capture that must be fresh: a file left by an earlier run would otherwise
+// pass the existence check and be returned as this run's result.
+function discardStale(path) {
+  try { if (statSync(path).isFile()) unlinkSync(path); } catch {}
+}
+
+// The files a result promises to the caller; retention never removes them.
+function promisedPaths(result) {
+  if (!result || typeof result !== "object") return [];
+  if (result.type === "file") return result.files.map((f) => f.path);
+  if (result.type === "image") return [result.path, result.source].filter(Boolean);
+  return [];
+}
+
 /**
  * Run a command whose non-zero exit is a RESULT, not a failure.
  *
@@ -215,6 +242,64 @@ function shq(value) {
   return `'${String(value ?? "").replace(/'/g, "'\\''")}'`;
 }
 
+// `adb shell <cmd>` is parsed twice: once by the host shell, again by the
+// device shell. One shq() layer survives only the first, so the device shell
+// saw `;`, `&` and `$()` in a text or URL as syntax. The inner layer is what
+// the device shell receives.
+function remoteShq(value) {
+  return shq(shq(value));
+}
+
+// The ui-tree dumper prints its failure as a JSON object on stdout (with the
+// remedy) and exits 1; a plain exit-status error keeps only stderr.
+function dumperErrorOf(text) {
+  const s = String(text ?? "");
+  try {
+    const parsed = JSON.parse(s);
+    return parsed && typeof parsed.error === "string" ? parsed.error : null;
+  } catch {}
+  const m = s.match(/"error"\s*:\s*("(?:[^"\\]|\\.)*")/);
+  if (!m) return null;
+  try { return JSON.parse(m[1]); } catch { return null; }
+}
+
+const DUMPER_SOURCE = join(__dirname, "ui-tree-dumper.swift");
+
+// `swift <script>` re-parses and JITs the dumper on every call (0.9-1.2 s); the
+// -O binary answers in 0.05 s. Compiled on first use, never at server start,
+// and keyed by source + toolchain so an edit or an Xcode update rebuilds it.
+// The directory comes from the environment and the home directory only, never
+// from a tool argument, the same rule the offload dir follows.
+function dumperCacheDir() {
+  const xdg = process.env.XDG_CACHE_HOME;
+  const base = xdg && isAbsolute(xdg) ? xdg
+    : process.platform === "darwin" ? join(homedir(), "Library", "Caches")
+    : join(homedir(), ".cache");
+  for (const dir of [join(base, "multi-agent-toolkit-mcp"), join(tmpdir(), "multi-agent-toolkit-mcp")]) {
+    try { mkdirSync(dir, { recursive: true }); return dir; } catch {}
+  }
+  return null;
+}
+
+let dumperPrefix = null;
+function dumperCommand() {
+  if (dumperPrefix) return dumperPrefix;
+  dumperPrefix = `swift ${shq(DUMPER_SOURCE)}`;
+  const version = runOrNull("swiftc --version", { timeout: 15000 });
+  const dir = version ? dumperCacheDir() : null;
+  if (!dir) return dumperPrefix;
+  const key = createHash("sha256").update(readFileSync(DUMPER_SOURCE)).update(version).digest("hex").slice(0, 16);
+  const binary = join(dir, `ui-tree-dumper-${key}`);
+  if (!existsSync(binary)) {
+    const staging = `${binary}.${process.pid}`;
+    const built = run(`swiftc -O -o ${shq(staging)} ${shq(DUMPER_SOURCE)}`, { timeout: 120000 });
+    if (isFailure(built) || !existsSync(staging)) return dumperPrefix;
+    try { renameSync(staging, binary); } catch { return dumperPrefix; }
+  }
+  dumperPrefix = shq(binary);
+  return dumperPrefix;
+}
+
 // Numeric coordinates / scales: reject anything that is not a plain number so it
 // can be interpolated bare.
 function num(value, label) {
@@ -249,6 +334,39 @@ function hasCommand(cmd) {
 }
 
 const HAS_XCRUN = hasCommand("xcrun");
+const HAS_SIPS = hasCommand("sips");
+
+// The inline image goes to the model on every capture, and a simulator PNG is
+// ~2.9 MB (3.9 MB as base64). sips turns it into an 800 px JPEG of ~60 KB in
+// 0.12 s, so that is the default; the full-resolution file stays on disk.
+function captureOptions(args) {
+  const format = args.format === "png" ? "png" : "jpeg";
+  const maxWidth = num(args.max_width ?? 800, "max_width");
+  const quality = num(args.quality ?? 80, "quality");
+  if (!Number.isInteger(maxWidth) || maxWidth < 0) throw new Error(`Invalid max_width: ${args.max_width} (0 or a positive pixel count)`);
+  if (!Number.isInteger(quality) || quality < 1 || quality > 100) throw new Error(`Invalid quality: ${args.quality} (1-100)`);
+  return { format, maxWidth, quality };
+}
+
+function inlineCapture(f, { format, maxWidth, quality }) {
+  const asIs = (note) => ({ type: "image", data: readFileSync(f).toString("base64"), mimeType: "image/png", path: f, note });
+  if (format === "png" && maxWidth === 0) return asIs("");
+  if (!HAS_SIPS) return asIs(" (sips unavailable, full-resolution PNG returned)");
+  const out = f.replace(/\.png$/, "") + (format === "jpeg" ? ".jpg" : `_${maxWidth}.png`);
+  discardStale(out);
+  const scale = maxWidth ? ` -Z ${maxWidth}` : "";
+  const options = format === "jpeg" ? ` -s formatOptions ${quality}` : "";
+  const converted = run(`sips${scale} -s format ${format}${options} ${shq(f)} --out ${shq(out)}`);
+  if (isFailure(converted) || !existsSync(out)) return asIs(" (sips failed, full-resolution PNG returned)");
+  return {
+    type: "image",
+    data: readFileSync(out).toString("base64"),
+    mimeType: format === "jpeg" ? "image/jpeg" : "image/png",
+    path: out,
+    source: f,
+    note: ` (full-resolution PNG: ${f})`,
+  };
+}
 
 // idb (Facebook) is the real iOS Simulator UI driver - `simctl io` has NO tap/swipe/type
 // operation, so tap/swipe/type/geometry route through idb. Resolve its binary + set a PATH
@@ -325,9 +443,9 @@ function iosDevice(id) {
 const IOS_TOOLS = [
   { name: "ios_list_devices", description: "List all available iOS simulators and their state", inputSchema: { type: "object", properties: {} } },
   { name: "ios_boot_device", description: "Boot an iOS simulator by UDID or name", inputSchema: { type: "object", properties: { device: { type: "string", description: "Device UDID or name" } }, required: ["device"] } },
-  { name: "ios_screenshot", description: "Capture an iOS simulator screenshot. Returns a base64 PNG by default; pass `path` to write the file and return only its location, which is what a run taking many captures needs - a base64 image per capture exhausts the caller's context. Use when you need to see the screen, or to collect captures for a later comparison.", inputSchema: { type: "object", properties: { device_id: { type: "string" }, path: { type: "string", description: "Absolute file path to write the PNG to. The parent directory must already exist. Returns the path instead of the image." } } } },
+  { name: "ios_screenshot", description: "Capture an iOS simulator screenshot. Without `path` the image comes back inline, downscaled to 800 px on the longest side as a quality-80 JPEG (~60 KB instead of the ~3 MB full-resolution PNG, which is ~4 MB as base64 on every capture); `format: \"png\"` with `max_width: 0` returns the original PNG bytes. The full-resolution PNG stays on disk either way. Pass `path` to write the full-resolution PNG there and return only its location, which is what a run taking many captures needs - and what design-check and ios_visual_diff read. Use when you need to see the screen, or to collect captures for a later comparison.", inputSchema: { type: "object", properties: { device_id: { type: "string" }, path: { type: "string", description: "Absolute file path to write the PNG to. The parent directory must already exist. Returns the path instead of the image." }, max_width: { type: "integer", description: "Longest side of the inline image in pixels (default 800). 0 keeps the original size. Ignored with `path`." }, format: { type: "string", enum: ["jpeg", "png"], description: "Inline image format (default jpeg). Ignored with `path`." }, quality: { type: "integer", description: "JPEG quality 1-100 (default 80). Ignored for png and with `path`." } } } },
   { name: "ios_tap", description: "Tap at coordinates on iOS simulator", inputSchema: { type: "object", properties: { x: { type: "number" }, y: { type: "number" }, device_id: { type: "string" } }, required: ["x", "y"] } },
-  { name: "ios_swipe", description: "Swipe on iOS simulator", inputSchema: { type: "object", properties: { x1: { type: "number" }, y1: { type: "number" }, x2: { type: "number" }, y2: { type: "number" }, device_id: { type: "string" } }, required: ["x1", "y1", "x2", "y2"] } },
+  { name: "ios_swipe", description: "Swipe on iOS simulator", inputSchema: { type: "object", properties: { x1: { type: "number" }, y1: { type: "number" }, x2: { type: "number" }, y2: { type: "number" }, duration_ms: { type: "number", description: "Swipe duration in milliseconds" }, device_id: { type: "string" } }, required: ["x1", "y1", "x2", "y2"] } },
   { name: "ios_type_text", description: "Type text on iOS simulator", inputSchema: { type: "object", properties: { text: { type: "string" }, device_id: { type: "string" } }, required: ["text"] } },
   { name: "ios_launch_app", description: "Launch iOS app by bundle ID", inputSchema: { type: "object", properties: { bundle_id: { type: "string" }, device_id: { type: "string" } }, required: ["bundle_id"] } },
   { name: "ios_terminate_app", description: "Terminate iOS app", inputSchema: { type: "object", properties: { bundle_id: { type: "string" }, device_id: { type: "string" } }, required: ["bundle_id"] } },
@@ -357,7 +475,7 @@ const IOS_TOOLS = [
   { name: "ios_export_ipa", description: "Export a .xcarchive to a signed .ipa via xcodebuild -exportArchive. Generates the exportOptions.plist from the arguments (method defaults to app-store-connect), so callers do not have to hand-maintain one. Returns the .ipa path plus parsed errors; a run that exits 0 without producing an .ipa is reported as a failure. Pair with ios_testflight_validate for the pre-submission gate.", inputSchema: { type: "object", properties: { archive_path: { type: "string", description: "Absolute path to the .xcarchive" }, output_dir: { type: "string", description: "Directory to write the .ipa into" }, method: { type: "string", description: "Export method: app-store-connect (default) | release-testing | enterprise | development" }, team_id: { type: "string", description: "Apple Developer team ID" }, provisioning_profiles: { type: "object", description: "Map of bundleId -> provisioning profile name (manual signing)" }, signing_style: { type: "string", description: "automatic | manual" }, upload_symbols: { type: "boolean", description: "Include symbols (default true)" }, allow_provisioning_updates: { type: "boolean", description: "Off by default. Lets xcodebuild register devices and create/modify provisioning profiles in the developer account - a change on Apple's side, so it is opt-in" }, timeout_sec: { type: "number", description: "Default 900" } }, required: ["archive_path", "output_dir"] } },
   { name: "ios_testflight_validate", description: "Run Apple's own pre-submission validation on an .ipa via `xcrun altool --validate-app`, then map returned ITMS error codes onto the App Store rule each one implies. This is the authoritative gate: unlike the static ios_app_store_audit it can catch an unregistered bundle ID, a profile that does not match the App Store Connect app record, a version+build pair already used, and entitlements not provisioned for the app ID. Auth is a 3-tier chain: ASC API key (api_key_id + api_issuer_id), else Apple ID + app-specific password referenced indirectly through a keychain item or env var (never passed by value), else the gate returns verdict SKIPPED with a reason. SKIPPED is not a pass - it means Apple was never asked. Set list_providers=true for a pre-flight that reports which teams the credentials can deliver for (needed when a corporate Apple ID belongs to several).", inputSchema: { type: "object", properties: { ipa_path: { type: "string", description: "Absolute path to the .ipa" }, platform: { type: "string", description: "ios (default) | appletvos | visionos | macos" }, api_key_id: { type: "string", description: "App Store Connect API key ID (tier 1)" }, api_issuer_id: { type: "string", description: "App Store Connect issuer ID (tier 1)" }, p8_path: { type: "string", description: "Explicit path to AuthKey_<id>.p8; otherwise altool's search dirs are used" }, apple_id: { type: "string", description: "Apple ID (tier 2)" }, keychain_item: { type: "string", description: "Keychain item holding the app-specific password (tier 2, preferred)" }, password_env_var: { type: "string", description: "Env var holding the app-specific password (tier 2 fallback)" }, provider_public_id: { type: "string", description: "Required when the account belongs to multiple providers" }, list_providers: { type: "boolean", description: "Pre-flight only: list deliverable providers and return" }, timeout_sec: { type: "number", description: "Default 900" } }, required: [] } },
   { name: "ios_app_store_audit", description: "Deep App Store Review compliance audit for .xcarchive bundles. 18-rule catalog covering privacy manifest, code signing, embedded SDKs, entitlements, asset hygiene, IPv6 compliance, debug-tool leak detection, Swift ABI compatibility, SDK floor (ITMS-90725), and more. Returns structured JSON with severity-ranked violations and ITMS error code mappings. Replaces ios_archive_audit (deprecated). Pass rules='core' for the 6 baseline checks (code-signing, entitlements, info-plist, privacy-manifest, binary-size, sdk-floor); 'all'|'deep' for the full 18-rule scan; CSV like 'binary-size,ipv6-compliance' for an explicit subset.", inputSchema: { type: "object", properties: { archive_path: { type: "string", description: "Absolute path to the .xcarchive bundle" }, rules: { type: "string", description: "'all' (default) | 'core' | 'deep' | comma-separated ruleIDs" } }, required: ["archive_path"] } },
-  { name: "ios_xcodebuild", description: "Build / test / clean an Xcode project with progressive disclosure. Returns one-line summary plus xcresult ID; drill in via ios_xcresult. Token-efficient - full log stays out of context unless requested.", inputSchema: { type: "object", properties: { project: { type: "string", description: "Path to .xcodeproj (mutually exclusive with workspace)" }, workspace: { type: "string", description: "Path to .xcworkspace (mutually exclusive with project)" }, scheme: { type: "string" }, configuration: { type: "string", description: "Debug / Release (default: Release)" }, destination: { type: "string", description: "Xcode destination string. Default: generic iOS Simulator" }, action: { type: "string", enum: ["build", "test", "clean", "archive", "clean-build"], description: "Default: build" }, derived_data_path: { type: "string" }, extra_args: { type: "string", description: "Additional raw xcodebuild args appended verbatim" }, timeout_sec: { type: "number", description: "Build timeout in seconds (default 600)" } }, required: ["scheme"] } },
+  { name: "ios_xcodebuild", description: "Build / test / clean an Xcode project with progressive disclosure. Returns one-line summary plus xcresult ID; drill in via ios_xcresult. Token-efficient - full log stays out of context unless requested.", inputSchema: { type: "object", properties: { project: { type: "string", description: "Path to .xcodeproj (mutually exclusive with workspace)" }, workspace: { type: "string", description: "Path to .xcworkspace (mutually exclusive with project)" }, scheme: { type: "string" }, configuration: { type: "string", description: "Debug / Release (default: Release)" }, destination: { type: "string", description: "Xcode destination string. Default: generic iOS Simulator; for action test, the booted simulator (xcodebuild refuses a generic destination for test)" }, action: { type: "string", enum: ["build", "test", "clean", "archive", "clean-build"], description: "Default: build" }, derived_data_path: { type: "string" }, extra_args: { type: "string", description: "Additional raw xcodebuild args appended verbatim" }, timeout_sec: { type: "number", description: "Build timeout in seconds (default 600)" } }, required: ["scheme"] } },
   { name: "ios_xcresult", description: "Drill into a previous ios_xcodebuild result by xcresult ID. Modes: summary (counts), errors (file:line + message), warnings, log (last N lines), tests (failed), metrics (XCTMetric performance results as JSON). Use this instead of dumping the whole build log into context.", inputSchema: { type: "object", properties: { id: { type: "string", description: "xcresult ID returned by ios_xcodebuild" }, mode: { type: "string", enum: ["summary", "errors", "warnings", "log", "tests", "metrics"], description: "Default: summary" }, log_lines: { type: "number", description: "Lines of raw log to return when mode=log (default 200)" }, test_id: { type: "string", description: "mode=metrics only: scope to one test case or suite instead of every measured test" } }, required: ["id"] } },
   { name: "ios_visual_diff", description: "Compare two PNG screenshots. Returns JSON with diff_pct, pass/fail vs threshold, and an optional diff image. Use for snapshot regression checks across light/dark, locale, dynamic type variants.", inputSchema: { type: "object", properties: { baseline: { type: "string", description: "Path to baseline PNG" }, current: { type: "string", description: "Path to current PNG" }, threshold: { type: "number", description: "Per-pixel color threshold 0..1 (default 0.1, lower = stricter)" }, max_diff_pct: { type: "number", description: "Fail if diff exceeds this percent (default 1.0)" }, output: { type: "string", description: "Path to write diff PNG (optional)" } }, required: ["baseline", "current"] } },
   { name: "ios_leaks", description: "Look for leaked memory in a running simulator (or host) process with /usr/bin/leaks. mode=snapshot reports the current leak count and bytes; mode=diff reports only leaks new since a saved memory graph, which is the shape a regression gate wants. Reports measurable:false when the target lacks get-task-allow rather than reporting it as clean - leaks exits 0 in that case, so an unmeasurable target and a clean one are indistinguishable by exit status. Debug builds are debuggable; Apple-signed apps are not.", inputSchema: { type: "object", properties: { pid: { type: "number", description: "Process id. Either this or bundle_id." }, bundle_id: { type: "string", description: "Bundle id of an app running on the booted simulator; its pid is resolved for you." }, device_id: { type: "string" }, mode: { type: "string", enum: ["snapshot", "diff"], description: "Default: snapshot" }, baseline_graph: { type: "string", description: "mode=diff: path to the memory graph saved by an earlier call" }, output_graph: { type: "string", description: "Save a memory graph here to use as a later baseline" } }, required: [] } },
@@ -365,8 +483,12 @@ const IOS_TOOLS = [
   { name: "ios_list_crashes", description: "List recent crash reports from the host's ~/Library/Logs/DiagnosticReports - where simulator app crashes land. Filter by process name, bound by age and count.", inputSchema: { type: "object", properties: { app: { type: "string", description: "Only reports whose file name (the crashed process) contains this substring" }, since_min: { type: "number", description: "Only reports newer than this many minutes" }, limit: { type: "number", description: "Max reports returned, newest first (default 20)" } } } },
 ];
 
+// Pure-JS members of the ios_* family: comparing two PNGs or listing crash
+// reports needs no simulator, so a missing Xcode must not refuse them.
+const IOS_TOOLS_WITHOUT_XCRUN = new Set(["ios_visual_diff", "ios_list_crashes", "ios_xcresult"]);
+
 async function handleIOS(name, args, ctx = {}) {
-  if (!HAS_XCRUN) return `${ERROR_PREFIX}Xcode not installed - iOS tools unavailable. Install Xcode and run: xcode-select --install`;
+  if (!HAS_XCRUN && !IOS_TOOLS_WITHOUT_XCRUN.has(name)) return `${ERROR_PREFIX}Xcode not installed - iOS tools unavailable. Install Xcode and run: xcode-select --install`;
   const did = (n) => { try { return iosDevice(n); } catch (e) { return null; } };
 
   switch (name) {
@@ -393,11 +515,13 @@ async function handleIOS(name, args, ctx = {}) {
         const parent = dirname(f);
         if (!existsSync(parent)) return `ERROR: directory does not exist: ${parent}`;
       }
-      run(`xcrun simctl io ${d} screenshot ${shq(f)}`);
+      const inline = args.path ? null : captureOptions(args);
+      discardStale(f);
+      const shot = run(`xcrun simctl io ${d} screenshot ${shq(f)}`);
+      if (isFailure(shot)) return shot;
       if (!existsSync(f)) return "ERROR: Screenshot failed";
       if (args.path) return fileResult(`Screenshot written: ${f}`, f);
-      const buf = readFileSync(f);
-      return { type: "image", data: buf.toString("base64"), mimeType: "image/png", path: f };
+      return inlineCapture(f, inline);
     }
     case "ios_tap": { const d = iosDevice(args.device_id); const r = idb(`ui tap --udid ${d} ${num(args.x, "x")} ${num(args.y, "y")}`); return (typeof r === "string" && r.startsWith("ERROR")) ? r : `Tapped (${args.x}, ${args.y})`; }
     case "ios_swipe": { const d = iosDevice(args.device_id); const dur = args.duration_ms ? ` --duration ${(args.duration_ms / 1000).toFixed(2)}` : ""; const r = idb(`ui swipe --udid ${d} ${num(args.x1, "x1")} ${num(args.y1, "y1")} ${num(args.x2, "x2")} ${num(args.y2, "y2")}${dur}`); return isFailure(r) ? r : "Swiped"; }
@@ -416,7 +540,19 @@ async function handleIOS(name, args, ctx = {}) {
     }
     case "ios_set_appearance": { const d = iosDevice(args.device_id); return run(`xcrun simctl ui ${d} appearance ${token(args.mode, "appearance mode")}`) || `Appearance: ${args.mode}`; }
     case "ios_set_content_size": { const d = iosDevice(args.device_id); return run(`xcrun simctl ui ${d} content_size ${token(args.size, "content size")}`) || `Content size: ${args.size}`; }
-    case "ios_set_locale": { const d = iosDevice(args.device_id); const bid = sanitizeId(args.bundle_id); run(`xcrun simctl spawn ${d} defaults write ${bid} AppleLanguages -array ${shq(args.language)}`); run(`xcrun simctl terminate ${d} ${bid}`); run(`xcrun simctl launch ${d} ${bid}`); return `Locale: ${args.language}`; }
+    case "ios_set_locale": {
+      const d = iosDevice(args.device_id);
+      const bid = sanitizeId(args.bundle_id);
+      const written = run(`xcrun simctl spawn ${d} defaults write ${bid} AppleLanguages -array ${shq(args.language)}`);
+      if (isFailure(written)) return written;
+      // An app that is not running has nothing to terminate; that is not a
+      // failure of the locale change, which applies at the next launch.
+      const stopped = run(`xcrun simctl terminate ${d} ${bid}`);
+      if (isFailure(stopped) && !/No such process|found nothing to terminate|not running/i.test(stopped)) return stopped;
+      const launched = run(`xcrun simctl launch ${d} ${bid}`);
+      if (isFailure(launched)) return launched;
+      return `Locale: ${args.language} (${bid} relaunched)`;
+    }
     case "ios_open_url": { const d = iosDevice(args.device_id); return run(`xcrun simctl openurl ${d} ${shq(args.url)}`) || `Opened: ${args.url}`; }
     case "ios_status_bar": {
       const d = iosDevice(args.device_id);
@@ -481,11 +617,10 @@ async function handleIOS(name, args, ctx = {}) {
     }
     case "ios_add_media": { const d = iosDevice(args.device_id); return run(`xcrun simctl addmedia ${d} ${shq(args.file_path)}`) || "Media added"; }
     case "ios_keychain_reset": { const d = iosDevice(args.device_id); return run(`xcrun simctl keychain ${d} reset`) || "Keychain reset"; }
-    case "ios_get_app_container": { const d = iosDevice(args.device_id); return run(`xcrun simctl get_app_container ${d} ${sanitizeId(args.bundle_id)} ${args.container || "app"}`); }
+    case "ios_get_app_container": { const d = iosDevice(args.device_id); return run(`xcrun simctl get_app_container ${d} ${sanitizeId(args.bundle_id)} ${token(args.container || "app", "container")}`); }
     case "ios_erase_device": { const d = iosDevice(args.device_id); return run(`xcrun simctl erase ${d}`) || "Device erased"; }
     case "ios_get_ui_tree": {
-      const script = join(__dirname, "ui-tree-dumper.swift");
-      if (!existsSync(script)) return "ui-tree-dumper.swift not found";
+      if (!existsSync(DUMPER_SOURCE)) return "ui-tree-dumper.swift not found";
       // Path check first, matching the Android sibling: the AX dump takes up to
       // 15s, too expensive to spend before rejecting a bad destination.
       if (args.path) {
@@ -493,16 +628,18 @@ async function handleIOS(name, args, ctx = {}) {
         if (!existsSync(parent)) return `${ERROR_PREFIX}directory does not exist: ${parent}`;
       }
       const depth = num(args.max_depth ?? 10, "max_depth");
-      const tree = run(`swift ${shq(script)} ${depth}`, { timeout: 15000 });
-      if (!args.path || isFailure(tree)) return tree;
+      const tree = runCapture(`${dumperCommand()} ${depth}`, { timeout: 15000 });
+      if (isFailure(tree)) return tree;
+      const dumperError = dumperErrorOf(tree);
+      if (dumperError) return `${ERROR_PREFIX}${dumperError}`;
+      if (!args.path) return tree;
       writeFileSync(String(args.path), tree);
       return fileResult(`UI tree written: ${args.path}`, String(args.path));
     }
     case "ios_accessibility_audit": {
-      const script = join(__dirname, "ui-tree-dumper.swift");
-      if (!existsSync(script)) return "ui-tree-dumper.swift not found";
+      if (!existsSync(DUMPER_SOURCE)) return "ui-tree-dumper.swift not found";
       const depth = num(args.max_depth ?? 10, "max_depth");
-      const treeJson = run(`swift ${shq(script)} ${depth}`, { timeout: 30000 });
+      const treeJson = run(`${dumperCommand()} ${depth}`, { timeout: 30000 });
       let tree = null;
       try {
         tree = JSON.parse(treeJson);
@@ -553,14 +690,14 @@ async function handleIOS(name, args, ctx = {}) {
       const binaryName = appName.replace(".app", "");
       const binaryPath = `${appDir}/${binaryName}`;
       // 2. Binary size
-      const sizeOut = run(`stat -f "%z" ${shq(binaryPath)} 2>/dev/null`);
-      if (sizeOut) { const sizeMB = parseInt(sizeOut) / 1048576; findings.push({ check: "binary_size", value: `${sizeMB.toFixed(1)} MB`, status: sizeMB > 500 ? "warning" : "pass", detail: sizeMB > 500 ? "Binary exceeds 500MB - may hit App Store limits" : "OK" }); }
+      try { const sizeMB = statSync(binaryPath).size / 1048576; findings.push({ check: "binary_size", value: `${sizeMB.toFixed(1)} MB`, status: sizeMB > 500 ? "warning" : "pass", detail: sizeMB > 500 ? "Binary exceeds 500MB - may hit App Store limits" : "OK" }); } catch {}
       // 3. Debug tool leak check
       const debugSymbols = run(`nm ${shq(binaryPath)} 2>/dev/null | grep -iE "FLEX|Reveal|Stetho|Flipper|CocoaDebug|Pulse" | head -10`);
       findings.push({ check: "debug_tools", status: debugSymbols ? "critical" : "pass", detail: debugSymbols ? `Debug tools found in binary: ${debugSymbols}` : "No debug tools detected" });
-      // 4. Code signing
-      const codesign = run(`codesign -dvv ${shq(appDir)} 2>&1`);
-      const hasSignature = codesign && !codesign.includes("not signed");
+      // 4. Code signing. codesign exits 1 on an unsigned bundle, and run()'s
+      // failure marker does not carry its "not signed" line; runCapture does.
+      const codesign = runCapture(`codesign -dvv ${shq(appDir)} 2>&1`);
+      const hasSignature = codesign && !isFailure(codesign) && !codesign.includes("not signed");
       findings.push({ check: "code_signing", status: hasSignature ? "pass" : "critical", detail: hasSignature ? "Signed" : "NOT SIGNED - will be rejected" });
       // 5. Provisioning profile
       const provProfile = run(`ls ${shq(appDir + "/embedded.mobileprovision")} 2>/dev/null`);
@@ -689,7 +826,16 @@ async function handleIOS(name, args, ctx = {}) {
       if (args.project && args.workspace) return "ERROR: pass project OR workspace, not both";
       const action = args.action || "build";
       const config = args.configuration || "Release";
-      const dest = args.destination || "generic/platform=iOS Simulator";
+      let dest = args.destination;
+      if (!dest) {
+        if (action === "test") {
+          const d = did();
+          if (!d) return `${ERROR_PREFIX}action "test" needs a booted simulator: xcodebuild refuses generic/platform=iOS Simulator for test. Boot one with ios_boot_device, or pass destination explicitly.`;
+          dest = `platform=iOS Simulator,id=${d}`;
+        } else {
+          dest = "generic/platform=iOS Simulator";
+        }
+      }
       const id = `xcresult-${new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14)}-${Math.random().toString(36).slice(2, 8)}`;
       const xcresultPath = join(SCREENSHOT_DIR, `${id}.xcresult`);
       const logPath = join(SCREENSHOT_DIR, `${id}.log`);
@@ -804,13 +950,21 @@ async function handleIOS(name, args, ctx = {}) {
       return diffImagePath ? fileResult(report, diffImagePath) : report;
     }
     case "ios_leaks": {
-      let pid = Number.isInteger(args.pid) ? args.pid : null;
+      // The schema validator accepts a numeric string for `pid`, so coerce
+      // rather than re-check the raw type here.
+      const pidNum = args.pid === undefined || args.pid === null || args.pid === "" ? NaN : Number(args.pid);
+      let pid = Number.isInteger(pidNum) && pidNum > 0 ? pidNum : null;
       if (!pid && args.bundle_id) {
         const d = iosDevice(args.device_id);
-        const out = run(`xcrun simctl spawn ${d} launchctl list 2>/dev/null | grep ${shq(sanitizeId(args.bundle_id))}`);
-        const m = out && out.match(/^(\d+)\s/m);
-        if (!m) return `ERROR: no running process for ${args.bundle_id} on the booted simulator; launch it first`;
-        pid = parseInt(m[1], 10);
+        const id = sanitizeId(args.bundle_id);
+        const out = run(`xcrun simctl spawn ${d} launchctl list 2>/dev/null`);
+        if (isFailure(out)) return out;
+        // Whole-token match: a substring grep of com.x also matched com.xy, and
+        // the dots were regex wildcards.
+        const label = new RegExp(`(^|[^A-Za-z0-9._-])${id.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&")}($|[^A-Za-z0-9._-])`);
+        const line = out.split("\n").find((l) => /^\d+\s/.test(l) && label.test(l));
+        if (!line) return `ERROR: no running process for ${args.bundle_id} on the booted simulator; launch it first`;
+        pid = parseInt(line, 10);
       }
       if (!pid) return "ERROR: pass pid or bundle_id";
 
@@ -823,8 +977,12 @@ async function handleIOS(name, args, ctx = {}) {
       const diffArg = mode === "diff" ? ` --diffFrom=${shq(args.baseline_graph)}` : "";
       // leaks exits 1 when it FINDS leaks, so a non-zero status is a result and
       // not a failure. Everything below is decided from the parsed output.
-      const raw = runCapture(`leaks ${pid}${diffArg}${graphOut} 2>&1`, { timeout: 120000 });
-      const parsed = parseLeaksOutput(raw);
+      // spawnCollect rather than execSync: a two-minute scan must not block the
+      // event loop, and its output is capped instead of killing the child.
+      const res = await spawnCollect(`leaks ${pid}${diffArg}${graphOut} 2>&1`, { timeout: 120000, signal: ctx.signal });
+      if (res.timedOut) return `${ERROR_PREFIX}leaks did not finish within 120s for pid ${pid}`;
+      if (res.aborted) return `${ERROR_PREFIX}leaks cancelled`;
+      const parsed = parseLeaksOutput(res.output);
       return JSON.stringify({
         pid,
         mode,
@@ -847,14 +1005,28 @@ async function handleIOS(name, args, ctx = {}) {
       const only = args.test_identifier ? ` -only-testing:${shq(args.test_identifier)}` : "";
       // xcodebuild exits non-zero when the audit finds anything, because each
       // finding is an XCTest failure. That is a result, not a failure to run.
-      runCapture(
-        `xcodebuild test ${container} -scheme ${shq(args.scheme)} -destination ${shq(`platform=iOS Simulator,id=${d}`)} -resultBundlePath ${shq(bundle)}${only} 2>&1`,
-        { timeout: 900000 },
-      );
+      // spawnCollect: a 15-minute test run through execSync blocked the event
+      // loop for its whole duration, and its 1MB maxBuffer killed the child on
+      // any real build log.
+      const stopHeartbeat = startHeartbeat(ctx, "xcodebuild test (accessibility audit)");
+      let build;
+      try {
+        build = await spawnCollect(
+          `xcodebuild test ${container} -scheme ${shq(args.scheme)} -destination ${shq(`platform=iOS Simulator,id=${d}`)} -resultBundlePath ${shq(bundle)}${only} 2>&1`,
+          { timeout: 900000, signal: ctx.signal },
+        );
+      } finally {
+        stopHeartbeat();
+      }
       if (!existsSync(bundle)) {
-        return JSON.stringify({ measurable: false, reason: "xcodebuild produced no result bundle; the build failed before any test ran", test_ran: false, findings: [] }, null, 2);
+        const reason = build.timedOut
+          ? "xcodebuild did not finish within 900s; no result bundle was written"
+          : build.aborted
+            ? "the request was cancelled before xcodebuild finished"
+            : "xcodebuild produced no result bundle; the build failed before any test ran";
+        return JSON.stringify({ measurable: false, reason, test_ran: false, findings: [] }, null, 2);
       }
-      const json = runCapture(`xcrun xcresulttool get test-results tests --path ${shq(bundle)} --format json 2>&1`, { timeout: 60000 });
+      const json = (await spawnCollect(`xcrun xcresulttool get test-results tests --path ${shq(bundle)} --format json 2>&1`, { timeout: 60000, signal: ctx.signal })).output;
       const r = parseAuditResults(json, args.test_identifier || null);
       return JSON.stringify({
         measurable: r.measurable,
@@ -897,14 +1069,23 @@ async function handleIOS(name, args, ctx = {}) {
 // model-controlled device_id a command injection.
 function adbFlag(id) { return id ? `-s ${deviceSerial(id)}` : ""; }
 
+// One rule for both launchers: `activity` is the class, relative or fully
+// qualified, and the component is package/activity. A value that already
+// carries the package (com.x/.Main) is used as it is.
+function androidComponent(packageName, activity) {
+  const pkg = sanitizeId(packageName);
+  const act = sanitizeId(activity);
+  return act.includes("/") ? act : `${pkg}/${act}`;
+}
+
 const ANDROID_TOOLS = [
   { name: "android_list_devices", description: "List connected Android devices and emulators", inputSchema: { type: "object", properties: {} } },
-  { name: "android_screenshot", description: "Capture an Android screenshot. Returns a base64 PNG by default; pass `path` to write the file and return only its location - a base64 image per capture exhausts the caller's context on multi-capture runs.", inputSchema: { type: "object", properties: { device_id: { type: "string" }, path: { type: "string", description: "Absolute file path to write the PNG to. The parent directory must already exist. Returns the path instead of the image." } } } },
+  { name: "android_screenshot", description: "Capture an Android screenshot. Without `path` the image comes back inline, downscaled to 800 px on the longest side as a quality-80 JPEG (~60 KB instead of a multi-MB full-resolution PNG on every capture); `format: \"png\"` with `max_width: 0` returns the original PNG bytes. Downscaling needs sips (macOS); without it the original PNG is returned and the result says so. Pass `path` to write the full-resolution PNG there and return only its location - what a multi-capture run and the design tools need.", inputSchema: { type: "object", properties: { device_id: { type: "string" }, path: { type: "string", description: "Absolute file path to write the PNG to. The parent directory must already exist. Returns the path instead of the image." }, max_width: { type: "integer", description: "Longest side of the inline image in pixels (default 800). 0 keeps the original size. Ignored with `path`." }, format: { type: "string", enum: ["jpeg", "png"], description: "Inline image format (default jpeg). Ignored with `path`." }, quality: { type: "integer", description: "JPEG quality 1-100 (default 80). Ignored for png and with `path`." } } } },
   { name: "android_tap", description: "Tap at coordinates on Android", inputSchema: { type: "object", properties: { x: { type: "number" }, y: { type: "number" }, device_id: { type: "string" } }, required: ["x", "y"] } },
   { name: "android_swipe", description: "Swipe on Android", inputSchema: { type: "object", properties: { x1: { type: "number" }, y1: { type: "number" }, x2: { type: "number" }, y2: { type: "number" }, duration_ms: { type: "number" }, device_id: { type: "string" } }, required: ["x1", "y1", "x2", "y2"] } },
-  { name: "android_type_text", description: "Type text on Android", inputSchema: { type: "object", properties: { text: { type: "string" }, device_id: { type: "string" } }, required: ["text"] } },
+  { name: "android_type_text", description: "Type text on Android via `adb shell input text`. The text reaches the device shell as a quoted literal, so shell characters are typed, not interpreted. Platform limit: `input text` drops non-ASCII characters and some symbols; use the keyboard for those.", inputSchema: { type: "object", properties: { text: { type: "string" }, device_id: { type: "string" } }, required: ["text"] } },
   { name: "android_key_event", description: "Send Android key event (HOME=3, BACK=4, ENTER=66)", inputSchema: { type: "object", properties: { keycode: { type: "number" }, device_id: { type: "string" } }, required: ["keycode"] } },
-  { name: "android_launch_app", description: "Launch Android app by package name", inputSchema: { type: "object", properties: { package_name: { type: "string" }, activity: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
+  { name: "android_launch_app", description: "Launch Android app by package name", inputSchema: { type: "object", properties: { package_name: { type: "string" }, activity: { type: "string", description: "Activity class, relative (.MainActivity) or fully qualified (com.example.MainActivity); started as package_name/activity. Omit to launch through the LAUNCHER intent." }, device_id: { type: "string" } }, required: ["package_name"] } },
   { name: "android_stop_app", description: "Force-stop Android app", inputSchema: { type: "object", properties: { package_name: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
   { name: "android_list_packages", description: "List installed Android packages", inputSchema: { type: "object", properties: { filter: { type: "string" }, device_id: { type: "string" } } } },
   { name: "android_go_home", description: "Press Android home button", inputSchema: { type: "object", properties: { device_id: { type: "string" } } } },
@@ -924,13 +1105,26 @@ const ANDROID_TOOLS = [
   { name: "android_open_url", description: "Open URL or deep link on Android", inputSchema: { type: "object", properties: { url: { type: "string" }, device_id: { type: "string" } }, required: ["url"] } },
   { name: "android_clear_app_data", description: "Clear all data for Android app", inputSchema: { type: "object", properties: { package_name: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
   { name: "android_accessibility_audit", description: "Audit Android app accessibility on the connected device: missing contentDescription, clickable nodes TalkBack cannot focus, touch targets under 48dp, missing resource-ids, and whether the reading order follows the visual layout. Reports measurable:false with a reason rather than a clean result when the dump could not be read.", inputSchema: { type: "object", properties: { device_id: { type: "string" }, scope: { type: "string", description: "Filter: only audit elements whose resource-id contains this prefix (e.g. 'login_', 'com.example:id/login_'). Omit to audit all." }, rtl: { type: "boolean", description: "Expect right-to-left reading within a row. Default false." } } } },
-  { name: "android_launch_time", description: "Measure Android app launch time: force-stops the package, starts it with am start -W, and reports TotalTime/WaitTime in ms plus the platform's own LaunchState (COLD/WARM/HOT). Below Android 10 there is no LaunchState and cold_start is null rather than assumed.", inputSchema: { type: "object", properties: { package_name: { type: "string" }, activity: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
+  { name: "android_launch_time", description: "Measure Android app launch time: force-stops the package, starts it with am start -W, and reports TotalTime/WaitTime in ms plus the platform's own LaunchState (COLD/WARM/HOT). Below Android 10 there is no LaunchState and cold_start is null rather than assumed.", inputSchema: { type: "object", properties: { package_name: { type: "string" }, activity: { type: "string", description: "Activity class, relative (.MainActivity) or fully qualified (com.example.MainActivity); started as package_name/activity. Default .MainActivity." }, device_id: { type: "string" } }, required: ["package_name"] } },
   { name: "android_apk_audit", description: "Audit APK/AAB for Play Store compliance: debug flag, target SDK, permissions, signing, ProGuard", inputSchema: { type: "object", properties: { apk_path: { type: "string", description: "Path to .apk file" } }, required: ["apk_path"] } },
   { name: "android_meminfo", description: "Read an Android app's memory via `adb shell dumpsys meminfo` (KB, no root). mode=snapshot returns the App Summary rows and totals; mode=diff compares two snapshots so growth across the same flow is visible, which is the signal a leak actually produces - a single absolute number says almost nothing. Reports measurable:false when the package has no running process rather than returning zeros.", inputSchema: { type: "object", properties: { package_name: { type: "string" }, device_id: { type: "string" }, mode: { type: "string", enum: ["snapshot", "diff"], description: "Default: snapshot" }, baseline_json: { type: "string", description: "mode=diff: the JSON returned by an earlier snapshot call" } }, required: ["package_name"] } },
   { name: "android_list_crashes", description: "Dump the Android crash log buffer (`adb logcat -b crash -d`), tail-bounded. Empty output means no crashes since the buffer was last cleared.", inputSchema: { type: "object", properties: { lines: { type: "number", description: "Max lines returned, from the end (default 200)" }, device_id: { type: "string" } } } },
   { name: "android_set_orientation", description: "Rotate the Android screen to portrait or landscape. Disables accelerometer rotation and pins user_rotation, so the device stays put until rotation is re-enabled. Accounts for the device's natural orientation (detected via wm size), so landscape-natural tablets rotate correctly too. No iOS counterpart: simctl exposes no rotation lever.", inputSchema: { type: "object", properties: { orientation: { type: "string", enum: ["portrait", "landscape"] }, device_id: { type: "string" } }, required: ["orientation"] } },
 ];
 
+// The snapshot shape the tool emits, and the shape diffMeminfo accepts back
+// as a baseline. One function so the two cannot drift apart again.
+function meminfoPayload(snapshot) {
+  return {
+    measurable: snapshot.measurable,
+    reason: snapshot.reason,
+    pss_kb: snapshot.pss,
+    total_pss_kb: snapshot.totalPssKb,
+    total_rss_kb: snapshot.totalRssKb,
+    total_swap_kb: snapshot.totalSwapKb,
+  };
+}
+
 async function handleAndroid(name, args, ctx = {}) {
   if (!HAS_ADB) return `${ERROR_PREFIX}Android SDK not installed - adb not on PATH, so Android tools cannot run. Install platform-tools and ensure adb is on PATH.`;
   const df = adbFlag(args.device_id);
@@ -943,21 +1137,24 @@ async function handleAndroid(name, args, ctx = {}) {
         const parent = dirname(f);
         if (!existsSync(parent)) return `${ERROR_PREFIX}directory does not exist: ${parent}`;
       }
-      run(`adb ${df} shell screencap -p /sdcard/_mcp_screen.png`);
-      run(`adb ${df} pull /sdcard/_mcp_screen.png ${shq(f)}`);
+      const inline = args.path ? null : captureOptions(args);
+      discardStale(f);
+      const cap = run(`adb ${df} shell screencap -p /sdcard/_mcp_screen.png`);
+      if (isFailure(cap)) return cap;
+      const pulled = run(`adb ${df} pull /sdcard/_mcp_screen.png ${shq(f)}`);
       run(`adb ${df} shell rm /sdcard/_mcp_screen.png`);
+      if (isFailure(pulled)) return pulled;
       if (!existsSync(f)) return "ERROR: Screenshot failed";
       if (args.path) return fileResult(`Screenshot written: ${f}`, f);
-      const buf = readFileSync(f);
-      return { type: "image", data: buf.toString("base64"), mimeType: "image/png", path: f };
+      return inlineCapture(f, inline);
     }
     case "android_tap": return run(`adb ${df} shell input tap ${num(args.x, "x")} ${num(args.y, "y")}`) || `Tapped (${args.x}, ${args.y})`;
     case "android_swipe": return run(`adb ${df} shell input swipe ${num(args.x1, "x1")} ${num(args.y1, "y1")} ${num(args.x2, "x2")} ${num(args.y2, "y2")} ${num(args.duration_ms || 300, "duration_ms")}`) || "Swiped";
     // `adb shell input text` wants spaces as %s; single-quote the result so the
     // remaining characters cannot reach the shell as syntax.
-    case "android_type_text": return run(`adb ${df} shell input text ${shq(String(args.text ?? "").replace(/ /g, "%s"))}`) || `Typed: ${args.text}`;
+    case "android_type_text": return run(`adb ${df} shell input text ${remoteShq(String(args.text ?? "").replace(/ /g, "%s"))}`) || `Typed: ${args.text}`;
     case "android_key_event": return run(`adb ${df} shell input keyevent ${token(args.keycode, "keycode")}`) || `Key ${args.keycode}`;
-    case "android_launch_app": return args.activity ? run(`adb ${df} shell am start -n ${sanitizeId(args.package_name)}/${sanitizeId(args.activity)}`) : run(`adb ${df} shell monkey -p ${sanitizeId(args.package_name)} -c android.intent.category.LAUNCHER 1`) || `Launched`;
+    case "android_launch_app": return args.activity ? run(`adb ${df} shell am start -n ${androidComponent(args.package_name, args.activity)}`) : run(`adb ${df} shell monkey -p ${sanitizeId(args.package_name)} -c android.intent.category.LAUNCHER 1`) || `Launched`;
     case "android_stop_app": return run(`adb ${df} shell am force-stop ${sanitizeId(args.package_name)}`) || "Stopped";
     case "android_list_packages": { const out = run(`adb ${df} shell pm list packages`); return args.filter ? out.split("\n").filter(l => l.toLowerCase().includes(args.filter.toLowerCase())).join("\n") : out; }
     case "android_go_home": return run(`adb ${df} shell input keyevent 3`) || "Home";
@@ -968,9 +1165,12 @@ async function handleAndroid(name, args, ctx = {}) {
         const parent = dirname(f);
         if (!existsSync(parent)) return `${ERROR_PREFIX}directory does not exist: ${parent}`;
       }
-      run(`adb ${df} shell uiautomator dump /sdcard/_mcp_ui.xml`);
-      run(`adb ${df} pull /sdcard/_mcp_ui.xml ${shq(f)}`);
+      discardStale(f);
+      const dumped = run(`adb ${df} shell uiautomator dump /sdcard/_mcp_ui.xml`);
+      if (isFailure(dumped)) return dumped;
+      const pulled = run(`adb ${df} pull /sdcard/_mcp_ui.xml ${shq(f)}`);
       run(`adb ${df} shell rm /sdcard/_mcp_ui.xml`);
+      if (isFailure(pulled)) return pulled;
       if (!existsSync(f)) return "ERROR: UI dump failed";
       if (args.filter === "interactive") {
         const elements = interactiveElements(readFileSync(f, "utf-8"));
@@ -1076,7 +1276,7 @@ async function handleAndroid(name, args, ctx = {}) {
     case "android_uninstall_app": return run(`adb ${df} shell pm uninstall ${sanitizeId(args.package_name)}`) || "Uninstalled";
     case "android_logcat": { const lines = args.lines !== undefined ? num(args.lines, "lines") : 50; const tf = args.tag ? `| grep -i ${shq(args.tag)}` : ""; return run(`adb ${df} logcat -d ${tf} | tail -${lines}`); }
     case "android_get_screen_size": return run(`adb ${df} shell wm size`);
-    case "android_open_url": return run(`adb ${df} shell am start -a android.intent.action.VIEW -d ${shq(args.url)}`) || `Opened: ${args.url}`;
+    case "android_open_url": return run(`adb ${df} shell am start -a android.intent.action.VIEW -d ${remoteShq(args.url)}`) || `Opened: ${args.url}`;
     case "android_clear_app_data": return run(`adb ${df} shell pm clear ${sanitizeId(args.package_name)}`) || "Cleared";
     case "android_accessibility_audit": {
       run(`adb ${df} shell uiautomator dump /sdcard/_mcp_a11y.xml`);
@@ -1101,8 +1301,8 @@ async function handleAndroid(name, args, ctx = {}) {
     }
     case "android_launch_time": {
       run(`adb ${df} shell am force-stop ${sanitizeId(args.package_name)}`);
-      const activity = sanitizeId(args.activity || `${args.package_name}/.MainActivity`);
-      const result = run(`adb ${df} shell am start -W -n ${activity} 2>&1`);
+      const component = androidComponent(args.package_name, args.activity || ".MainActivity");
+      const result = run(`adb ${df} shell am start -W -n ${component} 2>&1`);
       const parsed = parseLaunchOutput(result);
       return JSON.stringify({
         package: args.package_name,
@@ -1122,7 +1322,7 @@ async function handleAndroid(name, args, ctx = {}) {
       if (!existsSync(p)) return `ERROR: APK not found at ${p}`;
       const findings = [];
       // 1. Basic info via aapt2
-      const aapt = run(`aapt2 dump badging ${shq(p)} 2>/dev/null`) || run(`aapt dump badging ${shq(p)} 2>/dev/null`);
+      const aapt = runOrNull(`aapt2 dump badging ${shq(p)} 2>/dev/null`) || runOrNull(`aapt dump badging ${shq(p)} 2>/dev/null`);
       if (aapt) {
         const pkg = aapt.match(/package: name='([^']*)'/)?.[1];
         const versionName = aapt.match(/versionName='([^']*)'/)?.[1];
@@ -1143,19 +1343,29 @@ async function handleAndroid(name, args, ctx = {}) {
       } else {
         findings.push({ check: "aapt", status: "warning", detail: "aapt2/aapt not found - install Android SDK Build-Tools for full audit" });
       }
-      // 2. Signing check
-      const signingInfo = run(`apksigner verify --print-certs ${shq(p)} 2>&1`);
-      if (signingInfo && !signingInfo.includes("ERROR")) {
-        const hasV2 = signingInfo.includes("v2 scheme") || run(`apksigner verify -v ${shq(p)} 2>&1`)?.includes("Verified using v2");
+      // 2. Signing check. apksigner exits 1 on a failed verification with the
+      // verdict on stdout, so the output is captured whatever the status.
+      const signingInfo = runCapture(`apksigner verify --print-certs ${shq(p)} 2>&1`);
+      if (/DOES NOT VERIFY/.test(signingInfo)) {
+        findings.push({ check: "signing", status: "critical", detail: signingInfo.slice(0, 500) });
+      } else if (isFailure(signingInfo) || /command not found|No such file or directory/i.test(signingInfo)) {
+        findings.push({ check: "signing", status: "warning", detail: "apksigner not found - install Android SDK Build-Tools to verify the signature" });
+      } else if (/^(ERROR|Exception)/m.test(signingInfo)) {
+        findings.push({ check: "signing", status: "warning", detail: signingInfo.slice(0, 500) });
+      } else {
+        const hasV2 = signingInfo.includes("v2 scheme") || (runOrNull(`apksigner verify -v ${shq(p)} 2>&1`) || "").includes("Verified using v2");
         findings.push({ check: "signing", status: "pass", detail: "APK is signed" });
         findings.push({ check: "signing_v2", status: hasV2 ? "pass" : "warning", detail: hasV2 ? "v2+ signature present" : "Only v1 signature - consider v2+ for tamper protection" });
-      } else {
-        findings.push({ check: "signing", status: signingInfo?.includes("DOES NOT VERIFY") ? "critical" : "warning", detail: signingInfo || "apksigner not found" });
       }
       // 3. File size
-      try { const stat = run(`stat -f "%z" ${shq(p)} 2>/dev/null`) || run(`stat -c "%s" ${shq(p)} 2>/dev/null`); if (stat) { const mb = parseInt(stat) / 1048576; findings.push({ check: "apk_size", value: `${mb.toFixed(1)} MB`, status: mb > 150 ? "warning" : "pass", detail: mb > 150 ? "APK > 150MB - consider App Bundle (.aab)" : "OK" }); } } catch {}
+      try {
+        const mb = statSync(p).size / 1048576;
+        findings.push({ check: "apk_size", value: `${mb.toFixed(1)} MB`, status: mb > 150 ? "warning" : "pass", detail: mb > 150 ? "APK > 150MB - consider App Bundle (.aab)" : "OK" });
+      } catch (e) {
+        findings.push({ check: "apk_size", status: "warning", detail: `could not read the file size: ${e.message}` });
+      }
       // 4. ProGuard/R8 check
-      const hasMapping = run(`unzip -l ${shq(p)} 2>/dev/null | grep -c "classes.dex"`)?.trim();
+      const hasMapping = runOrNull(`unzip -l ${shq(p)} 2>/dev/null | grep -c "classes.dex"`);
       const dexCount = parseInt(hasMapping) || 0;
       findings.push({ check: "dex_files", value: `${dexCount} dex file(s)`, status: dexCount > 3 ? "warning" : "info", detail: dexCount > 3 ? "Many DEX files - ensure R8/ProGuard minification is enabled" : "OK" });
       // Summary
@@ -1177,18 +1387,9 @@ async function handleAndroid(name, args, ctx = {}) {
           return "ERROR: baseline_json is not valid JSON";
         }
         const d = diffMeminfo(before, snapshot);
-        return JSON.stringify({ package: args.package_name, mode, comparable: d.comparable, reason: d.reason, delta_kb: d.deltaKb, total_pss_delta_kb: d.totalPssDeltaKb, after: snapshot }, null, 2);
+        return JSON.stringify({ package: args.package_name, mode, comparable: d.comparable, reason: d.reason, delta_kb: d.deltaKb, total_pss_delta_kb: d.totalPssDeltaKb, after: meminfoPayload(snapshot) }, null, 2);
       }
-      return JSON.stringify({
-        package: args.package_name,
-        mode,
-        measurable: snapshot.measurable,
-        reason: snapshot.reason,
-        pss_kb: snapshot.pss,
-        total_pss_kb: snapshot.totalPssKb,
-        total_rss_kb: snapshot.totalRssKb,
-        total_swap_kb: snapshot.totalSwapKb,
-      }, null, 2);
+      return JSON.stringify({ package: args.package_name, mode, ...meminfoPayload(snapshot) }, null, 2);
     }
     case "android_list_crashes": {
       const lines = args.lines !== undefined ? num(args.lines, "lines") : 200;
@@ -1224,9 +1425,15 @@ async function handleAndroid(name, args, ctx = {}) {
 
 let _browser = null;
 let _page = null;
-
-async function ensureBrowser(browserType = "chromium") {
-  if (_browser && _page) return _page;
+let _engine = null;
+
+// A request for a different engine closes the current browser and relaunches;
+// a partial launch (newContext/newPage threw) is closed rather than left as a
+// browser with no page that the next call would launch beside.
+async function ensureBrowser(browserType) {
+  const wanted = browserType || _engine || "chromium";
+  if (_browser && _page && _engine === wanted) return _page;
+  if (_browser || _page) await closeBrowser();
   let pw;
   try {
     pw = await import("playwright");
@@ -1234,10 +1441,17 @@ async function ensureBrowser(browserType = "chromium") {
     throw new Error("Web tools require Playwright. Install once with: npm i -g playwright && npx playwright install chromium");
   }
   const engines = { chromium: pw.chromium, webkit: pw.webkit, firefox: pw.firefox };
-  const engine = engines[browserType] || pw.chromium;
+  const engine = engines[wanted];
+  if (!engine) throw new Error(`unknown browser engine: ${wanted}`);
   _browser = await engine.launch({ headless: true });
-  const ctx = await _browser.newContext();
-  _page = await ctx.newPage();
+  try {
+    const ctx = await _browser.newContext();
+    _page = await ctx.newPage();
+  } catch (e) {
+    await closeBrowser();
+    throw e;
+  }
+  _engine = wanted;
   return _page;
 }
 
@@ -1246,6 +1460,7 @@ async function closeBrowser() {
   try { await _browser?.close(); } catch {}
   _page = null;
   _browser = null;
+  _engine = null;
 }
 
 const WEB_TOOLS = [
@@ -1350,6 +1565,10 @@ const AGENT_TOOLS = [
 // a batch able to nest itself has no recursion bound.
 async function dispatchStep(tool, stepArgs) {
   if (tool.startsWith("agent_")) throw new Error(`Nested batch steps are not supported: ${tool}`);
+  // The same boundary check a direct call gets: a batched step used to reach
+  // the handler with its enum/type/required contract unenforced.
+  const schemaError = validateArgs(tool, stepArgs);
+  if (schemaError) throw new Error(`invalid arguments: ${schemaError}`);
   let result;
   if (tool.startsWith("ios_")) result = await handleIOS(tool, stepArgs);
   else if (tool.startsWith("android_")) result = await handleAndroid(tool, stepArgs);
@@ -1611,7 +1830,7 @@ const bundleAuditSchema = (pathKey) => ({
       items: {
         type: "object",
         properties: {
-          status: { type: "string", enum: ["pass", "warning", "critical"] },
+          status: { type: "string", enum: ["pass", "warning", "critical", "info"] },
           rule: { type: "string" },
           message: { type: "string" },
         },
@@ -1664,7 +1883,7 @@ const OUTPUT_SCHEMAS = {
       max_diff_pct: { type: "number" },
       baseline: { type: "string" },
       current: { type: "string" },
-      diff_image: { type: "string" },
+      diff_image: { type: ["string", "null"] },
     },
   },
 
@@ -1694,9 +1913,11 @@ const OUTPUT_SCHEMAS = {
     required: ["package", "cold_start"],
     properties: {
       package: { type: "string" },
-      cold_start: { type: "boolean" },
+      launch_state: { type: ["string", "null"] },
+      cold_start: { type: ["boolean", "null"] },
       total_time_ms: { type: ["integer", "null"] },
       wait_time_ms: { type: ["integer", "null"] },
+      error: { type: ["string", "null"] },
       raw: { type: "string" },
     },
   },
@@ -1733,9 +1954,11 @@ const OUTPUT_SCHEMAS = {
         items: {
           type: "object",
           properties: {
+            step: { type: "integer" },
             tool: { type: "string" },
             status: { type: "string", enum: ["ok", "error"] },
-            output: { type: "string" },
+            result: { type: "string" },
+            error: { type: "string" },
           },
         },
       },
@@ -1773,7 +1996,8 @@ const designCtx = {
   adbFlag,
   idb,
   hasIdb: HAS_IDB,
-  dumperScript: join(__dirname, "ui-tree-dumper.swift"),
+  dumperScript: DUMPER_SOURCE,
+  dumperCommand,
 };
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: ANNOTATED_TOOLS }));
@@ -1821,11 +2045,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     if (result === null || result === undefined) {
       return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
     }
+    pruneWorkDir(SCREENSHOT_DIR, { keep: promisedPaths(result) });
     if (typeof result === "object" && result?.type === "image") {
       return {
         content: [
           { type: "image", data: result.data, mimeType: result.mimeType },
-          { type: "text", text: `Screenshot: ${result.path}` },
+          { type: "text", text: `Screenshot: ${result.path}${result.note ?? ""}` },
           ...(result.path ? [{ type: "resource_link", uri: `file://${result.path}`, name: basename(result.path), mimeType: result.mimeType }] : []),
         ],
       };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-toolkit-mcp",
-  "version": "3.7.1",
+  "version": "3.9.0",
   "description": "MCP server for iOS Simulator, Android Emulator and headless web control. 87 tools: device automation (tap/swipe/type), accessibility audits, visual diff, crash logs, App Store / Play Store pre-submission compliance. Runs standalone over stdio with any MCP client.",
   "type": "module",
   "main": "index.js",

package/tools/design-check/index.js

@@ -128,7 +128,7 @@ function safeArg(x, label) {
   return x;
 }
 
-// ctx: { run, iosDevice, adbFlag, dumperScript }
+// ctx: { run, iosDevice, adbFlag, dumperScript, dumperCommand }
 export async function handleDesign(name, args, ctx) {
   switch (name) {
     case "design_mock_detect":
@@ -172,7 +172,8 @@ export async function handleDesign(name, args, ctx) {
           }
         }
         const depth = Number(args.max_depth) || 12;
-        const raw = ctx.run(`swift ${shq(ctx.dumperScript)} ${depth}`, { timeout: 15000 });
+        const dumper = ctx.dumperCommand ? ctx.dumperCommand() : `swift ${shq(ctx.dumperScript)}`;
+        const raw = ctx.run(`${dumper} ${depth}`, { timeout: 15000 });
         let tree; try { tree = JSON.parse(raw); } catch { return `ERROR: idb unavailable and AX dumper failed: ${String(raw).slice(0, 200)}`; }
         const elements = flattenIosAxTree(tree);
         const rf = tree.frame || {};

package/tools/design-check/report.js

@@ -541,6 +541,19 @@ ${variants.map((v, i) => variantSection(v, i, fileKey, L)).join("")}
 </body></html>`;
 }
 
+// The browser is closed on every path: a failed setContent/pdf used to leave a
+// headless Chromium running for the life of the server.
+export async function renderPdf({ html, pdfPath, chromium }) {
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage();
+    await page.setContent(html, { waitUntil: "networkidle" });
+    await page.pdf({ path: pdfPath, format: "A4", printBackground: true, margin: { top: "12mm", bottom: "12mm", left: "10mm", right: "10mm" } });
+  } finally {
+    await browser.close();
+  }
+}
+
 export async function writeReport({ report, outDir, formats = ["html"] }) {
   const html = renderHtml(report);
   const out = {};
@@ -571,11 +584,8 @@ export async function writeReport({ report, outDir, formats = ["html"] }) {
     let ok = false, err = "";
     try {
       const { chromium } = await import("playwright");
-      const browser = await chromium.launch();
-      const page = await browser.newPage();
-      await page.setContent(html, { waitUntil: "networkidle" });
-      await page.pdf({ path: pdfPath, format: "A4", printBackground: true, margin: { top: "12mm", bottom: "12mm", left: "10mm", right: "10mm" } });
-      await browser.close(); ok = true;
+      await renderPdf({ html, pdfPath, chromium });
+      ok = true;
     } catch (e) {
       err = e.message;
       // Fallback: use the chrome-headless-shell binary directly (no `playwright` package).

package/tools/ios-app-store-audit/index.js

@@ -67,8 +67,18 @@ const RULE_GROUPS = {
 function resolveRuleSelection(rules) {
   if (!rules || rules === "all" || rules === "deep") return RULE_GROUPS.all();
   if (rules === "core") return RULE_GROUPS.core();
-  // Comma-separated explicit list.
-  return rules.split(",").map((s) => s.trim()).filter(Boolean);
+  // Comma-separated explicit list. An unknown id used to select nothing, and
+  // nothing selected audited nothing and reported PASS.
+  const known = RULE_REGISTRY.map((r) => r.id);
+  const asked = String(rules).split(",").map((s) => s.trim()).filter(Boolean);
+  const unknown = asked.filter((id) => !known.includes(id));
+  if (unknown.length > 0) {
+    throw new Error(`unknown rule id(s): ${unknown.join(", ")}. Valid values: all, core, deep, or a comma-separated subset of ${known.join(", ")}`);
+  }
+  if (asked.length === 0) {
+    throw new Error(`no rules selected from "${rules}". Valid values: all, core, deep, or a comma-separated subset of ${known.join(", ")}`);
+  }
+  return asked;
 }
 
 // ---------- Public entry ---------------------------------------------------
@@ -87,6 +97,7 @@ export async function runAudit({ archivePath, rules = "all", options = {} } = {}
 
   const selectedIDs = new Set(resolveRuleSelection(rules));
   const toRun = RULE_REGISTRY.filter((r) => selectedIDs.has(r.id));
+  if (toRun.length === 0) throw new Error("no rules selected; an audit that runs nothing cannot pass");
 
   const violations = [];
   const ranIDs = [];
@@ -135,6 +146,9 @@ export async function runAudit({ archivePath, rules = "all", options = {} } = {}
     info: violations.filter((v) => v.severity === "info").length,
     total: violations.length,
   };
+  if (ranIDs.length === 0) {
+    throw new Error(`no rule ran: ${skippedIDs.map((s) => `${s.id} (${s.reason})`).join("; ")}`);
+  }
   const verdict = summary.error > 0 ? "FAIL" : summary.warning > 0 ? "WARN" : "PASS";
 
   return {

package/tools/ios-testflight/index.js

@@ -24,7 +24,7 @@
  */
 
 import { execFile } from "child_process";
-import { existsSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "fs";
+import { existsSync, mkdtempSync, readdirSync, rmSync, statSync, writeFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
 
@@ -227,6 +227,15 @@ export function resolveAuth(opts = {}) {
  * @param {string} [opts.signingStyle]    "automatic" | "manual"
  * @returns {string} plist XML
  */
+export function xmlEscape(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
 export function buildExportOptionsPlist(opts) {
   const {
     method = "app-store-connect",
@@ -236,17 +245,17 @@ export function buildExportOptionsPlist(opts) {
     signingStyle,
   } = opts;
 
-  const entries = [`    <key>method</key>\n    <string>${method}</string>`];
+  const entries = [`    <key>method</key>\n    <string>${xmlEscape(method)}</string>`];
   entries.push(
     `    <key>uploadSymbols</key>\n    <${uploadSymbols ? "true" : "false"}/>`,
   );
-  if (teamId) entries.push(`    <key>teamID</key>\n    <string>${teamId}</string>`);
+  if (teamId) entries.push(`    <key>teamID</key>\n    <string>${xmlEscape(teamId)}</string>`);
   if (signingStyle) {
-    entries.push(`    <key>signingStyle</key>\n    <string>${signingStyle}</string>`);
+    entries.push(`    <key>signingStyle</key>\n    <string>${xmlEscape(signingStyle)}</string>`);
   }
   if (provisioningProfiles && Object.keys(provisioningProfiles).length > 0) {
     const rows = Object.entries(provisioningProfiles)
-      .map(([bundleId, profile]) => `      <key>${bundleId}</key>\n      <string>${profile}</string>`)
+      .map(([bundleId, profile]) => `      <key>${xmlEscape(bundleId)}</key>\n      <string>${xmlEscape(profile)}</string>`)
       .join("\n");
     entries.push(`    <key>provisioningProfiles</key>\n    <dict>\n${rows}\n    </dict>`);
   }
@@ -263,6 +272,36 @@ export function buildExportOptionsPlist(opts) {
   ].join("\n");
 }
 
+/**
+ * The .ipa this export wrote: the newest one in output_dir, and only if it was
+ * written after the export started. An older .ipa left by a previous run was
+ * reported as this run's result.
+ *
+ * @param {string} outputDir
+ * @param {number} notBefore - epoch ms; files modified earlier are stale
+ * @returns {{ipaPath: string|null, stale: string[]}}
+ */
+export function pickExportedIpa(outputDir, notBefore) {
+  if (!outputDir || !existsSync(outputDir)) return { ipaPath: null, stale: [] };
+  const candidates = readdirSync(outputDir)
+    .filter((f) => f.endsWith(".ipa"))
+    .map((f) => {
+      const full = join(outputDir, f);
+      try {
+        return { full, mtime: statSync(full).mtimeMs };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.mtime - a.mtime);
+  const fresh = candidates.find((c) => c.mtime >= notBefore);
+  return {
+    ipaPath: fresh ? fresh.full : null,
+    stale: candidates.filter((c) => c.mtime < notBefore).map((c) => c.full),
+  };
+}
+
 /**
  * Export a .xcarchive to a signed .ipa.
  *
@@ -305,6 +344,8 @@ export async function exportIpa(opts) {
   // want that.
   if (allowProvisioningUpdates) argv.push("-allowProvisioningUpdates");
 
+  // 2s of slack for filesystems with coarse mtime granularity.
+  const startedAt = Date.now() - 2000;
   const { err, stdout, stderr } = await execFileAsync("xcodebuild", argv, {
     encoding: "utf-8",
     timeout: timeoutSec * 1000,
@@ -317,13 +358,15 @@ export async function exportIpa(opts) {
     : stdout;
 
   const errors = (log.match(/^.*error:.*$/gim) || []).map((l) => l.trim());
-  let ipaPath;
-  if (existsSync(outputDir)) {
-    const ipa = readdirSync(outputDir).find((f) => f.endsWith(".ipa"));
-    if (ipa) ipaPath = join(outputDir, ipa);
-  }
+  const picked = pickExportedIpa(outputDir, startedAt);
+  const ipaPath = picked.ipaPath || undefined;
   // xcodebuild can exit 0 and still produce nothing useful.
-  if (!ipaPath) ok = false;
+  if (!ipaPath) {
+    ok = false;
+    if (picked.stale.length > 0) {
+      errors.push(`error: no .ipa was written by this export; ${picked.stale.join(", ")} in output_dir predates this run`);
+    }
+  }
 
   // The plist is consumed by the time xcodebuild returns. Leaving the temp dir
   // behind would accumulate one per export for the life of the machine; the path

package/tools/memory/index.js

@@ -132,17 +132,32 @@ export function parseMeminfoOutput(raw) {
   return { measurable: true, reason: null, pss, totalPssKb, totalRssKb, totalSwapKb };
 }
 
+/**
+ * Accept both snapshot shapes: the parser's (pss, totalPssKb) and the one the
+ * android_meminfo tool emits and hands back as baseline_json (pss_kb,
+ * total_pss_kb). The diff read only the parser shape while the tool emitted
+ * the other, so mode=diff never compared anything.
+ */
+function normalizeSnapshot(s) {
+  if (!s || typeof s !== "object") return null;
+  const pss = s.pss && typeof s.pss === "object" ? s.pss : s.pss_kb && typeof s.pss_kb === "object" ? s.pss_kb : {};
+  const totalPssKb = typeof s.totalPssKb === "number" ? s.totalPssKb : typeof s.total_pss_kb === "number" ? s.total_pss_kb : null;
+  return { measurable: s.measurable === true, pss, totalPssKb };
+}
+
 /**
  * Difference between two meminfo snapshots, in KB.
  *
  * Only keys present in both are compared; a key missing from either side is
  * absent from the result rather than counted as zero growth.
  *
- * @param {object} before - parseMeminfoOutput result
- * @param {object} after - parseMeminfoOutput result
+ * @param {object} before - parseMeminfoOutput result, or the android_meminfo snapshot payload
+ * @param {object} after - parseMeminfoOutput result, or the android_meminfo snapshot payload
  * @returns {{comparable: boolean, reason: string|null, deltaKb: object, totalPssDeltaKb: number|null}}
  */
-export function diffMeminfo(before, after) {
+export function diffMeminfo(beforeRaw, afterRaw) {
+  const before = normalizeSnapshot(beforeRaw);
+  const after = normalizeSnapshot(afterRaw);
   if (!before?.measurable || !after?.measurable) {
     return { comparable: false, reason: "one of the snapshots was not measurable", deltaKb: {}, totalPssDeltaKb: null };
   }

package/tools/offload/index.js

@@ -15,7 +15,7 @@
 // outputSchema answers with JSON the host parses as structuredContent, and
 // replacing that with a summary would break the parse.
 
-import { writeFileSync, readFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSync } from "fs";
+import { writeFileSync, readFileSync, mkdirSync, existsSync, readdirSync, statSync, rmSync } from "fs";
 import { join, resolve, sep } from "path";
 import { homedir } from "os";
 
@@ -31,20 +31,24 @@ const TAIL_LINES = 20;
 export const OFFLOAD_KEEP_FILES = 50;
 export const OFFLOAD_KEEP_DAYS = 7;
 
-// `keep` is the file the caller just wrote. It is never deleted, whatever the
-// retention numbers say: the returned text promises that path to the caller, and
-// this module exists precisely because losing the payload is the failure mode. A
-// keepFiles of 0 must bound the directory, not break the answer.
-export function pruneOffloadDir(dir, opts = {}) {
-  const keepFiles = opts.keepFiles ?? OFFLOAD_KEEP_FILES;
-  const keepDays = opts.keepDays ?? OFFLOAD_KEEP_DAYS;
-  const now = opts.now ?? Date.now();
-  const keep = typeof opts.keep === "string" ? resolve(opts.keep) : null;
+// The server's own scratch directory (screenshots, UI dumps, push payloads,
+// build logs, .xcresult bundles) gets the same treatment with a wider count,
+// since a single design audit writes 100+ captures.
+export const WORK_KEEP_ENTRIES = 200;
+export const WORK_KEEP_DAYS = 7;
+
+// `keep` names the file(s) the caller was just promised. They are never deleted,
+// whatever the retention numbers say: the returned text promises that path to
+// the caller, and this module exists precisely because losing the payload is the
+// failure mode. A keepFiles of 0 must bound the directory, not break the answer.
+function pruneEntries(dir, { keepFiles, keepDays, now, keep, match }) {
+  const keepList = Array.isArray(keep) ? keep : keep ? [keep] : [];
+  const keepSet = new Set(keepList.filter((k) => typeof k === "string").map((k) => resolve(k)));
   const cutoff = now - keepDays * 24 * 60 * 60 * 1000;
   let removed = 0;
   try {
     const entries = readdirSync(dir)
-      .filter((n) => n.endsWith(".txt"))
+      .filter(match)
       .map((n) => {
         const full = join(dir, n);
         try {
@@ -57,12 +61,12 @@ export function pruneOffloadDir(dir, opts = {}) {
       .sort((a, b) => b.mtime - a.mtime);
 
     for (let i = 0; i < entries.length; i++) {
-      if (keep && resolve(entries[i].full) === keep) continue;
+      if (keepSet.has(resolve(entries[i].full))) continue;
       const tooOld = entries[i].mtime < cutoff;
       const tooMany = i >= keepFiles;
       if (!tooOld && !tooMany) continue;
       try {
-        unlinkSync(entries[i].full);
+        rmSync(entries[i].full, { recursive: true, force: true });
         removed++;
       } catch {
         // A file another process holds open is skipped, not fatal.
@@ -74,6 +78,28 @@ export function pruneOffloadDir(dir, opts = {}) {
   return removed;
 }
 
+export function pruneOffloadDir(dir, opts = {}) {
+  return pruneEntries(dir, {
+    keepFiles: opts.keepFiles ?? OFFLOAD_KEEP_FILES,
+    keepDays: opts.keepDays ?? OFFLOAD_KEEP_DAYS,
+    now: opts.now ?? Date.now(),
+    keep: opts.keep,
+    match: (n) => n.endsWith(".txt"),
+  });
+}
+
+// Every entry counts here, directories included: an .xcresult bundle is a
+// directory and was the largest thing nothing ever removed.
+export function pruneWorkDir(dir, opts = {}) {
+  return pruneEntries(dir, {
+    keepFiles: opts.keepFiles ?? WORK_KEEP_ENTRIES,
+    keepDays: opts.keepDays ?? WORK_KEEP_DAYS,
+    now: opts.now ?? Date.now(),
+    keep: opts.keep,
+    match: () => true,
+  });
+}
+
 let lastOffload = null;
 
 export function lastOffloadRecord() {