frameworks-base.patch

diff --git a/README.md b/README.md
new file mode 100644
index 000000000000..e169b08cfd3e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,489 @@
+# MobileAgentService — AOSP Framework Modifications
+
+Platform-layer mechanisms for Android that enable GUI agents to operate applications
+efficiently and concurrently with users—without occupying the screen, competing for
+GPU resources, or relying on the screenshot-to-pixel pipeline.
+
+**Branch**: `exp_agent_dirty_readiness_stop` (based on AOSP `25Q3-release`, Android 16)
+
+This branch adds the production dirty/readiness return policy on top of the
+DisplayList export, on-demand traversal, foreground checkpoint, and traversal-only
+freeze branches. Its observation contract is deliberately narrow: after an Agent
+action has been injected, return the first complete active DisplayList for which
+the current UI pipeline is quiet. It does not wait for unrelated future network or
+timer updates to make the page permanently identical.
+
+## Architecture
+
+Three components spanning the windowing system and rendering pipeline:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ C1: Isolated Agent Task Execution (services/wm)         │
+│   ActivityStarter override → same-process dual-instance  │
+│   on isolated Virtual Display                            │
+├─────────────────────────────────────────────────────────┤
+│ C2: DisplayList as UI Representation (hwui)              │
+│   RenderNode tree → JSON export via dumpsys gfxinfo      │
+├─────────────────────────────────────────────────────────┤
+│ C3: On-Demand Perception, GPU Bypassed (view/hwui)       │
+│   Dual-phase traversal: settle (measure+layout only)     │
+│   → single record pass → zero GPU via mSyncOnlyFrame    │
+│   Per-window freeze + stability detection + profiling    │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Modified Files
+
+| File | Purpose |
+|------|---------|
+| `core/java/android/view/ViewRootImpl.java` | Freeze, dual-phase traversal, dirty/readiness observation return, profiling counters; **persistent GPU bypass (`mAgentPersistentNoDrawOverride` tri-state + process-wide `sAgentPersistentNoDrawDefault`, first-frame `mAgentHasDrawnOnce` bootstrap)** |
+| `core/java/android/view/Choreographer.java` | `doFrameForAgent()` synthetic VSYNC pump |
+| `core/java/android/view/ThreadedRenderer.java` | `syncForAgent()` record+sync without GPU draw |
+| `core/java/android/view/WindowManagerGlobal.java` | Parse fresh/nodraw/vsyncN/freeze/traversalfreeze/readysettle/readywaitN and profiling controls; inject agent stats into DL output |
+| `graphics/java/android/graphics/HardwareRenderer.java` | `setSyncOnlyNextFrame()` public hidden API |
+| `libs/hwui/jni/android_graphics_HardwareRenderer.cpp` | JNI bridge for setSyncOnlyNextFrame |
+| `libs/hwui/renderthread/DrawFrameTask.{h,cpp}` | `mSyncOnlyFrame` skips GPU draw after syncFrameState |
+| `libs/hwui/renderthread/RenderProxy.{h,cpp}` | setSyncOnlyNextFrame passthrough |
+| `libs/hwui/pipeline/skia/FlatExportOpsCanvas.h` | C2 export canvas: maps all op bounds to device (screen) space via `getLocalToDeviceAs3x3()`; emits per-run `{font, glyphs}` for external reverse-cmap |
+| `services/core/.../wm/ActivityStarter.java` | C1: detect agent display, override to LAUNCH_MULTIPLE |
+| `services/core/.../wm/ActivityTaskManagerService.java` | `isAgentDisplay()` / mAgentDisplayIds registry |
+| `tools/dlglyph/dl_glyph_decode.py` | Host-side post-processor: reverses glyph IDs back to UTF-8 via fontTools |
+| *(frameworks/native)* `services/surfaceflinger/SurfaceFlinger.{cpp,h}` | **L3 SF compose-bypass: backdoor code 1050 skips compositing an agent VD by layerStack — cuts SF composition GPU + back-pressures video producers without touching window/display/input state (separate repo)** |
+
+## Quick Start: Build & Deploy
+
+```bash
+# Prerequisites: AOSP source tree with this branch checked out at frameworks/base
+cd <AOSP_ROOT>
+source build/envsetup.sh
+lunch gsi_arm64-trunk_staging-userdebug  # or your target
+
+# Build (choose based on what you modified):
+m framework-minus-apex -j$(nproc)  # core/java + graphics/java changes
+m libhwui -j$(nproc)               # libs/hwui C++ changes
+m services -j$(nproc)              # services/wm C1 changes
+
+# Deploy to device (must be rooted + remounted):
+SERIAL=<your_device>
+adb -s $SERIAL root && adb -s $SERIAL remount
+
+OUT=out/target/product/<target>/system/framework
+adb -s $SERIAL push $OUT/framework.jar /system/framework/
+adb -s $SERIAL push $OUT/services.jar /system/framework/
+adb -s $SERIAL push out/target/product/<target>/system/lib64/libhwui.so /system/lib64/
+
+# Clear dalvik cache + soft reboot (NEVER hard reboot - overlayfs will lose changes)
+adb -s $SERIAL shell "rm -rf /data/dalvik-cache/*/system@framework@*"
+adb -s $SERIAL shell stop && sleep 3 && adb -s $SERIAL shell start
+```
+
+## API Reference
+
+All interaction through `dumpsys gfxinfo <pkg> displaylist [subparams]`:
+
+| Subparam | Effect |
+|----------|--------|
+| `fresh` | Force on-demand traversal (dual-phase) |
+| `nodraw` | Skip GPU draw (sync-only, zero GPU/SF) |
+| `vsyncN` | Pump up to N synthetic VSYNC frames in Phase 1 (default 3 if no number) |
+| `freeze` | Freeze agent window (stop real-VSYNC self-rendering) |
+| `unfreeze` | Resume normal rendering |
+| `traversalfreeze` | Stop Agent traversal scheduling while preserving the current active DL and renderer content. Use this between Agent steps. |
+| `traversalunfreeze` | Resume Agent traversal scheduling without reconstructing renderer content. |
+| `asyncsettle` | Run settle passes as posted foreground-yielding continuations instead of one synchronous loop. |
+| `readysettle` | Start dirty/readiness settle on the visible Agent root, publish one final active DL, and traversal-freeze atomically. Implies `fresh asyncsettle`. |
+| `readywaitN` | Set the `readysettle` wall-clock fallback to N milliseconds. This is an upper bound, not a minimum sleep. Default: 2000. |
+| `agentstate` | Return compact per-root control/readiness JSON without exporting renderer data. |
+| `gpubypass` | Persistent no-draw: EVERY traversal (incl. the app's own real-VSYNC frames while unfrozen) skips the GPU draw. Process-wide default, inherited by newly-navigated agent windows automatically. Agent-UI only. Independent of freeze. |
+| `nogpubypass` | Disable persistent no-draw (resume real drawing) |
+| `reset` | Reset per-window profiling counters |
+
+### Output Format
+
+Per-window header with agent stats followed by DL JSON:
+```
+<pkg/activity/VRI@hash> (visibility=N){"settled":B,"phase1_traversals":P1,"phase2_traversals":P2}{"frame":"flat_render","width":W,"height":H,"nodes":[...]}
+```
+
+- `settled=true`: Phase 1 exited via early-break (view tree stable)
+- `settled=false`: Phase 1 exhausted vsyncN budget (perpetual animation present)
+- `phase1_traversals`: cumulative measure+layout-only passes since last reset
+- `phase2_traversals`: cumulative full-record passes since last reset
+- `observe_result=readiness`: dirty/readiness ended the observation before the fallback
+- `observe_result=timeout`: `readywaitN` fired and the fallback snapshot was published
+- `observe_result=sync_failed|detached`: no consumable snapshot; the caller must retry or use pixel fallback
+- `observe_duration_ms` / `observe_passes`: device-side return latency and settle passes
+- `last_sync_valid=true,last_sync_result=0`: the final root DL is valid and crossed the
+  RenderThread staging-to-active sync boundary
+
+When a package has both physical-display and Agent-display roots, match the root whose
+stats contain `"agent_ui":true`, the expected `"display":<VD_ID>`, and
+`visibility=0`. Do not select a window by package name or list order alone.
+
+Each op's `bounds`/`dst` is in **device (screen) coordinates** — the export
+canvas maps every local-space input through `SkCanvas::getLocalToDeviceAs3x3()`
+at the time of capture, so rectangles can be used directly as tap targets
+without further math.
+
+`drawText` ops additionally carry the SkTextBlob's raw runs:
+
+```json
+{"op":"drawText","x":221,"y":309,"bounds":[224,322,565,355],"size":33,
+ "color":"#ff30323b",
+ "runs":[{"font":"Roboto","glyphs":[51,74,89,92,84,87,80,5,11,5,78,83,89,74,87,83,74,89]}]}
+```
+
+The framework intentionally does NOT do glyph→UTF-8 reverse-cmap inline. That
+step is a pure font-table lookup; doing it in C++ would require shipping
+GSUB/cmap logic and font fallback into HWUI for no benefit. Instead, the host
+script `tools/dlglyph/dl_glyph_decode.py` performs the reverse with `fontTools`
+(see *DisplayList Usability* section below).
+
+## Usage Examples
+
+### Basic: Get fresh DL with GPU bypassed
+```bash
+adb shell "dumpsys gfxinfo com.example.app displaylist fresh nodraw"
+```
+
+### With stability detection (wait up to 2s = 120 frames @60Hz)
+```bash
+adb shell "dumpsys gfxinfo com.example.app displaylist fresh nodraw vsync120"
+```
+
+### Recommended workflow: action to readiness-aligned observation
+```bash
+# 1. Start user instance on display 0
+adb shell am start --display 0 -n com.example.app/.MainActivity
+
+# 2. Create agent Virtual Display and launch agent instance
+app_process -cp /data/local/tmp/vd_agent.dex / \
+  com.agent.VirtualDisplayAgent offdump com.example.app/.MainActivity 600 iso
+
+# 3. Get agent display ID from log
+DID=$(cat /data/local/tmp/vd_off.log | grep -oE "READY displayId=[0-9]+" | grep -oE "[0-9]+")
+
+# 4. Let the new Agent window complete its first real draw, then preserve that
+#    active DL while stopping only traversal scheduling between steps.
+adb shell "dumpsys gfxinfo com.example.app displaylist agentctl traversalfreeze"
+
+# 5. Inject one complete action on the Agent display. The command must return
+#    before starting observation; DOWN-only injection is not an action boundary.
+adb shell input -d $DID tap 540 800
+
+# 6. Immediately request the post-action observation. Dirty/readiness may return
+#    early; 2000 ms is the former fixed wait retained only as a fallback bound.
+adb exec-out "dumpsys gfxinfo com.example.app displaylist fresh nodraw \
+  asyncsettle readysettle readywait2000" > /tmp/post_action_dl.txt
+
+# 7. Verify the selected Agent root before giving the DL to the next Agent step.
+adb shell "dumpsys gfxinfo com.example.app displaylist agentstate"
+# Accept: observe_result is readiness or timeout, frozen=true,
+#         last_sync_valid=true, last_sync_result=0, observe_active=false.
+# Reject: sync_failed, detached, wrong display/root, empty DL, ANR/login/ad UI.
+```
+
+`readysettle` unfreezes the visible Agent root internally. After a stable candidate,
+it performs one complete Java DL record and synchronous RenderThread handoff, checks
+that recording did not schedule more UI work, and then traversal-freezes before the
+dumpsys output is generated. If readiness never appears, the same final record/sync
+runs at `readywaitN`. The command therefore replaces both the old unconditional
+post-action sleep and the additional sleep used to wait for an unfrozen traversal.
+
+## Caller Alignment
+
+The readiness request must be aligned to an Agent action, not to inference time or a
+host polling interval:
+
+| Old caller behavior | This branch |
+|---|---|
+| `sleep(wait_after_action_seconds)` | Remove the sleep; call `readysettle` immediately after action injection returns |
+| Unfreeze, then `sleep(300 ms)` before dumping DL | Remove both; `readysettle` owns unfreeze, settle, final sync, and refreeze |
+| `wait_after_action_seconds=2.0` | `readywait2000`; preserve the value as fallback only |
+| `freeze` between every step | `traversalfreeze`; avoid per-step `clearContent()` and DL reconstruction |
+| Assume the first package window is the Agent UI | Select `agent_ui=true`, matching VD display ID, `visibility=0` |
+| Treat every dumpsys return as valid | Gate on result, sync validity, root/display, non-empty DL, and blocking UI |
+
+For this workspace, the aligned commercial caller is
+`agent_os/experiments/exp_commercial_three_configs_profiled/code/m3a_dl_agent.py`.
+It records before/after `observe_result`, `observe_duration_ms`, `observe_passes`, and
+Phase-1/2 counters in each `step.json`. The device-side smoke entry is:
+
+```bash
+cd /home/lishengkai/scripts/agent_os/experiments
+python3 exp_displaylist_ondemand/smoke_ready_settle.py \
+  --serial <serial> --adb-port <port> --package <pkg> --display-id <VD_ID> \
+  --action swipe_up --action tap:540:1200 --ready-wait-ms 2000
+```
+
+The smoke tool assumes the Agent VD and target app are already running. It does not
+create, reassign, or destroy displays, which makes it safe to hand to a tester after
+the device owner has confirmed the display and package.
+
+### Profiling: measure traversal counts and GPU frames
+```bash
+# Reset counters at task start
+adb shell "dumpsys gfxinfo com.example.app displaylist reset"
+
+# ... run agent task (multiple actions + observations) ...
+
+# Check cumulative stats
+adb shell "dumpsys gfxinfo com.example.app displaylist fresh nodraw" | \
+  grep -oP '(?<=visibility=\d\))\{[^{]*\}'
+# Output: {"settled":true,"phase1_traversals":5,"phase2_traversals":3}
+
+# Compare with GPU frames (should be 0 for agent window while frozen)
+adb shell "dumpsys gfxinfo com.example.app" | grep "Total frames rendered"
+```
+
+## DisplayList Usability
+
+This section quantifies what the DL representation actually delivers as an
+agent-side input, relative to screenshots and the AccessibilityService XML.
+
+### What the export captures
+
+Each `drawText`/`drawRect`/`drawPath`/`drawImage`/... op in the JSON carries:
+- **Device-space bounds** — directly usable as tap targets, no matrix math
+  on the consumer side
+- **Color** (ARGB hex), **font size**, **stroke style** where applicable
+- For text: **font family name** + **raw glyph ID array** per Skia run
+- For nested RenderNodes: hierarchical `drawDrawable.ops[...]` blocks that
+  preserve the rendering tree (incl. HardwareLayers)
+
+Three things the export does NOT carry, by design:
+1. **Image pixel content** — `drawImage` emits dst rect + source w×h only.
+   This is the only inherent limit of the DisplayList channel; agents that
+   need image semantics still need a vision model for that subregion.
+2. **View identity / clickable flags** — the op stream is a rendering view;
+   `View.isClickable()` is application semantics and belongs in a thin
+   side-channel (~50 bytes per interactive View), not in the op stream itself.
+3. **UTF-8 text** — only glyph IDs are emitted (Skia loses the source text
+   once it shapes into a TextBlob). Recovered by the host-side script below.
+
+### Glyph → UTF-8 recovery (deterministic, model-free)
+
+`tools/dlglyph/dl_glyph_decode.py` walks each `runs[]` entry and reverse-maps
+glyph IDs to Unicode codepoints via `fontTools.ttLib`. For TrueType
+Collections (Noto CJK ships as a TTC of 5 region variants), the cmaps of all
+sub-fonts are unioned under the same family name.
+
+```bash
+# One-time: pull device fonts
+adb -s <serial> pull /system/fonts/Roboto-Regular.ttf       ~/fonts/
+adb -s <serial> pull /system/fonts/NotoSansCJK-Regular.ttc  ~/fonts/
+
+# Optional: pull app-private fonts (rarely needed)
+adb -s <serial> shell pm path <pkg> | sed 's/^package://' | \
+  xargs -I {} adb -s <serial> pull {} /tmp/app.apk
+unzip -j /tmp/app.apk "assets/*.ttf" "assets/*.otf" -d ~/fonts/
+
+# Capture + decode
+adb -s <serial> exec-out "dumpsys gfxinfo <pkg> displaylist fresh nodraw" \
+  > /tmp/dl.json
+tools/dlglyph/dl_glyph_decode.py --fonts ~/fonts /tmp/dl.json \
+  -o /tmp/dl_decoded.json
+```
+
+The decoded JSON has the same structure as the raw output, with each
+`drawText` op gaining a `text` field:
+
+```json
+{"op":"drawText","bounds":[224,322,565,355],"size":33,
+ "color":"#ff30323b","text":"Network & internet", ...}
+```
+
+### Empirical recovery rate
+
+Measured on Settings home, Zhihu home, Bilibili home (Android 16 GSI, Pixel 10
+Pro) — every `drawText` op extracted, every glyph in every run reverse-mapped:
+
+| App      | Total glyphs | Recovered | Rate    |
+|----------|-------------:|----------:|--------:|
+| Settings |          735 |       735 | 100.0%  |
+| Zhihu    |          990 |       990 | 100.0%  |
+| Bilibili |          288 |       287 |  99.7%  |
+
+By font:
+
+| Font                    | Glyphs | Recovered | Rate    |
+|-------------------------|-------:|----------:|--------:|
+| Roboto (Latin/digits)   |  1,519 |     1,519 | 100.0%  |
+| Noto Sans CJK SC        |    493 |       493 | 100.0%  |
+| App-private iconfont    |      1 |         0 |   0.0%  |
+
+The single missed glyph on Bilibili comes from an in-app font name reported
+by `SkTypeface::getFamilyName()` as `"bilibili"`. The corresponding glyph is
+not present in any of the system fonts; if the app's `assets/*.ttf` is
+unpacked and supplied via `--fonts`, that gap closes too.
+
+### Known limitations (and what each costs)
+
+| Source of loss | Effect | Severity for Chinese/English UI |
+|----------------|--------|---------------------------------|
+| App-private fonts not unpacked from APK | Glyphs in that font reverse to `�` | 0.05% on the test set; fix is one-time per app |
+| GSUB ligatures (Latin `fi`, `ffi`) | Reverse yields one codepoint instead of two | Negligible — apps rarely use Latin ligatures |
+| Complex shaping (Arabic, Devanagari) | Glyph order ≠ logical char order; positional variants need GSUB reverse | Out of scope for our target apps |
+| Unicode variant codepoints (e.g. Kangxi radical "⻔" vs "门") | Decoded char is visually identical but has a different codepoint | Visual equivalence preserved; downstream string match needs normalization |
+| Image content (`drawImage`) | Only dst-rect + w/h, no pixels | Inherent to DL channel; out of scope |
+
+### What this means relative to existing channels
+
+- **vs Screenshot**: the DL op stream carries equivalent visual information
+  (modulo image internals) in structured form — a button rendered as
+  drawRRect-background + centered drawText is recognizable from the op
+  attributes the same way a VLM recognizes it from pixels, but at a fraction
+  of the token cost.
+- **vs AccessibilityService**: DL captures every glyph that is drawn,
+  including text rendered by custom `canvas.drawText` calls that the a11y
+  layer cannot see. Conversely, DL does not carry `clickable`/`focusable`
+  flags — those come from `View` state and require a thin side-channel.
+- **Limits that remain after this work**: only image pixel content (the one
+  inherent limit) and the optional `{id, clickable, role}` side-channel
+  (~50 bytes/View) the agent needs to disambiguate semantically-clickable-
+  but-visually-passive elements.
+
+## Experiment Notes
+
+1. **Never `adb reboot`** — overlayfs is tmpfs, hard reboot loses all pushed changes.
+   Always use `adb shell stop && start` for soft reboot.
+
+2. **Never `m framework`** — that builds the class jar, not the DEX jar.
+   Always use `m framework-minus-apex`.
+
+3. **C1 verification**: check logcat for `AgentDisplay: Overriding to LAUNCH_MULTIPLE`
+   after launching on agent display.
+
+4. **GPU isolation verification**: after traversal-freeze, `Total frames rendered` should not
+   increase for the agent window. Small increments (1-4) may come from system UI on
+   display 0, not from the agent window.
+
+5. **`uiautomator dump --display N`** is unreliable in multi-display setups — always
+   use `dumpsys gfxinfo ... displaylist` + `screencap` for cross-validation.
+
+6. **Display ID is dynamic** — each `vd_agent` launch gets a new ID. Always read it
+   from the vd_agent log, never hardcode.
+
+7. **Readiness fallback selection**:
+   - Start validation with `readywait2000` to align with the previous commercial
+     runner's `wait_after_action_seconds=2.0`.
+   - Keep `readywaitN` constant across compared configurations; report readiness and
+     timeout samples separately.
+   - `readywaitN` does not certify future network completion. It bounds when the
+     current action observation is delivered.
+   - `vsyncN` remains a legacy pass-budget interface for synchronous experiments; do
+     not mix it with production readiness latency numbers.
+
+## Commit History
+
+Current branch `exp_agent_dirty_readiness_stop` (newest first):
+```
+6b300f7a Agent UI: stop observations on cheap readiness
+de2203f8 Agent UI: refine cheap readiness profiling
+654664c6 Agent UI: profile DisplayList readiness generations
+daa61196 Agent UI: add traversal-only freeze controls
+fa317639 Agent UI: checkpoint on-demand traversals
+2eef669a Agent UI: dispatch foreground frames at node checkpoints
+8e6fb21d Agent C3 L2: persistent GPU bypass as an auto agent-UI window property
+6ed448b  dlglyph: multi-candidate font matching + CJK word-freq disambiguation
+1bb67aae Agent C3: release agent window GPU resources on freeze (agent-UI-only)
+1005f63e Agent C3 Layer-1: idle-driven decouple traversal + anti-starvation bound
+e4b6f442 add bounds and drawimage/drawpath functions (DL visual completion)
+a90aa32d Agent C3 Layer-1: make decouple an automatic window property of agent UIs
+cb00a319 Agent C3: three-layer decoupled architecture (callback reroute / GPU bypass / DL semantic-hash stability)
+42f0934d Agent on-demand: add display id + frozen flag to stats JSON
+d58973d5 Agent on-demand: switch settle to posted self-continuation
+c8fcd683 Agent on-demand: idle-driven foreground-yielding settle + animation attribution
+831e8169 DisplayList Export: device-space op bounds + per-run glyph IDs + reverse-cmap script
+```
+
+### Three-layer GPU-bypass design (current)
+
+The agent UI's GPU cost is cut by three orthogonal, independently-switchable,
+agent-UI-only layers. None touches window visibility / display power / input /
+activity lifecycle, so the agent stays perceivable (DisplayList) and operable (tap).
+The table separately lists the long-idle resource-release variant of L1 because it
+must not be substituted for the per-step scheduling freeze:
+
+| Layer | Cuts | Mechanism | Switch |
+|-------|------|-----------|--------|
+| **L1 scheduling freeze** | no Agent traversal between steps while retaining the active DL | `setAgentTraversalFrozen`: `scheduleTraversals` early-return, no `clearContent()` | `displaylist traversalfreeze` / `traversalunfreeze`; `readysettle` refreezes automatically |
+| **Long-idle resource freeze** | additionally releases this window's GPU resources when reconstruction cost is acceptable | `setAgentFrozen`: scheduling gate + `clearContent()` | `displaylist freeze` / `unfreeze`; do not use per Agent step |
+| **L2 persistent no-draw** | EVERY traversal skips `context->draw()` (rasterization + SF submit), incl. the app's own VSYNC frames — not just the observe frame | `mAgentPersistentNoDraw*`: `performDraw` routes to `syncForAgent` (record DL + RT sync, skip draw). Process-wide default so navigated sub-windows inherit; first real frame builds the DisplayList, then bypass | `displaylist gpubypass` / `nogpubypass` |
+| **L3 SF compose-bypass** | SF's composition pass for the agent VD + video/SurfaceView producer back-pressure | *(frameworks/native)* SurfaceFlinger backdoor code 1050 skips the agent VD's Output by layerStack | `service call SurfaceFlinger 1050 i32 <displayId> i32 <1/0>` |
+
+Measured (2-round avg, c3_dl_nofg_compose vs bgui_nofg baseline): target-app GPU
+compute **−94.6%**, SF composition GPU **−95.1%**, rendered frames ≈ **−99%**
+(agent VD renders single-digit frames vs thousands). CPU is roughly flat per unit
+time (DL export + agent scheduling replace the rasterization CPU). WebView pages
+(Firefox: GPU in a separate `:gpu` process) are an intrinsic boundary the render-
+pipeline bypass cannot reach.
+
+## License
+
+Same as AOSP — Apache 2.0.
+
+## C2 DisplayList Export 修改说明
+
+本分支在 Android `frameworks/base` 中加入了 C2 使用的 DisplayList 导出能力。该修改的目标是从 Android RenderThread / HWUI 渲染流程中导出当前窗口的绘制指令，并将其转换为结构化 JSON，供上层 agent 使用。
+
+### 修改目标
+
+原始 Android framework 只能通过截图或 ViewTree 获取界面信息。为了让 agent 能够直接访问 UI 的底层绘制结构，本修改在 HWUI 中加入了 DisplayList 导出逻辑，使系统可以输出如下信息：
+
+- 当前窗口的绘制操作，例如 `drawText`、`drawPath`、`drawImage`、`drawRect` 等；
+- 文本内容、绘制 bounds、颜色、图片采样信息；
+- 图标和 path 的几何形状；
+- 元素在全局屏幕坐标系中的位置；
+- 当前窗口的 surface origin 和 surface insets 信息。
+
+这些信息会被后续 Python 侧脚本进一步过滤、简化，并转换为 agent observation。
+
+### 核心修改
+
+本次修改涉及 Java framework、JNI、RenderProxy、CanvasContext 和 HWUI Skia pipeline。主要修改文件如下：
+
+```text
+core/java/android/view/ThreadedRenderer.java
+core/java/android/view/WindowManagerGlobal.java
+graphics/java/android/graphics/HardwareRenderer.java
+libs/hwui/jni/android_graphics_HardwareRenderer.cpp
+libs/hwui/pipeline/skia/FlatExportOpsCanvas.h
+libs/hwui/renderthread/CanvasContext.cpp
+libs/hwui/renderthread/CanvasContext.h
+libs/hwui/renderthread/RenderProxy.cpp
+libs/hwui/renderthread/RenderProxy.h
+```
+
+### FlatExportOpsCanvas
+
+`FlatExportOpsCanvas` 是本修改的核心组件。它继承自 `SkCanvas`，在 DisplayList replay 过程中拦截绘制操作，并导出 JSON 格式的绘制记录。
+
+目前支持导出的主要绘制操作包括：
+
+- `drawTextBlob`
+- `drawPath`
+- `drawImage`
+- `drawRect`
+- `drawOval`
+- `drawRRect`
+- `drawCircle`
+- `clipRect`
+
+对于不同操作，会导出对应的结构化信息，例如：
+
+- `op`
+- `bounds`
+- `color`
+- `text`
+- `path`
+- `src`
+- `dst`
+- `imageId`
+- `visualStatus`
+- `sampleWidth`
+- `sampleHeight`
+- `argbRle`
+
+其中 `drawImage` 会尝试导出小尺寸 ARGB 采样，并使用 run-length encoding 表示图片像素信息，供后续脚本生成图标语义描述。
diff --git a/core/java/android/view/Choreographer.java b/core/java/android/view/Choreographer.java
index 3a2ec91b3b20..fcf46feca294 100644
--- a/core/java/android/view/Choreographer.java
+++ b/core/java/android/view/Choreographer.java
@@ -32,6 +32,7 @@ import android.graphics.Insets;
 import android.hardware.display.DisplayManagerGlobal;
 import android.os.Build;
 import android.os.Handler;
+import android.os.HandlerThread;
 import android.os.Looper;
 import android.os.Message;
 import android.os.SystemClock;
@@ -41,6 +42,8 @@ import android.util.Log;
 import android.util.TimeUtils;
 import android.view.animation.AnimationUtils;
 
+import com.android.internal.annotations.GuardedBy;
+
 import java.io.PrintWriter;
 import java.util.Locale;
 import java.util.concurrent.atomic.AtomicBoolean;
@@ -353,6 +356,31 @@ public final class Choreographer {
         setFPSDivisor(SystemProperties.getInt(ThreadedRenderer.DEBUG_FPS_DIVISOR, 1));
     }
 
+    // Agent node-checkpoint prototype. A receiver on the main Looper cannot publish VSYNC
+    // while an agent traversal occupies that Looper, so a side receiver mirrors requested
+    // app VSYNCs into this mailbox. Only the main thread consumes the mailbox.
+    private HandlerThread mAgentCheckpointVsyncThread;
+    private AgentCheckpointDisplayEventReceiver mAgentCheckpointDisplayEventReceiver;
+    @GuardedBy("mLock")
+    private boolean mAgentCheckpointTraversalActive;
+    @GuardedBy("mLock")
+    private boolean mAgentCheckpointVsyncScheduled;
+    @GuardedBy("mLock")
+    private boolean mAgentCheckpointVsyncPending;
+    @GuardedBy("mLock")
+    private boolean mAgentCheckpointFrameDispatching;
+    @GuardedBy("mLock")
+    private long mAgentCheckpointVsyncTimestampNanos;
+    @GuardedBy("mLock")
+    private int mAgentCheckpointVsyncFrame;
+    @GuardedBy("mLock")
+    private final DisplayEventReceiver.VsyncEventData mAgentCheckpointVsyncEventData =
+            new DisplayEventReceiver.VsyncEventData();
+    @GuardedBy("mLock")
+    private long mLastAgentCheckpointVsyncId = FrameInfo.INVALID_VSYNC_ID;
+    @GuardedBy("mLock")
+    private long mLastAgentCheckpointVsyncTimestampNanos = Long.MIN_VALUE;
+
     private static float getRefreshRate() {
         DisplayInfo di = DisplayManagerGlobal.getInstance().getDisplayInfo(
                 Display.DEFAULT_DISPLAY);
@@ -419,6 +447,22 @@ public final class Choreographer {
 
     private void dispose() {
         mDisplayEventReceiver.dispose();
+        final AgentCheckpointDisplayEventReceiver checkpointReceiver;
+        final HandlerThread checkpointThread;
+        synchronized (mLock) {
+            checkpointReceiver = mAgentCheckpointDisplayEventReceiver;
+            checkpointThread = mAgentCheckpointVsyncThread;
+            mAgentCheckpointDisplayEventReceiver = null;
+            mAgentCheckpointVsyncThread = null;
+            mAgentCheckpointTraversalActive = false;
+            mAgentCheckpointVsyncPending = false;
+        }
+        if (checkpointReceiver != null) {
+            checkpointReceiver.dispose();
+        }
+        if (checkpointThread != null) {
+            checkpointThread.quitSafely();
+        }
     }
 
     /**
@@ -1191,6 +1235,129 @@ public final class Choreographer {
         }
     }
 
+    /**
+     * Synthetic VSYNC pump for agent on-demand traversal. Runs the full doFrame
+     * callback chain (INPUT/ANIMATION/INSETS_ANIMATION/TRAVERSAL/COMMIT) on the UI
+     * thread without waiting for a real display VSYNC. This advances animations,
+     * frame callbacks and content (image decode commits, lazy-load) so the recorded
+     * DisplayList reflects settled content even while the display is STATE_OFF.
+     * Must be called on this Choreographer's looper thread.
+     * @hide
+     */
+    public void doFrameForAgent() {
+        final long now = System.nanoTime();
+        synchronized (mLock) {
+            // doFrame early-returns "no work to do" unless a frame is scheduled.
+            mFrameScheduled = true;
+        }
+        DisplayEventReceiver.VsyncEventData data = new DisplayEventReceiver.VsyncEventData();
+        // ~60Hz interval; a real value (not -1) so jitter/timeline logic stays sane.
+        data.frameInterval = 16_666_666L;
+        doFrame(now, 0, data);
+    }
+
+    /**
+     * Whether a frame is currently scheduled on this (shared, per-thread) Choreographer.
+     * Used by the agent on-demand idle-driven settle to yield to the foreground: if a
+     * foreground frame is pending, the agent defers its next settle pass.
+     * @hide
+     */
+    public boolean isFrameScheduledForAgentCheck() {
+        synchronized (mLock) {
+            return mFrameScheduled;
+        }
+    }
+
+    /** Begin an agent traversal that may service an arrived foreground VSYNC inline. @hide */
+    public void beginAgentNodeCheckpointTraversal() {
+        ensureAgentCheckpointDisplayEventReceiver();
+        synchronized (mLock) {
+            mAgentCheckpointTraversalActive = true;
+            mAgentCheckpointVsyncPending = false;
+            // Keep the side receiver subscribed while the agent owns the main Looper. A frame
+            // request posted from another thread cannot run MSG_DO_SCHEDULE_VSYNC until the
+            // traversal returns, but it does set mFrameScheduled under mLock immediately.
+            scheduleAgentCheckpointVsyncLocked();
+        }
+    }
+
+    /** End an agent node-checkpoint traversal and restore the vanilla VSYNC path. @hide */
+    public void endAgentNodeCheckpointTraversal() {
+        synchronized (mLock) {
+            mAgentCheckpointTraversalActive = false;
+            mAgentCheckpointVsyncPending = false;
+            if (mFrameScheduled && mDisplayEventReceiver != null) {
+                mDisplayEventReceiver.scheduleVsync();
+            }
+        }
+    }
+
+    /**
+     * Runs one already-arrived foreground frame while preserving the caller's agent traversal
+     * stack. This is deliberately a frame-only pump; it does not dispatch arbitrary Looper work.
+     * @hide
+     */
+    public boolean doFrameAtAgentNodeCheckpoint() {
+        final long timestampNanos;
+        final int frame;
+        final DisplayEventReceiver.VsyncEventData data =
+                new DisplayEventReceiver.VsyncEventData();
+        synchronized (mLock) {
+            if (!mAgentCheckpointTraversalActive || mAgentCheckpointFrameDispatching
+                    || !mAgentCheckpointVsyncPending || !mFrameScheduled) {
+                return false;
+            }
+            mAgentCheckpointVsyncPending = false;
+            mAgentCheckpointFrameDispatching = true;
+            timestampNanos = mAgentCheckpointVsyncTimestampNanos;
+            frame = mAgentCheckpointVsyncFrame;
+            data.copyFrom(mAgentCheckpointVsyncEventData);
+            mLastAgentCheckpointVsyncId = data.preferredFrameTimeline().vsyncId;
+            mLastAgentCheckpointVsyncTimestampNanos = timestampNanos;
+        }
+        Trace.traceBegin(Trace.TRACE_TAG_VIEW, "agentNodeCheckpoint#doFrame");
+        try {
+            doFrame(timestampNanos, frame, data);
+            return true;
+        } finally {
+            synchronized (mLock) {
+                mAgentCheckpointFrameDispatching = false;
+            }
+            Trace.traceEnd(Trace.TRACE_TAG_VIEW);
+        }
+    }
+
+    private void ensureAgentCheckpointDisplayEventReceiver() {
+        synchronized (mLock) {
+            if (mAgentCheckpointDisplayEventReceiver != null || !USE_VSYNC) {
+                return;
+            }
+        }
+        final HandlerThread thread = new HandlerThread("AgentCheckpointVsync");
+        thread.start();
+        final AgentCheckpointDisplayEventReceiver receiver =
+                new AgentCheckpointDisplayEventReceiver(thread.getLooper());
+        synchronized (mLock) {
+            if (mAgentCheckpointDisplayEventReceiver == null) {
+                mAgentCheckpointVsyncThread = thread;
+                mAgentCheckpointDisplayEventReceiver = receiver;
+                return;
+            }
+        }
+        receiver.dispose();
+        thread.quitSafely();
+    }
+
+    @GuardedBy("mLock")
+    private void scheduleAgentCheckpointVsyncLocked() {
+        if (!mAgentCheckpointTraversalActive || mAgentCheckpointVsyncScheduled
+                || mAgentCheckpointDisplayEventReceiver == null) {
+            return;
+        }
+        mAgentCheckpointVsyncScheduled = true;
+        mAgentCheckpointDisplayEventReceiver.scheduleVsync();
+    }
+
     void doScheduleVsync() {
         synchronized (mLock) {
             if (mFrameScheduled) {
@@ -1214,7 +1381,12 @@ public final class Choreographer {
     private void scheduleVsyncLocked() {
         try {
             Trace.traceBegin(Trace.TRACE_TAG_VIEW, "Choreographer#scheduleVsyncLocked");
-            mDisplayEventReceiver.scheduleVsync();
+            if (mAgentCheckpointTraversalActive
+                    && mAgentCheckpointDisplayEventReceiver != null) {
+                scheduleAgentCheckpointVsyncLocked();
+            } else {
+                mDisplayEventReceiver.scheduleVsync();
+            }
         } finally {
             Trace.traceEnd(Trace.TRACE_TAG_VIEW);
         }
@@ -1550,10 +1722,48 @@ public final class Choreographer {
         @Override
         public void run() {
             mHavePendingVsync = false;
+            synchronized (mLock) {
+                final long vsyncId = mLastVsyncEventData.preferredFrameTimeline().vsyncId;
+                final boolean consumedAtAgentCheckpoint =
+                        (vsyncId != FrameInfo.INVALID_VSYNC_ID
+                                && vsyncId <= mLastAgentCheckpointVsyncId)
+                        || mTimestampNanos <= mLastAgentCheckpointVsyncTimestampNanos;
+                if (consumedAtAgentCheckpoint) {
+                    if (mFrameScheduled && !mAgentCheckpointTraversalActive) {
+                        mDisplayEventReceiver.scheduleVsync();
+                    }
+                    return;
+                }
+            }
             doFrame(mTimestampNanos, mFrame, mLastVsyncEventData);
         }
     }
 
+    private final class AgentCheckpointDisplayEventReceiver extends DisplayEventReceiver {
+        AgentCheckpointDisplayEventReceiver(Looper looper) {
+            super(looper, VSYNC_SOURCE_APP, /* eventRegistration */ 0, /* layerHandle */ 0L);
+        }
+
+        @Override
+        public void onVsync(long timestampNanos, long physicalDisplayId, int frame,
+                VsyncEventData vsyncEventData) {
+            synchronized (mLock) {
+                mAgentCheckpointVsyncScheduled = false;
+                if (!mAgentCheckpointTraversalActive) {
+                    return;
+                }
+                if (mFrameScheduled) {
+                    mAgentCheckpointVsyncTimestampNanos =
+                            Math.min(timestampNanos, System.nanoTime());
+                    mAgentCheckpointVsyncFrame = frame;
+                    mAgentCheckpointVsyncEventData.copyFrom(vsyncEventData);
+                    mAgentCheckpointVsyncPending = true;
+                }
+                scheduleAgentCheckpointVsyncLocked();
+            }
+        }
+    }
+
     private static final class CallbackRecord {
         public CallbackRecord next;
         public long dueTime;
diff --git a/core/java/android/view/ThreadedRenderer.java b/core/java/android/view/ThreadedRenderer.java
index ad46f2b6df84..e04f3e43d4f8 100644
--- a/core/java/android/view/ThreadedRenderer.java
+++ b/core/java/android/view/ThreadedRenderer.java
@@ -661,15 +661,33 @@ public final class ThreadedRenderer extends HardwareRenderer {
 
     /** @hide */
     public static void handleDumpGfxInfo(FileDescriptor fd, String[] args) {
-        dumpGlobalProfileInfo(fd, dumpArgsToFlags(args));
+        boolean agentCommand = false;
+        for (String arg : args) {
+            if ("agentctl".equals(arg) || "agentstate".equals(arg)) {
+                agentCommand = true;
+                break;
+            }
+        }
+        if (!agentCommand) {
+            dumpGlobalProfileInfo(fd, dumpArgsToFlags(args));
+        }
         WindowManagerGlobal.getInstance().dumpGfxInfo(fd, args);
     }
 
     /**
      * Outputs extra debugging information in the specified file descriptor.
      */
-    void dumpGfxInfo(PrintWriter pw, FileDescriptor fd, String[] args) {
+    void dumpGfxInfo(PrintWriter pw, FileDescriptor fd, String[] args,
+            int surfaceOriginX, int surfaceOriginY, int surfaceInsetX, int surfaceInsetY) {
         pw.flush();
+        // Check if displaylist dump is requested: 'dumpsys gfxinfo <pkg> displaylist'
+        for (String arg : args) {
+            if ("displaylist".equals(arg)) {
+                dumpDisplayList(fd, surfaceOriginX, surfaceOriginY,
+                        surfaceInsetX, surfaceInsetY);
+                return;
+            }
+        }
         dumpProfileInfo(fd, dumpArgsToFlags(args));
     }
 
@@ -792,6 +810,48 @@ public final class ThreadedRenderer extends HardwareRenderer {
      * @param view The view to draw.
      * @param attachInfo AttachInfo tied to the specified view.
      */
+    /**
+     * Agent no-draw sync: record the View tree's DisplayList and sync it to the
+     * RenderThread (staging->active) but skip the GPU draw. Mirrors {@link #draw}
+     * minus the actual frame draw, giving an up-to-date DisplayList with zero
+     * GPU/SurfaceFlinger work.
+     */
+    void syncForAgent(View view, AttachInfo attachInfo, DrawCallbacks callbacks) {
+        final ViewRootImpl root = attachInfo.mViewRootImpl;
+        final boolean profileDlReadiness = root.isAgentDlProfileRecordingActive();
+        root.mViewFrameInfo.markDrawStart();
+        if (profileDlReadiness) {
+            root.agentDlProfileOnRecordPassBegin();
+        }
+        final long recordStartNanos = profileDlReadiness ? System.nanoTime() : 0;
+        updateRootDisplayList(view, callbacks);
+        if (profileDlReadiness) {
+            root.agentDlProfileOnRecordPassComplete(
+                    mRootNode.hasDisplayList(), view.getUniqueDrawingId(),
+                    System.nanoTime() - recordStartNanos);
+        }
+        if (attachInfo.mPendingAnimatingRenderNodes != null) {
+            final int count = attachInfo.mPendingAnimatingRenderNodes.size();
+            for (int i = 0; i < count; i++) {
+                registerAnimatingRenderNode(
+                        attachInfo.mPendingAnimatingRenderNodes.get(i));
+            }
+            attachInfo.mPendingAnimatingRenderNodes.clear();
+            attachInfo.mPendingAnimatingRenderNodes = null;
+        }
+        final FrameInfo frameInfo = root.getUpdatedFrameInfo();
+        // Skip GPU draw; the DrawFrameTask still runs syncFrameState which pushes the
+        // staging DisplayList to active.
+        setSyncOnlyNextFrame();
+        final long syncStartNanos = profileDlReadiness ? System.nanoTime() : 0;
+        final int syncResult = syncAndDrawFrame(frameInfo);
+        root.agentOnSyncForAgentComplete(mRootNode.hasDisplayList(), syncResult);
+        if (profileDlReadiness) {
+            root.agentDlProfileOnActiveSyncComplete(
+                    syncResult, System.nanoTime() - syncStartNanos);
+        }
+    }
+
     void draw(View view, AttachInfo attachInfo, DrawCallbacks callbacks) {
         attachInfo.mViewRootImpl.mViewFrameInfo.markDrawStart();
 
diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 1c6bd4268ca2..0ac2dec6ce92 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -24067,6 +24067,7 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
     @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
     public RenderNode updateDisplayListIfDirty() {
         final RenderNode renderNode = mRenderNode;
+        boolean agentDisplayListRecorded = false;
         if (!canHaveDisplayList()) {
             // can't populate RenderNode, don't try
             return renderNode;
@@ -24138,6 +24139,7 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
             } finally {
                 renderNode.endRecording();
                 setDisplayListProperties(renderNode);
+                agentDisplayListRecorded = true;
             }
         } else {
             if ((mPrivateFlags4 & PFLAG4_HAS_VIEW_PROPERTY_INVALIDATION)
@@ -24153,6 +24155,10 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
         }
         mPrivateFlags4 &= ~PFLAG4_HAS_MOVED;
         mFrameContentVelocity = -1;
+        // The current RenderNode is closed here. An ancestor RecordingCanvas may remain on the
+        // stack; allowing a foreground frame at this boundary is the aggressive checkpoint whose
+        // reentrancy and latency are evaluated by the node-checkpoint experiment.
+        ViewRootImpl.agentNodeCheckpoint(this, agentDisplayListRecorded);
         return renderNode;
     }
 
@@ -25879,6 +25885,7 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
         }
 
         notifyAppearedOrDisappearedForContentCaptureIfNeeded(true);
+        ViewRootImpl.agentNodeCheckpoint(this);
     }
 
     private boolean hasParentWantsFocus() {
@@ -28615,6 +28622,7 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
 
         mMeasureCache.put(key, ((long) mMeasuredWidth) << 32 |
                 (long) mMeasuredHeight & 0xffffffffL); // suppress sign extension
+        ViewRootImpl.agentNodeCheckpoint(this);
     }
 
     /**
diff --git a/core/java/android/view/ViewRootImpl.java b/core/java/android/view/ViewRootImpl.java
index 40d6318c831f..7625b7bd9c79 100644
--- a/core/java/android/view/ViewRootImpl.java
+++ b/core/java/android/view/ViewRootImpl.java
@@ -204,6 +204,7 @@ import android.os.Handler;
 import android.os.IBinder;
 import android.os.Looper;
 import android.os.Message;
+import android.os.MessageQueue;
 import android.os.ParcelFileDescriptor;
 import android.os.Process;
 import android.os.RemoteException;
@@ -342,6 +343,10 @@ public final class ViewRootImpl implements ViewParent,
     private static final boolean DEBUG_IMF = false || LOCAL_LOGV;
     private static final boolean DEBUG_CONFIGURATION = false || LOCAL_LOGV;
     private static final boolean DEBUG_FPS = false;
+    // Agent on-demand observe diagnostics (settle steps, yields). Off by default;
+    // perfetto trace sections (agentObserve/agentSettlePass/agentRecordPhase2/
+    // agentYieldToForeground) carry the profiling signal regardless of this flag.
+    private static final boolean DEBUG_AGENT = false;
     private static final boolean DEBUG_INPUT_STAGES = false || LOCAL_LOGV;
     private static final boolean DEBUG_KEEP_SCREEN_ON = false || LOCAL_LOGV;
     private static final boolean DEBUG_CONTENT_CAPTURE = false || LOCAL_LOGV;
@@ -727,6 +732,220 @@ public final class ViewRootImpl implements ViewParent,
     /** Set to true while in performTraversals for detecting when die(true) is called from internal
      * callbacks such as onMeasure, onPreDraw, onDraw and deferring doDie() until later. */
     boolean mIsInTraversal;
+    // Agent forced-traversal no-draw mode: record DisplayList + sync staging->active,
+    // but skip GPU draw (zero GPU/SF). Set only on the UI thread for the duration of
+    // a forceTraversalForAgent() call.
+    boolean mAgentNoDraw;
+    // Agent PERSISTENT no-draw (GPU bypass): when true, EVERY performDraw() on this
+    // window skips the GPU draw -- not only the on-demand observe frame (mAgentNoDraw),
+    // but also the app's own real-VSYNC-driven traversals while the window is unfrozen
+    // and active. This is the "unfreeze period has traversal but all GPU is bypassed"
+    // mode: the view tree still measures/layouts/records its DisplayList (so on-demand
+    // DL perception stays correct and the app's state machine advances on input), but
+    // the RenderThread never rasterizes a frame for this window (zero GPU / zero SF
+    // buffer queued). Independent of freeze. Gated to agent UIs only.
+    //
+    // Tri-state per-window override, mirroring mAgentDecoupleOverride:
+    //   AUTO(0)  -> follow the PROCESS-WIDE default sAgentPersistentNoDrawDefault
+    //               (see below): a newly-created agent window inherits whatever mode
+    //               the agent last set process-wide, so sub-activities/dialogs the
+    //               agent navigates to AFTER task start are covered automatically
+    //               (fixes multi-window nav apps e.g. Zhihu question->answer, whose
+    //               new ViewRootImpls previously rendered at full GPU).
+    //   ON(1)    -> force on for this window (agent UI only).
+    //   OFF(-1)  -> force off for this window.
+    // Actual state decided by isAgentPersistentNoDrawActive(); see performDraw().
+    // NOTE: unlike decouple, the AUTO default is OFF (process default starts false),
+    // because nodraw BLANKS the window's output -- B-GUI / screenshot configs that
+    // render the agent VD for ImageReader capture must NOT be blanked. The agent
+    // opts in by calling gpubypass, which flips the process default ON.
+    static final int AGENT_NODRAW_AUTO = 0;
+    static final int AGENT_NODRAW_ON = 1;
+    static final int AGENT_NODRAW_OFF = -1;
+    int mAgentPersistentNoDrawOverride = AGENT_NODRAW_AUTO;
+    // Process-wide default for agent-UI persistent no-draw, inherited by every new
+    // agent ViewRootImpl at construction (so newly navigated agent windows bypass
+    // GPU without per-window re-engagement). Flipped by the gpubypass/nogpubypass
+    // dumpsys backdoor. Starts false so non-bypass configs (B-GUI screenshot) are
+    // unaffected until the agent explicitly opts in.
+    static volatile boolean sAgentPersistentNoDrawDefault = false;
+    // A window must complete at least one REAL draw() to build its RenderNode
+    // DisplayList before persistent no-draw may safely skip draws -- otherwise
+    // syncForAgent() records an empty/uninitialized DL and the agent perceives a
+    // blank screen. Set true after the first real draw in performDraw(); until then
+    // isAgentPersistentNoDrawActive() returns false so the first frame renders
+    // normally (builds the DL), then subsequent frames bypass GPU. This lets newly
+    // navigated agent windows self-bootstrap: 1 real frame, then nodraw.
+    boolean mAgentHasDrawnOnce;
+    // Agent freeze: when true this window stops scheduling its own traversal/draw on
+    // real VSYNC (app self-rendering for this window halts, zero GPU). The agent still
+    // updates the DisplayList on demand via forceTraversalForAgent(), whose traversals run
+    // through the agent checkpoint wrapper. Gated to agent displays only (never display 0).
+    boolean mAgentFrozen;
+    // Agent dual-phase: skip draw-command recording in Phase 1 (measure+layout only).
+    boolean mAgentSkipRecord;
+    // Per-window invalidate counter: incremented on every invalidate() call.
+    // Used by forceTraversalForAgent to detect when the view tree has settled.
+    long mAgentDirtyTick;
+    // Per-window profiling counters for E3 experiment (reset via 'fresh reset').
+    // mAgentPhase1Count: measure+layout-only traversals during settle phase.
+    // mAgentPhase2Count: full record traversals (one per forceTraversalForAgent call).
+    // mAgentSettled: true if the last call exited via early-break, false if bound was hit.
+    int mAgentPhase1Count;
+    int mAgentPhase2Count;
+    boolean mAgentSettled;
+
+    // === Agent UI identification (launch-origin, NOT foreground/display-based) ===
+    // An "agent UI" is a UI instance launched by an agent via the agent-display API
+    // (C1), as opposed to a "main UI" launched by user interaction. Per design, the
+    // distinction is by launch origin and must follow windows derived from an agent
+    // UI (e.g. dialogs/sub-activities the agent navigates to), even if such a window
+    // were to surface on the physical display.
+    //
+    // Current identification: a window is agent UI iff it lives on a non-default
+    // display. This holds because agent UIs are launched on agent VirtualDisplays
+    // and the user's UI owns the default display; navigation-spawned windows inherit
+    // the agent display and are thus correctly classified. The fully launch-origin
+    // plumb (a flag propagated from ActivityStarter's agent override through to the
+    // client window token) is the robust long-term form; see isAgentUi().
+    private int mIsAgentUiCache = -1; // -1 unknown, 0 no, 1 yes
+
+    // === Layer 1: agent-UI traversal decoupled from VSYNC (foreground-yielding) ===
+    // When active on an agent UI, a scheduled traversal is NOT bound to the shared
+    // VSYNC CALLBACK_TRAVERSAL queue (which would compete with the user's frame and
+    // post a sync barrier on the main looper). Instead it is posted as a deferred
+    // runnable that yields to the foreground: it runs the traversal only when the
+    // shared Choreographer has no foreground frame pending, re-posting otherwise.
+    // Continuation is automatic — if a traversal causes new invalidate/requestLayout,
+    // scheduleTraversals() re-arms the deferred runnable; "stable" = no more arming.
+    // This is independent of GPU bypass (Layer 2 / mAgentNoDraw): Layer 1 keeps normal
+    // GPU draw so the agent VirtualDisplay's ImageReader still receives frames.
+    //
+    // Decouple defaults ON for agent UIs. Its process-wide default is changed by
+    // the experiment controls so newly-created sub-activities inherit G1/G4 instead
+    // of silently returning to the automatic decoupled path after navigation. A
+    // tri-state per-window override remains available: 0=process default, 1=on,
+    // -1=off.
+    static final int AGENT_DECOUPLE_AUTO = 0;
+    static final int AGENT_DECOUPLE_ON = 1;
+    static final int AGENT_DECOUPLE_OFF = -1;
+    int mAgentDecoupleOverride = AGENT_DECOUPLE_AUTO;
+    static volatile boolean sAgentDecoupleDefault = true;
+    boolean mAgentTraversalScheduled;   // a deferred agent traversal is posted
+    int mAgentDeferredCount;            // profiling: deferred traversals run
+    // Layer 1 (IdleHandler-driven decouple): the agent traversal runs in the
+    // main-thread idle slot — i.e. the gap after the foreground's VSYNC doFrame has
+    // dispatched all its callbacks and the looper is about to sleep. This is event-
+    // driven (no polling, no mFrameScheduled boolean check, no 2ms self-repost) and
+    // never schedules a VSYNC of its own, so the vanilla foreground frame pipeline is
+    // untouched. Anti-starvation: on perpetually-invalidating pages the looper may
+    // stay busy and the idle slot never arrive; if the agent traversal has been
+    // pending longer than AGENT_DECOUPLE_MAX_DEFER_MS, the next idle/timeout forces
+    // one synthetic frame so the agent window cannot be starved into an input-
+    // dispatch-timeout ANR. A short bounded delay is acceptable; indefinite is not.
+    MessageQueue.IdleHandler mAgentTraversalIdler; // runs the deferred traversal at idle
+    boolean mAgentIdlerRegistered;      // idler currently added to the queue
+    long mAgentTraversalArmedAt;        // SystemClock.uptimeMillis() when armed
+    Runnable mAgentTraversalDeadlineRunnable; // safety-bound forced traversal
+    static final long AGENT_DECOUPLE_MAX_DEFER_MS = 48; // ~3 frames @60Hz: bound before forcing
+    // Layer 3: DL semantic-hash stability detection.
+    // When enabled, settle stability is judged by comparing the agent-consumable
+    // semantic fingerprint (text glyphs + device-space layout bounds, computed on
+    // the RenderThread) between consecutive passes, instead of (or in addition to)
+    // framework dirty flags. This settles "framework-perpetual" pages (spinners,
+    // periodic invalidates) as soon as their *content* stops changing.
+    boolean mAgentHashStabilityEnabled;
+    long mAgentLastSemanticHash;
+    boolean mAgentHasLastHash;
+
+    // Profiling-only readiness detector. Disabled by default and never controls when an
+    // observation stops. It correlates terminal input, a complete Java DisplayList pass,
+    // and the subsequent synchronous RenderThread staging-to-active handoff.
+    boolean mAgentDlProfileEnabled;
+    boolean mAgentDlProfileArmed;
+    boolean mAgentDlProfileActionActive;
+    boolean mAgentDlProfileTerminalDelivered;
+    boolean mAgentDlProfileRecordPassActive;
+    boolean mAgentDlProfilePendingSync;
+    long mAgentDlProfileActionGeneration;
+    long mAgentDlProfileActionStartNanos;
+    long mAgentDlProfileTerminalRecordGeneration;
+    long mAgentDlProfileRecordGeneration;
+    long mAgentDlProfileActiveGeneration;
+    long mAgentDlProfileActiveRecordGeneration;
+    long mAgentDlProfileLastRecordDurationNanos;
+    long mAgentDlProfileLastSyncDurationNanos;
+    long mAgentDlProfileRecordDurationTotalNanos;
+    long mAgentDlProfileSyncDurationTotalNanos;
+    long mAgentDlProfileSemanticDurationTotalNanos;
+    long mAgentDlProfileBookkeepingDurationTotalNanos;
+    long mAgentDlProfileRecordCount;
+    long mAgentDlProfileSyncCount;
+    long mAgentDlProfileSemanticCount;
+    long mAgentDlProfilePassRecordedNodes;
+    long mAgentDlProfilePassNodeSketch;
+    long mAgentDlProfileActiveRecordedNodes;
+    long mAgentDlProfileActiveNodeSketch;
+    long mAgentDlProfileActiveDirtyTick;
+    long mAgentDlProfileActiveRootId;
+    boolean mAgentDlProfileActiveRootValid;
+    int mAgentDlProfileLastSyncResult;
+    long mAgentDlProfileLastSemanticHash;
+    boolean mAgentDlProfileHasSemanticHash;
+    long mAgentDlProfileLastSampleDirtyTick;
+    long mAgentDlProfileLastSampleRootId;
+    int mAgentDlProfileQuietSlots;
+    long mAgentDlProfileReadyAtUs = -1;
+    long mAgentDlProfileQuiet1AtUs = -1;
+    long mAgentDlProfileQuiet2AtUs = -1;
+
+    private static final int AGENT_DL_PROFILE_SAMPLE_CAPACITY = 64;
+    private static final int AGENT_DL_PROFILE_SAMPLE_STRIDE = 15;
+    private static final int AGENT_DL_READY_TERMINAL = 1 << 0;
+    private static final int AGENT_DL_READY_POST_ACTION_RECORD = 1 << 1;
+    private static final int AGENT_DL_READY_ACTIVE_VALID = 1 << 2;
+    private static final int AGENT_DL_READY_INPUT_QUIET = 1 << 3;
+    private static final int AGENT_DL_READY_FRAMEWORK_QUIET = 1 << 4;
+    private static final int AGENT_DL_READY = 1 << 5;
+    private static final int AGENT_DL_HASH_REPEAT = 1 << 6;
+    private static final int AGENT_DL_HASH_SAMPLED = 1 << 7;
+    private static final int AGENT_DL_ROOT_CHANGED = 1 << 8;
+    long[] mAgentDlProfileSamples;
+    int mAgentDlProfileSampleCount;
+    int mAgentDlProfileSampleWrite;
+
+    // Only set while this thread is traversing an agent ViewRoot outside Choreographer#doFrame.
+    // View measure/layout/DisplayList recording use it to insert agent-only frame checkpoints;
+    // foreground ViewRoots never install this context and retain the vanilla traversal path.
+    private static final ThreadLocal<ViewRootImpl> sAgentNodeCheckpointRoot = new ThreadLocal<>();
+    long mAgentNodeCheckpointCount;
+    long mAgentNodeCheckpointFrameCount;
+
+    // === Agent on-demand idle-driven settle (foreground-yielding) ===
+    // Async counterpart of forceTraversalForAgent(): instead of running the whole
+    // settle loop synchronously (blocking the foreground), one settle pass is run
+    // per main-thread idle slot via mAgentSettleIdler. The IdleHandler only runs
+    // when the MessageQueue has no due messages, so the foreground's VSYNC doFrame
+    // always takes priority; each pass returns to the queue, re-checking for
+    // foreground work before the next pass. See docs/c3_ondemand_scheduling_design.md.
+    boolean mAgentObserveActive;        // an async observe session is in progress
+    boolean mAgentObserveNoDraw;        // noDraw flag captured for this session's Phase 2
+    int mAgentObserveBudget;            // max Phase 1 settle passes for this session
+    int mAgentObservePass;              // Phase 1 passes already run this session
+    long mAgentObserveLastTick;         // mAgentDirtyTick snapshot from previous pass
+    long mAgentObserveStartNanos;       // wall-clock start, for profiling
+    long mAgentObserveTimeoutMs;        // wall-clock fallback; 0 for legacy pass-bound mode
+    boolean mAgentObserveFreezeOnDone;  // traversal-only freeze after a consumable Phase 2
+    String mAgentObserveResult = "idle"; // active/readiness/timeout/budget/sync_failed
+    long mAgentObserveDurationMs;
+    Runnable mAgentObserveOnDone;       // optional callback fired (on UI thread) at Phase 2 end
+    Runnable mAgentSettleRunnable;      // the self-re-posting settle step
+    // Profiling: number of times a settle pass was deferred because the foreground
+    // had pending frame/traversal work (i.e. agent yielded to the foreground).
+    int mAgentYieldCount;
+    boolean mAgentLastSyncForAgentValid;
+    int mAgentLastSyncForAgentResult = -1;
+
     boolean mApplyInsetsRequested;
     boolean mLayoutRequested;
     boolean mFirst;
@@ -2609,6 +2828,7 @@ public final class ViewRootImpl implements ViewParent,
     @UnsupportedAppUsage
     void invalidate() {
         mDirty.set(0, 0, mWidth, mHeight);
+        mAgentDirtyTick++;
         if (!mWillDrawSoon) {
             scheduleTraversals();
         }
@@ -2674,6 +2894,12 @@ public final class ViewRootImpl implements ViewParent,
         if (!intersected) {
             localDirty.setEmpty();
         }
+        // Track partial invalidations as well as the full-root invalidate() path.
+        // This is an O(1) readiness signal; it deliberately avoids walking the
+        // View hierarchy or hashing the recorded DisplayList.
+        if (intersected || mIsAnimating) {
+            mAgentDirtyTick++;
+        }
         if (!mWillDrawSoon && (intersected || mIsAnimating)) {
             scheduleTraversals();
         }
@@ -3040,6 +3266,19 @@ public final class ViewRootImpl implements ViewParent,
 
     @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
     void scheduleTraversals() {
+        // Agent-frozen window: do not subscribe to real VSYNC / schedule traversal.
+        // The DisplayList is advanced only on demand (idle省电, Layer-1 disabled).
+        if (mAgentFrozen) {
+            return;
+        }
+        // Layer 1: agent UI with decouple active — route the traversal off the shared
+        // VSYNC TRAVERSAL queue into a foreground-yielding deferred runnable instead of
+        // posting a sync barrier + CALLBACK_TRAVERSAL (which competes with the user frame).
+        // Decouple defaults ON for agent UIs (window property); see isAgentDecoupleActive().
+        if (isAgentDecoupleActive()) {
+            scheduleAgentDeferredTraversal();
+            return;
+        }
         if (!mTraversalScheduled) {
             mTraversalScheduled = true;
             mTraversalBarrier = mHandler.getLooper().getQueue().postSyncBarrier();
@@ -3050,7 +3289,149 @@ public final class ViewRootImpl implements ViewParent,
         }
     }
 
+    /**
+     * Layer 1: arm a deferred agent traversal that runs in the main-thread idle slot
+     * (the gap between foreground VSYNC frames) via a {@link MessageQueue.IdleHandler}.
+     * This path posts NO sync barrier, NO Choreographer TRAVERSAL callback and does NOT
+     * subscribe to VSYNC, so the foreground frame pipeline is untouched (vanilla VSYNC
+     * semantics preserved). The traversal is serviced only when the looper has no due
+     * messages — i.e. after the foreground doFrame has run and the thread is about to
+     * sleep — with no polling and no mFrameScheduled check. A safety deadline
+     * (AGENT_DECOUPLE_MAX_DEFER_MS) forces one traversal if a continuously-busy looper
+     * never yields an idle slot, bounding deferral and preventing input-timeout ANRs.
+     */
+    private void scheduleAgentDeferredTraversal() {
+        if (mAgentTraversalScheduled) {
+            return;
+        }
+        mAgentTraversalScheduled = true;
+        mAgentTraversalArmedAt = SystemClock.uptimeMillis();
+
+        if (mAgentTraversalIdler == null) {
+            mAgentTraversalIdler = () -> {
+                // Runs when the main thread is about to idle: the foreground frame (if
+                // any) has already been dispatched. Run exactly one agent traversal,
+                // then remove the idler (return false). This callback itself runs on
+                // the UI looper, so it cannot execute concurrently with a traversal.
+                if (!mAgentTraversalScheduled) {
+                    mAgentIdlerRegistered = false;
+                    return false;
+                }
+                mAgentIdlerRegistered = false;
+                runAgentDeferredTraversalNow();
+                return false;
+            };
+        }
+        if (mAgentTraversalDeadlineRunnable == null) {
+            mAgentTraversalDeadlineRunnable = () -> {
+                // Safety bound: idle slot never arrived in time (busy looper). Force one
+                // traversal so the agent window cannot be starved into an ANR.
+                if (mAgentTraversalScheduled) {
+                    Trace.instant(Trace.TRACE_TAG_VIEW, "agentDeferDeadlineForce");
+                    runAgentDeferredTraversalNow();
+                }
+            };
+        }
+        if (!mAgentIdlerRegistered) {
+            mHandler.getLooper().getQueue().addIdleHandler(mAgentTraversalIdler);
+            mAgentIdlerRegistered = true;
+        }
+        mHandler.removeCallbacks(mAgentTraversalDeadlineRunnable);
+        mHandler.postDelayed(mAgentTraversalDeadlineRunnable, AGENT_DECOUPLE_MAX_DEFER_MS);
+    }
+
+    /**
+     * Run one agent traversal inside a synthetic frame. Shared by the idle path and the
+     * safety-deadline path. Clears the armed state and cancels the deadline.
+     */
+    private void runAgentDeferredTraversalNow() {
+        mAgentTraversalScheduled = false;
+        if (mAgentTraversalDeadlineRunnable != null) {
+            mHandler.removeCallbacks(mAgentTraversalDeadlineRunnable);
+        }
+        if (mAgentFrozen || mView == null || !mAdded) {
+            return;
+        }
+        // Profiling: count how many times the traversal had to wait past one frame for
+        // its idle slot (replaces the old 2ms busy-spin yield counter).
+        final long waited = SystemClock.uptimeMillis() - mAgentTraversalArmedAt;
+        if (waited > AGENT_DECOUPLE_MAX_DEFER_MS) {
+            mAgentYieldCount++;
+        }
+        Trace.traceBegin(Trace.TRACE_TAG_VIEW, "agentDeferredTraversal");
+        final boolean previousNoDraw = mAgentNoDraw;
+        try {
+            // Run outside Choreographer#doFrame so an arrived physical-display frame can be
+            // dispatched inline at a node checkpoint without recursively entering an outer
+            // agent doFrame. This prototype uses the existing DisplayList sync-only path.
+            if (mTraversalScheduled) {
+                mTraversalScheduled = false;
+                mHandler.getLooper().getQueue().removeSyncBarrier(mTraversalBarrier);
+                mChoreographer.removeCallbacks(
+                        Choreographer.CALLBACK_TRAVERSAL, mTraversalRunnable, null);
+            }
+            mFullRedrawNeeded = true;
+            mAgentNoDraw = true;
+            performAgentNodeCheckpointTraversal();
+            mAgentDeferredCount++;
+        } finally {
+            mAgentNoDraw = previousNoDraw;
+            Trace.traceEnd(Trace.TRACE_TAG_VIEW);
+        }
+    }
+
+    private void performAgentNodeCheckpointTraversal() {
+        if (!isAgentUi()) {
+            performTraversals();
+            return;
+        }
+        final ViewRootImpl previousRoot = sAgentNodeCheckpointRoot.get();
+        sAgentNodeCheckpointRoot.set(this);
+        mChoreographer.beginAgentNodeCheckpointTraversal();
+        try {
+            performTraversals();
+        } finally {
+            mChoreographer.endAgentNodeCheckpointTraversal();
+            if (previousRoot == null) {
+                sAgentNodeCheckpointRoot.remove();
+            } else {
+                sAgentNodeCheckpointRoot.set(previousRoot);
+            }
+            agentDlProfileOnTraversalComplete();
+        }
+    }
+
+    static void agentNodeCheckpoint(View view) {
+        agentNodeCheckpoint(view, false);
+    }
+
+    static void agentNodeCheckpoint(View view, boolean displayListRecorded) {
+        final ViewRootImpl root = sAgentNodeCheckpointRoot.get();
+        if (root == null || view == null || view.mAttachInfo == null
+                || view.mAttachInfo.mViewRootImpl != root || !root.mIsInTraversal) {
+            return;
+        }
+        if (displayListRecorded && root.mAgentDlProfileEnabled
+                && root.mAgentDlProfileRecordPassActive) {
+            root.agentDlProfileOnNodeRecorded(view);
+        }
+        root.mAgentNodeCheckpointCount++;
+        if (root.mChoreographer.doFrameAtAgentNodeCheckpoint()) {
+            root.mAgentNodeCheckpointFrameCount++;
+        }
+    }
+
     void unscheduleTraversals() {
+        if (mAgentTraversalScheduled) {
+            mAgentTraversalScheduled = false;
+            if (mAgentIdlerRegistered && mAgentTraversalIdler != null) {
+                mHandler.getLooper().getQueue().removeIdleHandler(mAgentTraversalIdler);
+                mAgentIdlerRegistered = false;
+            }
+            if (mAgentTraversalDeadlineRunnable != null) {
+                mHandler.removeCallbacks(mAgentTraversalDeadlineRunnable);
+            }
+        }
         if (mTraversalScheduled) {
             mTraversalScheduled = false;
             mHandler.getLooper().getQueue().removeSyncBarrier(mTraversalBarrier);
@@ -3077,6 +3458,1025 @@ public final class ViewRootImpl implements ViewParent,
         }
     }
 
+    /**
+     * Force a single measure/layout/draw-record traversal on demand, bypassing VSYNC.
+     * When {@code noDraw} is true the DisplayList is recorded and synced to the
+     * RenderThread but the GPU draw is skipped (zero GPU/SurfaceFlinger work), which
+     * is what lets an agent read a fresh DisplayList from an unbound or STATE_OFF
+     * display. Must be called on the UI thread (use mHandler.runWithScissors from
+     * other threads).
+     * @hide
+     */
+    public void forceTraversalForAgent(boolean noDraw) {
+        forceTraversalForAgent(noDraw, 0);
+    }
+
+    /**
+     * Force on-demand traversal with an optional fake-VSYNC pump (dual-phase).
+     *
+     * <p><b>Phase 1 (settle):</b> Repeatedly synthesizes frame-clock signals via
+     * {@link Choreographer#doFrameForAgent} and runs measure+layout (skipping
+     * drawing-command recording) until the view tree settles—no new invalidation,
+     * no pending layout, no active hardware animations—or until {@code vsyncFrames}
+     * synthetic frames have been delivered, whichever comes first. This advances
+     * property animations, frame callbacks, and async content while paying only the
+     * CPU cost of measure and layout per iteration.
+     *
+     * <p><b>Phase 2 (record):</b> A single full traversal records drawing commands
+     * into the DisplayList and syncs to the RenderThread. {@code noDraw} keeps the
+     * renderer in sync-only mode (zero GPU/SurfaceFlinger work).
+     *
+     * <p>Must be called on the UI thread.
+     * @hide
+     */
+    public void forceTraversalForAgent(boolean noDraw, int vsyncFrames) {
+        // This API is dispatched with runWithScissors on the UI looper, so there is
+        // no concurrent traversal on this thread. Do not trust a stale
+        // mIsInTraversal bit left by an earlier aborted platform traversal.
+        if (mView == null || !mAdded) {
+            return;
+        }
+        final boolean prevNoDraw = mAgentNoDraw;
+        final boolean prevSkipRecord = mAgentSkipRecord;
+        final boolean hashMode = mAgentHashStabilityEnabled;
+        mAgentHasLastHash = false; // reset hash baseline for this observe
+        try {
+            // === Phase 1: pump animations + settle view tree ===
+            // In hash mode we MUST record during settle (skip-record produces no DL
+            // to fingerprint), so the hash reflects current content each pass.
+            mAgentNoDraw = true;
+            mAgentSkipRecord = !hashMode;
+            long lastTick = mAgentDirtyTick;
+            boolean settled = true;
+
+            for (int i = 0; i < vsyncFrames; i++) {
+                agentRunOneSettlePass();
+                boolean stable;
+                if (hashMode) {
+                    // Layer 3: settle when agent-consumable content stops changing,
+                    // even if framework dirty flags keep firing (spinner/periodic).
+                    stable = agentIsContentStable();
+                } else {
+                    // Framework-stable: no new invalidation, no pending layout/hw-anim.
+                    stable = (mAgentDirtyTick == lastTick) && agentIsFrameworkStable();
+                }
+                if (stable) {
+                    break;
+                }
+                lastTick = mAgentDirtyTick;
+                if (i == vsyncFrames - 1) settled = false;  // ran out of budget
+            }
+            mAgentSettled = settled;
+
+            // === Phase 2: view tree settled (or bound reached), record DL once ===
+            mAgentNoDraw = noDraw;
+            mAgentSkipRecord = false;
+            agentRecordPhase2();
+        } finally {
+            mAgentNoDraw = prevNoDraw;
+            mAgentSkipRecord = prevSkipRecord;
+        }
+    }
+
+    // ===================================================================================
+    // Agent on-demand shared helpers + idle-driven (foreground-yielding) settle.
+    // See docs/c3_ondemand_scheduling_design.md (§2 scheduling, §4 settle, §5 animation).
+    // ===================================================================================
+
+    /**
+     * Returns true if the agent view tree is framework-stable: no pending layout and
+     * no active hardware animations. (Caller separately compares mAgentDirtyTick to
+     * detect new invalidations between passes.)
+     */
+    private boolean agentIsFrameworkStable() {
+        return !mLayoutRequested
+                && (mAttachInfo == null
+                    || mAttachInfo.mPendingAnimatingRenderNodes == null
+                    || mAttachInfo.mPendingAnimatingRenderNodes.isEmpty());
+    }
+
+    /**
+     * Layer 3: current DL semantic fingerprint (text + layout), or 0 if unavailable.
+     * Computed synchronously on the RenderThread; requires a recorded DisplayList,
+     * so only meaningful after a recording traversal (not a skip-record pass).
+     */
+    private long agentSemanticHash() {
+        if (mAttachInfo != null && mAttachInfo.mThreadedRenderer != null) {
+            return mAttachInfo.mThreadedRenderer.computeSemanticHash();
+        }
+        return 0;
+    }
+
+    /**
+     * Layer 3: returns true if the agent-consumable content (text+layout) has not
+     * changed since the previous pass, i.e. the semantic fingerprint repeated.
+     * Updates the stored hash. The first call after reset always returns false
+     * (no prior hash to compare). Use to settle framework-perpetual pages.
+     */
+    private boolean agentIsContentStable() {
+        long h = agentSemanticHash();
+        boolean stable = mAgentHasLastHash && (h == mAgentLastSemanticHash);
+        mAgentLastSemanticHash = h;
+        mAgentHasLastHash = true;
+        return stable;
+    }
+
+    boolean isAgentDlProfileRecordingActive() {
+        return mAgentDlProfileEnabled && mAgentDlProfileActionActive;
+    }
+
+    /** Enables the profiling-only DL readiness observer. It never changes settle behavior. */
+    public void setAgentDlProfileEnabled(boolean enabled) {
+        mAgentDlProfileEnabled = enabled && isAgentUi();
+        if (mAgentDlProfileEnabled && mAgentDlProfileSamples == null) {
+            mAgentDlProfileSamples = new long[AGENT_DL_PROFILE_SAMPLE_CAPACITY
+                    * AGENT_DL_PROFILE_SAMPLE_STRIDE];
+        }
+        if (!mAgentDlProfileEnabled) {
+            mAgentDlProfileArmed = false;
+            mAgentDlProfileActionActive = false;
+            mAgentDlProfileRecordPassActive = false;
+            mAgentDlProfilePendingSync = false;
+        }
+    }
+
+    /** Arms the next touch/key action as a profiling epoch. */
+    public void armAgentDlProfile() {
+        if (!mAgentDlProfileEnabled || !isAgentUi()) {
+            return;
+        }
+        mAgentDlProfileArmed = true;
+        mAgentDlProfileActionActive = false;
+        mAgentDlProfileTerminalDelivered = false;
+        mAgentDlProfileSampleCount = 0;
+        mAgentDlProfileSampleWrite = 0;
+        mAgentDlProfileHasSemanticHash = false;
+        mAgentDlProfileQuietSlots = 0;
+        mAgentDlProfileReadyAtUs = -1;
+        mAgentDlProfileQuiet1AtUs = -1;
+        mAgentDlProfileQuiet2AtUs = -1;
+        mAgentDlProfileLastSampleDirtyTick = mAgentDirtyTick;
+        mAgentDlProfileLastSampleRootId = 0;
+    }
+
+    private void agentDlProfileOnInputDispatched(InputEvent event) {
+        if (!mAgentDlProfileEnabled || !mAgentDlProfileArmed) {
+            return;
+        }
+        final boolean startsAction = event instanceof MotionEvent
+                ? ((MotionEvent) event).getActionMasked() == MotionEvent.ACTION_DOWN
+                : event instanceof KeyEvent
+                        && ((KeyEvent) event).getAction() == KeyEvent.ACTION_DOWN
+                        && ((KeyEvent) event).getRepeatCount() == 0;
+        if (!startsAction) {
+            return;
+        }
+        mAgentDlProfileActionGeneration++;
+        mAgentDlProfileActionActive = true;
+        mAgentDlProfileTerminalDelivered = false;
+        mAgentDlProfileActionStartNanos = System.nanoTime();
+        mAgentDlProfileTerminalRecordGeneration = mAgentDlProfileRecordGeneration;
+        mAgentDlProfileSampleCount = 0;
+        mAgentDlProfileSampleWrite = 0;
+        mAgentDlProfileHasSemanticHash = false;
+        mAgentDlProfileQuietSlots = 0;
+        mAgentDlProfileReadyAtUs = -1;
+        mAgentDlProfileQuiet1AtUs = -1;
+        mAgentDlProfileQuiet2AtUs = -1;
+        mAgentDlProfileLastSampleDirtyTick = mAgentDirtyTick;
+        mAgentDlProfileLastSampleRootId = 0;
+    }
+
+    private void agentDlProfileOnInputFinished(InputEvent event) {
+        if (!mAgentDlProfileEnabled || !mAgentDlProfileActionActive) {
+            return;
+        }
+        final boolean finishesAction = event instanceof MotionEvent
+                ? ((MotionEvent) event).getActionMasked() == MotionEvent.ACTION_UP
+                        || ((MotionEvent) event).getActionMasked() == MotionEvent.ACTION_CANCEL
+                : event instanceof KeyEvent && ((KeyEvent) event).getAction() == KeyEvent.ACTION_UP;
+        if (!finishesAction) {
+            return;
+        }
+        mAgentDlProfileTerminalDelivered = true;
+        mAgentDlProfileTerminalRecordGeneration = mAgentDlProfileRecordGeneration;
+        mAgentDlProfileArmed = false;
+        Trace.instant(Trace.TRACE_TAG_VIEW, "agentDlProfileTerminalInput");
+    }
+
+    void agentDlProfileOnRecordPassBegin() {
+        if (!mAgentDlProfileEnabled) {
+            return;
+        }
+        mAgentDlProfileRecordPassActive = true;
+        mAgentDlProfilePassRecordedNodes = 0;
+        mAgentDlProfilePassNodeSketch = 0;
+    }
+
+    private void agentDlProfileOnNodeRecorded(View view) {
+        final long id = view.getUniqueDrawingId();
+        long mixed = id + 0x9e3779b97f4a7c15L;
+        mixed = (mixed ^ (mixed >>> 30)) * 0xbf58476d1ce4e5b9L;
+        mixed = (mixed ^ (mixed >>> 27)) * 0x94d049bb133111ebL;
+        mixed ^= mixed >>> 31;
+        mAgentDlProfilePassRecordedNodes++;
+        mAgentDlProfilePassNodeSketch ^= Long.rotateLeft(mixed,
+                (int) (mAgentDlProfilePassRecordedNodes & 63));
+    }
+
+    void agentDlProfileOnRecordPassComplete(boolean stagingRootValid, long rootId,
+            long durationNanos) {
+        if (!mAgentDlProfileEnabled) {
+            return;
+        }
+        mAgentDlProfileRecordGeneration++;
+        mAgentDlProfileRecordCount++;
+        mAgentDlProfileLastRecordDurationNanos = durationNanos;
+        mAgentDlProfileRecordDurationTotalNanos += durationNanos;
+        mAgentDlProfileActiveRecordGeneration = mAgentDlProfileRecordGeneration;
+        mAgentDlProfileActiveRecordedNodes = mAgentDlProfilePassRecordedNodes;
+        mAgentDlProfileActiveNodeSketch = mAgentDlProfilePassNodeSketch;
+        mAgentDlProfileActiveDirtyTick = mAgentDirtyTick;
+        mAgentDlProfileActiveRootId = rootId;
+        mAgentDlProfileActiveRootValid = stagingRootValid;
+    }
+
+    void agentDlProfileOnActiveSyncComplete(int syncResult, long durationNanos) {
+        if (!mAgentDlProfileEnabled) {
+            return;
+        }
+        // syncAndDrawFrame() is synchronous: this is the record generation that has
+        // crossed the RenderThread staging-to-active boundary, not a separate counter.
+        mAgentDlProfileActiveGeneration = mAgentDlProfileActiveRecordGeneration;
+        mAgentDlProfileSyncCount++;
+        mAgentDlProfileLastSyncDurationNanos = durationNanos;
+        mAgentDlProfileSyncDurationTotalNanos += durationNanos;
+        mAgentDlProfileLastSyncResult = syncResult;
+        mAgentDlProfilePendingSync = true;
+    }
+
+    private void agentDlProfileOnTraversalComplete() {
+        if (!mAgentDlProfileEnabled || !mAgentDlProfilePendingSync) {
+            return;
+        }
+        mAgentDlProfilePendingSync = false;
+        mAgentDlProfileRecordPassActive = false;
+        if (!mAgentDlProfileActionActive) {
+            return;
+        }
+
+        final long bookkeepingStart = System.nanoTime();
+        int readiness = 0;
+        if (mAgentDlProfileTerminalDelivered) {
+            readiness |= AGENT_DL_READY_TERMINAL;
+        }
+        if (mAgentDlProfileTerminalDelivered
+                && mAgentDlProfileActiveRecordGeneration
+                        > mAgentDlProfileTerminalRecordGeneration) {
+            readiness |= AGENT_DL_READY_POST_ACTION_RECORD;
+        }
+        if (mAgentDlProfileActiveRootValid) {
+            readiness |= AGENT_DL_READY_ACTIVE_VALID;
+        }
+        if (mPendingInputEventCount == 0 && !mProcessInputEventsScheduled) {
+            readiness |= AGENT_DL_READY_INPUT_QUIET;
+        }
+        if (!mTraversalScheduled && !mAgentTraversalScheduled && !mLayoutRequested) {
+            readiness |= AGENT_DL_READY_FRAMEWORK_QUIET;
+        }
+        final boolean rootChanged = mAgentDlProfileLastSampleRootId != 0
+                && mAgentDlProfileLastSampleRootId != mAgentDlProfileActiveRootId;
+        if (rootChanged) {
+            readiness |= AGENT_DL_ROOT_CHANGED;
+        }
+        final int required = AGENT_DL_READY_TERMINAL | AGENT_DL_READY_POST_ACTION_RECORD
+                | AGENT_DL_READY_ACTIVE_VALID | AGENT_DL_READY_INPUT_QUIET
+                | AGENT_DL_READY_FRAMEWORK_QUIET;
+        final int candidateRequired = AGENT_DL_READY_TERMINAL
+                | AGENT_DL_READY_POST_ACTION_RECORD | AGENT_DL_READY_ACTIVE_VALID
+                | AGENT_DL_READY_INPUT_QUIET;
+        final boolean ready = (readiness & required) == required;
+        final boolean candidateReady = (readiness & candidateRequired) == candidateRequired;
+        if (ready) {
+            readiness |= AGENT_DL_READY;
+        }
+
+        final boolean generationChanged = mAgentDlProfileActiveRecordedNodes != 0
+                || mAgentDlProfileActiveDirtyTick != mAgentDlProfileLastSampleDirtyTick
+                || rootChanged;
+        if (candidateReady && !generationChanged) {
+            mAgentDlProfileQuietSlots++;
+        } else {
+            mAgentDlProfileQuietSlots = 0;
+        }
+        long semanticDurationNanos = 0;
+        if (candidateReady && (!mAgentDlProfileHasSemanticHash || generationChanged
+                || mAgentDlProfileQuietSlots == 1)) {
+            final long hashStart = System.nanoTime();
+            final long hash = agentSemanticHash();
+            semanticDurationNanos = System.nanoTime() - hashStart;
+            if (mAgentDlProfileHasSemanticHash && hash == mAgentDlProfileLastSemanticHash) {
+                readiness |= AGENT_DL_HASH_REPEAT;
+            }
+            mAgentDlProfileLastSemanticHash = hash;
+            mAgentDlProfileHasSemanticHash = true;
+            mAgentDlProfileSemanticCount++;
+            mAgentDlProfileSemanticDurationTotalNanos += semanticDurationNanos;
+            readiness |= AGENT_DL_HASH_SAMPLED;
+        } else if (candidateReady && mAgentDlProfileHasSemanticHash && !generationChanged) {
+            readiness |= AGENT_DL_HASH_REPEAT;
+        }
+        final long sinceActionUs = mAgentDlProfileActionStartNanos == 0 ? -1
+                : (System.nanoTime() - mAgentDlProfileActionStartNanos) / 1000;
+        if (ready && mAgentDlProfileReadyAtUs < 0) {
+            mAgentDlProfileReadyAtUs = sinceActionUs;
+        }
+        if (mAgentDlProfileQuietSlots >= 1 && mAgentDlProfileQuiet1AtUs < 0) {
+            mAgentDlProfileQuiet1AtUs = sinceActionUs;
+        }
+        if (mAgentDlProfileQuietSlots >= 2 && mAgentDlProfileQuiet2AtUs < 0) {
+            mAgentDlProfileQuiet2AtUs = sinceActionUs;
+        }
+        agentDlProfileAppendSample(sinceActionUs, readiness, semanticDurationNanos);
+        mAgentDlProfileLastSampleDirtyTick = mAgentDlProfileActiveDirtyTick;
+        mAgentDlProfileLastSampleRootId = mAgentDlProfileActiveRootId;
+        mAgentDlProfileBookkeepingDurationTotalNanos +=
+                System.nanoTime() - bookkeepingStart - semanticDurationNanos;
+    }
+
+    private void agentDlProfileAppendSample(long sinceActionUs, int readiness,
+            long semanticDurationNanos) {
+        if (mAgentDlProfileSamples == null) {
+            return;
+        }
+        final int slot = mAgentDlProfileSampleWrite;
+        final int base = slot * AGENT_DL_PROFILE_SAMPLE_STRIDE;
+        mAgentDlProfileSamples[base] = sinceActionUs;
+        mAgentDlProfileSamples[base + 1] = mAgentDlProfileActionGeneration;
+        mAgentDlProfileSamples[base + 2] = mAgentDlProfileRecordGeneration;
+        mAgentDlProfileSamples[base + 3] = mAgentDlProfileActiveGeneration;
+        mAgentDlProfileSamples[base + 4] = mAgentDlProfileActiveRecordedNodes;
+        mAgentDlProfileSamples[base + 5] = mAgentDlProfileActiveNodeSketch;
+        mAgentDlProfileSamples[base + 6] = mAgentDlProfileActiveDirtyTick;
+        mAgentDlProfileSamples[base + 7] = mAgentDlProfileActiveRootId;
+        mAgentDlProfileSamples[base + 8] = readiness;
+        mAgentDlProfileSamples[base + 9] = mAgentDlProfileQuietSlots;
+        mAgentDlProfileSamples[base + 10] = mAgentDlProfileLastSemanticHash;
+        mAgentDlProfileSamples[base + 11] = mAgentDlProfileLastRecordDurationNanos;
+        mAgentDlProfileSamples[base + 12] = mAgentDlProfileLastSyncDurationNanos;
+        mAgentDlProfileSamples[base + 13] = semanticDurationNanos;
+        mAgentDlProfileSamples[base + 14] = mAgentDlProfileLastSyncResult;
+        mAgentDlProfileSampleWrite = (slot + 1) % AGENT_DL_PROFILE_SAMPLE_CAPACITY;
+        if (mAgentDlProfileSampleCount < AGENT_DL_PROFILE_SAMPLE_CAPACITY) {
+            mAgentDlProfileSampleCount++;
+        }
+    }
+
+    /**
+     * Run one Phase-1 settle pass on the agent window: advance this window's own
+     * animations, then one measure+layout traversal with DisplayList recording
+     * skipped (mAgentSkipRecord). Caller must have set mAgentNoDraw/mAgentSkipRecord.
+     */
+    private void agentRunOneSettlePass() {
+        Trace.traceBegin(Trace.TRACE_TAG_VIEW, "agentSettlePass");
+        try {
+            // Part B: advance only this agent window's animations. Property animations
+            // (ValueAnimator) share a single thread-wide AnimationHandler callback and
+            // cannot be split per-display here, so we do NOT pump them; they ride the
+            // foreground's real VSYNC. We drive only this window's frame-clock callbacks
+            // (View#postOnAnimation actions + hardware animators) via doFrameForAgent.
+            mChoreographer.doFrameForAgent();
+            if (mTraversalScheduled) {
+                mTraversalScheduled = false;
+                mHandler.getLooper().getQueue().removeSyncBarrier(mTraversalBarrier);
+            }
+            mFullRedrawNeeded = true;
+            performAgentNodeCheckpointTraversal();
+            mAgentPhase1Count++;
+        } finally {
+            Trace.traceEnd(Trace.TRACE_TAG_VIEW);
+        }
+    }
+
+    /** Phase-2: one full traversal that records the DisplayList and syncs to RT. */
+    private void agentRecordPhase2() {
+        Trace.traceBegin(Trace.TRACE_TAG_VIEW, "agentRecordPhase2");
+        try {
+            // Phase 2 runs with mAgentNoDraw set by the caller: performDraw routes
+            // through syncForAgent (record + RT sync, no GPU draw), which does NOT
+            // call Choreographer.getFrameTimeNanos(), so no frame-in-progress context
+            // is required here.
+            if (mTraversalScheduled) {
+                mTraversalScheduled = false;
+                mHandler.getLooper().getQueue().removeSyncBarrier(mTraversalBarrier);
+            }
+            mAgentLastSyncForAgentValid = false;
+            mAgentLastSyncForAgentResult = -1;
+            mFullRedrawNeeded = true;
+            performAgentNodeCheckpointTraversal();
+            mAgentPhase2Count++;
+        } finally {
+            Trace.traceEnd(Trace.TRACE_TAG_VIEW);
+        }
+    }
+
+    /**
+     * True if the foreground (main display) has pending frame work this looper is
+     * about to service. Used by the idle-driven settle to yield: when the foreground
+     * has a scheduled frame, the agent defers its next pass so the foreground VSYNC
+     * doFrame runs first.
+     */
+    private boolean agentForegroundHasPendingWork() {
+        // mChoreographer is the shared per-thread instance; if a frame is scheduled on
+        // it, a foreground doFrame is pending. Also honor any pending traversal that is
+        // not our own frozen agent window.
+        return mChoreographer != null && mChoreographer.isFrameScheduledForAgentCheck();
+    }
+
+    /**
+     * Begin an asynchronous, foreground-yielding on-demand observe. Runs at most
+     * {@code vsyncFrames} Phase-1 settle passes — one per main-thread idle slot — then
+     * a single Phase-2 record pass, then invokes {@code onDone} (on the UI thread).
+     *
+     * <p>Unlike {@link #forceTraversalForAgent}, this never blocks the foreground: each
+     * settle pass runs only when the MessageQueue has no due messages, and yields back
+     * to the queue between passes so foreground VSYNC frames are serviced first.
+     *
+     * <p>Must be called on the UI thread.
+     * @hide
+     */
+    public void beginAgentObserve(boolean noDraw, int vsyncFrames, Runnable onDone) {
+        beginAgentObserveInternal(noDraw, Math.max(1, vsyncFrames), 0, false, onDone);
+    }
+
+    /**
+     * Begin a cheap action-to-observation settle. Framework dirty/readiness may end the
+     * window early; {@code timeoutMs} retains the old fixed wait as a hard fallback.
+     * A successful final DisplayList record/sync is followed by traversal-only freeze.
+     *
+     * <p>The caller starts this after action injection has completed. This deliberately
+     * defines readiness as "the action has been consumed and a current UI snapshot is
+     * available", not equality with UI content that may arrive asynchronously later.
+     * @hide
+     */
+    public void beginAgentReadyObserve(boolean noDraw, long timeoutMs, Runnable onDone) {
+        if (!isAgentUi() || mView == null || !mAdded || !mAppVisible
+                || mView.getVisibility() != View.VISIBLE) {
+            if (onDone != null) onDone.run();
+            return;
+        }
+        setAgentTraversalFrozen(false);
+        beginAgentObserveInternal(noDraw, 0, Math.max(1, timeoutMs), true, onDone);
+    }
+
+    private void beginAgentObserveInternal(boolean noDraw, int passBudget, long timeoutMs,
+            boolean freezeOnDone, Runnable onDone) {
+        if (mView == null || !mAdded) {
+            if (DEBUG_AGENT) Log.i(mTag, "AgentObserve: skip (view=" + (mView != null)
+                    + " added=" + mAdded + ")");
+            if (onDone != null) onDone.run();
+            return;
+        }
+        if (mAgentObserveActive) {
+            // Already running; ignore re-entrant request but still release the caller.
+            if (DEBUG_AGENT) Log.i(mTag, "AgentObserve: already active, releasing caller");
+            if (onDone != null) onDone.run();
+            return;
+        }
+        if (DEBUG_AGENT) Log.i(mTag, "AgentObserve: begin noDraw=" + noDraw
+                + " budget=" + passBudget + " timeoutMs=" + timeoutMs
+                + " freezeOnDone=" + freezeOnDone);
+        mAgentObserveActive = true;
+        mAgentObserveNoDraw = noDraw;
+        mAgentObserveBudget = passBudget;
+        mAgentObservePass = 0;
+        mAgentObserveLastTick = mAgentDirtyTick;
+        mAgentObserveStartNanos = System.nanoTime();
+        mAgentObserveTimeoutMs = timeoutMs;
+        mAgentObserveFreezeOnDone = freezeOnDone;
+        mAgentObserveResult = "active";
+        mAgentObserveDurationMs = 0;
+        mAgentObserveOnDone = onDone;
+        mAgentSettled = true;
+        mAgentHasLastHash = false; // reset hash baseline for this observe
+        Trace.asyncTraceBegin(Trace.TRACE_TAG_VIEW, "agentObserve", System.identityHashCode(this));
+
+        if (mAgentSettleRunnable == null) {
+            mAgentSettleRunnable = this::agentOnSettleStep;
+        }
+        // Post the first pass. Each pass self-continues by re-posting, returning to the
+        // looper between passes so the foreground's doFrame (also a queued message) is
+        // serviced first when due.
+        mHandler.post(mAgentSettleRunnable);
+    }
+
+    /**
+     * One step of the posted-continuation settle. Runs at most one Phase-1 pass, then
+     * either re-posts itself (more passes needed) or records Phase 2 and finishes. Yields
+     * to the foreground by deferring (re-post) when a foreground frame is scheduled.
+     */
+    private void agentOnSettleStep() {
+        if (DEBUG_AGENT) Log.i(mTag, "AgentObserve: step pass=" + mAgentObservePass
+                + " active=" + mAgentObserveActive + " yields=" + mAgentYieldCount);
+        if (!mAgentObserveActive || mView == null || !mAdded) {
+            if (mAgentObserveActive) mAgentObserveResult = "detached";
+            agentFinishObserve();
+            return;
+        }
+        // Yield: if the foreground has a frame scheduled, defer this pass so the
+        // foreground doFrame is serviced first. Re-post with a small delay to avoid a
+        // busy loop while the foreground frame is pending.
+        final boolean deadlineReached = mAgentObserveTimeoutMs > 0
+                && (System.nanoTime() - mAgentObserveStartNanos) / 1_000_000
+                        >= mAgentObserveTimeoutMs;
+        if (agentForegroundHasPendingWork() && !deadlineReached) {
+            mAgentYieldCount++;
+            Trace.instant(Trace.TRACE_TAG_VIEW, "agentYieldToForeground");
+            mHandler.postDelayed(mAgentSettleRunnable, 4);
+            return;
+        }
+        final boolean prevNoDraw = mAgentNoDraw;
+        final boolean prevSkipRecord = mAgentSkipRecord;
+        // The production ready-settle path is intentionally O(1): never enable the
+        // profiling semantic hash even if a previous experiment left hash mode on.
+        final boolean hashMode = mAgentHashStabilityEnabled && mAgentObserveTimeoutMs == 0;
+        boolean done = false;
+        try {
+            // Phase 1 pass. In hash mode, record during settle so the content
+            // fingerprint reflects the current frame.
+            mAgentNoDraw = true;
+            mAgentSkipRecord = !hashMode;
+            agentRunOneSettlePass();
+            mAgentObservePass++;
+
+            final boolean stable;
+            if (hashMode) {
+                stable = agentIsContentStable();
+            } else {
+                stable = (mAgentDirtyTick == mAgentObserveLastTick)
+                        && agentIsFrameworkStable()
+                        && (mAgentObserveTimeoutMs == 0
+                                || (!mTraversalScheduled && !mAgentTraversalScheduled));
+            }
+            mAgentObserveLastTick = mAgentDirtyTick;
+
+            final long elapsedMs = (System.nanoTime() - mAgentObserveStartNanos) / 1_000_000;
+            final boolean timedOut = mAgentObserveTimeoutMs > 0
+                    && elapsedMs >= mAgentObserveTimeoutMs;
+            final boolean budgetExhausted = mAgentObserveBudget > 0
+                    && mAgentObservePass >= mAgentObserveBudget;
+            if (stable || timedOut || budgetExhausted) {
+                // A candidate and both fallback paths publish one final complete DL.
+                // In readiness mode, re-check O(1) framework state after recording:
+                // record callbacks can themselves schedule more UI work.
+                mAgentNoDraw = mAgentObserveNoDraw;
+                mAgentSkipRecord = false;
+                final long beforeRecordTick = mAgentDirtyTick;
+                agentRecordPhase2();
+                final boolean syncReady = mAgentLastSyncForAgentValid
+                        && mAgentLastSyncForAgentResult == 0;
+                final boolean quietAfterRecord = mAgentDirtyTick == beforeRecordTick
+                        && agentIsFrameworkStable() && !mTraversalScheduled
+                        && !mAgentTraversalScheduled;
+                final boolean readinessReady = stable && syncReady
+                        && (!mAgentObserveFreezeOnDone || quietAfterRecord);
+
+                if (readinessReady || timedOut || budgetExhausted) {
+                    mAgentSettled = readinessReady;
+                    if (!syncReady) {
+                        mAgentObserveResult = "sync_failed";
+                    } else if (readinessReady) {
+                        mAgentObserveResult = "readiness";
+                    } else if (timedOut) {
+                        mAgentObserveResult = "timeout";
+                    } else {
+                        mAgentObserveResult = "budget";
+                    }
+                    if (syncReady && mAgentObserveFreezeOnDone) {
+                        setAgentTraversalFrozen(true);
+                    }
+                    done = true;
+                }
+            }
+        } finally {
+            mAgentNoDraw = prevNoDraw;
+            mAgentSkipRecord = prevSkipRecord;
+        }
+
+        if (done) {
+            agentFinishObserve();
+        } else {
+            // Readiness is sampled at approximately one 60-Hz UI period. This avoids
+            // turning an idle queue into a tight synthetic-frame loop.
+            mHandler.postDelayed(mAgentSettleRunnable,
+                    mAgentObserveTimeoutMs > 0 ? 16 : 0);
+        }
+    }
+
+    private void agentFinishObserve() {
+        if (!mAgentObserveActive) {
+            return;
+        }
+        mAgentObserveActive = false;
+        mAgentObserveDurationMs = (System.nanoTime() - mAgentObserveStartNanos) / 1_000_000;
+        Trace.asyncTraceEnd(Trace.TRACE_TAG_VIEW, "agentObserve", System.identityHashCode(this));
+        final Runnable onDone = mAgentObserveOnDone;
+        mAgentObserveOnDone = null;
+        if (mAgentSettleRunnable != null) {
+            mHandler.removeCallbacks(mAgentSettleRunnable);
+        }
+        if (onDone != null) {
+            onDone.run();
+        }
+    }
+
+    /** O(1) completion marker for the sync-only RenderThread handoff. */
+    void agentOnSyncForAgentComplete(boolean rootDisplayListValid, int syncResult) {
+        mAgentLastSyncForAgentValid = rootDisplayListValid;
+        mAgentLastSyncForAgentResult = syncResult;
+    }
+
+    /**
+     * Returns true if the view tree has no pending traversal/layout work, i.e. the
+     * DisplayList obtained right now reflects a settled UI. Note this does not detect
+     * asynchronous work (network/decode) that has not yet posted back to the UI thread.
+     * @hide
+     */
+    public boolean isViewTreeStable() {
+        return !mTraversalScheduled && !mLayoutRequested && !mIsInTraversal
+                && (mAttachInfo == null || mAttachInfo.mPendingAnimatingRenderNodes == null
+                        || mAttachInfo.mPendingAnimatingRenderNodes.isEmpty());
+    }
+
+    /**
+     * Freeze/unfreeze only this agent window's real-VSYNC-driven traversal scheduling.
+     * Unlike {@link #setAgentFrozen}, this method does not destroy HardwareRenderer
+     * content. It exists for the CPU scheduling experiment where GPU-resource release
+     * and reconstruction would be a confounding variable.
+     * @hide
+     */
+    public void setAgentTraversalFrozen(boolean frozen) {
+        if (frozen && !isAgentUi()) {
+            return;
+        }
+        if (mAgentFrozen == frozen) {
+            return;
+        }
+        mAgentFrozen = frozen;
+        if (!frozen) {
+            scheduleTraversals();
+        }
+    }
+
+    /**
+     * Freeze/unfreeze this window's real-VSYNC-driven self-rendering. Only honored on
+     * agent displays (never the main display 0) so the user's UI is never frozen. While
+     * frozen, scheduleTraversals() is a no-op (the app stops rendering this window on
+     * VSYNC, zero GPU); the agent advances the DisplayList on demand via
+     * forceTraversalForAgent(). Unfreezing schedules a traversal to resume normal rendering.
+     * Must be called on the UI thread.
+     * @hide
+     */
+    public void setAgentFrozen(boolean frozen) {
+        if (frozen && !isAgentUi()) {
+            return; // never freeze a main (user) UI window
+        }
+        if (mAgentFrozen == frozen) {
+            return;
+        }
+        mAgentFrozen = frozen;
+        if (frozen) {
+            // Agent-UI-only GPU memory release. When an agent window freezes it
+            // will not render until unfrozen, so its GPU-resident resources
+            // (this window's HardwareLayers, prefetched layers, pinned images)
+            // are dead weight. clearContent() -> nDestroyHardwareResources is
+            // PER-CONTEXT (this window's RenderProxy only); it must NOT be
+            // confused with the static HardwareRenderer.trimMemory()/trimCaches()
+            // which are process-global and would harm a co-process user UI
+            // (C1 foreground+VD shared process). Re-assert the agent-UI guard
+            // so this can never run for the user's display-0 window.
+            if (isAgentUi() && mAttachInfo != null
+                    && mAttachInfo.mThreadedRenderer != null) {
+                try {
+                    mAttachInfo.mThreadedRenderer.clearContent();
+                } catch (Throwable t) {
+                    // best-effort; freezing must still succeed
+                }
+            }
+        } else {
+            scheduleTraversals();
+        }
+    }
+
+    /**
+     * Layer 1: whether decoupled (foreground-yielding) traversal is currently active
+     * for this window. Defaults ON for any agent UI (window property, follows derived
+     * windows); a manual override can force it on/off for experiments (e.g. B-GUI
+     * forces it OFF to use the original VSYNC-bound path).
+     * @hide
+     */
+    public boolean isAgentDecoupleActive() {
+        // The deferred Agent traversal is sync-only and cannot publish the first
+        // buffer. Let a newly-created Agent window complete one normal draw first,
+        // matching the bootstrap guard used by persistent GPU bypass below. Without
+        // this guard WMS never receives non-empty input geometry for a new window.
+        if (!mAgentHasDrawnOnce) {
+            return false;
+        }
+        switch (mAgentDecoupleOverride) {
+            case AGENT_DECOUPLE_ON:  return isAgentUi();
+            case AGENT_DECOUPLE_OFF: return false;
+            default: return sAgentDecoupleDefault && isAgentUi();
+        }
+    }
+
+    /**
+     * Layer 1 manual override. {@code enabled==true} forces decouple on (agent UI only),
+     * {@code false} forces it off (used by B-GUI to keep the VSYNC-bound traversal).
+     * To return to the default window-property behavior use {@link #setAgentDecoupleAuto()}.
+     * No-op-on-effect for a main (user) UI window, which is never decoupled.
+     * @hide
+     */
+    public void setAgentDecoupleEnabled(boolean enabled) {
+        sAgentDecoupleDefault = enabled;
+        mAgentDecoupleOverride = enabled ? AGENT_DECOUPLE_ON : AGENT_DECOUPLE_OFF;
+    }
+
+    /**
+     * Layer 1: clear the manual override and return to the default (auto = on for
+     * agent UIs).
+     * @hide
+     */
+    public void setAgentDecoupleAuto() {
+        sAgentDecoupleDefault = true;
+        mAgentDecoupleOverride = AGENT_DECOUPLE_AUTO;
+    }
+
+    /**
+     * Layer 3: enable/disable DL semantic-hash stability detection for on-demand
+     * settle. When enabled, settle passes record the DisplayList and the loop exits
+     * when the agent-consumable content fingerprint repeats (settles spinner/periodic
+     * pages); when disabled, framework dirty-flag stability is used.
+     * @hide
+     */
+    public void setAgentHashStabilityEnabled(boolean enabled) {
+        mAgentHashStabilityEnabled = enabled;
+    }
+
+    /**
+     * Whether persistent GPU bypass (no-draw) is currently active for this window.
+     * AUTO (default) == isAgentUi(): on for ANY agent-UI window, including
+     * sub-activities/dialogs the agent navigates to after task start (they are agent
+     * UIs by display), so no per-window re-engagement is needed. A manual override
+     * can force on/off for experiments. Mirrors isAgentDecoupleActive().
+     * @hide
+     */
+    public boolean isAgentPersistentNoDrawActive() {
+        // Never skip draws until the window has rendered one real frame to build its
+        // DisplayList; otherwise syncForAgent records an empty DL (blank perception).
+        // This lets a newly navigated agent window self-bootstrap: 1 real frame to
+        // build the DL, then all subsequent frames bypass GPU.
+        if (!mAgentHasDrawnOnce) {
+            return false;
+        }
+        switch (mAgentPersistentNoDrawOverride) {
+            case AGENT_NODRAW_ON:  return isAgentUi();
+            case AGENT_NODRAW_OFF: return false;
+            default:               // AUTO: follow process-wide default, agent UI only
+                return sAgentPersistentNoDrawDefault && isAgentUi();
+        }
+    }
+
+    /**
+     * Persistent GPU bypass (no-draw). When active, every performDraw() on this
+     * window -- including the app's own real-VSYNC-driven traversals while unfrozen
+     * and active -- records the DisplayList and syncs to the RenderThread but skips
+     * the GPU draw (zero GPU / zero SF buffer for this window). Realizes "unfreeze
+     * period has traversal but all GPU bypassed".
+     *
+     * This is a tri-state manual OVERRIDE on top of the AUTO default (= isAgentUi()):
+     * {@code enabled==true} forces on (agent UI only), {@code false} forces off. To
+     * return to AUTO use {@link #setAgentPersistentNoDrawAuto()}. Because AUTO already
+     * covers every agent-UI window, the common case needs NO call at all -- newly
+     * navigated agent windows bypass automatically.
+     *
+     * Gated to agent UIs only; no-op-on-effect for a main/user UI window (display-0
+     * never blanks). Independent of freeze.
+     * @hide
+     */
+    public void setAgentPersistentNoDraw(boolean enabled) {
+        // Flip the PROCESS-WIDE default so every agent window -- current and future
+        // (sub-activities the agent navigates to later) -- inherits this mode without
+        // per-window re-engagement. This is the fix for multi-window nav apps.
+        sAgentPersistentNoDrawDefault = enabled;
+        // Clear any per-window manual override so this window follows the new default.
+        final boolean wasActive = isAgentPersistentNoDrawActive();
+        mAgentPersistentNoDrawOverride = AGENT_NODRAW_AUTO;
+        final boolean nowActive = isAgentPersistentNoDrawActive();
+        if (nowActive == wasActive) {
+            return;
+        }
+        if (nowActive) {
+            // Release this window's GPU-resident resources now; dead weight while we
+            // never rasterize. PER-CONTEXT (this window's RenderProxy only), agent-UI
+            // guarded -- never the static process-global trim.
+            if (isAgentUi() && mAttachInfo != null
+                    && mAttachInfo.mThreadedRenderer != null) {
+                try {
+                    mAttachInfo.mThreadedRenderer.clearContent();
+                } catch (Throwable t) {
+                    // best-effort
+                }
+            }
+        } else {
+            // Re-enable real drawing: force a full redraw so the window repaints.
+            mFullRedrawNeeded = true;
+            invalidate();
+        }
+    }
+
+    /**
+     * Return persistent no-draw to the default AUTO (= follow process default).
+     * @hide
+     */
+    public void setAgentPersistentNoDrawAuto() {
+        mAgentPersistentNoDrawOverride = AGENT_NODRAW_AUTO;
+    }
+
+    /**
+     * Whether this window belongs to an agent UI (launched by an agent via the
+     * agent-display API), as opposed to a main UI (user-launched). Layer-1 callback
+     * rerouting, freeze, and on-demand observe all key off this. The classification
+     * follows the launch origin and its derived windows; see mIsAgentUiCache.
+     * @hide
+     */
+    public boolean isAgentUi() {
+        if (mIsAgentUiCache < 0) {
+            // Agent UIs are launched on agent (non-default) displays; the user's UI
+            // owns the default display. Navigation-spawned windows inherit the agent
+            // display and are thus classified as agent UI as well.
+            mIsAgentUiCache = (getDisplayId() != Display.DEFAULT_DISPLAY) ? 1 : 0;
+        }
+        return mIsAgentUiCache == 1;
+    }
+
+    /**
+     * Returns agent profiling stats as a compact JSON object:
+     * {"settled":bool,"phase1_traversals":N,"phase2_traversals":N}
+     * settled=true  → last forceTraversalForAgent exited via early-break (view tree stable)
+     * settled=false → ran out of vsyncFrames budget (perpetual animation or too few frames)
+     * phase1_traversals → cumulative measure+layout-only passes since last resetAgentStats()
+     * phase2_traversals → cumulative full-record passes since last resetAgentStats()
+     * @hide
+     */
+    public String getAgentStatsJson() {
+        return "{\"display\":" + getDisplayId()
+                + ",\"agent_ui\":" + isAgentUi()
+                + ",\"host_visibility\":" + getHostVisibility()
+                + ",\"has_view\":" + (mView != null)
+                + ",\"added\":" + mAdded
+                + ",\"in_traversal\":" + mIsInTraversal
+                + ",\"has_drawn_once\":" + mAgentHasDrawnOnce
+                + ",\"traversal_scheduled\":" + mTraversalScheduled
+                + ",\"agent_traversal_scheduled\":" + mAgentTraversalScheduled
+                + ",\"frozen\":" + mAgentFrozen
+                + ",\"persistent_nodraw\":" + isAgentPersistentNoDrawActive()
+                + ",\"persistent_nodraw_override\":" + mAgentPersistentNoDrawOverride
+                + ",\"decouple\":" + isAgentDecoupleActive()
+                + ",\"decouple_override\":" + mAgentDecoupleOverride
+                + ",\"deferred_traversals\":" + mAgentDeferredCount
+                + ",\"hash_stability\":" + mAgentHashStabilityEnabled
+                + ",\"last_hash\":\"" + Long.toHexString(mAgentLastSemanticHash) + "\""
+                + ",\"settled\":" + mAgentSettled
+                + ",\"phase1_traversals\":" + mAgentPhase1Count
+                + ",\"phase2_traversals\":" + mAgentPhase2Count
+                + ",\"yield_count\":" + mAgentYieldCount
+                + ",\"node_checkpoints\":" + mAgentNodeCheckpointCount
+                + ",\"checkpoint_frames\":" + mAgentNodeCheckpointFrameCount
+                + ",\"observe_active\":" + mAgentObserveActive
+                + ",\"observe_result\":\"" + mAgentObserveResult + "\""
+                + ",\"observe_duration_ms\":" + mAgentObserveDurationMs
+                + ",\"observe_timeout_ms\":" + mAgentObserveTimeoutMs
+                + ",\"observe_passes\":" + mAgentObservePass
+                + ",\"last_sync_valid\":" + mAgentLastSyncForAgentValid
+                + ",\"last_sync_result\":" + mAgentLastSyncForAgentResult
+                + ",\"dl_profile\":" + getAgentDlProfileJson() + "}";
+    }
+
+    private String getAgentDlProfileJson() {
+        final StringBuilder out = new StringBuilder(512 + mAgentDlProfileSampleCount * 96);
+        out.append("{\"enabled\":").append(mAgentDlProfileEnabled)
+                .append(",\"armed\":").append(mAgentDlProfileArmed)
+                .append(",\"action_active\":").append(mAgentDlProfileActionActive)
+                .append(",\"terminal_delivered\":")
+                .append(mAgentDlProfileTerminalDelivered)
+                .append(",\"action_generation\":")
+                .append(mAgentDlProfileActionGeneration)
+                .append(",\"record_generation\":")
+                .append(mAgentDlProfileRecordGeneration)
+                .append(",\"active_generation\":")
+                .append(mAgentDlProfileActiveGeneration)
+                .append(",\"last_sync_result\":")
+                .append(mAgentDlProfileLastSyncResult)
+                .append(",\"ready_at_us\":").append(mAgentDlProfileReadyAtUs)
+                .append(",\"quiet1_at_us\":").append(mAgentDlProfileQuiet1AtUs)
+                .append(",\"quiet2_at_us\":").append(mAgentDlProfileQuiet2AtUs)
+                .append(",\"record_count\":").append(mAgentDlProfileRecordCount)
+                .append(",\"record_total_ns\":")
+                .append(mAgentDlProfileRecordDurationTotalNanos)
+                .append(",\"sync_count\":").append(mAgentDlProfileSyncCount)
+                .append(",\"sync_total_ns\":").append(mAgentDlProfileSyncDurationTotalNanos)
+                .append(",\"semantic_count\":").append(mAgentDlProfileSemanticCount)
+                .append(",\"semantic_total_ns\":")
+                .append(mAgentDlProfileSemanticDurationTotalNanos)
+                .append(",\"bookkeeping_total_ns\":")
+                .append(mAgentDlProfileBookkeepingDurationTotalNanos)
+                .append(",\"sample_columns\":[\"time_us\",\"action_gen\",\"record_gen\","
+                        + "\"active_gen\",\"recorded_nodes\",\"node_sketch\",\"dirty_tick\","
+                        + "\"root_id\",\"readiness_mask\",\"quiet_slots\",\"semantic_hash\","
+                        + "\"record_ns\",\"sync_ns\",\"semantic_ns\",\"sync_result\"],"
+                        + "\"samples\":[");
+        if (mAgentDlProfileSamples != null) {
+            final int start = (mAgentDlProfileSampleWrite - mAgentDlProfileSampleCount
+                    + AGENT_DL_PROFILE_SAMPLE_CAPACITY) % AGENT_DL_PROFILE_SAMPLE_CAPACITY;
+            for (int i = 0; i < mAgentDlProfileSampleCount; i++) {
+                if (i != 0) out.append(',');
+                final int slot = (start + i) % AGENT_DL_PROFILE_SAMPLE_CAPACITY;
+                final int base = slot * AGENT_DL_PROFILE_SAMPLE_STRIDE;
+                out.append('[');
+                for (int j = 0; j < AGENT_DL_PROFILE_SAMPLE_STRIDE; j++) {
+                    if (j != 0) out.append(',');
+                    out.append(mAgentDlProfileSamples[base + j]);
+                }
+                out.append(']');
+            }
+        }
+        return out.append("]}").toString();
+    }
+
+    /**
+     * Reset per-window agent profiling counters. Called when agent passes 'reset'
+     * subparam to 'dumpsys gfxinfo ... displaylist fresh reset'.
+     * @hide
+     */
+    public void resetAgentStats() {
+        mAgentPhase1Count = 0;
+        mAgentPhase2Count = 0;
+        mAgentSettled = false;
+        mAgentYieldCount = 0;
+        mAgentDeferredCount = 0;
+        mAgentNodeCheckpointCount = 0;
+        mAgentNodeCheckpointFrameCount = 0;
+        mAgentObserveResult = "idle";
+        mAgentObserveDurationMs = 0;
+        mAgentObserveTimeoutMs = 0;
+        mAgentObservePass = 0;
+        mAgentLastSyncForAgentValid = false;
+        mAgentLastSyncForAgentResult = -1;
+        resetAgentDlProfileStats();
+    }
+
+    private void resetAgentDlProfileStats() {
+        mAgentDlProfileArmed = false;
+        mAgentDlProfileActionActive = false;
+        mAgentDlProfileTerminalDelivered = false;
+        mAgentDlProfileRecordPassActive = false;
+        mAgentDlProfilePendingSync = false;
+        mAgentDlProfileActionGeneration = 0;
+        mAgentDlProfileActionStartNanos = 0;
+        mAgentDlProfileTerminalRecordGeneration = 0;
+        mAgentDlProfileRecordGeneration = 0;
+        mAgentDlProfileActiveGeneration = 0;
+        mAgentDlProfileActiveRecordGeneration = 0;
+        mAgentDlProfileLastRecordDurationNanos = 0;
+        mAgentDlProfileLastSyncDurationNanos = 0;
+        mAgentDlProfileRecordDurationTotalNanos = 0;
+        mAgentDlProfileSyncDurationTotalNanos = 0;
+        mAgentDlProfileSemanticDurationTotalNanos = 0;
+        mAgentDlProfileBookkeepingDurationTotalNanos = 0;
+        mAgentDlProfileRecordCount = 0;
+        mAgentDlProfileSyncCount = 0;
+        mAgentDlProfileSemanticCount = 0;
+        mAgentDlProfilePassRecordedNodes = 0;
+        mAgentDlProfilePassNodeSketch = 0;
+        mAgentDlProfileActiveRecordedNodes = 0;
+        mAgentDlProfileActiveNodeSketch = 0;
+        mAgentDlProfileActiveDirtyTick = 0;
+        mAgentDlProfileActiveRootId = 0;
+        mAgentDlProfileActiveRootValid = false;
+        mAgentDlProfileLastSyncResult = 0;
+        mAgentDlProfileLastSemanticHash = 0;
+        mAgentDlProfileHasSemanticHash = false;
+        mAgentDlProfileLastSampleDirtyTick = mAgentDirtyTick;
+        mAgentDlProfileLastSampleRootId = 0;
+        mAgentDlProfileQuietSlots = 0;
+        mAgentDlProfileReadyAtUs = -1;
+        mAgentDlProfileQuiet1AtUs = -1;
+        mAgentDlProfileQuiet2AtUs = -1;
+        mAgentDlProfileSampleCount = 0;
+        mAgentDlProfileSampleWrite = 0;
+    }
+
     private void applyKeepScreenOnFlag(WindowManager.LayoutParams params) {
         // Update window's global keep screen on flag: if a view has requested
         // that the screen be kept on, then it is always set; otherwise, it is
@@ -5459,6 +6859,30 @@ public final class ViewRootImpl implements ViewParent,
 
     private boolean performDraw(@Nullable SurfaceSyncGroup surfaceSyncGroup) {
         mLastPerformDrawSkippedReason = null;
+        if (mAgentSkipRecord) {
+            // Phase 1 of dual-phase agent traversal: measure+layout done, skip record entirely.
+            return true;
+        }
+        if (mAgentNoDraw || isAgentPersistentNoDrawActive()) {
+            // Agent no-draw path: record the DisplayList and sync staging->active on the
+            // RenderThread, but skip the GPU draw. Works even when the display is STATE_OFF
+            // or the surface is unbound, so we deliberately bypass the screen_off guard below.
+            //
+            // Two ways to enter here:
+            //   mAgentNoDraw                    -- transient, set for the duration of one
+            //                                      on-demand forceTraversalForAgent() frame.
+            //   isAgentPersistentNoDrawActive() -- persistent GPU bypass: ANY traversal
+            //                                      (incl. the app's own real-VSYNC frames
+            //                                      while unfrozen) skips the GPU draw. AUTO
+            //                                      = isAgentUi(), so it applies to every
+            //                                      agent-UI window automatically, including
+            //                                      sub-activities navigated to after task
+            //                                      start. Never the user's display-0 window.
+            if (mView != null && mAttachInfo.mThreadedRenderer != null) {
+                mAttachInfo.mThreadedRenderer.syncForAgent(mView, mAttachInfo, this);
+            }
+            return true;
+        }
         if (mAttachInfo.mDisplayState == Display.STATE_OFF && !mReportNextDraw) {
             mLastPerformDrawSkippedReason = "screen_off";
             if (!mLastDrawScreenOff) {
@@ -5491,6 +6915,12 @@ public final class ViewRootImpl implements ViewParent,
             if (mAttachInfo.mThreadedRenderer != null && !usingAsyncReport) {
                 mAttachInfo.mThreadedRenderer.setFrameCallback(null);
             }
+            // This window has now completed at least one real draw, so its DisplayList
+            // is built. Persistent no-draw may safely skip subsequent draws for an
+            // agent UI (see isAgentPersistentNoDrawActive()).
+            if (!mAgentHasDrawnOnce && isAgentUi()) {
+                mAgentHasDrawnOnce = true;
+            }
         } finally {
             mIsDrawing = false;
             Trace.traceEnd(Trace.TRACE_TAG_VIEW);
@@ -10511,6 +11941,7 @@ public final class ViewRootImpl implements ViewParent,
     private void deliverInputEvent(QueuedInputEvent q) {
         Trace.asyncTraceBegin(Trace.TRACE_TAG_VIEW, "deliverInputEvent",
                 q.mEvent.getId());
+        agentDlProfileOnInputDispatched(q.mEvent);
 
         if (Trace.isTagEnabled(Trace.TRACE_TAG_VIEW)) {
             Trace.traceBegin(Trace.TRACE_TAG_VIEW, "deliverInputEvent src=0x"
@@ -10558,6 +11989,7 @@ public final class ViewRootImpl implements ViewParent,
     private void finishInputEvent(QueuedInputEvent q) {
         Trace.asyncTraceEnd(Trace.TRACE_TAG_VIEW, "deliverInputEvent",
                 q.mEvent.getId());
+        agentDlProfileOnInputFinished(q.mEvent);
 
         if (q.mReceiver != null) {
             boolean handled = (q.mFlags & QueuedInputEvent.FLAG_FINISHED_HANDLED) != 0;
diff --git a/core/java/android/view/WindowManagerGlobal.java b/core/java/android/view/WindowManagerGlobal.java
index 738b8f689f39..d382a7e9dbeb 100644
--- a/core/java/android/view/WindowManagerGlobal.java
+++ b/core/java/android/view/WindowManagerGlobal.java
@@ -32,6 +32,7 @@ import android.content.pm.ApplicationInfo;
 import android.content.res.Configuration;
 import android.content.res.TypedArray;
 import android.graphics.HardwareRenderer;
+import android.graphics.Rect;
 import android.os.Binder;
 import android.os.Build;
 import android.os.Handler;
@@ -649,6 +650,196 @@ public final class WindowManagerGlobal {
         FileOutputStream fout = new FileOutputStream(fd);
         PrintWriter pw = new FastPrintWriter(fout);
         try {
+            // 'dumpsys gfxinfo <pkg> displaylist fresh [nodraw] [vsync[N]] [reset]':
+            // fresh     -> force on-demand traversal (dual-phase: settle then record)
+            // nodraw    -> skip GPU draw (sync-only, zero GPU/SF)
+            // vsyncN    -> pump up to N synthetic VSYNC frames during Phase 1 settle
+            // freeze    -> freeze agent window (stop real-VSYNC-driven self-rendering)
+            // unfreeze  -> unfreeze agent window
+            // gpubypass -> persistent no-draw: EVERY traversal (incl. app's own VSYNC
+            //              frames while unfrozen) skips GPU draw. Independent of freeze.
+            // nogpubypass-> disable persistent no-draw (resume real drawing)
+            // reset     -> reset per-window agent profiling counters before fresh
+            // agentctl  -> apply controls and return without dumping any state
+            // agentstate-> return compact control state without renderer data
+            // traversalfreeze / traversalunfreeze -> toggle only traversal scheduling;
+            //              unlike freeze, never release/reconstruct GPU resources
+            // dlprofile / nodlprofile -> enable/disable profiling-only DL readiness observer
+            // dlprofilearm -> bind the next touch/key action to a profiling epoch
+            // readysettle -> dirty/readiness early return with readywaitN-ms fallback;
+            //                final record/sync is followed by traversal-only freeze
+            boolean fresh = false, noDraw = false, reset = false;
+            int vsyncFrames = 0;
+            int freeze = 0; // 0=none, 1=freeze, -1=unfreeze
+            int traversalFreeze = 0; // pure scheduling gate for CPU experiments
+            boolean agentControl = false;
+            boolean agentState = false;
+            boolean asyncSettle = false; // use idle-driven foreground-yielding settle
+            boolean readySettle = false;
+            long readyWaitMs = 2000;
+            int decouple = 0; // 0=none, 1=enable Layer-1, -1=disable
+            int hashStable = 0; // 0=none, 1=enable Layer-3 hash stability, -1=disable
+            int gpuBypass = 0; // 0=none, 1=enable persistent no-draw, -1=disable
+            int dlProfile = 0; // 0=none, 1=enable, -1=disable readiness profiling
+            boolean dlProfileArm = false;
+            for (String arg : args) {
+                if ("agentctl".equals(arg)) agentControl = true;
+                else if ("agentstate".equals(arg)) agentState = true;
+                else if ("fresh".equals(arg)) fresh = true;
+                else if ("nodraw".equals(arg)) noDraw = true;
+                else if ("reset".equals(arg)) reset = true;
+                else if ("freeze".equals(arg)) freeze = 1;
+                else if ("unfreeze".equals(arg)) freeze = -1;
+                else if ("traversalfreeze".equals(arg)) traversalFreeze = 1;
+                else if ("traversalunfreeze".equals(arg)) traversalFreeze = -1;
+                else if ("asyncsettle".equals(arg)) asyncSettle = true;
+                else if ("readysettle".equals(arg)) {
+                    readySettle = true;
+                    asyncSettle = true;
+                    fresh = true;
+                }
+                else if (arg.startsWith("readywait")) {
+                    String n = arg.substring(9);
+                    try { readyWaitMs = Long.parseLong(n); }
+                    catch (NumberFormatException e) { readyWaitMs = 2000; }
+                }
+                else if ("decouple".equals(arg)) decouple = 1;
+                else if ("undecouple".equals(arg)) decouple = -1;
+                else if ("autodecouple".equals(arg)) decouple = 2;
+                else if ("hashstable".equals(arg)) hashStable = 1;
+                else if ("nohashstable".equals(arg)) hashStable = -1;
+                else if ("gpubypass".equals(arg)) gpuBypass = 1;
+                else if ("nogpubypass".equals(arg)) gpuBypass = -1;
+                else if ("dlprofile".equals(arg)) dlProfile = 1;
+                else if ("nodlprofile".equals(arg)) dlProfile = -1;
+                else if ("dlprofilearm".equals(arg)) dlProfileArm = true;
+                else if (arg.startsWith("vsync")) {
+                    String n = arg.substring(5);
+                    try { vsyncFrames = n.isEmpty() ? 3 : Integer.parseInt(n); }
+                    catch (NumberFormatException e) { vsyncFrames = 3; }
+                }
+            }
+            if (fresh || freeze != 0 || traversalFreeze != 0 || reset || decouple != 0
+                    || hashStable != 0
+                    || gpuBypass != 0 || dlProfile != 0 || dlProfileArm) {
+                final ViewRootImpl[] roots;
+                synchronized (mLock) {
+                    roots = mRoots.toArray(new ViewRootImpl[0]);
+                }
+                final boolean nd = noDraw;
+                final int vf = vsyncFrames;
+                final int fz = freeze;
+                final int tfz = traversalFreeze;
+                final boolean doFresh = fresh;
+                final boolean doReset = reset;
+                final boolean doAsync = asyncSettle;
+                final boolean doReadySettle = readySettle;
+                // agentctl is a control-plane command. For ready-settle, let it arm
+                // the asynchronous observer and return immediately; callers poll
+                // agentstate and dump the completed DisplayList separately. Waiting
+                // here can exceed ActivityManager's gfxinfo pipe timeout on busy apps.
+                final boolean nonBlockingReadyControl = agentControl && doReadySettle;
+                final long readyTimeoutMs = Math.max(1, readyWaitMs);
+                final int dec = decouple;
+                final int hs = hashStable;
+                final int gb = gpuBypass;
+                final int dlp = dlProfile;
+                final boolean dlpArm = dlProfileArm;
+                for (final ViewRootImpl root : roots) {
+                    try {
+                        if (doFresh && doAsync) {
+                            // Idle-driven (foreground-yielding) settle. It must NOT run
+                            // inside runWithScissors: that would block the UI thread and
+                            // prevent the MessageQueue from ever going idle (where the
+                            // settle passes run). Post the start and wait bounded on a
+                            // latch fired from the observe's onDone callback.
+                            if (doReset || fz == 1 || tfz != 0 || dec != 0 || hs != 0
+                                    || gb != 0 || dlp != 0 || dlpArm) {
+                                root.mHandler.runWithScissors(() -> {
+                                    if (doReset) root.resetAgentStats();
+                                    if (dec == 1) root.setAgentDecoupleEnabled(true);
+                                    if (dec == -1) root.setAgentDecoupleEnabled(false);
+                                    if (dec == 2) root.setAgentDecoupleAuto();
+                                    if (hs == 1) root.setAgentHashStabilityEnabled(true);
+                                    if (hs == -1) root.setAgentHashStabilityEnabled(false);
+                                    if (gb == 1) root.setAgentPersistentNoDraw(true);
+                                    if (gb == -1) root.setAgentPersistentNoDraw(false);
+                                    if (dlp == 1) root.setAgentDlProfileEnabled(true);
+                                    if (dlp == -1) root.setAgentDlProfileEnabled(false);
+                                    if (dlpArm) root.armAgentDlProfile();
+                                    if (fz == 1) root.setAgentFrozen(true);
+                                    if (tfz == 1) root.setAgentTraversalFrozen(true);
+                                    if (tfz == -1) root.setAgentTraversalFrozen(false);
+                                }, 1000);
+                            }
+                            // A navigation can leave the previous Activity's root in
+                            // mRoots while its replacement becomes visible. Hidden
+                            // roots are not consumable observations and may no longer
+                            // have a valid surface to sync, so never start a fresh
+                            // readiness epoch on them. Persistent mode controls above
+                            // still apply to every root.
+                            if (root.getHostVisibility() != View.VISIBLE) {
+                                continue;
+                            }
+                            final java.util.concurrent.CountDownLatch done =
+                                    new java.util.concurrent.CountDownLatch(1);
+                            root.mHandler.post(() -> {
+                                if (doReadySettle) {
+                                    root.beginAgentReadyObserve(
+                                            nd, readyTimeoutMs, done::countDown);
+                                } else {
+                                    root.beginAgentObserve(nd, vf, done::countDown);
+                                }
+                            });
+                            if (!nonBlockingReadyControl) {
+                                try {
+                                    done.await(doReadySettle ? readyTimeoutMs + 1000 : 3000,
+                                            java.util.concurrent.TimeUnit.MILLISECONDS);
+                                } catch (InterruptedException ie) {
+                                    Thread.currentThread().interrupt();
+                                }
+                            }
+                            if (fz == -1) {
+                                root.mHandler.runWithScissors(
+                                        () -> root.setAgentFrozen(false), 1000);
+                            }
+                        } else {
+                            root.mHandler.runWithScissors(() -> {
+                                if (doReset) root.resetAgentStats();
+                                if (dec == 1) root.setAgentDecoupleEnabled(true);
+                                if (dec == -1) root.setAgentDecoupleEnabled(false);
+                                if (dec == 2) root.setAgentDecoupleAuto();
+                                if (hs == 1) root.setAgentHashStabilityEnabled(true);
+                                if (hs == -1) root.setAgentHashStabilityEnabled(false);
+                                if (gb == 1) root.setAgentPersistentNoDraw(true);
+                                if (gb == -1) root.setAgentPersistentNoDraw(false);
+                                if (dlp == 1) root.setAgentDlProfileEnabled(true);
+                                if (dlp == -1) root.setAgentDlProfileEnabled(false);
+                                if (dlpArm) root.armAgentDlProfile();
+                                if (fz == 1) root.setAgentFrozen(true);
+                                if (tfz == 1) root.setAgentTraversalFrozen(true);
+                                if (doFresh) root.forceTraversalForAgent(nd, vf);
+                                if (fz == -1) root.setAgentFrozen(false);
+                                if (tfz == -1) root.setAgentTraversalFrozen(false);
+                            }, 2000);
+                        }
+                    } catch (Exception e) {
+                        // Best-effort; fall through to dumping whatever is current.
+                    }
+                }
+            }
+            if (agentControl) {
+                return;
+            }
+            if (agentState) {
+                synchronized (mLock) {
+                    pw.println("Agent control state:");
+                    for (int i = 0; i < mRoots.size(); i++) {
+                        pw.println(mRoots.get(i).getAgentStatsJson());
+                    }
+                }
+                return;
+            }
             synchronized (mLock) {
                 final int count = mViews.size();
 
@@ -657,12 +848,22 @@ public final class WindowManagerGlobal {
                 for (int i = 0; i < count; i++) {
                     ViewRootImpl root = mRoots.get(i);
                     String name = getWindowName(root);
-                    pw.printf("\n\t%s (visibility=%d)", name, root.getHostVisibility());
+                    // Append agent profiling stats to the window header so the agent
+                    // can parse settled/traversal counts per window without extra RPCs.
+                    pw.printf("\n\t%s (visibility=%d)%s", name, root.getHostVisibility(),
+                            root.getAgentStatsJson());
 
                     ThreadedRenderer renderer =
                             root.getView().mAttachInfo.mThreadedRenderer;
                     if (renderer != null) {
-                        renderer.dumpGfxInfo(pw, fd, args);
+                        // HWUI coordinates are relative to the Window Surface.
+                        // Include its screen origin for dialogs and popup windows.
+                        final Rect surfaceInsets = root.mWindowAttributes.surfaceInsets;
+                        final int surfaceOriginX = root.mWinFrame.left - surfaceInsets.left;
+                        final int surfaceOriginY = root.mWinFrame.top - surfaceInsets.top;
+                        renderer.dumpGfxInfo(
+                                pw, fd, args, surfaceOriginX, surfaceOriginY,
+                                surfaceInsets.left, surfaceInsets.top);
                     }
                 }
 
diff --git a/graphics/java/android/graphics/HardwareRenderer.java b/graphics/java/android/graphics/HardwareRenderer.java
index 4f8044e82fdf..0b526a6e46bb 100644
--- a/graphics/java/android/graphics/HardwareRenderer.java
+++ b/graphics/java/android/graphics/HardwareRenderer.java
@@ -949,6 +949,63 @@ public class HardwareRenderer {
         nDumpProfileInfo(mNativeProxy, fd, dumpFlags);
     }
 
+    /**
+     * Dumps the current DisplayList ops as structured JSON to the given file descriptor.
+     * This outputs the raw rendering operations (drawRect, drawText, drawImage, etc.)
+     * with full parameters, not the View tree or accessibility information.
+     * @hide
+     */
+    public void dumpDisplayList(FileDescriptor fd) {
+        dumpDisplayList(fd, 0, 0);
+    }
+
+    /**
+     * Dumps the current DisplayList in global logical-screen coordinates.
+     *
+     * @param surfaceOriginX x coordinate of the rendering surface on screen
+     * @param surfaceOriginY y coordinate of the rendering surface on screen
+     * @hide
+     */
+    public void dumpDisplayList(FileDescriptor fd, int surfaceOriginX, int surfaceOriginY) {
+        dumpDisplayList(fd, surfaceOriginX, surfaceOriginY, 0, 0);
+    }
+
+    /**
+     * Dumps the current DisplayList in global logical-screen coordinates.
+     *
+     * @param surfaceOriginX x coordinate of the rendering surface on screen
+     * @param surfaceOriginY y coordinate of the rendering surface on screen
+     * @param surfaceInsetX left inset applied while recording the root DisplayList
+     * @param surfaceInsetY top inset applied while recording the root DisplayList
+     * @hide
+     */
+    public void dumpDisplayList(FileDescriptor fd, int surfaceOriginX, int surfaceOriginY,
+            int surfaceInsetX, int surfaceInsetY) {
+        nDumpDisplayList(mNativeProxy, fd, surfaceOriginX, surfaceOriginY,
+                surfaceInsetX, surfaceInsetY);
+    }
+
+    /**
+     * Layer-3 stability detection (C3): returns a 64-bit fingerprint of the
+     * agent-consumable semantic content (text glyphs + device-space layout bounds)
+     * of the last recorded frame. Stable under cosmetic churn; changes when text
+     * or layout changes. Runs synchronously on the RenderThread.
+     * @hide
+     */
+    public long computeSemanticHash() {
+        return nComputeSemanticHash(mNativeProxy);
+    }
+
+    /**
+     * Marks the next frame to sync the staging DisplayList to active but skip the
+     * GPU draw (zero GPU/SurfaceFlinger work). Used by the agent no-draw path so a
+     * forced traversal updates the DisplayList without rasterizing.
+     * @hide
+     */
+    public void setSyncOnlyNextFrame() {
+        nSetSyncOnlyNextFrame(mNativeProxy);
+    }
+
     /**
      * To avoid unnecessary overdrawing of the main content all additionally passed render nodes
      * will be prevented to overdraw this area. It will be synchronized with the draw call.
@@ -1671,6 +1728,11 @@ public class HardwareRenderer {
     private static native void nDumpProfileInfo(long nativeProxy, FileDescriptor fd,
             @DumpFlags int dumpFlags);
 
+    private static native void nDumpDisplayList(long nativeProxy, FileDescriptor fd,
+            int surfaceOriginX, int surfaceOriginY, int surfaceInsetX, int surfaceInsetY);
+    private static native long nComputeSemanticHash(long nativeProxy);
+    private static native void nSetSyncOnlyNextFrame(long nativeProxy);
+
     private static native void nDumpGlobalProfileInfo(FileDescriptor fd, @DumpFlags int dumpFlags);
 
     private static native void nAddRenderNode(long nativeProxy, long rootRenderNode,
diff --git a/libs/hwui/DisplayList.h b/libs/hwui/DisplayList.h
index 894454dd9772..e85866fb954b 100644
--- a/libs/hwui/DisplayList.h
+++ b/libs/hwui/DisplayList.h
@@ -119,6 +119,12 @@ public:
         }
     }
 
+    void exportOps(std::ostream& output, uint32_t level) const {
+        if (mImpl) {
+            mImpl->exportOps(output, level);
+        }
+    }
+
     [[nodiscard]] bool hasFunctor() const {
         return mImpl && mImpl->hasFunctor();
     }
@@ -183,6 +189,7 @@ private:
         size_t getUsedSize() const { return 0; }
         size_t getAllocatedSize() const { return 0; }
         void output(std::ostream& output, uint32_t level) const { }
+        void exportOps(std::ostream& output, uint32_t level) const { }
         bool hasFunctor() const { return false; }
         bool prepareListAndChildren(
                 TreeObserver& observer, TreeInfo& info, bool functorsNeedLayer,
@@ -301,6 +308,10 @@ public:
         apply([&](const auto& it) { it.output(output, level); });
     }
 
+    void exportOps(std::ostream& output, uint32_t level) const {
+        apply([&](const auto& it) { it.exportOps(output, level); });
+    }
+
     [[nodiscard]] bool hasFunctor() const {
         return apply([](const auto& it) -> auto { return it.hasFunctor(); });
     }
diff --git a/libs/hwui/RenderNode.cpp b/libs/hwui/RenderNode.cpp
index 8574051e2129..146b1475ad71 100644
--- a/libs/hwui/RenderNode.cpp
+++ b/libs/hwui/RenderNode.cpp
@@ -112,6 +112,10 @@ void RenderNode::output(std::ostream& output, uint32_t level) {
     output << std::endl;
 }
 
+void RenderNode::exportDisplayList(std::ostream& output, uint32_t level) const {
+    mDisplayList.exportOps(output, level);
+}
+
 void RenderNode::visit(std::function<void(const RenderNode&)> func) const {
     func(*this);
     if (mDisplayList) {
diff --git a/libs/hwui/RenderNode.h b/libs/hwui/RenderNode.h
index 7ea919b966b1..6bbc70da3821 100644
--- a/libs/hwui/RenderNode.h
+++ b/libs/hwui/RenderNode.h
@@ -105,6 +105,7 @@ public:
     void discardStagingDisplayList();
 
     void output();
+    void exportDisplayList(std::ostream& output, uint32_t level) const;
     int getUsageSize();
     int getAllocatedSize();
 
diff --git a/libs/hwui/canvas/CanvasOpBuffer.cpp b/libs/hwui/canvas/CanvasOpBuffer.cpp
index 336c5d8dab35..cd027a81967d 100644
--- a/libs/hwui/canvas/CanvasOpBuffer.cpp
+++ b/libs/hwui/canvas/CanvasOpBuffer.cpp
@@ -35,6 +35,10 @@ void CanvasOpBuffer::output(std::ostream& output, uint32_t level) const {
     LOG_ALWAYS_FATAL("TODO");
 }
 
+void CanvasOpBuffer::exportOps(std::ostream& output, uint32_t level) const {
+    LOG_ALWAYS_FATAL("TODO");
+}
+
 bool CanvasOpBuffer::prepareListAndChildren(
             TreeObserver& observer, TreeInfo& info, bool functorsNeedLayer,
             std::function<void(RenderNode*, TreeObserver&, TreeInfo&, bool)> childFn) {
diff --git a/libs/hwui/canvas/CanvasOpBuffer.h b/libs/hwui/canvas/CanvasOpBuffer.h
index 529546d5c49c..c307c81cee19 100644
--- a/libs/hwui/canvas/CanvasOpBuffer.h
+++ b/libs/hwui/canvas/CanvasOpBuffer.h
@@ -118,6 +118,7 @@ public:
     }
 
     void output(std::ostream& output, uint32_t level) const;
+    void exportOps(std::ostream& output, uint32_t level) const;
 
 private:
     struct Contains {
diff --git a/libs/hwui/jni/android_graphics_HardwareRenderer.cpp b/libs/hwui/jni/android_graphics_HardwareRenderer.cpp
index 9c83c59cbbdb..13a6760ebfab 100644
--- a/libs/hwui/jni/android_graphics_HardwareRenderer.cpp
+++ b/libs/hwui/jni/android_graphics_HardwareRenderer.cpp
@@ -413,6 +413,27 @@ static void android_view_ThreadedRenderer_dumpProfileInfo(JNIEnv* env, jobject c
     proxy->dumpProfileInfo(fd, dumpFlags);
 }
 
+static void android_view_ThreadedRenderer_dumpDisplayList(JNIEnv* env, jobject clazz,
+        jlong proxyPtr, jobject javaFileDescriptor, jint surfaceOriginX, jint surfaceOriginY,
+        jint surfaceInsetX, jint surfaceInsetY) {
+    RenderProxy* proxy = reinterpret_cast<RenderProxy*>(proxyPtr);
+    int fd = jniGetFDFromFileDescriptor(env, javaFileDescriptor);
+    proxy->dumpDisplayList(
+            fd, surfaceOriginX, surfaceOriginY, surfaceInsetX, surfaceInsetY);
+}
+
+static jlong android_view_ThreadedRenderer_computeSemanticHash(JNIEnv* env, jobject clazz,
+        jlong proxyPtr) {
+    RenderProxy* proxy = reinterpret_cast<RenderProxy*>(proxyPtr);
+    return (jlong)proxy->computeSemanticHash();
+}
+
+static void android_view_ThreadedRenderer_setSyncOnlyNextFrame(JNIEnv* env, jobject clazz,
+        jlong proxyPtr) {
+    RenderProxy* proxy = reinterpret_cast<RenderProxy*>(proxyPtr);
+    proxy->setSyncOnlyNextFrame();
+}
+
 static void android_view_ThreadedRenderer_dumpGlobalProfileInfo(JNIEnv* env, jobject clazz,
                                                                 jobject javaFileDescriptor,
                                                                 jint dumpFlags) {
@@ -1023,6 +1044,12 @@ static const JNINativeMethod gMethods[] = {
         {"nNotifyFramePending", "(J)V", (void*)android_view_ThreadedRenderer_notifyFramePending},
         {"nDumpProfileInfo", "(JLjava/io/FileDescriptor;I)V",
          (void*)android_view_ThreadedRenderer_dumpProfileInfo},
+        {"nDumpDisplayList", "(JLjava/io/FileDescriptor;IIII)V",
+         (void*)android_view_ThreadedRenderer_dumpDisplayList},
+        {"nComputeSemanticHash", "(J)J",
+         (void*)android_view_ThreadedRenderer_computeSemanticHash},
+        {"nSetSyncOnlyNextFrame", "(J)V",
+         (void*)android_view_ThreadedRenderer_setSyncOnlyNextFrame},
         {"nDumpGlobalProfileInfo", "(Ljava/io/FileDescriptor;I)V",
          (void*)android_view_ThreadedRenderer_dumpGlobalProfileInfo},
         {"setupShadersDiskCache", "(Ljava/lang/String;Ljava/lang/String;)V",
diff --git a/libs/hwui/pipeline/skia/ExportOpsCanvas.h b/libs/hwui/pipeline/skia/ExportOpsCanvas.h
new file mode 100644
index 000000000000..362c3d9b7c58
--- /dev/null
+++ b/libs/hwui/pipeline/skia/ExportOpsCanvas.h
@@ -0,0 +1,324 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <sstream>
+#include <iomanip>
+#include <vector>
+#include <string>
+#include "RenderNode.h"
+#include "SkiaDisplayList.h"
+
+#include <SkRRect.h>
+#include <SkTextBlob.h>
+#include <SkFont.h>
+
+namespace android {
+namespace uirenderer {
+namespace skiapipeline {
+
+/**
+ * ExportOpsCanvas replays a SkiaDisplayList and outputs structured JSON
+ * containing full op parameters (bounds, colors, text, etc.).
+ * Used to export the DisplayList for agent UI understanding.
+ */
+class ExportOpsCanvas : public SkCanvas {
+public:
+    ExportOpsCanvas(std::ostream& output, int level, const SkiaDisplayList& displayList)
+            : mOutput(output)
+            , mLevel(level)
+            , mDisplayList(displayList)
+            , mFirst(true) {}
+
+protected:
+    void onDrawRect(const SkRect& rect, const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawRect\","
+                << "\"bounds\":" << rectJson(rect) << ","
+                << "\"color\":\"" << colorHex(paint) << "\""
+                << paintStyle(paint) << "}";
+    }
+
+    void onDrawRRect(const SkRRect& rrect, const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawRRect\","
+                << "\"bounds\":" << rectJson(rrect.rect()) << ","
+                << "\"rx\":" << rrect.getSimpleRadii().x() << ","
+                << "\"ry\":" << rrect.getSimpleRadii().y() << ","
+                << "\"color\":\"" << colorHex(paint) << "\""
+                << paintStyle(paint) << "}";
+    }
+
+    void onDrawDRRect(const SkRRect& outer, const SkRRect& inner,
+                      const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawDRRect\","
+                << "\"outer\":" << rectJson(outer.rect()) << ","
+                << "\"inner\":" << rectJson(inner.rect()) << ","
+                << "\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawOval(const SkRect& rect, const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawOval\","
+                << "\"bounds\":" << rectJson(rect) << ","
+                << "\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawArc(const SkRect& rect, SkScalar startAngle, SkScalar sweepAngle,
+                   bool useCenter, const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawArc\","
+                << "\"bounds\":" << rectJson(rect) << ","
+                << "\"start\":" << startAngle << ",\"sweep\":" << sweepAngle << ","
+                << "\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawPath(const SkPath& path, const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawPath\","
+                << "\"bounds\":" << rectJson(path.getBounds()) << ","
+                << "\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawPaint(const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawPaint\","
+                << "\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawTextBlob(const SkTextBlob* blob, SkScalar x, SkScalar y,
+                        const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawText\","
+                << "\"x\":" << x << ",\"y\":" << y << ","
+                << "\"bounds\":" << rectJson(blob->bounds().makeOffset(x, y)) << ","
+                << "\"text\":\"" << escapeJson(extractText(blob)) << "\","
+                << "\"size\":" << (blob->bounds().height()) << ","
+                << "\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawImageRect2(const SkImage* image, const SkRect& src, const SkRect& dst,
+                          const SkSamplingOptions&, const SkPaint*,
+                          SrcRectConstraint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawImage\","
+                << "\"dst\":" << rectJson(dst);
+        if (image) {
+            mOutput << ",\"w\":" << image->width() << ",\"h\":" << image->height();
+        }
+        mOutput << "}";
+    }
+
+    void onDrawImageLattice2(const SkImage* image, const Lattice&, const SkRect& dst,
+                             SkFilterMode, const SkPaint*) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawImageLattice\","
+                << "\"dst\":" << rectJson(dst) << "}";
+    }
+
+    void onDrawPoints(SkCanvas::PointMode mode, size_t count, const SkPoint pts[],
+                      const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawPoints\","
+                << "\"count\":" << count << ","
+                << "\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawRegion(const SkRegion&, const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawRegion\","
+                << "\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawPicture(const SkPicture*, const SkMatrix*, const SkPaint*) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawPicture\"}";
+    }
+
+    void onClipRect(const SkRect& rect, SkClipOp op, ClipEdgeStyle) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"clipRect\","
+                << "\"bounds\":" << rectJson(rect) << "}";
+    }
+
+    void onClipRRect(const SkRRect& rrect, SkClipOp, ClipEdgeStyle) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"clipRRect\","
+                << "\"bounds\":" << rectJson(rrect.rect()) << "}";
+    }
+
+    void onClipPath(const SkPath& path, SkClipOp, ClipEdgeStyle) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"clipPath\","
+                << "\"bounds\":" << rectJson(path.getBounds()) << "}";
+    }
+
+    void onClipRegion(const SkRegion&, SkClipOp) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"clipRegion\"}";
+    }
+
+    void onResetClip() override {
+        sep();
+        mOutput << indent() << "{\"op\":\"resetClip\"}";
+    }
+
+    void onDrawDrawable(SkDrawable* drawable, const SkMatrix*) override {
+        auto* rnd = getRenderNodeDrawable(drawable);
+        if (rnd) {
+            sep();
+            auto* node = rnd->getRenderNode();
+            mOutput << indent() << "{\"op\":\"drawRenderNode\","
+                    << "\"name\":\"" << escapeJson(node->getName()) << "\"";
+
+            // Output RenderNode properties (bounds from RenderProperties)
+            const auto& props = node->properties();
+            mOutput << ",\"left\":" << props.getLeft()
+                    << ",\"top\":" << props.getTop()
+                    << ",\"right\":" << props.getRight()
+                    << ",\"bottom\":" << props.getBottom();
+            if (props.getAlpha() < 1.0f) {
+                mOutput << ",\"alpha\":" << props.getAlpha();
+            }
+            if (props.getTranslationX() != 0 || props.getTranslationY() != 0) {
+                mOutput << ",\"tx\":" << props.getTranslationX()
+                        << ",\"ty\":" << props.getTranslationY();
+            }
+
+            // Recurse into children
+            mOutput << ",\"children\":[";
+            node->exportDisplayList(mOutput, mLevel + 1);
+            mOutput << "]";
+            mOutput << "}";
+            return;
+        }
+
+        auto* functor = getFunctorDrawable(drawable);
+        if (functor) {
+            sep();
+            mOutput << indent() << "{\"op\":\"drawFunctor\"}";
+            return;
+        }
+
+        sep();
+        mOutput << indent() << "{\"op\":\"drawDrawable\"}";
+    }
+
+private:
+    void sep() {
+        if (!mFirst) mOutput << ",\n";
+        mFirst = false;
+    }
+
+    std::string indent() const {
+        return std::string((mLevel + 1) * 2, ' ');
+    }
+
+    static std::string rectJson(const SkRect& r) {
+        std::ostringstream s;
+        s << "[" << (int)r.fLeft << "," << (int)r.fTop << ","
+          << (int)r.fRight << "," << (int)r.fBottom << "]";
+        return s.str();
+    }
+
+    static std::string colorHex(const SkPaint& paint) {
+        SkColor c = paint.getColor();
+        std::ostringstream s;
+        s << "#" << std::hex << std::setfill('0') << std::setw(8) << c;
+        return s.str();
+    }
+
+    static std::string paintStyle(const SkPaint& paint) {
+        if (paint.getStyle() == SkPaint::kStroke_Style) {
+            std::ostringstream s;
+            s << ",\"style\":\"stroke\",\"strokeWidth\":" << paint.getStrokeWidth();
+            return s.str();
+        }
+        return "";
+    }
+
+    // NOTE: Text content is not extracted here because Skia's SkFont API
+    // (in this version) only supports unicharsToGlyphs (one-way). Glyph IDs
+    // alone don't reliably map back to unicode characters with OpenType features.
+    // Text extraction requires a higher-level Canvas hook (e.g., RecordingCanvas)
+    // before glyph conversion. For now, only bounds and styling are emitted.
+    static std::string extractText(const SkTextBlob* blob) {
+        return "";
+    }
+
+    // Inline UTF-8 encoder. Kept for future use when text extraction is wired
+    // through a higher-level hook that has access to the original text strings.
+    static void appendUtf8(std::string& out, SkUnichar uni) {
+        if (uni < 0 || uni > 0x10FFFF) return;
+        uint32_t u = static_cast<uint32_t>(uni);
+        if (u < 0x80) {
+            out += static_cast<char>(u);
+        } else if (u < 0x800) {
+            out += static_cast<char>(0xC0 | (u >> 6));
+            out += static_cast<char>(0x80 | (u & 0x3F));
+        } else if (u < 0x10000) {
+            out += static_cast<char>(0xE0 | (u >> 12));
+            out += static_cast<char>(0x80 | ((u >> 6) & 0x3F));
+            out += static_cast<char>(0x80 | (u & 0x3F));
+        } else {
+            out += static_cast<char>(0xF0 | (u >> 18));
+            out += static_cast<char>(0x80 | ((u >> 12) & 0x3F));
+            out += static_cast<char>(0x80 | ((u >> 6) & 0x3F));
+            out += static_cast<char>(0x80 | (u & 0x3F));
+        }
+    }
+
+    static std::string escapeJson(const std::string& s) {
+        std::string out;
+        out.reserve(s.size());
+        for (char c : s) {
+            switch (c) {
+                case '"': out += "\\\""; break;
+                case '\\': out += "\\\\"; break;
+                case '\n': out += "\\n"; break;
+                case '\r': out += "\\r"; break;
+                case '\t': out += "\\t"; break;
+                default: out += c;
+            }
+        }
+        return out;
+    }
+
+    const RenderNodeDrawable* getRenderNodeDrawable(SkDrawable* drawable) {
+        for (auto& child : mDisplayList.mChildNodes) {
+            if (drawable == &child) return &child;
+        }
+        return nullptr;
+    }
+
+    FunctorDrawable* getFunctorDrawable(SkDrawable* drawable) {
+        for (auto& child : mDisplayList.mChildFunctors) {
+            if (drawable == child) return child;
+        }
+        return nullptr;
+    }
+
+    std::ostream& mOutput;
+    int mLevel;
+    const SkiaDisplayList& mDisplayList;
+    bool mFirst;
+};
+
+}  // namespace skiapipeline
+}  // namespace uirenderer
+}  // namespace android
diff --git a/libs/hwui/pipeline/skia/FlatExportOpsCanvas.h b/libs/hwui/pipeline/skia/FlatExportOpsCanvas.h
new file mode 100644
index 000000000000..51abd5e4dc65
--- /dev/null
+++ b/libs/hwui/pipeline/skia/FlatExportOpsCanvas.h
@@ -0,0 +1,625 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+#include <iomanip>
+#include <mutex>
+#include <sstream>
+#include <string>
+#include <utility>
+#include <unordered_map>
+#include <vector>
+
+#include <SkCanvas.h>
+#include <SkData.h>
+#include <SkColor.h>
+#include <SkImage.h>
+#include <SkRRect.h>
+#include <SkTextBlob.h>
+#include <SkFont.h>
+#include <SkPath.h>
+#include <SkPixmap.h>
+#include <SkRegion.h>
+#include <SkPicture.h>
+#include <SkString.h>
+#include <SkTypeface.h>
+
+namespace android {
+namespace uirenderer {
+namespace skiapipeline {
+
+/**
+ * FlatExportOpsCanvas captures a fully-rendered frame as a hierarchical JSON
+ * stream. It's designed to be the target SkCanvas for RenderNodeDrawable.draw(),
+ * which traverses the entire RenderNode tree (including nested HardwareLayers)
+ * just like GPU rendering does. By default, SkCanvas's onDrawDrawable() inlines
+ * a drawable's content via drawable->draw(this), so nested RenderNodes are
+ * captured recursively.
+ *
+ * All bounds and points emitted are in global logical SCREEN space:
+ * every onDrawXxx callback maps its local-space inputs through the current
+ * local-to-device matrix maintained by SkCanvas (which is updated by the
+ * save()/concat() calls RenderNodeDrawable issues as it walks the tree), then
+ * offsets the replayed coordinates into global logical-screen space. Root
+ * DisplayLists are recorded with the Surface inset translated into the canvas;
+ * CanvasContext removes that replay inset from the Window Surface origin before
+ * constructing this canvas.
+ *
+ * For drawText, in addition to the device-space bounds/baseline, each run of
+ * the SkTextBlob is exported with its typeface family name and raw glyph IDs:
+ * an external Python script using fontTools can reverse-map glyph IDs to UTF-8
+ * by walking the font's cmap. The reverse cmap is intentionally NOT done in
+ * the framework — it is a pure data transformation that does not benefit from
+ * being inside HWUI.
+ *
+ * Output format:
+ *   {"op":"clipRect","bounds":[...]},
+ *   {"op":"drawText","x":..,"y":..,"bounds":[...],"size":..,"color":"..",
+ *     "runs":[{"font":"<family>","glyphs":[g1,g2,...]}, ...]},
+ *   {"op":"drawDrawable","ops":[                  <- nested RenderNode
+ *     {"op":"drawRect",...},
+ *     {"op":"drawDrawable","ops":[...]},
+ *     ...
+ *   ]},
+ *   ...
+ */
+class FlatExportOpsCanvas : public SkCanvas {
+public:
+    FlatExportOpsCanvas(std::ostream& output, int width, int height,
+                        int screenOffsetX = 0, int screenOffsetY = 0)
+            : SkCanvas(width, height)
+            , mOutput(output)
+            , mLevel(0)
+            , mFirstStack({true})
+            , mScreenOffsetX(screenOffsetX)
+            , mScreenOffsetY(screenOffsetY) {}
+
+protected:
+    // ── State ─────────────────────────────────────────────────────────
+    void onClipRect(const SkRect& rect, SkClipOp, ClipEdgeStyle) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"clipRect\",\"bounds\":" << rectJsonDevice(rect) << "}";
+    }
+
+    void onClipRRect(const SkRRect& rrect, SkClipOp, ClipEdgeStyle) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"clipRRect\",\"bounds\":" << rectJsonDevice(rrect.rect())
+                << ",\"rx\":" << rrect.getSimpleRadii().x()
+                << ",\"ry\":" << rrect.getSimpleRadii().y() << "}";
+    }
+
+    void onClipPath(const SkPath& path, SkClipOp, ClipEdgeStyle) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"clipPath\",\"bounds\":" << rectJsonDevice(path.getBounds())
+                << "}";
+    }
+
+    void onClipRegion(const SkRegion&, SkClipOp) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"clipRegion\"}";
+    }
+
+    void onResetClip() override {
+        sep();
+        mOutput << indent() << "{\"op\":\"resetClip\"}";
+    }
+
+    // ── Draws ─────────────────────────────────────────────────────────
+    void onDrawPaint(const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawPaint\",\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawRect(const SkRect& rect, const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawRect\",\"bounds\":" << rectJsonDevice(rect)
+                << ",\"color\":\"" << colorHex(paint) << "\""
+                << paintStyle(paint) << "}";
+    }
+
+    void onDrawRRect(const SkRRect& rrect, const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawRRect\",\"bounds\":" << rectJsonDevice(rrect.rect())
+                << ",\"rx\":" << rrect.getSimpleRadii().x()
+                << ",\"ry\":" << rrect.getSimpleRadii().y()
+                << ",\"color\":\"" << colorHex(paint) << "\""
+                << paintStyle(paint) << "}";
+    }
+
+    void onDrawDRRect(const SkRRect& outer, const SkRRect& inner,
+                      const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawDRRect\",\"outer\":" << rectJsonDevice(outer.rect())
+                << ",\"inner\":" << rectJsonDevice(inner.rect())
+                << ",\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawOval(const SkRect& rect, const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawOval\",\"bounds\":" << rectJsonDevice(rect)
+                << ",\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawArc(const SkRect& rect, SkScalar startAngle, SkScalar sweepAngle,
+                   bool, const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawArc\",\"bounds\":" << rectJsonDevice(rect)
+                << ",\"start\":" << startAngle << ",\"sweep\":" << sweepAngle
+                << ",\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawPath(const SkPath& path, const SkPaint& paint) override {
+        SkPath devicePath;
+        path.transform(currentMatrix(), &devicePath);
+        devicePath.offset(mScreenOffsetX, mScreenOffsetY);
+        sep();
+        mOutput << indent() << "{\"op\":\"drawPath\",\"bounds\":"
+                << rectJson(devicePath.getBounds())
+                << ",\"color\":\"" << colorHex(paint) << "\""
+                << paintStyle(paint);
+        writeNormalizedPath(devicePath);
+        mOutput << "}";
+    }
+
+    void onDrawTextBlob(const SkTextBlob* blob, SkScalar x, SkScalar y,
+                        const SkPaint& paint) override {
+        sep();
+        // Bounds and baseline in global logical-screen space.
+        SkRect localBounds = blob ? blob->bounds().makeOffset(x, y) : SkRect::MakeEmpty();
+        SkScalar bx = x, by = y;
+        pointToDevice(&bx, &by);
+        mOutput << indent() << "{\"op\":\"drawText\""
+                << ",\"x\":" << bx << ",\"y\":" << by
+                << ",\"bounds\":" << rectJsonDevice(localBounds)
+                << ",\"size\":" << localBounds.height()
+                << ",\"color\":\"" << colorHex(paint) << "\"";
+
+        // Emit raw glyph IDs per run for external Python reverse-cmap.
+        // Skia's SkTextBlob::Iter exposes typeface + glyph array per run; the
+        // run does not carry UTF-8 once shaped, hence the side-channel reverse
+        // map. Family name + glyph IDs is the minimal set required.
+        if (blob) {
+            mOutput << ",\"runs\":[";
+            bool firstRun = true;
+            SkTextBlob::Iter iter(*blob);
+            SkTextBlob::Iter::Run run;
+            while (iter.next(&run)) {
+                if (!firstRun) mOutput << ",";
+                firstRun = false;
+                SkString family;
+                if (run.fTypeface) {
+                    run.fTypeface->getFamilyName(&family);
+                }
+                mOutput << "{\"font\":\"";
+                writeEscaped(family.c_str());
+                mOutput << "\"";
+                if (run.fTypeface) {
+                    mOutput << ",\"fontFingerprint\":\"" << fontFingerprint(run.fTypeface) << "\""
+                            << ",\"fontWeight\":" << run.fTypeface->fontStyle().weight()
+                            << ",\"fontWidth\":" << run.fTypeface->fontStyle().width()
+                            << ",\"fontSlant\":" << (int)run.fTypeface->fontStyle().slant();
+                }
+                mOutput << ",\"glyphs\":[";
+                for (int i = 0; i < run.fGlyphCount; ++i) {
+                    if (i) mOutput << ",";
+                    mOutput << (unsigned int)run.fGlyphIndices[i];
+                }
+                mOutput << "]}";
+            }
+            mOutput << "]";
+        }
+        mOutput << "}";
+    }
+
+    void onDrawImageRect2(const SkImage* image, const SkRect& src, const SkRect& dst,
+                          const SkSamplingOptions&, const SkPaint*,
+                          SrcRectConstraint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawImage\",\"src\":" << rectJson(src)
+                << ",\"dst\":" << rectJsonDevice(dst);
+        if (image) {
+            mOutput << ",\"w\":" << image->width() << ",\"h\":" << image->height()
+                    << ",\"imageId\":" << image->uniqueID();
+            writeImageVisual(image, src);
+        } else {
+            mOutput << ",\"visualStatus\":\"no_image\"";
+        }
+        mOutput << "}";
+    }
+
+    void onDrawImageLattice2(const SkImage*, const Lattice&, const SkRect& dst,
+                             SkFilterMode, const SkPaint*) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawImageLattice\",\"dst\":" << rectJsonDevice(dst) << "}";
+    }
+
+    void onDrawPoints(SkCanvas::PointMode, size_t count, const SkPoint[],
+                      const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawPoints\",\"count\":" << count
+                << ",\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawRegion(const SkRegion&, const SkPaint& paint) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawRegion\",\"color\":\"" << colorHex(paint) << "\"}";
+    }
+
+    void onDrawPicture(const SkPicture*, const SkMatrix*, const SkPaint*) override {
+        sep();
+        mOutput << indent() << "{\"op\":\"drawPicture\"}";
+    }
+
+    /**
+     * Override onDrawDrawable to wrap the inlined content with a "drawDrawable"
+     * marker, preserving RenderNode hierarchy in the output. The default Skia
+     * behavior (drawable->draw(this)) inlines the drawable's content through
+     * our other onDrawXXX overrides, recursively handling nested RenderNodes.
+     *
+     * The drawable's own bounds are emitted in device space using the CURRENT
+     * matrix (i.e. the outer RenderNode's transform), captured BEFORE we
+     * concat the inner matrix and recurse.
+     */
+    void onDrawDrawable(SkDrawable* drawable, const SkMatrix* matrix) override {
+        if (!drawable) return;
+        sep();
+        SkRect b = drawable->getBounds();
+        mOutput << indent() << "{\"op\":\"drawDrawable\",\"bounds\":" << rectJsonDevice(b)
+                << ",\"ops\":[";
+        mLevel++;
+        mFirstStack.push_back(true);
+        if (matrix) {
+            this->save();
+            this->concat(*matrix);
+            drawable->draw(this);
+            this->restore();
+        } else {
+            drawable->draw(this);
+        }
+        mFirstStack.pop_back();
+        mLevel--;
+        mOutput << "]}";
+    }
+
+private:
+    // Identity of tables that determine glyph numbering, names and substitutions.
+    // FNV-1a is an identity hint, not a cryptographic integrity claim. Host assets
+    // retain SHA256 independently. Cache once per typeface, never once per run.
+    static std::string fontFingerprint(const SkTypeface* typeface) {
+        static std::mutex lock;
+        static std::unordered_map<SkTypefaceID, std::string> cache;
+        std::lock_guard<std::mutex> guard(lock);
+        const auto id = typeface->uniqueID();
+        auto found = cache.find(id);
+        if (found != cache.end()) return found->second;
+        uint64_t hash = UINT64_C(14695981039346656037);
+        auto byte = [&hash](uint8_t b) { hash ^= b; hash *= UINT64_C(1099511628211); };
+        constexpr SkFontTableTag tags[] = {0x636d6170, 0x6d617870, 0x706f7374, 0x47535542};
+        for (const auto tag : tags) {
+            auto data = typeface->copyTableData(tag);
+            const uint32_t size = data ? static_cast<uint32_t>(data->size()) : 0;
+            for (int shift = 24; shift >= 0; shift -= 8) byte((tag >> shift) & 0xff);
+            for (int shift = 24; shift >= 0; shift -= 8) byte((size >> shift) & 0xff);
+            if (data) {
+                const auto* bytes = static_cast<const uint8_t*>(data->data());
+                for (size_t i = 0; i < data->size(); ++i) byte(bytes[i]);
+            }
+        }
+        std::ostringstream result;
+        result << "fnv1a64:" << std::hex << std::setw(16) << std::setfill('0') << hash;
+        if (cache.size() >= 512) cache.clear();
+        return cache.emplace(id, result.str()).first->second;
+    }
+    static constexpr int kMaxImageSampleDimension = 64;
+    static constexpr size_t kMaxImageColorRuns = 1024;
+    static constexpr int kMaxPathVerbs = 256;
+
+    void sep() {
+        if (!mFirstStack.back()) {
+            mOutput << ",\n";
+        }
+        mFirstStack.back() = false;
+    }
+
+    std::string indent() const {
+        return std::string((mLevel + 1) * 2, ' ');
+    }
+
+    // ── Coordinate mapping helpers ────────────────────────────────────
+    //
+    // Every onDrawXxx callback runs with SkCanvas's local-to-device matrix
+    // updated by all preceding save()/concat() calls (notably the ones issued
+    // by RenderNodeDrawable while it walks the tree). We snapshot that matrix
+    // here and use it to map local geometry to Surface space, then add the
+    // Window Surface origin to produce global logical-screen coordinates.
+    //
+    // For pure translate+scale transforms (the common UI case), SkMatrix::mapRect
+    // is exact. For rotations/perspective, it returns the axis-aligned bounding
+    // box of the transformed quad — acceptable for agent layout reasoning.
+
+    SkMatrix currentMatrix() const {
+        return this->getLocalToDeviceAs3x3();
+    }
+
+    std::string rectJsonDevice(const SkRect& localRect) {
+        SkRect device;
+        currentMatrix().mapRect(&device, localRect);
+        device.offset(mScreenOffsetX, mScreenOffsetY);
+        return rectJson(device);
+    }
+
+    void pointToDevice(SkScalar* x, SkScalar* y) {
+        SkPoint p = {*x, *y};
+        currentMatrix().mapPoints(&p, &p, 1);
+        *x = p.fX + mScreenOffsetX;
+        *y = p.fY + mScreenOffsetY;
+    }
+
+    static std::string rectJson(const SkRect& r) {
+        std::ostringstream s;
+        s << "[" << (int)r.fLeft << "," << (int)r.fTop << ","
+          << (int)r.fRight << "," << (int)r.fBottom << "]";
+        return s.str();
+    }
+
+    static std::string colorHex(const SkPaint& paint) {
+        SkColor c = paint.getColor();
+        std::ostringstream s;
+        s << "#" << std::hex << std::setfill('0') << std::setw(8) << c;
+        return s.str();
+    }
+
+    static std::string paintStyle(const SkPaint& paint) {
+        if (paint.getStyle() == SkPaint::kStroke_Style) {
+            std::ostringstream s;
+            s << ",\"style\":\"stroke\",\"strokeWidth\":" << paint.getStrokeWidth();
+            return s.str();
+        }
+        return "";
+    }
+
+    static std::string colorHex(SkColor color) {
+        std::ostringstream s;
+        s << "#" << std::hex << std::setfill('0') << std::setw(8) << color;
+        return s.str();
+    }
+
+    /**
+     * Export a bounded, nearest-neighbor ARGB sample of the source image.
+     *
+     * This is an intermediate visual representation, not the final icon mask.
+     * Python may later crop, resize, threshold, or reject it using experiment
+     * settings without rebuilding libhwui. Run-length encoding keeps flat UI
+     * icons compact. Complex photographic images are rejected once their color
+     * run count exceeds the safety limit.
+     *
+     * Texture-backed/lazy images for which peekPixels() is unavailable are
+     * reported without forcing a synchronous GPU readback on RenderThread.
+     */
+    void writeImageVisual(const SkImage* image, const SkRect& requestedSrc) {
+        SkPixmap pixmap;
+        if (!image->peekPixels(&pixmap)) {
+            mOutput << ",\"visualStatus\":\"pixels_unavailable\"";
+            return;
+        }
+
+        SkRect src = requestedSrc;
+        const SkRect imageBounds =
+                SkRect::MakeWH(static_cast<SkScalar>(pixmap.width()),
+                               static_cast<SkScalar>(pixmap.height()));
+        if (!src.isFinite() || !src.intersect(imageBounds) ||
+            src.isEmpty() || src.width() < 1.0f || src.height() < 1.0f) {
+            mOutput << ",\"visualStatus\":\"invalid_src\"";
+            return;
+        }
+
+        const float scale = std::min(
+                1.0f,
+                static_cast<float>(kMaxImageSampleDimension) /
+                        std::max(src.width(), src.height()));
+        const int sampleWidth = std::max(1, static_cast<int>(std::ceil(src.width() * scale)));
+        const int sampleHeight = std::max(1, static_cast<int>(std::ceil(src.height() * scale)));
+
+        struct ColorRun {
+            int count;
+            SkColor color;
+        };
+        std::vector<ColorRun> runs;
+        runs.reserve(std::min<size_t>(
+                static_cast<size_t>(sampleWidth) * sampleHeight,
+                kMaxImageColorRuns));
+
+        for (int y = 0; y < sampleHeight; ++y) {
+            for (int x = 0; x < sampleWidth; ++x) {
+                const float sourceX =
+                        src.left() + (static_cast<float>(x) + 0.5f) *
+                                src.width() / sampleWidth;
+                const float sourceY =
+                        src.top() + (static_cast<float>(y) + 0.5f) *
+                                src.height() / sampleHeight;
+                const int pixelX = std::clamp(
+                        static_cast<int>(sourceX), 0, pixmap.width() - 1);
+                const int pixelY = std::clamp(
+                        static_cast<int>(sourceY), 0, pixmap.height() - 1);
+                const SkColor color = pixmap.getColor(pixelX, pixelY);
+
+                if (!runs.empty() && runs.back().color == color) {
+                    ++runs.back().count;
+                } else {
+                    runs.push_back({1, color});
+                    if (runs.size() > kMaxImageColorRuns) {
+                        mOutput << ",\"visualStatus\":\"too_complex\""
+                                << ",\"sampleWidth\":" << sampleWidth
+                                << ",\"sampleHeight\":" << sampleHeight;
+                        return;
+                    }
+                }
+            }
+        }
+
+        mOutput << ",\"visualStatus\":\"available\""
+                << ",\"sampleWidth\":" << sampleWidth
+                << ",\"sampleHeight\":" << sampleHeight
+                << ",\"argbRle\":[";
+        for (size_t i = 0; i < runs.size(); ++i) {
+            if (i) mOutput << ",";
+            mOutput << "[" << runs[i].count << ",\"" << colorHex(runs[i].color) << "\"]";
+        }
+        mOutput << "]";
+    }
+
+    /**
+     * Export scale- and translation-independent path geometry.
+     *
+     * Points are normalized into the path's local bounds. Python can rasterize
+     * the data at any desired mask size after libhwui has been compiled.
+     */
+    void writeNormalizedPath(const SkPath& path) {
+        const SkRect bounds = path.getBounds();
+        if (!bounds.isFinite() || bounds.isEmpty() ||
+            bounds.width() <= 0.0f || bounds.height() <= 0.0f) {
+            mOutput << ",\"pathVisualStatus\":\"invalid_bounds\"";
+            return;
+        }
+
+        struct PathCommand {
+            const char* verb;
+            std::vector<SkPoint> points;
+            float conicWeight = 0.0f;
+            bool hasConicWeight = false;
+        };
+
+        std::vector<PathCommand> commands;
+        commands.reserve(32);
+        SkPath::RawIter iter(path);
+        SkPoint points[4];
+        bool tooComplex = false;
+
+        while (true) {
+            const SkPath::Verb verb = iter.next(points);
+            if (verb == SkPath::kDone_Verb) break;
+            if (commands.size() >= static_cast<size_t>(kMaxPathVerbs)) {
+                tooComplex = true;
+                break;
+            }
+
+            PathCommand command;
+            int pointCount = 0;
+            switch (verb) {
+                case SkPath::kMove_Verb:
+                    command.verb = "M";
+                    pointCount = 1;
+                    break;
+                case SkPath::kLine_Verb:
+                    command.verb = "L";
+                    pointCount = 2;
+                    break;
+                case SkPath::kQuad_Verb:
+                    command.verb = "Q";
+                    pointCount = 3;
+                    break;
+                case SkPath::kConic_Verb:
+                    command.verb = "O";
+                    pointCount = 3;
+                    command.conicWeight = iter.conicWeight();
+                    command.hasConicWeight = true;
+                    break;
+                case SkPath::kCubic_Verb:
+                    command.verb = "C";
+                    pointCount = 4;
+                    break;
+                case SkPath::kClose_Verb:
+                    command.verb = "Z";
+                    break;
+                case SkPath::kDone_Verb:
+                    break;
+            }
+
+            command.points.reserve(pointCount);
+            for (int i = 0; i < pointCount; ++i) {
+                command.points.push_back(SkPoint::Make(
+                        (points[i].x() - bounds.left()) / bounds.width(),
+                        (points[i].y() - bounds.top()) / bounds.height()));
+            }
+            commands.push_back(std::move(command));
+        }
+
+        if (tooComplex) {
+            mOutput << ",\"pathVisualStatus\":\"too_complex\""
+                    << ",\"pathVerbLimit\":" << kMaxPathVerbs;
+            return;
+        }
+
+        mOutput << ",\"pathVisualStatus\":\"available\""
+                << ",\"pathFillType\":" << static_cast<int>(path.getFillType())
+                << ",\"pathCommands\":[";
+        for (size_t i = 0; i < commands.size(); ++i) {
+            if (i) mOutput << ",";
+            const PathCommand& command = commands[i];
+            mOutput << "{\"verb\":\"" << command.verb << "\",\"points\":[";
+            for (size_t j = 0; j < command.points.size(); ++j) {
+                if (j) mOutput << ",";
+                mOutput << "[" << command.points[j].x() << ","
+                        << command.points[j].y() << "]";
+            }
+            mOutput << "]";
+            if (command.hasConicWeight) {
+                mOutput << ",\"weight\":" << command.conicWeight;
+            }
+            mOutput << "}";
+        }
+        mOutput << "]";
+    }
+
+    // JSON-escape and write a C-string to mOutput. Font family names from
+    // SkTypeface are usually plain ASCII (e.g. "Roboto", "sans-serif",
+    // "NotoSerifCJK-Regular"), but guard against quotes/backslashes anyway.
+    void writeEscaped(const char* s) {
+        if (!s) return;
+        for (; *s; ++s) {
+            char c = *s;
+            switch (c) {
+                case '"':  mOutput << "\\\""; break;
+                case '\\': mOutput << "\\\\"; break;
+                case '\n': mOutput << "\\n";  break;
+                case '\r': mOutput << "\\r";  break;
+                case '\t': mOutput << "\\t";  break;
+                default:
+                    if ((unsigned char)c < 0x20) {
+                        char buf[8];
+                        std::snprintf(buf, sizeof(buf), "\\u%04x", (unsigned int)(unsigned char)c);
+                        mOutput << buf;
+                    } else {
+                        mOutput << c;
+                    }
+            }
+        }
+    }
+
+    std::ostream& mOutput;
+    int mLevel;
+    std::vector<bool> mFirstStack;  // tracks "first item in current level"
+    int mScreenOffsetX;
+    int mScreenOffsetY;
+};
+
+}  // namespace skiapipeline
+}  // namespace uirenderer
+}  // namespace android
diff --git a/libs/hwui/pipeline/skia/SemanticHashCanvas.h b/libs/hwui/pipeline/skia/SemanticHashCanvas.h
new file mode 100644
index 000000000000..f3e0b897ed37
--- /dev/null
+++ b/libs/hwui/pipeline/skia/SemanticHashCanvas.h
@@ -0,0 +1,146 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <cstdint>
+
+#include <SkCanvas.h>
+#include <SkTextBlob.h>
+#include <SkRRect.h>
+
+namespace android {
+namespace uirenderer {
+namespace skiapipeline {
+
+/**
+ * SemanticHashCanvas computes a cheap 64-bit fingerprint of the
+ * agent-consumable semantic content of a frame, for Layer-3 UI stability
+ * detection (C3). It walks the RenderNode tree exactly like
+ * FlatExportOpsCanvas, but instead of emitting JSON it folds only the fields
+ * an agent's decision depends on into an FNV-1a hash:
+ *
+ *   - drawText: each run's glyph IDs (the text content) + the device-space
+ *     bounds (where the text sits, tap-ready) + integer baseline.
+ *   - interactive/structural geometry: device-space bounds of rect/rrect ops
+ *     (button/row backgrounds) folded at low weight so layout changes register.
+ *
+ * Deliberately EXCLUDED (so the hash is stable under cosmetic churn):
+ *   - colors, gradients, shaders, alpha
+ *   - image pixel content (only nothing — images excluded entirely)
+ *   - sub-pixel jitter (bounds are quantized to integer device pixels)
+ *   - paint style / stroke width
+ *
+ * Rationale: two consecutive on-demand passes with the same text + layout
+ * produce the same hash even while a spinner animates or a gradient pulses
+ * (those don't change glyphs or integer bounds), so the detector reports
+ * "agent-stable". When real content arrives (new text / moved rows), the hash
+ * changes and the detector keeps settling. Cost is O(ops) with no allocation
+ * and no string building — strictly cheaper than the JSON export path.
+ */
+class SemanticHashCanvas : public SkCanvas {
+public:
+    SemanticHashCanvas(int width, int height)
+            : SkCanvas(width, height), mHash(kFnvOffset) {}
+
+    uint64_t hash() const { return mHash; }
+
+protected:
+    void onDrawTextBlob(const SkTextBlob* blob, SkScalar x, SkScalar y,
+                        const SkPaint&) override {
+        if (!blob) return;
+        // Device-space baseline + bounds (quantized).
+        SkScalar bx = x, by = y;
+        pointToDevice(&bx, &by);
+        foldInt((int32_t)bx);
+        foldInt((int32_t)by);
+        foldDeviceRect(blob->bounds().makeOffset(x, y));
+        // Glyph IDs per run = the text content.
+        SkTextBlob::Iter iter(*blob);
+        SkTextBlob::Iter::Run run;
+        while (iter.next(&run)) {
+            for (int i = 0; i < run.fGlyphCount; ++i) {
+                foldInt((int32_t)(uint16_t)run.fGlyphIndices[i]);
+            }
+        }
+    }
+
+    // Structural geometry: fold device bounds so row/button layout changes are
+    // detected, but at coarse granularity (integer device px) to ignore jitter.
+    void onDrawRect(const SkRect& rect, const SkPaint&) override {
+        foldTag(0x52); // 'R'
+        foldDeviceRect(rect);
+    }
+    void onDrawRRect(const SkRRect& rrect, const SkPaint&) override {
+        foldTag(0x72); // 'r'
+        foldDeviceRect(rrect.rect());
+    }
+
+    // Recurse into nested RenderNodes (HardwareLayers / child nodes), matching
+    // FlatExportOpsCanvas so the hash covers the whole tree.
+    void onDrawDrawable(SkDrawable* drawable, const SkMatrix* matrix) override {
+        if (!drawable) return;
+        if (matrix) {
+            this->save();
+            this->concat(*matrix);
+            drawable->draw(this);
+            this->restore();
+        } else {
+            drawable->draw(this);
+        }
+    }
+
+    // Everything else (paint, image, path, points, color ops) is intentionally
+    // ignored — not part of the agent-stable signal.
+
+private:
+    static constexpr uint64_t kFnvOffset = 1469598103934665603ULL;
+    static constexpr uint64_t kFnvPrime = 1099511628211ULL;
+
+    void foldByte(uint8_t b) {
+        mHash ^= b;
+        mHash *= kFnvPrime;
+    }
+    void foldInt(int32_t v) {
+        foldByte((uint8_t)(v & 0xFF));
+        foldByte((uint8_t)((v >> 8) & 0xFF));
+        foldByte((uint8_t)((v >> 16) & 0xFF));
+        foldByte((uint8_t)((v >> 24) & 0xFF));
+    }
+    void foldTag(uint8_t t) { foldByte(t); }
+
+    void foldDeviceRect(const SkRect& localRect) {
+        SkRect d;
+        this->getLocalToDeviceAs3x3().mapRect(&d, localRect);
+        foldInt((int32_t)d.fLeft);
+        foldInt((int32_t)d.fTop);
+        foldInt((int32_t)d.fRight);
+        foldInt((int32_t)d.fBottom);
+    }
+
+    void pointToDevice(SkScalar* x, SkScalar* y) {
+        SkPoint p = {*x, *y};
+        this->getLocalToDeviceAs3x3().mapPoints(&p, &p, 1);
+        *x = p.fX;
+        *y = p.fY;
+    }
+
+    uint64_t mHash;
+};
+
+}  // namespace skiapipeline
+}  // namespace uirenderer
+}  // namespace android
diff --git a/libs/hwui/pipeline/skia/SkiaDisplayList.cpp b/libs/hwui/pipeline/skia/SkiaDisplayList.cpp
index 36dc933aa7b0..2106e49ca4c3 100644
--- a/libs/hwui/pipeline/skia/SkiaDisplayList.cpp
+++ b/libs/hwui/pipeline/skia/SkiaDisplayList.cpp
@@ -22,6 +22,7 @@
 // clang-format off
 #include "FunctorDrawable.h" // Must be included before DumpOpsCanvas.h
 #include "DumpOpsCanvas.h"
+#include "ExportOpsCanvas.h"
 // clang-format on
 #include "SkiaPipeline.h"
 #include "TreeInfo.h"
@@ -192,6 +193,11 @@ void SkiaDisplayList::output(std::ostream& output, uint32_t level) const {
     mDisplayList.draw(&canvas);
 }
 
+void SkiaDisplayList::exportOps(std::ostream& output, uint32_t level) const {
+    ExportOpsCanvas canvas(output, level, *this);
+    mDisplayList.draw(&canvas);
+}
+
 }  // namespace skiapipeline
 }  // namespace uirenderer
 }  // namespace android
diff --git a/libs/hwui/pipeline/skia/SkiaDisplayList.h b/libs/hwui/pipeline/skia/SkiaDisplayList.h
index 508a856e9050..654639b19da5 100644
--- a/libs/hwui/pipeline/skia/SkiaDisplayList.h
+++ b/libs/hwui/pipeline/skia/SkiaDisplayList.h
@@ -165,6 +165,7 @@ public:
     void draw(SkCanvas* canvas) { mDisplayList.draw(canvas); }
 
     void output(std::ostream& output, uint32_t level) const;
+    void exportOps(std::ostream& output, uint32_t level) const;
 
     LinearAllocator allocator;
 
diff --git a/libs/hwui/renderthread/CanvasContext.cpp b/libs/hwui/renderthread/CanvasContext.cpp
index 57ceb193b8ff..454e6391733f 100644
--- a/libs/hwui/renderthread/CanvasContext.cpp
+++ b/libs/hwui/renderthread/CanvasContext.cpp
@@ -17,6 +17,7 @@
 #include "CanvasContext.h"
 
 #include <apex/window.h>
+#include <cstdio>
 #include <fcntl.h>
 
 #ifdef __ANDROID__
@@ -47,6 +48,9 @@
 #include "pipeline/skia/SkiaGpuPipeline.h"
 #include "pipeline/skia/SkiaOpenGLPipeline.h"
 #include "pipeline/skia/SkiaVulkanPipeline.h"
+#include "pipeline/skia/RenderNodeDrawable.h"
+#include "pipeline/skia/FlatExportOpsCanvas.h"
+#include "pipeline/skia/SemanticHashCanvas.h"
 #include "thread/CommonPool.h"
 #include "utils/GLUtils.h"
 #include "utils/TimeUtils.h"
@@ -66,13 +70,16 @@ namespace renderthread {
 namespace {
 class ScopedActiveContext {
 public:
-    ScopedActiveContext(CanvasContext* context) { sActiveContext = context; }
+    ScopedActiveContext(CanvasContext* context) : mPreviousContext(sActiveContext) {
+        sActiveContext = context;
+    }
 
-    ~ScopedActiveContext() { sActiveContext = nullptr; }
+    ~ScopedActiveContext() { sActiveContext = mPreviousContext; }
 
     static CanvasContext* getActiveContext() { return sActiveContext; }
 
 private:
+    CanvasContext* mPreviousContext;
     static CanvasContext* sActiveContext;
 };
 
@@ -1077,6 +1084,82 @@ void CanvasContext::dumpFrames(int fd) {
     mJankTracker.dumpFrames(fd);
 }
 
+void CanvasContext::dumpDisplayList(int fd, int surfaceOriginX, int surfaceOriginY,
+                                    int surfaceInsetX, int surfaceInsetY) {
+    // Replay ops (e.g. non-antialiased DrawPoints) consult the active context
+    // for pixel snapping, even when the target canvas does not rasterize.
+    ScopedActiveContext activeContext(this);
+    // Use the same render path as GPU rendering (SkiaPipeline::renderFrameImpl)
+    // to ensure we capture every RenderNode in the tree, including nested
+    // HardwareLayers and child RenderNodes that don't appear in mRootNode's
+    // own DisplayList.
+    //
+    // RenderNodeDrawable.draw() recursively traverses the entire subtree by
+    // replaying each node's DisplayList ops onto the canvas. The default
+    // SkCanvas::onDrawDrawable() inlines each drawable into the current
+    // canvas via drawable->draw(this), giving us full visibility into the
+    // tree even when complex apps use HardwareLayers.
+    std::ostringstream oss;
+    oss << "{\"frame\":\"flat_render\",\"width\":" << mLastFrameWidth
+        << ",\"height\":" << mLastFrameHeight
+        << ",\"coordinateSpace\":\"screen\""
+        << ",\"surfaceOrigin\":[" << surfaceOriginX << "," << surfaceOriginY << "]"
+        << ",\"surfaceInsets\":[" << surfaceInsetX << "," << surfaceInsetY << "]"
+        << ",\"surfaceBoundsOnScreen\":[" << surfaceOriginX << "," << surfaceOriginY
+        << "," << surfaceOriginX + mLastFrameWidth
+        << "," << surfaceOriginY + mLastFrameHeight << "]"
+        << ",\"nodes\":[";
+
+    int width = std::max(mLastFrameWidth, 1);
+    int height = std::max(mLastFrameHeight, 1);
+
+    bool firstNode = true;
+    for (const sp<RenderNode>& node : mRenderNodes) {
+        if (!firstNode) oss << ",";
+        firstNode = false;
+        oss << "{\"name\":\"" << node->getName() << "\",\"ops\":[";
+        if (!node->nothingToDraw()) {
+            // Create a FlatExportOpsCanvas with frame dimensions. SkCanvas with
+            // explicit dimensions creates a "no-draw" canvas where draw ops
+            // route through onDraw* virtuals (our overrides) without any GPU
+            // rasterization.
+            skiapipeline::FlatExportOpsCanvas canvas(
+                    oss, width, height,
+                    surfaceOriginX - surfaceInsetX,
+                    surfaceOriginY - surfaceInsetY);
+            // Wrap the RenderNode in a RenderNodeDrawable and force-draw onto
+            // our canvas. forceDraw() is what SkiaPipeline uses internally;
+            // it handles RenderLayer composition and recursively renders
+            // child RenderNodes by calling canvas->drawDrawable(child), which
+            // our FlatExportOpsCanvas captures as nested drawDrawable ops.
+            skiapipeline::RenderNodeDrawable drawable(node.get(), &canvas, false);
+            drawable.forceDraw(&canvas);
+        }
+        oss << "]}";
+    }
+    oss << "]}\n";
+    std::string result = oss.str();
+    dprintf(fd, "%s", result.c_str());
+}
+
+uint64_t CanvasContext::computeSemanticHash() {
+    ScopedActiveContext activeContext(this);
+    // Walk the same RenderNode tree as dumpDisplayList(), but fold only the
+    // agent-stable semantic content (text glyphs + device-space layout bounds)
+    // into a 64-bit fingerprint. No JSON, no allocation per op.
+    int width = std::max(mLastFrameWidth, 1);
+    int height = std::max(mLastFrameHeight, 1);
+    skiapipeline::SemanticHashCanvas canvas(width, height);
+    for (const sp<RenderNode>& node : mRenderNodes) {
+        if (node->nothingToDraw()) {
+            continue;
+        }
+        skiapipeline::RenderNodeDrawable drawable(node.get(), &canvas, false);
+        drawable.forceDraw(&canvas);
+    }
+    return canvas.hash();
+}
+
 void CanvasContext::resetFrameStats() {
     mJankTracker.reset();
 }
diff --git a/libs/hwui/renderthread/CanvasContext.h b/libs/hwui/renderthread/CanvasContext.h
index 5fe9fe4ceffe..6ccadd2abf6c 100644
--- a/libs/hwui/renderthread/CanvasContext.h
+++ b/libs/hwui/renderthread/CanvasContext.h
@@ -173,6 +173,14 @@ public:
     std::mutex& profilerLock() { return mFrameInfoMutex; }
 
     void dumpFrames(int fd);
+    void dumpDisplayList(int fd, int surfaceOriginX, int surfaceOriginY,
+                         int surfaceInsetX, int surfaceInsetY);
+
+    // Layer-3 stability detection (C3): compute a cheap 64-bit fingerprint of the
+    // agent-consumable semantic content (text glyphs + device-space layout bounds)
+    // of the current frame. Stable under cosmetic churn (color/spinner/jitter);
+    // changes when text or layout changes. Runs on the RenderThread.
+    uint64_t computeSemanticHash();
     void resetFrameStats();
 
     void setName(const std::string&& name);
diff --git a/libs/hwui/renderthread/DrawFrameTask.cpp b/libs/hwui/renderthread/DrawFrameTask.cpp
index 826d00e1f32f..0584674c8a67 100644
--- a/libs/hwui/renderthread/DrawFrameTask.cpp
+++ b/libs/hwui/renderthread/DrawFrameTask.cpp
@@ -107,6 +107,13 @@ void DrawFrameTask::run() {
         canDrawThisFrame = !info.out.skippedFrameReason.has_value();
         solelyTextureViewUpdates = info.out.solelyTextureViewUpdates;
 
+        // Agent no-draw mode: the staging DisplayList has been synced to active
+        // by syncFrameState above; skip the GPU draw entirely (zero GPU/SF work).
+        if (mSyncOnlyFrame) {
+            canDrawThisFrame = false;
+            mSyncOnlyFrame = false;
+        }
+
         if (mFrameCommitCallback) {
             mContext->addFrameCommitListener(std::move(mFrameCommitCallback));
             mFrameCommitCallback = nullptr;
diff --git a/libs/hwui/renderthread/DrawFrameTask.h b/libs/hwui/renderthread/DrawFrameTask.h
index 4130d4abe09e..adbc8f584c95 100644
--- a/libs/hwui/renderthread/DrawFrameTask.h
+++ b/libs/hwui/renderthread/DrawFrameTask.h
@@ -96,6 +96,9 @@ public:
 
     void forceDrawNextFrame() { mForceDrawFrame = true; }
 
+    // Agent no-draw mode: sync the staging DisplayList to active but skip GPU draw.
+    void setSyncOnlyNextFrame() { mSyncOnlyFrame = true; }
+
     void setHardwareBufferRenderParams(const HardwareBufferRenderParams& params) {
         mHardwareBufferParams = params;
     }
@@ -132,6 +135,7 @@ private:
     std::function<void()> mFrameCompleteCallback;
 
     bool mForceDrawFrame = false;
+    bool mSyncOnlyFrame = false;
 };
 
 } /* namespace renderthread */
diff --git a/libs/hwui/renderthread/RenderProxy.cpp b/libs/hwui/renderthread/RenderProxy.cpp
index c9ce32c17eef..d5295e4d29e1 100644
--- a/libs/hwui/renderthread/RenderProxy.cpp
+++ b/libs/hwui/renderthread/RenderProxy.cpp
@@ -182,6 +182,10 @@ int RenderProxy::syncAndDrawFrame() {
     return mDrawFrameTask.drawFrame();
 }
 
+void RenderProxy::setSyncOnlyNextFrame() {
+    mDrawFrameTask.setSyncOnlyNextFrame();
+}
+
 void RenderProxy::destroy() {
     // destroyCanvasAndSurface() needs a fence as when it returns the
     // underlying BufferQueue is going to be released from under
@@ -312,6 +316,22 @@ void RenderProxy::dumpProfileInfo(int fd, int dumpFlags) {
     });
 }
 
+void RenderProxy::dumpDisplayList(int fd, int surfaceOriginX, int surfaceOriginY,
+                                  int surfaceInsetX, int surfaceInsetY) {
+    mRenderThread.queue().runSync([&]() {
+        mContext->dumpDisplayList(
+                fd, surfaceOriginX, surfaceOriginY, surfaceInsetX, surfaceInsetY);
+    });
+}
+
+uint64_t RenderProxy::computeSemanticHash() {
+    uint64_t result = 0;
+    mRenderThread.queue().runSync([&]() {
+        result = mContext->computeSemanticHash();
+    });
+    return result;
+}
+
 void RenderProxy::resetProfileInfo() {
     mRenderThread.queue().runSync([this]() {
         std::lock_guard lock(mRenderThread.getJankDataMutex());
diff --git a/libs/hwui/renderthread/RenderProxy.h b/libs/hwui/renderthread/RenderProxy.h
index d375d1c0f424..31babbc5f01b 100644
--- a/libs/hwui/renderthread/RenderProxy.h
+++ b/libs/hwui/renderthread/RenderProxy.h
@@ -92,6 +92,7 @@ public:
     void setRenderSdrHdrRatio(float ratio);
     int64_t* frameInfo();
     void forceDrawNextFrame();
+    void setSyncOnlyNextFrame();
     int syncAndDrawFrame();
     void destroy();
 
@@ -119,6 +120,9 @@ public:
     void notifyGpuLoadUp();
 
     void dumpProfileInfo(int fd, int dumpFlags);
+    void dumpDisplayList(int fd, int surfaceOriginX, int surfaceOriginY,
+                         int surfaceInsetX, int surfaceInsetY);
+    uint64_t computeSemanticHash();
     // Not exported, only used for testing
     void resetProfileInfo();
     uint32_t frameTimePercentile(int p);
diff --git a/services/core/java/com/android/server/wm/ActivityStarter.java b/services/core/java/com/android/server/wm/ActivityStarter.java
index 48d41cee6b41..dfa5ebcedca7 100644
--- a/services/core/java/com/android/server/wm/ActivityStarter.java
+++ b/services/core/java/com/android/server/wm/ActivityStarter.java
@@ -51,6 +51,7 @@ import static android.content.pm.ActivityInfo.DOCUMENT_LAUNCH_ALWAYS;
 import static android.content.pm.ActivityInfo.FLAG_SHOW_FOR_ALL_USERS;
 import static android.content.pm.ActivityInfo.LAUNCH_SINGLE_INSTANCE;
 import static android.content.pm.ActivityInfo.LAUNCH_SINGLE_INSTANCE_PER_TASK;
+import static android.content.pm.ActivityInfo.LAUNCH_MULTIPLE;
 import static android.content.pm.ActivityInfo.LAUNCH_SINGLE_TASK;
 import static android.content.pm.ActivityInfo.LAUNCH_SINGLE_TOP;
 import static android.content.pm.ActivityInfo.launchModeToString;
@@ -58,6 +59,7 @@ import static android.os.Process.INVALID_UID;
 import static android.security.Flags.preventIntentRedirectAbortOrThrowException;
 import static android.security.Flags.preventIntentRedirectShowToast;
 import static android.view.Display.DEFAULT_DISPLAY;
+import static android.view.Display.INVALID_DISPLAY;
 import static android.view.WindowManager.TRANSIT_FLAG_AVOID_MOVE_TO_FRONT;
 import static android.view.WindowManager.TRANSIT_OPEN;
 import static android.window.TaskFragmentOperation.OP_TYPE_START_ACTIVITY_IN_TASK_FRAGMENT;
@@ -2742,6 +2744,20 @@ class ActivityStarter {
 
         mLaunchMode = r.launchMode;
 
+        // Agent Display: force MULTIPLE_TASK on agent displays to ensure a new task
+        // is created instead of reusing existing one (via taskAffinity or singleTask).
+        final int preferredDisplayId = mPreferredTaskDisplayArea != null
+                ? mPreferredTaskDisplayArea.getDisplayId() : -1;
+        final boolean isAgent = mService.isAgentDisplay(preferredDisplayId);
+        Slog.i("AgentDisplay", "setInitialState: activity=" + r.shortComponentName
+                + " displayId=" + preferredDisplayId + " isAgent=" + isAgent
+                + " origLaunchMode=" + r.launchMode);
+        if (isAgent) {
+            mLaunchMode = LAUNCH_MULTIPLE;
+            mLaunchFlags |= FLAG_ACTIVITY_NEW_TASK | FLAG_ACTIVITY_MULTIPLE_TASK;
+            Slog.i("AgentDisplay", "Overriding to LAUNCH_MULTIPLE + MULTIPLE_TASK");
+        }
+
         mLaunchFlags = adjustLaunchFlagsToDocumentMode(
                 r, LAUNCH_SINGLE_INSTANCE == mLaunchMode,
                 LAUNCH_SINGLE_TASK == mLaunchMode, mIntent.getFlags());
@@ -3030,6 +3046,12 @@ class ActivityStarter {
         // an explicit task to launch in to, and we can find a task that was started with this
         // same component, then instead of launching bring that one to the front.
         putIntoExistingTask &= mInTask == null && mStartActivity.resultTo == null;
+        // Agent Display exemption: allow new singleTask instance on agent displays.
+        if (putIntoExistingTask && mOptions != null
+                && mOptions.getLaunchDisplayId() != INVALID_DISPLAY
+                && mService.isAgentDisplay(mOptions.getLaunchDisplayId())) {
+            return null;
+        }
         ActivityRecord intentActivity = null;
         if (putIntoExistingTask) {
             if (LAUNCH_SINGLE_INSTANCE == mLaunchMode) {
diff --git a/services/core/java/com/android/server/wm/ActivityTaskManagerService.java b/services/core/java/com/android/server/wm/ActivityTaskManagerService.java
index e6767bd543b7..b868e3da5fcc 100644
--- a/services/core/java/com/android/server/wm/ActivityTaskManagerService.java
+++ b/services/core/java/com/android/server/wm/ActivityTaskManagerService.java
@@ -393,6 +393,9 @@ public class ActivityTaskManagerService extends IActivityTaskManager.Stub {
     /** The starting activities which are waiting for their processes to attach. */
     final ArrayList<ActivityRecord> mStartingProcessActivities = new ArrayList<>();
 
+    /** Display IDs registered as Agent displays, exempt from singleTask reuse. */
+    final ArraySet<Integer> mAgentDisplayIds = new ArraySet<>();
+
     /* Global service lock used by the package the owns this service. */
     final WindowManagerGlobalLock mGlobalLock = new WindowManagerGlobalLock();
     /**
@@ -7697,4 +7700,23 @@ public class ActivityTaskManagerService extends IActivityTaskManager.Stub {
         }
         return sIsPip2ExperimentEnabled;
     }
+
+    /** @hide */
+    public void registerAgentDisplay(int displayId) {
+        synchronized (mGlobalLock) {
+            mAgentDisplayIds.add(displayId);
+        }
+    }
+
+    /** @hide */
+    public void unregisterAgentDisplay(int displayId) {
+        synchronized (mGlobalLock) {
+            mAgentDisplayIds.remove(displayId);
+        }
+    }
+
+    /** @hide */
+    boolean isAgentDisplay(int displayId) {
+        return displayId != 0; // TEMP: all non-primary displays are agent displays
+    }
 }
diff --git a/tools/dlglyph/dl_glyph_decode.py b/tools/dlglyph/dl_glyph_decode.py
new file mode 100755
index 000000000000..2743633f14e6
--- /dev/null
+++ b/tools/dlglyph/dl_glyph_decode.py
@@ -0,0 +1,378 @@
+#!/usr/bin/env python3
+# Copyright (C) 2026 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+"""
+dl_glyph_decode.py — Reverse-map glyph IDs in `dumpsys gfxinfo <pkg> displaylist`
+output back to UTF-8 text using fontTools.
+
+This is a deterministic, model-free preprocessing step. The framework-side
+`FlatExportOpsCanvas` emits each drawText op's runs as
+  {"font": "<typeface_family>", "glyphs": [g1, g2, ...]}
+and this script walks the corresponding font's cmap (plus all TTC sub-fonts)
+to recover the original characters.
+
+Usage:
+  # Pull system fonts (one-time)
+  adb -s <serial> pull /system/fonts/Roboto-Regular.ttf       ~/fonts/
+  adb -s <serial> pull /system/fonts/NotoSansCJK-Regular.ttc  ~/fonts/
+
+  # Optional: pull app-private fonts from APK assets
+  adb -s <serial> pull /data/app/<...>/<pkg>-<...>/base.apk    /tmp/app.apk
+  unzip -j /tmp/app.apk "assets/*.ttf" "assets/*.otf" -d ~/fonts/
+
+  # Decode
+  adb -s <serial> exec-out "dumpsys gfxinfo <pkg> displaylist fresh nodraw" \
+    > /tmp/dl.json
+  ./dl_glyph_decode.py --fonts ~/fonts /tmp/dl.json -o /tmp/dl_decoded.json
+
+Empirical recovery rate on Settings/Zhihu/Bilibili home screens (see
+README.md §DisplayList Usability):
+  • Roboto (Latin):      100.0%  (1,519 / 1,519 glyphs)
+  • Noto Sans CJK SC:    100.0%  (   493 /    493 glyphs)
+  • App-private fonts:     0.0%  unless the corresponding TTF/OTF is supplied
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+try:
+    from fontTools.ttLib import TTFont, TTCollection
+except ImportError:
+    sys.stderr.write("ERROR: pip install fontTools\n")
+    sys.exit(1)
+
+
+# ── Font loading ───────────────────────────────────────────────────────────
+
+def cmap_of(font):
+    """Return {glyph_id: unicode_codepoint} for one TTFont.
+
+    Uses getBestCmap() which prefers Unicode platforms. Multiple Unicodes
+    that map to the same glyph (e.g. precomposed + decomposed forms) will
+    keep only the first one — acceptable for agent perception.
+    """
+    cmap = font.getBestCmap()
+    glyph_order = font.getGlyphOrder()
+    name_to_gid = {n: i for i, n in enumerate(glyph_order)}
+    rev = {}
+    for u, name in cmap.items():
+        gid = name_to_gid.get(name)
+        if gid is not None and gid not in rev:
+            rev[gid] = u
+    return rev
+
+
+def load_fonts_dir(fonts_dir):
+    """Walk fonts_dir, load every .ttf/.otf/.ttc file.
+
+    For TTC (TrueType Collection), union the cmaps of ALL sub-fonts so that
+    region-specific glyphs (SC/TC/JP/KR/HK variants of Noto Sans CJK) are
+    all available under the same family name.
+
+    Returns a dict {family_name (lowercased): [cmap_dict, ...]}. Each physical
+    font registers its OWN cmap as a separate candidate, because multiple
+    files can legitimately share a family name yet carry DIFFERENT glyph
+    orderings (e.g. several subsetted "FZYouHeiS" instances downloaded by one
+    app). decode_run() tries every candidate and keeps the best fit. Family
+    name is taken from the font's `name` table to match what
+    SkTypeface::getFamilyName() reports.
+    """
+    families = {}  # lowercased name -> list of {gid: unicode}
+
+    def register(font, src):
+        # Collect ALL candidate family names this font may be referenced by.
+        # Skia's SkTypeface::getFamilyName() (what the DL "font" field carries)
+        # may report the typographic family (name id 16) WITHOUT the subfamily
+        # suffix, while the legacy family (id 1) often includes it
+        # (e.g. "FZYouHeiS 508R" vs typographic "FZYouHeiS"). Index under every
+        # distinct name so the DL family matches regardless.
+        names = set()
+        try:
+            for rec in font['name'].names:
+                if rec.nameID in (1, 4, 6, 16):
+                    try:
+                        val = rec.toUnicode().strip()
+                    except Exception:
+                        continue
+                    if val:
+                        names.add(val)
+                        # Postscript names (id 6) often replace spaces with
+                        # hyphens; also add a space-normalized variant.
+                        names.add(val.replace('-', ' '))
+        except Exception:
+            pass
+        if not names:
+            names.add(src.stem)
+        m = cmap_of(font)
+        primary = None
+        for val in sorted(names):
+            key = val.lower()
+            if primary is None:
+                primary = val
+            # Append this font's cmap as a candidate for the family name.
+            # Avoid duplicate identical cmaps under the same key.
+            bucket = families.setdefault(key, [])
+            if m not in bucket:
+                bucket.append(m)
+        return primary, len(m)
+
+    loaded = []
+    for path in sorted(Path(fonts_dir).rglob('*')):
+        if not path.is_file():
+            continue
+        suffix = path.suffix.lower()
+        try:
+            if suffix in ('.ttf', '.otf'):
+                font = TTFont(str(path), lazy=True)
+                fam, n = register(font, path)
+                loaded.append((path.name, fam, n))
+            elif suffix == '.ttc':
+                ttc = TTCollection(str(path), lazy=True)
+                for i, sub in enumerate(ttc.fonts):
+                    fam, n = register(sub, path)
+                    loaded.append((f"{path.name}#{i}", fam, n))
+        except Exception as e:
+            print(f"  ! skipped {path.name}: {e}", file=sys.stderr)
+
+    return families, loaded
+
+
+# ── Decoding ───────────────────────────────────────────────────────────────
+
+# Optional CJK plausibility scorer. When several fonts share a family name but
+# carry different glyph orderings (subsetted instances), the DL "font" field
+# (a bare family name) cannot disambiguate them, and several candidates may
+# decode every glyph WITHOUT a miss — yet only one yields real words. We break
+# such ties by word-level frequency (most plausible text wins). Degrades
+# gracefully to the fewest-misses heuristic if wordfreq is unavailable.
+try:
+    from wordfreq import zipf_frequency as _zipf
+    try:
+        import jieba as _jieba
+        _jieba.setLogLevel(60)
+        _HAS_JIEBA = True
+    except Exception:
+        _HAS_JIEBA = False
+    _HAS_WORDFREQ = True
+except Exception:
+    _HAS_WORDFREQ = False
+    _HAS_JIEBA = False
+
+
+def _has_cjk(s):
+    return any('\u4e00' <= c <= '\u9fff' for c in s)
+
+
+def _plausibility(text):
+    """Higher = more plausible real text. CJK: max word-level zipf frequency
+    over the string and its jieba tokens. Non-CJK or no wordfreq: 0."""
+    if not _HAS_WORDFREQ or not text or not _has_cjk(text):
+        return 0.0
+    cands = [text]
+    if _HAS_JIEBA:
+        cands += list(_jieba.cut(text))
+    best = 0.0
+    for t in cands:
+        if _has_cjk(t):
+            try:
+                best = max(best, _zipf(t, 'zh'))
+            except Exception:
+                pass
+    return best
+
+
+def decode_run(family, glyphs, font_table):
+    """Translate a run's glyph IDs into a Python str.
+
+    A family name may map to several candidate fonts with different glyph
+    orderings (subsetted instances that share a name). Try each candidate;
+    keep the decoding with the fewest unmapped glyphs, breaking ties by CJK
+    word-frequency plausibility (so "推荐" wins over an equally-mapped but
+    nonsensical "掐茹"). Unmapped glyphs are emitted as U+FFFD so the output
+    stays a valid string and callers can measure failure rate.
+    Returns (decoded_str, num_unmapped).
+    """
+    candidates = font_table.get(family.lower())
+    if not candidates:
+        # Try family aliases (e.g. "sans-serif" → "roboto")
+        if family.lower() in ('sans-serif', 'default', 'normal'):
+            candidates = font_table.get('roboto')
+    if not candidates:
+        return '\ufffd' * len(glyphs), len(glyphs)
+
+    best = None  # (neg_miss, plausibility, chars)
+    for cmap in candidates:
+        chars = []
+        miss = 0
+        for g in glyphs:
+            u = cmap.get(g)
+            if u is None:
+                chars.append('\ufffd')
+                miss += 1
+            else:
+                chars.append(chr(u))
+        text = ''.join(chars)
+        score = (-miss, _plausibility(text))
+        if best is None or score > best[0]:
+            best = (score, miss, chars)
+            if miss == 0 and best[0][1] == 0.0 and len(candidates) == 1:
+                break
+    return ''.join(best[2]), best[1]
+
+
+def extract_dl_blocks(content):
+    """Extract balanced {"frame":...} blocks from raw dumpsys output.
+
+    `dumpsys gfxinfo <pkg> displaylist` prefixes each window's JSON with a
+    profile-stats header; we walk the content and pull out every JSON
+    object that starts with `{"frame"`.
+    """
+    blocks = []
+    pos = 0
+    while True:
+        i = content.find('{"frame"', pos)
+        if i < 0:
+            break
+        depth = 0
+        in_str = False
+        esc = False
+        end = -1
+        for j in range(i, len(content)):
+            c = content[j]
+            if esc:
+                esc = False
+                continue
+            if c == '\\':
+                esc = True
+                continue
+            if c == '"':
+                in_str = not in_str
+                continue
+            if in_str:
+                continue
+            if c == '{':
+                depth += 1
+            elif c == '}':
+                depth -= 1
+                if depth == 0:
+                    end = j + 1
+                    break
+        if end < 0:
+            break
+        try:
+            blocks.append(json.loads(content[i:end]))
+        except json.JSONDecodeError:
+            pass
+        pos = end
+    return blocks
+
+
+def decode_blocks(blocks, font_table):
+    """Walk each drawText op in every block, attach a "text" field decoded
+    from its runs. Returns (modified_blocks, stats_dict).
+    """
+    total_glyphs = 0
+    miss_glyphs = 0
+    per_font = {}  # family -> [glyphs, missing]
+
+    def walk(ops):
+        nonlocal total_glyphs, miss_glyphs
+        for op in ops:
+            if op.get('op') == 'drawText' and 'runs' in op:
+                parts = []
+                for run in op['runs']:
+                    family = run.get('font', '')
+                    glyphs = run.get('glyphs', [])
+                    s, miss = decode_run(family, glyphs, font_table)
+                    parts.append(s)
+                    total_glyphs += len(glyphs)
+                    miss_glyphs += miss
+                    rec = per_font.setdefault(family, [0, 0])
+                    rec[0] += len(glyphs)
+                    rec[1] += miss
+                op['text'] = ''.join(parts)
+            # Nested drawDrawable
+            if 'ops' in op:
+                walk(op['ops'])
+
+    for b in blocks:
+        for node in b.get('nodes', []):
+            walk(node.get('ops', []))
+
+    return blocks, {
+        'total_glyphs': total_glyphs,
+        'missed_glyphs': miss_glyphs,
+        'recovery_rate': (total_glyphs - miss_glyphs) / total_glyphs if total_glyphs else 1.0,
+        'per_font': per_font,
+    }
+
+
+# ── CLI ────────────────────────────────────────────────────────────────────
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__.split('\n')[0])
+    p.add_argument('input', help="Raw dumpsys gfxinfo ... displaylist output, "
+                                 "or use '-' for stdin")
+    p.add_argument('--fonts', required=True,
+                   help="Directory of .ttf/.otf/.ttc files (pull from "
+                        "/system/fonts/ and APK assets)")
+    p.add_argument('-o', '--output',
+                   help="Write decoded JSON here. If omitted, prints to stdout.")
+    p.add_argument('--stats-only', action='store_true',
+                   help="Print recovery statistics only; suppress JSON output.")
+    args = p.parse_args()
+
+    if not Path(args.fonts).is_dir():
+        sys.stderr.write(f"ERROR: fonts dir does not exist: {args.fonts}\n")
+        sys.exit(2)
+
+    font_table, loaded = load_fonts_dir(args.fonts)
+    print(f"Loaded {len(loaded)} font(s) covering "
+          f"{len(font_table)} family name(s):", file=sys.stderr)
+    for src, fam, n in loaded:
+        print(f"  {src:<35} family={fam!r:<25} glyphs={n}", file=sys.stderr)
+
+    if args.input == '-':
+        content = sys.stdin.read()
+    else:
+        content = Path(args.input).read_text()
+
+    blocks = extract_dl_blocks(content)
+    if not blocks:
+        sys.stderr.write("ERROR: no DL JSON blocks found in input\n")
+        sys.exit(3)
+    decoded, stats = decode_blocks(blocks, font_table)
+
+    print(f"\nGlyph recovery: {stats['total_glyphs'] - stats['missed_glyphs']}"
+          f" / {stats['total_glyphs']} "
+          f"({stats['recovery_rate']*100:.1f}%)", file=sys.stderr)
+    if stats['per_font']:
+        print("Per-font breakdown:", file=sys.stderr)
+        for fam, (total, miss) in sorted(stats['per_font'].items(),
+                                         key=lambda x: -x[1][0]):
+            recovered = total - miss
+            pct = recovered * 100 / total if total else 0
+            print(f"  {fam:<30} {recovered:>6}/{total:<6} ({pct:5.1f}%)",
+                  file=sys.stderr)
+
+    if args.stats_only:
+        return
+
+    out_json = json.dumps(decoded, ensure_ascii=False, indent=2)
+    if args.output:
+        Path(args.output).write_text(out_json)
+        print(f"\nWrote: {args.output}", file=sys.stderr)
+    else:
+        sys.stdout.write(out_json)
+
+
+if __name__ == '__main__':
+    main()