@swmansion/argent 0.9.0 → 0.11.0

package/README.md

@@ -4,7 +4,10 @@
     <img width="1100" height="382" alt="argent-header" src="https://github.com/user-attachments/assets/6cec01d5-da3c-4b6c-97c3-0374a63c213c" />
   </a>
 </p>
-<br/>
+
+[![Ad](https://swm-delivery.com/www/images/zone-gh-argent-1?n=1)](https://swm-delivery.com/www/delivery/ck-slug.php?zoneid=zone-gh-argent-1&n=1)
+[![Ad](https://swm-delivery.com/www/images/zone-gh-argent-2?n=1)](https://swm-delivery.com/www/delivery/ck-slug.php?zoneid=zone-gh-argent-2&n=1)
+[![Ad](https://swm-delivery.com/www/images/zone-gh-argent-3?n=1)](https://swm-delivery.com/www/delivery/ck-slug.php?zoneid=zone-gh-argent-3&n=1)
 
 **[Argent](https://argent.swmansion.com)** is an **agentic toolkit** that gives your AI assistant direct access to iOS Simulators and Android Emulators. Ask it to tap a button, run a profiler or reproduce an issue manually - all from within your CLI, without switching context.
 
@@ -37,6 +40,43 @@ npx @swmansion/argent init
 - For iOS: macOS with **Xcode** installed
 - For Android: **Android SDK Platform Tools** (`adb`) on `PATH`, and the **Android Emulator** package if you want to boot AVDs from Argent. Create AVDs via Android Studio or `avdmanager`.
 
+##### Linux host: extra prerequisites for Android emulators
+
+Argent runs Android emulators on Linux but the default install can be slow if a few host-side knobs aren't right. Cover these once and the experience matches macOS:
+
+- **KVM access.** The emulator falls back to slow software emulation (TCG) without `/dev/kvm`. Make sure virtualization is enabled in BIOS/UEFI (`vmx` for Intel, `svm` for AMD in `/proc/cpuinfo`) and that your user can read/write `/dev/kvm` — on most distros that means joining the `kvm` group:
+
+  ```bash
+  sudo usermod -aG kvm "$USER"
+  # log out and back in so the new group takes effect
+  ```
+
+- **GPU mode (`-gpu swiftshader` on Linux, override available).** The Android emulator's Linux GPU story is messy: `-gpu auto` frequently resolves to lavapipe (slow software Vulkan via host libvulkan, ~10× cold-boot regression on flagship hardware), and `-gpu host` silently produces a corrupted or black emulator window on hosts with non-trivial GL stacks — dual-GPU / Optimus laptops, NVIDIA + Mesa coexistence via libglvnd, Wayland sessions on hybrid graphics, headless / containerized hosts. The failure mode is invisible to argent's framebuffer-based screenshot tool, so an agent reports success while the developer sees a black window.
+
+  Argent picks `-gpu swiftshader` on Linux for universal compatibility: it sidesteps the host GL stack entirely and renders via the emulator's bundled SwiftShader. On modern multi-core machines this is indistinguishably smooth from hardware-accelerated `-gpu host` (and far faster than lavapipe).
+
+  Override with the `ARGENT_EMULATOR_GPU_MODE` env var if you've verified `-gpu host` works on your machine (typical single-GPU Mesa box with a healthy X session):
+
+  ```bash
+  ARGENT_EMULATOR_GPU_MODE=host argent ...
+  ```
+
+  Argent's boot-device preflight prints a warning if `/dev/kvm` isn't usable — the condition that causes a 10–50× TCG-vs-KVM slowdown.
+
+- **System image.** Prefer the `default` or `google_apis` variants of `x86_64` system images for headless agent workflows; `google_apis_playstore` adds noticeable boot-time CPU churn from Play services. Always pick `x86_64` on Intel/AMD hosts — ARM images run via QEMU translation and are dramatically slower.
+
+- **AVD config.** AVDs created via `avdmanager create avd` default to `hw.gpu.enabled=no`. Argent overrides this with an explicit `-gpu` arg at launch (so the on-disk config doesn't need editing). For the smoothest experience under heavy native builds (gradle compilations alongside the AVD), bump the AVD's RAM and CPU count — edit `~/.android/avd/<name>.avd/config.ini`:
+
+  ```
+  hw.ramSize = 8192
+  hw.cpu.ncore = 6
+  vm.heapSize = 512
+  ```
+
+  Stock 2 GB / 4 vCPU AVDs can be CPU-starved into wedged-system_server states by a concurrent gradle/Kotlin compile.
+
+- **Headless / CI mode (`ARGENT_EMULATOR_NO_WINDOW=1`).** Argent shows the emulator window by default so a local developer can see the AVD UI. In a headless context — CI runner, container, or a Wayland-only session where the emulator's bundled Qt has no `wayland` platform plugin and SIGABRTs on the crash-consent dialog — opt out by exporting `ARGENT_EMULATOR_NO_WINDOW=1` before starting the tool-server. This appends `-no-window` to the spawn args, selecting `qemu-system-x86_64-headless` which doesn't need a Qt window. Argent's screencap-based screenshot tool reads the in-memory framebuffer correctly without a visible window.
+
 #### Run `init` in your project
 
 From your project root:
@@ -60,14 +100,17 @@ argent init
 
 ## CLI Reference
 
-| Command            | Description                                                 |
-| ------------------ | ----------------------------------------------------------- |
-| `argent init`      | Install globally and configure MCP in the current workspace |
-| `argent install`   | Alias for `init` command                                    |
-| `argent update`    | Pull the latest version and refresh workspace configuration |
-| `argent remove`    | Unregister the MCP server and uninstall the package         |
-| `argent uninstall` | Alias for `remove` command                                  |
-| `argent mcp`       | Start MCP server instance, used internally by agent         |
+| Command            | Description                                                            |
+| ------------------ | ---------------------------------------------------------------------- |
+| `argent init`      | Install globally and configure MCP in the current workspace            |
+| `argent install`   | Alias for `init` command                                               |
+| `argent update`    | Pull the latest version and refresh workspace configuration            |
+| `argent remove`    | Unregister the MCP server and uninstall the package                    |
+| `argent uninstall` | Alias for `remove` command                                             |
+| `argent mcp`       | Start MCP server instance, used internally by agent                    |
+| `argent enable`    | Enable a predefined feature flag (`--scope project` for project-local) |
+| `argent disable`   | Disable a feature flag (`--scope project` for project-local)           |
+| `argent flags`     | List available feature flags and their state                           |
 
 ## Supported Editors
 
@@ -99,7 +142,7 @@ Argent uses a mixed licensing model.
 
 **Source code** is released under the [Apache License 2.0](LICENSE.txt).
 
-**Proprietary binaries** (the `bin/simulator-server` and `bin/ax-service` executables and the `.dylib` files in `native-devtools-ios`) are the intellectual property of Software Mansion S.A. and are licensed solely for use within this project. Decompiling, reverse-engineering, or redistributing them without explicit written permission is prohibited.
+**Proprietary binaries** (the per-platform `bin/<platform>/simulator-server` and `bin/darwin/ax-service` executables and the `.dylib` files in `native-devtools-ios`) are the intellectual property of Software Mansion S.A. and are licensed solely for use within this project. Decompiling, reverse-engineering, or redistributing them without explicit written permission is prohibited.
 
 By using Argent, you acknowledge and agree to this structure. See [LICENSE](https://github.com/software-mansion/argent/blob/main/LICENSE.txt) for full details.
 

package/assets/argent.tracecfg.pbtxt

@@ -0,0 +1,133 @@
+# Argent — Perfetto TraceConfig (text protobuf)
+#
+# The Android twin of packages/tool-server/src/utils/ios-profiler/Argent.tracetemplate.
+# Pushed to the device and consumed by `perfetto --txt -c <this-file>`.
+#
+# In production this is template-substituted: TARGET_CMDLINE_PLACEHOLDER and
+# TARGET_PACKAGE_PLACEHOLDER are replaced with the auto-detected foreground app
+# (mirrors detectRunningApp in native-profiler-start.ts:46-117).
+#
+# Buffers sized for ~5 minutes of capture on a typical RN app. Adjust if you
+# extend RECORDING_CAP_MS beyond the iOS 10-min default.
+
+# duration_ms is intentionally omitted — the recording is stopped explicitly via
+# `kill -TERM <perfetto-pid>` from native-profiler-stop, mirroring xctrace SIGINT.
+# If you want a hard cap, set duration_ms here AND keep the stop signal as a
+# safety net (the perfetto daemon will exit either way).
+
+buffers: {
+  size_kb: 65536          # 64 MB — CPU samples + atrace slices
+  fill_policy: DISCARD    # ring-buffer once full; we want recency over completeness
+}
+buffers: {
+  size_kb: 16384          # 16 MB — frame timeline + ANRs (sparser, smaller buffer)
+  fill_policy: DISCARD
+}
+
+# ----------------------------------------------------------------------------
+# Data source 1: CPU callstack sampling (the Time Profiler equivalent)
+# ----------------------------------------------------------------------------
+# Outputs perf_sample rows we GROUP BY callsite + thread in queries/cpu-hotspots.sql.
+# target_cmdline restricts sampling to the user's app — system-wide noise is
+# excluded at capture time, not analysis time.
+data_sources: {
+  config: {
+    name: "linux.perf"
+    target_buffer: 0
+    perf_event_config: {
+      timebase: {
+        # 100 Hz software CPU clock — matches the iOS coresampler2 default.
+        # Adjust higher (e.g. 1000) for tight CPU-bound investigations.
+        counter: SW_CPU_CLOCK
+        frequency: 100
+        timestamp_clock: PERF_CLOCK_MONOTONIC
+      }
+      callstack_sampling: {
+        scope: {
+          target_cmdline: "TARGET_CMDLINE_PLACEHOLDER"
+          # Drop the next two if Perfetto warns about missing /proc access:
+          # target_installed_by: "PLAY_STORE"  # only for production-builds w/ trusted source
+        }
+        kernel_frames: true     # include kernel callsites; great for "stuck in syscall" diagnosis
+      }
+    }
+  }
+}
+
+# ----------------------------------------------------------------------------
+# Data source 2: kernel scheduler events + atrace app slices
+# ----------------------------------------------------------------------------
+# Feeds thread_state table; used in queries/ui-hangs.sql to attribute main-thread
+# stalls to "blocked on I/O", "blocked on lock", etc.
+#
+# atrace categories / atrace_apps are nested in ftrace_config (NOT as a separate
+# `android.atrace` data source with `atrace_config` — that field was removed
+# from DataSourceConfig and is rejected by perfetto >= v45). See
+# https://perfetto.dev/docs/data-sources/atrace.
+data_sources: {
+  config: {
+    name: "linux.ftrace"
+    target_buffer: 0
+    ftrace_config: {
+      ftrace_events: "sched/sched_switch"
+      ftrace_events: "sched/sched_wakeup"
+      ftrace_events: "sched/sched_wakeup_new"
+      ftrace_events: "sched/sched_process_exit"
+      # sched_blocked_reason gives us the "main thread blocked on what?" answer.
+      ftrace_events: "sched/sched_blocked_reason"
+      # binder events — surfaces IPC contention on the main thread.
+      ftrace_events: "binder/binder_transaction"
+      ftrace_events: "binder/binder_transaction_received"
+      # System atrace categories — see `adb shell atrace --list_categories` for the full set.
+      atrace_categories: "view"        # View system: measure/layout/draw
+      atrace_categories: "gfx"         # SurfaceFlinger/HWUI
+      atrace_categories: "wm"          # WindowManager
+      atrace_categories: "am"          # ActivityManager
+      atrace_categories: "input"       # input dispatch (key/touch)
+      atrace_categories: "binder_driver"
+      atrace_categories: "dalvik"      # GC, JIT, class loading
+      atrace_categories: "ss"          # SystemServer
+      atrace_categories: "aidl"        # AIDL call slices
+      # Per-app categories — capture slices that the app itself emits via Trace.beginSection.
+      atrace_apps: "TARGET_PACKAGE_PLACEHOLDER"
+    }
+  }
+}
+
+# ----------------------------------------------------------------------------
+# Data source 4: SurfaceFlinger frame timeline (the Hangs equivalent + reason codes)
+# ----------------------------------------------------------------------------
+# Produces expected_frame_timeline_slice and actual_frame_timeline_slice rows.
+# A frame whose actual end > expected end is a jank; the jank_type enum tells us
+# whose fault (AppDeadlineMissed / BufferStuffing / SfCpu / SfGpu / ...).
+data_sources: {
+  config: {
+    name: "android.surfaceflinger.frametimeline"
+    target_buffer: 1
+  }
+}
+
+# ----------------------------------------------------------------------------
+# Data source 5: process stats — for the weak RSS-growth signal until phase-2 leak detection lands
+# ----------------------------------------------------------------------------
+data_sources: {
+  config: {
+    name: "linux.process_stats"
+    target_buffer: 1
+    process_stats_config: {
+      proc_stats_poll_ms: 1000           # 1 s cadence is enough for RSS-trend detection
+      scan_all_processes_on_start: true
+    }
+  }
+}
+
+# Drop incremental_state every 5 s so we recover symbol tables even if perfetto crashes
+# mid-recording — partial trace is still useful (mirrors iOS handleXctraceExit recovery).
+incremental_state_config: {
+  clear_period_ms: 5000
+}
+
+# When the on-device file is large, write it directly instead of going through the
+# 32 MB ring buffer before flushing. Avoids data loss on long recordings.
+write_into_file: true
+file_write_period_ms: 2500

package/assets/queries/README.md

@@ -0,0 +1,93 @@
+# Argent Android profiler — PerfettoSQL queries
+
+These `*.sql` files are the source of truth for every query the Argent Android
+native profiler runs against a captured `.pftrace`. They run through the
+in-process Perfetto WASM trace-processor from the tool-server pipeline
+(`runTpQuery` / `runTpInline` in
+`tool-server/src/utils/android-profiler/pipeline/run-tp.ts`).
+
+The directory lives in `native-devtools-android`; the bundler copies it next to
+the bundled tool-server at publish time, so `traceProcessorQueriesDir()` resolves
+the same path in dev and packaged builds.
+
+Each `.sql` header documents only what's specific to that query. The shared
+conventions live here so they aren't repeated nine times.
+
+## What each file is for
+
+| File                           | Consumed by                                  | Purpose                                                          |
+| ------------------------------ | -------------------------------------------- | ---------------------------------------------------------------- |
+| `trace-bounds.sql`             | every analyze run                            | Trace start timestamp anchor (see _Timestamps_).                 |
+| `ui-hangs.sql`                 | analyze                                      | ANRs + app-jank frames → one hang per frame.                     |
+| `cpu-hotspots.sql`             | analyze                                      | Per-thread hottest leaf functions + burst windows.               |
+| `thread-breakdown.sql`         | profiler-stack-query `mode=thread_breakdown` | Per-thread sample share.                                         |
+| `hang-folds-batched.sql`       | batched analyze                              | State breakdown + GC overlap for ALL hangs in one batched query. |
+| `hang-state-breakdown.sql`     | drill-down (single hang)                     | Main-thread state breakdown for one hang window.                 |
+| `hang-main-thread-samples.sql` | profiler-stack-query `mode=hang_stacks`      | Main-thread CPU samples inside one hang window.                  |
+| `function-callers.sql`         | profiler-stack-query `mode=function_callers` | Callsites that hit one hot function.                             |
+| `memory-rss.sql`               | analyze                                      | RSS-growth weak signal (not leak detection).                     |
+
+## Conventions
+
+### Parameters via the `_argent_args` view
+
+Each query declares its runtime parameters once in a small `_argent_args`
+PERFETTO VIEW at the top, then references them by name:
+
+```sql
+DROP VIEW IF EXISTS _argent_args;
+CREATE PERFETTO VIEW _argent_args AS
+SELECT '{{TARGET_PROCESS}}' AS target_process;
+...
+WHERE p.name = (SELECT target_process FROM _argent_args)
+```
+
+This keeps each value at one self-documenting site, and the body reads like
+normal SQL instead of scattering bare tokens through it.
+
+### `{{NAME}}` template tokens
+
+`{{NAME}}` placeholders are resolved by `renderSqlTemplate` (`run-tp.ts`) before
+the query runs. It throws on a mismatch either way: a `{{NAME}}` with no
+substitution, or a substitution the template never uses — catching forgotten or
+stale tokens early.
+
+Values are **not** escaped for SQL injection — they're interpolated into the
+query string passed to the in-process engine, so callers must validate them
+(numeric for `*_ns`; identifier-shaped for process/thread/function names) — see
+`hang-folds-batched.ts` for the strictest example.
+
+Most queries render through `runTpQuery`. `hang-folds-batched.sql` is the
+exception: `pipeline/hang-folds-batched.ts` loads it directly, builds the
+`{{HANG_WINDOWS_VALUES}}` tuple list, and resolves it through the same renderer.
+
+### Timestamps are CLOCK_MONOTONIC nanoseconds
+
+Perfetto's `ts` columns are CLOCK_MONOTONIC nanoseconds since device boot — not
+trace-relative. `trace-bounds.sql` returns the earliest `ts`; the JS side
+subtracts it (`traceStartMs`) to normalise every emitted timestamp to
+trace-relative ns. Any native ms/ns a query emits (burst windows, hang bounds)
+stays native until JS does that subtraction.
+
+### One trace parse per warm engine → batch
+
+Re-parsing the whole trace on every query is expensive (~1.3 s for 76 MB), so
+one query per item is quadratic — the per-hang loop this replaced took ~47 min
+for 1013 hangs. Instead, fold many per-item queries into a single script with
+`CREATE PERFETTO VIEW`/`TABLE` + a terminal `UNION ALL SELECT`, joining over a
+runtime-built table. See `hang-folds-batched.sql`: one ~1.7 s run regardless of
+hang count. Only the final SELECT reaches stdout.
+
+### Two copies of the hang state breakdown — keep them in sync
+
+The main-thread state-breakdown logic lives in two places:
+
+- `hang-state-breakdown.sql` — single window, drill-down path;
+- the `argent_hang_state` view in `hang-folds-batched.sql` — all windows.
+
+Keep the window-clipping math in sync: each `thread_state` slice is clipped to
+the hang window (`MIN(ts.ts + ts.dur, end) - MAX(ts.ts, start)`) so a slice
+straddling a boundary only counts its overlap. A plain `SUM(dur)` over slices
+that merely start inside the window can overshoot its length.
+
+There's no standalone GC query — GC overlap lives only in the batched file.

package/assets/queries/cpu-hotspots.sql

@@ -0,0 +1,106 @@
+-- Argent — CPU hotspots.
+--
+-- One output row per (thread_name, leaf_function) — the leaf frame name IS the
+-- dominant function, so one SQL row maps 1:1 to one aggregateCpuHotspots group
+-- (we drop leaf_mapping, which was unused and only fragmented the grouping).
+-- The aggregator normalises the thread name and applies severity bands.
+--
+-- Burst windows are computed here in SQL rather than shipping every sample
+-- timestamp (the old `GROUP_CONCAT(ts_ns)` shipped ~54 KB of timestamps that
+-- JS re-parsed). A "burst" is a run of samples for the same (thread, function)
+-- with no gap larger than the burst threshold. LAG() finds the gaps, a running
+-- SUM() assigns burst ids, and we emit one `start_ms:end_ms:count` triple per
+-- burst. start_ms/end_ms are native ms (README.md, "Timestamps"); the JS side
+-- subtracts traceStartMs to make them trace-relative.
+--
+-- The total_samples column is repeated on every output row so the JS side can
+-- compute weight % without a second round-trip.
+--
+-- Placeholders (declared in the _argent_args view below): target_process —
+-- package / cmdline; burst_gap_ns — burst gap threshold in ns (BURST_GAP_MS ×
+-- 1e6 from aggregate.ts, so the SQL and iOS-JS burst paths share one constant).
+-- See README.md for the shared _argent_args / template-token conventions.
+
+DROP VIEW IF EXISTS _argent_args;
+CREATE PERFETTO VIEW _argent_args AS
+SELECT
+  '{{TARGET_PROCESS}}' AS target_process,
+  {{BURST_GAP_NS}}     AS burst_gap_ns;
+
+DROP VIEW IF EXISTS argent_app_total_samples;
+CREATE PERFETTO VIEW argent_app_total_samples AS
+SELECT COUNT(*) AS total_samples
+FROM perf_sample ps
+JOIN thread t USING (utid)
+JOIN process p USING (upid)
+WHERE p.name = (SELECT target_process FROM _argent_args);
+
+WITH samples AS (
+  SELECT
+    ps.ts            AS ts_ns,
+    t.name           AS thread_name,
+    t.is_main_thread AS is_main_thread,
+    spf.name         AS leaf_function
+  FROM perf_sample ps
+  JOIN thread t USING (utid)
+  JOIN process p USING (upid)
+  LEFT JOIN stack_profile_callsite spc ON ps.callsite_id = spc.id
+  LEFT JOIN stack_profile_frame    spf ON spc.frame_id   = spf.id
+  WHERE p.name = (SELECT target_process FROM _argent_args)
+),
+-- Flag each sample whose gap to the previous sample of the same
+-- thread+function exceeds the burst threshold. LAG over the first sample is
+-- NULL, so its CASE yields 0 — the opening sample never counts as a gap.
+flagged AS (
+  SELECT
+    thread_name, is_main_thread, leaf_function, ts_ns,
+    CASE
+      WHEN ts_ns - LAG(ts_ns) OVER w > (SELECT burst_gap_ns FROM _argent_args) THEN 1
+      ELSE 0
+    END AS is_new_burst
+  FROM samples
+  WINDOW w AS (PARTITION BY thread_name, leaf_function ORDER BY ts_ns)
+),
+-- Running sum of the gap flags == a monotonically increasing burst id within
+-- each thread+function partition.
+ided AS (
+  SELECT
+    thread_name, is_main_thread, leaf_function, ts_ns,
+    SUM(is_new_burst) OVER (
+      PARTITION BY thread_name, leaf_function
+      ORDER BY ts_ns
+      ROWS UNBOUNDED PRECEDING
+    ) AS burst_id
+  FROM flagged
+),
+-- Collapse each burst to [start_ns, end_ns, sample_count]. Every sample lands
+-- in exactly one burst, so summing burst counts == total samples and
+-- MIN/MAX of burst bounds == first/last sample of the (thread, function).
+per_burst AS (
+  SELECT
+    thread_name, leaf_function,
+    MAX(is_main_thread) AS is_main_thread,
+    MIN(ts_ns)          AS burst_start_ns,
+    MAX(ts_ns)          AS burst_end_ns,
+    COUNT(*)            AS burst_count
+  FROM ided
+  GROUP BY thread_name, leaf_function, burst_id
+)
+SELECT
+  thread_name,
+  MAX(is_main_thread) AS is_main_thread,
+  leaf_function,
+  SUM(burst_count)    AS sample_count,
+  MIN(burst_start_ns) AS first_ts_ns,
+  MAX(burst_end_ns)   AS last_ts_ns,
+  (SELECT total_samples FROM argent_app_total_samples) AS total_samples,
+  -- Compact `start_ms:end_ms:count` triples, comma-separated. JS sorts them
+  -- by start before display, so GROUP_CONCAT order is irrelevant.
+  GROUP_CONCAT(
+    (burst_start_ns / 1000000) || ':' || (burst_end_ns / 1000000) || ':' || burst_count,
+    ','
+  ) AS burst_windows
+FROM per_burst
+GROUP BY thread_name, leaf_function
+ORDER BY sample_count DESC
+LIMIT 200;

package/assets/queries/function-callers.sql

@@ -0,0 +1,62 @@
+-- Argent — callers/callees for a single hot function.
+--
+-- Drill-down for profiler-stack-query mode=function_callers. Returns one row
+-- per unique callsite (+ owning thread) whose LEAF frame matches the requested
+-- function, callstack text unwound via experimental_annotated_callstack.
+--
+-- Function matching is a literal, case-sensitive SUBSTRING test (INSTR), not
+-- exact equality: perf frame names are stored MANGLED (e.g. the source symbol
+-- "uncompressLZW" lives inside "_Z13uncompressLZWP7_JNIEnv..."), so an exact
+-- match on a demangled name would miss. The Itanium length prefix means the
+-- bare symbol still appears verbatim, so a substring catches it. matched_function
+-- exposes the real leaf name and is_exact flags the rows that matched verbatim
+-- (ordered first) so a precise query isn't drowned by incidental substrings.
+--
+-- Thread filter (the thread_name placeholder), resolved caller-side:
+--   '__ALL__'   → all threads; each row is labelled with its thread so the
+--                 caller can see where the function runs without knowing names.
+--   '__MAIN__'  → the UI/main thread, matched via thread.is_main_thread. The
+--                 main thread's raw perf `comm` is the truncated package
+--                 (e.g. ".blueskyweb.app"), never the literal "main", so a
+--                 name match would silently miss it.
+--   <name>      → exact thread name match (raw perf `comm`).
+-- Sentinels are upper-snake so they can't collide with a real comm name.
+--
+-- Placeholders (declared in the _argent_args view below): target_process —
+-- package / cmdline; thread_name — see above; function_name — leaf function.
+-- See README.md for the shared _argent_args / template-token conventions.
+
+DROP VIEW IF EXISTS _argent_args;
+CREATE PERFETTO VIEW _argent_args AS
+SELECT
+  '{{TARGET_PROCESS}}' AS target_process,
+  '{{THREAD_NAME}}'    AS thread_name,
+  '{{FUNCTION_NAME}}'  AS function_name;
+
+SELECT
+  t.name AS thread_name,
+  MAX(t.is_main_thread) AS is_main_thread,
+  spf.name AS matched_function,
+  (spf.name = (SELECT function_name FROM _argent_args)) AS is_exact,
+  (
+    SELECT GROUP_CONCAT(inner_spf.name, ' <- ' ORDER BY eac.depth DESC)
+    FROM experimental_annotated_callstack(ps.callsite_id) eac
+    LEFT JOIN stack_profile_frame inner_spf ON eac.frame_id = inner_spf.id
+  ) AS callstack_text,
+  COUNT(*) AS occurrences
+FROM perf_sample ps
+JOIN thread t USING (utid)
+JOIN process p USING (upid)
+LEFT JOIN stack_profile_callsite spc ON ps.callsite_id = spc.id
+LEFT JOIN stack_profile_frame    spf ON spc.frame_id   = spf.id
+WHERE p.name = (SELECT target_process FROM _argent_args)
+  AND spf.name IS NOT NULL
+  AND INSTR(spf.name, (SELECT function_name FROM _argent_args)) > 0
+  AND (
+    (SELECT thread_name FROM _argent_args) = '__ALL__'
+    OR ((SELECT thread_name FROM _argent_args) = '__MAIN__' AND t.is_main_thread = 1)
+    OR t.name = (SELECT thread_name FROM _argent_args)
+  )
+GROUP BY ps.callsite_id, t.name, spf.name
+ORDER BY is_exact DESC, occurrences DESC
+LIMIT 50;

package/assets/queries/hang-folds-batched.sql

@@ -0,0 +1,88 @@
+-- Argent — batched per-hang annotation (state breakdown + GC overlap).
+--
+-- Computes the main-thread state breakdown AND ART GC overlap for EVERY hang
+-- window in ONE batched trace-processor query, via a JOIN over the
+-- runtime-built `argent_hang_windows` table instead of looping one query
+-- per hang. See README.md, "One trace parse per warm engine → batch".
+--
+-- Single source of truth for the batched analyze path. The `argent_hang_state`
+-- view below mirrors the standalone, single-window `hang-state-breakdown.sql`
+-- (drill-down) — keep the two consistent (README.md, "Two copies of the hang
+-- state breakdown"). There is no standalone GC query; GC overlap lives here
+-- only (drill-down never surfaced GC).
+--
+-- Loaded directly by pipeline/hang-folds-batched.ts, not the generic runTpQuery
+-- path.
+--
+-- Placeholders: target_process (declared in the _argent_args view below); and a
+-- hang-windows token in the `FROM (VALUES ...)` below, which the TS replaces
+-- with one `(hang_index, start_ns, end_ns)` tuple per hang. That windows token
+-- must NOT appear anywhere else (e.g. this header): its replacement spans
+-- multiple lines and would break a comment, so it is referenced only obliquely.
+-- See README.md for the shared _argent_args / template-token conventions.
+
+DROP VIEW IF EXISTS _argent_args;
+CREATE PERFETTO VIEW _argent_args AS
+SELECT '{{TARGET_PROCESS}}' AS target_process;
+
+DROP TABLE IF EXISTS argent_hang_windows;
+CREATE PERFETTO TABLE argent_hang_windows AS
+SELECT
+  column1 AS hang_index,
+  column2 AS start_ns,
+  column3 AS end_ns
+FROM (VALUES
+  {{HANG_WINDOWS_VALUES}}
+);
+
+DROP VIEW IF EXISTS argent_hang_state;
+CREATE PERFETTO VIEW argent_hang_state AS
+SELECT
+  hw.hang_index                     AS hang_index,
+  'state'                           AS row_kind,
+  ts.state                          AS state_v,
+  ts.blocked_function               AS blocked_function_v,
+  -- Clip each thread_state slice to the hang window so a state that begins
+  -- before the window or extends past its end contributes only the overlapping
+  -- duration. Plain SUM(dur) over states whose START falls in the window can
+  -- otherwise exceed the window length (SmartPerfetto time-interval JOIN).
+  CAST(SUM(MIN(ts.ts + ts.dur, hw.end_ns) - MAX(ts.ts, hw.start_ns)) AS TEXT) AS total_dur_ns_v,
+  CAST(COUNT(*)    AS TEXT)         AS occurrences_v,
+  NULL                              AS gc_reason_v,
+  NULL                              AS gc_ts_ns_v,
+  NULL                              AS gc_dur_ns_v
+FROM argent_hang_windows hw
+JOIN thread_state ts
+  ON ts.ts < hw.end_ns AND ts.ts + ts.dur > hw.start_ns
+JOIN thread t USING (utid)
+JOIN process p USING (upid)
+WHERE p.name = (SELECT target_process FROM _argent_args)
+  AND t.is_main_thread
+GROUP BY hw.hang_index, ts.state, ts.blocked_function;
+
+DROP VIEW IF EXISTS argent_hang_gc;
+CREATE PERFETTO VIEW argent_hang_gc AS
+SELECT
+  hw.hang_index                     AS hang_index,
+  'gc'                              AS row_kind,
+  NULL                              AS state_v,
+  NULL                              AS blocked_function_v,
+  NULL                              AS total_dur_ns_v,
+  NULL                              AS occurrences_v,
+  s.name                            AS gc_reason_v,
+  CAST(s.ts  AS TEXT)               AS gc_ts_ns_v,
+  CAST(s.dur AS TEXT)               AS gc_dur_ns_v
+FROM argent_hang_windows hw
+JOIN slice s
+  ON s.ts < hw.end_ns AND s.ts + s.dur > hw.start_ns
+JOIN thread_track tt ON s.track_id = tt.id
+JOIN thread t USING (utid)
+JOIN process p USING (upid)
+WHERE p.name = (SELECT target_process FROM _argent_args)
+  AND t.is_main_thread
+  AND s.name GLOB 'GC*';
+
+SELECT * FROM argent_hang_state
+UNION ALL
+SELECT * FROM argent_hang_gc
+ORDER BY hang_index, row_kind;

package/assets/queries/hang-main-thread-samples.sql

@@ -0,0 +1,32 @@
+-- Argent — main-thread CPU samples during a hang window.
+--
+-- Drill-down for profiler-stack-query mode=hang_stacks. Returns one row per
+-- perf_sample on the main thread inside the hang window, with the full
+-- callstack text unwound via experimental_slice_callstack.
+--
+-- Placeholders (declared in the _argent_args view below): target_process —
+-- package / cmdline; hang_start_ns / hang_end_ns — hang window bounds, native ns.
+-- See README.md for the shared _argent_args / template-token conventions.
+
+DROP VIEW IF EXISTS _argent_args;
+CREATE PERFETTO VIEW _argent_args AS
+SELECT
+  '{{TARGET_PROCESS}}' AS target_process,
+  {{HANG_START_NS}}    AS hang_start_ns,
+  {{HANG_END_NS}}      AS hang_end_ns;
+
+SELECT
+  ps.ts AS ts_ns,
+  (
+    SELECT GROUP_CONCAT(inner_spf.name, ' <- ' ORDER BY eac.depth DESC)
+    FROM experimental_annotated_callstack(ps.callsite_id) eac
+    LEFT JOIN stack_profile_frame inner_spf ON eac.frame_id = inner_spf.id
+  ) AS callstack_text
+FROM perf_sample ps
+JOIN thread t USING (utid)
+JOIN process p USING (upid)
+WHERE p.name = (SELECT target_process FROM _argent_args)
+  AND t.is_main_thread
+  AND ps.ts BETWEEN (SELECT hang_start_ns FROM _argent_args)
+                AND (SELECT hang_end_ns FROM _argent_args)
+ORDER BY ts_ns;

package/assets/queries/hang-state-breakdown.sql

@@ -0,0 +1,44 @@
+-- Argent — main-thread state breakdown during a single hang window.
+--
+-- Called once per UiHang from the drill-down path (pipeline/index.ts
+-- renderHangStacksAndroid). The aggregator folds the rows back into the hang
+-- object as `stateBreakdown`.
+--
+-- iOS literally cannot produce this — Time Profiler only samples while a
+-- thread is *running*, so a 500ms hang spent blocked on a futex shows up as
+-- an empty sample window. ftrace gives us the partition for free.
+--
+-- Single-window twin of the `argent_hang_state` view in hang-folds-batched.sql;
+-- keep the two consistent (see README.md, "Two copies of the hang state
+-- breakdown").
+--
+-- Placeholders (declared in the _argent_args view below): target_process —
+-- package / cmdline; hang_start_ns / hang_end_ns — hang window bounds, native ns.
+-- See README.md for the shared _argent_args / template-token conventions.
+
+DROP VIEW IF EXISTS _argent_args;
+CREATE PERFETTO VIEW _argent_args AS
+SELECT
+  '{{TARGET_PROCESS}}' AS target_process,
+  {{HANG_START_NS}}    AS hang_start_ns,
+  {{HANG_END_NS}}      AS hang_end_ns;
+
+SELECT
+  state,
+  blocked_function,
+  -- Clip each thread_state slice to the hang window so a state that begins
+  -- before the window or extends past its end contributes only the overlapping
+  -- duration. Plain SUM(dur) over states whose START falls in the window can
+  -- otherwise exceed the window length (SmartPerfetto time-interval JOIN).
+  SUM(MIN(ts.ts + ts.dur, (SELECT hang_end_ns FROM _argent_args))
+      - MAX(ts.ts, (SELECT hang_start_ns FROM _argent_args))) AS total_dur_ns,
+  COUNT(*) AS occurrences
+FROM thread_state ts
+JOIN thread t USING (utid)
+JOIN process p USING (upid)
+WHERE p.name = (SELECT target_process FROM _argent_args)
+  AND t.is_main_thread
+  AND ts.ts < (SELECT hang_end_ns FROM _argent_args)
+  AND ts.ts + ts.dur > (SELECT hang_start_ns FROM _argent_args)
+GROUP BY state, blocked_function
+ORDER BY total_dur_ns DESC;