AXP-Resurection/docs/009-magisk-preinstall-runbook.md

009 Magisk preinstall runbook (AXP / GOLDEN class)

Device roles: GOLDEN 11071JEC203839 = adb read-only oracle.
LAB 11231JEC207477 = flash/test only. Never flash or Magisk-change GOLDEN.

Evidence: /srv/rom/artifacts/009-axp-los23-port/
Contract: specs/009-axp-los23-port/contracts/magisk-preinstall.md

Ship policy (owner 2026-09-17)

• Clone AXP first (mandatory): Magisk packaging = EXTENDROM EXTENDROM_PREROOT_BOOT method. Copy that flow; do not invent alternate Magisk install paths. Only diverge if LOS23 / Magisk version breaks the AXP/EXTENDROM path, and document why.
• Magisk clean: ship Magisk preroot only — do not bake GOLDEN modules (playintegrityfix, teesim, hosts, flag-secure-disabler, zygisk_vector, …). Owner installs modules later if wanted.
• Manager UI: stock Magisk upstream (not Magia branding).
• Dormant until activation (AXP Pro): after flash, Magisk is pre-rooted in boot but root must stay inactive until the user opens Magisk and completes Additional Setup. Skipping setup ⇒ no su / no Magisk binaries in the OS (undetectable). Do not bake Magisk as PRODUCT_PACKAGE; do not sideload the full Magisk APK before measuring virgin LAB state.
• Build host: LAB/GOLDEN USB not required to compile. Phones only for measurement (GOLDEN adb) or flash validation (LAB).

GOLDEN measurement (2026-09-17, live adb)

Item	Value
Build	22.2-2026.003-sunfish-pro / BP1A.250505.005
Magisk binary	29.0:MAGISK:R (29000) at /system_ext/bin/magisk
Also present	/system_ext/bin/magiskpolicy
Runtime	/data/adb/magisk/ full toolkit + stub.apk; magisk.db
Settings (sqlite via magisk --sqlite)	zygisk=1, denylist=1, mnt_ns=2, bootloop=0
Manager UI	Magisk app hidden/renamed (random pkg oq.aq.cjn, versionName=1.0) — AXP brands this UI as Magia in docs/screenshots; package name is not stable after “Hide the Magisk app”
Modules seen	flag-secure-disabler, hosts, playintegrityfix, teesim, zygisk_vector
Secure toggles	allow_signature_fake=1, extendrom_call_recording=1

Important: GOLDEN is already fully activated. The virgin “preinstalled but not fully activated” UX is the first-boot / additional setup Magisk flow after an AXP-style preroot image (see AXP setup guide + EXTENDROM FAQ: “Requires Additional Setup”). Measure that class from AXP docs + EXTENDROM PREINITDEVICE=userdata behaviour — do not wipe GOLDEN to re-see it.

How AXP / EXTENDROM builds Magisk into the ROM

Attribute: sfX-android android_vendor_extendrom + Magisk APK.

1. EXTENDROM_PREROOT_BOOT=true — Magisk is not a normal PRODUCT_PACKAGE; it patches boot / init_boot at image build time.
2. Magisk APK (v22+) is unzipped under out/.magisk/; boot_patch.sh runs via vendor/extendrom/config/magisk/patch.sh.
3. Releasetools inject: patch under config/magisk/{lineage|axp}/A{version}/0001-build_make_tools_releasetools_common.py hooks common.py _BuildBootableImage / prebuilt boot.
4. Patcher env of note: KEEPVERITY=true, KEEPFORCEENCRYPT=true, PREINITDEVICE=userdata, BOOTMODE=false.
5. Post-flash virgin: stub may appear; /system_ext/bin/magisk and su appear only after user activation (AXP FAQ “Revert Magisk activation”). Measure virgin before opening Magisk. GOLDEN already activated is not virgin.

Host reference tree: /srv/rom/references/extendrom/ on rom-dev01.

Enable Magisk on next bacon (009)

export ANDROID_BUILD_TOP=/srv/rom/src/lineage
export OUT_DIR=/srv/rom/src/lineage/out   # or /srv/rom/out-009 for parallel
export SUNFISH_A16_MAGISK_PREROOT=1
# Copy staged runtime into OUT (or re-run prepare):
#   rsync -a /srv/rom/prebuilts/magisk/runtime/ "$OUT_DIR/.magisk/"
# or: MAGISK_STAGE_DIR=$OUT_DIR/.magisk vendor/sunfish-a16/magisk/prepare_magisk.sh

Hook is already in build/make/tools/releasetools/common.py but no-ops unless SUNFISH_A16_MAGISK_PREROOT=1 (008 in-flight stays safe).

1. Clean-flash LAB with Magisk-preroot 009 images (wipe /data if LAB had Magisk activated before).
2. Virgin check (before opening Magisk): adb shell 'which su; which magisk; ps -A | grep magiskd' — expect no su, no Magisk binaries (AXP dormant). Record under …/magisk/pre-activation.md.
3. Open Magisk stub → download/install full Magisk if prompted → complete Additional setup → reboot (AXP setup guide).
4. Confirm magisk -v matches pin (target: newest workable stable; host aims at v30.7 unless regression).
5. Enable Zygisk + DenyList as needed.
6. For DenyList smoke (MVP): hide a non-bank test package before first open.
7. Banking DenyList workflow = deferred (US3 / Gate E).

Optional KernelSU recycle (FR-016)

Paths under /srv/rom/artifacts/007-*/ — debug/reference only. Not ship. Never gate Magisk acceptance on KSU.

Hard rule for Magisk LAB: sunfish_defconfig must keep # CONFIG_KSU is not set (and SusFS off). Magisk + in-kernel ReSukiSU/KSU on the same boot causes app failed to attach / start timeout and hung su.

Full AXP-clone bacon (detached):
/srv/rom/artifacts/009-axp-los23-port/scripts/009-bacon-axp.sh
session 009-bacon-axp — Magisk preroot + noksu + Phonesky exact-alarm + WMS FLAG_SECURE (no ro.debuggable gate). After zip sideload, flash artifact boot.img (TF IMAGES) to both slots.

Staged known-good images (FR-013)

Keep prior LAB flashables + SHA-256 under /srv/rom/artifacts/009-axp-los23-port/<build-id>/ before each risky Magisk or hardening stage.