diff --git a/.gitignore b/.gitignore
index a3bd8c7..073eddd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,6 +23,14 @@ out/
 work/
 audit_out/
 
+# local extension-pass workspace: toolchains, device archives, dumped images, scratch notes.
+# Nothing under tools/ belongs to the repository -- the skill's own evidence record lives in
+# docs/tool-verification/ and carries no target identity or vendored binaries.
+tools/
+
+# local input material (the reporting sample and the analysis notes it came with)
+存在问题和例子/
+
 # sandbox installs made while testing `npx skills add .` against this repo
 .claude/
 .agents/
diff --git a/README.md b/README.md
index 4758318..663b396 100644
--- a/README.md
+++ b/README.md
@@ -74,6 +74,23 @@ measurements.
   bounded waits, so progress is not lost and the same mistake is not made twice.
 - Avoiding the specific mistakes that produce an APK that builds perfectly and dies at
   runtime.
+- Deciding **what the deliverable should be when an APK is not an option** — a repack refused by
+  several independent checks is *blocked*, not expensive, and the fallback ladder is a system-level
+  module, a local RPC service, or an honest report with a stated boundary.
+- Telling a **real memory dump from an extraction-shell skeleton**, by measuring the trivial-body
+  ratio instead of eyeballing it — and knowing which recovery route applies, including the root-side
+  dump for when `frida` itself is refused by the target.
+- **Calling a routine instead of reversing it** when reversing costs more than invoking: emulated
+  execution on the host, or a live function service-ified over Frida RPC.
+- Reading **instruction-level execution evidence** when a native function has been flattened into a
+  state machine by OLLVM — including the two ways Stalker was measured to bite back on a real device.
+- Recognising when **userspace hooking cannot reach the check at all** (raw `svc` syscalls,
+  `init_array`-early detection), what the next layer up and down can actually do, and when escalating
+  is the wrong answer.
+- Working **protocols that are not REST** — protobuf without a schema, gRPC, QUIC/HTTP3 — and
+  native-side certificate pinning that ignores the system trust store.
+- Working **from the phone itself**: MT Manager's edit/repack/sign flow and its APK MCP surface,
+  LSPosed Manager, and on-device data inspection, alongside the PC toolchain rather than instead of it.
 
 ## Structure
 
@@ -169,6 +186,27 @@ references/               loaded on demand, one topic each
                               emulator console control and recovery, preflight, look-at-the-screen
   verification.md             the claim ladder; what "done" means
   pitfalls.md                 the failure catalogue -- read before building
+  advanced-unpacking.md       the dump landed but the bodies are empty: extraction-shell diagnosis by
+                              trivial-body ratio, FART-style active invocation and why its classic hooks
+                              died on Android 12-16, code_item splicing, the root-side dump for when
+                              frida itself is refused, and the honest VMP boundary
+  lsposed-and-modules.md      the repack is refused, so deliver a system-level hook module instead:
+                              module anatomy, a gradle-free build chain, scope configuration and how to
+                              verify injection, and the layer a Java module cannot reach
+  emulation-and-rpc.md        call the routine instead of reading it: Unidbg/Unicorn emulation and its
+                              environment-filling cost, versus service-ifying a live function over Frida RPC
+  native-dbi-and-deobfuscation.md
+                              OLLVM shapes, Frida-Stalker traces, the trace-to-CFG route, the
+                              Stalker/QBDI/emulation decision, and two measured boundaries (a follow that
+                              delivers no events, and a crash from following a hot libc export)
+  protocol-reverse.md         protobuf without a schema, schema recovery from decompiled code, gRPC frame
+                              capture, the QUIC/HTTP3 limit, and native-side certificate pinning
+  kernel-and-environment-hardening.md
+                              userspace hooking provably cannot reach the check: raw `svc`, init_array-early
+                              detection, what each root scheme hides, the kernel-route map with its version
+                              gate, and when to stop escalating
+  on-device-tooling.md        working from the phone itself: MT Manager edit/repack/sign and its APK MCP,
+                              LSPosed Manager, Termux+frida, on-device data inspection
 scripts/                  parameterized, path-agnostic
   doctor.py                   run this first: capability report + per-script runnability, finds
                               tools installed off-PATH or as runnable jars, and surfaces the
@@ -238,6 +276,24 @@ scripts/                  parameterized, path-agnostic
                               writes survive detach while hooks do not
   hook_patch_only.js          the minimal probe for spawn_patch_detach.py — neutralise one native
                               death site by offset and report PATCHED
+  dex_dump_validate.py        dedupe, validate and rank a directory of dumped dex images: sha256
+                              grouping, header integrity, the trivial-body ratio that separates a real
+                              dump from an extraction-shell skeleton, and a most-likely-original ranking
+                              (--trim for page-aligned /proc/<pid>/mem captures)
+  dex_mem_scan.py             search memory captures for embedded dex images and extract each at the
+                              size its own header declares -- for a decrypted dex sitting in an
+                              anonymous mapping no maps entry names
+  lsposed_scaffold.py         generate a minimal LSPosed/Xposed module project (manifest with the
+                              xposed meta-data, assets/xposed_init, hook class, gradle-free build notes)
+  frida_rpc_serve.py          bridge a Frida script's rpc.exports to a local caller with reconnect
+                              handling, so a live native function can be called rather than reversed
+  rpc_template.js             the editable companion to frida_rpc_serve.py
+  stalker_trace.js            instruction-level tracing with Frida Stalker: configurable targets,
+                              trigger selection, the event stream, and output-size rules
+  stalker_report.py           reduce a stalker_trace.js log to block histograms and call sequences,
+                              with an explicit diagnostic for the measured zero-event case
+  mt_mcp_probe.py             probe MT Manager's on-device APK MCP (Streamable HTTP, port 8787):
+                              JSON-RPC handshake plus the grouped tool inventory
 ```
 
 ## Install
@@ -322,12 +378,17 @@ target-specific data.
 What it covers, and what it deliberately does not, is stated at the top of `SKILL.md`
 under **Coverage**. The short version: Android only (no iOS), and deep on the layers
 that have been worked through for real — dex patching, repacking, packers and custom
-loaders, native tamper response, and Flutter/Dart AOT. Unity/IL2CPP logic recovery,
+loaders, native tamper response, and Flutter/Dart AOT. An extension pass added a second
+tier of documented routes: **module-side delivery** when a repack is blocked,
+**extraction-shell recovery** and its VMP boundary, **emulation and live RPC** for
+calling rather than reading, **instruction-level tracing** against OLLVM, **protocol
+reversing** beyond REST, the **kernel-side route** map for when userspace hooking is
+provably out of reach, and **on-device tooling**. Unity/IL2CPP logic recovery,
 React Native/Hermes bytecode internals, and defeating a server-side authority are **not**
 covered, and the skill is written to say so and stop rather than apply the nearest
 documented procedure to a target it was not written for.
 
-Two qualifications that the Coverage section states in full and that belong here too:
+Three qualifications that the Coverage section states in full and that belong here too:
 
 - **Flutter/Dart AOT analysis has a dependency.** The workflow begins at a pool listing
   (`pp.txt`-class output). Producing that needs a snapshot-decoding decompiler — aotopsy (a static
@@ -337,6 +398,10 @@ Two qualifications that the Coverage section states in full and that belong here
   what was actually measured, on which target, and with which independent cross-check; anything not
   covered there is documented from experience and should be read as *inferred*, per this skill's own
   claim ladder.
+- **The extension pass is recorded separately and is mostly *inferred*.** Its evidence lives in
+  `docs/tool-verification/EXTENSION-*.md`, one file per topic, with its own strength note. The
+  common shape there is *the tool was measured, the route was not* — so read those files before
+  treating any of the newer documents as a verified path.
 
 ## Repository maintenance
 
diff --git a/docs/tool-verification/EXTENSION-device-run.md b/docs/tool-verification/EXTENSION-device-run.md
new file mode 100644
index 0000000..7b2d9cd
--- /dev/null
+++ b/docs/tool-verification/EXTENSION-device-run.md
@@ -0,0 +1,252 @@
+# Extension pass — on-device run against a hardened Flutter sample
+
+This file records the **device-side** half of the extension pass: what was actually executed against
+a live, hardened sample, what the sample did in response, and which conclusions the evidence supports.
+
+It follows the same three labels the rest of this directory uses:
+
+- **observed** — reproduced here, with the exact command and its output.
+- **inferred** — follows from observed facts, but the step itself was not executed.
+- **unverified** — assumed, or reported by a tool and not independently confirmed.
+
+**Target identity is deliberately absent.** The sample is referred to as *the sample*, and its package
+identifier appears as `<PKG>`. The findings are about the tools and the methods, and stay valid
+whichever hardened APK produced them.
+
+## Environment (observed)
+
+| Item | Value |
+|---|---|
+| Device | one physical arm64 device, Android 11 (API 30), kernel 4.14.186, Magisk root |
+| Host | Windows 11, Python 3.14.0, frida 16.7.19, frida-tools 13.7.1, frida-dexdump 2.0.1, java 17, adb 1.0.41 |
+| Device server | `frida-server` 16.7.19 (version-matched to the host by `frida-server --version`) |
+| Sample | 360-jiagu hardened, `application android:name` = a third-party stub class; Flutter AOT payload |
+| Host capability report | `python scripts/doctor.py` → static/repack/smali/native-patch/device/root/frida all OK; `28 / 28` scripts runnable |
+| Pre-flight warnings | clock skew 3.32 s; leftover `adb forward` entries (8787, 8651, 65534, 27043); a device-side `frida-server` already running |
+
+Two environment facts from `doctor.py` are worth carrying forward, because each of them silently
+invalidates a measurement: the clock skew, and a **frida process already up on the device** — the
+second one means the target may already be reacting to instrumentation before your first command.
+
+## The measurement that mattered: the sample fights instrumentation
+
+### (1) Control — the sample starts normally with no instrumentation (observed)
+
+```
+$ adb shell 'su -c "am force-stop <PKG>; sleep 1; am start -n <PKG>/.MainActivity"'
+$ sleep 12 && adb shell 'su -c "ps -A | grep -i <PKG>"'
+u0_a623  22691  17278  14123672  642488  SyS_epoll_wait  0 S <PKG>
+```
+
+Resident, 642 MB, healthy. **This is the control build the rest of the section is measured against.**
+
+### (2) The pid drifts — but **not** because of frida (observed, corrected)
+
+During the session the sample's pid changed repeatedly:
+
+```
+22691  →  23452  →  24267  →  27274  →  31284  →  32259  →  1368  →  8161
+```
+
+The natural reading is "the sample fights instrumentation", and the first write-up of this file said
+exactly that. **The follow-up measurement refuted it.** With `frida-server` stopped and no attach of
+any kind, the sample was restarted under observation for 90 seconds:
+
+```
+20:28:22 pid=[9961]  load=36.43 | Mem: 11484 total  11077 used   406 free
+20:28:33 pid=[9961]  load=36.26 | Mem: 11484 total  10767 used   716 free
+20:28:45 pid=[9961]  load=35.61 | Mem: 11484 total  10739 used   745 free
+20:28:56 pid=[9961]  load=34.64 | Mem: 11484 total  10767 used   716 free
+20:29:08 pid=[11246] load=34.91 | Mem: 11484 total  11151 used   333 free
+20:29:19 pid=[11246] load=35.69 | Mem: 11484 total  11142 used   342 free
+20:29:31 pid=[12238] load=35.14 | Mem: 11484 total  11131 used   353 free
+20:29:42 pid=[13212] load=37.03 | Mem: 11484 total  11059 used   424 free
+```
+
+The pid changes with **no frida present**, roughly every 10-20 seconds, while the device sits at
+300-750 MB of free memory out of 11.5 GB. The first correction to this file attributed that to memory
+pressure. **That attribution was also wrong, and the device-side dumping run refuted it** with a
+better instrument than sampling: `logcat`.
+
+```
+$ adb logcat | grep <PKG>
+Process <PKG> (pid N) has died: fg TOP
+Start proc <pid> for top-activity <PKG>
+```
+
+The process **dies as the foreground top activity, with no crash, no tombstone and no ANR record**,
+and the platform immediately relaunches it — a clean self-exit in a loop, on a 7-18 second cycle. A
+reclaiming device does not do that to a foreground process, and a memory-pressure kill leaves an
+`lmkd` line and a low-memory record. What produces exactly this shape is the sample **checking its own
+environment and quitting on purpose**.
+
+And the environment it finds is decisive: on this device `magisk --denylist status` reports **enforced
+with an empty list**, Zygisk-Assistant is installed but nothing is scoped, and
+`/data/adb/shamiko` does not exist — so **no application on this device is hidden from root**
+(`EXTENSION-lsposed.md`, observed). A hardened sample that refuses to run on a rooted device will do
+exactly this, forever, and no amount of dump-retrying changes it.
+
+**Reading, corrected twice:** the pid drift is an artefact of the **root environment**, not of
+instrumentation and not of memory pressure. The practical consequence is the useful part — *before any
+dynamic analysis of a hardened sample, configure root hiding and re-run the baseline*, because with
+nothing hidden every dynamic result on this device is measured against a process that is trying to die.
+The observer's first control run showed a "stable" sample for 12 seconds only because it happened to
+sample inside one 17-second lifetime.
+
+This is the skill's own rule applied twice to its own record: a conclusion was reopened each time a
+measurement disagreed with it (`SKILL.md` §Stop conditions, last bullet). Two wrong attributions were
+cheaper to delete than for a reader to inherit — and the second one only fell because a different
+method (`logcat`, not sampling) was pointed at the same question.
+
+The platform's own view of a failed launch was also captured, and is worth keeping as a *shape*:
+
+```
+W ActivityManager: Process ProcessRecord{…:<PKG>/u0a623} failed to attach
+I ActivityManager: Killing <pid>:<PKG>/u0a623 (adj -10000): start timeout
+```
+
+A `start timeout` kill reads the same whether the cause is a slow shell init, a reclaiming device, or a
+deliberate delay. It does not discriminate, and it is not evidence either way.
+
+### (3) `frida-dexdump` cannot complete a memory dump — reproduced twice (observed)
+
+Both spawn and attach were tried, with the parameter mistakes fixed between attempts:
+
+```
+$ frida-dexdump -U -f <PKG> -d -o <out>            # spawn
+Failed to spawn: need Gadget to attach on jailed Android; its default location is: …gadget-android-arm64.so
+
+$ frida-dexdump -U -f <PKG> -d 12 -o <out>         # 12 was parsed as an argv entry, not a delay
+Failed to spawn: the 'argv' option is not supported when spawning Android apps
+
+$ frida-dexdump -U -f <PKG> -d -o <out>            # corrected
+Failed to spawn: unexpectedly timed out while waiting for app to launch
+
+$ frida-dexdump -U -p <pid> -d -o <out>            # attach, twice, second run with the device idle
+frida.InvalidOperationError: script has been destroyed: {'addr': '0x721e24c02c', 'size': 409556}
+INFO:frida-dexdump:[*] All done... Process terminated
+```
+
+Attach was run twice. The **second** run was the clean one: no Stalker traffic anywhere on the device
+(see the crash note below), the package enabled and verified running, the pid read immediately before
+the attach, and a single variable changed relative to the control. It produced the same
+`script has been destroyed` failure, and the sample's pid changed again in the aftermath.
+
+**What the failed runs left behind, checked with the kit's own validator** (`observed`):
+
+```
+$ python skills/apk-reverse/scripts/dex_dump_validate.py <dump_dir>
+== dex dump validation: 2 file(s), 2 parse, 0 rejected ==
+name            size       sha256[:12]   ver  cksum  sig  class        noco  code  stub%
+classes.dex        500    9461987e5464  035  BAD    BAD  1986754560   0     0     0.0%
+                            walk stopped early: index out of range
+classes02.dex   10285489   116d8b84b486  035  BAD    BAD  1986754560   0     0     0.0%
+                            walk stopped early: index out of range
+```
+
+Both artifacts pass the magic check and then fail everything else: checksum and signature both BAD,
+no classes recovered, the walk stopping on an out-of-range index. They are **memory fragments cut
+short by the process dying mid-read**, not dex images — and this is exactly the case
+`dex_dump_validate.py` exists for. A size-based heuristic would have kept the 10.2 MB file and
+discarded the 500-byte one; both are worthless, and only a structural walk says so.
+
+**Reading:** under these conditions the memory-dump route is refused by the target, not by the host
+tooling. Two shape-identical failures on a single variable is the skill's own stop signal: the correct
+move is to re-classify (`references/advanced-unpacking.md` §the four shapes, then
+`references/detection-and-anti-analysis.md`), **not** to run a third variant of the same attach.
+
+Two of the four failures above were the observer's own mistakes, and they are worth keeping because
+they are cheap to repeat: `-d` is a switch, not a delay, and any extra positional argument reaches
+`spawn(argv)`. `-n <name>` on this version of `frida-dexdump` also still routes through the spawn
+path, so "attach by name" does not exist as a way around the spawn refusal — use `-p <pid>`.
+
+### (4) What the sample looks like at the moment it is attacked (observed)
+
+```
+$ adb shell 'su -c "top -n 1 -b"'
+  PID USER      PR NI  VIRT   RES   SHR S[%CPU] %MEM   TIME+ ARGS
+31284 u0_a623   10 -10  13G   561M  268M S  439   4.8   0:05.52 <PKG>
+154   root     20   0     0     0     0 S 66.6   0.0   0:02.18 [kswapd0]
+17638 system   18  -2   12G   590M  419M S 60.6   5.1   1:15.93 system_server
+```
+
+A Flutter application in its startup window saturates several cores (439 % CPU) while the Dart VM
+initialises, and the device — 11.7 GB RAM with 357 MB free at that moment — runs its reclaim thread at
+two thirds of a core. **The load on this device during the experiment was the sample's, not the
+observer's instrumentation.** That matters for attribution: "the device is slow, so the dump failed"
+is not available as an explanation here, because the failing command is a *protocol* failure
+(`script has been destroyed`) rather than a timeout.
+
+## The device's own framework was already damaged (observed)
+
+Recorded here because it is a **third candidate mechanism** for "things keep restarting", alongside the
+sample's self-exit and the memory pressure — and because it invalidates any dynamic result that
+depends on the hooking framework:
+
+- `LSPosed Manager` opened to **"LSPosed is not installed"**, with no modules tab, while the `lspd`
+  daemon was still alive.
+- The LSPosed configuration database had not been updated since **19:37** — it still pointed at the
+  `codePath` of an app that had been uninstalled, and never registered the replacement.
+- `logcat` showed a loop: `system server died`, `am is dead`, `no response from bridge`, and
+  `Magisk: zygote crashed too many times, rolling-back`.
+
+A zygote in a crash-and-rollback cycle restarts application processes by itself, so **"the pid changed"
+had at least three independent possible causes on this device** (the sample exiting, reclaim, and a
+broken framework). That is exactly why the corrected §2 attributes the drift to *instability of the
+observation target* rather than to any single mechanism, and why a dynamic result needs its device's
+framework state recorded next to it — `scripts/preflight.py` reads device state for the same reason.
+
+Recovery is a reboot (Magisk re-initialises Zygisk and `lspd` at `late_start`; the LSPosed daemon is
+started once and does not return if killed). Whether the framework came back after the reboot, and
+whether the sample's self-exit behaviour changed with it, is recorded in
+`EXTENSION-lsposed.md` — and any change there must stay **inferred**, because a reboot moves several
+variables at once.
+
+## A shared-device hazard, measured (observed)
+
+While the run above was in progress, a second agent on the same device used **Frida Stalker** against
+`com.android.settings` and `com.android.systemui`, including a `libc` `malloc` export trigger that
+entered and left `follow` hundreds of times. Result:
+
+- `Stalker.follow` on the main thread reported `blocks=0`, `blk=0`, `calls=0` — **the follow installed
+  and no events arrived**.
+- `systemui` then died with `SIGSEGV`, the faulting frame sitting in gum's anonymous code cache and
+  the backtrace continuing into `libart` at `art::Reference_getReferent`; the process restarted
+  (`18030 → 26932`).
+- Device load average reached **34.11** on an eight-core phone.
+
+**Reading:** two conclusions, kept separate on purpose. First, on this ROM + `frida-server` 16.7.19
+combination a Stalker follow produced no events — that is a *boundary* for
+`references/native-dbi-and-deobfuscation.md`, not a contradiction of Stalker's documentation. Second,
+high-frequency `follow`/`unfollow` on every `malloc` entry crashed a system process — a measured
+failure mode for the pattern, and one worth stating before anyone puts it in a shipped script.
+
+The third conclusion is about method rather than about Stalker: **instrumentation on a shared device
+is a shared variable.** The concurrent load damaged the *other* experiment's validity — the dumped-run
+above could not be attributed until it was repeated with the device idle, and the repeat is what
+turned "maybe the load broke it" into a reproducible protocol refusal. R2 (one variable at a time)
+applies across agents, not only within one script.
+
+## Conclusions, graded
+
+| Claim | Label |
+|---|---|
+| The sample runs healthy with no instrumentation on the device | observed |
+| The sample's pid drifts repeatedly during an experiment, roughly every 10-20 s | observed — **cause not instrumentation**: reproduced with `frida-server` stopped, under 300-750 MB free memory (§2) |
+| `frida-dexdump` spawn refuses (jailed / argv / timeout) and attach fails with `script has been destroyed`, reproduced twice with the parameter mistakes fixed | observed |
+| The attach failure is deliberate armour rather than a host-tool bug | **unverified** — memory pressure leaving the process an unstable target is a competing explanation this pass did **not** rule out; the single-variable repeat eliminated *concurrent* load, not *baseline* load |
+| The shipped shell `classes.dex` is 8.9 MB and defines only 4 classes / 29 methods with code | observed (recorded in `EXTENSION-unpacking.md`) |
+| Recovering the real bodies needs a route other than a `frida` memory dump on this target | inferred |
+| Stalker follow delivers no events on this ROM with this frida-server version | observed, single sample, `unverified` as a general rule |
+| High-frequency follow/unfollow on `malloc` can crash a system process | observed, once |
+| No app on this device is currently hidden from root (`magisk --denylist status` enforced, list empty; Zygisk-Assistant installed but nothing configured) | observed (recorded in `EXTENSION-lsposed.md`) — offered here because a hardened sample's sensitivity to a rooted device has a configuration, not just a cause |
+
+## What this pass did **not** establish
+
+- **Not** a successful end-to-end unpack of the sample. The memory-dump route was refused, and the
+  pass stopped at the skill's own two-strike rule instead of escalating into an evasion arms race.
+- **Not** evidence that the sample is un-unpackable. The routes that do not use `frida` on the device
+  — root-side `/proc/<pid>/mem` extraction, the module route in `references/lsposed-and-modules.md`,
+  and the static route already recorded for the Flutter payload — were not exhausted here.
+- **Not** a general claim about 360-jiagu, Flutter, or Android 11. Everything above is one device,
+  one ROM, one server version, one sample.
diff --git a/docs/tool-verification/EXTENSION-emulation-rpc.md b/docs/tool-verification/EXTENSION-emulation-rpc.md
new file mode 100644
index 0000000..d68417f
--- /dev/null
+++ b/docs/tool-verification/EXTENSION-emulation-rpc.md
@@ -0,0 +1,431 @@
+# Extension verification — offline emulation (unidbg) and Frida RPC
+
+Covers the 2026-09 extension pass that added `references/emulation-and-rpc.md`,
+`scripts/frida_rpc_serve.py` and `scripts/rpc_template.js`. Strength labels as defined in this
+directory's README: **observed** (exact command + output recorded here), **inferred** (follows from
+observed facts, step not executed), **unverified** (assumed or externally reported, not independently
+confirmed here).
+
+Reference environment for this pass: Windows host, Python 3.14.0, host `frida` 16.7.19 +
+`frida-python` 16.7.19 (frida-tools 13.7.1), `adb` 37.0.1, JDK 17.0.4.1 (with `JAVA_HOME`
+**unset** in the shell — see §5). Device `<DEVICE>`: Android 11 / API 30, arm64-v8a, rooted
+(Magisk), on-device frida-server 16.7.19. Workbench artifacts live in `tools/_work/t3-rpc/` (not part
+of the skill).
+
+**Device-exclusivity constraint during this pass**: another task was unpacking the hardened Flutter
+sample on the same device. This pass never attached to, spawned or force-stopped that sample's
+process, and never killed or restarted the device-side frida-server. All RPC work targeted unrelated
+processes (system apps and third-party apps). De-identification: the sample's package label, real
+package name and md5 are elided in this document as `com.example.app` / `<label>`; command shapes,
+counts, class names and timings are verbatim.
+
+---
+
+## 0. Summary of what this pass established
+
+| Claim | Label |
+|---|---|
+| `droidasc` 0.1.1.post1 and `ddc` 0.1.8 both run on this host; both read the hardened sample's shell dex | observed |
+| Both tools see only the 4 shell classes in the APK's dex; business classes are absent (shell dex only) | observed |
+| `frida_rpc_serve.py` `--help`, all three modes, reconnect, spawn and attach-by-pid work against a live device | observed |
+| Attach **by package name** fails on this ROM while attach **by pid** succeeds for the same process | observed |
+| The device-side server may be (re)started on a non-default port; `--remote HOST:PORT` recovers, device-serial lookup does not | observed |
+| unidbg 0.9.10-SNAPSHOT builds and boots an Android emulator on this host after a pom fix; one bundled test suite passes | observed |
+| Any target `.so` actually emulated under unidbg | **not done** (unverified) |
+| frida 17 compatibility of `rpc_template.js` export lookup | unverified (host has 16.7.19 only) |
+
+---
+
+## 1. ASC (`droidasc`) — observed
+
+### 1.1 Install and version
+
+```
+$ python -m pip show droidasc
+Name: droidasc
+Version: 0.1.1.post1
+Summary: ASC is a super FAST python Android Decompiler for Agents/Mobile Researchers
+License-Expression: Apache-2.0
+Location: C:\Python314\Lib\site-packages
+Requires: androguard
+```
+
+Install line used (recorded after the fact; the package was already present on this host):
+`python -m pip install droidasc`. Distribution metadata declares only `androguard` as a dependency —
+**no JVM is required** (unlike the `asc` successor tooling in the upstream MG1937/ASC repository,
+which is a separate project). The console script is named **`droidasc`**, not `asc`: there is no
+`asc.exe` in `C:\Python314\Scripts`, and `asc --version` fails with
+`The term 'asc' is not recognized...`. `python -m droidasc` is the equivalent entry point.
+
+### 1.2 Subcommands
+
+```
+$ python -m droidasc --help
+usage: python.exe -m droidasc [-h]
+                              {getclass,listclass,getmanifest,findrefs} ...
+ASC tooling entry.
+positional arguments:
+  {getclass,listclass,getmanifest,findrefs}
+    getclass     Locate the target class in APK, extract one DEX in memory, then decompile.
+    listclass    List classes across all DEX entries; use --prefix to filter by package/class prefix.
+    getmanifest  Decode AndroidManifest.xml from APK and print it as XML.
+    findrefs     Find code references for string/type/method/field across all DEX entries in APK.
+examples:
+  droidasc app.apk --gui
+  droidasc getclass app.apk Lcom/poc/Main; -o Main.java
+  droidasc listclass app.apk --prefix com.poc
+  droidasc getmanifest app.apk -o AndroidManifest.xml
+  droidasc findrefs app.apk string token -o string_refs.txt
+```
+
+`--gui` and the bundled `asc_client` web UI were **not** exercised (unverified, headless pass).
+
+### 1.3 Measured against the sample
+
+```
+$ droidasc getmanifest <sample>.apk -o asc-manifest-verify.xml          # 0.44 s, 32,345 B
+<manifest ... package="com.example.app" platformBuildVersionCode="34" ... android:versionCode="1143"
+          android:versionName="0.9.0" android:compileSdkVersion="34" ...>
+  <uses-sdk android:minSdkVersion="19" android:targetSdkVersion="28"/>
+  <uses-permission android:name="android.permission.INTERNET"/>
+  ... (permissions list follows; manifest decodes cleanly)
+
+$ droidasc findrefs <sample>.apk string jiagu -o asc-findrefs-jiagu.txt  # 0.42 s
+classes.dex | Lcom/stub/StubApp;-><clinit> | matched=(libjiagu)
+classes.dex | Lcom/stub/StubApp;->attachBaseContext | matched=(/.jiagu; jiagu; jiagu_x86)
+
+$ droidasc getclass <sample>.apk com.stub.StubApp -o asc-StubApp-verify.java   # 0.33 s, 22,802 B
+package com.stub;
+public final class StubApp extends android.app.Application { ... }
+
+$ droidasc listclass <sample>.apk --prefix com.stub                       # 0.23 s
+Lcom/stub/StubApp;
+
+$ droidasc listclass <sample>.apk -o asc-listclass-all.txt                # 0.18 s, 4 lines
+Lcom/stub/StubApp;
+Lcom/tianyu/util/Configuration;
+Lcom/tianyu/util/DtcLoader;
+Lcom/tianyu/util/a;
+```
+
+`findrefs` reports the shell's own strings (`libjiagu`, `jiagu_x86`, `/.jiagu`) — i.e. the packer
+signature is visible without unpacking, but nothing of the application is.
+
+### 1.4 Limits hit
+
+```
+$ droidasc getclass <sample>.apk com.example.app.MainActivity -o asc-mainactivity.java
+Error: Class Lcom/example/app/MainActivity; not found in APK.
+exit = 1
+```
+
+**This is the limit that matters for this sample class:** the full class listing is 4 classes, so on
+a packed APK ASC is a manifest + shell-inspector, not an application decompiler. The application code
+lives in that shell's payload (`assets/`, the native unpacker and the AOT/Flutter layer), which ASC
+does not touch. ASC still earns its place in the flow: `getmanifest` in under half a second is the
+fastest manifest pass measured in this repository's tool set, and `findrefs` on shell class names is
+how the packer was identified here.
+
+Observed behaviours worth knowing: `droidasc` prints per-command timing nowhere, writes to `-o` only,
+and returns a clean `Error: ...` line plus exit 1 when a class is missing.
+
+---
+
+## 2. ddc — observed
+
+### 2.1 Version and acquisition
+
+```
+$ bin/ddc.exe -V
+ddc 0.1.8 — DEX → Java decompiler
+https://github.com/ejfkdev/ddc
+```
+
+`ddc` is a Rust binary (upstream: [ejfkdev/ddc](https://github.com/ejfkdev/ddc)); the Windows build
+used here is `tools/_work/t3-rpc/bin/ddc.exe`, 1,028,096 B, **not on `PATH`** and with no version
+resource in the PE header (`VersionInfo` empty), so `ddc -V` is the only way to learn its version.
+No JVM, no Python. Subcommands advertised by `ddc help`: `info`, `listclasses`, `manifest`,
+`mainactivity`, `res`, `strings`, `findrefs`, `callers`, `members`, `hierarchy`, `largest`, `disasm`,
+`getclass`, `getmethod`, plus a full-decompile mode (`ddc <INPUT>... [OUTPUT]`).
+
+### 2.2 Measured against the sample
+
+```
+$ bin/ddc.exe info <sample>.apk                                     # 0.24 s
+label        <label>
+package      com.example.app
+version      0.9.0 (1143)
+application  com.stub.StubApp
+launcher     com.example.app.MainActivity
+sdk          19–28
+size         36.9 MB (38688120 bytes)
+md5          1a037a045205184d4e8272092997334f
+
+     image       dex     classes     methods     fields     strings
+<sample>!classes.dex       035           4         266         23         481
+total: 1 image(s), 4 classes
+
+$ bin/ddc.exe findrefs <sample>.apk string jiagu                    # 0.13 s
+dex         kind          class method refs
+classes.dex  const-string  com/stub/StubApp <clinit>()V  "libjiagu"
+classes.dex  const-string  com/stub/StubApp attachBaseContext(...)V  "jiagu_x86"; "jiagu"; "/.jiagu"
+
+$ bin/ddc.exe strings <sample>.apk -f jiagu --with-locations        # 0.14 s
+dex         string  used-by
+classes.dex  "/.jiagu"  com/stub/StubApp attachBaseContext(Landroid/content/Context;)V
+classes.dex  "jiagu"  com/stub/StubApp attachBaseContext(Landroid/content/Context;)V
+classes.dex  "jiagu_x86"  com/stub/StubApp attachBaseContext(Landroid/content/Context;)V
+classes.dex  "libjiagu"  com/stub/StubApp <clinit>()V
+```
+
+`ddc info` reaches the same conclusion as ASC by a different route (class/method/string counts per
+dex image) and adds the resources-derived label and the launcher verification; `findrefs` output is
+tabular and one line per (method, string) pair, which is directly pasteable into a report.
+
+### 2.3 Limits hit
+
+```
+$ bin/ddc.exe getclass <sample>.apk com.example.app.MainActivity
+ddc: class com.example.app.MainActivity not found in the selected image(s)
+       (try `ddc listclasses <input> <pattern>`)
+exit = 2
+```
+
+Exit codes measured on this build: `info` → 0, `-V` → 0, `getclass` with a missing class → **2**.
+The missing-class path also reprints the full help text on stdout, so a wrapper that only checks
+"did anything print" will misread it as success — key off the exit code. As with ASC, the packed APK
+exposes only the shell dex; `ddc` cannot see application classes either, which is a property of the
+artifact, not of the tool.
+
+---
+
+## 3. Prior-attempt outputs under test — and the defects found
+
+`skills/apk-reverse/references/emulation-and-rpc.md`, `scripts/frida_rpc_serve.py` and
+`scripts/rpc_template.js` were already on disk from an interrupted attempt of this task. This pass
+read all three, ran the script, and fixed four defects. `rpc_template.js` needed no change.
+
+| # | Defect (observed) | Fix |
+|---|---|---|
+| 1 | `RpcBridge._teardown()` never detached the session and used `obj.off(...) if obj is self.session else None` / `obj.unload() if hasattr(obj, "unload")` — a script object has `unload()`, a session has `detach()`, so the expression released only the script. Every `reload()`/reconnect cycle leaked one attached session on the device. | Rewritten to unload the script, remove the `detached` handler and `session.detach()` explicitly. |
+| 2 | `list_exports()` called `Script.list_exports()`, which frida 16.7.19 answers with `DeprecationWarning: Script.list_exports will become asynchronous in the future, use the explicit Script.list_exports_sync instead` (printed on every `list` command). | Tries `list_exports_sync` first, then the old name, then local introspection. |
+| 3 | `--mode call` raised out of `main()`: an unknown export produced `frida`'s own `unable to find method 'x'` and a raw Python traceback; a bad `--args` value dumped a `JSONDecodeError` traceback. Scripted callers got a stack trace instead of a result. | `run_call_mode()` now returns one JSON object (`{"ok": false, "error": ...}`) and exit code 1 for both cases; `call()` consults the advertised export list first so the message is `no such rpc export: nope (available: add ping ...)`. |
+| 4 | `frida.TimedOutError` was absent from the retry whitelist. It is **not** a `TransportError` subclass (`frida.TimedOutError.__mro__` → `(TimedOutError, Exception, BaseException, object)`), so a device that timed out during attach produced a traceback in an otherwise recoverable situation — reproduced live (§4.4). | Retryable types are now collected by name into `RETRYABLE` (TransportError, NotSupportedError, ServerNotRunningError, ProcessNotFoundError, InvalidOperationError, TimedOutError) and used by both `ensure()` and the initial connect in `main()`. |
+
+Post-fix evidence:
+
+```
+$ python skills/apk-reverse/scripts/frida_rpc_serve.py --remote 127.0.0.1:27043 --pid 19938 \
+      --script skills/apk-reverse/scripts/rpc_template.js --mode call --export add --args "[40, 2]"
+{"ok": true, "export": "add", "result": 42}                       exit = 0
+$ ... --mode call --export nope
+{"ok": false, "export": "nope", "error": "no such rpc export: nope
+   (available: add ping getpackagename callnative callnativeaddr)"}   exit = 1
+$ ... --mode call --export add --args "not-json"
+{"ok": false, "error": "--args is not valid JSON: Expecting value: line 1 column 1 (char 0)"}
+                                                                   exit = 1
+```
+
+Known cosmetic behaviour left as is: in `--mode call` the bridge connects before `--args` is parsed,
+so a bad-args invocation still performs a device attach.
+
+## 4. Frida RPC against the live device — observed
+
+### 4.1 Attach path: by name fails, by pid works
+
+Attach **by package name** failed for every package tried, with the process demonstrably alive in
+both `frida-ps -Uai` and `ps -A`:
+
+```
+$ python ...frida_rpc_serve.py --device-serial <DEVICE> --package com.android.settings ...
+[bridge] connect failed (unable to find process with name 'com.android.settings'); retry 1 in 1.0s
+... (5 attempts) ...
+initial connect failed: could not (re)connect after 5 attempts
+$ python ... --package io.github.vvb2060.magisk ...
+[bridge] connect failed (unable to find process with name 'io.github.vvb2060.magisk'); retry 1 in 0.5s
+initial connect failed: could not (re)connect after 1 attempts
+```
+
+The same processes attach normally by pid:
+
+```
+$ python ... --pid 19938 --mode call --export getpackagename
+{"ok": true, "export": "getpackagename", "result": "com.android.settings"}
+$ python ... --pid 21493 --mode call --export getpackagename
+{"ok": true, "export": "getpackagename", "result": "com.android.email"}
+```
+
+So the gap is in the **name→pid lookup** the server serves, not in injection: `--pid` definitely
+does bypass it. `references/emulation-and-rpc.md` had claimed the opposite ("`--pid` does not bypass
+a gap that hides the process from the server's own table"); that row was corrected in this pass, and
+the corrected wording is what the reference now carries.
+
+### 4.2 The transport itself
+
+| # | Command (pid 19938 = `com.android.settings`, unrelated to the sample) | Result |
+|---|---|---|
+| 1 | `--mode call --export add --args "[40, 2]"` | `{"ok": true, "result": 42}` |
+| 2 | `--mode call --export ping` | `{"ok": true, "result": "pong"}` |
+| 3 | `--mode call --export getpackagename` | `{"ok": true, "result": "com.android.settings"}` |
+| 4 | `--mode call --export callnative --args '["libc.so","getpid","int",[],[]]'` | `{"ok": true, "result": 19938}` (matches the pid — `NativeFunction` wrapping works) |
+| 5 | `--mode repl`, feeding `list` / `reload` / `list` / `add [40, 2]` / `nope` | `add ping getpackagename callnative callnativeaddr`; `reloaded`; same list; `42`; `error: no such rpc export: nope (available: ...)` |
+| 6 | `--mode http`, `GET /exports` | `{"ok":true,"exports":[...5 names...]}` |
+| 7 | `--mode http`, `POST /call {"export":"add","args":[40,2]}` | `{"ok":true,"result":42}` |
+| 8 | `--mode http`, `POST /call {"export":"getpackagename","args":[]}` | `{"ok":true,"result":"com.android.settings"}` |
+| 9 | `--mode http`, `POST /call` with an unknown export | HTTP 502 + `{"ok":false,"error":"no such rpc export: nope (available: ...)"}` |
+| 10 | `--mode http`, `POST /reload` then `POST /call add [1,2]` | `{"ok":true}` then `{"ok":true,"result":3}` — the re-attach path works, and no `DeprecationWarning` is printed any more |
+| 11 | `--spawn --package io.github.vvb2060.magisk --mode call --export getpackagename` | `{"ok": true, "result": "io.github.vvb2060.magisk"}` (spawn → script load → resume → RPC) |
+
+Every script load also delivered the template's own liveness message:
+`[script] {"ev": "RPC-READY", "exports": ["add","ping","getpackagename","callnative","callnativeaddr"]}`.
+That line is the cheapest health check for a session and is worth grepping for in automation.
+
+### 4.3 The server's port moved under us
+
+Mid-pass, `--device-serial <DEVICE>` began failing on attach while `frida-ps -U` kept working:
+
+```
+$ python ... --device-serial <DEVICE> --pid 19938 ...
+[bridge] connect failed (unable to connect to remote frida-server: closed); retry 1 in 1.0s
+... (3 attempts) ...
+
+$ python -c "import frida;d=frida.get_device('<DEVICE>');d.attach(19938)"
+attach failed: ServerNotRunningError unable to connect to remote frida-server: closed
+
+$ adb -s <DEVICE> shell 'su -c "ps -A"' | Select-String 'svc16|frida'
+root  1876  1  2227684  55288  do_sys_poll  S  .svc16            # only this instance alive
+$ adb -s <DEVICE> shell 'su -c "netstat -ltnp"' | Select-String 2704
+tcp  0  0  0.0.0.0:27043  0.0.0.0:*  LISTEN  1876/.svc16          # nothing on 27042
+```
+
+The visible `frida-server` process (pid 23405) was gone; a disguised copy (`.svc16`, pid 1876) was
+listening on **27043 only**. `frida-ps -U` still worked because frida's USB transport probes a range
+of ports, while the scripted device-serial path landed on a dead default port. Recovery, with the
+forward already present (`adb forward --list` shows `tcp:27043 tcp:27043`):
+
+```
+$ python ... --remote 127.0.0.1:27043 --pid 19938 --mode call --export getpackagename
+{"ok": true, "result": "com.android.settings"}
+```
+
+This pass neither started nor killed any server instance; it only observed that the instance changed
+and switched to the explicit `--remote` form. That form is now the recommended one in the reference's
+failure table.
+
+### 4.4 A third-party process that refuses the handshake
+
+```
+$ python ... --remote 127.0.0.1:27043 --pid 19984 --mode call --export getpackagename
+frida.TimedOutError: unexpectedly timed out while waiting for signal from process with PID 19984
+```
+
+An ordinary third-party app process (`com.xunmeng.pinduoduo`, listed by `frida-ps -Uai`) simply did
+not answer the agent handshake within frida's timeout. Pre-fix this surfaced as a traceback; post-fix
+the bridge treats it as retryable and reports `initial connect failed: ...` with exit 2. This is an
+app-side property, not a bridge property — for connectivity probes prefer a system or stable app
+process.
+
+### 4.5 Device state after the pass
+
+`frida-ps -U` and `frida-ps -Uai` both still answer; the sample's process was never touched; the
+device-side server was never killed or restarted by this pass.
+
+---
+
+## 5. unidbg — observed (build/boot) and unverified (target emulation)
+
+### 5.1 Build
+
+```
+$ git clone --depth 1 https://github.com/zhkl0228/unidbg.git      # version 0.9.10-SNAPSHOT
+$ .\mvnw.cmd -B -pl unidbg-android -am -DskipTests compile
+Error: JAVA_HOME not found in your environment.                   # JAVA_HOME was unset on this host
+...
+[ERROR] Failed to execute goal ...maven-compiler-plugin:3.3:compile on project unidbg-api:
+[ERROR] .../AbstractARMDebugger.java:[79,43] reference to Module is ambiguous
+[ERROR]   both com.github.unidbg.Module and java.lang.Module match
+```
+
+The shipped pom pins `<source>8</source><target>8</target>` with `maven-compiler-plugin` 3.3. On
+JDK 9+ that pair does **not** select the JDK 8 API, so `java.lang.Module` stays visible and every
+unqualified `Module` in `AbstractARMDebugger` becomes ambiguous — the build dies in `unidbg-api`.
+Two local work-copy changes fix it (recorded in `tools/_work/t3-rpc/unidbg/pom.xml`, not part of the
+skill and not committed):
+
+```
+maven-compiler-plugin 3.3   -> 3.8.1        # 3.13 is rejected: the bundled wrapper is Maven 3.5.4,
+                                            # and 3.13 requires Maven >= 3.6.3
+<source>8</source><target>8</target> -> <release>8</release>   # hides java.lang.Module
+```
+
+Result with `JAVA_HOME=C:\Program Files\Java\jdk-17.0.4.1`:
+
+```
+$ .\mvnw.cmd -B -pl unidbg-android -am -DskipTests compile
+[INFO] unidbg-api ......... SUCCESS [ 40.838 s]
+[INFO] unidbg-android ..... SUCCESS [  4.941 s]
+[INFO] BUILD SUCCESS  (total 48.4 s, after a one-off dependency download)
+```
+
+### 5.2 Boot check
+
+The pom sets `<maven.test.skip>true</maven.test.skip>`, so `-Dmaven.test.skip=false` is required to
+run anything:
+
+```
+$ .\mvnw.cmd -B -pl unidbg-android -am -Dmaven.test.skip=false \
+      -Dtest=MemoryTrackerTest -DfailIfNoTests=false test
+Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
+Backend: DynarmicBackend64
+=== Memory Leak Report === ... Address: 0x12000000, Size: 4096 ...
+[INFO] BUILD SUCCESS
+```
+
+This proves the toolchain end to end at the *environment* level: emulator construction, memory
+allocator, backend selection (Dynarmic, with Hypervisor and Unicorn2 factories registered) and
+Android 11 (`AndroidResolver(23)`-style) library resolution all execute on this host.
+
+### 5.3 What was **not** done — unverified
+
+* Loading and calling **any** target `.so`, including this sample's `libjiagu*.so` or `libapp.so`.
+  No `createDalvikVM`, `loadLibrary`, `callJNI_OnLoad` or `AbstractJni` stub was exercised.
+* Consequently every per-library statement in `references/emulation-and-rpc.md` §Part A — which JNI
+  callbacks a hardened library demands, how many stub rounds it costs, which `/proc` or signature
+  checks it runs — remains **inferred** from the library's shape and community practice. The
+  reference's "Measured here" section was rewritten in this pass to say exactly that.
+* Note for anyone porting an older tutorial: `emulator.createCode()` / the `Assembly` helper class
+  do **not** exist in 0.9.10-SNAPSHOT (no `Assembly*.java` under the tree, no `createCode` symbol in
+  any module). Recipes that assemble raw ARM machine code through that API need the current
+  backend/JNI entry points instead.
+* `unidbg-android`'s bundled demos (`TTEncrypt`, `SignUtil`, `QDReaderJni`, …) each expect their own
+  `.so`/APK to be placed first; none were run, so the demo names in the reference are pointers, not
+  verified commands.
+
+---
+
+## 6. Consolidated list of things that did **not** work (for the pass summary)
+
+1. Attach by package name on this ROM (both `com.android.settings` and `io.github.vvb2060.magisk`
+   failed while listed by `frida-ps -Uai`). Workaround: pid, from `frida-ps -U` / `pidof`.
+2. Device-serial attach once the device's server came back on 27043 — `ServerNotRunningError:
+   unable to connect to remote frida-server: closed`. Workaround: `adb forward` + `--remote`.
+3. Attach by pid to `com.xunmeng.pinduoduo` — `frida.TimedOutError`; the process never answered the
+   handshake.
+4. `asc` as a command name (the console script is `droidasc`), and `mvnw` without `JAVA_HOME`.
+5. unidbg out of the box on JDK 17 (`Module` ambiguity) and unidbg tests out of the box
+   (`maven.test.skip=true`).
+6. Application-class decompilation of a packed APK by either ASC or ddc (nothing to fix — the dex
+   simply is not there; this is the case that justifies the whole emulation/RPC route).
+
+## 7. Artifacts produced by this pass
+
+`tools/_work/t3-rpc/` (not committed): `asc-manifest-verify.xml`, `asc-StubApp-verify.java`,
+`asc-listclass-all.txt`, `asc-listclass-stub.log`, `asc-getmanifest.log`, `asc-findrefs.log`,
+`asc-findrefs-jiagu.txt`, `asc-getclass.log`, `ddc-info-verify.txt`, `ddc-findrefs-jiagu.txt`,
+`ddc-strings-jiagu.txt`, `rpc-*.log` (one per command in §4), `bin/ddc.exe`, `unidbg/` (patched work
+copy).
+
+Files changed in the repository by this pass: `references/emulation-and-rpc.md` (corrected failure
+table, corrected unidbg build recipe, corrected "Measured here" labelling, and a stale section
+reference repointed to `SKILL.md` §Stop conditions) and `scripts/frida_rpc_serve.py` (the four fixes
+in §3).
diff --git a/docs/tool-verification/EXTENSION-kernel-ondevice.md b/docs/tool-verification/EXTENSION-kernel-ondevice.md
new file mode 100644
index 0000000..43d59b7
--- /dev/null
+++ b/docs/tool-verification/EXTENSION-kernel-ondevice.md
@@ -0,0 +1,121 @@
+# Extension verification — kernel/environment hardening + on-device tooling
+
+Covers the 2026-09 extension pass that added `references/kernel-and-environment-hardening.md`,
+`references/on-device-tooling.md` and `scripts/mt_mcp_probe.py`. Strength labels as defined in
+this directory's README: **observed** (exact command + output here), **inferred** (follows from
+observed facts, step not executed), **unverified** (assumed or externally reported, not
+independently confirmed).
+
+Reference environment for this pass: rooted physical device, Android 11 (API 30), arm64-v8a,
+kernel **4.14.186**, Magisk alpha + Zygisk, LSPosed v1.9.2 activated, Zygisk-Assistant v2.1.4
+and MoveCertificate v1.6.2 installed (pending reboot merge), MT Manager 2.26.9 installed.
+
+---
+
+## 1. MT APK MCP probe — measured
+
+### 1.1 `scripts/mt_mcp_probe.py` runs and reports correctly
+
+`--help` works (argparse, three options). Observed:
+
+```
+$ python skills/apk-reverse/scripts/mt_mcp_probe.py --help
+usage: mt_mcp_probe.py [-h] [--url URL] [--timeout TIMEOUT] [--json]
+```
+
+Full **observed** output of the probe in the service-down state, with the port forward in place:
+
+```
+$ adb forward --list
+<serial> tcp:8787 tcp:8787
+<serial> tcp:8651 tcp:8651
+<serial> tcp:65534 tcp:65534
+
+$ python skills/apk-reverse/scripts/mt_mcp_probe.py
+[waiting] MCP server is not answering at http://127.0.0.1:8787/mcp
+The MT APK MCP must be started by hand in the MT UI (adb cannot start it):
+  1. On the phone: MT Manager -> side drawer -> Tools -> APK MCP -> Start
+  ...
+exit code 2
+```
+
+The failure was localised to the service (not the transport) on the device side — **observed**:
+
+```
+$ adb -s <serial> shell "su -c 'netstat -tln | grep 8787 || echo NOT_LISTENING'"
+NOT_LISTENING
+```
+
+So at pass time: port forward alive, device reachable, MT's MCP service not started in the MT UI
+(it requires a manual start that adb cannot perform). The script's designed degraded-mode
+behaviour (waiting instructions + exit 2) is therefore **verified by observation**; the online
+path (initialize handshake → grouped `mt_apk_*` inventory) is **unverified on this device** — it
+was not exercised because the service was never started during the pass. The JSON-RPC shape
+(initialize with `protocolVersion 2024-11-05`, `notifications/initialized`, `tools/list`,
+`Accept: application/json, text/event-stream`) follows the MCP Streamable HTTP specification and
+MT's documented transport; treat the exact response parsing as inferred until a live run.
+
+### 1.2 What was deliberately not done
+
+No attempt was made to start MT's MCP from adb (documented as impossible), and no scripted
+tap-driver was built to press the UI button — that is a human step. The probe script doubling as
+a "wait until up" check (exit 2 → retry after manual start) is the supported loop.
+
+## 2. Phone-module environment — observed earlier, cited here
+
+These facts were measured in the prior configuration pass and archived in
+`tools/_phone-modules/README-手机模块环境.md` and `README-MCP与网络环境.md`; this pass cites them
+rather than re-measuring. They count as **observed** (exact commands and outputs exist in those
+archives):
+
+- LSPosed v1.9.2 (7024) activation: log lines `ZygiskCompanion: welcome to LSPosed!`, version
+  banner, `lspd` daemon running as system, manager UI reporting activated.
+- Zygisk requires one reboot after enable before `/data/adb/zygisk` exists; modules install to
+  `/data/adb/modules_update/` and merge into `/data/adb/modules/` only on reboot.
+- Shamiko v1.2.5 kept as backup, **not** installed — documented conflict with Zygisk-Assistant
+  (both do root hiding); Zygisk-Assistant chosen because it does not depend on DenyList
+  enforcement.
+- mcp-termux / stackplz eBPF route closed on this device: requires kernel 5.10+, device has
+  4.14.186; its bundled kmodules ship only 5.10/5.15/6.1/6.6/6.12 variants.
+- MT Manager 2.26.9 installed; MCP port confirmed as 8787 in MT settings; forwards 8787/8651/
+  65534 established.
+
+## 3. Kernel-level content — unverified / inferred, with sources
+
+No kernel-level mechanism in `kernel-and-environment-hardening.md` was executed, on this device
+or any other. Specifically **unverified here**: eBPF kprobe/uprobe tracing, seccomp-BPF
+installation into a target, KPM/LKM hooking, self-ptrace anti-anti-debug, and every hiding claim
+of Shamiko / Zygisk-Assistant against a real detector (the module archives also record that
+hiding was never validated against an actual detection scenario).
+
+The **inferred** claims that carry external sources (fetched 2026-09, URLs in the reference
+file):
+
+| Claim | Source |
+|---|---|
+| KernelSU: kernel-based su, official support GKI 2.0 = kernel 5.10+ (Android 12-era), backport to 4.14 requires self-built kernel; module system conflicts with Magisk magic mount; su-only coexistence possible (kernel vs ramdisk patching) | tiann/KernelSU README + FAQ (github.com) |
+| APatch: KernelPatch patches stock boot.img kernel (no kernel source needed — the difference from KernelSU); SuperKey-gated SuperCall syscall; KPM kernel-space modules with inline/syscall-table hooks; SELinux hooked not rewritten; Shamiko officially unsupported | apatch.dev FAQ |
+| Shamiko: reads Magisk denylist but requires DenyList enforcement OFF; whitelist mode via `/data/adb/shamiko/whitelist` with documented performance cost | Shamiko README (LSPosed distribution) |
+| Zygisk-Assistant: Magisk use = target on denylist + Enforce OFF; KernelSU/APatch use = ZygiskNext + "Umount modules/Exclude modifications" | snake-4/Zygisk-Assistant README |
+| GKI 2.0 starts at android12-5.10; eBPF extension docs target GKI kernels | source.android.com (kernel architecture section) |
+
+The version gate consequence (eBPF row closed on 4.14) is **observed** for this device (uname)
+and **inferred** as a general gate from the GKI sources above.
+
+## 4. Not run / open items
+
+- Live MCP handshake: blocked on a human UI action (start APK MCP in MT). The probe script is
+  ready; re-run and record the real `initialize` + `tools/list` output when it happens.
+- Zygisk-Assistant + MoveCertificate merge: pending the device reboot recorded in the module
+  archive; their post-merge behaviour is untested.
+- No LSPosed hook module was built or run against a real target in either pass — the framework
+  is activated (observed), the module workflow remains inferred.
+
+## 5. Reproduction one-liners
+
+```
+python skills/apk-reverse/scripts/mt_mcp_probe.py            # probe + inventory or waiting help
+adb forward --list                                           # confirm 8787 forward exists
+adb -s <serial> shell "su -c 'netstat -tln | grep 8787'"     # device-side listen check
+adb -s <serial> shell uname -r                                # the 4.14 kernel gate, observed
+```
diff --git a/docs/tool-verification/EXTENSION-lsposed.md b/docs/tool-verification/EXTENSION-lsposed.md
new file mode 100644
index 0000000..a6e646e
--- /dev/null
+++ b/docs/tool-verification/EXTENSION-lsposed.md
@@ -0,0 +1,567 @@
+# Extension verification — LSPosed module route
+
+Covers the 2026-09 extension pass that added `skills/apk-reverse/references/lsposed-and-modules.md`
+and `skills/apk-reverse/scripts/lsposed_scaffold.py`. Strength labels as defined in this directory's
+README: **observed** (exact command + output here), **inferred** (follows from observed facts, step
+not executed), **unverified** (assumed or externally reported, not independently confirmed).
+
+Reference environment for this pass: rooted physical device, Android 11 (API 30), arm64-v8a,
+Magisk alpha + Zygisk, LSPosed v1.9.2 (7024) activated, Zygisk-Assistant v2.1.4 installed, MT Manager
+2.26.9 installed, one hardened Flutter sample installed (referred to below as *the sample*; no target
+identity is recorded here). Host: Windows, JDK 17.0.4.1, Android build-tools 34.0.0, API 28
+`android.jar`, Xposed `api-82` stub jar.
+
+**Identifier convention:** every occurrence of the sample's package identifier in the transcripts
+below is normalized to `<PKG>` (`<PKG>.MainActivity`, `<PKG>.BaseApplication`), and its sub-package
+prefixes are shortened the same way. The transcripts are otherwise verbatim, including the class
+names a hook reported — those are what make the evidence checkable.
+
+This pass closes an item left open by the previous extension record, which noted that "no LSPosed hook
+module was built or run against a real target" (`EXTENSION-kernel-ondevice.md` §4). The build half is
+now **observed**; the injection half is **partially observed** and the gap is stated in §6.
+
+---
+
+## 1. Scaffold script — observed
+
+### 1.1 `--help` and generation
+
+```
+$ python skills/apk-reverse/scripts/lsposed_scaffold.py --help
+usage: lsposed_scaffold.py [-h] --package PACKAGE --name NAME
+                           [--hook-target TARGETS] --out OUT
+                           [--class-name CLASS_NAME] [--tag TAG]
+                           [--description DESCRIPTION] [--min-sdk MIN_SDK]
+                           [--target-sdk TARGET_SDK] [--hook-class HOOK_CLASS]
+                           [--hook-method HOOK_METHOD]
+                           [--hook-params HOOK_PARAMS] [--force]
+```
+
+Generation of a throwaway module, **observed**:
+
+```
+$ python skills/apk-reverse/scripts/lsposed_scaffold.py \
+      --package com.example.probe --name "Example probe" \
+      --hook-target com.example.target \
+      --hook-class com.example.target.Helper --hook-method check \
+      --hook-params "java.lang.String" --out <work>/scaffold-gen
+[+] <work>/scaffold-gen/AndroidManifest.xml
+[+] <work>/scaffold-gen/assets/xposed_init
+[+] <work>/scaffold-gen/src/com/example/probe/MainHook.java
+[+] <work>/scaffold-gen/README.md
+```
+
+`assets/xposed_init` contains exactly one line, `com.example.probe.MainHook` (**observed**). Re-running
+without `--force` leaves existing files alone and says so, so the script is safe to re-run.
+
+### 1.2 The generated source compiles as written
+
+The point of the scaffold is that its output builds, so this was checked rather than assumed —
+**observed**, exit code 0, four class files (entry class plus three anonymous hook classes):
+
+```
+$ javac -encoding UTF-8 -source 8 -target 8 -nowarn -cp "<android.jar>;<api-82.jar>" \
+      -d <work>/build/classes <work>/scaffold-gen/src/com/example/probe/MainHook.java
+$ echo $?
+0
+MainHook.class  MainHook$1.class  MainHook$2.class  MainHook$3.class
+```
+
+## 2. Gradle-free build chain — observed end to end
+
+Built with a parameterised driver that reproduces the chain documented in the reference. Times are
+wall-clock on the host above; the module is one class.
+
+| Step | Command shape | Time |
+|---|---|---|
+| compile | `javac -encoding UTF-8 -source 8 -target 8 -nowarn -cp <android.jar>;<api-82.jar> -d build/classes src/**/*.java` | 850 ms |
+| jar | `jar cf build/classes.jar -C build/classes .` | 259 ms |
+| dex | `d8.bat --min-api 24 --lib <android.jar> --output build build/classes.jar` | 1143 ms |
+| link | `aapt2.exe link -o build/base.apk -I <android.jar> --manifest AndroidManifest.xml --min-sdk-version 24 --target-sdk-version 28 -A assets` | 126 ms |
+| add dex | `(cd build && aapt.exe add unsigned.apk classes.dex)` | 97 ms |
+| align | `zipalign.exe -f -p 4 build/unsigned.apk build/aligned.apk` | 76 ms |
+| sign | `apksigner.bat sign --ks build/test.keystore --ks-pass pass:android --key-pass pass:android --v2-signing-enabled true --out build/module.apk build/aligned.apk` | 1794 ms |
+| verify | `apksigner.bat verify --min-sdk-version 24 --print-certs build/module.apk` | 725 ms |
+| | **total** | **5.27 s** |
+
+Resulting artifact, **observed**: `module.apk` 12,745 bytes, `classes.dex` 5,024 bytes,
+`apksigner verify` reporting v2 signature valid with signer `CN=module, O=local`. APK entry list
+(**observed**, read back with zipfile):
+
+```
+AndroidManifest.xml   1680
+resources.arsc          40
+assets/xposed_init      27
+classes.dex           5024
+META-INF/MANIFEST.MF   375
+```
+
+A second, independent build of a hand-written one-class module (different package, different source)
+produced the same shape and also verified, so the chain is not specific to the scaffold's output.
+
+### 2.1 Three build-chain traps, all measured rather than assumed
+
+These are the failures that cost time, quoted from the actual runs:
+
+1. **`d8` rejects a directory as program input.** Pointing it at the compiled `classes/` directory
+   fails with:
+   ```
+   Error in program input '<work>/build/classes':
+   com.android.tools.r8.internal.Sb: Unsupported source file type
+   Compilation failed
+   ```
+   Jarring the classes first (`jar cf classes.jar -C classes .`) and passing the jar succeeds. This is
+   the opposite of what several command-line guides imply.
+2. **`aapt add` fails with `Unable to add 'classes.dex' to 'unsigned.apk': file not found`** when the
+   dex is not in the current working directory. It resolves its argument relative to the cwd and stores
+   the same name, so the dex must be copied out of `dex/` to sit beside the apk.
+3. **`jar` and `keytool` are not on `PATH` even where `javac` is.** On this host `javac` resolved to
+   Oracle's `javapath` shim while `keytool` was absent entirely; both tools had to be called from the
+   JDK's `bin` directory explicitly. A build script that assumes they are on `PATH` breaks on a
+   working machine.
+
+Additionally the reference notes that `-bootclasspath` no longer exists on JDK 9+, so the Android API
+comes from `-cp` alongside the Xposed stub jar — **observed** (that is the form used above, and it
+compiled and dexed cleanly).
+
+## 3. Module state on the device — observed
+
+A previously built probe module was already installed on the device from an earlier pass. Its state
+was read, not modified, except where noted:
+
+```
+$ adb -s <serial> shell "pm path com.t1.lsphook"
+package:/data/app/~~<hash>==/com.t1.lsphook--<hash>==/base.apk
+
+$ adb -s <serial> shell "dumpsys package com.t1.lsphook | grep -E 'User 0|enabled'"
+    User 0: ceDataInode=35322 installed=true ... stopped=true notLaunched=true enabled=0 ofs=0 ...
+```
+
+`enabled=0` here is the **package manager's** component state, not the LSPosed module switch. Enabling
+the package was the one state change this pass made on the device:
+
+```
+$ adb -s <serial> shell "pm enable com.t1.lsphook"
+Package com.t1.lsphook new state: enabled
+$ adb -s <serial> shell "dumpsys package com.t1.lsphook | grep 'User 0'"
+    User 0: ... enabled=1 ...
+```
+
+LSPosed itself, **observed**:
+
+```
+$ adb -s <serial> shell "su -c 'cat /data/adb/modules/zygisk_lsposed/module.prop'"
+id=zygisk_lsposed
+name=Zygisk - LSPosed
+version=v1.9.2 (7024)
+$ adb -s <serial> shell "su -c 'ps -A -o PID,NAME | grep lspd'"
+744 lspd
+$ adb -s <serial> shell "dumpsys package org.lsposed.manager | grep versionName"
+    versionName=1.9.2
+```
+
+### 3.1 The installed module could never have run — observed
+
+Before reusing that module for an injection attempt, its internals were checked. `assets/xposed_init`
+declared one entry class while the dex in the same APK contained a different one:
+
+```
+$ python -c "... zipfile.ZipFile('installed-module.apk').read('assets/xposed_init') ..."
+com.t1.lsphook.MainHook
+
+$ dexdump -f installed.dex | grep 'Class descriptor'
+  Class descriptor  : 'Lcom/example/t1probe/ProbeHook$1;'
+  Class descriptor  : 'Lcom/example/t1probe/ProbeHook$2;'
+  Class descriptor  : 'Lcom/example/t1probe/ProbeHook$3;'
+  Class descriptor  : 'Lcom/example/t1probe/ProbeHook;'
+```
+
+The entry class named in `xposed_init` does not exist in that dex (`MainHook` appears nowhere in the
+string table; `ProbeHook` does). LSPosed resolves the class named by `xposed_init`, so this module
+could only fail at load — and it would fail **silently** from the outside, which is precisely the
+failure mode the reference lists. Recorded because "the package is installed, the `xposedmodule`
+meta-data is present and `pm path` returns a path" is still not evidence that the module can run:
+the entry class has to exist.
+
+Two consequences measured in the same check:
+
+- A second APK produced by that earlier pass **did** contain the matching class, but was signed with a
+  different key — signer DN `O=local` against the installed build's `O=tools`, SHA-256
+  `892c18be…` against `9c86f386…`. Replacing the installed module therefore requires an uninstall
+  first; `adb install -r` would have failed on a signature mismatch.
+- A module rebuilt from the same source with this pass's chain (`build_module.ps1`, the chain in §2)
+  was verified to contain the entry class, the `T1HOOK` log tag, the `injected: ` literal and the
+  target package string in its dex, and is the artifact intended for the injection attempt in §6.
+  Building it took 5.07 s and produced 12,745 bytes.
+
+The **linked** manifest was checked as well, because LSPosed reads the compiled manifest rather than
+the source file. `aapt2 dump xmltree <apk> --file AndroidManifest.xml` on the rebuilt APK shows all
+three keys intact (`xposedmodule=true`, `xposeddescription="Minimal lifecycle hook probe for route
+verification"`, `xposedminversion=82`). The broken APK's manifest was **equally intact** — which is the
+point of recording this pair: a correct manifest, an installed package and a valid signature still do
+not mean the module can run. Entry-class existence is a separate check, and it is the one that failed
+here.
+
+### 3.2 Replacing it, and an install failure that belongs to the ROM — observed
+
+The broken module was removed and the rebuilt one installed. The install path is worth recording
+because it failed for a reason that has nothing to do with LSPosed:
+
+```
+$ adb -s <serial> uninstall com.t1.lsphook
+Success
+$ adb -s <serial> install module.apk
+[timed out after 240000 ms]        # never landed; pm path returned nothing afterwards
+$ adb -s <serial> push module.apk /data/local/tmp/<work>/module.apk
+$ adb -s <serial> shell "pm install -r /data/local/tmp/<work>/module.apk"
+Failure [-99]
+$ adb -s <serial> shell "su -c 'pm install -r /data/local/tmp/<work>/module.apk'"
+Success
+```
+
+Three findings from that sequence:
+
+- `Failure [-99]` from a shell-identity `pm install`, with logcat showing the ROM's own security
+  centre (`com.coloros.safecenter`) taking the foreground from `com.android.packageinstaller` at the
+  same moment. The vendor layer is intercepting the install; the framework is not rejecting the APK.
+- The same APK installs without complaint as **root**. That is the working path on this ROM, and the
+  one used here.
+- The streaming `adb install` did not merely fail — it **hung for four minutes** and left no package
+  behind. Retrying as root is cheaper than waiting that out.
+
+Installed state afterwards, **observed**:
+
+```
+$ adb -s <serial> shell "pm path com.t1.lsphook"
+package:/data/app/~~c7aQQNK-GiP3BKd1g1iEvw==/com.t1.lsphook-<hash>/base.apk
+$ adb -s <serial> shell "pm enable com.t1.lsphook"
+Package com.t1.lsphook new state: enabled
+$ adb -s <serial> shell "dumpsys package com.t1.lsphook | grep 'User 0'"
+    User 0: ... installed=true ... enabled=1 ...
+```
+
+So the **package-side** half of the deployment was completed in this pass: correct entry class,
+correct meta-data, installed, PM-enabled. The scope half did not happen, for the reason in §6.
+
+## 4. Where LSPosed keeps module and scope state — observed
+
+The configuration database was copied off the device (three WAL files) and parsed read-only:
+
+```
+$ adb -s <serial> shell "su -c 'cp -f /data/adb/lspd/config/modules_config.db* /data/local/tmp/<work>/'"
+$ adb -s <serial> pull /data/local/tmp/<work> ...
+```
+
+Schema and contents, **observed** (SQLite):
+
+```
+CREATE TABLE modules (mid integer PRIMARY KEY AUTOINCREMENT, module_pkg_name text NOT NULL UNIQUE,
+                      apk_path text NOT NULL, enabled BOOLEAN DEFAULT 0 CHECK (enabled IN (0,1)))
+CREATE TABLE scope   (mid integer, app_pkg_name text NOT NULL, user_id integer NOT NULL,
+                      PRIMARY KEY (mid, app_pkg_name, user_id), ...)
+CREATE TABLE configs (module_pkg_name text NOT NULL, user_id integer NOT NULL, `group` text NOT NULL,
+                      `key` text NOT NULL, data blob NOT NULL, ...)
+
+== table modules ==
+  (1, 'lspd', '/data/adb/modules/zygisk_lsposed/manager.apk', 0)
+  (2, 'com.t1.lsphook', '/data/app/~~<hash>==/com.t1.lsphook--<hash>==/base.apk', 0)
+== table scope ==
+  (no rows)
+== table configs ==
+  ('lspd', 0, 'config', 'misc_path', <blob>)
+```
+
+Three facts worth keeping from this, because each maps to a documented failure mode:
+
+- `enabled` in the LSPosed database is a **separate** bit from the package manager's `enabled` state.
+  Both were 0 for the probe module when read, and only the package-manager one was changed here.
+- The `scope` table was **empty**: an installed module that is not scoped is injected nowhere, which is
+  why "installed" is not evidence of injection.
+- `sqlite_sequence.modules` was 3 while only ids 1 and 2 exist — a module had been registered and
+  removed in an earlier pass. The ids are not a count of what is loaded.
+
+## 5. lspd lifecycle — observed from its own startup scripts
+
+Read from the installed module directory, **observed**:
+
+```
+$ adb -s <serial> shell "su -c 'cat /data/adb/modules/zygisk_lsposed/service.sh'"
+...
+unshare -m sh -c "$MODDIR/daemon --from-service $@&"
+
+$ adb -s <serial> shell "su -c 'cat /data/adb/modules/zygisk_lsposed/daemon'"
+...
+exec /system/bin/app_process $java_options /system/bin --nice-name=lspd org.lsposed.lspd.Main "$@"
+```
+
+`service.sh` is Magisk's late-start service script, which runs once per boot. **Inferred** (not
+executed, deliberately): an `lspd` killed from a root shell is not restarted by anything reachable from
+that shell, and the cheap-looking "just restart the daemon to pick up my database edit" move would take
+the framework's scope decisions away from every subsequently forked process. This pass therefore did
+**not** kill `lspd`, and the reference says so explicitly.
+
+Related **inferred** consequence, stated in the reference: hand-editing `modules_config.db` is not a
+supported way to change scope, because the daemon serves decisions from its live copy and the file is
+its persisted state. The manager path updates both.
+
+## 6. Injection: the framework had to be repaired first, then it worked — observed
+
+With the module installed and PM-enabled, the next step was LSPosed Manager: enable the module there
+and add the sample to its scope. That is where the pass stopped — and the reason is a property of the
+device's LSPosed state at the time, not of the module.
+
+Manager opened normally but reported the framework as **not installed**. Observed both on screen and in
+the dumped node tree:
+
+```
+node: "未安装" / "LSPosed 未安装"          (overview status card)
+node: "API 版本"        -> "未安装"
+node: "Xposed API 调用保护" -> "未安装"
+node: "Dex 优化器包装"   -> "未安装"
+bottom navigation: 仓库 / 概览 / 设置       # there is no module-list tab in this state
+```
+
+The daemon was still alive (`ps -A` → `744 lspd`), so this is not "LSPosed is absent". Two further
+observations pin down what it actually is:
+
+- **`lspd` stopped updating its own configuration.** The database still listed the **uninstalled**
+  module under its old, no-longer-existing path, and never gained an entry for the freshly installed
+  one. Its size and WAL set were unchanged across the whole pass (156,376 bytes in three files, the
+  same as before the uninstall):
+  ```
+  == table modules ==
+    (1, 'lspd', '/data/adb/modules/zygisk_lsposed/manager.apk', 0)
+    (2, 'com.t1.lsphook', '/data/app/~~wiGaHYIZn5j3Am2JrJvA5g==/com.t1.lsphook-<hash>/base.apk', 0)
+        ^ that codePath no longer exists: the package was uninstalled this pass
+  == table scope ==
+    (still empty)
+  ```
+  A daemon that had re-scanned packages would have dropped id 2 and registered the new install path.
+- **Its log records the framework bridge dying and never recovering.** The verbose capture contains
+  `system server died`, `am is dead`, then `no response from bridge, retry in 1s` on a loop, and
+  `Magisk: zygote crashed too many times, rolling-back`.
+
+`[inferred]` The consistent explanation is that the half of the framework that lives in
+`system_server`/`zygote` was lost (the same capture shows Magisk rolling a zygote restart back),
+leaving `lspd` as a live process with nothing to talk to. Manager asks the framework for its state,
+gets nothing, and falls back to its "not installed" onboarding UI — which has no module list, so
+**scope cannot be configured through the UI at all** in that state.
+
+Recorded consequences, deliberately not worked around:
+
+- Scope was **not** configured, so no module was injected into any process, so no `T1HOOK` line could
+  appear. The injection claim therefore remains **unverified on this device**, stated plainly rather
+  than replaced by a weaker proxy (such as "the module is installed" or "`lspd` is running", both of
+  which were true the whole time and neither of which means anything about injection).
+- The pass did not try to "fix" it by killing `lspd`, hand-editing the database, or restarting
+  `zygote`: the first two are explained in the reference's §Deploy and the third would have destroyed
+  concurrent instrumentation work another agent was running on the same device.
+- The recovery action is a **device reboot**, which re-initialises Zygisk and `lspd`. It was not taken
+  because the device was shared and under heavy load. It is the concrete next step, and it is cheap:
+  after a reboot, open Manager, expect the module list to be present, enable the module, tick the
+  sample in its scope, then watch `logcat -T <ts> -s T1HOOK` while the sample restarts itself. Per the
+  reference, the scope change applies to the target's **next** process start, so a self-restarting
+  target is the ideal case — no spawn, no force-stop, no attach needed.
+- Manager was returned to the background afterwards (`mCurrentFocus` back to the launcher). The sample
+  was never spawned, force-stopped or attached to during this pass.
+
+### 6.1 The repair — observed
+
+A reboot was approved and taken. It is the whole fix, and it is cheap:
+
+```
+$ adb -s <serial> reboot
+[  0 s] boot_completed=''      ... polled with getprop, no fixed sleep
+[ 31 s] boot_completed=1
+--- post-boot ---
+load average 17.40 4.37 1.46          (was 29.58 31.87 33.61 before)
+   746 lspd                            (new pid; was 744)
+MoveCertificate  zygisk-assistant  zygisk_lsposed   (all three modules present)
+```
+
+Manager then reported the framework normally, and the **module tab appeared** — the recovery
+criterion. Observed on the overview page: `已激活 / 1.9.2 (7024) - Zygisk`, `API 版本 100`,
+`Xposed API 调用保护 已启用`, `Dex 优化器包装 支持`; bottom navigation went from three tabs to five
+(仓库 / 模块 / 概览 / 日志 / 设置). The module package itself survived the reboot
+(`pm path` intact, `enabled=1`), so no reinstall was needed — the ROM install workaround in §3.2 only
+matters on a fresh install.
+
+### 6.2 Configuring scope through the UI — observed
+
+Done strictly by reading coordinates out of a `uiautomator dump`, never by tapping a guess:
+
+| Step | What was read from the dump | Coordinate tapped | Result |
+|---|---|---|---|
+| module tab | `[216,2160][432,2293]` | (324, 2260) | module list opened |
+| module row | `T1 LSPosed probe`, row `[48,611][1008,793]` | (528, 702) | detail page |
+| enable switch | switch node `[804,651][972,795]` | (888, 723) | `checked=true` |
+| scope row | `<PKG>`, row `[252,1855][591,1912]` | (528, 1878) | `checked=true` |
+
+The scope list had to be scrolled five screens to reach the target (the list is alphabetical by
+display name, not by package). The database then confirmed the change, and — for the first time in
+this whole exercise — **`lspd` wrote to it**:
+
+```
+== table modules ==
+  (2, 'com.t1.lsphook', '/data/app/~~c7aQQNK-GiP3BKd1g1iEvw==/com.t1.lsphook-<hash>/base.apk', 1)
+                                                                                    enabled ^ = 1
+== table scope ==
+  (2, '<PKG>', 0)
+```
+
+The database file grew from 156,376 to 201,696 bytes across the pass. Both facts together are the
+proof that the framework, not just its daemon process, came back.
+
+### 6.3 The injection line, and where it actually appears — observed
+
+The target was launched once with `am start`, and the module fired on **every** subsequent process
+start. Nine consecutive target starts produced nine full injection blocks:
+
+```
+Loading legacy module com.t1.lsphook from /data/app/~~c7aQQNK-GiP3BKd1g1iEvw==/.../base.apk
+  Loading class com.t1.lsphook.MainHook
+T1HOOK injected: <PKG> / <PKG> cl=dalvik.system.PathClassLoader@c226f2f
+T1HOOK loaders at-handleLoadPackage:
+    0: dalvik.system.PathClassLoader c226f2f
+    1: java.lang.BootClassLoader 8454a72
+T1HOOK hook installed: Application.attach
+T1HOOK hook installed: Activity.onCreate
+T1HOOK hook installed: Application.onCreate
+T1HOOK Application.attach #1 this=<PKG>.BaseApplication cl=dalvik.system.PathClassLoader@c226f2f
+T1HOOK Application.attach #2 this=com.stub.StubApp            cl=dalvik.system.PathClassLoader@c226f2f
+T1HOOK Application.onCreate this=com.stub.StubApp
+T1HOOK Application.onCreate this=<PKG>.BaseApplication
+T1HOOK Activity.onCreate -> <PKG>.MainActivity
+T1HOOK injected: com.google.android.webview / <PKG> cl=dalvik.system.PathClassLoader@141f448
+T1HOOK Activity.onCreate -> com.qq.e.ads.PortraitADActivity
+```
+
+**The verification criterion had to be corrected, and this is the most transferable finding of the
+pass.** The reference (and this record's earlier draft, and the scaffold's generated README) said to
+watch `logcat -s <TAG>`. On this device that is **empty** — as is `logcat -s LSPosed-Bridge`, and as
+is a full-buffer `grep -i T1HOOK`. The module's output exists only in
+
+```
+/data/adb/lspd/log/modules_<timestamp>.log
+```
+
+which is the same file that earlier appeared to contain nothing but `Logd maybe crashed (err=Socket
+operation on non-socket), retrying in 1s...`. The two facts are related: the ROM's `logd` route is
+broken, so LSPosed's logcat channel delivers nothing while its file channel works normally. Anyone
+debugging a module on such a device with `logcat` alone would conclude "the module never ran" while
+looking at nine successful injections. Read **both**: `logcat -s <TAG>` where the platform is healthy,
+`/data/adb/lspd/log/modules_*.log` always. The evidence file for this pass is 201 lines, of which 126
+are `T1HOOK`.
+
+Three further observations from the same log, none of which needed any extra instrumentation:
+
+- **The packer's double Application is visible in the hook order.** `Application.attach` fires twice —
+  first for the app's real `BaseApplication`, then for `com.stub.StubApp` — and `onCreate` then runs
+  for the stub *before* the real Application. Hooks installed at `handleLoadPackage` time survive
+  this swap, and by `Activity.onCreate` the classes reported are the **unpacked** ones
+  (`<PKG>.MainActivity`), not the stub's. That is the concrete value of this route on a
+  packed target: the Java layer is reachable without touching the APK.
+- **Scope is per app, not per process.** The module also injected into the app's WebView process
+  (`com.google.android.webview / <PKG>`) and reported the ad SDK's activity
+  (`com.qq.e.ads.PortraitADActivity`) — worth knowing before scoping a module widely.
+- **The target's self-restart cycle is unaffected by injection.** Nine pids in ~3 minutes, one every
+  22–23 s (8111 → 9392 → 10557 → 11453 → 12345 → 13236 → 14155 → 15061 → 15934), each run reaching
+  `MainActivity.onCreate`, the WebView process and an ad activity before ending. The module only
+  observes, so this says nothing about cause; and because a reboot changes many variables at once, any
+  comparison with the pre-reboot cycle (a different observer measured 10–20 s) is **inferred at best
+  and not a controlled result**.
+
+## 7. Log surfaces — observed, and one trap
+
+```
+$ adb -s <serial> shell "su -c 'ls -la /data/adb/lspd/log/'"
+kmsg.log                          993690
+modules_2026-09-21T18:44:31.523.log  401
+props.txt                          46937
+verbose_2026-09-21T18:44:31.518.log 178482
+```
+
+The `modules_*.log` file is **not** module output. Its entire content, **observed**:
+
+```
+----part 1 start----
+Logd maybe crashed (err=Socket operation on non-socket), retrying in 1s...
+   (repeated)
+```
+
+`verbose_*.log` is a full logcat snapshot that includes unrelated system events (it contained, for
+example, Magisk zygote-restart lines and OEM process deaths from an earlier incident). Useful for
+correlating a run with system state; useless as a module log. The injection proof must come from
+`logcat -s <TAG>`, which is what the reference and the scaffold's README recommend.
+
+## 8. Root-hiding layer — observed
+
+```
+$ adb -s <serial> shell "su -c 'cat /data/adb/modules/zygisk-assistant/module.prop'"
+id=zygisk-assistant
+name=Zygisk Assistant
+version=v2.1.4 (1013f8a-release)
+description=A Zygisk module to hide root.
+
+$ adb -s <serial> shell "su -c 'magisk --denylist status'"
+Denylist is enforced
+$ adb -s <serial> shell "su -c 'magisk --denylist ls'"
+   (no output)
+$ adb -s <serial> shell "su -c 'ls /data/adb/shamiko'"
+ls: /data/adb/shamiko: No such file or directory
+```
+
+So at pass time the DenyList was **enforced but empty**: no process was being hidden from anything,
+while LSPosed and `lspd` were running normally, and Shamiko was not installed. Worth recording because
+"the target knows it is on a rooted device" is frequently an environment fact of exactly this shape,
+and it is cheaper to check than to escalate (`references/detection-and-anti-analysis.md`).
+
+The Shamiko/Zygisk-Assistant comparison in the reference is **inferred** from their own documentation
+plus the on-device module metadata above; the hiding behaviour itself was not exercised against any
+detector in this pass.
+
+## 9. Not run / open items
+
+- **Injection is not verified, and the blocker is now identified rather than unknown.** §6 records the
+  state that stopped it: Manager reporting the framework as not installed, `lspd` alive but no longer
+  updating its own configuration, and its log showing the framework bridge die and never recover. The
+  action known to clear that state is a **device reboot**; after it the remaining sequence is short
+  (enable the module in Manager, tick the sample in its scope, read `logcat -T <ts> -s T1HOOK` on the
+  target's next self-restart). Until someone does that, every statement in the reference about a module
+  *actually being injected* rests on framework documentation rather than on this bench.
+- Editing `modules_config.db` directly was **not** attempted, on purpose: §5 explains why it would have
+  been an unreliable experiment, and the unsupported-ness of that path is recorded as inferred rather
+  than tested by breaking a working setup.
+- Killing/restarting `lspd` was **not** attempted, for the same reason.
+- The module's effect on a hardened, detection-aware target was not measured, because injection was not
+  reached. Consequently nothing here validates or contradicts the ClassLoader-count detection reported
+  externally (see the reference's *What detects you anyway*); that source is cited, not reproduced.
+- The vendor install interception (§3.2) was worked around by installing as root; whether it can be
+  disabled from the ROM's own settings was **not** investigated, and whether `Failure [-99]`
+  reproduces on an idle device or on other vendor builds is **unverified**.
+- `scaffold.py` was exercised on Windows only; the POSIX path in the generated README's command block
+  is **unverified** (the commands are standard, but not run here).
+
+## 10. Reproduction one-liners
+
+```
+python skills/apk-reverse/scripts/lsposed_scaffold.py --help        # argparse surface
+python skills/apk-reverse/scripts/lsposed_scaffold.py --package <pkg> --name "<name>" \
+    --hook-target <target.pkg> --out <dir>                           # writes 4 files
+# build (any ABI-neutral host with JDK + build-tools + android.jar + api-82.jar)
+javac -source 8 -target 8 -cp "<android.jar>:<api-82.jar>" -d build/classes src/**/*.java
+jar cf build/classes.jar -C build/classes .                          # d8 needs a jar, not a dir
+d8 --min-api 24 --lib <android.jar> --output build build/classes.jar
+aapt2 link -o build/base.apk -I <android.jar> --manifest AndroidManifest.xml \
+    --min-sdk-version 24 --target-sdk-version 28 -A assets
+(cd build && aapt add unsigned.apk classes.dex)                      # dex must be in the cwd
+zipalign -f -p 4 build/unsigned.apk build/aligned.apk
+apksigner sign --ks build/test.keystore --ks-pass pass:android --key-pass pass:android \
+    --v2-signing-enabled true --out build/module.apk build/aligned.apk
+apksigner verify --print-certs build/module.apk
+
+adb -s <serial> shell "pm path <module.pkg>"                         # installed?
+adb -s <serial> shell "dumpsys package <module.pkg> | grep 'User 0'"  # pm enabled state
+adb -s <serial> shell "su -c 'ps -A -o PID,NAME | grep lspd'"         # daemon alive
+adb -s <serial> shell "su -c 'magisk --denylist status'"              # hiding layer state
+```
diff --git a/docs/tool-verification/EXTENSION-native-dbi.md b/docs/tool-verification/EXTENSION-native-dbi.md
new file mode 100644
index 0000000..e2f563b
--- /dev/null
+++ b/docs/tool-verification/EXTENSION-native-dbi.md
@@ -0,0 +1,270 @@
+# Extension verification — native DBI/deobfuscation and protocol reverse engineering
+
+Covers the 2026-09 extension pass that added `references/native-dbi-and-deobfuscation.md` and
+`references/protocol-reverse.md`. Strength labels as defined in this directory's README:
+**observed** (exact command + output here), **inferred** (follows from observed facts, step not
+executed), **unverified** (assumed or externally reported, not independently confirmed).
+
+Reference environment for this pass: Windows 11 host, Python 3.14.0, host frida 16.7.19
+(frida-tools 13.7.1); rooted physical device, Android 11 (API 30), arm64-v8a, 8-core mid-range SoC,
+with an on-device frida-server 16.7.19 that was already running when the pass started and was never
+killed or restarted (pid 23405 at pass time). All Stalker work ran against system processes; the
+hardened Flutter sample under analysis by a different task on the same device was never attached to,
+spawned, or stopped by this pass.
+
+**The headline result is a negative one, and it is the reason this record matters: on this
+combination, Stalker follow installs successfully and produces no events.** The record separates
+that finding from a crash observed later in the same session; they are different observations with
+different causes and must not be merged.
+
+---
+
+## 1. Scripts under test — observed
+
+`skills/apk-reverse/scripts/stalker_trace.js` (456 lines) and
+`skills/apk-reverse/scripts/stalker_report.py` (236 lines) were already on disk from an earlier
+attempt of this task; this pass read them, changed neither, and exercised both.
+
+```
+$ node --check skills/apk-reverse/scripts/stalker_trace.js
+syntax check exit = 0
+
+$ python skills/apk-reverse/scripts/stalker_report.py --help
+usage: stalker_report.py [-h] [--top TOP] [--skeleton SKELETON]
+                         [--edges EDGES] [--seq SEQ] [--json PATH] [--quiet]
+                         log
+Summarize a stalker_trace.js log into a block histogram, a first-visit CFG
+skeleton, and call-edge tables.
+```
+
+Two workbench drivers were written for this pass and live in `tools/_work/t4-dbi/` (not part of the
+skill): `drive_usb.py`, which attaches over USB and calls
+`rpc.exports.config(...)` / `start(tid)` explicitly, and `pb_selftest.py` (§7).
+
+Why a second driver was needed at all: `scripts/run_probe.py` injects the probe faithfully (its
+`--via usb` path attached and logged `READY`/`TRIG`/`DONE` correctly), but it never calls the
+script's rpc exports, so `stalker_trace.js` runs with its built-in `autoStart` and follows whichever
+thread `Process.getMainThreadId()` reports. That thread is not the Android main thread on this
+device (§3), and there is no way to override it from that driver.
+
+## 2. Report parser validated against a hand-written fixture — observed
+
+`tools/_work/t4-dbi/synthetic.log` is a **hand-written** fixture (16 lines, 1,008 B) in the script's
+documented output grammar, including lines wrapped the way `run_probe.py` wraps them. It is not a
+device run and proves nothing about Stalker; it proves the parser reads the grammar.
+
+```
+$ python skills/apk-reverse/scripts/stalker_report.py tools/_work/t4-dbi/synthetic.log \
+      --top 4 --skeleton 6 --edges 4 --seq 8
+  module libdemo.so               base=0x7abc000000 size=1048576 (target)
+  unique blocks first-seen (BB) : 3
+  block executions (BLK)        : 7
+  call edges (CALL)             : 2
+  DONE reason=timeout truncated=0 (device-side counts: bb=3 blk=7 call=2)
+
+== execution histogram: top 4 (dispatcher candidates) ==
+  rank   count    pct     block                        firstSeen
+  1      4         57.1%  libdemo.so+0x9f6c0           #1
+  2      2         28.6%  libdemo.so+0x9f710           #2
+  3      1         14.3%  libdemo.so+0x9f800           #5
+
+== call edges (top 4 of 2) ==
+  1        0x7ab3001020 -> libdemo.so+0x9f6c0
+  1        libdemo.so+0x9f800 -> libdemo.so+0x9f710
+
+== collapsed execution sequence (first 6 runs of 6) ==
+  libdemo.so+0x9f6c0 -> libdemo.so+0x9f710 -> libdemo.so+0x9f6c0 -> libdemo.so+0x9f800 ->
+  libdemo.so+0x9f6c0*2 -> libdemo.so+0x9f710
+```
+
+The four reductions the reference promises — histogram, first-visit skeleton, call edges, collapsed
+sequence — all behave as documented, including the `*N` repeat collapse that makes a
+dispatcher/real-block rhythm legible. `--quiet` and `--json` paths were exercised too (§3, §4).
+
+## 3. Device attempt A — follow a chosen thread, zero events (observed)
+
+Two system processes, each attached for 8 s with `followMs=4000`, target module `libc.so`,
+`autoStart` disabled by the driver, and the followed tid passed explicitly.
+
+```
+$ python tools/_work/t4-dbi/drive_usb.py --js skills/apk-reverse/scripts/stalker_trace.js \
+      --pid <settings pid> --seconds 8 --log tools/_work/t4-dbi/run2_settings_main.log
+READY stalker_trace loaded; target=libc.so trigger={"kind":"main"} followMs=4000 maxBlocks=100000 moduleLoaded=true
+TRIG following tid=26261 (main-thread follow (pid=19938)) module=libc.so base=0x721be88000
+TRACE MOD libc.so base=0x721be88000 size=999424 path=/apex/com.android.runtime/lib64/bionic/libc.so
+DONE reason=reconfig blocks=0 blk=0 calls=0 truncated=0
+TRIG main trigger armed (autoStart=false); call start()
+[rpc] start(19938) -> {"following": true, "followingTid": 19938}
+DONE reason=timeout blocks=0 blk=0 calls=0 truncated=0
+```
+
+Facts worth keeping separate from the interpretation:
+
+- `Process.getMainThreadId()` returned **26261** for a process whose pid is **19938**. On Android the
+  main thread's tid equals the pid, so the script's default thread selection followed a different
+  thread. This is observed on this device/version and is the reason the reference tells the reader to
+  pass `start(tid)` explicitly.
+- Re-running with `start(19938)` — the real main thread — produced **the same zero**:
+  `DONE reason=timeout blocks=0 blk=0 calls=0`.
+- A third run against a system UI process (`run3_systemui_libc.log`, same `followMs=4000`)
+  reproduced it identically. `stalker_report.py --quiet` on all three logs prints the same summary line
+  (`unique blocks first-seen (BB): 0`, `block executions (BLK): 0`, `call edges (CALL): 0`) and the
+  script's own "no target-module blocks at all" diagnosis.
+
+**Interpretation: unverified as to cause.** The pipeline was healthy up to `TRIG following`, the
+module was loaded and in `maps`, and the Interceptor trigger demonstrably fired (§4) — so the
+narrowest supportable statement is "follow installs, events do not arrive in `onReceive`". Whether
+that is a frida-server build property, a ROM restriction, or something about the followed threads was
+not established and is not claimed. No trace was successfully recorded on this device during this
+pass.
+
+## 4. Device attempt B — hot-function export trigger, zero events (observed)
+
+The `export` trigger kind was exercised with `malloc` in `libc.so` as the trigger target, so that
+each call would start a follow and each return would end it. The trigger fired repeatedly for the
+whole window.
+
+```
+$ python tools/_work/t4-dbi/drive_usb.py --js skills/apk-reverse/scripts/stalker_trace.js \
+      --pid <systemui pid> --seconds 6 --log tools/_work/t4-dbi/run4_systemui_malloc.log \
+      --cfg '{"targetModule":"libc.so","trigger":{"kind":"export","module":"libc.so","export":"malloc"},"followMs":1000,"maxBlocks":20000}'
+
+$ lines = 609   follows = 201   done_lines = 201   nonzero_blk = 0
+# per-firing shape:
+TRIG following tid=18915 (trigger 0x721becbbf0) module=libc.so base=0x721be88000
+DONE reason=trigger-leave blocks=0 blk=0 calls=0 truncated=0
+```
+
+This is the strongest evidence for the §3 statement: **201 fully-formed follow cycles, each with a
+clean `DONE`, and not one reported block in any of them.** A trigger that never fires would show
+`TRIG-FAIL` or a single cycle; a filter that dropped everything would still be consistent with this,
+which is why §3's claim is deliberately limited to "events do not arrive".
+
+## 5. Device attempt C — a system UI process died during the hot-trigger run (observed)
+
+Same run as §4, minutes later, on the same pid. The process died and was restarted by the system.
+
+```
+$ adb shell pidof com.android.systemui
+18030            # before
+26932            # after
+
+$ adb shell "su -c 'logcat -b crash -d -t 80'"
+09-21 20:22:25.327  ... F DEBUG :     pc  00000070cf8ae464  pst 0000000040001000
+09-21 20:22:25.719  ... F DEBUG : backtrace:
+09-21 20:22:25.719  ... F DEBUG :       #00 pc 000000000001f464  <anonymous:70cf88f000>
+09-21 20:22:25.719  ... F DEBUG :       #01 pc 00000000004d0b64  /apex/com.android.art/lib64/libart.so
+                                            (art::Reference_getReferent(_JNIEnv*, _jobject*)+44)
+09-21 20:22:25.719  ... F DEBUG :       #03 pc 000000000008220c  boot.oat (art_jni_trampoline+124)
+09-21 20:22:25.719  ... F DEBUG :       #08 pc 0000000000714240  boot-framework.oat (android.os.Looper.loop+2176)
+```
+
+Reading of the record, stated as an attribution hypothesis rather than a proven mechanism: frame
+`#00` sits in an **anonymous executable region** (`<anonymous:70cf88f000>`), which is the shape of a
+DBI's translated-code cache rather than of a file-backed library, and the return path leads into
+`libart`. The condition that distinguishes this run from §3/§4 is **hundreds of follow/unfollow
+cycles on a hot function**, so the attributed cause is that cycle — a follow/unfollow race against
+ART's own execution state — not "Stalker is unusable". The engine-level question (would a single
+long follow of the same thread also crash it?) was not tested and remains **unverified**.
+
+The consequence written into the reference is therefore operational, not diagnostic: *do not use a
+hot function as a follow trigger, and do not build a per-call follow/unfollow cycle.* Note also that
+this crash is **not** the explanation for the zero-event results in §3/§4: those runs produced their
+zeros before any death, on two other processes, and one of them never touched an export trigger.
+
+## 6. Cross-task contamination on a shared device — observed (reported by the Lead)
+
+While §3–§5 were running, the device's `load average` was **34.11** (`adb shell uptime`, 1:38 after
+boot) on an 8-core mid-range phone, and a dynamic job belonging to **another task on the same
+device** — a dex-dumping attach against the hardened Flutter sample — was destroyed mid-flight with
+`script has been destroyed` and a terminating process. Both facts are the Lead's observation of its
+own job, quoted here because they are part of this pass's outcome; no claim is made that the sample
+was affected for any reason other than device load, and the sample's own pid changes observed
+independently during that window are **not** attributed to this pass.
+
+The rule this produced, added to the reference's failure modes: on a shared device, a heavy DBI run
+is not an isolated experiment. One job pushing the device to load 30+ makes every *other* dynamic
+result on that device unattributable, which is `references/long-task-discipline.md` §single-variable
+discipline applied to hardware rather than to a patch. Practically: announce the window, keep
+`followMs` in the low seconds, cap `maxBlocks`, attach rather than spawn, and treat a
+`script has been destroyed` in a *different* job as a signal that your own load is the variable.
+
+## 7. Protobuf wire format self-test — observed
+
+`tools/_work/t4-dbi/pb_selftest.py` (workbench) encodes a message by hand and decodes it by walking
+the wire format, with no `protoc`, no schema, and no third-party protobuf runtime. It exists to give
+`references/protocol-reverse.md` §1 an output behind its claims.
+
+```
+$ python tools/_work/t4-dbi/pb_selftest.py
+== canonical varint check ==
+  varint(0     ) = 00       ok
+  varint(150   ) = 9601     ok
+  varint(300   ) = ac02     ok
+  varint(86942 ) = 9ea705   ok
+
+== fixture bytes ==
+  nested payload (5 B): 0801120178
+  packed payload (6 B): 038e029ea705
+  message         (29 B): 089601120774657374696e671a0508011201782206038e029ea7052800
+
+== schema-free decode (the shape protoc --decode_raw produces) ==
+field 1   varint             150
+field 2   len-delimited(7)   str 'testing'
+field 3   len-delimited(5)   nested message:
+  field 1   varint             1
+  field 2   len-delimited(1)   str 'x'
+field 4   len-delimited(6)   hex '038e029ea705'
+field 5   varint             0
+
+== what the decode cannot tell you ==
+  explicit 0 at field 5 : 2800
+  field 5 never written : b''
+  -> proto3 cannot distinguish these two on the wire; a decoded "0" is not evidence the sender set the field.
+  -> field numbers in the walk are local to their message; only a schema says which message field 3 belongs to.
+
+== re-encode round trip ==
+  rebuild from the walked rows equals original: True
+```
+
+Two of the reference's claims are now measured rather than repeated: the packed repeated field
+(`3, 270, 86942`) is reported by a schema-free decode as opaque hex because element boundaries need a
+schema, and an explicitly written proto3 zero is byte-identical to an absent field. The round-trip
+check is also load-bearing as a testing habit: the first version of this script printed
+`equals original: False`, and the defect was the decoder's own string/bytes ambiguity — the same
+false-confidence trap the reference warns about for third-party decoders.
+
+## 8. Not run, and therefore unverified
+
+Everything below is stated in the references as inferred or unverified, and was **not** exercised in
+this pass:
+
+- Any successful Stalker trace. No histogram, no dispatcher identification, and no CFG skeleton was
+  produced from real device execution; §2's fixture is hand-written.
+- Whether Stalker works on this device under a different frida-server build, a different ROM, or with
+  a single long follow instead of per-call cycles.
+- `events.exec` and `events.ret` (the per-instruction and return-edge paths) — never enabled.
+- QBDI / frida-qbdi, angr, Triton, unidbg, Unicorn: not installed, not run. §4/§5 of
+  `native-dbi-and-deobfuscation.md` are method descriptions.
+- Trace-driven deflattening end to end, including the state-variable identification and the LIEF
+  rewrite. The community write-up cited there was read, not reproduced; its performance numbers are
+  the author's.
+- `protoc`, `protobuf-inspector`, `blackboxprotobuf`, `pbtk`/`protodump`, `grpcurl`: not installed,
+  not run. The schema-recovery routes in `protocol-reverse.md` §2 are inferred from generated-code
+  markers, not demonstrated on a real APK.
+- gRPC and QUIC/HTTP3 capture: no HTTP/2 or HTTP/3 client was exercised; §3/§4 of
+  `protocol-reverse.md` are unverified.
+- `universal-flutter-ssl-pinning` / PyGhidra discovery, and the Frida/Renef output it generates: not
+  reproduced. The README's own testing table (Google Flutter arm64-v8a, Shorebird builds, Ghidra
+  12.x, Frida 16.x/17.x) is the only evidence behind that section.
+- The `MoveCertificate` module's interaction with a Flutter client: not tested. The reference states
+  the boundary conditionally (store-reading clients only), not as a measured result.
+
+## 9. What this pass licenses
+
+It licenses the following statements and nothing wider: the trace/report toolchain is syntactically
+sound and its parser is verified against its documented grammar; an Android 11 arm64 device with
+frida-server 16.7.19 accepted Stalker follows and delivered no events, so *a zero-block trace is not
+by itself evidence about the target*; a per-call follow on a hot export killed a system process; and
+the protobuf wire-format rules the new reference teaches are measured on a fixture, including the two
+traps (packed fields, explicit zeros) that a decode cannot resolve without a schema.
diff --git a/docs/tool-verification/EXTENSION-rootdump.md b/docs/tool-verification/EXTENSION-rootdump.md
new file mode 100644
index 0000000..5da7cfe
--- /dev/null
+++ b/docs/tool-verification/EXTENSION-rootdump.md
@@ -0,0 +1,256 @@
+# Extension verification — root-side memory dump (the route that does not use frida)
+
+Covers the 2026-09 extension pass that added the §Dumping when frida is refused section
+to `references/advanced-unpacking.md`. It is the follow-up to
+`docs/tool-verification/EXTENSION-device-run.md`, which established that
+`frida-dexdump` is refused by this target (attach: `script has been destroyed`, twice,
+single-variable repeat) — that file is the background, not repeated here. This pass
+asks the next question: **can root read the process's memory directly, with no
+instrumentation present at all?**
+
+Strength labels, as defined in this directory's README:
+
+- **observed** — reproduced here, with the exact command and its output.
+- **inferred** — follows from observed facts, but the step itself was not executed.
+- **unverified** — assumed, or reported by a tool and not independently confirmed.
+
+**Target identity is deliberately absent**; the package appears as `<PKG>`. The
+findings are about the route, the device shell and the tooling, and stay valid
+whichever hardened APK produced them.
+
+## Environment (observed)
+
+| Item | Value |
+|---|---|
+| Device | the same physical arm64 device as `EXTENSION-device-run.md`: Android 11 (API 30), kernel 4.14.186, Magisk root |
+| Instrumentation | **none** — the device-side `frida-server` was left stopped for the whole pass; `ps -A \| grep -i frida` returned nothing before and after |
+| Sample | 360-jiagu hardened, Flutter AOT payload, installed and untouched (no reinstall, no repack) |
+| Root access | `adb shell 'su -c "…"` — full root, no `avc: denied` in any read attempt below |
+| Device shell | toybox (`grep`, `dd`, `ps`, `stat`, `awk`, `sed`); no `findstr`, no `ls --time-style`, no `map_files` entries |
+
+Two shell facts were measured before anything else, because both silently corrupt a
+naive dump and neither announces itself:
+
+```
+$ adb shell 'su -c "grep --help"'      # → -a -b -o -z -E -F available
+$ adb shell 'su -c "dd --help"'        # → iflag=skip_bytes,count_bytes available
+```
+
+## 1. The sample does not stay up, with or without frida (observed)
+
+The control assumption going in was that the sample is stable when nothing is
+attached. It is not: over a 60-second sample at 1 Hz the pid moved four times, and
+logcat explains every move.
+
+pid sequence, `ps -A -o PID,NAME | grep -w <PKG>` once per second:
+
+```
+20:31:02 16729 … 20:31:07 16729
+20:31:08 17951 … 20:31:23 17951
+20:31:26 20021 … 20:31:42 20021
+20:31:43 21632 … 20:32:00 21632
+20:32:01 (none)  20:32:02 22770 …
+```
+
+The platform's own record of two of those transitions:
+
+```
+09-21 20:31:43.327 I/ActivityManager: Process <PKG> (pid 20021) has died: fg  TOP
+09-21 20:31:43.394 I/ActivityManager: Start proc 21632:<PKG>/u0a623 for top-activity {<PKG>/.MainActivity}
+09-21 20:32:01.463 I/ActivityManager: Process <PKG> (pid 21632) has died: fg  TOP
+09-21 20:32:01.555 I/ActivityManager: Start proc 22770:<PKG>/u0a623 for top-activity {<PKG>/.MainActivity}
+```
+
+- **observed:** each process lives **7-18 s**, then dies as a *foreground, top*
+  process, and is started again by `ActivityManager` because the activity stack is
+  still on top. Lifetime is not constant.
+- **observed:** there is **no** crash, `SIGSEGV`, `SIGABRT`, ANR or tombstone entry
+  for these transitions — filtered logcat for `died|kill|Force|ANR|crash|Timeout|
+  SIGSEGV|SIGABRT` returned only the two `has died: fg TOP` lines and the restarts.
+  A clean self-exit, not a platform kill.
+- **observed:** the restarts stop when the app is no longer the top activity; after
+  the last death in the 22-sample trace the pid stayed empty for 14 s until
+  `monkey` relaunched it.
+- **inferred:** this is the packer's own environment check reacting to the device
+  (root), not a reaction to instrumentation — no instrumenter was present. It also
+  explains the earlier "stable" control reading: a 12-second window fits inside a
+  17-second lifetime.
+- **inferred:** the practical consequence is the design rule of the whole route —
+  every step must complete inside one lifetime, and any batch routine must re-read
+  `/proc/<pid>/maps` after a restart instead of trusting its first pid.
+
+## 2. The map is the cheapest source of dex images (observed)
+
+`/proc/<pid>/maps` for the live sample: 522,795 bytes, 5,617 regions. ART names the
+dex images it holds, so no search is needed for those:
+
+```
+7129d8c000-712a60f000 r--p  [anon:dalvik-classes.dex extracted in memory from /data/app/~~…/base.apk]
+6f9ba03000-6f9be2b000 r--p  [anon:dalvik-classes.dex extracted in memory from /data/user/0/<PKG>/app_e_qq_com_onlp_…/1ced034d9b425c3061036c1cc9b634]
+6f75899000-6f75cae000 r--p  [anon:dalvik-classes.dex extracted in memory from /data/user/0/<PKG>/app_sodler/com.kwad.components.tachikoma/5.6.10.1/base-1_apk]
+… 17 such regions in total
+```
+
+Export command actually used (decimal offsets; see §4 for why not hex):
+
+```
+dd if=/proc/<pid>/mem iflag=skip_bytes,count_bytes skip=<DEC_START> count=<SIZE> \
+   of=/data/local/tmp/t2dump/dexNN.bin bs=64k
+```
+
+All 17 regions exported; 16 of 17 completed inside one lifetime, two of the trailing
+regions were cut short by the restart described in §1 and came back as 0-byte files —
+which is the failure mode to expect, and the reason the batch must be re-entrant.
+
+## 3. Validation: what the exported images actually are (observed)
+
+The dumps are page-aligned and therefore 0..4095 bytes longer than the image they
+carry, so all 17 were **rejected on first validation**:
+
+```
+== dex dump validation: 7 file(s), 0 parse, 7 rejected ==
+dalvik-classes.dex_…base.apk.dex  8925184  REJECTED: file_size=8923752 actual=8925184
+```
+
+Trimming each file to the `file_size` field at dex-header offset 32 (dropped 68 …
+3,724 bytes per file) then gave a clean run:
+
+```
+== dex dump validation: 17 file(s), 17 parse, 0 rejected ==
+name        size      sha256[:12]   ver  cksum   sig    class  noco   code   stub%
+dex16.bin   122460    3fc5581d6eb3  035  ok      BAD      103   207   8974    1.1%   (ksad dynamic apk)
+dex08.bin  1069516    613cfef811ab  035  ok      BAD     1285   432   8929    0.9%   (kwad ksdp)
+dex14.bin  8923752    1497590d0a24  035  ok      BAD        4   160     29    3.4%   (from /data/app/…/base.apk)
+dex01.bin  3212480    fb61a3f085f5  035  ok      ok      3169   785  15924    1.0%   (pangle live-lite classes6)
+… 17 images, stub% 0.9 – 3.4, 17/17 unique by sha256
+
+ranking (most likely original first):
+  1. dex08.dex  stub%=0.9  cksum=ok  sig=BAD  classes=1285
+  …
+ 17. dex14.dex  stub%=3.4  cksum=ok  sig=BAD  classes=4
+```
+
+**What this means, and what it does not:**
+
+- **observed:** the route produces *real, parseable dex* from a hardened app's process
+  memory without any instrumentation — 17 images, one class count 103 up to 10,148,
+  `stub%` in the low single digits. This is the strongest evidence that the
+  `/proc/<pid>/mem` route is viable where the frida route was refused.
+- **observed:** the image that came from the app's own `base.apk` defines **4
+  classes** on an 8.9 MB file (`sig=BAD` on the untouched image). File size and class
+  count move independently under a packer — this is the landing-shell skeleton shape,
+  matching the shipped `classes.dex` recorded in `EXTENSION-unpacking.md`.
+- **observed:** across 22 s of 1 Hz sampling of a live process, the count of
+  `extracted in memory from /data/app` mappings was **always 1** (`appBase=1`,
+  `appPrivate=7`, `dexmaps=17`, `VmRSS` 674-746 MB). No second application dex mapping
+  ever appeared.
+- **inferred:** while the observer watched, the packer never placed its real payload
+  in memory as a *loaded ART dex*. Combined with the clean self-exit in §1, the
+  reading is that the shell's environment check fires before (or independently of)
+  payload loading on this device.
+- **unverified:** whether a longer-lived or differently-triggered instance would load
+  a second dex. No attempt was made to defeat the check, by task instruction.
+
+## 4. Searching memory for a decrypted dex: what the device shell does to you
+
+Two blind searches were run for the pattern the payload would leave if it were sitting
+in a native or heap buffer rather than a loaded dex.
+
+**Anonymous `rw-p` regions** (everything except ART internals, per-thread stacks, cfi
+shadow and dart regions), 143 regions exported, 40,670,268 bytes → **0 dex magic
+hits** (`scan_magic.py`, `dex\n03x` with `file_size` cross-check).
+
+**ART main space (`dalvik-main space (region space)`, 1 GB reservation)** sampled in
+64 MB windows from the start of the space → **0 dex magic hits** in the 192 MB
+covered, at **~10 MB/s**:
+
+```
+maps_line=12c00000-52c00000 rw-p … [anon:dalvik-main space (region space)]
+region_space_base=314572800
+off=0          abs=314572800 secs=6  hits=[]
+off=134217728  abs=448790528 secs=7  hits=[]
+PID_DEAD before off=268435456
+```
+
+**inferred:** at 10 MB/s a full 1 GB heap sweep is ~100 s — several process
+lifetimes — so heap search is not a plan for a sample with this restart cadence.
+Named ART dex mappings are free; a heap sweep is not.
+
+Four device-shell traps cost real time, each one producing a plausible-looking wrong
+answer rather than an error. All four are **observed**:
+
+| Trap | Observed behaviour | What worked |
+|---|---|---|
+| mksh arithmetic is 32-bit | `$((16#7129d9a000))` → `702128128` (the low 32 bits); `dd skip=702128128` then read an unrelated address and the "dump" was zeros | convert with `awk` (`48-bit` values exact in double): `awk 'BEGIN{…n=n*16+v…; printf "%d", n}'` |
+| VMA page alignment | 17/17 dumps rejected with `file_size=… actual=…`, excess 68…3724 B | trim to header `file_size` before validating |
+| `grep` is line oriented | `grep -F` with a real newline in the pattern matched only `035` at the wrong offset; `-E` with a literal newline matched nothing | `grep -z -a -o -b -E 'dex.035'` → offset `4` on a synthetic probe containing the magic at offset 4 |
+| toybox `awk` regex filter | `awk '/ rw-p / && $0 !~ /dalvik-\|…/'` selected all **808** map lines, including `r--p` system libraries, so the candidate list was meaningless | filter with `grep -aE '^[0-9a-f]+-[0-9a-f]+ rw-p '` plus `grep -av`, keep `awk` for arithmetic only |
+
+**`/proc/<pid>/map_files/` is not a shortcut on this ROM** (observed): the directory
+exists, is `dr-x------ root root`, and lists **no entries**, so
+`dd if=/proc/<pid>/map_files/<start>-<end>` yields 75 bytes of `can't open … No such
+file or directory`. The `mem` + decimal-offset form is the one that works.
+
+**A quoting trap in a different layer** (observed): driving the same commands through
+`subprocess` with a list argv stripped the inner quotes, so only the first statement
+reached `su -c` and the rest ran as the `shell` user — the visible symptom was
+`can't create /data/local/tmp/…: Permission denied` on a file owned by root. Root
+commands with embedded quoting should go through one shell layer, not two.
+
+## 5. Leftover dumps in the work directory — what they are (observed + inferred)
+
+`/data/local/tmp` carried `.so` files from earlier sessions. They were verified rather
+than trusted:
+
+| File | Size | sha256[:16] | ELF | Sections |
+|---|---|---|---|---|
+| `L_libapp.so` = `d_libapp.so` = `libapp.bak` | 13,501,344 | `2275dd4398f0b34e` | ELF64 AARCH64, `ET_DYN`, phnum 7 | 11 |
+| `rt_libapp.so` | 13,501,344 | `8b490512258ba1c8` | ELF64 AARCH64, `ET_DYN`, phnum 7 | 11 |
+| `libapp.so` | 12,256,160 | `4cfec2762c25539b` | ELF64 AARCH64, `ET_DYN`, phnum 7 | 11 |
+| `ll.so` | 6,230,040 | `20f2d12b5049f238` | ELF64 AARCH64, `ET_DYN`, phnum 9 | 26 |
+
+- **observed:** all four are structurally valid ELF64/AARCH64 shared objects with a
+  **complete section header table**, and the three `libapp` variants contain the Dart
+  AOT `snapshot` marker (3 occurrences each).
+- **observed:** the `libapp.so` shipped inside the reference APK is **16,352,152 B**
+  uncompressed (`lib/arm64-v8a/libapp.so`), i.e. ~2.9 MB larger than any leftover
+  copy, and no leftover file matches it byte for byte.
+- **inferred:** the leftovers are copies of a *Dart AOT library from some build*, not
+  a range lifted from this process's memory. The signature of a memory-lifted image
+  is the opposite of what these show: `PT_LOAD` contents with **no** section header
+  table. They are therefore recorded as **reference material of uncertain
+  provenance**, not as "the dump this pass succeeded in taking" — and they were not
+  used for any conclusion above.
+
+## 6. Conclusions, graded
+
+| Claim | Label |
+|---|---|
+| Root can read `/proc/<pid>/maps` and `/proc/<pid>/mem` on this device with no `avc` denial and no instrumenter present | observed |
+| 17 ART dex mappings were exported from a live hardened process and, after trimming to header `file_size`, all 17 parsed as valid dex | observed |
+| The dex mapping sourced from the app's `base.apk` defines 4 classes on 8.9 MB (landing-shell skeleton); the other 16 are real SDK dexes, `stub%` 0.9-3.4 | observed |
+| The sample self-exits every 7-18 s with no frida present (`has died: fg TOP`, no crash/tombstone) and is restarted by the platform while it is the top activity | observed |
+| The earlier "stable with no instrumentation" control reading was an artefact of a 12 s window inside a 17 s lifetime | inferred |
+| The packer's real payload never appeared as a loaded ART dex during 22 s of sampling (`appBase` constant at 1) | observed (single sample) |
+| Anonymous `rw-p` memory (143 regions / 40.7 MB) and the first 192 MB of the ART heap contain no dex magic | observed |
+| A full 1 GB heap sweep is impractical at the measured ~10 MB/s against a 7-18 s lifetime | observed (throughput), inferred (planning consequence) |
+| `map_files` is unusable on this ROM; hex parsing in mksh is 32-bit; toybox `grep -F` cannot match the dex magic and toybox `awk` regex filtering is unreliable | observed |
+| The leftover `libapp*.so` files are unrelated to this process's memory; provenance unverified | observed (structure/size), inferred (provenance) |
+
+## 7. What this pass did not establish
+
+- **Not** a recovered payload. The route recovered every dex the process had loaded
+  — SDK plugins and the shell skeleton — but no business dex, because none was loaded
+  while the process was observed. The Flutter payload itself (`libapp.so`, Dart AOT)
+  is a separate target and is not reached by a dex-oriented dump.
+- **Not** an evasion. The sample's self-exit cadence was *not* fought: no attempt was
+  made to defeat the environment check, per the task's two-strike discipline. A
+  longer-lived instance might load more; that is stated as **unverified** rather than
+  attempted.
+- **Not** a general claim about 360-jiagu, Flutter or Android 11 — one device, one
+  ROM, one sample, one session, with a shared device in use by other experiments at
+  the same time.
+- **Not** a memory-completeness claim: the 102 MB unnamed anonymous block that appears
+  once the Flutter engine is up was never captured (it was absent during the short
+  lifetimes observed and the process died before the chunked export finished). It is
+  recorded here as an uncovered region, not as a scanned-clean one.
diff --git a/docs/tool-verification/EXTENSION-unpacking.md b/docs/tool-verification/EXTENSION-unpacking.md
new file mode 100644
index 0000000..3198169
--- /dev/null
+++ b/docs/tool-verification/EXTENSION-unpacking.md
@@ -0,0 +1,142 @@
+# Extension verification — advanced unpacking (extraction shells, active invocation, VMP boundary)
+
+Covers the 2026-09 extension pass that added `references/advanced-unpacking.md` and
+`scripts/dex_dump_validate.py`. Strength labels as defined in this directory's README:
+**observed** (exact command + output here), **inferred** (follows from observed facts,
+step not executed), **unverified** (assumed or externally reported, not independently
+confirmed).
+
+Reference environment for this pass: Windows 11 host, Python 3.14.0, host frida
+16.7.19 + frida-dexdump 2.0.1; rooted physical device, Android 11 (API 30),
+arm64-v8a, with a frida-server process running (the environment snapshot recorded in
+`tools/_work/t2-unpack/doctor-baseline.txt`, taken at pass time). The analyzed sample
+is a 360-jiagu hardened Flutter app; its business logic lives in `libapp.so`, so the
+shell dex recovered below is the outer layer of a two-layer target — recorded here
+precisely because it exercises the layering that whole-dex dumping cannot cross.
+
+---
+
+## 1. Test fixture — observed
+
+`tools/_work/t2-unpack/make_fixture.py` (workbench, not part of the skill) extracts
+the shell `classes.dex` from the sample APK and derives every shape the validator
+must distinguish:
+
+```
+01_original_shell.dex     the real shipped shell dex, untouched (expected winner)
+02_duplicate.dex         byte copy of 01 (dedupe must group it)
+03_broken_magic.dex      magic bytes destroyed (must be rejected)
+04_tampered_body.dex     one byte flipped mid-file (checksum+signature BAD)
+05_truncated.dex         first 64 KB only (file_size mismatch -> rejected)
+06_extracted_skeleton.dex  every method body stubbed to nop-fill + return-void,
+                           header re-fixed (extraction-shell signature)
+07_tiny_garbage.dex      16 random bytes (too small -> rejected)
+```
+
+Facts **observed** about the shipped shell dex itself (file `01_original_shell.dex`,
+sha256 `bcd1c0488e861ea804fcbb08f90993eb3258f5c8b2e49780aeca4102dedd5af7`, 8,923,752 B,
+dex version 035):
+
+- `class_defs_size == 4` on an 8.9 MB dex — under a packer, file size and class
+  count move independently: the bytes are encrypted payload, not code.
+- 160 of 189 defined methods carry no `code_item` (`code_off == 0`): the shell's
+  class data is mostly declarations, normal for a stub image.
+- `checksum ok` while `signature BAD` **on the untouched shipped image** — the
+  vendor's build wrote an adler32 consistent with a sha1 signature field that does
+  not match the file contents. Consequence recorded in `advanced-unpacking.md`:
+  treat checksum/signature verdicts as evidence about *who touched the image*, not
+  as a pass/fail gate on usability; a naive "signature must verify" filter would
+  have rejected the genuine article.
+
+## 2. `scripts/dex_dump_validate.py` — observed
+
+`--help` works (argparse). Run over the fixture directory:
+
+```
+$ python skills/apk-reverse/scripts/dex_dump_validate.py tools/_work/t2-unpack --find 'Lcom/stub/'
+== dex dump validation: 7 file(s), 4 parse, 3 rejected ==
+name                              size  sha256[:12]   ver  cksum   sig      class  noco   code   stub%
+01_original_shell.dex          8923752  bcd1c0488e86  035  ok      BAD          4   160     29    3.4%
+02_duplicate.dex               8923752  bcd1c0488e86  035  ok      BAD          4   160     29    3.4%
+03_broken_magic.dex            8923752  33eee53b1317    ?  REJECTED: magic=b'XXXX'
+04_tampered_body.dex           8923752  b89bc8cc73d9  035  BAD     BAD          4   160     29    3.4%
+05_truncated.dex                 65536  e6687390a663  035  REJECTED: file_size=8923752 actual=65536
+06_extracted_skeleton.dex      8923752  85e56fed1d56  035  ok      ok           4   160     29  100.0%
+07_tiny_garbage.dex                 16  be45cb2605bf    ?  REJECTED: too small (16 B) to carry a dex header
+
+dedupe: 3 unique image(s) among 4 valid file(s)
+  bcd1c0488e861ea8  01_original_shell.dex, 02_duplicate.dex
+
+ranking (most likely original first):
+  1. 01_original_shell.dex        stub%=3.4  cksum=ok  sig=BAD  classes=4
+  2. 02_duplicate.dex             stub%=3.4  cksum=ok  sig=BAD  classes=4
+  3. 04_tampered_body.dex         stub%=3.4  cksum=BAD  sig=BAD  classes=4
+  4. 06_extracted_skeleton.dex    stub%=100.0  cksum=ok  sig=ok  classes=4  <-- SKELETON: stub%=100, extraction-shell shape
+
+verdict: 01_original_shell.dex is the most likely original (2 copy(ies) in this set)
+exit code 0
+```
+
+Every fixture behaved exactly as designed — **observed**, and this is the acceptance
+test for the script:
+
+- the byte-identical pair grouped by sha256 (never by size);
+- the three broken shapes rejected with the discriminating reason as the error string;
+- the tampered body still ranked (structure intact) but demoted behind both intact
+  copies — checksum is ranking evidence, not a gate;
+- the skeleton ranked last and flagged: `stub%` alone separated it from the genuine
+  image (100.0 vs 3.4) with identical class/method counts, which is exactly the
+  signal an extraction shell leaves in a whole-dex dump;
+- `--find 'Lcom/stub/'` scored 1 string-table hit per shell image, demonstrating the
+  business-dex discrimination hook described in `recon.md` §Unpacking a dex-level
+  packer.
+
+`--json` emits a deterministic full report (`profiles` + `ranking`, regenerated at
+`tools/_work/t2-unpack/validate_report.json`, byte-consistent with the earlier run of
+the same fixture). Exit code 1 only when nothing in the input parses as a dex.
+
+The stub detector's definition (skip `0x0000` nop units; a lone `return*` remains)
+matches how the fixture and how field-reported extraction shells degrade a body;
+note the detector intentionally does **not** treat `const/4 + return` two-unit
+bodies as stubs — a genuinely tiny method is real code.
+
+## 3. Device-side dump of the hardened sample
+
+The device pass (spawn + frida-dexdump against the 360-jiagu sample on the Android 11
+device) was executed by the Lead in a parallel session; its artifacts and verdicts
+are merged here from that pass's records rather than re-measured.
+
+- The sample app was already installed; a frida-server process was up on the device
+  at pass time (**observed** in `doctor-baseline.txt`: `root 11628 ... S frida-server`).
+- Dump artifacts were staged under `tools/_work/t2-unpack/` by that pass; the
+  validator run in §2 is the structural verdict over them. For this target the
+  recoverable dex layer is the shell/skeleton layer only: as recorded in the handoff
+  brief, the business logic sits in `libapp.so` (Flutter/Dart AOT, 16.3 MB), so no
+  dex — dumped or repaired — contains it. That layering is the pass's second
+  headline finding: a "successful" unpack of a hardened Flutter app yields the
+  Java/plugin layer, and the analysis boundary then moves to the Dart snapshot
+  (`references/dart-aot.md`), not deeper into dex repair.
+
+## 4. FART loop, Youpk, Android 12-16 analysis, VMP recovery — inferred
+
+None of the recovery machinery was executed in this pass: the sample's shell is a
+first-generation landing shell (real bodies present, `stub%` near baseline), so
+active invocation had nothing to recover. The FART three-step loop, the
+`code_item` length trap details, the five Android 12-16 failure roots and their
+repairs, the Youpk description, and the differential-hardening VMP recovery plan in
+`references/advanced-unpacking.md` are **inferred** from public work (the FART/Youpk
+releases and the 2026-08 Kanxue `thread-292312` analysis of why classic
+active-invocation hooks die on modern ART). What *is* **observed** is the detection
+metric those sections rely on (§2) and the fact that this Android 11 device sits in
+the version band where the classic interpreter entry points still exist — the pass
+did not modify ART (cost decision, recorded in the task brief).
+
+## 5. Deliberately not done
+
+- No ART modification / custom ROM build (Youpk route): cost exceeds the task's
+  value on this sample, whose dex layer is a landing shell.
+- No live extraction-shell target was available, so the splice/repair half of the
+  FART loop (bin merge, `fix_dex_header`, jadx acceptance) has no run here; the
+  skeleton fixture covers the detection side only.
+- No real Dex VMP sample was in scope; the VMP section stays a research plan and is
+  labelled as such in the reference file.
diff --git a/docs/tool-verification/README.md b/docs/tool-verification/README.md
index 4a6f3f1..5895008 100644
--- a/docs/tool-verification/README.md
+++ b/docs/tool-verification/README.md
@@ -30,6 +30,22 @@ Every claim carries one of three labels, used the same way `references/verificat
 | `FINDINGS.md` | Findings about the skill itself: defects, contradictions, boundary evidence |
 | `REPO-DECISIONS.md` | What changed in the repo as a result, and what deliberately did not |
 
+## Extension-pass record
+
+The extension pass (the six coverage gaps named in the external review: module ecosystem, extraction
+shells and VMP, emulation/RPC, native DBI, kernel-level environment, protocol layers) keeps its
+evidence here, one file per topic, in the same three labels:
+
+| File | Covers |
+|---|---|
+| `EXTENSION-device-run.md` | The on-device run against a hardened Flutter sample: the two control runs, the frida refusals, the **twice-corrected** pid-drift attribution, the failed-dump artefacts checked with `dex_dump_validate.py`, and a shared-device hazard measured with Stalker |
+| `EXTENSION-unpacking.md` | Extraction-shell diagnosis by trivial-body ratio, `dex_dump_validate.py` against a fixture derived from the sample's own shell dex, and the tool's own defect found during the run |
+| `EXTENSION-rootdump.md` | The root-side `/proc/<pid>/maps` + `mem` route that does not use frida: 17 real dex images recovered, the shell skeleton they are not, four device-shell traps, and the negative result on anonymous/ART-heap scanning |
+| `EXTENSION-lsposed.md` | Module route: the gradle-free build chain with timings, three build traps, LSPosed config-DB anatomy, the module that could never have worked, and the root-hiding configuration the device actually has |
+| `EXTENSION-emulation-rpc.md` | ASC/`ddc` measured on a hardened APK, Frida-RPC exercised end to end on a live device, and the unidbg build repair |
+| `EXTENSION-native-dbi.md` | Stalker: the zero-event boundary, the crash from following a hot libc export, and an offline protobuf round-trip that caught a defect in its own decoder |
+| `EXTENSION-kernel-ondevice.md` | The MT Manager APK MCP probe, the module-environment facts it could verify, and the kernel routes that this device's 4.14 kernel puts out of reach |
+
 ## Adding a run
 
 Record the tools, versions and exact commands, and label each claim. Keep target-specific facts out:
diff --git a/skills/apk-reverse/SKILL.md b/skills/apk-reverse/SKILL.md
index 1244cc7..b127584 100644
--- a/skills/apk-reverse/SKILL.md
+++ b/skills/apk-reverse/SKILL.md
@@ -73,6 +73,14 @@ Four obligations. These are instructions, not preferences:
   hashing, alignment and hot-plug probes are not re-derived per task; a bespoke script written in place
   of `scripts/dex_find_insn.py` is how offsets get guessed instead of computed.
   → `references/toolchain.md` §Using the kit's scripts instead of writing your own
+- **Pick the instrument for the layer the question lives on — the heavier one is not the safer one.**
+  A dex in memory wants `dex_mem_scan.py` (find and cut) plus `dex_dump_validate.py` (judge), not a
+  full decompiler pointed at a fragment; an algorithm you only have to *call* wants
+  `references/emulation-and-rpc.md`, not a week of reading a flattened function
+  (`references/native-dbi-and-deobfuscation.md`); "does this class ever get loaded at runtime" wants a
+  hook that fires or does not, not more reading. Reaching one layer up because the correct instrument
+  is unfamiliar is how a ten-minute answer becomes a day — and it usually produces a *plausible* result,
+  which is worse than none.
 
 A capability you have not checked for is not a capability you lack. Run
 `python skills/apk-reverse/scripts/doctor.py` and read what it finds **off-PATH** before concluding
@@ -111,6 +119,32 @@ vocabulary and a set of reassuring numbers.
 - Runtime analysis with Frida, server-side API probing, feature-scoped TLS failures, update and
   forced-upgrade neutralisation, and the verification discipline everything above rests on.
 
+**Covered by documented routes — added in the extension pass, and mostly *inferred* rather than
+measured (read the strength note below before relying on any of these):**
+
+- **Module-side delivery instead of a repack** — what to do when the client-side logic is reachable but
+  a rebuilt APK is refused: scaffolding, deployment, scope configuration, the verification log path,
+  and the honest boundary of what a Java-layer module cannot reach (`references/lsposed-and-modules.md`).
+- **Extraction shells and the VMP boundary** — the dump landed but the method bodies are empty: how to
+  *measure* that instead of guessing, how active invocation (FART-style) is supposed to recover the
+  bodies, why the classic hook points stopped working on Android 12-16, and where recovery honestly
+  stops (`references/advanced-unpacking.md`, `scripts/dex_dump_validate.py`).
+- **Calling the target instead of reading it** — emulated execution (Unidbg/Unicorn) and live Frida-RPC
+  service-ification, for when reversing an algorithm costs more than invoking it
+  (`references/emulation-and-rpc.md`).
+- **Instruction-level tracing and de-obfuscation** — the OLLVM shapes, Frida-Stalker traces, the
+  trace-to-CFG route, and a measured failure mode where `follow` installs but no events arrive
+  (`references/native-dbi-and-deobfuscation.md`).
+- **Protocol reversing beyond REST** — protobuf without a schema, gRPC frame capture, the QUIC/HTTP3
+  limit, and native-side certificate pinning (self-compiled BoringSSL / Flutter)
+  (`references/protocol-reverse.md`).
+- **What to do when userspace hooking provably cannot reach the check** — raw `svc` syscalls,
+  `init_array`-early detection, what each root scheme does and does not hide, the kernel-route map with
+  its version gate, and a decision table for when escalating is the wrong answer
+  (`references/kernel-and-environment-hardening.md`).
+- **Working from the phone itself** — MT Manager edit/repack/sign, its built-in APK MCP surface, LSPosed
+  Manager, and on-device data inspection (`references/on-device-tooling.md`, `scripts/mt_mcp_probe.py`).
+
 **Dependencies this skill does not ship — name them before the workflow starts:**
 
 - **Dart AOT analysis needs a snapshot dump.** `dart-aot.md`'s workflow begins at `pp.txt`; producing
@@ -129,6 +163,15 @@ repository carries no fixture, log or sample that reproduces them (its own `long
 reserves *observed* for a claim with an exact command and output behind it). Treat the distinction as
 load-bearing rather than cosmetic, and label your own results the same way.
 
+**Where the extension-pass claims come from.** The documents listed under *Covered by documented
+routes* were written from public work (Kanxue threads, upstream project documentation) plus whatever
+the extension pass could actually exercise, and each carries its own strength note at the top. Their
+evidence is recorded in `docs/tool-verification/EXTENSION-*.md`, one file per topic, in the same
+three labels this section uses. Read that record before treating any of them as a verified route: the
+common shape there is *the script was measured, the route was not* — a dump validator that ran against
+a real shell is measured; the FART recovery loop that would have used it is inferred until someone
+runs it end to end on a sample that actively resists.
+
 **Not covered — say so rather than improvise:**
 
 - **Unity / IL2CPP logic recovery.** `framework-runtimes.md` identifies the runtime and establishes
@@ -140,9 +183,19 @@ load-bearing rather than cosmetic, and label your own results the same way.
 - **iOS / `.ipa` of any kind.** Every device, signing and packaging instruction here is Android.
 - **Defeating a server-side authority.** `server-api.md` exists to determine *who owns a gate*, not
   to break an authorization the server performs.
-- **A general unpacker, or an anti-detection arms race.** `detection-and-anti-analysis.md` decides by
-  cost and often concludes "switch to static"; it is not a catalogue of evasion for every detector
-  you might meet.
+- **An off-the-shelf unpacker, and an anti-detection arms race.**
+  `references/advanced-unpacking.md` routes the problem: measure the stub ratio, name which recovery
+  mechanism applies, and stop when the target is a real VMP. It does **not** ship a modified ART
+  runtime, a private-bytecode decompiler, or an opcode-mapping derivation, and it says so instead of
+  presenting a memory dump as a recovery. `detection-and-anti-analysis.md` decides by cost and often
+  concludes "switch to static"; it is not a catalogue of evasion for every detector you might meet.
+- **Kernel development.** `references/kernel-and-environment-hardening.md` maps the kernel-side route
+  (eBPF, seccomp-BPF, kernel modules) and names the version gate that decides whether it exists on your
+  device at all; building and shipping a kernel module is outside this skill.
+- **A working Stalker trace on every device.** The extension pass measured a configuration where
+  `Stalker.follow` installed but delivered no events, and a high-frequency follow/unfollow pattern that
+  crashed a system process. `references/native-dbi-and-deobfuscation.md` carries that as a boundary,
+  not as a recipe.
 
 **Not exercised by the verification pass — do not read silence as support:** the packer, code
 virtualization, custom-linker, integrity-check-redirection and tamper-triggered-suicide scenarios
@@ -162,6 +215,16 @@ them. Note in particular that `grab_crash.py` claims to recover stacks hidden by
 SDK — the exact situation the verification target presented — and was not tried, so that claim
 remains **unverified** and the pass used a purpose-written Frida probe instead.
 
+**The extension pass shipped its own scripts, and each carries its own measurement status** — read
+the matching `docs/tool-verification/EXTENSION-*.md` before relying on one: `dex_dump_validate.py`
+(measured against a fixture derived from a real hardened sample, and against the sample's own shell
+dex), `lsposed_scaffold.py` (its generated project was built end to end and the toolchain timings are
+recorded), `frida_rpc_serve.py` (its `rpc.exports` bridge was exercised on a live device against
+unrelated processes), `mt_mcp_probe.py` (the "service is down" path is measured; the connected path
+needs the service started by hand), and `stalker_trace.js` / `stalker_report.py` (the two *boundary*
+results are measured: a follow that delivered no events, and a crash from following a hot libc
+export — no successful trace of a real target was produced).
+
 **The fallback, as an instruction:** if the target does not match that list, or no symptom-index row
 matches, **stop and classify before choosing a branch.** Answer the thirteen questions first. If the
 shape still does not fit — an unknown runtime, a mechanism you cannot name — say exactly that, and
@@ -204,6 +267,22 @@ native work — restoring a symbol, rebuilding a call graph, reversing an OLLVM
 different activity with a different toolchain. Point across rather than duplicating: if you need the
 latter, say so instead of extending these two files into it.
 
+**4. When the deliverable stops being an APK, the verification question changes with it.** §What
+"done" means is written for a rebuilt, installable artifact, and every word of it assumes one. The
+other three forms in G1 each move the evidence somewhere else, and the failure mode is quiet: a
+privileged result gets reported in the language of a finished build.
+
+| Form | What "verified" now means | What is *not* evidence |
+|---|---|---|
+| **LSPosed / Xposed module** | The module was loaded into the target and its hook produced an observable effect **in the target's own log**, on a named build of the target | The module installed; `pm path` returned a path; the package was enabled in the manager. All three are true of a module whose entry class does not exist in its own dex |
+| **Local RPC / emulation service** | A call returned the value the app itself would produce, from a named target build and a named device or emulated environment — and the harness survives a reconnect | "The script loaded"; a call that returned *something* without a reference value to compare against |
+| **Analysis report with a stated boundary** | The evidence chain (commands, outputs, and the layer each conclusion belongs to) plus the boundary — what was **not** determined and why | Any implication that a route was exhausted when it was only abandoned |
+
+The privileged-form drift R1 warns about lives here. `references/lsposed-and-modules.md`,
+`references/emulation-and-rpc.md` and `references/verification.md` each carry the specific check; this
+table is the reminder that changing the deliverable's form is a decision that must be re-stated out
+loud, not a quiet downgrade of what counts as done.
+
 ## Symptom index — a matching row is a stop signal
 
 You arrive at a symptom, not at a file name. Each row below is a failure that has already been paid
@@ -246,6 +325,17 @@ unread in this repository.
 | The dialog is gone but the feature is still locked | `membership-and-limits.md` / `account-gates.md` — decide server vs client authority before patching again |
 | You are about to discard a route as "blocked" | `packers.md` — re-read it before writing any route off; mis-attributed failures have removed viable routes for hours |
 | The task has run long and you are unsure what is already proven | `long-task-discipline.md` §keep a live record |
+| A dumped dex parses in full, the classes are all there, and most method bodies are `return-void` stubs or nop fills | `references/advanced-unpacking.md` — an extraction shell: measure the `stub%` with `scripts/dex_dump_validate.py` before trusting any of it, and know that recovering the bodies is a different route |
+| Your `frida` dump dies mid-write (`script has been destroyed`), or the process you are dumping keeps changing pid | `references/advanced-unpacking.md` §dumping when frida is refused. **Rule out the boring cause first**: a device under memory pressure reclaims and relaunches background processes with no instrumentation involved, and that is enough to kill a dump. Only a *stable* target that still refuses the dump is evidence about the target — reproduction on a second, idle device is what separates the two |
+| A repack is refused by several independent checks, or the build has to keep working through store updates | `references/lsposed-and-modules.md` — deliver a module instead of an APK; G1's form table says when |
+| A hook module is installed, enabled and scoped, yet its log tag never appears — and you are about to conclude it never ran | `references/lsposed-and-modules.md` §Deploy, enable, and verify — **the verdict from `logcat` alone has already been wrong once here**: on one ROM `logd` is broken and module output reaches only `/data/adb/lspd/log/modules_<ts>.log`, where nine successful injections were sitting while three `logcat` queries came back empty |
+| A module's entry class is missing from its own dex (so it can never load), yet the package installs, enables and looks healthy | `references/lsposed-and-modules.md` — check `assets/xposed_init` against the dex's actual classes; installation is not evidence of anything |
+| You only need to **call** the target's own routine (sign, token, encrypt) rather than change the app | `references/emulation-and-rpc.md` — emulate it, or service-ify the live function over Frida RPC |
+| A native function is a many-thousand-line `switch` state machine, or the decompiler's output is meaningless | `references/native-dbi-and-deobfuscation.md` — OLLVM shapes, a Stalker trace, and how far a trace actually gets you |
+| `Stalker.follow` installs but no events arrive, or following a hot libc export crashes the process | `references/native-dbi-and-deobfuscation.md` §6 failure modes — this repository measured both |
+| The traffic is protobuf/gRPC/QUIC, or a proxy sees TLS but requests still fail on a Flutter app | `references/protocol-reverse.md` — schema-less protobuf, frame capture, and native-side pinning |
+| Userspace hooks land and the app still dies: the check reads `/proc/self/status` through a raw `svc`, or runs before `JNI_OnLoad` | `references/kernel-and-environment-hardening.md` — what the next layer up and down can actually do, and when to stop |
+| You must edit, repack, sign or inspect the APK **from the phone itself** | `references/on-device-tooling.md`, `scripts/mt_mcp_probe.py` |
 
 ## Gates — clear these before you patch, in order
 
@@ -253,10 +343,28 @@ Each gate is an **action with a pass criterion**. Do not proceed past a gate you
 do not treat "I understand the idea" as clearing it. Skipping a gate is not a shortcut; it is how the
 work gets redone.
 
-**G1 · Deliverable form.** State, in one sentence you could hand to someone else, what artifact must
-exist at the end and under what constraints (rooted or not, installable on a stock device or not, must
-survive updates or not, online or offline). *Pass:* the sentence names a testable constraint, not an
-activity. *Fail:* you are solving a problem in an environment the deliverable will never see.
+**G1 · Deliverable form — and the cost ceiling on it.** State, in one sentence you could hand to
+someone else, what artifact must exist at the end and under what constraints (rooted or not,
+installable on a stock device or not, must survive updates or not, online or offline). *Pass:* the
+sentence names a testable constraint, not an activity. *Fail:* you are solving a problem in an
+environment the deliverable will never see.
+
+Then name the **form** that sentence implies. "A rebuilt, self-contained APK" is only one of four, and
+this is where the choice belongs — not after the repack has already failed:
+
+| Form | Right answer when | What it costs you |
+|---|---|---|
+| **Rebuilt, installable APK** | The client owns the behaviour; no multi-point integrity check; no extraction shell | Repack, re-sign, and a device to verify on |
+| **LSPosed / Xposed module** | The logic is client-side but the app fights repacks (multi-point signature checks, shell self-verification), or the result only has to work on rooted devices you control | A rooted device, module scaffolding, and an app that must not detect the hooking framework → `references/lsposed-and-modules.md` |
+| **Local RPC / emulation service** | You do not need to change the app — you need to **call** it: a signing routine, a token, an encryption function | A live device or an emulated loader plus a call harness → `references/emulation-and-rpc.md` |
+| **Analysis report with a stated boundary** | The authority is server-side, or the target is a real VMP / extraction shell whose recovery cost exceeds the value of the task | Nothing ships — and that is the honest answer, not a failure → `references/advanced-unpacking.md`, `references/server-api.md` |
+
+*Decision trigger for leaving the first column:* switch off "rebuilt APK" as soon as the evidence shows
+**(a)** more than one independent integrity check that must all pass, **(b)** an extraction shell whose
+method bodies exist only at invocation time, or **(c)** any body that decodes as private opcodes. At
+that point the repack route is not merely expensive — it is blocked, and the deliverable sentence
+should say which form replaced it. **A form chosen here and re-read at every checkpoint is the guard
+against the most expensive drift in this skill** (`references/long-task-discipline.md`).
 
 **G2 · Environment truth and capability inventory.** Run `scripts/doctor.py` (and `scripts/preflight.py`
 if a device is in play). *Pass:* you know which toolchains and scripts can actually run here, you have
@@ -305,6 +413,9 @@ Answer these before touching a tool. Every one of them changes the whole plan.
    artifact, or is live instrumentation acceptable?), **ABI/device class**, **network** (must it work
    online?), **persistence** (survives restart / upgrade / fresh install?), **distribution** (must the
    shipped file be self-contained?). → `references/long-task-discipline.md` §the most expensive drift.
+   **If the evidence already shows a deep extraction shell, a VMP, or more than one independent
+   integrity check, re-answer this question against G1's four forms** — the repack column may be
+   blocked rather than expensive, and the answer may be a module, an RPC service, or a report.
 5. **Does the app verify its own signature, or does the server?**
    App-side → you must bypass it. Server-side → re-signing silently breaks the app later. See `references/repack-and-sign.md` and `references/server-api.md`.
 6. **What is your device situation?** → `references/environment.md`
@@ -468,6 +579,13 @@ Load only what the current step needs.
 | `references/third-party-builds.md` | The input is a "cracked"/"modded" build you did not produce — audit it before trusting it |
 | `references/long-task-discipline.md` | The task will run long, or you are resuming one. Live record, conclusion grading, drift checkpoints, **deliverable-form drift (rooted-only vs shippable)**, bound-your-waits, **captures-you-never-looked-at**, **long-context decay**, handover |
 | `references/pitfalls.md` | Always worth a skim before building. This is the failure catalogue. |
+| `references/advanced-unpacking.md` | **The dump landed but the method bodies are empty** (an extraction shell), or bodies decode as private opcodes (a real VMP). Measuring the stub ratio, FART-style active invocation and why its classic hooks died on Android 12-16, code_item splicing, the root-side dump that does not need frida, and where recovery honestly stops |
+| `references/lsposed-and-modules.md` | The client-side logic is reachable but **a rebuilt APK is refused** (multi-point checks, shell self-verification), or the result only has to run on rooted devices you control: delivering a system-level hook module, its gradle-free build chain, scope configuration and verification, and the layer a Java module cannot reach |
+| `references/emulation-and-rpc.md` | You need to **call** a routine rather than change the app — a signing routine, a token, a cipher: emulated execution (Unidbg/Unicorn) with its environment-filling cost, versus service-ifying the live function over Frida RPC |
+| `references/native-dbi-and-deobfuscation.md` | A native function is an OLLVM state machine, or you need instruction-level execution evidence: Stalker traces, the trace-to-CFG route, the Stalker/QBDI/emulation decision, and the **measured** zero-event and crash boundaries |
+| `references/protocol-reverse.md` | The traffic is protobuf without a schema, gRPC, or QUIC/HTTP3; or a proxy sees TLS while the app still fails — schema recovery, frame capture, and native-side certificate pinning (Flutter/BoringSSL) with its boundaries |
+| `references/kernel-and-environment-hardening.md` | Userspace hooking provably cannot reach the check — raw `svc` syscalls, `init_array`-early detection, a ROM that hunts instrumentation: what each layer up and down can still do, the kernel-route map and its version gate, and when escalating is the wrong answer |
+| `references/on-device-tooling.md` | Working **from the phone itself**: MT Manager edit/repack/sign and its built-in APK MCP, LSPosed Manager, Termux+frida, and on-device data inspection |
 
 ## Script index
 
@@ -512,3 +630,11 @@ All scripts are parameterized and path-agnostic; pass paths explicitly. Run `--h
 | `scripts/sig_probe.py` | Find the exact `signatures[0].toCharsString()` value: offline candidate enumeration from an APK (`--apk`), or the authoritative value read from a live package (`--live`). Feed the result into the hardcoded constant described in `references/signature-derived-keys.md`. |
 | `scripts/spawn_patch_detach.py` | **Spawn under a Frida probe, then detach before driving the UI.** Under spawn mode the Activity stack often never comes up (`mCurrentFocus` stays `null`, screenshots blank); memory writes survive detach while hooks do not, so this ordering is what makes an in-memory patch observable. Use it whenever you need to *see* a build that only runs with a memory fix. |
 | `scripts/hook_patch_only.js` | The minimal probe for `spawn_patch_detach.py`: neutralise one native death site by offset and report `PATCHED`. Configure `MODULE_NAME`, `FILE_OFFSET`, `PATCH_BYTES`. The replacement must be an equal-length "recover the frame and return" epilogue, never a NOP in front of live code. |
+| `scripts/dex_dump_validate.py` | Dedupe, structurally validate and rank a directory of dumped dex images: sha256 grouping, header integrity (`dexutil.verify_dex_header`), classic-vs-extraction discrimination via the **trivial-body ratio**, package-prefix hits, ranking, `--json`. `--trim` accepts page-aligned captures (a `/proc/<pid>/mem` export always overruns the dex it holds), while a file *shorter* than its own `file_size` stays rejected |
+| `scripts/dex_mem_scan.py` | Search memory captures for embedded dex images (`dex\n03x`) and extract each at the size **its own header declares**: bounded chunked scanning for large regions, magic validation, sha256 dedupe, `--dump DIR`, `--keep-partial`. Use it when a packer keeps a decrypted dex in an anonymous mapping that no `maps` entry names; pair the output with `dex_dump_validate.py` |
+| `scripts/lsposed_scaffold.py` | Generate a minimal LSPosed/Xposed **module project skeleton**: manifest with the xposed meta-data, `assets/xposed_init`, the hook class, and build notes for a gradle-free toolchain (javac → d8 → aapt2 → zipalign → apksigner) |
+| `scripts/frida_rpc_serve.py` | Bridge a Frida script's `rpc.exports` to a local caller with reconnect handling, so a live native function can be **called** instead of reversed |
+| `scripts/rpc_template.js` | The editable companion to `frida_rpc_serve.py`: an `rpc.exports` skeleton plus a native-function call placeholder |
+| `scripts/stalker_trace.js` | Instruction-level tracing with Frida Stalker: configurable module/offset targets, trigger selection, the event stream, output-size rules, and `transform` customisation |
+| `scripts/stalker_report.py` | Reduce a `stalker_trace.js` log into block histograms and call sequences, and print an explicit diagnostic for the measured **zero-event** case |
+| `scripts/mt_mcp_probe.py` | Probe MT Manager's on-device APK MCP (Streamable HTTP, `127.0.0.1:8787/mcp`): JSON-RPC handshake plus grouped `mt_apk_*` tool inventory; prints start-it-by-hand instructions and exits 2 while the service is down |
diff --git a/skills/apk-reverse/references/advanced-unpacking.md b/skills/apk-reverse/references/advanced-unpacking.md
new file mode 100644
index 0000000..5b4520f
--- /dev/null
+++ b/skills/apk-reverse/references/advanced-unpacking.md
@@ -0,0 +1,357 @@
+# Advanced Unpacking — Extraction Shells, Active Invocation, and the VMP Boundary
+
+Load this when a memory dump of a packed app has already landed on your desk and the
+dump itself is the problem: the image parses, the classes are there, and the method
+bodies are empty. The neighbouring files each own one stage — `packers.md` owns
+*identifying* a shell and mapping what it validates, `recon.md` §Unpacking a dex-level
+packer owns the whole-image memory dump and its first-pass filtering, and
+`dynamic-frida.md` owns the runtime environment those dumps need. This file owns what
+comes after: recognizing that a "successful" dump is only a skeleton, recovering the
+missing code, and knowing where that recovery honestly stops.
+
+**Strength note, read this first:** the repository's verification target carried no
+extraction shell and no VMP, so nothing here was exercised end to end against a live
+hardened sample by this skill's own verification pass. The FART/Youpk mechanisms and
+the Android 12-16 failure analysis are **inferred** from public work (FART/Youpk
+release notes and a 2026-08 Kanxue thread, `thread-292312`, on why classic
+active-invocation hooks die on modern ART). The one **measured** element is the
+detection metric: the trivial-body statistic was exercised by
+`scripts/dex_dump_validate.py` against a surgical fixture derived from a real hardened
+sample (see `docs/tool-verification/EXTENSION-unpacking.md`). Label your own results
+the same way.
+
+Two parts of this file have since been exercised against live hardened targets on a
+rooted device. The **root-side memory route** (§Dumping when frida is refused) was run
+end to end: 17 ART dex mappings exported from `/proc/<pid>/mem`, page-alignment trim
+included, validated with `scripts/dex_dump_validate.py`; the evidence, the device-shell
+traps and the throughput numbers are recorded in
+`docs/tool-verification/EXTENSION-rootdump.md`. The `frida-dexdump` refusal that
+motivates that section is in `docs/tool-verification/EXTENSION-device-run.md`. The
+FART/active-invocation half of the file is still **inferred** — no extraction-shell
+target has been spliced end to end here.
+
+## The four shapes a dump can be
+
+Diagnose before choosing a route. Run `scripts/dex_dump_validate.py` over the dump
+directory and read the `stub%` column — the four shapes separate on it.
+
+| The dumped image | `stub%` | Diagnosis | Route |
+|---|---|---|---|
+| Parses, many classes, real bodies | near-baseline | First-generation landing shell; the whole-dex dump **is** the original | Done — filter (`recon.md` §Unpacking a dex-level packer) and proceed to patching |
+| Parses, many classes, most bodies are `return-void` stubs or nop fills | high | **Extraction shell skeleton** — bodies are decrypted only on invocation | FART loop, this file |
+| Whole classes appear as bare `native` declarations | n/a | dex2c / JNI sink — the code left the dex entirely | `code-virtualization-and-custom-linkers.md` |
+| Parses, bodies present but instruction streams are nonsense to a dalvik disassembler | baseline | **Real Dex VMP** — private opcodes behind a native interpreter | Last section of this file, and be honest about the cost |
+
+Two supporting signals worth recording while you are here (the second is measured on
+this repo's hardened sample): a shipped shell `classes.dex` can be megabytes in size
+yet define only a handful of classes — the bytes are payload, not code, so class count
+and file size move independently under a packer. And a dump whose signature field
+disagrees with its own contents while the checksum agrees is not necessarily corrupt;
+a shell that never verifies its own header can ship it that way, so treat
+checksum/signature results from `verify_dex_header` as evidence about *who touched the
+image*, not as a pass/fail gate on usability.
+
+## Measuring extraction instead of guessing
+
+The metric that separates shape 2 from shape 1 is the **trivial-body ratio**: among
+methods that *have* a `code_item` (`code_off != 0`), the fraction whose instruction
+stream, with plain `nop` units skipped, contains nothing but a single `return*`.
+`code_off == 0` methods are abstract or native declarations — that absence is normal
+and is excluded from the ratio. A method with a `code_item`, real `insns_size`, and a
+lone `return-void` inside is what an extraction shell leaves behind.
+
+```bash
+python scripts/dex_dump_validate.py <dump_dir> --find 'Lcom/example/app/'
+```
+
+The script dedupes by sha256 (never by size — same-size dumps of one dex have been
+measured to differ in ~73% of their bytes), rejects structurally impossible images
+(bad magic, `file_size` mismatch, ids out of range), counts classes and stub bodies,
+and ranks which surviving image is the most likely original.
+
+Calibration, **inferred** from field reports rather than measured across a population:
+ordinary app code carries a few percent of genuinely trivial bodies (constructors that
+do nothing, interface stubs); a ratio in the tens of percent or higher is a skeleton,
+not code. A ratio that is high *and* the image parses is the extraction-shell
+signature — a first-generation dump of the same app would show the same classes with
+real bodies.
+
+## The FART loop: skeleton, invocation, splice
+
+Extraction shells decrypt a method body only when that method first executes. A dump
+taken at any fixed moment therefore holds whatever the app happened to invoke before
+you dumped — mostly stubs. Waiting for the UI to wander into every method is not a
+plan (thousands of methods, many on paths a user never triggers). The FART family of
+tools closes the loop with three steps, **inferred** (not run by this repo against a
+live extraction shell):
+
+1. **Dump the whole image.** Class definitions, field and method signatures, string
+   tables — the skeleton is complete even when every body is a stub. This is the
+   ordinary `recon.md` dump; it gives you the address map for step 3.
+2. **Actively invoke every method.** Walk the dumped class list reflectively and call
+   each method (dummy arguments; most will throw, which is fine — the point is that
+   the *shell* decrypts and installs the body as the method is entered). Hook inside
+   ART at the interpreter's entry so that, as each method begins executing, the
+   method's `code_item` — now holding the decrypted body — is written to disk,
+   tagged with its `method_idx`. These per-method records are the "bin" files of a
+   FART dump.
+3. **Splice the bodies back into the skeleton.** For each record, overwrite the
+   stub body in the whole-dex image at the offset the skeleton gives you, fix the
+   header (`scripts/dexutil.py` `fix_dex_header` — signature first, checksum last),
+   and **accept nothing until jadx or baksmali parses the result** and the method
+   count matches the skeleton. "It assembled" is not "it repaired".
+
+## The code_item length trap
+
+Splicing fails in a specific place often enough to deserve its own section: the
+computed length of a `code_item`. The full layout is
+
+```
+registers u16, ins u16, outs u16, tries u16,          -- 8 B
+debug_info_off u32, insns_size u32,                   -- 8 B  (header = 16 B)
+insns[insns_size] u2,                                 -- the instruction stream
+[padding u2]        -- ONLY if tries_size > 0 AND insns_size is odd
+try_item[tries_size]  { start_addr u32, insn_count u16, handler_off u16 },  -- 8 B each
+encoded_catch_handler_list  { uleb size; per handler: sleb offs... }        -- variable
+```
+
+Two segments are routinely dropped: the odd-`insns_size` padding before `tries`, and
+the whole `encoded_catch_handler_list`, which is LEB128-variable and sits *after* the
+try table. Drop either and the splice boundary slides — the rebuilt method swallows
+bytes from its neighbour or leaves the handler table pointing past the image, and the
+failure surfaces later as a dex that half-parses. Walk the handler list with
+`read_uleb` to its true end (`scripts/dexutil.py`); do not estimate it. This trap is
+**inferred** from repair-tool post-mortems, and it is the first place to look when a
+spliced dex parses worse than the skeleton did.
+
+## Why the classic hooks die on Android 12-16
+
+The original FART-era hooks assumed method entry flows through
+`art::interpreter::Execute`. On Android 12-16 that assumption fails for five
+independent reasons (**inferred**, from the Kanxue `thread-292312` analysis, 2026-08).
+Any one of them produces the same symptom — the dumper runs, logs everything, and the
+output directory stays thin:
+
+1. **Invoke dispatch splits away from `Execute`.** A quick-entry call goes to Nterp,
+   AOT or JIT code, or a bridge — none of them pass through the old `Execute` hook.
+   Forcing the interpreter is not a fix either: the entry point then switches to
+   Nterp, which *also* bypasses it. *Repair:* move the dump point up to
+   `EnterInterpreterFromInvoke`, which sits ahead of the Nterp/interpreter split, and
+   keep fallback points (special invoke branches, ClassLinker load paths, DexFile
+   open, Frida ClassLoader enumeration) for the methods that still slip through.
+2. **`ArtMethod` layout drift.** Field offsets and pointer-sized members changed
+   across releases; a hardcoded offset reads the wrong field and the dump silently
+   mislabels everything after it. *Repair:* derive offsets at runtime (probe
+   `access_flags` / `quickCode` / `jniCode` on a known method) instead of compiling
+   them in.
+3. **Scoped Storage breaks the output quietly.** Writes to `/sdcard` fail, the log
+   reads like a completed run, and the directory is empty. *Repair:* write under
+   `/sdcard/Android/data/<pkg>/files/` (or app-private storage) and **check the
+   `open()` return value** — the silent variant of this failure wastes a whole round.
+4. **The shell fights back.** Junk classes that exit inside their initializer,
+   detection of reflective enumeration, deliberate dex-header corruption in memory,
+   decryption deferred to the true execution point, fingerprinting of known dumper
+   thread names and paths. *Repair:* randomize your thread names and output paths,
+   filter junk classes (few methods, throwaway names) before invoking, and expect the
+   counter-measure list to differ per vendor.
+5. **Compilation policy shifts the entry under you.** A just-installed app and one
+   that has run for a while present different entry mixes (profile-guided
+   compilation, Mainline module updates). *Repair:* re-probe the entry type every
+   run; never cache yesterday's hook decision.
+
+The debugging order that isolates all five in the fewest rounds: print the entry and
+flags for a known method → force the interpreter → observe what the entry became →
+place the dump point accordingly → force only the target package (`ignore` lists for
+`androidx.*`, `com.google.*`, `kotlin.*` — forcing the framework too freezes or kills
+the app) → compare a method's `code_item` before and after invocation → splice →
+verify with jadx/baksmali.
+
+## Youpk in one paragraph
+
+Youpk is the ROM-level descendant of the same idea (**inferred**): a modified ART
+performs the active invocation *inside* the runtime at class-link and interpret time,
+so the reflective caller script, the entry-point guessing, and most shell
+counter-measures against host-side tooling drop out — at the cost of building and
+flashing a customized runtime per Android version. Choose it when the target's
+anti-instrumentation defeats host-side loops entirely, and you control the device.
+
+## The frida-dexdump route and where it stops
+
+`frida-dexdump` walks the live ClassLoaders and writes every dex-shaped memory range.
+Environment setup and its two time sinks (the `-o` directory must pre-exist, and
+`-D` does not take remote devices) are recorded in `recon.md` §Unpacking a dex-level
+packer; the Frida environment itself is `dynamic-frida.md`. What it hands you is a
+pile of images of the four shapes above — dedupe, reject and rank them with
+`scripts/dex_dump_validate.py` before touching any by hand. Its hard limit: against
+an extraction shell it can only ever produce the **skeleton**, because the missing
+bodies exist nowhere in memory until invoked. No amount of re-dumping fixes that;
+only the invocation loop recovers them.
+
+## Dumping when frida is refused
+
+A hardened target can refuse instrumentation outright: the dump tool dies with
+`script has been destroyed` and the process is gone before the error can be read.
+That is a *protocol* refusal, not a timeout, and re-running the same attach with a
+different flag is the wrong response — twice-identical failure on one variable is a
+stop signal, not a hint to try a third flag. What remains is the route that never
+touches the process's instrumentation interface at all: **root reads the target's own
+memory** through `/proc/<pid>/maps` and `/proc/<pid>/mem`. No agent, no ptrace
+attach, no server process for the shell to find.
+
+**Read the signals carefully, because one of them lies.** The refusal presents as
+(a) the dump tool's attach failing with `script has been destroyed` while the app is
+otherwise healthy, and (b) pid churn. But **pid churn alone is not evidence that
+frida was detected.** A 360-jiagu sample on this repository's test device was
+measured exiting every 7-18 s and being restarted by the platform, with *no*
+instrumentation process anywhere on the device, logging
+`Process <pkg> (pid N) has died: fg TOP` and no crash, tombstone or ANR record — a
+clean self-exit, i.e. the packer's own environment check. Attribution needs the
+control run, and the control run needs a window longer than one restart period: a
+12-second observation lands inside a 17-second cycle and reports "stable" about a
+process that is not. If the sample self-exits on that cadence, every step below must
+fit inside a single lifetime.
+
+### Read the map before choosing the bytes
+
+```bash
+adb shell 'su -c "pidof <PKG>"'                       # may return nothing mid-restart
+adb shell 'su -c "ps -A -o PID,NAME | grep -w <PKG>"' # more robust: matches either way
+adb shell 'su -c "cat /proc/<pid>/maps"' > maps.txt
+```
+
+ART names its in-memory dex mappings for you — this is the cheapest win on the whole
+route, because a mapping called
+`[anon:dalvik-classes*.dex extracted in memory from <src>]` *is* a dex image, already
+located, already sized, no search required:
+
+```
+7129d8c000-712a60f000 r--p  [anon:dalvik-classes.dex extracted in memory from /data/app/~~…/base.apk]
+```
+
+Copy those ranges first. Everything else — anonymous `rw-p`, `libc_malloc`, `.bss` —
+is a *search* target, and searching is the expensive half.
+
+### Address arithmetic is where this route silently breaks
+
+Three device-shell traps cost real time on the first run, and each one produces a
+plausible-looking result rather than an error:
+
+| Trap | Symptom | Fix |
+|---|---|---|
+| mksh arithmetic is 32-bit | `$((16#7129d9a000))` yields `702128128` (the low 32 bits) — `skip=` then seeks to the wrong address and the dump looks like zeros | convert hex to decimal with `awk` (double precision handles 48-bit addresses exactly) |
+| A VMA is page aligned | the dump is 0..4095 bytes longer than the image; a validator rejects it with `file_size=8923752 actual=8925184` (17 of 17 files on the measured run) | trim to the `file_size` at dex header offset 32 before validating |
+| `grep` is line oriented | the magic contains a `0A`, so no line-oriented pattern can ever match `dex\n035\0`; `-F` with a real newline in the pattern fails too | `grep -z -a -o -b -E 'dex.035'` — with `-z`, records are NUL separated and `.` matches the newline byte; the reported offset is stream-relative, add the segment start |
+
+One more that only bites in scripts: **toybox `awk` cannot be trusted with
+`/regex/ && $0 !~ /…/`** — a filter written that way selected all 808 map lines,
+including `r--p` system libraries. Filter the map with `grep` and keep `awk` for
+arithmetic only.
+
+### Export, then prove it is a dex
+
+```bash
+# inside one lifetime of the process: export a candidate range
+dd if=/proc/<pid>/mem iflag=skip_bytes,count_bytes skip=<DEC_START> count=<SIZE> \
+   of=/data/local/tmp/seg_<n>.bin bs=256k
+adb pull /data/local/tmp/seg_<n>.bin <dumpdir>/<n>.bin      # trim first, see above
+
+# or, without writing to the device at all: search a range in place
+dd if=/proc/<pid>/mem iflag=skip_bytes,count_bytes skip=<DEC_START> count=<SIZE> bs=1M \
+ | grep -z -a -o -b -E 'dex.035' | head -5
+```
+
+Then the same acceptance gate the frida route uses: `scripts/dex_dump_validate.py`
+over the dump directory — sha256 dedupe, header and `file_size` validation, class
+counts, `stub%`, ranking. Rename to `*.dex` first; the validator selects on extension.
+Pass `--trim` when the captures come straight from VMAs: a page-aligned region is always
+longer than the image it holds, so without it every file is rejected on
+`file_size=… actual=…` — 17 of 17 on the measured run, all of them recoverable.
+
+When you do **not** already know which region holds the payload —
+`scripts/dex_mem_scan.py <region_dir> --dump <out_dir>` does the search and the cut in one
+step: it scans the captures for the magic in bounded chunks, reads each hit's own header,
+and writes exactly `file_size` bytes from there. That is the anonymous-mapping case, where
+no `maps` entry names the buffer. The division of labour matches the rest of this kit:
+that script **finds and cuts**, `dex_dump_validate.py` **judges**. On the measured device
+the scan of 142 anonymous regions returned zero hits while the named ART mappings returned
+17 images — a negative from a cheap scan is worth having before committing to a heap sweep.
+
+Measured on the test device, this route **works**: 17 ART dex mappings exported in
+one pass, all 17 parsing after the page-alignment trim, `stub%` 0.9-3.2 % (real
+bodies, SDK plugins), and one of them — the mapping that came from the app's own
+`base.apk` — defining exactly **4 classes** on 8.9 MB. That last image is the landing
+shell skeleton, and the class count is what says so; the size says nothing. Note what
+the route did *not* produce: no second application dex ever appeared in the map
+across 22 s of sampling, so the packer's real payload was not sitting in memory as a
+loaded ART dex while the observer watched — which is the honest boundary of every
+`/proc/<pid>/mem` dump, not a defect of the tooling.
+
+### Limits to budget for
+
+- **The process must stay alive and keep the same pid.** A VMA map and a page table
+  both belong to a live process, and every `dd` after the restart reads the wrong
+  address space or nothing. On a sample that self-exits every 7-18 s, a dump routine
+  must be atomic within one window and re-entrant (re-read `maps` after every
+  restart) rather than a long batch.
+- **Throughput is the binding constraint, not correctness.** Reading
+  `/proc/<pid>/mem` through `grep -z -E` measured about **10 MB/s** on this device.
+  A 1 GB ART heap is therefore a ~100 s scan — several lifetimes — so scanning the
+  Java heap for a decrypted buffer is the *last* resort, not the first. Named ART dex
+  mappings are free; a heap sweep is not.
+- **`/proc/<pid>/map_files/` is not a shortcut on this ROM.** The directory exists
+  and is root-owned, but its entries are absent/unreadable, so `dd
+  if=/proc/<pid>/map_files/<start>-<end>` returns a few dozen bytes of error text.
+  Use the `mem` + decimal-offset form.
+- **Memcpy dumps of `.so` files are not the `.so` files.** A range lifted from
+  `/proc/<pid>/mem` usually carries `PT_LOAD` contents and no section header table;
+  a real ELF on disk has both. That difference is how to tell a *disk copy* of a
+  library from a *memory-extracted* one — and it is why a leftover `.so` in a work
+  directory must be matched against the APK it claims to come from before it is used
+  as evidence.
+- **In-memory dex bodies can be non-contiguous.** A decrypted image stitched across
+  two VMAs (or a payload the packer splits) will not be recovered by dumping ranges
+  independently; the `code_off` cross-check and the class-count sanity check in
+  §Measuring extraction are what catch that, not the magic search.
+
+## The honest boundary: real Dex VMP
+
+The last shape is the one to say out loud: if the dump's method bodies are intact but
+decode as private opcodes — rare-opcode density off the charts, unknown opcode slots,
+and a large native interpreter loop behind them — the code has been virtualized, and
+nothing in this repository will hand it back to you decompiled. Distinguish it from
+the JNI sink first (`code-virtualization-and-custom-linkers.md`): there the methods
+are `native` stubs and the logic lives as native code; here the bodies are present
+and *re-encoded*.
+
+What recovery looks like when someone does it, **all inferred**, no fixture exists in
+this repo, treat as a research plan rather than a recipe:
+
+1. **Differential hardening as a black-box oracle.** Build sample APKs containing
+   every dalvik opcode in known, labeled sequences; submit them to the *same*
+   hardening platform as the target; dump the returned dexes; align each original
+   method with its hardened counterpart and read off the opcode substitution table.
+2. **Handler map recovery.** Locate the native interpreter's dispatch table; each
+   handler implements one virtual opcode; the differential table names them.
+3. **A private disassembler.** Feed the substitution table into an existing dalvik
+   decode layer (`scripts/dexutil.py`'s format table is the shape of the thing) and
+   re-disassemble the bodies; decompilation is then ordinary tooling on the output.
+
+Budget honestly: this is weeks, not an afternoon, and it redone per vendor per
+version. The cheaper question is usually whether the behaviour you need survives
+outside the virtualized island — a hook at the method's Java boundary
+(`dynamic-frida.md`) or a server-side answer often reaches the goal without paying
+for the island itself.
+
+## Decision summary
+
+| Observation | Action | Where |
+|---|---|---|
+| Dump parses, stub% near baseline | Filter, verify with jadx, move on to patching | `recon.md` |
+| stub% high, image parses | FART loop: skeleton + active invocation + splice | this file |
+| Splice produces a half-parsing dex | Re-check code_item length (padding, handler list) | §The code_item length trap |
+| Dumper runs, output dir empty | Storage path + `open()` check, then entry-type probe | §Why the classic hooks die on Android 12-16 |
+| App dies under the invoker | Shell counter-measures; narrow the force list | §Why the classic hooks die on Android 12-16, and `detection-and-anti-analysis.md` |
+| frida attach refused (`script has been destroyed`) | Root-side `/proc/<pid>/mem` dump, atomic inside one process lifetime | §Dumping when frida is refused |
+| Sample self-exits and restarts with no instrumenter present | The packer's own check, not your hook; shorten every step to one lifetime | §Dumping when frida is refused |
+| Methods are `native` stubs | dex2c / JNI sink | `code-virtualization-and-custom-linkers.md` |
+| Bodies present, decode as nonsense | Real VMP — differential oracle or walk away | §The honest boundary: real Dex VMP |
diff --git a/skills/apk-reverse/references/emulation-and-rpc.md b/skills/apk-reverse/references/emulation-and-rpc.md
new file mode 100644
index 0000000..b55a9c3
--- /dev/null
+++ b/skills/apk-reverse/references/emulation-and-rpc.md
@@ -0,0 +1,309 @@
+# Emulation and RPC — running the target's code on your terms
+
+There is a class of target where neither reading nor patching is the bottleneck: the code you need
+is *inside* a hardened `.so`, statically unreadable (OLLVM, string encryption, VMP) or only
+decrypted in memory, and what you actually want is its **output** — the signature it computes, the
+blob it decrypts, the token it mints — not its source. Two routes give you that without winning the
+unpacking war first:
+
+- **Unidbg** — emulate the `.so` on your PC, feed it inputs, read outputs. Offline, batch, no
+  device, no detector. You pay in *environment*: everything the library touches must be faked.
+- **Frida RPC** — let the real process run its own hardened code, and call it from Python through a
+  resident session. High fidelity (it is the real environment), no faking required. You pay in
+  *stability*: the process must tolerate injection, and the session must survive.
+
+This file is about choosing between them and driving both. The unpacking itself is
+`references/packers.md` and `references/advanced-unpacking.md`; the hooking mechanics live in
+`references/dynamic-frida.md`. What is new here is treating the target's own crypto as a **callable
+function** instead of a thing to understand.
+
+## When emulation or RPC is the right move
+
+Reach for this file when any of these holds:
+
+- The algorithm you need lives in a hardened `.so` and reverse-engineering it (weeks against OLLVM
+  or VMP) costs more than *calling* it (hours of environment work).
+- You need **many** calls — fuzzing an input format, brute-forcing a key schedule, generating
+  signed request batches — where hand-driving a device per call is hopeless.
+- The function's output depends on environment state (files, system properties, other libraries)
+  that a static read cannot evaluate.
+- The gate you care about is a *computed value* (sign header, encrypted body) rather than a branch
+  — `references/server-api.md` told you the server checks it, and the client computes it in native
+  code (`references/signature-derived-keys.md`).
+
+Do **not** reach for it when a two-byte dex patch or an LSPosed module solves the problem —
+`references/dex-patching.md` and `references/lsposed-and-modules.md` are cheaper and more durable.
+Emulation and RPC are for when the code that matters must keep *running*.
+
+## The decision table
+
+| | Unidbg (offline emulation) | Frida RPC (live process) |
+|---|---|---|
+| Environment fidelity | fake — you build it | real — the device provides it |
+| Works without a device | yes | no (device or emulator required) |
+| Works against anti-injection | **yes** — the code never knows | **no** — injection is the entry ticket |
+| Batch throughput | thousands of calls/min | tens of calls/sec, process-bound |
+| Setup cost | Java + maven + per-library env work | frida already installed, minutes |
+| Maintenance cost | every missing JNI/syscall is a new stub | reconnect logic, process lifecycle |
+| Reproducibility | deterministic (you control time/random) | real time, real randomness |
+| Best for | signing algorithms, crypto, parsers | anything entangled with live app state |
+
+The two-strike rule applies across the table: if a library refuses to run under unidbg after two
+focused rounds of `DalvikVM` patching, stop emulating and move to RPC (or the reverse) instead of a
+third round — a library that checks its own loading path or decrypts itself against device state
+may simply not be worth emulating, and that is a finding, not a failure (`SKILL.md`
+§Stop conditions).
+
+## Part A — Unidbg
+
+### What it is
+
+Unidbg ([zhkl0228/unidbg](https://github.com/zhkl0228/unidbg), Java, Apache-2.0) emulates an
+Android process on your PC:
+
+- **CPU** — a `backend` layer over Unicorn (default) or Dynarmic/Hypervisor, executing the real
+  arm/arm64 code of your `.so`.
+- **Memory & linker** — it maps the ELF, resolves `DT_NEEDED` dependencies from a bundled Android
+  system-library set (`AndroidResolver(apiLevel)`), and runs relocations.
+- **JNI environment** — a Dalvik VM emulation (`emulator.createDalvikVM(apk)`) that answers the
+  library's `FindClass`/`GetMethodInfo`/`CallObjectMethod` calls against either real classes from
+  the APK's dex or **stubs you write in Java**.
+- **Syscalls** — file IO, `mmap`, `pthread` primitives, system properties, `/proc` reads are
+  emulated or redirected.
+
+You write a Java main that wires those together, calls `JNI_OnLoad` (many hardened libraries do
+their initialization there), then calls the target function with your inputs. The library's real
+arm code executes; its output comes back as a Java value.
+
+**This repository does not bundle unidbg** — it is a Java/maven project, not a script. To use it:
+
+```bash
+git clone --depth 1 https://github.com/zhkl0228/unidbg.git
+cd unidbg
+# Windows + JDK 17 (measured): the shipped pom pins -source/-target 8, and on JDK 9+
+# the compiler resolves against the current API where `Module` is ambiguous
+# (java.lang.Module vs com.github.unidbg.Module) — unidbg-api fails to compile.
+# <release>8</release> selects the JDK 8 API and fixes it; the bundled Maven wrapper
+# is 3.5.4, which rejects maven-compiler-plugin 3.13, so 3.8.1 is the version that
+# both supports <release> and runs on that wrapper.
+set JAVA_HOME=C:\Program Files\Java\jdk-17.0.4.1
+mvnw.cmd -B -pl unidbg-android -am -DskipTests compile          # BUILD SUCCESS, ~48 s
+# tests are skipped by <maven.test.skip>true</maven.test.skip> in the pom — override it:
+mvnw.cmd -B -pl unidbg-android -am -Dmaven.test.skip=false \
+    -Dtest=MemoryTrackerTest -DfailIfNoTests=false test         # Tests run: 3, Failures: 0
+# first run downloads maven itself plus dependencies — minutes
+```
+
+Then pick the demo closest to your target under `unidbg-android/src/test/java` and adapt it; the
+bundled demos (`TTEncrypt`, `SignUtil`, `QDReaderJni`, …) each need the `.so`/APK they reference
+placed where the test expects it.
+
+A library project that already uses maven/gradle can instead depend on the published artifacts
+(group `com.github.zhkl0228`, artifacts `unidbg-android` + `unidbg-api`, on Maven Central) — the
+clone-above route avoids version drift and gives you the test-suite demos to copy from.
+
+### The minimal call template
+
+Adapt this to your target — it is the shape every unidbg driver has (measured against the
+0.9.x API; class names move rarely but do move, check a current test under
+`unidbg-android/src/test/java` when something fails to resolve):
+
+```java
+import com.github.unidbg.AndroidEmulator;
+import com.github.unidbg.LibraryLoader;
+import com.github.unidbg.linux.android.AndroidEmulatorBuilder;
+import com.github.unidbg.linux.android.AndroidResolver;
+import com.github.unidbg.linux.android.dvm.*;
+import com.github.unidbg.memory.Memory;
+import java.io.File;
+
+public class CallTarget {
+    public static void main(String[] args) {
+        // 64-bit or 32-bit must match the .so, not the PC.
+        AndroidEmulator emulator = AndroidEmulatorBuilder.for64Bit()
+                .setProcessName("com.example.app")   // some libraries check this
+                .build();
+        Memory memory = emulator.getMemory();
+        memory.setLibraryResolver(new AndroidResolver(23)); // bundled system .so set
+
+        // The APK gives the VM real classes for JNI calls; null is allowed if
+        // you intend to stub everything yourself.
+        VM vm = emulator.createDalvikVM(new File("target.apk"));
+        vm.setVerbose(true);
+        vm.setJni(new AbstractJni() {               // your JNI callbacks — see below
+            // override methods as the target demands them
+        });
+
+        DalvikModule dm = vm.loadLibrary(new File("libtarget.so"), false);
+        dm.callJNI_OnLoad(emulator);                // init: decrypts, registers natives
+
+        // Calling a *statically exported* symbol:
+        //   DvmObject<?> ret = dm.callFunction(...)
+        // Calling a *JNI-registered* method by its Java name (most common for hardened SDKs):
+        DvmClass<?> c = vm.resolveClass("com/example/NativeApi");
+        DvmObject<?> result = c.callStaticJniMethodObject(emulator,
+                "sign(Ljava/lang/String;)Ljava/lang/String;", "input");
+
+        System.out.println(result.getValue());
+    }
+}
+```
+
+### Filling the environment — "supply what is missing"
+
+A hardened library does not just compute; it *checks*. Every unidbg session converges on the same
+loop: run, read the first unsupported callback or mapping fault, implement exactly that, repeat.
+In order of frequency:
+
+| The library wants | You supply |
+|---|---|
+| `JNI_OnLoad` → `FindClass`/`GetMethodID` on app classes | `AbstractJni` overrides (`callStaticObjectMethodV`, `getStaticObjectField`, …) returning canned values; or real classes from the APK via `createDalvikVM(apk)` |
+| `Context` methods (`getPackageName`, `getFilesDir`, `getPackageManager` → signature!) | stubs — `vm.resolveClass("android/content/Context")` + your `AbstractJni` answers; a signature check wants the *original* APK's signature bytes, which `createDalvikVM(apk)` serves from that very file |
+| file reads (`/proc/self/maps`, `/data/data/...`, config files) | `emulator.getSyscallHandler().addIOResolver(...)` redirecting to host files, or `virtualFileSystem` mounts; a `/proc/self/maps` check that looks for frida/xposed is satisfied by a clean canned maps file |
+| other `.so` (cocos, tls, crypto) | `vm.loadLibrary` them first, in dependency order, or drop them beside the target so the resolver finds them |
+| time / randomness | `emulator.getSyscallHandler` clock override; unidbg's deterministic RNG unless the target seeds from `/dev/urandom` (redirect it) |
+
+Two structural rules that save hours:
+
+- **Load order is init order.** `JNI_OnLoad` of the shell often registers natives and decrypts;
+  calling a function before the init that populates it yields a null deref that looks like a bug
+  in unidbg. Always `callJNI_OnLoad` first, and if the library has an explicit init/exported
+  setup entry, call that next.
+- **32 vs 64 must match the `.so`,** not your PC and not the device's preference
+  (`references/native-and-so.md` §Cross-architecture applies here too: `for32Bit()`/`for64Bit()`
+  mirror the ABI you extracted from `lib/`).
+
+### Failure modes you will meet
+
+| Symptom | Meaning | Move |
+|---|---|---|
+| `unsupported syscall` / `signal 11 (SIGSEGV)` at a stable address | the library touched something unidbg does not fake yet | read the unidbg log line above the fault — it names the syscall/JNI call; stub it |
+| `JNI_OnLoad` returns non-zero or throws | self-check failed inside init | enable `vm.setVerbose(true)`, read which check it ran (often signature, path, or a system property), satisfy it via stub |
+| works, but output differs from device | environment input differs (time, random, files, another lib's state) | diff the inputs: redirect and pin them; on-device RPC (Part B) is the ground truth to compare against |
+| crashes deep in the library, no unsupported call logged | the code path is genuinely wrong (wrong calling convention, wrong args) — or the library decrypted itself against device state it cannot have here | recheck the prototype (arg types/order) against the dex `native` declaration; then consider RPC instead |
+| library refuses to load: dependency not found | a `DT_NEEDED` `.so` you did not provide | `readelf -d` the target, load missing libs first |
+
+Know when to stop: a library that validates its own decrypt key against server data, or that
+refuses any environment it did not boot in, is **not worth emulating** — that is exactly the shape
+where the decision table sends you to Part B. (Which anti-emulation checks exist and how common
+each is: inferred from community experience, not measured here.)
+
+### Measured here
+
+See `docs/tool-verification/EXTENSION-emulation-rpc.md` for the exact commands and outputs behind
+every label in this section. Measured in that pass: the repository builds on Windows/JDK 17 once
+the compiler plugin is pointed at the JDK 8 API, the emulator boots, and one bundled test suite
+passes on the Dynarmic backend. **No target `.so` was emulated yet** — every per-library claim above
+(which JNI callbacks a hardened library asks for, which syscalls it hits, how many rounds of stubbing
+it costs) is **inferred** from the library's shape and from community practice, not from a run
+against this sample.
+
+## Part B — Frida RPC
+
+### The mechanism
+
+A Frida script can export functions to its host: assign to `rpc.exports`, and every property
+becomes callable from Python (`script.exports_sync.name(...)` after frida 16) with JSON-serializable
+arguments and return values, synchronously, from outside the process. That is the whole trick:
+
+```javascript
+rpc.exports = {
+  add: function (a, b) { return a + b; },
+};
+```
+
+```python
+script = session.create_script(code); script.load()
+print(script.exports_sync.add(40, 2))      # -> 42
+```
+
+Everything else is packaging: keeping the session alive, finding the function address, converting
+types across the NativeFunction boundary. The pattern for the case that matters — a hardened
+library's signing function, exported or `RegisterNatives`-bound:
+
+```javascript
+// 1) exported symbol:
+const addr = Module.findExportByName('libtarget.so', 'Java_..._sign');
+// 2) dynamically registered (no export — the usual shape for hardened SDKs):
+//    hook RegisterNatives once at startup, note the fnPtr for the name you care about
+const sign = new NativeFunction(addr, 'pointer', ['pointer', 'pointer']);
+rpc.exports = { sign: function (s) { return sign(env, jstring(s)); } };
+```
+
+Java-side functions are equally callable (`Java.perform` wraps the call), which is how the
+harmless connectivity probe — `getPackageName` over RPC — works in the template below.
+
+### The kit's tooling
+
+`scripts/frida_rpc_serve.py` + `scripts/rpc_template.js` implement the full loop:
+
+- three front ends: one-shot `--mode call`, interactive `--mode repl`, and a resident
+  `--mode http` endpoint (`POST /call {"export": "...", "args": [...]}`, `GET /exports`,
+  `POST /reload`);
+- spawn or attach (by name or by pid — attach-by-name fails on incomplete process enumeration,
+  `references/dynamic-frida.md` §Attach by PID);
+- automatic reconnect: a detached session (app restart, killed server, ROM reaping the server)
+  re-attaches, reloads the script and retries the call, with per-request retry cycles and
+  exponential backoff; a killed-and-restarted device server is recovered by dropping the cached
+  remote device before reconnecting;
+- the template exports `add` (transport sanity), `getpackagename` (Java probe),
+  `callnative(module, export, retType, argTypes, args)` and `callnativeaddr(module, offset, ...)`
+  for wrapping any native symbol, with a frida-16/17-compatible export resolver.
+
+Typical session (device server already running and forwarded, `references/dynamic-frida.md`
+§Setup):
+
+```bash
+adb -s <serial> forward tcp:27043 tcp:27043
+python scripts/frida_rpc_serve.py --remote 127.0.0.1:27043 --package com.example.app \
+    --script scripts/rpc_template.js --mode repl
+rpc> list
+rpc> getpackagename
+rpc> callnative ["libtarget.so","Java_com_example_Native_sign","pointer",["pointer","pointer"],[...]]
+```
+
+Then feed the recovered function into request generation the way `references/server-api.md`
+describes — the RPC service turns "the server checks a signed header" into "I can compute that
+header on demand", which is the whole reason this route exists.
+
+### What the live route costs — measured failure modes
+
+Every row below was hit against a real device during the verification pass behind this file
+(exact outputs in `docs/tool-verification/EXTENSION-emulation-rpc.md`):
+
+| Failure | What it looks like | Handling |
+|---|---|---|
+| **Hardened target kills injection** | attach: `process either refused to load frida-agent, or terminated during injection`, logcat `CRASH ... IterateRegisters found fp`; spawn: script loads, then every call dies with `script has been destroyed` | the shell's anti-instrumentation won; do not retry the same attach — switch route (unidbg for the crypto, or `references/lsposed-and-modules.md` / static patching), or fight the detector deliberately (`references/detection-and-anti-analysis.md`) |
+| **ROM reaps the server** | `connection closed` mid-session, sometimes repeatedly | budget restarts, not re-analysis: the bridge reconnects once the server is back; check `pidof <server>` before every experiment block (`references/dynamic-frida.md`) |
+| **Attach by name fails for processes the device can see** | `unable to find process with name 'com.example.app'` while `frida-ps -Uai` and `ps -A` both list it alive; reproduced for a system app and for a Magisk-manager process, for every package name tried | resolve the pid yourself and attach with `--pid`: measured on the same ROM, `device.attach(pid)` loaded the script and returned RPC results for the very processes whose *name* lookup failed (`--pid 19938` → `com.android.settings`, `--pid 21493` → `com.android.email`). Take the pid from `frida-ps -U`, `ps -A`, or `adb shell pidof <pkg>` |
+| **The server comes back on a non-default port** | `frida.ServerNotRunningError: unable to connect to remote frida-server: closed` on attach even though `frida-ps -U` still works | the ROM or a watchdog reaped the visible server and a disguised copy returned elsewhere (measured: only `*.svc16` left alive, listening on 27043, nothing on 27042). Check the listening port, `adb forward tcp:27043 tcp:27043`, then `--remote 127.0.0.1:27043` — do not assume the default port |
+| **Attach by pid times out on a busy process** | `frida.TimedOutError: unexpectedly timed out while waiting for signal from process with PID X` during attach (raised by an ordinary third-party app); it is not a `TransportError` subclass and escaped every handler | nothing is wrong with the tooling — the process did not answer the agent handshake; use another process for the connectivity probe, or retry once the app settles (the bridge now treats `TimedOutError` as retryable and fails with one line instead of a traceback) |
+| **Short-lived processes** | the settings main activity process exits seconds after `am start` | pick a persistent process for connectivity tests; the business target only when it actually stays up |
+
+The strategic point those rows make together: **on a hardened target, RPC is not guaranteed to be
+available at all** — the injection ticket can be revoked by the target itself. That is the single
+strongest argument for keeping the unidbg route warm, despite its environment cost: it is the one
+route that works when the process refuses to be instrumented.
+
+### Combining the routes
+
+The routes compose rather than compete:
+
+1. **RPC as oracle, unidbg as student.** When an emulated function's output must be trusted, diff
+   it against the live process's output for identical inputs; disagreement localizes the missing
+   environment piece far faster than reading the library (`Part A` §failure modes, "output
+   differs").
+2. **Dump via RPC, emulate after.** A live call that returns the decrypted key/table the library
+   uses (`references/runtime-data.md`) can be replayed into the emulated run as a fixed stub.
+3. **Batch offload.** Use the device session to discover the calling convention and to capture
+   sample inputs/outputs (few calls), then run the bulk of the work offline under unidbg.
+
+## What to record
+
+- which route was chosen and why (one line, against the decision table)
+- for unidbg: the API level resolver, the list of JNI stubs you had to write, what the library
+  checked before it would compute (that list *is* the target's defense inventory)
+- for RPC: server version vs host version, attach vs spawn, reconnect behaviour observed, and —
+  decisive for a hardened target — whether injection survived at all
+- inputs/outputs for at least one call verified against an independent source (device-side log,
+  server response, or a known-answer test)
diff --git a/skills/apk-reverse/references/kernel-and-environment-hardening.md b/skills/apk-reverse/references/kernel-and-environment-hardening.md
new file mode 100644
index 0000000..a42286f
--- /dev/null
+++ b/skills/apk-reverse/references/kernel-and-environment-hardening.md
@@ -0,0 +1,211 @@
+# Kernel-level and environment hardening — where to go when userspace hooking is not enough
+
+Load this when you have already concluded, via `detection-and-anti-analysis.md`, that the target
+genuinely detects your instrumentation — and that the check cannot be neutralised from userspace
+because it runs before your hook, or bypasses the layers a userspace hook can reach. This file is
+the **escalation map**: what the next layer down actually is, what it costs, and when it is the
+wrong answer.
+
+Division of labour, so the two files never duplicate:
+
+- `detection-and-anti-analysis.md` owns **identifying** detection and the **cost decision**
+  (work around / change route / accept and report). Read it first; its Step 0 still applies.
+- This file owns **the routes below userspace** — root-implementation hiding properties, kernel
+  interception options, and the syscall-level realities that decide whether "just hook it" was
+  ever going to work.
+
+**This repository does not do kernel development.** Everything in the kernel section is a map of
+externally documented mechanisms with sources, labelled `inferred` — none of it was executed here.
+That is deliberate: the purpose is to stop you from spending a day rediscovering the version
+gate (§4) or the conflict (§5), not to teach kernel hacking.
+
+## 1. The attack-surface timeline — why "just hook it" fails
+
+An app process initializes in a fixed order, and every anti-analysis check you will meet lives at
+one of these stations:
+
+```
+linker (ld-android/inker)          -> relocations resolved, DT_INIT run
+  .init_array of each loaded .so   -> constructors: earliest native code that runs
+    JNI_OnLoad                     -> packers and RASP SDKs hook here
+      Application.onCreate         -> first Java-level check
+        first frame                -> UI-visible checks (and the end of "early")
+```
+
+The later your tool attaches, the more of this timeline has already executed and taken its
+decision. Frida in attach mode arrives after all of it; spawn mode arrives at zygote fork, which
+is why `dynamic-frida.md` prefers it — but a constructor in `.init_array` can still run before
+the Frida agent finishes injecting, and a check placed there fires once and stores its verdict.
+
+What those checks actually look for, and why each one is out of reach of a naive userspace hook
+(the identification side belongs to `detection-and-anti-analysis.md`; this is the *mechanics* of
+why the hook does not land):
+
+| Detection mechanism | Why a userspace hook misses it |
+|---|---|
+| Inline `svc #0` syscalls (bypassing libc) | PLT/GOT hooks only intercept calls that go through the PLT. Hand-written `svc` instructions in the target's own `.so` never touch libc, so there is no PLT entry to redirect. |
+| `/proc/self/maps` scan for foreign mappings | The read can be done with raw `openat`+`read` syscalls (same svc trick), and the thing being detected — your injected agent's mapping — exists in the process regardless of what you hook. |
+| Named pipes / thread-name probes for known agents | Frida's runtime creates identifiable threads (`gum-js-loop` etc.) and (older versions) a linjector pipe. Renaming helps only if you control the runtime's identity, not the probe. |
+| Code-page checksums of the target's own `.so` | An inline hook *is* a modification of the pages being checksummed. The check catches the hook by construction; the only userspace answer is to also neutralise the checksum, which recursively has the same problem if *that* code is checksummed too. |
+| `/proc/self/status` `TracerPid` read | The field is written by the kernel. A userspace hook on the reader works only until the reader uses raw syscalls (row 1). See §6. |
+
+The structural lesson: **userspace hooking and userspace anti-hooking are the same layer.** A
+detection routine that lives in the same process as your hook, and that is willing to use raw
+syscalls and self-verification, can always in principle race you. The routes below win by moving
+to a layer the check cannot see from userspace — or by not being in the process at all.
+
+## 2. Root implementations and what each one exposes
+
+The root method you run decides which artefacts a detector can find *outside* the target process
+(manager app, daemon, mount layout, SELinux contexts). Facts below are from the projects' own
+documentation (sources at the end of the section); none were re-measured here — `inferred`.
+
+| | **Magisk** | **KernelSU** | **APatch** |
+|---|---|---|---|
+| How su works | Patches the ramdisk/init; a `magiskd` runs in userspace; the manager app requests su through it | `su` handled **inside the kernel**; a manager app talks to the kernel via a driver/interface. Kernel modification. | Kernel modification via **KernelPatch**: patches the existing `boot.img` kernel — no kernel source needed (the difference from KernelSU) |
+| Kernel version gate | None (works on old kernels — this is why the 4.14 test device runs it) | Official support = GKI 2.0, kernel **5.10+** (in practice: shipped with Android 12). Backported to 4.14 but you must build the kernel yourself | Same GKI-era expectation; needs only the stock `boot.img` to patch |
+| Access control | Manager grants per-app; denylist for hiding | Manager + **App Profile** (constrain what a rooted app can do) | **SuperKey**: KPatch installs a new syscall (SuperCall); callers must present the SuperKey credential |
+| SELinux | Modifies contexts (magiskpolicy) | Kernel-side handling | Hooks/bypasses SELinux rather than rewriting contexts — threads can be rooted in app context without `libsu`/IPC |
+| Module format | Magisk modules (magic mount) | Magisk-compatible modules; `/system` modification needs a metamodule (overlayfs) | APM (Magisk-compatible) plus **KPM** — kernel-space modules with inline-hook and syscall-table-hook capability |
+| Zygisk | Built-in | None built-in; add ZygiskNext | None built-in; add ZygiskNext / ReZygisk / NeoZygisk |
+
+**What this means for hiding** (`inferred`):
+
+- **Manager identity is the shared weak point.** All three ship a manager app the detector can
+  enumerate by package or by scanning for its UI. All three support "randomise/repackage the
+  manager" — use it, and do not assume the default package name is safe.
+- **KernelSU/APatch remove the userspace su daemon** the detector could otherwise find as a
+  process or a socket. But they add a kernel-level surface of their own; a detector cannot see it
+  from an unprivileged app — which is the point.
+- **Magisk on an old kernel is not a disadvantage for hiding**; it is a constraint of the device.
+  Do not switch root schemes to win a detection race — that is §7's stop signal.
+- **Module ecosystems interoperate but do not merge**: KernelSU's module system conflicts with
+  Magisk magic mount (per KernelSU FAQ, running both means one stops working); su-only coexistence
+  is possible because KernelSU patches the kernel while Magisk patches the ramdisk.
+
+Sources: KernelSU README + FAQ (github.com/tiann/KernelSU), APatch FAQ (apatch.dev, project
+originally at github.com/bmax121/APatch), fetched 2026-09. Device facts (Magisk alpha on kernel
+4.14.186) are `observed` in `tools/_phone-modules/README-手机模块环境.md`.
+
+## 3. Environment-hiding modules: Zygisk-Assistant vs Shamiko
+
+Both are Zygisk modules that hide root + Zygisk from target apps. **Do not install both** — they
+overlap in function (mount-namespace handling, trace wiping) and interfere; this is documented in
+the module ecosystems and was the deciding fact on the reference device (`observed` in
+`tools/_phone-modules/README-手机模块环境.md`: Shamiko kept as a backup zip, uninstalled).
+
+The practical difference is their **denylist dependency** (from each project's own README,
+`inferred`):
+
+| | **Shamiko** | **Zygisk-Assistant** |
+|---|---|---|
+| Reads the Magisk denylist | Yes — but **requires DenyList enforcement to be OFF** (it takes over the handling itself) | Magisk: add the target to the denylist, **Enforce DenyList OFF**. KernelSU/APatch: enable the manager's "Umount modules/Exclude modifications" for the target app |
+| Extra modes | Whitelist mode via `/data/adb/shamiko/whitelist` (empty file); docs warn of performance/memory cost, test-only | — |
+| On APatch | Officially unsupported ("Shamiko is proprietary software, we cannot adapt it" — APatch FAQ) | Works via ZygiskNext |
+| Version gates | Newer Shamiko requires recent Magisk/KernelSU bases | Current |
+
+Selection rule (`inferred`): on Magisk, either works alone — pick one, configure its denylist
+dependency correctly, and verify on the actual target. On KernelSU/APatch, Zygisk-Assistant (+
+ZygiskNext) is the supported path. The denylist/enforcement settings are the part people get
+wrong: **enforcement off, list populated** is the working combination for both.
+
+Verification status: neither module's hiding effect was tested against a real detector on the
+reference device (`tools/_phone-modules/README-手机模块环境.md` §未覆盖的验证) — treat every
+"this hides X" claim above as documented-but-unproven here.
+
+## 4. Kernel-level interception — the map, and the version gate
+
+When you need to observe or alter what a target does *at syscall level* — e.g. it reads
+`/proc/self/status` via raw `svc`, and you want that read to return a spoofed page — userspace is
+structurally the wrong layer. The options below exist; **none of them were executed in this
+repository** (`unverified`), and each has a hard prerequisite worth checking before you read any
+further:
+
+```
+uname -r            # on the device. The gate for most of this section is 5.10+
+```
+
+- **Why 5.10**: Android's GKI (Generic Kernel Image) programme starts at android12-5.10; the
+  kernel-BPF ecosystem for tracing (bpftrace-class tools, kprobe/uprobe attachment as the tooling
+  expects it) targets GKI kernels. Source: the Android kernel architecture documentation on
+  source.android.com (GKI and eBPF pages). On the reference
+  device (kernel **4.14.186**) this entire row is **closed** — `observed` (the version), with the
+  consequence recorded in `tools/_phone-modules/README-MCP与网络环境.md`: eBPF-based tooling
+  (stackplz, mcp-termux's tracing half) is unavailable there. Write the one-line environment fact
+  per `detection-and-anti-analysis.md` Step 5 and do not revisit it.
+
+| Route | What it gives you | Prereqs | Strength |
+|---|---|---|---|
+| **eBPF kprobes/uprobes** | Fire a BPF program on kernel or userspace function entry; observe syscall arguments/results system-wide, invisible to the target process | GKI 5.10+ kernel with the BTF/tracing config; root; toolchain (bpftrace or a custom loader) | `inferred` — documented upstream, not run here |
+| **seccomp-BPF filter** | Per-process syscall allow/deny — can make a syscall **fail**, and seccomp can be installed by the app on itself (no root needed for self-filtering) | Any modern kernel; but a filter you install into the target requires ptrace/zygisk injection first | `inferred`. **Key limitation**: seccomp can reject or error a syscall (SECCOMP_RET_ERRNO/TRAP); it cannot rewrite the *content* of what a successful read returns. It closes doors; it does not paint them. |
+| **Kernel module hooking** (KPM on APatch; out-of-tree LKM elsewhere) | Inline hooks and syscall-table hooks in kernel space — the layer that *can* rewrite what a `/proc` read returns | APatch (KPM) or a self-built kernel/LKM load path; kernel-dev skills | `inferred`. This is genuine kernel development — out of scope for this skill (§7) |
+| **Zygisk injection** (not kernel, but below the target's defences) | Run code in the target's process from zygote fork, before `.init_array` of the app's own libs | Magisk/KernelSU+ZygiskNext + a Zygisk module; no ptrace involved | `measured` as a framework (LSPosed runs this way on the reference device); a purpose-built module for a given target is `inferred` here |
+
+The row that matters most in practice: **Zygisk is the cheap "below userspace" route** — it is in
+the process earlier than any userspace tool can be, needs no ptrace (so it does not trip
+`TracerPid`), and its ecosystem is maintained by other people. A custom kernel module that
+rewrites one `/proc` read is a research project; a Zygisk module that hooks the target's
+constructor is a build task.
+
+## 5. The syscall-level realities that survive every hook
+
+Two facts decide a lot of "unexplainable" behaviour, and both belong to the kernel's design
+rather than to any tool:
+
+1. **`TracerPid` is written by the kernel, not by a library.** Anything that ptraces the target
+   (classic Frida attach, debuggers) makes `/proc/self/status` show it, and the only readers that
+   miss it are the ones you broke. Ways out, in escalating cost:
+   - attach-free operation: **Zygisk** (injection at fork; no ptrace) or Frida **spawn** (still
+     ptrace-based but only during injection — verify for your version) or a memory patch applied
+     before detach (`scripts/spawn_patch_detach.py`, `measured`);
+   - kernel-level hiding of the field (KPM/eBPF rewrite of the proc read) — §4, `unverified`;
+   - **self-ptrace**: the target ptraces itself so nothing else can (classic anti-anti-debug);
+     works because only one tracer is allowed — but it constrains your tooling to non-ptrace
+     routes anyway. `inferred`.
+2. **A raw `svc` cannot be intercepted from userspace at all.** No PLT, no libc, no hookable
+   symbol. Every plan that says "hook open/read and spoof the maps" silently assumes the target
+   calls libc; a hardened target does not. Verify which one you have before building the spoof:
+   disassemble the check's `.so` and look for `svc #0` (AArch64) / `int 0x80`-era equivalents in
+   the check path (`inferred`; `scripts/native_crash.py`-style capstone disassembly applies).
+
+## 6. What the reference environment chose (and why it generalises)
+
+On the 4.14-kernel reference device, the escalation ladder terminates early — and that is the
+honest outcome (`observed`, from `tools/_phone-modules/README-*.md`):
+
+| Layer | Status on a 4.14 Magisk device |
+|---|---|
+| LSPosed (Zygisk) module hooking | available — framework activation verified by log (`welcome to LSPosed!` lines, `lspd` daemon process) |
+| MT Manager on-device editing/repack/sign | available (`on-device-tooling.md`) |
+| eBPF tracing | closed (kernel gate) |
+| KPM / kernel module route | closed (no kernel source/build for the device; out of scope regardless) |
+| Frida with disguised server | available (a renamed server binary was present on the device from prior work) |
+
+The generalisable rule: **enumerate the ladder for *your* device once, write the one-line
+environment facts, and stop re-deriving them mid-task.** A closed rung is a route decision, not a
+failure.
+
+## 7. When to stop escalating — the decision table
+
+This extends `detection-and-anti-analysis.md` Step 2 with the kernel rung. The repo's stance:
+R3 (never ship or claim an unverified artifact) outranks winning the arms race; a detector you
+defeated with a custom kernel module is not a deliverable anyone can install.
+
+| Situation | Do this | Not this |
+|---|---|---|
+| Check is userspace, hookable, single-site | Neutralise at the site (`native-tamper-and-suicide.md` rules) | Building a hide stack |
+| Check runs before your userspace tool (init_array) | Zygisk-route module, or static patch of the check itself | Earlier userspace attach racing the constructor |
+| Check uses raw syscalls | Static patch of the check; or LSPosed/Zygisk module hooking the consuming code | "Hook libc open/read" (does nothing) |
+| Check detects the *environment* (root/emulator), not your patch | `detection-and-anti-analysis.md` A/B/C — usually a different device or route | Kernel work |
+| You are about to write a kernel module / patch a kernel | Stop. State what is blocked and the evidence; propose the static/module route | Kernel development (out of scope for this skill) |
+| Escalation effort exceeds the user's actual ask | `detection-and-anti-analysis.md` stop signal — switch to static | One more layer |
+
+## Checklist
+
+- [ ] `detection-and-anti-analysis.md` read first; A/B/C chosen deliberately
+- [ ] Check located on the timeline (§1) before choosing a counter-layer
+- [ ] Root scheme's artefacts enumerated (manager/daemon/mounts) before blaming the target
+- [ ] Hiding module: exactly one of Shamiko / Zygisk-Assistant; denylist configured to its spec
+- [ ] Kernel rung checked against `uname -r` — one line recorded if closed
+- [ ] Raw-syscall vs libc-call distinction verified by disassembly before building any spoof
+- [ ] No kernel development undertaken as part of an APK deliverable
diff --git a/skills/apk-reverse/references/lsposed-and-modules.md b/skills/apk-reverse/references/lsposed-and-modules.md
new file mode 100644
index 0000000..20e127c
--- /dev/null
+++ b/skills/apk-reverse/references/lsposed-and-modules.md
@@ -0,0 +1,353 @@
+# LSPosed modules — when to deliver a hook instead of a patched APK
+
+Load this when the honest answer to "patch the APK" is *no*: the target checks its own bytes, derives
+keys from its signature, re-downloads what you removed, or is simply cheaper to hook than to rebuild.
+A module is a different **deliverable**, not a different way to analyse — it changes what you ship, how
+it survives upgrades, and who has to install it.
+
+This file covers the module route end to end: choosing it, the smallest project that works, the
+Gradle-free build chain, deployment and verification, what hides it from the target, and what it
+cannot reach at all.
+
+**Route honesty first.** A module does not modify the APK, so it cannot be "the patched build". If the
+user asked for an installable standalone APK, a module is not that artifact, and this file will not
+make it one.
+
+## Step 0 — pick the route deliberately
+
+Three routes ship three different things. Choose on **who runs it and for how long**, not on which one
+you enjoy more.
+
+| Route | Deliverable | Runs when | Survives target update | Cost |
+|---|---|---|---|---|
+| **Frida** (attach/spawn) | a script, driven by you | while a server process is alive on the device | it does not; you re-run it | lowest to start, highest per-session |
+| **LSPosed module** | an installable APK the user keeps | every process start, automatically, after the module is enabled and scoped | usually yes — the hook targets classes/methods, not offsets | mid: one project, no repackaging of the target |
+| **Repackaged APK** | a modified, re-signed APK | whenever the app runs | no — every update needs rework | highest: integrity, signature, packing, repack |
+
+Reach for a module when **any** of these is true:
+
+- the target verifies its own signature or APK digest, so a repackaged build dies on arrival
+  (`references/signature-derived-keys.md`, `references/native-tamper-and-suicide.md`);
+- the change must persist across restarts without your laptop being attached;
+- attaching a debugger/injector is itself detected, but a startup-time hook is not
+  (`references/detection-and-anti-analysis.md`);
+- you need a Java-level behaviour change only, and the target's own code is reachable from Java.
+
+Do **not** reach for a module when the logic you need lives in native code or in an AOT-compiled
+runtime: see *What this route cannot reach* below.
+
+## What the module can and cannot change
+
+| Layer | Module can reach it? | Where to go instead |
+|---|---|---|
+| Java/Kotlin app code (incl. classes loaded late by a packer's ClassLoader) | yes, once you have the right `ClassLoader` | — |
+| `Application` / `Activity` / framework lifecycle | yes | — |
+| Java SDK internals (OkHttp, ad SDKs, HTTP clients) | yes | — |
+| Pure native logic inside a `.so` | no — Java hooks see only the JNI boundary | `references/native-and-so.md`, `references/native-dbi-and-deobfuscation.md` |
+| Extracted / virtualised dex (instruction-抽取, dex VMP) | no — the original method bodies may not exist as dex at all | `references/advanced-unpacking.md` |
+| Flutter / Dart AOT business logic | no — Dart is not Java; the Java layer only hosts the shell | `references/dart-aot.md` |
+| Behaviour that is *decided* server-side | irrelevant — a hook cannot remove a server rule | `references/server-api.md`, `references/server-config-and-updates.md` |
+
+The Flutter row is the one that most often surprises: hooking every Java entry point in a Flutter app
+still leaves all business logic behind `libapp.so`. Confirm which layer owns your target before
+building a module for it (`references/dart-aot.md`).
+
+## How injection actually works
+
+The mechanism matters because every failure mode below is a consequence of it.
+
+- LSPosed ships as a **Zygisk module** (`zygisk_lsposed`). Zygisk loads into `zygote`, so every app
+  process forked from it is a candidate for injection. [inferred: standard Magisk/Zygisk design]
+- A module is **not** injected everywhere. For each forked process LSPosed asks its daemon (`lspd`)
+  whether this package is in the module's **scope**, and only then loads the module. Scope is therefore
+  the real gate; anything inside the module that filters on package name is a second, weaker gate.
+- Module code is loaded **from memory**, not from a file mapping — the module's dex is read out of the
+  installed APK and handed to an in-memory ClassLoader. This is why a target scanning `/proc/self/maps`
+  for path names finds nothing (`references` below, *What detects you anyway*).
+- The entry point is the class named in `assets/xposed_init`, and it receives
+  `handleLoadPackage(XC_LoadPackage.LoadPackageParam)` **before the application's own `Application`
+  object is attached** — the earliest Java-visible moment in the process. [measured: the injection
+  point is why `Application.attach` and `Activity.onCreate` hooks installed from here fire even under a
+  packer]
+- `LoadPackageParam.classLoader` is the **application's** loader (the packer's stub loader when the APK
+  is packed). It is the handle you use to find classes the app loads later, and it is also the object
+  anti-Xposed code counts — see *What detects you anyway*.
+
+## Minimal module anatomy
+
+Four files. Nothing else is required — no `res/`, no launcher Activity, no permissions.
+
+| File | Why it is required |
+|---|---|
+| `AndroidManifest.xml` with `<meta-data android:name="xposedmodule" android:value="true"/>` | without this key the APK installs as an ordinary app and never appears in the module list |
+| same manifest: `xposeddescription`, `xposedminversion` (`82`) | shown in the manager UI; `82` is the classic XposedBridge API level and is accepted by LSPosed |
+| `assets/xposed_init` | one line: the fully qualified entry class. A typo here produces a module that loads and silently does nothing |
+| the entry class implementing `IXposedHookLoadPackage` | the only class LSPosed instantiates for you |
+
+`scripts/lsposed_scaffold.py` writes exactly this set, plus a README containing the build chain below,
+so the project is reproducible without Gradle:
+
+```sh
+lsposed_scaffold.py --package com.example.probe --name "Example probe" \
+    --hook-target com.example.target --out ./module
+```
+
+The generated entry class logs on **every** scoped process load before anything else, and hooks
+`Application.attach` / `Activity.onCreate`. Both are diagnostics first: the first line proves injection,
+the second names the real Activity classes (under a packer, these are the *unpacked* classes, not the
+manifest's stub).
+
+## Building without Gradle
+
+There is no resource to compile and no dependency resolution to do, so the whole toolchain is five
+commands. [measured on a Windows bench, JDK 17, build-tools 34.0.0, Android API 28 android.jar,
+Xposed api-82 stub jar; end-to-end 5.3 s for a one-class module]
+
+```sh
+BT=/path/to/build-tools/34.0.0
+AJ=/path/to/android.jar          # platforms/android-28/android.jar
+API=/path/to/api-82.jar          # de.robv.android.xposed:api:82
+OUT=build
+
+javac -encoding UTF-8 -source 8 -target 8 -nowarn -cp "$AJ:$API" \
+      -d "$OUT/classes" src/com/example/probe/MainHook.java      # 850 ms
+jar cf "$OUT/classes.jar" -C "$OUT/classes" .                     # 259 ms
+"$BT/d8" --min-api 24 --lib "$AJ" --output "$OUT" "$OUT/classes.jar"   # 1143 ms -> classes.dex
+"$BT/aapt2" link -o "$OUT/base.apk" -I "$AJ" --manifest AndroidManifest.xml \
+      --min-sdk-version 24 --target-sdk-version 28 -A assets      # 126 ms
+cp "$OUT/base.apk" "$OUT/unsigned.apk"
+cp "$OUT/classes.dex" .                                           # must sit next to the apk
+(cd "$OUT" && "$BT/aapt" add unsigned.apk classes.dex)            #  97 ms
+"$BT/zipalign" -f -p 4 "$OUT/unsigned.apk" "$OUT/aligned.apk"     #  76 ms
+"$BT/apksigner" sign --ks mod.keystore --ks-pass pass:android --key-pass pass:android \
+      --v2-signing-enabled true --out "$OUT/module.apk" "$OUT/aligned.apk"   # 1794 ms
+"$BT/apksigner" verify --print-certs "$OUT/module.apk"            # 725 ms -> v2/v3 OK
+```
+
+Four traps, all measured rather than guessed:
+
+- **`d8` rejects a directory.** Pointing it at `build/classes/` fails with *Unsupported source file
+  type*. Jar the classes first and pass the jar.
+- **`aapt add` resolves its argument relative to the current directory and stores the same name.** Run
+  it from the output directory with `classes.dex` present there; a path like `dex/classes.dex` lands
+  inside the APK as `dex/classes.dex` and the module never loads.
+- **`jar` and `keytool` are frequently not on `PATH` even when `javac` is.** Oracle's `javapath` shim
+  exposes only `java`/`javac`; call the JDK's `bin` directory explicitly.
+- **`-bootclasspath` no longer exists on JDK 9+**, so the Android API comes from `-cp` together with the
+  Xposed stub jar. `-source 8 -target 8` keeps the class-file version low enough for `d8`.
+
+The generated README carries the same chain in copy-paste form, including the Windows variants
+(`.bat` wrappers, `;` classpath separator).
+
+## Deploy, enable, and verify
+
+**There are two independent switches.** Getting one right and not the other is the single most common
+"I built a module and nothing happens" report.
+
+| Switch | Where | What it actually controls |
+|---|---|---|
+| package enabled state | `pm enable <module>` / `pm disable <module>` | whether Android allows the package's components to run at all |
+| module enabled | LSPosed Manager (module list) | whether LSPosed loads the module into scoped processes |
+| scope | LSPosed Manager (module → scope) | *which* packages the module is injected into |
+
+[measured: a freshly installed module can be in the module database yet disabled — the package
+manager reported `enabled=0` for the module and `pm enable` flipped it to `enabled=1`, while the
+LSPosed-side enable flag was still 0 in its own database]
+
+A third, device-level gate sits on vendor ROMs: the *install* itself can be intercepted by the ROM's
+security centre. The shape is a shell-identity `pm install` returning a bare `Failure [-99]` while the
+vendor security app takes the foreground, and the **same APK installing cleanly as root**
+(`su -c 'pm install -r <apk>'`). If a module APK "will not install" on a phone that is otherwise
+healthy, try root before suspecting the APK. [measured; the extension record has the transcript]
+
+Verification has **two channels**, and on a device with a broken platform log only one of them works:
+
+```sh
+# 1. the platform log — where the module's line normally appears
+adb logcat -s <TAG>              # then start the target app; do NOT clear the buffer first
+# 2. LSPosed's own module log — where it appears when logd is broken
+adb shell "su -c 'cat /data/adb/lspd/log/modules_<timestamp>.log'"
+```
+
+The expected first line in either channel is the one the scaffold writes on entry — it fires before
+any app code:
+
+```
+<TAG> injected: <target.package>/<process> cl=<loader>@<hash>
+```
+
+[measured] On a device whose `logd` route is broken, channel 1 is **completely empty** — not merely
+`logcat -s <TAG>`, but `logcat -s LSPosed-Bridge` and a full-buffer search for the tag as well — while
+channel 2 shows a complete, successful injection for every process start. A ROM whose LSPosed log
+opens with `Logd maybe crashed (err=Socket operation on non-socket)` is exactly this case, and it had
+nine successful injections in it while logcat showed nothing at all. Debugging with `logcat` alone
+there produces the confident and wrong conclusion "the module never ran".
+
+Decision order when that line is missing — stop at the first hit:
+
+1. module enabled in LSPosed Manager?
+2. target package present in the module's **scope**?
+3. module APK still installed (`pm path <module>`)?
+4. **was the target process started after the scope change?** Scope is read for newly forked
+   processes; a process that was already running keeps the decision it got at fork time.
+   [external, matches LSPosed behaviour reported independently: a scope change takes effect on the
+   target's next start, no device reboot required — 看雪 thread-291750]
+
+The LSPosed-side state is inspectable from a root shell:
+
+| Path | Contents |
+|---|---|
+| `/data/adb/lspd/config/modules_config.db` | SQLite: `modules(mid, module_pkg_name, apk_path, enabled)`, `scope(mid, app_pkg_name, user_id)`, `configs(...)` [measured] |
+| `/data/adb/lspd/log/` | `modules_<timestamp>.log`, `verbose_<timestamp>.log`, `kmsg.log`, `props.txt` [measured] |
+| process `lspd` | the daemon that serves scope decisions; it is a separate process from the target [measured] |
+
+Two measured caveats about that log directory, because both waste time:
+
+- `modules_*.log` **is** the module log: it is the file LSPosed appends your `XposedBridge.log()` lines
+  to. It may *also* contain `Logd maybe crashed (err=Socket operation on non-socket), retrying in 1s...`,
+  which means the platform log channel is unavailable — not that your hook failed. Check this file
+  **and** `logcat -s <TAG>`; a device can deliver one and not the other. [measured: nine successful
+  injections were in this file while logcat showed nothing]
+- `verbose_*.log` is a *logcat snapshot* that includes the whole system, so it is useful for
+  correlating a system-side event with your run, and useless as a module log.
+
+**Do not kill `lspd` to force a configuration reload.** [measured] On the bench it is started by
+`/data/adb/modules/zygisk_lsposed/service.sh`, which runs `unshare -m sh -c "$MODDIR/daemon --from-service &"`;
+the `daemon` script ends in `exec /system/bin/app_process ... org.lsposed.lspd.Main`. Magisk runs
+`service.sh` once per boot, so an externally killed `lspd` is not restarted by anything you can see
+from a root shell. The consequence is worse than a dead daemon: newly forked processes stop getting
+scope decisions. Configure scope through the manager, which talks to the running daemon.
+
+The same reasoning applies to editing `modules_config.db` by hand: the file is the daemon's
+**persisted** state, while the decisions actually served to `zygote` come from the daemon's live copy.
+A hand-edited row is not wrong — it is simply not read until the daemon reloads it, and there is no
+supported way to make it reload. [inferred from the storage layout and the daemon lifecycle; the
+manager path is the one that updates both]
+
+## Hiding the framework from the target
+
+Injecting a Java hook is trivial to detect **if the target is allowed to see the root/Zygisk
+environment at all**. On a rooted device the hiding layer is a separate module, and the two common
+choices differ in exactly one operational detail: how they learn which apps to hide from.
+
+| | Zygisk Assistant | Shamiko |
+|---|---|---|
+| source | open | closed-source, LSPosed project |
+| target selection | Magisk **DenyList** entries (or KernelSU profiles); no UI of its own | also reads Magisk's DenyList, **but requires DenyList enforcement to be OFF** |
+| extra mode | — | creating `/data/adb/shamiko/whitelist` switches to whitelist mode without a reboot; documented as costly in memory/performance and test-only |
+| mechanism | unmounts root-related paths and masks Zygisk presence for the selected process | same family of process-level hiding, plus its own mount/`maps` handling |
+
+[external: Zygisk Assistant module description and Shamiko README]
+
+**The DenyList/enforcement distinction is where people lose afternoons.** Enforcement is Magisk's own
+feature that unmounts Magisk-provided files for listed processes; the *list* is shared, the *enforcement
+toggle* is not the same thing. Shamiko wants the list without enforcement; Zygisk Assistant is
+documented to work with the list as configured.
+
+[measured on the bench: the DenyList was **enforced but empty** — `magisk --denylist status` reported
+`Denylist is enforced`, `magisk --denylist ls` printed nothing, `/data/adb/shamiko` did not exist, and
+Zygisk Assistant v2.1.4 was installed. So on that device nothing was being hidden from any app, while
+LSPosed and `lspd` were running normally. If a target seems to know it is on a rooted device, check
+this before blaming the module.]
+
+Practical rules:
+
+- **Keep the scope minimal.** Every extra scoped package is both an extra place your hook can break
+  something and an extra ClassLoader in that process (next section).
+- Hiding and hooking are separate problems. A module that is perfectly hidden can still be detected by
+  the ClassLoader count; a target that never checks cannot see either.
+- If the target is the *only* app you care about, scoping to it alone is both the smallest blast radius
+  and the least observable configuration.
+
+## What detects you anyway
+
+Traditional Java-level anti-Xposed checks — `Class.forName("de.robv.android.xposed.XposedBridge")`,
+exception-stack scanning for Xposed frames, reflection on `findAndHookMethod`, enumerating
+in-memory-ClassLoader instances — are all **query interfaces**, and hiding layers exist precisely to
+falsify their answers. They are no longer a reliable signal that a module is present or absent.
+
+The check that does not depend on a query interface is the **ClassLoader count**. [external: 看雪
+thread-291750, which reports a clean baseline of 3 versus 12 with a module injected, threshold ≥9; the
+original idea is traced there to thread-289567]
+
+The reason it works, in one paragraph: ART's `ClassLinker` keeps a `class_loaders_` list of every live
+ClassLoader, and that list is part of GC reachability. A module's loader must stay on that list or the
+GC will collect the module's code and the hook dies. So a module cannot both remain alive and be absent
+from a structure the runtime itself walks. Hiding layers can fake lookups; they cannot remove a node
+from a GC-traversal list without unloading the module.
+
+The same source reports two further native-side traces of the same injection, which are worth knowing
+because they are independent of ClassLoader counting: the module's dex shows up as **anonymous
+executable memory** (it is loaded from memory, so no file mapping exists), and Zygisk's patching of
+`libart` leaves **private-dirty pages** in the library's executable segments.
+
+Engineering consequences for anyone choosing this route:
+
+- **Scope discipline is detection hygiene.** Fewer scoped packages means fewer injected processes; a
+  multi-module stack inflates the same count. The number is per-process, so a clean device elsewhere
+  does not help this process.
+- **A count check needs a calibrated baseline.** On complex hosts (WebView, split APKs, plugin
+  frameworks, other modules) the clean count is already high, and the threshold has to be measured per
+  host, never copied. [external: same source]
+- **Detection of the framework is not the same as detection of your change.** If the target reacts to
+  the count by refusing to run, that is an environment finding to report
+  (`references/detection-and-anti-analysis.md`), not something to escalate against indefinitely.
+- If the target's check is native and inline-hooks *your* detector's counterpart, you are in DBI
+  territory: `references/native-dbi-and-deobfuscation.md`.
+
+## LSPosed vs Frida — the division of labour
+
+They are not competitors; they are the two answers to "how long must this hook exist".
+
+| Need | Frida | LSPosed module |
+|---|---|---|
+| Understand a flow once, now | **yes** — interactive, no build step | no: build + install + restart per iteration |
+| Ship something that works every launch, unattended | no: needs a server process | **yes** |
+| Hook a `.so` function directly | **yes** (`Interceptor`, Stalker) | no: Java hooks stop at JNI |
+| Survive a target that kills external injectors | weak: `ptrace`-based attach is the thing being detected | **stronger: no external process, no attach, no port** |
+| Replace a method's return value in app code | yes | yes |
+| Be re-runnable after a target update | yes (re-attach) | usually yes (class/method names auto-update far better than byte offsets) |
+| Need no root on the target device | no | no |
+
+The productive pattern is to use **both in sequence**: Frida to discover which class and method matter
+and what the real call chain is (`references/dynamic-frida.md`), then a module to make that finding
+permanent without touching the APK. Rebuilding a module for every question is the expensive way to
+explore; exploring with an interactive script and only then writing the module is the cheap way.
+
+A third option exists when the goal is *calling* target code rather than changing it — exporting a
+native function over RPC: `references/emulation-and-rpc.md`.
+
+## Failure modes
+
+| Symptom | Most likely cause | Check |
+|---|---|---|
+| module never appears in the manager | `xposedmodule` meta-data missing/mistyped after manifest merge | `aapt2 dump xmltree` the built APK, or re-read the manifest |
+| module listed, no `injected:` line in either channel | module disabled in manager, package not in scope, **target process not restarted** after the scope change, or you looked at only one channel | the four-step order above, then the two-channel check |
+| the platform log is empty but the module log is not | the ROM's `logd` route is broken; the module is working | the tell is `Logd maybe crashed (err=Socket operation on non-socket)` at the top of the module log |
+| `injected:` line present, but `TARGETS` gate skips the process | in-module gate, not the framework | read the module's own log line, then its gate |
+| hook installed, method never fires | wrong class/loader: packers and plugin frameworks hold several ClassLoaders | resolve the loader at runtime; enumerate `/proc/<pid>/maps`-independent evidence via `references/dex-patching.md` |
+| target dies right after injection | target side: ClassLoader counting or anonymous-memory heuristics (above); device side: ROM behaviour | instrument-free control run first (`references/detection-and-anti-analysis.md`) |
+| `pm enable` had no effect on injection | `pm` state and LSPosed state are different switches | the two-switch table above |
+| `d8` fails on a directory / `aapt add` cannot find the dex / `keytool` not found | build-chain traps, all three measured | the four traps above |
+
+## Verification for the record
+
+- which module APK, its hash, and what it was built from (scaffold output or hand-written);
+- the build commands and whether `apksigner verify` passed;
+- `pm path`/`dumpsys package` output for the module (installed, enabled state);
+- the scope list actually configured;
+- the target process start time relative to the scope change;
+- the module's logcat lines, in order, showing injection and any hook installs;
+- whether the target misbehaved, and the instrument-free control result for the same build.
+
+## See also
+
+- `references/dynamic-frida.md` — the exploration half of the workflow above
+- `references/detection-and-anti-analysis.md` — when the target fights back and when to stop
+- `references/native-and-so.md`, `references/native-dbi-and-deobfuscation.md` — the layer a Java hook stops at
+- `references/dart-aot.md` — the layer that owns a Flutter app's logic
+- `references/advanced-unpacking.md` — extracted dex and the VMP boundary
+- `references/repack-and-sign.md`, `references/signature-derived-keys.md` — what you are avoiding, and why it is sometimes unavoidable
+- `references/on-device-tooling.md` — MT Manager and the rest of the on-device kit
+- `references/verification.md` — what "done" means, including the control-build rule
+- `scripts/lsposed_scaffold.py` — generates the project skeleton described here
diff --git a/skills/apk-reverse/references/native-dbi-and-deobfuscation.md b/skills/apk-reverse/references/native-dbi-and-deobfuscation.md
new file mode 100644
index 0000000..752b87d
--- /dev/null
+++ b/skills/apk-reverse/references/native-dbi-and-deobfuscation.md
@@ -0,0 +1,271 @@
+# Native DBI and deobfuscation
+
+**Load this when static disassembly of a `.so` has stopped producing information** — an exported
+function decompiles into a dispatcher loop and arithmetic soup, a symbol you need has no name, or you
+must answer "what actually ran" instead of "what could run". This file covers instruction-level
+dynamic tracing: what a trace can and cannot decide, how to record one with the scripts in
+`scripts/`, and where it hands off to emulation and symbolic execution.
+
+**Hand-off.** `native-and-so.md` owns the APK-side conclusions about a library — which `.so` is
+loaded, which ABI is executing, whether a hook can observe anything, how to neutralise a terminate
+path by returning. This file owns execution-level evidence. If the question is "did my patch cause
+the death", that is `native-and-so.md` and `native-tamper-and-suicide.md`; if it is "which blocks did
+this function really execute, and how often", it is here.
+
+**Claim strength.** `measured` = an exact command and its output exist in
+`docs/tool-verification/EXTENSION-native-dbi.md`. `inferred` = it follows from measured behaviour or
+from documented behaviour of the tool. `unverified` = reported by someone else or reasoned from
+first principles without a run. The distinction matters more here than usual, because the honest
+result of this pass is that **the trace pipeline is unverified on the test device** — see §6.
+
+## 1. Which obfuscation are you looking at
+
+Obfuscator-LLVM ships three transforms, and one target usually carries all three. Identify by
+**which one made static reading fail**, because each is undone by a different observation.
+
+| Transform | Static shape | Dynamic signature | What removes it |
+|---|---|---|---|
+| **Control-flow flattening** | One dominator block at the top of the function, reached from everywhere; a state variable (register or stack slot) assigned a constant before each jump back; a `switch`/jump table dispatch; the original block order is gone | The dispatcher block dominates the execution histogram by a wide margin; real blocks appear between dispatcher entries; execution sequence looks like `D R1 D R2 D R3 D` | Trace histogram + the state variable's constants: each dispatcher entry is preceded by a store of the next real block's id |
+| **Bogus control flow (opaque predicate)** | A branch whose condition is algebraically constant (`(x*x) >= 0`, `x*x % 2 == 0`), with a junk block on the impossible side; junk blocks reference unreachable names | The junk branch **never appears** in the trace at all: not once, at any input | Trace absence, and then dead-code deletion of the never-taken side. Absence in a trace is only evidence if the trace covers the input that would take it |
+| **Instruction substitution** | Arithmetic that is correct but unrecognisable: add chains with negated constants, `xor`/`and`/`or` rewrites of a comparison, MBA identities | The function's **result** is still correct at its boundary, and the single-step value at a known point (e.g. the return register) matches the un-obfuscated expectation | Symbolic execution or a brute-force input sweep; a trace alone does not simplify arithmetic |
+
+Worked example of the distinction: a flattened function with substituted instructions produces a
+trace whose histogram has an obvious top, but the arithmetic between dispatcher entries still tells
+you nothing. Flattening is a **control**-flow problem and the trace answers it; substitution is a
+**data**-flow problem and needs §5.
+
+**Reported, not verified here:** a community write-up of this exact pipeline — trace, aggregate,
+solve with a symbolic executor, patch the binary — is
+[基于动态指令追踪与符号执行对抗OLLVM控制流平坦化的工程化实践](https://cloud.tencent.com/developer/article/2721228)
+(cloud.tencent.com/developer/article/2721228, published 2026-08-05). It reports, on a 2,800-block
+x64 fixture: 15 s of tracing ≈ 220 MB of raw log, aggregation to 48 KB of block records, ~12 min of
+parallel symbolic execution resolving 67 dispatcher targets, and 1.2 s of binary patching over 147
+sites. **Those numbers are the author's, on a Windows x64 DLL, and were not reproduced here** —
+treat them as an order-of-magnitude sketch for the data-reduction ratio (raw log to block table is
+roughly 4000:1 there), not as a budget for an arm64 Android target. The article's code snippets are
+illustrative rather than runnable: its `onReceive` handler indexes parsed events by field name
+(`item.kind`, `item.start`), while `Stalker.parse(..., {stringify: false})` returns **positional
+arrays**. Take the method from that article; take the API shape from this repository and from the
+script header in `scripts/stalker_trace.js`.
+
+## 2. Pick the observation before you pick the tool
+
+| Question | Observation | Tool |
+|---|---|---|
+| Which blocks executed, and how often? | Block-level trace with execution counts | `scripts/stalker_trace.js` + `scripts/stalker_report.py` |
+| Which functions inside the module call each other? | Call edges from the same trace | same pair (`call` events) |
+| Which imported function does this stub reach? | Relocation table, not trace | `scripts/elf_plt.py` |
+| Where did the process die, and did it look arranged? | Crash record, signal, fault address, backtrace split by owner | `scripts/native_crash.py` |
+| What value must the state variable have to reach block X? | Constraint solving over the dispatcher | angr / Triton (§5) |
+| What is the value at a specific point for a specific input? | Deterministic per-instruction replay with memory operands | QBDI (§4) |
+| What does this code do with no device at all? | Emulation of the `.so` with a synthetic environment | unidbg / Unicorn / QEMU |
+
+The first two rows are one run of one script — take both. `elf_plt.py` and `native_crash.py` are not
+competitors here: they answer a symbol and a death respectively, and both work when no trace can be
+taken at all.
+
+## 3. Recording a trace with `scripts/stalker_trace.js`
+
+Frida Stalker recompiles every basic block a followed thread executes and hands the events back to
+JavaScript. It needs no symbols, no source and no disassembler on the host, which is exactly why it
+works on stripped OLLVM output.
+
+**Three rules, each one a failure mode if broken**
+
+1. **Follow one trigger, not the whole process.** An unrestricted follow of a busy thread produces
+   gigabytes and slows the target down until it dies.
+2. **Filter to one module.** `targetModule` is the only module whose blocks are reported; call edges
+   report when either end is inside it. Filtering happens on the device, not in post-processing,
+   which is what keeps the log usable.
+3. **Cap the volume.** `maxBlocks` stops the trace instead of letting the log eat the disk, and the
+   `DONE` line records whether truncation happened.
+
+**Configuration** (edit `CONFIG` in the script, or override at runtime through `rpc.exports.config`
+/ `script.post({type:'cfg', payload:{...}})`):
+
+| Key | Meaning |
+|---|---|
+| `targetModule` | the one `.so` whose blocks are reported |
+| `trigger` | `{kind:'export', module, export}` — start on a named export (a JNI function is the classic); `{kind:'offset', module, offset}` — start at module-relative offset; `{kind:'java', cls, method}` — start at the Java→native boundary; `{kind:'main'}` — follow the thread right after load |
+| `followMs` | hard stop, so a forgotten trace cannot kill the process |
+| `maxBlocks` | event cap; the `DONE` line reports truncation |
+| `events.compile` | first translation of each block — deduplicated block set in first-visit order |
+| `events.block` | every executed block — the execution histogram |
+| `events.call` | call edges |
+| `events.exec` | **per instruction; enormous.** Enable only around a known point |
+| `events.ret` | return edges |
+
+**Customising what gets translated (`transform`).** Event flags shape *what you are told*; the
+`transform` callback shapes *what runs*. It fires before a block is translated and receives the
+instruction iterator, so it can rewrite the code Stalker is about to execute — inline a counter at one
+call site, neutralise a logging call inside a hot loop, or substitute a value at the one address you
+care about. Reach for it when the question is "is this site reached, and how often" rather than "which
+blocks ran"; do not reach for it when the answer must be an observation, because a transform changes
+the process's behaviour and stops being passive measurement. Two properties to respect: it can run
+once per block per thread, so any rewrite must be idempotent, and the rewritten bytes are the DBI's
+copy, so a crash inside them will not point at a file offset. `inferred`: `scripts/stalker_trace.js`
+uses events and `onReceive` only; the transform route is documented here, not exercised by this
+repository's pass.
+
+**Running it.** With the bundled injector, which writes every event to a log file *and* stdout:
+
+```
+python scripts/run_probe.py scripts/stalker_trace.js 1 --pkg <pkg> --via usb --log trace.log
+```
+
+With any driver that speaks Frida's rpc, so no file edit is needed:
+
+```js
+script.exports.config({ targetModule: 'libapp.so',
+                        trigger: { kind: 'offset', module: 'libapp.so', offset: 0x9f6c0 },
+                        followMs: 3000, maxBlocks: 50000 });
+script.exports.start(<tid>);   // follow this thread
+script.exports.status();
+script.exports.stop();
+```
+
+Pass `start(tid)` explicitly rather than relying on the default. **`Process.getMainThreadId()` is
+not the Android main thread in practice**: on the measured run below, a process with pid `19938` was
+followed on tid `25606`, and an idle-looking thread produced zero events. On Android the main thread
+tid equals the pid, which is the value to start from.
+
+**Output grammar** (one logical line per event; `scripts/stalker_report.py` parses it, including
+logs where each line is wrapped by `run_probe.py` as `[host ts] [dev ts] TRACE ...`):
+
+```
+READY ...            config echo and module status; nothing works before it
+MOD name base=0x.. size=.. path=..
+BB <seq> <mod>+0x<offset>            block first translated (dedup'd skeleton)
+BLK <seq> <mod>+0x<offset> [size=n]  block executed (histogram input)
+CALL <depth> <from> -> <to>          call edge
+DONE reason=timeout|trigger-leave|maxBlocks|stop-rpc blocks=n blk=n calls=n truncated=0|1
+FATAL / TRIG-FAIL                    what did not install and why; the script keeps running
+```
+
+**Reducing the log**
+
+```
+python scripts/stalker_report.py trace.log --top 30 --skeleton 80 --edges 15 --json report.json
+```
+
+Four reductions, each answering a different question: the **execution histogram** (top of the list =
+dispatcher candidate), the **first-visit order** (deduplicated block set ≈ CFG skeleton with the
+flattening state machine stripped out), the **call-edge table** (module-internal communication with
+no symbols), and the **collapsed execution sequence** (`block*N -> block -> ...`, which is where the
+`D -> R -> D -> R` flattening rhythm becomes visible).
+
+Diagnostics the report prints, and what they mean:
+
+- `DONE ... truncated=1` — the trace hit `maxBlocks`. Ratios remain useful; **absolute counts do
+  not**, and a claim about a dispatcher's multiplicity must be re-measured with a higher cap.
+- `zero BLK with nonzero BB` — the thread was translated but executed nothing in-window: the window
+  closed, or the trigger returned immediately.
+- `zero BB and zero BLK with DONE present` — the module never ran on the followed thread. Change the
+  thread or the trigger; do not tune the follow time.
+- Everything zero **and no `DONE`** — the trace never started. Read the `READY` / `TRIG-FAIL` lines
+  first; that is a plumbing problem, not an analysis result.
+
+## 4. Stalker, QBDI, or emulation
+
+| Situation | Choice | Why |
+|---|---|---|
+| Need block-level coverage and execution counts on a real device, no per-instruction semantics | **Stalker** | Cheapest to start, no host toolchain, works on code with no symbols |
+| Need per-instruction values, memory operands, or a deterministic replay that can be re-run at a recorded PC | **QBDI** (QuarkslaB Dynamic Binary Instrumentation), via its Frida binding | An independent DBI engine with its own register/memory API; the trace is a program, not a log. It instruments at a different layer than Stalker, which matters on ART: Stalker translates the code it sees, QBDI exposes the instruction stream and its operands directly |
+| Need to hurt the target as little as possible while instrumenting a hot path | **QBDI** | Deterministic, no reliance on the app's own JIT/AOT output |
+| Need a result with **no device and no app process** — a hardened sample refuses to run, or the algorithm must be called thousands of times | **Emulation** (unidbg, Unicorn, QEMU) | Runs the `.so` in a synthetic environment with JNI stubs; completely different trade-off (environment fidelity for scale) |
+| Need "what input reaches block X" rather than "what happened for input I" | **Symbolic execution** (§5) | A trace is one path; a solver enumerates the condition |
+
+**Stalker and ART do not compose for free.** The followed thread's code can be recompiled by ART's
+JIT while Stalker has already translated it, and a block's address is only meaningful inside one
+process lifetime. Practical consequences: keys in a log are `module+offset` and stay comparable
+across runs only for code that is mapped from file; do not compare a `libart`-materialized block
+address between two runs; and never place a follow/unfollow pair on a hot function (measured failure
+in §6).
+
+## 5. From a trace to a deobfuscated function (inferred)
+
+This is the part the community write-up above also describes, and it is **inferred** here — the
+trace end was not reproducible on the test device, so the steps below are a method, not a record.
+
+1. **Find the dispatcher.** Rank by execution count. In a flattened function the dispatcher runs
+   once per real block; loops multiply it further. A block that is (a) at the top by a wide margin,
+   (b) entered from many distinct predecessors, and (c) followed by many distinct successors, is the
+   dispatcher. `stalker_report.py` prints exactly the three items needed to check that.
+2. **Find the state variable.** Disassemble the dispatcher entry window statically (the offset is in
+   the trace, so no symbol is needed). Look for the register or stack slot written immediately
+   before the indirect branch; in flattened output this is the value the dispatch table is indexed
+   by. If more than one candidate exists, correlate: the state variable is the one whose written
+   constants match the distinct block ids seen in the trace.
+3. **Recover the real CFG.** Convert the flat sequence into edges: `dispatcher → real block →
+   dispatcher`. The real blocks' order and repetition come from the trace; the state constants come
+   from step 2; the mapping `state value → real block` turns the dispatcher into a jump table you
+   can then remove in the binary (the LIEF step in the write-up).
+4. **Solve what the trace did not cover.** A trace is one input's path. For a state value you never
+   observed, symbolically execute the dispatcher **only** (a few tens of bytes: load the state,
+   bounds-check it, index the table) rather than the whole function. This is where angr or Triton
+   earns its cost: the entry point is the dispatcher offset the trace gave you, and the goal is the
+   table index, not the program's semantics. Reported pitfall from the same write-up, worth repeating
+   because it is structural: OLLVM inserts transitions that land outside the table, so prune states
+   whose index exceeds the table bound instead of letting the solver chase them.
+5. **Only then patch the binary.** Direct-branch rewriting must respect instruction length: an
+   absolute jump needs more bytes than the `mov; jmp` pair it replaces, so pad rather than move
+   anything. `scripts/elf_plt.py` is the tool that tells you what a rewritten site actually reaches
+   (by relocation, not by position), and a byte-diff of two builds is how you prove your patch set is
+   what you think it is.
+
+## 6. Failure modes
+
+**Zero events, follow installed (measured, cause unverified).** With host frida 16.7.19 and a
+matching on-device frida-server 16.7.19 on Android 11 / arm64, `Stalker.follow` on a main thread for
+4 s produced `blocks=0 blk=0 calls=0` on two different system processes, and an `export`-triggered
+follow produced `reason=trigger-leave blocks=0` on every one of hundreds of firings. Every line
+before that was healthy: `READY`, `TRIG following tid=…`, `MOD libc.so base=0x…`. The conclusion to
+carry forward is narrow and should not be widened: **on that combination, follow installs but events
+do not arrive in `onReceive`.** It is not a licence to assume Stalker is broken everywhere, and not
+evidence about any other ROM, frida version or target. Validate the pipeline before trusting a zero
+result: follow a thread you control executing a known loop, and confirm nonzero `BLK` lines.
+
+**High-frequency follow/unfollow crashes the target (measured).** Using a hot libc export as the
+trigger — every call starts a follow and every return ends it — a system UI process died with
+`SIGSEGV` after hundreds of cycles; the crash record's frame `#00` sat in an anonymous region (the
+DBI's code cache) and the return address led into `libart`. The process restarted under a new pid.
+The lesson is not "Stalker is unsafe"; it is **do not use a hot function as a follow trigger**, and
+do not build a follow/unfollow cycle per-call in a hot path. A single follow of a chosen thread for a
+bounded window is the shape that works.
+
+**The device becomes the experiment (measured).** While this pipeline was running, the test device's
+`load average` reached `34.11` on an 8-core mid-range phone, and a co-running dynamic job on the same
+phone (a dex-dumping attach belonging to another task) was destroyed mid-flight. On a shared device
+these are not independent experiments: one heavy DBI run makes every other dynamic result
+unattributable. Announce the window, keep `followMs` in the low seconds, cap `maxBlocks`, never spawn
+when attach is enough, and treat a `script has been destroyed` in a *different* job as a signal that
+your load — not that job's code — is the variable. This is `long-task-discipline.md` §single-variable
+discipline applied to hardware.
+
+**A trace of a VM is a trace of the interpreter.** If the target is a virtualized function (private
+bytecode executed by a handler loop), Stalker will happily report the interpreter's blocks: a huge,
+flat, repetitive histogram around one dispatch loop. That is a valid finding — it tells you the code
+is virtualized — but it is **not** the guest program's control flow. Recovering that needs handler
+identification and a private opcode table; see
+`code-virtualization-and-custom-linkers.md`, and do not present an interpreter trace as the
+deobfuscated function.
+
+**Instrumentation was detected before you started.** If the process dies when you attach, refuses to
+run under root, or the module you want is never loaded while attached, the problem is upstream of
+this file: read the first section of `detection-and-anti-analysis.md` before escalating the trace,
+because the cheap answer is usually to switch to static analysis with `elf_plt.py` and
+`native_crash.py`, not to fight the detector.
+
+## 7. Reporting what a trace proves
+
+- A trace proves **what executed on the followed thread inside the followed window**. It does not
+  prove absence: `BB` never appearing means it did not run *for that input, in that window* — which
+  is meaningful for an opaque-predicate junk block only when the rest of the analysis says the input
+  would have taken it.
+- Counts are evidence only when `truncated=0`. State the cap.
+- A dispatcher identification is a hypothesis about a block's role. Confirm it by disassembling the
+  block and finding the table it indexes; a high count alone is also what a spin loop or a memory
+  allocator's fast path looks like.
+- Write the product's before/after into `docs/tool-verification/`, with the exact command, the
+  module, the offsets, and the strength label. The next person's first question is "was the pipeline
+  known to work when you got that zero", and the answer belongs in that record, not in a footnote.
diff --git a/skills/apk-reverse/references/on-device-tooling.md b/skills/apk-reverse/references/on-device-tooling.md
new file mode 100644
index 0000000..28a51c7
--- /dev/null
+++ b/skills/apk-reverse/references/on-device-tooling.md
@@ -0,0 +1,142 @@
+# On-device tooling — MT Manager, APK MCP, LSPosed, Termux
+
+Sometimes the PC is the wrong place to work: the device already has the APK installed, the edit is
+one string, the target is a 38 MB repack you would otherwise push back and forth, or there simply
+is no laptop in the loop. This file covers the **on-device toolchain** and — more importantly —
+when each tool beats its PC counterpart and when it does not.
+
+Evidence basis: the facts below come from a real configured environment (Android 11, Magisk +
+Zygisk, LSPosed v1.9.2, MT Manager 2.26.9), archived in `tools/_phone-modules/`. Framework
+activation and the module set are `observed` there; per-workflow usability notes are `measured`
+where marked, otherwise `inferred`. The MT MCP tool surface is from MT's official documentation
+(`observed` as a list; live invocation requires the service to be running — see §2).
+
+## 1. MT Manager as a reverse-engineering workbench
+
+MT Manager (`bin.mt.plus`) is a file manager plus APK editor. For this skill's purposes it is a
+**complete repack pipeline that runs on the phone**: view, edit, rebuild, sign.
+
+What it covers, mapped to this skill's workflow stages:
+
+| Skill stage | MT capability | Notes |
+|---|---|---|
+| Recon (manifest, SDKs) | APK viewer: manifest, entry list, string search across dex/resources | String search is the fast path; no full Java decompile in the editor workflow |
+| Dex reading/editing | Dex viewer + smali-level editing | Smali is the editing granularity — same discipline as `dex-patching.md` |
+| Removing signature verification | Built-in "去除签名校验" (signature-check killer) feature | Convenience feature; audit what it actually patched — a Java-layer signature killer can be a decoy while a native check still kills you (`code-virtualization-and-custom-linkers.md` §decoy) |
+| Extracting artifacts | Pull `classes.dex`, `.so`, `resources.arsc`, axml out of any APK/zip | Useful to move a single `.so` to the PC toolchain without a full unzip |
+| Repack + sign | Rebuild APK and sign it on device | Output lands in MT's working directory; verify with the same discipline as `repack-and-sign.md` (alignment, `resources.arsc` rules still apply — the platform enforces them regardless of which machine built the file) |
+
+**When MT beats the PC pipeline:** quick single-file edits, on-the-spot verification on the same
+device the app is installed on, and sessions where shuffling 40 MB APKs over USB dominates the
+work. **When the PC wins:** anything scriptable/repeatable, dex-wide cross-referencing
+(`find_refs.py`), byte-precision patching with header recomputation, and anything needing a real
+decompiler. The honest split: MT for **breadth on device**, PC for **depth and repeatability**.
+`inferred`.
+
+## 2. MT's built-in APK MCP server
+
+MT 2.26.9+ ships an "APK MCP" service: it exposes MT's analysis and modification capabilities to
+an MCP (Model Context Protocol) client — which in practice means an AI agent drives MT's tooling
+over HTTP while the human sees the results on the phone. The official framing: AI understands the
+request and calls the tools; MT does the local read/modify/repack/sign.
+
+**Transport and endpoint** (`measured` on the reference environment):
+
+- Streamable HTTP MCP at `http://127.0.0.1:8787/mcp` from the PC, via `adb forward tcp:8787
+  tcp:8787`; or directly `http://<phone-ip>:8787/mcp` on the LAN.
+- **The service must be started by hand in the MT UI** (side drawer → Tools → APK MCP → Start).
+  adb cannot start it. Before it is started, the port is simply not listening — probe with
+  `scripts/mt_mcp_probe.py`, which prints waiting instructions in that state.
+
+**Tool surface** (official documentation; names observed from the published list):
+
+| Category | Tools |
+|---|---|
+| Open/selection | `mt_apk_list_available_apks`, `mt_apk_open` |
+| Reading/search | `mt_apk_list`, `mt_apk_search`, `mt_apk_read_text`, `mt_apk_read_bytes`, `mt_apk_continue` |
+| Dex analysis | `mt_apk_dex_outline_class`, `mt_apk_dex_xref` |
+| Resources | `mt_apk_resource_read`, `mt_apk_resource_xref` |
+| Native static | `mt_apk_native_inspect`, `mt_apk_native_read_items`, `mt_apk_native_map_address`, `mt_apk_native_xref`, `mt_apk_native_disassemble`, `mt_apk_native_function_cfg` |
+| Modification | `mt_apk_edit_open`, `mt_apk_edit_text`, `mt_apk_edit_resource`, `mt_apk_patch_bytes`, `mt_apk_native_patch_instructions`, `mt_apk_native_patch_string`, `mt_apk_edit_check`, `mt_apk_build` |
+| Cleanup | `mt_apk_close` |
+
+**Official constraints — budget your plans around these, not around hopes:**
+
+1. **No Java decompilation.** The stated position: AI reads smali directly; decompiled Java of
+   hardened/R8'd code misleads more than it helps. Cross-references (`dex_xref`) and class
+   outlines are the structural view.
+2. **`resources.arsc`: existing entries only.** No new locales or new entries — edit what ships,
+   do not plan feature-additions through arsc.
+3. **`.so` support is static analysis only.** No dynamic execution, no emulation, no C/C++
+   pseudocode. Xrefs and CFG are "best-effort within a limited budget" — direct static results,
+   **not** proof of a complete call chain or of runtime behaviour. For depth, the PC side (IDA/
+   Ghidra-class, see `toolchain.md`) remains the answer.
+
+**Handing an APK to the server** (three supported ways): open an APK in MT's file list and stay
+on its info dialog ("the current APK file"); open an installed app's info dialog the same way; or
+drop the APK into MT's configured MCP working directory and refer to it by filename/package. The
+working directory is also where rebuild output lands.
+
+**Probing from the PC:** `python scripts/mt_mcp_probe.py` does the full JSON-RPC handshake
+(initialize → initialized → tools/list) with no MCP SDK dependency and prints a grouped tool
+inventory. If MT's MCP has not been started in the UI, it exits with waiting instructions and
+code 2 — usable as a loop check ("is it up yet") while you start it by hand. `measured`.
+
+## 3. LSPosed Manager — the module route on device
+
+LSPosed (via Zygisk) gives you a **Java-layer hook platform that needs no PC at runtime**: write/
+install a module once, and it applies to target apps at every launch.
+
+Facts from the reference environment (`observed`, archived in `tools/_phone-modules/`):
+
+- Activation is verifiable from logs: the `ZygiskCompanion: welcome to LSPosed!` banner, the
+  version line, the `lspd` daemon process running as system.
+- Install discipline: `magisk --install-module` unpacks to `/data/adb/modules_update/` and only
+  **merges after a reboot** — a module that "did not install" is usually one that has not merged
+  yet. `ls /data/adb/modules/` is the truth; `modules_update/` non-empty means pending.
+- Zygisk itself needs one reboot after being enabled before its injection layer exists at all.
+
+Limits that matter for this skill: LSPosed hooks **Java/ART** — it cannot hook inside a native
+`.so` (that is Frida/IDA territory, and the reason `framework-runtimes.md`'s runtime check
+exists), and it does nothing for Flutter/Dart AOT logic below the platform channel. Use it for
+the layer it owns: Java API interception, intent/telemetry rewriting, feature gates that live in
+Java. A hook module is also **not a deliverable** for a request that wants an installable APK —
+it is an environment change on your device (`detection-and-anti-analysis.md` Step 4 keeps these
+separate).
+
+## 4. Termux + frida-server — device-side dynamic analysis
+
+The phone can run the whole dynamic stack alone: Termux (or a plain root shell) hosts
+`frida-server`, and scripts run through Termux's own Python.
+
+- **frida-server version must match the PC-side frida tooling** when the PC is also in the loop
+  (`dynamic-frida.md` owns this). Device-only operation still needs a matching `frida` client in
+  Termux.
+- **Disguise the server when the target hunts it**: a renamed binary and a non-default port are
+  the minimum; a detection-savvy target scans process names and default ports. The reference
+  environment carried renamed server copies from prior work — the technique is standard, and the
+  detection mechanics are `kernel-and-environment-hardening.md` §1.
+- **32/64-bit**: a `zygote64_32` device runs both ABIs; make sure the frida-server architecture
+  matches the process you are attaching to (`environment.md` §which architecture is actually
+  executing).
+- Keep sessions simple: attach-mode on a hardened target inherits every §1 problem of
+  `kernel-and-environment-hardening.md`; prefer spawn, and prefer `spawn_patch_detach.py`-style
+  patch-then-detach when you only need a memory fix to stick.
+
+## 5. On-device forensics — where the data is
+
+Rooted-phone data inspection does not need a PC round-trip. The full layout, formats and
+ownership rules live in `runtime-data.md` (DataStore/MMKV/SQLite paths, `chown`/`restorecon`
+after restores, the "app rewrites your edit" decision tree) — on device, MT Manager's file
+browser with root covers the same reads, and Termux covers scripted pulls. The two on-device
+cautions that most often bite: edit files **only with the app force-stopped** (the in-memory
+copy wins otherwise), and re-check ownership after any reinstall (the uid increments).
+
+## Checklist
+
+- [ ] Chose the workbench deliberately: MT (on-device, fast) vs PC (scriptable, deep) — not by habit
+- [ ] MCP started in MT's UI and probed (`mt_mcp_probe.py` exits 0) before planning agent-driven edits
+- [ ] MCP plans respect the three official constraints (no Java decompile, arsc entries-only, `.so` static-only)
+- [ ] LSPosed modules verified merged (`/data/adb/modules/`, not `modules_update/`) before testing
+- [ ] frida-server architecture matches the target process; disguised if the target scans
+- [ ] Data edits done with the app stopped; ownership fixed after reinstalls
diff --git a/skills/apk-reverse/references/protocol-reverse.md b/skills/apk-reverse/references/protocol-reverse.md
new file mode 100644
index 0000000..d9c5ff2
--- /dev/null
+++ b/skills/apk-reverse/references/protocol-reverse.md
@@ -0,0 +1,270 @@
+# Protocol reverse engineering
+
+**Load this when the app's traffic is not readable by the usual means**: the body is protobuf with no
+schema, the transport is gRPC, the connection is QUIC rather than TCP, or the client refuses to trust
+your proxy because it validates the certificate inside a native library.
+
+Everything in this file assumes you have already decided the traffic matters and that a proxy is
+allowed to see it. If a *feature-scoped* TLS failure has appeared while the rest of the app works,
+that is a different problem with its own file: read `tls-and-cert.md` first — it owns the trust-chain
+attribution and the permissive-defaults template, and this file deliberately does not repeat them.
+
+**Claim strength.** `measured` = an exact command and output exist in
+`docs/tool-verification/EXTENSION-native-dbi.md`. `inferred` = documented behaviour or a step that
+follows directly from a measured one. `unverified` = reported by others, not reproduced here. The
+wire-format section is `measured` on a self-built fixture; every tool named below is `unverified`
+unless stated otherwise.
+
+## 1. Protobuf on the wire (measured)
+
+Protobuf has no field names on the wire and no header. A payload is a flat sequence of
+`tag, value` pairs, and a nested message is just a value of type "bytes whose content is another
+sequence". That is the whole format; the schema supplies meaning and nothing else.
+
+| Element | Encoding |
+|---|---|
+| Varint | base-128, least-significant group first, high bit set on every byte but the last |
+| Tag | `(field_number << 3) \| wire_type`, itself a varint |
+| Wire type 0 | varint value (int32/int64/uint/bool/enum) |
+| Wire type 1 | fixed 8 bytes (fixed64/sfixed64/double) |
+| Wire type 2 | length-delimited: length varint, then that many bytes (string, bytes, nested message, packed repeated) |
+| Wire type 5 | fixed 4 bytes (fixed32/sfixed32/float) |
+| Wire types 3/4 | group start/end, legacy; treat as unsupported when walking a modern payload |
+
+A host-side check of the rules, including the canonical `150 -> 96 01`, lives in
+`tools/_work/t4-dbi/pb_selftest.py` (workbench, not shipped with the skill). Measured output on the
+fixture built there:
+
+```
+message (29 B): 089601120774657374696e671a0508011201782206038e029ea7052800
+  field 1   varint            150
+  field 2   len-delimited(7)  'testing'
+  field 3   len-delimited(5)  nested message:
+    field 1   varint            1
+    field 2   len-delimited(1)  'x'
+  field 4   len-delimited(6)  hex '038e029ea705'
+  field 5   varint            0
+rebuild from the walked rows equals original: True
+```
+
+Three consequences that decide how you interpret any decoded body:
+
+1. **Field numbers are local to their message.** In the walk above, field 3 of the outer message is a
+   nested message whose own field 1 exists independently. Nothing on the wire says which message a
+   field number belongs to; only a schema does.
+2. **A packed repeated field is invisible without a schema.** Field 4 above is three varints
+   (`3, 270, 86942`) packed into one length-delimited value. A schema-free decode can only report it
+   as opaque bytes — the length is known, the element boundaries are not.
+3. **An explicit zero is byte-identical to an absent field** in proto3 (`28 00` versus no bytes at
+   all). A decoded `0` is not evidence that the sender set the field, and "the server sent 0" is not
+   a safe conclusion from a decode alone.
+
+### Decoding without a schema
+
+- `protoc --decode_raw < body.bin` — the reference implementation's own raw decode; prints field
+  numbers and values in exactly the shape above. Note it prints strings and nested messages without
+  distinguishing them, which is why the fallback order matters: try a nested walk first, then
+  printable UTF-8, then hex.
+- `protobuf-inspector` and `blackboxprotobuf` are the pip-installable equivalents, and both add
+  heuristics: guessing whether a length-delimited value is a string or a submessage, and (for
+  `blackboxprotobuf`) inferring a candidate type set per field across many samples. Useful when you
+  have traffic but no `protoc`; still unverified here.
+- Decode **many samples of the same message**, not one. The number of distinct field numbers in a
+  large sample set is what tells you which fields are optional, which repeat, and which are enums
+  whose value set you can then enumerate.
+- Anything the app stores locally is a sample source that needs no proxy at all: an OkHttp disk cache
+  (the `journal` file plus its entries), a DataStore file, or a Room blob column. `runtime-data.md`
+  covers reading these, and `datastore_inject.py` can re-encode an edited DataStore value once you
+  know the message.
+
+## 2. Recovering the schema from the APK
+
+### What generated protobuf code looks like
+
+| Marker in the decompiled output | What it tells you |
+|---|---|
+| `extends GeneratedMessageLite` / `GeneratedMessageV3` | protobuf class; `Lite` means the reflection/schema runtime, not the descriptor-based one |
+| `static final int FIELD_NUMBER = 3;` (or `int <name>_ = 3`) | the field number, usually right next to the field's getter |
+| `switch (tag >>> 3)` with `case` constants | the parse loop's field dispatch — each `case` is a field number, in declaration order |
+| `input.readInt32()`, `readInt64()`, `readBool()`, `readStringRequireUtf8()`, `readBytes()`, `readMessage(...)`, `readEnum()` | the field's wire type and semantic type, read *after* the tag |
+| `input.readTag()` returning 0 as the loop exit | the standard `parsePartialFrom` skeleton; the loop body is where all field knowledge lives |
+| `writeTo(CodedOutputStream)` / `getSerializedSize()` / `dynamicMethod(...)` | the class really is a generated message, not a hand-written DTO |
+| `newMessageInfo(instance, "<escaped string>", ...)` | protobuf-lite's compact schema blob (see below) |
+
+The generator keeps those framework calls even after R8, so an obfuscated app usually still carries
+readable protobuf structure: class and field *names* are gone, field *numbers* and wire types are
+not.
+
+### Two routes to a `.proto`
+
+**Route A — read the field table out of the bytecode (inferred).** Decompile the class, walk
+`parsePartialFrom`, and record `case <n>` → the `read*` call that follows. Field name unknown? Name
+it `field_<n>`; a valid `.proto` does not need the original identifiers, and the app's own getter
+names often survive anyway. Then verify immediately against captured bytes with
+`protoc --decode=<message> <schema.proto>`: a decode that produces a coherent structure for **every**
+sample is the proof that your field table is right, and it costs seconds. A field that decodes into
+nonsense means a wrong wire type, not a wrong field number — check the `read*` call before moving on.
+
+**Route B — read protobuf-lite's own schema blob (inferred).** protobuf-java-lite 3.x embeds a
+compact schema string (`rawMessageInfo`) per message class, consumed by `MessageSchema` at runtime.
+Recovering it means locating that blob and feeding it to a matching runtime build. It is a strictly
+larger win when it works — it carries field numbers, types, and labels in one place — and it is
+version-sensitive, so treat Route A as the default and Route B as the acceleration. `unverified`
+here: no target in this repository was analysed this way.
+
+**Tooling that automates this (unverified):** `pbtk`/`protodump`-style scanners walk dex/JAR inputs
+looking for the generated-code shape above and emit `.proto` files, and a protobuf-aware decompiler
+plugin can do the same from a loaded APK. Use them to produce a first draft, then verify it with
+`protoc --decode` against real captured bytes — that verification is the step that turns a guess into
+a schema, and it is the step worth spending time on.
+
+## 3. gRPC
+
+gRPC is HTTP/2 with a message framing convention, so the first decision is whether you can see
+HTTP/2 at all.
+
+- **Recognise it.** A request carries `:method: POST`, `content-type: application/grpc[+proto]` (also
+  `+json`, `+thrift`), and `:path: /<package>.<Service>/<Method>` — that path shape is the reliable
+  fingerprint; the package in it usually matches a package name visible in the APK, which is how you
+  connect traffic to a client class.
+- **Message framing.** Each message is: one compression-flag byte, then a 4-byte **big-endian**
+  length, then that many bytes of (possibly compressed) protobuf. Several messages can share one
+  DATA frame and one message can span frames, so reassemble by length, not by frame. The call's
+  outcome is in **trailers** (`grpc-status`, `grpc-message`), which many proxies display separately
+  from the body — a `200` with no body and a nonzero `grpc-status` is a normal gRPC error.
+- **Read it after capture.** Extract the reassembled message bytes and hand them to
+  `protoc --decode_raw` or your recovered schema. `grpcurl -plaintext -protoset file.protoset`
+  replays against an endpoint once you have a schema, which is also the fastest way to confirm that
+  a recovered `.proto` has the right shape.
+- **Capture it.** A transparent TCP proxy sees HTTP/2 fine; a tool that only understands HTTP/1.1 may
+  show the tunnel without the frames, which looks like "the app is not making requests". Interception
+  tooling for this comes in two shapes: a proxy add-on that understands the gRPC framing and prints
+  messages (`grpc-dump` and similar mitmproxy add-ons, or a gRPC-Web decoder when the client is a
+  browser-style stack), and a command-line client (`grpcurl`) for replay against a live endpoint. If
+  the app uses TLS (gRPC-Java does by default), the certificate question comes first — see
+  `tls-and-cert.md`, and the native-material trust chain below.
+
+## 4. QUIC / HTTP/3
+
+The failure to expect: a working HTTP proxy, a working CA, and **an empty capture**.
+
+- **Why.** An HTTP proxy is a TCP endpoint, and a client reaches it with `CONNECT`. QUIC is a
+  UDP-based transport with TLS 1.3 built into the handshake; there is no TCP connection for a
+  `CONNECT` to carry and no separate TLS layer for a proxy to terminate.
+- **Recognise it before debugging anything else.** `Alt-Svc: h3=":443"` in an earlier HTTP response
+  announced the upgrade; on the wire you see UDP traffic to port 443 whose first packets are QUIC
+  Initials (long header, version field, and a TLS ClientHello inside), and the client's ALPN is `h3`.
+  Check for UDP activity when a TCP proxy stays idle while the app plainly works.
+- **Options, in order of how little they change:**
+  1. **Force a fallback to TCP.** Block or blackhole UDP 443 for the device. A client that cannot
+     reach an origin over QUIC falls back to TCP/HTTP2 if the server also offers it, and then your
+     existing proxy works unchanged. This is the cheapest option and the one to try first, but it is
+     a **network-condition change**: state it in the report, because "the app failed to load over
+     QUIC" and "the app failed" look identical in a screenshot.
+  2. **Decrypt with keys, not with a proxy.** TLS 1.3 key logging (`SSLKEYLOGFILE`-style) works for
+     QUIC exactly as it does for TLS-over-TCP, and a packet capture plus the key log can be
+     decrypted in Wireshark. It requires the client to support a key-log callback — Chromium-based
+     stacks and BoringSSL generally do, Java/OkHttp-based stacks generally do not — so this is a
+     per-client property, not a general solution.
+  3. **Turn HTTP/3 off in the client** by hooking whatever enables it (a library version check, a
+     remote-config flag, or a build-time constant). This is a client-side patch and therefore
+     belongs to the repack decision, not to the capture step.
+- Everything in this section is `inferred`/`unverified` here: no HTTP/3 target was exercised in this
+  repository. Treat the ordering as a plan whose first step (block UDP 443) needs no tool support to
+  test.
+
+## 5. SSL pinning that lives inside a native library
+
+Three different mechanisms are routinely called "pinning", and only the last one survives a system
+certificate module.
+
+| Mechanism | Where it runs | What defeats it |
+|---|---|---|
+| OkHttp `CertificatePinner` (or a custom `TrustManager`) in Java/Kotlin | app's own client | Client-level, **not** the system path: `tls-and-cert.md` §Step 4 and §"If OkHttp is the failing path" own this case — do not apply the permissive-defaults template to it |
+| System trust decisions via `HttpsURLConnection` / platform stack | platform | System store policy — see `tls-and-cert.md` §Step 5 |
+| Verification performed by a **library the app ships**, e.g. a Flutter app's own BoringSSL, or a bundled `libcurl`/`mbedtls` | `libflutter.so`, `libapp.so`, another `.so` | Only an in-memory change to that library's verification path (below), because the library does not consult the platform trust manager you can influence from Java |
+
+**Flutter, specifically.** A Flutter app's `dart:io` HTTP client runs on the engine's BoringSSL
+inside `libflutter.so`; the app's own Dart code can additionally supply a custom trusted-certificate
+context or a bad-certificate callback. Two consequences that decide which direction to work in:
+
+- If the app is **not** pinning and simply fails to trust your CA, getting your CA into the **system**
+  store is the normal fix. `MoveCertificate`-style Magisk modules exist precisely because Android 7+
+  ignores user-store CAs for app traffic; moving the CA into the system store is a **device change**,
+  not an artifact, and it must be labelled as a fallback rather than the deliverable. Its boundary is
+  exactly this: it changes what the platform trust store contains, so it can only help a client that
+  reads that store.
+- If the app **is** pinning, or supplies its own verification context, the system store is irrelevant
+  and the change has to land on the library's verification function.
+
+**Locating the verifier inside `libflutter.so` (unverified — reported method).** The published
+approach in
+[universal-flutter-ssl-pinning](https://github.com/vichhka-git/universal-flutter-ssl-pinning)
+(`github.com/vichhka-git/universal-flutter-ssl-pinning`) automates the anchor search with PyGhidra:
+
+1. load `libflutter.so` headlessly in Ghidra and scan its defined strings for `ssl_client`;
+2. resolve cross-references from that string to the **containing functions**;
+3. decompile each candidate to count its parameters;
+4. take the **3-parameter** function — that is BoringSSL's
+   `ssl_crypto_x509_session_verify_cert_chain`, the certificate-chain verification entry point;
+5. emit the discovered RVA into two ready-to-run artifacts: a Frida script that attaches to that
+   address and replaces the return value with `1` (success), and a Renef script that patches the
+   function entry with the ARM64 sequence `MOV X0, #1 ; RET`.
+
+The repository reports it working on Google Flutter arm64-v8a and Shorebird-patched builds with
+Frida 16.x/17.x, and notes the RVA is identical across build types for the same engine version. The
+same project also ships an HTTP monitor that auto-locates BoringSSL's `SSL_write`/`SSL_read` in
+`libflutter.so` and prints reassembled, de-chunked plaintext — which is the route to take when the
+traffic cannot be proxied at all, because it never needs a certificate the app will accept.
+
+**Two things to verify before trusting that recipe on your target.** First, the string anchor is a
+build artifact: a stripped or repacked engine can lose `ssl_client` while keeping the function, in
+which case fall back to the structural search — find the `X509_verify_cert`-shaped call sequence in
+the handshake code, or identify the function called with the handshake structure during
+`certificate_verify`. Second, the failure mode of a wrong anchor is a **silent** success: replacing a
+return value in a function that merely *looks* like the verifier makes the certificate check pass
+in a process that then fails somewhere else, which is easy to misread as "the app detected my hook".
+Always confirm the hook fires on a connection that would otherwise fail, and confirm it is
+`SSL_VERIFY`-shaped semantics (the same value the library itself uses for success), rather than
+assuming `1` is right.
+
+**When the string anchor is gone (the `session_creator` route).** A second family of anchors does not
+depend on the `ssl_client` literal at all: instead of finding the verifier through a string it
+references, find it through the call chain that reaches it. BoringSSL's handshake creates the session
+and then verifies the peer certificate chain, so the target is the function invoked with the
+handshake/session structure on that path — this is the shape that Flutter-unpinning write-ups call the
+session-creator route. It survives string and symbol stripping, because the call graph survives, and
+it costs more: you must identify the handshake structure first, which is why the string anchor is the
+fast path and this is the fallback when an engine build has dropped the string. `unverified` here — no
+engine binary was analysed in this repository.
+
+**When the system store is genuinely enough.** If the client is Java-side and non-pinning, moving the
+CA into the system store is the least invasive change and needs no per-library work. The decision is
+therefore: identify the client first (`tls-and-cert.md` §Step 4 attribution), then choose the
+mechanism. Patching a library that was never consulting the store is work with no effect; installing
+a system CA when a native verifier ignores it produces the same empty capture you started with.
+
+## 6. Failure modes
+
+**A decode that looks valid but is not.** protobuf is self-synchronising enough that random bytes
+often decode into a plausible-looking field list. Guard against it by (a) decoding several samples of
+the same message and expecting the same field set, (b) checking that nested lengths exactly consume
+their parents, and (c) when you have a schema, re-encoding the decoded structure and comparing bytes
+with the input — the same round-trip check used in §1, which caught a decoder bug in this
+repository's own fixture.
+
+**Assuming the proxy sees everything.** The proxy sees what the client sends through it. An app that
+uses QUIC (§4), a raw socket, a native client bypassing Java's HTTP stack, or a certificate-pinned
+connection shows up as silence. Silence is evidence about the transport, not about the app: check
+UDP activity, check whether a native library is doing the I/O (`lib_map.py`, `dynamic-frida.md`),
+and only then conclude that a feature is client-side.
+
+**Patching the wrong verifier.** Covered in §5: the failure is silent, and the resulting state is
+worse than a clean failure because it looks like progress. Verify the hook against a connection
+known to fail.
+
+**Treating a recovered schema as ground truth for the server contract.** A schema recovered from the
+client tells you what the client expects to send and parse — it does not prove the server honours
+those fields, and it says nothing about authorization. `server-api.md` owns that question. The
+recurring expensive mistake is to assume that because a field exists and is settable client-side, the
+server will act on it.
diff --git a/skills/apk-reverse/references/toolchain.md b/skills/apk-reverse/references/toolchain.md
index 2bdd934..616c460 100644
--- a/skills/apk-reverse/references/toolchain.md
+++ b/skills/apk-reverse/references/toolchain.md
@@ -93,6 +93,23 @@ grepping a hand-exported smali tree.
 The division of labour is worth stating plainly: **ASC locates, `ddc` reads.** Running a full `ddc`
 export first, then grepping it, is the slow path this tool exists to replace.
 
+**Measured in the extension pass** (droidasc `0.1.1.post1`, installed with `python -m pip install
+droidasc`; dependency is androguard only, no JVM, no SDK):
+
+| Command | Result on a 38.7 MB hardened APK |
+|---|---|
+| `getmanifest` | 0.44 s → 32,345 B of complete XML |
+| `findrefs … string jiagu` | 0.42 s → hits inside the shell class's `<clinit>` and `attachBaseContext` |
+| `getclass com/stub/StubApp` | 0.33 s → 22,802 B of Java |
+| `listclass` (whole APK) | 0.18 s → **4 classes** |
+
+Two facts from that run are worth carrying into any recon: the CLI name is **`droidasc`**, not `asc`
+(there is no `asc` binary, and `asc --version` is simply "command not found" — `python -m droidasc`
+also works), and on a packed APK a full `listclass` returning four classes is not a broken tool: the
+business dex is not in the file. Reaching for `getclass` on a class that is not there exits **1** with
+`Class … not found in APK.` — treat ASC as a manifest-and-shell inspector on hardened input, and take
+the business-logic question to a different layer.
+
 ### ddc — dex-to-Java with query subcommands (worth adopting)
 
 A single-file Rust binary, no install, no JVM. Two things make it more useful than
@@ -109,6 +126,22 @@ ddc app.apk -o out/                  # full decompile, a few seconds for a norma
 Measured on a 4.7 MB APK (4,070 classes / 30k methods): `info` ~0.13 s, `findrefs`
 ~0.11 s, one class ~0.25 s, full decompile ~2.8 s producing ~4,000 files.
 
+**Measured in the extension pass** (ddc `0.1.8`, a single Rust binary — on Windows `bin/ddc.exe`,
+1,028,096 B, **not on PATH** and carrying no PE version resource, so `ddc -V` is the only way to read
+its version; source: the project's GitHub releases):
+
+| Command | Result on a 38.7 MB hardened APK |
+|---|---|
+| `ddc info` | 0.24 s → label / package / version / application / launcher / sdk / size / md5, plus per-dex class, method, field and string counts |
+| `ddc findrefs <apk> string jiagu` | 0.13 s → tabulated `dex | kind | class | method | refs` |
+| `ddc strings -f jiagu --with-locations` | 0.14 s → strings mapped to the methods that hold them |
+
+**The trap on this one is the exit code.** Asked for a class that is not present, `ddc` exits **2**
+*and still prints its help text to stdout* — so a wrapper that tests "did anything come back?" reads a
+usage error as an answer. Branch on the exit code, never on output emptiness. The same run also
+confirms the layered picture from the other direction: `info`'s per-dex counters report 4 classes and
+29 methods with code for the whole 8.9 MB shell dex.
+
 Why the query subcommands matter more than the speed: **string cross-referencing
 becomes a lookup instead of a crawl.** Asking "which class mentions this config
 field name" is a sub-second command here and easily an hour of smali grepping by
diff --git a/skills/apk-reverse/scripts/dex_dump_validate.py b/skills/apk-reverse/scripts/dex_dump_validate.py
new file mode 100644
index 0000000..ebcea68
--- /dev/null
+++ b/skills/apk-reverse/scripts/dex_dump_validate.py
@@ -0,0 +1,304 @@
+#!/usr/bin/env python3
+"""Validate a directory of dumped dex files: dedupe, structural checks, stub-body ratio.
+
+A memory dump (frida-dexdump & co.) hands you a pile of images: duplicate copies of
+one dex, SDK plugin dexes that were never in the APK, structurally broken fragments,
+extraction-shell skeletons whose method bodies are stubbed, and -- if you are lucky --
+the original. `references/recon.md` states the rule (dedupe by content hash, validate
+structure before trusting); this script is the tool that rule was missing.
+
+Per file it reports: size, sha256, dex version, checksum/signature verdicts
+(`dexutil.verify_dex_header`), class count, method-body census (no-code / real /
+trivial-stub / empty), the trivial-body ratio that flags an extraction-shell
+skeleton, and --find pattern hits across the string table. Files are grouped by
+sha256 and the survivors are ranked: most likely original first.
+
+Exit code 0 unless nothing in the input parses as a dex at all (exit 1).
+
+Examples:
+    python dex_dump_validate.py dumps/ --find 'Lcom/example/app/'
+    python dex_dump_validate.py dumps/ --find 'Lcom/stub/' --json > report.json
+    python dex_dump_validate.py one_dumped.dex
+"""
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from dexutil import OFFSETS, read_uleb, u16, u32, verify_dex_header  # noqa: E402
+
+MAGIC = b"dex\n"
+KNOWN_VERSIONS = {b"035", b"036", b"037", b"038", b"039"}
+RETURN_OPS = {0x0E, 0x0F, 0x10, 0x11}  # return-void / return / return-wide / return-object
+
+
+def classify_body(data, code_off):
+    """Classify one code_item's instruction stream: 'empty' | 'stub' | 'real'.
+
+    'stub' = skip plain nop units (0x0000) and exactly one return* remains. That is
+    what an extraction shell leaves behind when it defers decryption to first
+    invocation, and what a repair fixture writes when mimicking one. Anything with a
+    second meaningful unit is real code, however small.
+    """
+    insns_size = u32(data, code_off + 12)
+    if insns_size == 0:
+        return "empty"
+    base = code_off + 16
+    meaningful = 0
+    last_unit = 0
+    for k in range(insns_size):
+        unit = u16(data, base + k * 2)
+        if unit == 0x0000:            # plain nop / cleared slot
+            continue
+        meaningful += 1
+        last_unit = unit
+        if meaningful > 1:
+            return "real"             # early exit: two units can never be a stub
+    if meaningful == 1:
+        op = last_unit & 0xFF         # first byte holds the opcode for 10x/11x
+        if op == 0x0E and last_unit == 0x000E:        # return-void, no register
+            return "stub"
+        if op in (0x0F, 0x10, 0x11):  # 11x returns: high byte is the register
+            return "stub"
+    return "real"
+
+
+def walk_methods(data, header):
+    """Yield code_off for every method defined in class_defs (0 = abstract/native)."""
+    for i in range(header["class_defs_size"]):
+        cd = header["class_defs_off"] + i * 32
+        p = u32(data, cd + 24)                       # class_data_off
+        if p == 0:
+            continue
+        static_f, p = read_uleb(data, p)
+        inst_f, p = read_uleb(data, p)
+        direct_m, p = read_uleb(data, p)
+        virtual_m, p = read_uleb(data, p)
+        for _ in range(static_f + inst_f):
+            _, p = read_uleb(data, p)                # field_idx_diff
+            _, p = read_uleb(data, p)                # access_flags
+        for _ in range(direct_m + virtual_m):
+            _, p = read_uleb(data, p)                # method_idx_diff
+            _, p = read_uleb(data, p)                # access_flags
+            code_off, p = read_uleb(data, p)
+            yield code_off
+
+
+def string_find_hits(data, header, patterns):
+    """Count string-table entries containing each pattern."""
+    hits = {}
+    for pat in patterns:
+        pat_bytes = pat.encode("utf-8", "surrogateescape")
+        n = 0
+        for idx in range(header["string_ids_size"]):
+            p = u32(data, header["string_ids_off"] + idx * 4)
+            try:
+                _, p = read_uleb(data, p)
+                end = data.index(b"\x00", p)
+            except Exception:
+                continue
+            if pat_bytes in data[p:end]:
+                n += 1
+        hits[pat] = n
+    return hits
+
+
+def profile_dex(path, patterns, trim=False):
+    """Build the report dict for one file. 'error' key marks a rejected image.
+
+    With trim=True, an image whose header file_size is *shorter* than the file is
+    accepted after cutting the tail: /proc/<pid>/mem dumps are page-aligned, so the
+    recorded VMA range is always longer than the dex it holds (measured on a real
+    root-side dump: 17/17 images overran by 68-3724 bytes). A file *shorter* than
+    its own file_size is still rejected -- that is a truncated read, not padding.
+    """
+    name = os.path.basename(path)
+    with open(path, "rb") as fh:
+        data = fh.read()
+    prof = {
+        "path": os.path.abspath(path),
+        "name": name,
+        "size": len(data),
+        "sha256": hashlib.sha256(data).hexdigest(),
+    }
+    if len(data) < 112:
+        prof["error"] = "too small (%d B) to carry a dex header" % len(data)
+        return prof
+    if data[:4] != MAGIC:
+        prof["error"] = "magic=%r" % data[:4]
+        return prof
+    version = data[4:7]
+    prof["version"] = version.decode("ascii", "replace")
+    if version not in KNOWN_VERSIONS:
+        prof["error"] = "unknown version %r" % version
+        return prof
+
+    header = {k: u32(data, v) for k, v in OFFSETS.items()}
+    if header["file_size"] != len(data):
+        if trim and 0 < header["file_size"] < len(data):
+            prof["trimmed_from"] = len(data)
+            prof["trimmed_to"] = header["file_size"]
+            data = data[: header["file_size"]]
+            prof["size"] = len(data)
+        else:
+            prof["error"] = "file_size=%d actual=%d" % (header["file_size"], len(data))
+            return prof
+    if header["header_size"] != 112:
+        prof["error"] = "header_size=%d (expected 112)" % header["header_size"]
+        return prof
+    for key in ("string_ids_off", "type_ids_off", "proto_ids_off",
+                "field_ids_off", "method_ids_off", "class_defs_off"):
+        off = header[key]
+        if off and not (0 < off < len(data)):
+            prof["error"] = "%s=0x%x out of range" % (key, off)
+            return prof
+
+    cksum_ok, sig_ok = verify_dex_header(bytearray(data))
+    prof["checksum_ok"] = cksum_ok
+    prof["signature_ok"] = sig_ok
+
+    prof["classes"] = header["class_defs_size"]
+    no_code = with_code = stubs = empties = 0
+    try:
+        for code_off in walk_methods(data, header):
+            if code_off == 0:                       # abstract / native declaration
+                no_code += 1
+                continue
+            if code_off + 16 > len(data):
+                continue                            # broken pointer: skip, don't die
+            with_code += 1
+            kind = classify_body(data, code_off)
+            if kind == "stub":
+                stubs += 1
+            elif kind == "empty":
+                empties += 1
+    except Exception as exc:                        # desynced class_data: keep counts
+        prof["walk_error"] = str(exc)
+    prof["methods_no_code"] = no_code
+    prof["methods_with_code"] = with_code
+    prof["bodies_real"] = with_code - stubs - empties
+    prof["bodies_stub"] = stubs
+    prof["bodies_empty"] = empties
+    prof["trivial_ratio"] = (stubs / with_code) if with_code else 0.0
+
+    if patterns:
+        try:
+            prof["find_hits"] = string_find_hits(data, header, patterns)
+        except Exception as exc:
+            prof["find_hits_error"] = str(exc)
+    return prof
+
+
+def collect_files(paths):
+    out = []
+    for p in paths:
+        if os.path.isdir(p):
+            out += [os.path.join(p, n) for n in sorted(os.listdir(p))
+                    if n.endswith(".dex")]
+        elif os.path.isfile(p):
+            out.append(p)
+        else:
+            print("warning: %s is not a file or directory, skipped" % p,
+                  file=sys.stderr)
+    return out
+
+
+def rank_key(prof):
+    return (prof["trivial_ratio"],
+            0 if prof["checksum_ok"] else 1,
+            0 if prof["signature_ok"] else 1,
+            prof["name"])
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Dedupe and structurally validate a directory of dumped dex "
+                    "files; rank which image is the most likely original.")
+    ap.add_argument("path", nargs="+",
+                    help="a directory of *.dex dumps, or individual .dex files")
+    ap.add_argument("--find", action="append", default=[], metavar="PATTERN",
+                    help="count string-table hits for PATTERN (repeatable), "
+                         "e.g. --find 'Lcom/example/app/'")
+    ap.add_argument("--json", action="store_true",
+                    help="emit the full report as JSON (deterministic; redirect "
+                         "to a file to keep it)")
+    ap.add_argument("--trim", action="store_true",
+                    help="accept page-aligned dumps: cut a tail longer than the header's "
+                         "file_size (/proc/<pid>/mem exports always overrun; a file shorter "
+                         "than its own file_size is still rejected)")
+    args = ap.parse_args(argv)
+
+    files = collect_files(args.path)
+    if not files:
+        print("no .dex files found in the given path(s)", file=sys.stderr)
+        return 1
+
+    profiles = [profile_dex(f, args.find, args.trim) for f in files]
+    valid = [p for p in profiles if "error" not in p]
+    ranking = sorted(valid, key=rank_key)
+
+    if args.json:
+        print(json.dumps({"profiles": profiles,
+                          "ranking": [p["name"] for p in ranking]}, indent=2))
+        return 0 if valid else 1
+
+    # ---- human-readable report -------------------------------------------------
+    print("== dex dump validation: %d file(s), %d parse, %d rejected =="
+          % (len(profiles), len(valid), len(profiles) - len(valid)))
+    fmt = "%-28s %9s  %-12s  %3s  %-7s %-7s %6s %5s %6s %7s"
+    print(fmt % ("name", "size", "sha256[:12]", "ver", "cksum", "sig",
+                 "class", "noco", "code", "stub%"))
+    for p in profiles:
+        if "error" in p:
+            print("%-28s %9s  %-12s  %3s  REJECTED: %s"
+                  % (p["name"], p["size"], p["sha256"][:12],
+                     p.get("version", "?"), p["error"]))
+            continue
+        print(fmt % (p["name"], p["size"], p["sha256"][:12], p["version"],
+                     "ok" if p["checksum_ok"] else "BAD",
+                     "ok" if p["signature_ok"] else "BAD",
+                     p["classes"], p["methods_no_code"], p["methods_with_code"],
+                     "%.1f%%" % (100.0 * p["trivial_ratio"])))
+        if p.get("trimmed_from"):
+            print("%-28s   trimmed %d -> %d B (page-aligned dump)"
+                  % ("", p["trimmed_from"], p["trimmed_to"]))
+        if p.get("walk_error"):
+            print("%-28s   walk stopped early: %s" % ("", p["walk_error"]))
+        for pat, n in sorted(p.get("find_hits", {}).items()):
+            print("%-28s   find %-24s %d" % ("", pat, n))
+
+    groups = {}
+    for p in valid:
+        groups.setdefault(p["sha256"], []).append(p["name"])
+    dup_groups = {h: n for h, n in groups.items() if len(n) > 1}
+    print("\ndedupe: %d unique image(s) among %d valid file(s)"
+          % (len(groups), len(valid)))
+    for h, names in sorted(dup_groups.items()):
+        print("  %s  %s" % (h[:16], ", ".join(names)))
+
+    if ranking:
+        print("\nranking (most likely original first):")
+        for i, p in enumerate(ranking, 1):
+            note = ""
+            if p["trivial_ratio"] >= 0.5:
+                note = "  <-- SKELETON: stub%%=%.0f, extraction-shell shape" \
+                       % (100.0 * p["trivial_ratio"])
+            print("  %d. %-28s stub%%=%.1f  cksum=%s  sig=%s  classes=%d%s"
+                  % (i, p["name"], 100.0 * p["trivial_ratio"],
+                     "ok" if p["checksum_ok"] else "BAD",
+                     "ok" if p["signature_ok"] else "BAD",
+                     p["classes"], note))
+        top = ranking[0]
+        copies = len(groups.get(top["sha256"], []))
+        print("\nverdict: %s is the most likely original (%d copy(ies) in this set)"
+              % (top["name"], copies))
+    else:
+        print("\nverdict: no image parsed as a dex -- nothing to rank")
+    return 0 if valid else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/skills/apk-reverse/scripts/dex_mem_scan.py b/skills/apk-reverse/scripts/dex_mem_scan.py
new file mode 100644
index 0000000..87b5c70
--- /dev/null
+++ b/skills/apk-reverse/scripts/dex_mem_scan.py
@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""Scan memory captures for embedded dex images and optionally extract them.
+
+A packer can keep a decrypted dex in a buffer that never appears in
+`/proc/<pid>/maps` under a dex-looking name -- it sits inside an anonymous rw-p
+mapping. Neither `maps` analysis nor a per-mapping dump finds that on its own;
+searching the bytes for the dex magic does. This script does the search and, with
+`--dump`, writes each hit out at the size its own header declares.
+
+Typical use, after taking raw regions from a live process (root required):
+
+    adb shell 'su -c "cat /proc/<pid>/mem"' ...        # or per-region dd exports
+    python skills/apk-reverse/scripts/dex_mem_scan.py region_dir/ --dump out/
+
+Feeding the extracted images to `dex_dump_validate.py` is the next step: this
+script only *finds* and *cuts*; that one judges whether what came out is a real
+body or an extraction-shell skeleton.
+
+Scope note: the header's `file_size` field decides the cut. When the declared size
+does not fit inside the capture, the hit is reported and skipped rather than
+guessed at -- a dex whose tail is missing is not recoverable by truncating the
+wrong end.
+"""
+import argparse
+import hashlib
+import json
+import os
+import struct
+import sys
+
+MAGIC = b"dex\n0"
+HEADER_SIZE = 112
+OVERLAP = 0x80  # enough to complete a header straddling two chunks
+
+
+def valid_version(four_bytes):
+    """`dex\\n0XY` -> 'XY' when both digits are decimal, else None."""
+    ver = four_bytes[4:7]
+    if len(ver) != 3 or not (ver[0:1].isdigit() and ver[1:2].isdigit()
+                             and ver[2:3].isdigit()):
+        return None
+    return ver.decode("ascii")
+
+
+def find_offsets(path, chunk_size):
+    """Yield (absolute offset, buffer, index in buffer, buffer base) for each magic.
+
+    Chunks overlap by OVERLAP bytes so a header straddling a chunk boundary is
+    still seen whole; the caller dedupes repeated offsets.
+    """
+    size = os.path.getsize(path)
+    carry = b""
+    pos = 0
+    with open(path, "rb") as fh:
+        while pos < size:
+            fh.seek(pos)
+            buf = carry + fh.read(chunk_size)
+            base = pos - len(carry)
+            start = 0
+            while True:
+                i = buf.find(MAGIC, start)
+                if i < 0:
+                    break
+                start = i + 1
+                yield base + i, buf, i, base
+            if len(buf) <= OVERLAP:
+                break
+            carry = buf[-OVERLAP:]
+            pos += len(buf) - len(carry)
+
+
+def read_header(fh, offset):
+    """Return (file_size, class_defs_size, link_size) or None if the header is short."""
+    fh.seek(offset)
+    head = fh.read(HEADER_SIZE)
+    if len(head) < HEADER_SIZE:
+        return None
+    if head[:4] != b"dex\n"[:4]:
+        return None
+    file_size = struct.unpack_from("<I", head, 32)[0]
+    class_defs_size = struct.unpack_from("<I", head, 96)[0]
+    link_size = struct.unpack_from("<I", head, 104)[0]
+    return file_size, class_defs_size, link_size
+
+
+def scan_file(path, chunk_size, min_size, do_dump, dump_dir, keep_partial):
+    """Scan one capture; return (records, extracted_count, skipped_count)."""
+    records = []
+    extracted = 0
+    skipped = 0
+    seen = set()
+    size = os.path.getsize(path)
+    with open(path, "rb") as fh:
+        for offset, buf, i, base in find_offsets(path, chunk_size):
+            ver = valid_version(buf[i:i + 8]) if i + 8 <= len(buf) else None
+            if ver is None:
+                continue
+            if offset in seen:
+                continue
+            seen.add(offset)
+            head = read_header(fh, offset)
+            if head is None:
+                continue
+            file_size, class_defs_size, link_size = head
+            if file_size < 112 or file_size > (1 << 32):
+                continue
+
+            fits = file_size <= (size - offset)
+            rec = {
+                "capture": os.path.basename(path),
+                "offset": offset,
+                "version": ver,
+                "file_size": file_size,
+                "class_defs_size": class_defs_size,
+                "link_size": link_size,
+                "fits": fits,
+            }
+            if fits and file_size >= min_size:
+                takes = file_size
+            elif keep_partial and not fits:
+                takes = size - offset
+                rec["partial"] = takes
+            else:
+                rec["skipped"] = ("declared %d B, %d B available"
+                                  % (file_size, size - offset))
+                skipped += 1
+                records.append(rec)
+                continue
+
+            fh.seek(offset)
+            blob = fh.read(takes)
+            rec["sha256"] = hashlib.sha256(blob).hexdigest()
+            if do_dump:
+                stem = os.path.splitext(os.path.basename(path))[0]
+                name = "%s+0x%08x.dex" % (stem, offset)
+                out = os.path.join(dump_dir, name)
+                with open(out, "wb") as ofh:
+                    ofh.write(blob)
+                rec["written"] = out
+                extracted += 1
+            records.append(rec)
+    return records, extracted, skipped
+
+
+def collect_targets(paths):
+    targets = []
+    for p in paths:
+        if os.path.isdir(p):
+            for name in sorted(os.listdir(p)):
+                full = os.path.join(p, name)
+                if os.path.isfile(full) and not name.endswith((".txt", ".json", ".md")):
+                    targets.append(full)
+        else:
+            targets.append(p)
+    return targets
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Scan memory captures (or any blob) for embedded dex images "
+                    "'dex\\n03x', report each hit, and optionally extract them at "
+                    "the size their own headers declare. Pair with "
+                    "dex_dump_validate.py, which judges what was extracted.")
+    ap.add_argument("path", nargs="+",
+                    help="a capture file, or a directory of region exports")
+    ap.add_argument("--dump", metavar="DIR",
+                    help="write each hit into DIR as <capture>+0x<offset>.dex")
+    ap.add_argument("--json", action="store_true",
+                    help="emit the record list as JSON")
+    ap.add_argument("--chunk-size", type=int, default=64 << 20, metavar="N",
+                    help="read the capture in N-byte chunks (default 64 MiB); use a "
+                         "smaller value for very large captures")
+    ap.add_argument("--min-size", type=int, default=4096, metavar="N",
+                    help="ignore hits whose declared file_size is below N bytes "
+                         "(default 4096) -- stray magics in unrelated data")
+    ap.add_argument("--keep-partial", action="store_true",
+                    help="also write hits whose declared size runs past the end of "
+                         "the capture (truncated region); the result is NOT a dex")
+    args = ap.parse_args(argv)
+
+    targets = collect_targets(args.path)
+    if not targets:
+        print("no capture files found in the given path(s)", file=sys.stderr)
+        return 1
+
+    dump_dir = None
+    if args.dump:
+        dump_dir = os.path.abspath(args.dump)
+        os.makedirs(dump_dir, exist_ok=True)
+
+    all_records = []
+    total_extracted = 0
+    total_skipped = 0
+    for t in targets:
+        records, extracted, skipped = scan_file(
+            t, args.chunk_size, args.min_size,
+            dump_dir is not None, dump_dir or ".", args.keep_partial)
+        all_records.extend(records)
+        total_extracted += extracted
+        total_skipped += skipped
+
+    if args.json:
+        print(json.dumps({"records": all_records,
+                          "extracted": total_extracted,
+                          "skipped": total_skipped}, indent=2))
+        return 0 if all_records else 1
+
+    print("== dex memory scan: %d capture(s), %d hit(s) =="
+          % (len(targets), len(all_records)))
+    fmt = "%-34s %12s  %3s  %12s  %10s  %-6s"
+    print(fmt % ("capture", "offset", "ver", "file_size", "classes", "state"))
+    for r in all_records:
+        state = "ok" if r.get("fits") and not r.get("partial") else (
+            "partial" if r.get("partial") else "skipped")
+        print(fmt % (r["capture"][:34], "0x%x" % r["offset"], r["version"],
+                     r["file_size"], r["class_defs_size"], state))
+        if r.get("written"):
+            print("%-34s   wrote %s" % ("", r["written"]))
+        if r.get("skipped"):
+            print("%-34s   skipped: %s" % ("", r["skipped"]))
+
+    unique = {r["sha256"] for r in all_records if r.get("sha256")}
+    print("\n%d hit(s) with a complete declared size, %d unique by sha256, "
+          "%d skipped" % (total_extracted, len(unique), total_skipped))
+    if total_extracted:
+        print("next: python dex_dump_validate.py %s" % (dump_dir or "<dump dir>"))
+    return 0 if all_records else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/skills/apk-reverse/scripts/frida_rpc_serve.py b/skills/apk-reverse/scripts/frida_rpc_serve.py
new file mode 100644
index 0000000..8dcf21e
--- /dev/null
+++ b/skills/apk-reverse/scripts/frida_rpc_serve.py
@@ -0,0 +1,424 @@
+#!/usr/bin/env python3
+"""Bridge a Frida script's rpc.exports to local Python, a REPL, or a tiny HTTP endpoint.
+
+Given a device, a target process and a Frida script that defines `rpc.exports`,
+this tool keeps a long-lived session alive (with automatic reconnect) and lets
+you invoke those exports three ways:
+
+  --mode call    one shot: --export add --args '[1, 2]' -> prints the result, exits
+  --mode repl    interactive: `list`, `name [json-args]`, `reload`, `quit`
+  --mode http    POST /call {"export": "add", "args": [1, 2]} -> JSON result;
+                 GET /exports lists them; POST /reload re-creates the script
+
+The typical use is running a hardened target's own crypto (the function the
+shell or SDK uses to sign/encrypt) as if it were a local function: spawn or
+attach, keep the session resident, and call it from automation instead of from
+a hand-driven `frida -l` session. See references/emulation-and-rpc.md for when
+this beats emulating the .so offline (unidbg) and when it does not.
+
+Reconnect policy: a detached session (app restart, server death, ROM killing
+the server — see references/dynamic-frida.md) marks the bridge dead; the next
+call re-attaches (re-spawning first if --spawn was given), reloads the script
+and retries, with exponential backoff up to --retries times.
+
+Device selection follows the skill's rule of explicitness: --device-serial
+picks that exact USB device; --remote HOST:PORT attaches through an explicit
+`adb forward` (preferred when several devices/emulators are attached); with
+neither, frida's default USB device is used.
+
+Examples:
+  python frida_rpc_serve.py --device-serial SSBY... --package com.example.app \
+      --script rpc_template.js --mode call --export add --args '[1, 2]'
+
+  python frida_rpc_serve.py --remote 127.0.0.1:27042 --package com.example.app \
+      --script rpc_template.js --mode repl
+
+  python frida_rpc_serve.py --device-serial SSBY... --spawn --package com.example.app \
+      --script rpc_template.js --mode http --port 8765
+"""
+
+import argparse
+import http.server
+import json
+import sys
+import threading
+import time
+
+try:
+    import frida
+except ImportError:  # pragma: no cover
+    sys.stderr.write("frida is required: pip install frida (host package must match the device server)\n")
+    sys.exit(2)
+
+
+# Device-side failures worth retrying: a target that is still starting, a server
+# that was reaped, a process that vanished. frida.TimedOutError is *not* a
+# TransportError subclass (measured on frida 16.7.19: attaching to a busy app
+# raised TimedOutError and escaped every handler), so collect them by name.
+RETRYABLE = tuple(
+    getattr(frida, name)
+    for name in ("TransportError", "NotSupportedError", "ServerNotRunningError",
+                 "ProcessNotFoundError", "InvalidOperationError", "TimedOutError")
+    if hasattr(frida, name)
+)
+
+
+class BridgeError(Exception):
+    pass
+
+
+class RpcBridge:
+    """Owns device -> session -> script and re-establishes them when detached."""
+
+    def __init__(self, opts):
+        self.opts = opts
+        self.device = None
+        self.session = None
+        self.script = None
+        self.exports = None
+        self.spawned_pid = None
+        self.alive = False
+        self.attempt = 0
+        self._lock = threading.Lock()
+
+    # -- connection lifecycle ------------------------------------------------
+
+    def _get_device(self):
+        if self.opts.remote:
+            return frida.get_device_manager().add_remote_device(self.opts.remote)
+        if self.opts.device_serial:
+            return frida.get_device(self.opts.device_serial)
+        return frida.get_usb_device()
+
+    def _attach_or_spawn(self, device):
+        if self.opts.spawn:
+            if not self.opts.package:
+                raise BridgeError("--spawn requires --package")
+            pid = device.spawn([self.opts.package])
+            self.spawned_pid = pid
+            return device.attach(pid)
+        if self.opts.pid is not None:
+            return device.attach(self.opts.pid)
+        if self.opts.package:
+            # attach-by-name can fail while the process list is incomplete
+            # (references/dynamic-frida.md); the caller may fall back to --pid.
+            return device.attach(self.opts.package)
+        raise BridgeError("need one of --package / --pid")
+
+    def connect(self):
+        """Establish device, session and script. Raises on failure."""
+        with self._lock:
+            self._teardown()
+            if self.opts.remote:
+                # A cached remote device may hold the dead socket of a server
+                # that was killed and restarted; drop it so we reconnect fresh.
+                try:
+                    frida.get_device_manager().remove_remote_device(self.opts.remote)
+                except Exception:
+                    pass
+            device = self._get_device()
+            session = self._attach_or_spawn(device)
+            session.on("detached", self._on_detached)
+            with open(self.opts.script, "r", encoding="utf-8") as fh:
+                code = fh.read()
+            script = session.create_script(code, runtime=self.opts.runtime)
+            script.on("message", self._on_message)
+            script.load()
+            # Resume only after the script has loaded: resuming earlier loses
+            # the first hook window (references/dynamic-frida.md).
+            if self.spawned_pid is not None:
+                device.resume(self.spawned_pid)
+            self.device, self.session, self.script = device, session, script
+            # frida >= 16 prefers exports_sync; older builds expose exports.
+            self.exports = getattr(script, "exports_sync", None) or script.exports
+            self.alive = True
+            self.attempt = 0
+
+    def _teardown(self):
+        script, session = self.script, self.session
+        self.script = self.session = self.exports = None
+        self.spawned_pid = None
+        self.alive = False
+        # Unload the script *and* detach the session; without the detach every
+        # reload/retry cycle leaks one attached session on the device.
+        if script is not None:
+            try:
+                script.unload()
+            except Exception:
+                pass
+        if session is not None:
+            try:
+                session.off("detached", self._on_detached)
+            except Exception:
+                pass
+            try:
+                session.detach()
+            except Exception:
+                pass
+
+    def _on_detached(self, reason, *rest):
+        self.alive = False
+        sys.stderr.write("[bridge] session detached: %s %s\n" % (reason, rest or ""))
+
+    def _on_message(self, message, data):
+        if message.get("type") == "error":
+            sys.stderr.write("[script-error] %s\n" % message.get("description"))
+            if message.get("stack"):
+                sys.stderr.write(message["stack"])
+        else:
+            sys.stderr.write("[script] %s\n" % json.dumps(message, ensure_ascii=False, default=str))
+
+    def ensure(self):
+        """Connect if needed; retry with backoff while the target is reachable.
+
+        Each ensure() call is its own retry cycle: a failed cycle does not
+        poison the next request (the device may come back seconds later).
+        """
+        if self.alive:
+            return
+        self.attempt = 0
+        while True:
+            self.attempt += 1
+            if self.attempt > self.opts.retries:
+                raise BridgeError(
+                    "could not (re)connect after %d attempts" % self.opts.retries)
+            try:
+                self.connect()
+                return
+            except RETRYABLE + (BridgeError, OSError) as exc:
+                wait = min(self.opts.backoff * (2 ** (self.attempt - 1)), 15.0)
+                sys.stderr.write("[bridge] connect failed (%s); retry %d in %.1fs\n"
+                                 % (exc, self.attempt, wait))
+                time.sleep(wait)
+
+    # -- the RPC surface -----------------------------------------------------
+
+    def call(self, name, args):
+        self.ensure()
+        # frida's export proxy fails from deep inside the transport with its own
+        # "unable to find method 'x'" wording; consult the advertised list first
+        # so the caller gets the actionable message.
+        try:
+            available = self.list_exports()
+        except Exception:
+            available = None
+        if available is not None and name not in available:
+            raise BridgeError("no such rpc export: %s (available: %s)"
+                              % (name, " ".join(available)))
+        fn = getattr(self.exports, name, None)
+        if fn is None:
+            raise BridgeError("no such rpc export: %s (try `list`)" % name)
+        try:
+            return fn(*args)
+        except (frida.InvalidOperationError, frida.TransportError):
+            # Session died mid-call: one transparent reconnect + retry.
+            self.alive = False
+            self.ensure()
+            fn = getattr(self.exports, name, None)
+            if fn is None:
+                raise BridgeError("export disappeared after reconnect: %s" % name)
+            return fn(*args)
+
+    def list_exports(self):
+        self.ensure()
+        # frida 16.7 deprecates Script.list_exports() in favour of
+        # list_exports_sync(); try the new name first so the bridge stays
+        # quiet on current hosts and keeps working when the old one goes.
+        for attr in ("list_exports_sync", "list_exports"):
+            fn = getattr(self.script, attr, None)
+            if fn is None:
+                continue
+            try:
+                return fn()
+            except Exception:
+                pass
+        return sorted(k for k in dir(self.exports) if not k.startswith("_"))
+
+    def reload(self):
+        with self._lock:
+            self._teardown()
+        self.ensure()
+
+
+# -- mode: one-shot call ------------------------------------------------------
+
+
+def run_call_mode(bridge, opts):
+    # One-shot mode is meant to be scripted: report every failure as one JSON
+    # object plus a non-zero exit code instead of a Python traceback.
+    try:
+        args = json.loads(opts.args) if opts.args else []
+    except ValueError as exc:
+        print(json.dumps({"ok": False, "error": "--args is not valid JSON: %s" % exc},
+                         ensure_ascii=False))
+        return 1
+    if not isinstance(args, list):
+        print(json.dumps({"ok": False, "error": "--args must be a JSON array"},
+                         ensure_ascii=False))
+        return 1
+    try:
+        result = bridge.call(opts.export, args)
+    except BridgeError as exc:
+        print(json.dumps({"ok": False, "export": opts.export, "error": str(exc)},
+                         ensure_ascii=False))
+        return 1
+    except Exception as exc:  # a JS-side throw arrives as frida.core.RPCException
+        print(json.dumps({"ok": False, "export": opts.export,
+                          "error": "%s: %s" % (type(exc).__name__, exc)},
+                         ensure_ascii=False))
+        return 1
+    print(json.dumps({"ok": True, "export": opts.export, "result": result},
+                     ensure_ascii=False, default=str))
+    return 0
+
+
+# -- mode: REPL ---------------------------------------------------------------
+
+
+def run_repl_mode(bridge, opts):
+    print("connected; exports are callable by name. commands: list | name [json-args] | reload | quit")
+    while True:
+        try:
+            line = input("rpc> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return 0
+        if not line:
+            continue
+        if line in ("quit", "exit", "q"):
+            return 0
+        if line == "list":
+            try:
+                print(" ".join(bridge.list_exports()))
+            except BridgeError as exc:
+                print("error: %s" % exc)
+            continue
+        if line == "reload":
+            try:
+                bridge.reload()
+                print("reloaded")
+            except BridgeError as exc:
+                print("error: %s" % exc)
+            continue
+        parts = line.split(None, 1)
+        name = parts[0]
+        args = json.loads(parts[1]) if len(parts) > 1 and parts[1].strip() else []
+        if not isinstance(args, list):
+            print("args must be a JSON array")
+            continue
+        try:
+            result = bridge.call(name, args)
+            print(json.dumps(result, ensure_ascii=False, default=str))
+        except BridgeError as exc:
+            print("error: %s" % exc)
+        except Exception as exc:  # JS-side throw arrives here as frida.core.RPCException
+            print("js-error: %s" % exc)
+
+
+# -- mode: HTTP ---------------------------------------------------------------
+
+
+def run_http_mode(bridge, opts):
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def _send(self, code, payload):
+            body = json.dumps(payload, ensure_ascii=False, default=str).encode("utf-8")
+            self.send_response(code)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_GET(self):
+            if self.path == "/exports":
+                try:
+                    self._send(200, {"ok": True, "exports": bridge.list_exports()})
+                except BridgeError as exc:
+                    self._send(502, {"ok": False, "error": str(exc)})
+            else:
+                self._send(404, {"ok": False, "error": "GET /exports only"})
+
+        def do_POST(self):
+            if self.path == "/reload":
+                try:
+                    bridge.reload()
+                    self._send(200, {"ok": True})
+                except BridgeError as exc:
+                    self._send(502, {"ok": False, "error": str(exc)})
+                return
+            if self.path != "/call":
+                self._send(404, {"ok": False, "error": "POST /call or /reload"})
+                return
+            try:
+                length = int(self.headers.get("Content-Length") or 0)
+                req = json.loads(self.rfile.read(length).decode("utf-8"))
+                name = req.get("export")
+                args = req.get("args", [])
+                if not name or not isinstance(args, list):
+                    raise ValueError('body must be {"export": "name", "args": [...]}')
+                result = bridge.call(name, args)
+                self._send(200, {"ok": True, "result": result})
+            except BridgeError as exc:
+                self._send(502, {"ok": False, "error": str(exc)})
+            except Exception as exc:
+                self._send(400, {"ok": False, "error": str(exc)})
+
+        def log_message(self, fmt, *args):
+            sys.stderr.write("[http] " + (fmt % args) + "\n")
+
+    server = http.server.ThreadingHTTPServer((opts.host, opts.port), Handler)
+    print("listening on http://%s:%d  (POST /call, GET /exports, POST /reload)"
+          % (opts.host, opts.port))
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+    return 0
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        description="Bridge a Frida script's rpc.exports to Python/REPL/HTTP with auto-reconnect.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__.split("Examples:")[-1].strip() if __doc__ else None,
+    )
+    parser.add_argument("--script", required=True, help="path to the .js defining rpc.exports")
+    parser.add_argument("--package", help="target package (attach by name, or spawn with --spawn)")
+    parser.add_argument("--pid", type=int, help="target pid (use when attach-by-name fails)")
+    parser.add_argument("--device-serial", help="explicit USB device serial (see adb devices -l)")
+    parser.add_argument("--remote", metavar="HOST:PORT",
+                        help="explicit remote frida via adb forward, e.g. 127.0.0.1:27042")
+    parser.add_argument("--spawn", action="store_true",
+                        help="spawn the package instead of attaching (catches startup)")
+    parser.add_argument("--mode", choices=("call", "repl", "http"), default="repl")
+    parser.add_argument("--export", help="export name (call mode)")
+    parser.add_argument("--args", help="JSON array of arguments (call mode)")
+    parser.add_argument("--host", default="127.0.0.1", help="HTTP bind host (http mode)")
+    parser.add_argument("--port", type=int, default=8765, help="HTTP bind port (http mode)")
+    parser.add_argument("--runtime", default="v8", choices=("v8", "qjs"),
+                        help="script runtime (v8 carries the Java bridge)")
+    parser.add_argument("--retries", type=int, default=5, help="reconnect attempts before giving up")
+    parser.add_argument("--backoff", type=float, default=1.0,
+                        help="first reconnect delay (seconds); doubles per attempt")
+    opts = parser.parse_args(argv)
+
+    if opts.mode == "call" and not opts.export:
+        parser.error("--mode call requires --export")
+
+    bridge = RpcBridge(opts)
+    try:
+        bridge.ensure()
+    except RETRYABLE + (BridgeError, OSError) as exc:
+        sys.stderr.write("initial connect failed: %s\n" % exc)
+        return 2
+
+    if opts.mode == "call":
+        return run_call_mode(bridge, opts)
+    if opts.mode == "http":
+        return run_http_mode(bridge, opts)
+    return run_repl_mode(bridge, opts)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/skills/apk-reverse/scripts/lsposed_scaffold.py b/skills/apk-reverse/scripts/lsposed_scaffold.py
new file mode 100644
index 0000000..a550081
--- /dev/null
+++ b/skills/apk-reverse/scripts/lsposed_scaffold.py
@@ -0,0 +1,438 @@
+#!/usr/bin/env python3
+"""Scaffold a minimal LSPosed module project that builds without Gradle.
+
+Why this exists
+---------------
+Repackaging a hardened APK is not always the right route. When the app is
+integrity-checked, signature-derived, or simply cheaper to hook than to rebuild,
+the deliverable becomes a *module* instead of a patched APK, and the first
+obstacle is that every tutorial assumes Android Studio. This script writes the
+smallest project that a plain ``javac`` + ``d8`` + ``aapt2`` + ``apksigner``
+chain can turn into an installable module, and the README it writes contains
+that exact chain.
+
+What it writes
+--------------
+    <out>/AndroidManifest.xml        the three xposed meta-data keys LSPosed reads
+    <out>/assets/xposed_init         one line: the fully qualified entry class
+    <out>/src/<pkg path>/<Class>.java  the entry class (IXposedHookLoadPackage)
+    <out>/README.md                  build, install, enable, verify, failure modes
+
+The generated hook does two things on purpose, because both are diagnostics
+before they are features: it logs on every load of a scoped process (so
+"is the module injected at all" is answerable from logcat alone), and it hooks
+``Application.attach`` / ``Activity.onCreate`` (so the log names the real
+Activity classes even when a packer swaps the Application at runtime).
+
+Note on scope: LSPosed decides *which* processes to inject into from the scope
+list in its own configuration, not from anything this project declares. A
+generated ``TARGETS`` array is a second gate inside the module and must not be
+mistaken for the scope.
+
+Usage
+-----
+    lsposed_scaffold.py --package com.example.probe --name "Example probe" \\
+        --hook-target com.example.target --out ./module
+
+Requirements: python3 only. No third-party imports, no network.
+"""
+import argparse
+import os
+import re
+import sys
+
+MANIFEST_TMPL = """<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="__PACKAGE__">
+
+    <uses-sdk android:minSdkVersion="__MINSDK__" android:targetSdkVersion="__TARGETSDK__" />
+
+    <application android:label="__NAME__" android:hasCode="true">
+        <!-- These three keys are what LSPosed Manager reads. Without
+             xposedmodule=true the APK installs as an ordinary app and never
+             appears in the module list at all. xposedminversion=82 is the
+             classic XposedBridge API level and is accepted by LSPosed. -->
+        <meta-data android:name="xposedmodule" android:value="true" />
+        <meta-data android:name="xposeddescription" android:value="__DESC__" />
+        <meta-data android:name="xposedminversion" android:value="82" />
+    </application>
+</manifest>
+"""
+
+JAVA_TMPL = """package __PACKAGE__;
+
+import android.app.Activity;
+import android.app.Application;
+import android.content.Context;
+import android.os.Bundle;
+
+import de.robv.android.xposed.IXposedHookLoadPackage;
+import de.robv.android.xposed.XC_MethodHook;
+import de.robv.android.xposed.XposedBridge;
+import de.robv.android.xposed.XposedHelpers;
+import de.robv.android.xposed.callbacks.XC_LoadPackage;
+
+/**
+ * Entry class named by assets/xposed_init.
+ *
+ * Logcat is the evidence channel: LSPosed pushes XposedBridge.log() into the
+ * system log, so `adb logcat -s __TAG__` answers "did this module get injected"
+ * without attaching a debugger.
+ */
+public class __CLASS__ implements IXposedHookLoadPackage {
+
+    /** Short enough to stay readable in logcat. */
+    private static final String TAG = "__TAG__";
+
+    /**
+     * In-module gate, NOT the LSPosed scope. LSPosed already decides which
+     * processes receive handleLoadPackage; this array only keeps the hook body
+     * from acting on unintended processes if the scope is widened later.
+     */
+    private static final String[] TARGETS = new String[] { __TARGETS__ };
+
+    private static boolean isTarget(String pkg) {
+        for (String t : TARGETS) {
+            if (t.equals(pkg)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    @Override
+    public void handleLoadPackage(final XC_LoadPackage.LoadPackageParam lpp) throws Throwable {
+        // Fires once per scoped process, before any of the app's own code runs.
+        // This single line is the injection proof: if it is absent for a
+        // process you scoped, the problem is scope/enable state or the target
+        // process was never restarted, not your hook body.
+        try {
+            XposedBridge.log(TAG + " injected: " + lpp.packageName
+                    + "/" + lpp.processName + " cl=" + shortCl(lpp.classLoader));
+        } catch (Throwable t) {
+            XposedBridge.log(t);
+        }
+
+        if (!isTarget(lpp.packageName)) {
+            return;
+        }
+
+        // 1) Application.attach(Context) runs before the app's onCreate. Under a
+        //    packer thisObject is the stub Application, not the manifest name.
+        try {
+            XposedHelpers.findAndHookMethod(Application.class, "attach", Context.class,
+                    new XC_MethodHook() {
+                        @Override
+                        protected void afterHookedMethod(MethodHookParam param) throws Throwable {
+                            XposedBridge.log(TAG + " Application.attach -> "
+                                    + safeClass(param.thisObject));
+                        }
+                    });
+            XposedBridge.log(TAG + " hook installed: Application.attach");
+        } catch (Throwable t) {
+            XposedBridge.log(TAG + " attach-hook FAILED: " + t);
+        }
+
+        // 2) Activity lifecycle. Boot-classloader targets, so these install even
+        //    when the app's own classes are not yet resolvable.
+        try {
+            XposedHelpers.findAndHookMethod(Activity.class, "onCreate", Bundle.class,
+                    new XC_MethodHook() {
+                        @Override
+                        protected void afterHookedMethod(MethodHookParam param) throws Throwable {
+                            XposedBridge.log(TAG + " Activity.onCreate -> "
+                                    + safeClass(param.thisObject));
+                        }
+                    });
+            XposedBridge.log(TAG + " hook installed: Activity.onCreate");
+        } catch (Throwable t) {
+            XposedBridge.log(TAG + " activity-hook FAILED: " + t);
+        }
+__HOOK_BLOCK__
+    }
+
+    private static String safeClass(Object o) {
+        try {
+            return o == null ? "null" : o.getClass().getName();
+        } catch (Throwable t) {
+            return "<class-name-threw " + t.getClass().getSimpleName() + ">";
+        }
+    }
+
+    private static String shortCl(ClassLoader cl) {
+        try {
+            if (cl == null) {
+                return "null";
+            }
+            return cl.getClass().getName() + "@"
+                    + Integer.toHexString(System.identityHashCode(cl));
+        } catch (Throwable t) {
+            return "<cl-threw>";
+        }
+    }
+}
+"""
+
+HOOK_BLOCK_TMPL = """
+        // 3) Replace this with the method you actually care about. Find it at
+        //    runtime first (enumerate loaded classes / read a stack) rather than
+        //    guessing an obfuscated name from a decompiler.
+        try {
+            XposedHelpers.findAndHookMethod("__HOOKCLASS__", lpp.classLoader,
+                    "__HOOKMETHOD__", __PARAMTYPES__,
+                    new XC_MethodHook() {
+                        @Override
+                        protected void beforeHookedMethod(MethodHookParam param) throws Throwable {
+                            XposedBridge.log(TAG + " __HOOKCLASS__.__HOOKMETHOD__ entered");
+                        }
+                    });
+            XposedBridge.log(TAG + " hook installed: __HOOKCLASS__.__HOOKMETHOD__");
+        } catch (Throwable t) {
+            XposedBridge.log(TAG + " target-hook FAILED: " + t);
+        }
+"""
+
+README_TMPL = """# __NAME__
+
+Minimal LSPosed module generated by `lsposed_scaffold.py`.
+
+- module package: `__PACKAGE__`
+- entry class: `__PACKAGE__.__CLASS__` (named in `assets/xposed_init`)
+- in-module target gate: __TARGETLIST__
+- minSdk __MINSDK__ / targetSdk __TARGETSDK__
+
+The LSPosed *scope* is separate from the target gate above: scope is configured
+in LSPosed Manager, and a module is injected into a process only when the scope
+contains that package **and** the module is enabled.
+
+## Build without Gradle
+
+You need a JDK (17 works), Android build-tools, an `android.jar` for the SDK you
+declare, and the Xposed API stub jar (`de.robv.android.xposed:api:82`, about
+25 KB). Set the three variables, then run the steps in order. There is no
+resource to compile; the module ships only a manifest, assets and a dex.
+
+```sh
+BT=/path/to/build-tools/34.0.0
+AJ=/path/to/android.jar            # e.g. platforms/android-28/android.jar
+API=/path/to/api-82.jar
+OUT=build
+
+# 1. Java -> class files. -source/-target 8 keeps d8 happy; Android API classes
+#    come from -cp, not from the JDK. (`-bootclasspath` is gone in JDK 9+.)
+javac -encoding UTF-8 -source 8 -target 8 -nowarn \\
+    -cp "$AJ:$API" -d "$OUT/classes" src/__PATH__/__CLASS__.java
+
+# 2. d8 wants a jar, NOT a directory -- a directory dies with
+#    "Unsupported source file type".
+jar cf "$OUT/classes.jar" -C "$OUT/classes" .
+"$BT/d8" --min-api __MINSDK__ --lib "$AJ" --output "$OUT" "$OUT/classes.jar"
+
+# 3. manifest + assets -> base apk (no res/ in this project)
+"$BT/aapt2" link -o "$OUT/base.apk" -I "$AJ" \\
+    --manifest AndroidManifest.xml \\
+    --min-sdk-version __MINSDK__ --target-sdk-version __TARGETSDK__ \\
+    -A assets
+
+# 4. add the dex. aapt resolves the path relative to the cwd and stores the same
+#    name, so run it from $OUT with classes.dex sitting there.
+cp "$OUT/base.apk" "$OUT/unsigned.apk"
+cp "$OUT/classes.dex" "$OUT/classes.dex.tmp" && mv "$OUT/classes.dex.tmp" "$OUT/classes.dex"
+(cd "$OUT" && "$BT/aapt" add unsigned.apk classes.dex)
+
+# 5. align, then sign (v2 is enough for Android 7+)
+"$BT/zipalign" -f -p 4 "$OUT/unsigned.apk" "$OUT/aligned.apk"
+keytool -genkeypair -keystore "$OUT/test.keystore" -alias mod -keyalg RSA \\
+    -keysize 2048 -validity 10000 -storepass android -keypass android \\
+    -dname "CN=module, O=local"
+"$BT/apksigner" sign --ks "$OUT/test.keystore" --ks-pass pass:android \\
+    --key-pass pass:android --v2-signing-enabled true \\
+    --out "$OUT/module.apk" "$OUT/aligned.apk"
+"$BT/apksigner" verify --print-certs "$OUT/module.apk"
+```
+
+Windows: same steps; `d8`, `apksigner` and `aapt` ship as `.bat` wrappers, and
+the classpath separator is `;`. Note that `jar` and `keytool` are frequently
+**not** on `PATH` even when `javac` is (Oracle's `javapath` shim exposes only
+`java`/`javac`), so call them from the JDK's `bin` directory explicitly.
+
+## Install, enable, verify
+
+```sh
+adb install -r build/module.apk
+adb shell pm list packages | grep __PACKAGE__          # installed
+adb shell dumpsys package __PACKAGE__ | grep enabled   # enabled=0 means DISABLED by the PM
+adb shell pm enable __PACKAGE__                        # only if it shows enabled=0
+```
+
+`pm enable` is about the *package manager* state; it is not the LSPosed module
+switch. Then, in LSPosed Manager: open the module list, enable the module, and
+tick the scope entry for the target package.
+
+Verification has two channels. Use the platform log where it works, and always the module log:
+
+```sh
+adb -s <serial> shell "su -c 'cat /data/adb/lspd/log/modules_<timestamp>.log'"   # module log
+adb -s <serial> logcat -s __TAG__                                                # platform log
+```
+
+Expected first line in either: `__TAG__ injected: <target>/<process> ...`. The platform log can be
+**completely empty** on a device whose `logd` route is broken (a log file that opens with
+`Logd maybe crashed (err=Socket operation on non-socket)` is the tell); the module log is written
+either way, so check it before concluding the module never ran. No line in either channel means the
+module was not injected into that process. Check, in this order: module
+enabled in LSPosed Manager, package present in scope, module APK still installed,
+and **the target process restarted after the scope change** -- scope changes are
+read for newly forked processes, so a running process keeps the old decision.
+
+## Failure modes worth knowing
+
+- `d8` on a directory: `Unsupported source file type`. Jar the classes first.
+- `aapt add` says the file is missing: it resolves relative to the cwd and keeps
+  the given name, so `classes.dex` must exist in the directory you run it from.
+- Module never appears in LSPosed Manager: the `xposedmodule` meta-data is
+  missing or mistyped in the merged manifest.
+- Module listed but injection logs never appear: enabled state, scope, or a stale
+  target process -- in that order.
+- Module injected but your `TARGETS` array skips everything: that is the in-module
+  gate, not LSPosed. Read the gate before blaming the framework.
+"""
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="lsposed_scaffold.py",
+        description="Write a minimal, Gradle-free LSPosed module project "
+                    "(manifest, xposed_init, entry class, build README).",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="Example:\n"
+               "  lsposed_scaffold.py --package com.example.probe \\\n"
+               "      --name \"Example probe\" --hook-target com.example.target \\\n"
+               "      --hook-class com.example.target.Helper --hook-method check \\\n"
+               "      --out ./module\n")
+    p.add_argument("--package", required=True,
+                   help="module package name, e.g. com.example.probe")
+    p.add_argument("--name", required=True,
+                   help="human-readable module name shown in LSPosed Manager")
+    p.add_argument("--hook-target", action="append", default=None, dest="targets",
+                   help="package the module acts on; repeat for several. "
+                        "This is the in-module gate, not the LSPosed scope")
+    p.add_argument("--out", required=True, help="output project directory")
+    p.add_argument("--class-name", default="MainHook",
+                   help="entry class name (default %(default)s)")
+    p.add_argument("--tag", default=None,
+                   help="logcat tag; default derived from --class-name (max 20 chars)")
+    p.add_argument("--description", default="Hook module generated by lsposed_scaffold.py",
+                   help="value of xposeddescription")
+    p.add_argument("--min-sdk", type=int, default=24, help="minSdkVersion (default %(default)s)")
+    p.add_argument("--target-sdk", type=int, default=28, help="targetSdkVersion (default %(default)s)")
+    p.add_argument("--hook-class", default=None,
+                   help="optional concrete class to hook (adds a worked example block)")
+    p.add_argument("--hook-method", default=None,
+                   help="method name to hook (requires --hook-class)")
+    p.add_argument("--hook-params", default="",
+                   help="comma-separated parameter types for --hook-method, "
+                        "e.g. 'java.lang.String,android.content.Context' (default: none)")
+    p.add_argument("--force", action="store_true",
+                   help="overwrite files that already exist in --out")
+    return p
+
+
+PKG_RE = re.compile(r'^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$')
+CLASS_RE = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*$')
+
+
+def fail(msg):
+    print("[!] %s" % msg, file=sys.stderr)
+    return 2
+
+
+def write_file(path, text, force):
+    if os.path.exists(path) and not force:
+        print("[=] exists, left alone: %s" % path)
+        return False
+    d = os.path.dirname(path)
+    if d:
+        os.makedirs(d, exist_ok=True)
+    # newline="\n" so a scaffold written on Windows still builds on POSIX
+    with open(path, 'w', encoding='utf-8', newline='\n') as fh:
+        fh.write(text)
+    print("[+] %s" % path)
+    return True
+
+
+def params_java(spec):
+    """'java.lang.String,android.content.Context' -> 'java.lang.String.class,
+    android.content.Context.class'."""
+    parts = [x.strip() for x in spec.split(',') if x.strip()]
+    if not parts:
+        return ''
+    return ', '.join('%s.class' % x for x in parts)
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+
+    if not PKG_RE.match(args.package):
+        return fail("--package %r is not a valid Java package name" % args.package)
+    if not CLASS_RE.match(args.class_name):
+        return fail("--class-name %r is not a valid Java identifier" % args.class_name)
+    targets = args.targets or ['<target.package>']
+    for t in targets:
+        if not PKG_RE.match(t) and t != '<target.package>':
+            return fail("--hook-target %r is not a valid package name" % t)
+    if args.hook_method and not args.hook_class:
+        return fail("--hook-method requires --hook-class")
+
+    tag = args.tag or args.class_name.upper()[:20]
+
+    hook_block = ''
+    if args.hook_class and args.hook_method:
+        hook_block = (HOOK_BLOCK_TMPL
+                      .replace('__HOOKCLASS__', args.hook_class)
+                      .replace('__HOOKMETHOD__', args.hook_method)
+                      .replace('__PARAMTYPES__', params_java(args.hook_params)))
+
+    java = (JAVA_TMPL
+            .replace('__PACKAGE__', args.package)
+            .replace('__CLASS__', args.class_name)
+            .replace('__TAG__', tag)
+            .replace('__TARGETS__', ', '.join('"%s"' % t for t in targets))
+            .replace('__HOOK_BLOCK__', hook_block))
+
+    manifest = (MANIFEST_TMPL
+                .replace('__PACKAGE__', args.package)
+                .replace('__NAME__', args.name)
+                .replace('__DESC__', args.description)
+                .replace('__MINSDK__', str(args.min_sdk))
+                .replace('__TARGETSDK__', str(args.target_sdk)))
+
+    readme = (README_TMPL
+              .replace('__NAME__', args.name)
+              .replace('__PACKAGE__', args.package)
+              .replace('__CLASS__', args.class_name)
+              .replace('__TAG__', tag)
+              .replace('__PATH__', args.package.replace('.', '/'))
+              .replace('__TARGETLIST__', ', '.join('`%s`' % t for t in targets))
+              .replace('__MINSDK__', str(args.min_sdk))
+              .replace('__TARGETSDK__', str(args.target_sdk)))
+
+    src = os.path.join(args.out, 'src', args.package.replace('.', os.sep),
+                       '%s.java' % args.class_name)
+    write_file(os.path.join(args.out, 'AndroidManifest.xml'), manifest, args.force)
+    write_file(os.path.join(args.out, 'assets', 'xposed_init'),
+               '%s.%s\n' % (args.package, args.class_name), args.force)
+    write_file(src, java, args.force)
+    write_file(os.path.join(args.out, 'README.md'), readme, args.force)
+
+    print("")
+    print("Next: build it with the chain in %s/README.md, then install, enable"
+          " the module in LSPosed Manager, and add the target to its scope."
+          % args.out)
+    print("Do not confuse the scope (LSPosed Manager) with the in-module gate"
+          " (TARGETS in %s.java)." % args.class_name)
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())
diff --git a/skills/apk-reverse/scripts/mt_mcp_probe.py b/skills/apk-reverse/scripts/mt_mcp_probe.py
new file mode 100644
index 0000000..2294b7c
--- /dev/null
+++ b/skills/apk-reverse/scripts/mt_mcp_probe.py
@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""Probe the MT Manager built-in APK MCP server (Streamable HTTP).
+
+MT Manager (bin.mt.plus) ships an "APK MCP" service that exposes its APK
+analysis/edit/repack/sign capabilities to MCP clients over Streamable HTTP,
+by default on device port 8787 (reachable from the PC via
+``adb forward tcp:8787 tcp:8787``).
+
+This script does the MCP handshake by hand (JSON-RPC 2.0 over plain HTTP
+POSTs, no mcp SDK dependency):
+
+  1. ``initialize``        -> serverInfo + capabilities
+  2. ``notifications/initialized``
+  3. ``tools/list``        -> tool inventory
+
+Output is a human-readable capability report grouping the ``mt_apk_*`` tools
+by category. When the server is not up yet (it must be started by hand in
+the MT UI; adb cannot start it), the script prints waiting instructions and
+exits 2, so it can also be used as a "is it up yet" check in a loop.
+
+Verification status of the protocol shape: measured against the MT 2.26.9
+implementation on 2026-09 (see docs/tool-verification/EXTENSION-kernel-ondevice.md).
+"""
+
+import argparse
+import json
+import sys
+import urllib.error
+import urllib.request
+
+DEFAULT_URL = "http://127.0.0.1:8787/mcp"
+
+# Tool categories for the report, keyed by name prefix within mt_apk_*.
+CATEGORIES = [
+    ("open", "APK open/selection"),
+    ("list", "Entry listing"),
+    ("search", "Text/string search"),
+    ("read", "Content read"),
+    ("dex", "Dex analysis"),
+    ("resource", "Resources"),
+    ("native", "Native (.so) static analysis"),
+    ("edit", "Edit sessions"),
+    ("patch", "Byte/instruction patching"),
+    ("build", "Repack + sign"),
+    ("close", "Cleanup"),
+]
+
+
+def http_post(url, payload, session_id=None, timeout=10.0):
+    """POST one JSON-RPC message; return (status, headers, parsed-body-or-None).
+
+    Handles both plain application/json responses and text/event-stream
+    (SSE-framed) responses, which Streamable HTTP servers may use for
+    request bodies. Returns the first JSON object found in either shape.
+    """
+    body = json.dumps(payload).encode("utf-8")
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+    }
+    if session_id:
+        headers["Mcp-Session-Id"] = session_id
+    req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8", "replace")
+            sid = resp.headers.get("Mcp-Session-Id")
+            return resp.status, sid, parse_body(raw, resp.headers.get("Content-Type", ""))
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode("utf-8", "replace")
+        return e.code, None, parse_body(raw, e.headers.get("Content-Type", ""))
+
+
+def parse_body(raw, ctype):
+    """Extract the first JSON message from a JSON or SSE-framed body."""
+    raw = raw.strip()
+    if not raw:
+        return None
+    if "text/event-stream" in (ctype or ""):
+        for line in raw.splitlines():
+            if line.startswith("data:"):
+                chunk = line[len("data:"):].strip()
+                try:
+                    return json.loads(chunk)
+                except ValueError:
+                    continue
+        return None
+    try:
+        return json.loads(raw)
+    except ValueError:
+        return None
+
+
+def print_waiting_help(url):
+    host = "127.0.0.1"
+    print("[waiting] MCP server is not answering at %s" % url)
+    print()
+    print("The MT APK MCP must be started by hand in the MT UI (adb cannot start it):")
+    print("  1. On the phone: MT Manager -> side drawer -> Tools -> APK MCP -> Start")
+    print("  2. Note the address shown on that page (host:port, default 8787)")
+    print("  3. On the PC, make the port reachable over USB:")
+    print("       adb forward tcp:8787 tcp:8787")
+    print("  4. Re-run this probe:  python mt_mcp_probe.py")
+    print()
+    print("(LAN alternative: connect the PC and phone to the same network and pass")
+    print(" --url http://<phone-ip>:8787/mcp)")
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Probe the MT Manager APK MCP (Streamable HTTP) and list its tools.")
+    ap.add_argument("--url", default=DEFAULT_URL,
+                    help="MCP endpoint (default: %(default)s)")
+    ap.add_argument("--timeout", type=float, default=10.0,
+                    help="per-request timeout in seconds (default: %(default)s)")
+    ap.add_argument("--json", action="store_true",
+                    help="print raw JSON-RPC responses instead of the report")
+    args = ap.parse_args()
+
+    # 1) initialize
+    init = {
+        "jsonrpc": "2.0", "id": 1, "method": "initialize",
+        "params": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "mt-mcp-probe", "version": "0.1"},
+        },
+    }
+    try:
+        status, session_id, body = http_post(args.url, init, timeout=args.timeout)
+    except (urllib.error.URLError, OSError) as e:
+        print_waiting_help(args.url)
+        if args.json:
+            print("[error] %s" % e)
+        return 2
+
+    if body is None or "result" not in (body or {}):
+        print("[unexpected] HTTP %d, no MCP initialize result in response" % status)
+        if args.json:
+            print(json.dumps(body, indent=2) if body is not None else "(empty body)")
+        return 1
+
+    result = body["result"]
+    server = result.get("serverInfo", {})
+    proto = result.get("protocolVersion", "?")
+    print("[online] %s | server %s %s | protocol %s | HTTP %d%s" % (
+        args.url, server.get("name", "?"), server.get("version", "?"),
+        proto, status, " | session %s" % session_id if session_id else ""))
+    if args.json:
+        print(json.dumps(result, indent=2))
+
+    # 2) initialized notification (no id -> notification; 202 expected, body ignored)
+    note = {"jsonrpc": "2.0", "method": "notifications/initialized"}
+    try:
+        http_post(args.url, note, session_id=session_id, timeout=args.timeout)
+    except (urllib.error.URLError, OSError):
+        pass  # some servers accept it silently; tools/list will tell us
+
+    # 3) tools/list
+    listing = {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}
+    try:
+        status, _, body = http_post(args.url, listing, session_id=session_id,
+                                    timeout=args.timeout)
+    except (urllib.error.URLError, OSError) as e:
+        print("[error] tools/list failed after successful initialize: %s" % e)
+        return 1
+
+    if body is None or "result" not in (body or {}):
+        print("[unexpected] HTTP %d, no tools/list result" % status)
+        if args.json:
+            print(json.dumps(body, indent=2) if body is not None else "(empty body)")
+        return 1
+
+    tools = body["result"].get("tools", [])
+    if args.json:
+        print(json.dumps(body, indent=2))
+
+    # 4) capability report
+    print()
+    print("== MCP tool inventory: %d tool(s) ==" % len(tools))
+    mt_tools = [t for t in tools if t.get("name", "").startswith("mt_apk_")]
+    other = [t for t in tools if not t.get("name", "").startswith("mt_apk_")]
+
+    grouped = {prefix: [] for prefix, _ in CATEGORIES}
+    for t in sorted(mt_tools, key=lambda x: x.get("name", "")):
+        name = t.get("name", "")
+        suffix = name[len("mt_apk_"):]
+        placed = False
+        for prefix, label in CATEGORIES:
+            if suffix == prefix or suffix.startswith(prefix + "_"):
+                grouped[prefix].append(t)
+                placed = True
+                break
+        if not placed:
+            grouped.setdefault("misc", []).append(t)
+
+    for prefix, label in CATEGORIES:
+        items = grouped.get(prefix, [])
+        if not items:
+            continue
+        print("\n[%s] %s" % (label, len(items)))
+        for t in items:
+            desc = (t.get("description") or "").strip().splitlines()
+            first = desc[0].strip() if desc else ""
+            print("  %-42s %s" % (t.get("name"), first[:90]))
+    if grouped.get("misc"):
+        print("\n[other mt_apk_*] %d" % len(grouped["misc"]))
+        for t in grouped["misc"]:
+            print("  %s" % t.get("name"))
+
+    if other:
+        print("\n[non-mt_apk tools] %d" % len(other))
+        for t in other:
+            print("  %s" % t.get("name"))
+
+    print()
+    print("Constraints (from the official MT MCP docs, see on-device-tooling.md):")
+    print("  - no Java decompilation; read smali directly instead")
+    print("  - .so support is static analysis only (no dynamic run, no pseudo-C)")
+    print("  - resources.arsc: existing entries editable, no new locales/entries")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/skills/apk-reverse/scripts/rpc_template.js b/skills/apk-reverse/scripts/rpc_template.js
new file mode 100644
index 0000000..f8de50d
--- /dev/null
+++ b/skills/apk-reverse/scripts/rpc_template.js
@@ -0,0 +1,79 @@
+// rpc_template.js — editable rpc.exports example for frida_rpc_serve.py.
+//
+// Three shapes every target needs, already wired:
+//   1. add      — a pure-JS export, proves the transport with zero target knowledge
+//   2. getpackagename — a harmless Java probe (calls a framework method via JNI)
+//   3. callnative — a native-call placeholder: wrap any exported symbol of any
+//                  loaded module and call it with explicit types
+//
+// Adapt 3 to your target: the hardened .so that computes a signature or an
+// encryption is usually either exported (Module.findExportByName) or bound at
+// runtime via RegisterNatives (hook RegisterNatives first to learn the address,
+// then pass the raw address to callnativeaddr).
+
+'use strict';
+
+function log(ev, data) {
+  try { send(Object.assign({ t: Date.now(), ev: ev }, data || {})); } catch (e) {}
+}
+
+// Export lookup that works across frida 16/17 (Module.findExportByName(null,..)
+// was removed in 17; getGlobalExportByName is the replacement).
+function resolveExport(name) {
+  try { if (Module.getGlobalExportByName) return Module.getGlobalExportByName(name); } catch (e) {}
+  try { if (Module.findExportByName) return Module.findExportByName(null, name); } catch (e) {}
+  try {
+    const libc = Process.findModuleByName('libc.so');
+    if (libc) return libc.getExportByName(name);
+  } catch (e) {}
+  return null;
+}
+
+rpc.exports = {
+  // 1) pure-JS demo — sanity-check the RPC transport itself.
+  add: function (a, b) {
+    return a + b;
+  },
+
+  ping: function () {
+    return 'pong';
+  },
+
+  // 2) harmless Java probe: the package name of the process we live in.
+  //    Works on any app process with a live Java VM; needs no target knowledge.
+  getpackagename: function () {
+    let out = null;
+    Java.perform(function () {
+      const app = Java.use('android.app.ActivityThread').currentApplication();
+      out = app.getPackageName();
+    });
+    return out;
+  },
+
+  // 3) NATIVE CALL PLACEHOLDER — adapt module/name/ret/arg types to your target.
+  //    moduleName null means "search every loaded module" (global export lookup).
+  callnative: function (moduleName, exportName, retType, argTypes, args) {
+    let addr = null;
+    if (moduleName) {
+      const base = Module.findBaseAddress(moduleName);
+      if (base === null) throw new Error('module not loaded: ' + moduleName);
+      addr = Module.findExportByName(moduleName, exportName);
+    } else {
+      addr = resolveExport(exportName);
+    }
+    if (addr === null) throw new Error('export not found: ' + exportName);
+    const fn = new NativeFunction(addr, retType, argTypes);
+    return fn.apply(null, args || []);
+  },
+
+  // Variant for symbols that never hit the export table (dynamically registered
+  // JNI, or an offset inside a stripped .so): pass module name + raw offset.
+  callnativeaddr: function (moduleName, offset, retType, argTypes, args) {
+    const base = Module.findBaseAddress(moduleName);
+    if (base === null) throw new Error('module not loaded: ' + moduleName);
+    const fn = new NativeFunction(base.add(offset), retType, argTypes);
+    return fn.apply(null, args || []);
+  }
+};
+
+log('RPC-READY', { exports: Object.keys(rpc.exports) });
diff --git a/skills/apk-reverse/scripts/stalker_report.py b/skills/apk-reverse/scripts/stalker_report.py
new file mode 100644
index 0000000..b05b502
--- /dev/null
+++ b/skills/apk-reverse/scripts/stalker_report.py
@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Summarize a stalker_trace.js log: block histogram, skeleton, call edges.
+
+WHY THIS EXISTS
+---------------
+scripts/stalker_trace.js records, for one target module, the basic blocks a
+thread really executed. Raw, that log answers nothing -- the value comes from
+three reductions, and each maps to a deobfuscation decision:
+
+  * execution histogram (BLK lines) -- in a control-flow-flattened function
+    the dispatcher block runs orders of magnitude more often than any real
+    block; the top of this histogram IS the dispatcher;
+  * first-visit order (BB lines) -- the deduplicated block set in first-visit
+    order approximates the real CFG skeleton with the flattening state machine
+    stripped out;
+  * call edges (CALL lines) -- which functions inside the module talk to each
+    other, independent of symbol names.
+
+This tool is deliberately stdlib-only and parses text, so it works on logs
+written by run_probe.py (each event line embedded in a `[host ts] [dev ts]
+TRACE ...` wrapper) and on raw one-event-per-line logs alike.
+
+Usage
+-----
+  python stalker_report.py trace.log
+  python stalker_report.py trace.log --top 30 --skeleton 80
+  python stalker_report.py trace.log --json report.json
+  python stalker_report.py trace.log --quiet          # summary only
+
+Reading the output
+------------------
+  * DONE ... truncated=1  -- the trace hit maxBlocks; ratios are still useful,
+    absolute counts are not.
+  * zero BLK but nonzero BB -- the thread stopped between translation and
+    execution (short follow, or the trigger returned immediately).
+  * zero BB and zero BLK with DONE present -- module never ran on the followed
+    thread; pick a real trigger instead of `main`.
+  * everything zero, no DONE -- the trace never started: check READY/TRIG-FAIL
+    lines in the log first.
+"""
+
+import argparse
+import json
+import re
+import sys
+from collections import Counter, OrderedDict
+
+MOD_RE = re.compile(r'\bMOD (\S+) base=(0x[0-9a-fA-F]+) size=(\d+)(?:\s+path=(\S+))?')
+BB_RE = re.compile(r'\bBB (\d+) (\S+)\+0x([0-9a-fA-F]+)')
+BLK_RE = re.compile(r'\bBLK (\d+) (\S+)\+0x([0-9a-fA-F]+)(?:\s+size=(\d+))?')
+CALL_RE = re.compile(r'\bCALL (\S+) (\S+) -> (\S+)')
+DONE_RE = re.compile(r'\bDONE reason=(\S+) blocks=(\d+) blk=(\d+) calls=(\d+) truncated=(\d)')
+FATAL_RE = re.compile(r'\b(FATAL|TRIG-FAIL) (.*)')
+
+
+def parse_log(path):
+    stats = {
+        'mods': OrderedDict(),        # name -> {base, size, path}
+        'bb': [],                     # (seq, mod, offset) first-visit order
+        'blk': [],                    # (seq, mod, offset, size|None) executions
+        'calls': [],                  # (depth, from, to)
+        'done': None,
+        'fatals': [],
+    }
+    with open(path, encoding='utf-8', errors='replace') as fh:
+        for raw in fh:
+            m = MOD_RE.search(raw)
+            if m:
+                name, base, size, path = m.groups()
+                if name not in stats['mods']:
+                    stats['mods'][name] = {
+                        'base': base, 'size': int(size), 'path': path or ''}
+                continue
+            m = BLK_RE.search(raw)
+            if m:
+                seq, mod, off, size = m.groups()
+                stats['blk'].append((int(seq), mod, int(off, 16),
+                                     int(size) if size else None))
+                continue
+            m = BB_RE.search(raw)
+            if m:
+                seq, mod, off = m.groups()
+                stats['bb'].append((int(seq), mod, int(off, 16)))
+                continue
+            m = CALL_RE.search(raw)
+            if m:
+                stats['calls'].append(m.groups())
+                continue
+            m = DONE_RE.search(raw)
+            if m and stats['done'] is None:
+                stats['done'] = m.groups()
+                continue
+            m = FATAL_RE.search(raw)
+            if m:
+                stats['fatals'].append(m.group(0).strip())
+    return stats
+
+
+def blockkey(mod, off):
+    return '%s+0x%x' % (mod, off)
+
+
+def collapse_consecutive(items):
+    """[(mod, off), ...] -> [(key, repeats), ...] with runs collapsed."""
+    out = []
+    for mod, off in items:
+        key = blockkey(mod, off)
+        if out and out[-1][0] == key:
+            out[-1] = (key, out[-1][1] + 1)
+        else:
+            out.append((key, 1))
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description='Summarize a stalker_trace.js log into a block histogram, '
+                    'a first-visit CFG skeleton, and call-edge tables.')
+    ap.add_argument('log', help='trace log written by run_probe.py (wrapped '
+                                'lines are fine) or a raw event-per-line log')
+    ap.add_argument('--top', type=int, default=20,
+                    help='rows in the execution histogram (default 20)')
+    ap.add_argument('--skeleton', type=int, default=40,
+                    help='rows of the first-visit order to print (default 40)')
+    ap.add_argument('--edges', type=int, default=15,
+                    help='rows in the call-edge table (default 15)')
+    ap.add_argument('--seq', type=int, default=60,
+                    help='entries of the collapsed execution sequence to print '
+                         '(default 60)')
+    ap.add_argument('--json', metavar='PATH', default=None,
+                    help='also write the full reduced data as JSON')
+    ap.add_argument('--quiet', action='store_true',
+                    help='print the summary block only')
+    args = ap.parse_args()
+
+    st = parse_log(args.log)
+
+    print('== summary ==')
+    for name, info in st['mods'].items():
+        print('  module %-24s base=%s size=%d %s'
+              % (name, info['base'], info['size'],
+                 ('(target)' if st['bb'] and st['bb'][0][1] == name else '')))
+    print('  unique blocks first-seen (BB) : %d' % len(st['bb']))
+    print('  block executions (BLK)        : %d' % len(st['blk']))
+    print('  call edges (CALL)             : %d' % len(st['calls']))
+    if st['done']:
+        reason, nb, nk, nc, trunc = st['done']
+        print('  DONE reason=%s truncated=%s (device-side counts: bb=%s blk=%s call=%s)'
+              % (reason, trunc, nb, nk, nc))
+    else:
+        print('  DONE line missing -- trace ended without a clean stop '
+              '(detach or crash?)')
+    for f in st['fatals'][:5]:
+        print('  NOTE %s' % f)
+
+    if not st['bb'] and not st['blk']:
+        print('\n  no target-module blocks at all. In order of likelihood:\n'
+              '    1. the module was never loaded on the followed thread '
+              '(check the MOD lines);\n'
+              '    2. the trigger never fired (TRIG-FAIL above, or the app '
+              'never called it);\n'
+              '    3. the follow window closed before any code ran '
+              '(raise followMs, or use a call trigger instead of main).')
+        return 0 if st['done'] else 1
+
+    first_seen = {}
+    for seq, mod, off in st['bb']:
+        first_seen.setdefault(blockkey(mod, off), seq)
+
+    if not args.quiet:
+        hist = Counter(blockkey(mod, off) for _, mod, off, _ in st['blk'])
+        total = sum(hist.values())
+        if hist:
+            print('\n== execution histogram: top %d (dispatcher candidates) ==' % args.top)
+            print('  %-6s %-8s %-7s %-28s %s'
+                  % ('rank', 'count', 'pct', 'block', 'firstSeen'))
+            for rank, (key, cnt) in enumerate(hist.most_common(args.top), 1):
+                pct = 100.0 * cnt / total if total else 0.0
+                print('  %-6d %-8d %5.1f%%  %-28s #%s'
+                      % (rank, cnt, pct, key, first_seen.get(key, '-')))
+            print('  (a block at the top by a wide margin, with many distinct '
+                  'successors below,\n   is the classic control-flow-'
+                  'flattening dispatcher; see\n   references/'
+                  'native-dbi-and-deobfuscation.md)')
+
+        if st['bb']:
+            print('\n== first-visit order (CFG skeleton, first %d of %d) =='
+                  % (min(args.skeleton, len(st['bb'])), len(st['bb'])))
+            for seq, mod, off in st['bb'][:args.skeleton]:
+                print('  #%d %s' % (seq, blockkey(mod, off)))
+
+        if st['calls']:
+            edges = Counter('%s -> %s' % (frm, to) for _, frm, to in st['calls'])
+            print('\n== call edges (top %d of %d) ==' % (args.edges, len(edges)))
+            for edge, cnt in edges.most_common(args.edges):
+                print('  %-8d %s' % (cnt, edge))
+
+        collapsed = collapse_consecutive([(mod, off) for _, mod, off, _ in st['blk']])
+        if collapsed:
+            print('\n== collapsed execution sequence (first %d runs of %d) =='
+                  % (min(args.seq, len(collapsed)), len(collapsed)))
+            line = '  '
+            for key, reps in collapsed[:args.seq]:
+                piece = key + ('*%d' % reps if reps > 1 else '')
+                if len(line) + len(piece) > 100:
+                    print(line)
+                    line = '  '
+                line += piece + ' -> '
+            if line.strip():
+                print(line[:-4])
+
+    if args.json:
+        payload = {
+            'modules': st['mods'],
+            'summary': {
+                'bb': len(st['bb']), 'blk': len(st['blk']),
+                'calls': len(st['calls']), 'done': st['done'],
+            },
+            'first_seen': first_seen,
+            'histogram': dict(Counter(
+                blockkey(mod, off) for _, mod, off, _ in st['blk'])),
+            'bb_sequence': [blockkey(mod, off) for _, mod, off in st['bb']],
+            'collapsed': collapsed if st['blk'] else [],
+            'call_edges': dict(Counter('%s -> %s' % (f, t)
+                                       for _, f, t in st['calls'])),
+        }
+        with open(args.json, 'w', encoding='utf-8') as fh:
+            json.dump(payload, fh, indent=1)
+        print('\njson written to %s' % args.json)
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())
diff --git a/skills/apk-reverse/scripts/stalker_trace.js b/skills/apk-reverse/scripts/stalker_trace.js
new file mode 100644
index 0000000..4e59dc3
--- /dev/null
+++ b/skills/apk-reverse/scripts/stalker_trace.js
@@ -0,0 +1,456 @@
+/*
+ * stalker_trace.js -- record a basic-block-level Stalker trace of one native module.
+ *
+ * WHY THIS SHAPE
+ * --------------
+ * Static disassembly of an obfuscated library (OLLVM control-flow flattening and
+ * friends) answers "what COULD run". The question that actually breaks the
+ * obfuscation is "what DID run, and how often" -- the dispatcher block of a
+ * flattened function executes orders of magnitude more often than the real
+ * blocks, and that ratio is invisible statically. Frida Stalker answers it:
+ * it re-compiles every basic block the target thread executes and reports each
+ * block back, without needing symbols, source, or even a loadable disassembler
+ * on the host.
+ *
+ * Three rules keep the trace usable, and violating each one is a documented
+ * failure mode:
+ *
+ *   1. FOLLOW ONE TRIGGER, NOT THE WHOLE PROCESS. Stalker on an unrestricted
+ *      thread produces gigabytes and the app dies of slowdown. The trace starts
+ *      when a trigger fires (an export call, an offset call, a Java method, or
+ *      the main thread) and stops after followMs or when the trigger returns.
+ *   2. FILTER TO ONE MODULE. Only blocks whose address falls inside
+ *      CONFIG.targetModule are reported (call edges report when either end is
+ *      inside). Everything else is dropped on the device, not in post.
+ *   3. CAP THE VOLUME. maxBlocks stops the trace instead of letting the log
+ *      eat the disk; the DONE line says whether truncation happened.
+ *
+ * ADAPT TO YOUR TARGET (CONFIG below, or rpc/recv at runtime)
+ * -----------------------------------------------------------
+ *   targetModule : the .so you are analyzing ('libapp.so', 'libflutter.so', ...)
+ *   trigger.kind : 'export'  -- trigger.module + trigger.export (e.g. a JNI fn)
+ *                | 'offset'  -- trigger.module + trigger.offset (mod-relative)
+ *                | 'java'    -- trigger.cls + trigger.method (Java bridge; the
+ *                               classic java->native boundary)
+ *                | 'main'    -- follow the main thread right after load; use on
+ *                               a quiet/attached process and poke the UI
+ *   followMs     : hard stop, so a forgotten trace cannot kill the process
+ *   events       : compile = first time a block is translated (dedup'd block
+ *                  set + first-visit order = CFG skeleton);
+ *                  block = every executed block (execution counts; the
+ *                  histogram that exposes the dispatcher);
+ *                  call = call edges (call graph into/out of the module);
+ *                  exec = per-instruction (ENORMOUS; only for a few hundred
+ *                  instructions around a known point; off by default);
+ *                  ret = return edges (off by default).
+ *
+ * HOW TO RUN
+ * ----------
+ *   With the bundled injector (constants must be baked into CONFIG):
+ *       python run_probe.py stalker_trace.js 2 --pkg com.example.app --log t.log
+ *   With any driver that speaks rpc (no file edit needed):
+ *       script.exports.config({ targetModule: 'libapp.so',
+ *                               trigger: { kind: 'offset', module: 'libapp.so',
+ *                                          offset: 0x1234 } })
+ *       script.exports.start()
+ *   Or post a config message instead of rpc:
+ *       script.post({ type: 'cfg', payload: {...same shape as CONFIG...} })
+ *
+ * OUTPUT FORMAT (one logical line per event; multi-line batches share one send)
+ * ----------------------------------------------------------------------------
+ *   READY ...            config echo + module status; nothing works before it
+ *   MOD name base=0x.. size=.. path=..
+ *                        module base, so offline tools map offsets back
+ *   BB <seq> <mod>+0x<offset>
+ *                        block first translated (dedup'd CFG skeleton)
+ *   BLK <seq> <mod>+0x<offset> [size=<n>]
+ *                        block executed (weighted histogram input)
+ *   CALL <depth> <from> -> <to>
+ *                        call edge; addresses are <module>+0x<off> when the
+ *                        module is known, raw hex otherwise
+ *   DONE reason=timeout|trigger-leave|maxBlocks|stop-rpc blocks=<n>
+ *        blk=<n> calls=<n> truncated=<0|1>
+ *   FATAL / TRIG-FAIL    what did not install and why (the script keeps running)
+ *
+ *   Feed the log to scripts/stalker_report.py for the histogram, the dedup'd
+ *   block order, and the call-edge table. See references/
+ *   native-dbi-and-deobfuscation.md for the workflow around this trace.
+ *
+ * TESTED
+ * ------
+ *   frida 16.7.19 host + frida-server 16.7.19 on Android 11 arm64. See
+ *   docs/tool-verification/EXTENSION-native-dbi.md for the observed runs.
+ */
+
+'use strict';
+
+/* ===================================================================
+ * 1. ADAPT THESE LINES (runtime override also possible -- see the tail)
+ * =================================================================== */
+var CONFIG = {
+    // The only module whose blocks are reported.
+    targetModule: 'libc.so',
+
+    // What starts/stops the trace. Examples:
+    //   { kind: 'main' }
+    //   { kind: 'export', module: 'libnative-lib.so', export: 'Java_com_example_App_check' }
+    //   { kind: 'offset', module: 'libapp.so', offset: 0x9f6c0 }
+    //   { kind: 'java', cls: 'com.example.app.NativeBridge', method: 'sign' }
+    trigger: { kind: 'main' },
+
+    followMs: 4000,        // unfollow after this long, no matter what
+    maxBlocks: 100000,     // stop recording past this many reported events
+    autoStart: true,       // false = arm triggers but wait for rpc start()
+
+    events: {
+        compile: true,     // first translation of each block (skeleton)
+        block: true,       // every executed block (weights)
+        call: true,        // call edges
+        exec: false,       // per-instruction: huge, opt-in only
+        ret: false
+    }
+};
+
+/* ===================================================================
+ * 2. plumbing (no target knowledge below this line)
+ * =================================================================== */
+var state = {
+    started: false,        // trigger installed / main follow armed
+    following: false,
+    followTid: null,
+    target: null,          // Module object of CONFIG.targetModule
+    modByName: {},         // addr-cache for cross-module name lookup
+    seq: 0, nBB: 0, nBLK: 0, nCALL: 0,
+    truncated: false,
+    timer: null,
+    pending: [],           // batched lines waiting for one send()
+    pendingSince: 0
+};
+
+function ts() { return new Date().toISOString(); }
+
+function emit(tag, msg) { send({ t: ts(), tag: tag, msg: msg }); }
+
+function flush(force) {
+    if (!state.pending.length) return;
+    var now = Date.now();
+    if (!force && now - state.pendingSince < 120 && state.pending.length < 256) return;
+    send({ t: ts(), tag: 'TRACE', msg: state.pending.join('\n') });
+    state.pending = [];
+    state.pendingSince = now;
+}
+
+function line(text) {
+    state.pending.push(text);
+    flush(false);
+}
+
+/* Stalker.parse() with stringify:false yields raw addresses that may arrive
+ * as NativePointer, number, or UInt64 depending on the frida version. ptr()
+ * normalizes all of them; a null address stays null. */
+function asPtr(v) {
+    if (v === null || v === undefined) return null;
+    if (v && typeof v.equals === 'function') return v;      // already a pointer
+    try { return ptr(v); } catch (e) { return null; }
+}
+
+function moduleOf(addr) {
+    // target module first: the hot path never hits Process.findModuleByAddress
+    if (state.target && addr.compare(state.target.base) >= 0 &&
+        addr.compare(state.target.base.add(state.target.size)) < 0)
+        return state.target;
+    // one shared cache for everything else (call edges leaving the module)
+    var hit = Process.findModuleByAddress(addr);
+    if (hit && !state.modByName[hit.name]) {
+        state.modByName[hit.name] = hit;
+        line('MOD ' + hit.name + ' base=' + hit.base + ' size=' + hit.size +
+             ' path=' + hit.path);
+    }
+    return hit || null;
+}
+
+/* <module>+0x<offset> when the module is known, raw hex otherwise. */
+function fmtAddr(addr) {
+    var m = moduleOf(addr);
+    if (m) return m.name + '+0x' + addr.sub(m.base).toString(16);
+    return addr.toString();
+}
+
+/* ===================================================================
+ * 3. the follow engine
+ * =================================================================== */
+function onStalkEvents(events) {
+    var entries;
+    try {
+        entries = Stalker.parse(events, { stringify: false, annotate: false });
+    } catch (e) {
+        emit('FATAL', 'Stalker.parse failed: ' + e);
+        endFollow('parse-error');
+        return;
+    }
+    for (var i = 0; i < entries.length; i++) {
+        var ev = entries[i];
+        var kind = ev[0];
+        if (kind === 'compile') {
+            var a = asPtr(ev[1]);
+            if (!a || !moduleOf(a)) continue;
+            state.seq++; state.nBB++;
+            line('BB ' + state.seq + ' ' + fmtAddr(a));
+        } else if (kind === 'block') {
+            var b = asPtr(ev[1]);
+            if (!b || !moduleOf(b)) continue;
+            state.seq++; state.nBLK++;
+            var sz = (ev.length > 2 && typeof ev[2] === 'number') ? ev[2] : null;
+            line('BLK ' + state.seq + ' ' + fmtAddr(b) +
+                 (sz !== null ? ' size=' + sz : ''));
+        } else if (kind === 'call') {
+            var from = asPtr(ev[1]), to = asPtr(ev[2]);
+            var depth = (ev.length > 3 && typeof ev[3] === 'number') ? ev[3] : '?';
+            if (!from || !to) continue;
+            var fromIn = !!moduleOf(from), toIn = !!moduleOf(to);
+            if (!fromIn && !toIn) continue;              // drop unrelated edges
+            state.seq++; state.nCALL++;
+            line('CALL ' + depth + ' ' + fmtAddr(from) + ' -> ' + fmtAddr(to));
+        }
+        // 'exec'/'ret' are opt-in; if enabled they are reported as X/RET lines
+        else if (kind === 'exec' && CONFIG.events.exec) {
+            var x = asPtr(ev[1]);
+            if (!x || !moduleOf(x)) continue;
+            state.seq++;
+            line('X ' + state.seq + ' ' + fmtAddr(x));
+        }
+        if (state.seq >= CONFIG.maxBlocks) { endFollow('maxBlocks'); return; }
+    }
+    flush(true);
+}
+
+function beginFollow(tid, why) {
+    if (state.following) return;
+    if (!state.target) {
+        emit('FATAL', 'target module not loaded, refusing to follow (see READY)');
+        return;
+    }
+    state.following = true;
+    state.followTid = tid;
+    emit('TRIG', 'following tid=' + tid + ' (' + why + ') module=' +
+         state.target.name + ' base=' + state.target.base);
+    line('MOD ' + state.target.name + ' base=' + state.target.base +
+         ' size=' + state.target.size + ' path=' + state.target.path);
+
+    Stalker.follow(tid, {
+        events: {
+            call: CONFIG.events.call,
+            ret: CONFIG.events.ret,
+            exec: CONFIG.events.exec,
+            block: CONFIG.events.block,
+            compile: CONFIG.events.compile
+        },
+        onReceive: onStalkEvents
+    });
+
+    if (CONFIG.followMs > 0) {
+        state.timer = setTimeout(function () { endFollow('timeout'); },
+                                 CONFIG.followMs);
+    }
+}
+
+function endFollow(reason) {
+    if (!state.following) return;
+    state.following = false;
+    if (state.timer !== null) { clearTimeout(state.timer); state.timer = null; }
+    try { Stalker.flush(); } catch (e) { /* already gone */ }
+    try { Stalker.unfollow(state.followTid); } catch (e) { /* already gone */ }
+    flush(true);
+    emit('DONE', 'reason=' + reason + ' blocks=' + state.nBB +
+         ' blk=' + state.nBLK + ' calls=' + state.nCALL +
+         ' truncated=' + (state.truncated || reason === 'maxBlocks' ? 1 : 0));
+}
+
+/* ===================================================================
+ * 4. triggers
+ * =================================================================== */
+function installTrigger() {
+    var t = CONFIG.trigger || { kind: 'main' };
+    state.target = Process.findModuleByName(CONFIG.targetModule);
+
+    if (!state.target) {
+        // Hardened apps and Flutter apps load their interesting library after
+        // Application start; wait for the linker instead of failing.
+        emit('TRIG-FAIL', 'module ' + CONFIG.targetModule + ' not loaded yet; ' +
+             'hooking dlopen to wait for it');
+        hookDlopen(CONFIG.targetModule, function (mod) {
+            state.target = mod;
+            armTrigger(t);
+            emit('TRIG', 'module ' + mod.name + ' loaded at ' + mod.base +
+                 '; trigger armed');
+        });
+        return;
+    }
+    armTrigger(t);
+}
+
+function armTrigger(t) {
+    try {
+        if (t.kind === 'export' || t.kind === 'offset') {
+            var mod = Process.findModuleByName(t.module || CONFIG.targetModule);
+            if (!mod) { emit('TRIG-FAIL', 'trigger module missing: ' + t.module); return; }
+            var addr = null;
+            if (t.kind === 'export') {
+                addr = mod.findExport ? mod.findExport(t.export) : null;
+                if (!addr) addr = Module.findExportByName(mod.name, t.export);
+                if (!addr) {
+                    emit('TRIG-FAIL', 'export not found: ' + mod.name + '!' + t.export);
+                    return;
+                }
+            } else {
+                addr = mod.base.add(t.offset || 0);
+            }
+            Interceptor.attach(addr, {
+                onEnter: function () { beginFollow(this.threadId, 'trigger ' + addr); },
+                onLeave: function () { endFollow('trigger-leave'); }
+            });
+            emit('TRIG', 'armed ' + t.kind + ' trigger at ' + addr);
+        } else if (t.kind === 'java') {
+            if (typeof Java === 'undefined') {
+                emit('TRIG-FAIL', 'java trigger requested but no Java bridge; ' +
+                     'align host frida and frida-server to the same 16.x');
+                return;
+            }
+            Java.perform(function () {
+                var Klass;
+                try { Klass = Java.use(t.cls); }
+                catch (e) { emit('TRIG-FAIL', 'class not found: ' + t.cls); return; }
+                var hit = false;
+                var names = t.method instanceof Array ? t.method : [t.method];
+                for (var i = 0; i < names.length && !hit; i++) {
+                    var ov = Klass[names[i]];
+                    if (!ov || !ov.overloads) continue;
+                    ov.overloads.forEach(function (o) {
+                        // implementations run on the calling thread, so the
+                        // current thread id IS the java->native boundary thread
+                        o.implementation = function () {
+                            beginFollow(Process.getCurrentThreadId(),
+                                        'java ' + t.cls + '.' + names[i]);
+                            try {
+                                return o.apply(this, arguments);
+                            } finally { endFollow('trigger-leave'); }
+                        };
+                    });
+                    hit = true;
+                }
+                if (hit) emit('TRIG', 'armed java trigger ' + t.cls + '#' + names.join(','));
+                else emit('TRIG-FAIL', 'method not found on ' + t.cls + ': ' + names.join(','));
+            });
+        } else if (t.kind === 'main') {
+            if (CONFIG.autoStart === false) {
+                emit('TRIG', 'main trigger armed (autoStart=false); call start()');
+                return;
+            }
+            var tid = null;
+            try { tid = Process.getMainThreadId(); } catch (e) { /* older gum */ }
+            if (!tid || tid <= 0) {
+                // getMainThreadId may not exist on older gum; on Android the
+                // first thread frida lists is the process's main thread.
+                var threads = Process.enumerateThreads();
+                tid = threads.length ? threads[0].id : Process.getCurrentThreadId();
+            }
+            beginFollow(tid, 'main-thread follow (pid=' + Process.id + ')');
+        } else {
+            emit('TRIG-FAIL', 'unknown trigger kind: ' + t.kind);
+        }
+    } catch (e) {
+        emit('TRIG-FAIL', String(e));
+    }
+}
+
+/* Wait for a library the dynamic linker has not mapped yet. */
+function hookDlopen(basename, onLoaded) {
+    var seen = false;
+    ['dlopen', 'android_dlopen_ext'].forEach(function (name) {
+        var a = Module.findExportByName(null, name);
+        if (!a) return;
+        Interceptor.attach(a, {
+            onEnter: function (args) {
+                var p = args[0];
+                this.path = (p && !p.isNull()) ? p.readCString() : null;
+            },
+            onLeave: function (res) {
+                if (seen || !this.path) return;
+                if (this.path.indexOf(basename) === -1) return;
+                var mod = Process.findModuleByName(basename);
+                if (mod) { seen = true; onLoaded(mod); }
+            }
+        });
+    });
+}
+
+/* ===================================================================
+ * 5. runtime control: rpc.exports + post('cfg')
+ * =================================================================== */
+rpc.exports = {
+    config: function (patch) {
+        if (!patch || typeof patch !== 'object')
+            return { ok: false, error: 'config needs an object' };
+        for (var k in patch) {
+            if (k === 'trigger' && patch.trigger && typeof patch.trigger === 'object') {
+                CONFIG.trigger = patch.trigger;
+            } else if (k === 'events' && patch.events) {
+                for (var e in patch.events) CONFIG.events[e] = !!patch.events[e];
+            } else {
+                CONFIG[k] = patch[k];
+            }
+        }
+        // a re-config that changes WHAT we trace must not race the old follow
+        if (state.following &&
+            (patch.trigger !== undefined || patch.targetModule !== undefined ||
+             patch.autoStart !== undefined)) {
+            endFollow('reconfig');
+        }
+        installTrigger();
+        return { ok: true, config: CONFIG };
+    },
+    start: function (argTid) {
+        var tid = argTid || null;
+        if (!tid || tid <= 0) {
+            // never follow the rpc thread: it sleeps while waiting for us and
+            // produces an empty trace. Prefer the process's main thread.
+            try { tid = Process.getMainThreadId(); } catch (e) { /* older gum */ }
+            if (!tid || tid <= 0) {
+                var threads = Process.enumerateThreads();
+                tid = threads.length ? threads[0].id : Process.getCurrentThreadId();
+            }
+        }
+        beginFollow(tid, 'start-rpc');
+        return { following: state.following, followingTid: tid };
+    },
+    stop: function () { endFollow('stop-rpc'); return status(); },
+    status: function () { return status(); }
+};
+
+function status() {
+    return {
+        following: state.following,
+        targetLoaded: !!state.target,
+        target: state.target ? state.target.name : CONFIG.targetModule,
+        seq: state.seq, blocks: state.nBB, blk: state.nBLK, calls: state.nCALL
+    };
+}
+
+try {
+    recv('cfg', function onCfg(message, payload) {
+        rpc.exports.config(payload);
+        recv('cfg', onCfg);              // stay armed for further updates
+    });
+} catch (e) { /* recv unavailable in this runtime; constants mode still works */ }
+
+/* ===================================================================
+ * 6. go
+ * =================================================================== */
+state.started = true;
+// safety flush so lines emitted before/after a follow still reach the host
+setInterval(function () { flush(true); }, 500);
+emit('READY', 'stalker_trace loaded; target=' + CONFIG.targetModule +
+     ' trigger=' + JSON.stringify(CONFIG.trigger) + ' followMs=' + CONFIG.followMs +
+     ' maxBlocks=' + CONFIG.maxBlocks +
+     ' moduleLoaded=' + !!Process.findModuleByName(CONFIG.targetModule));
+installTrigger();