AXP-Resurection/docs/007-kernelsu-runbook.md

007 — KernelSU-Next on sunfish (LAB runbook)

LAB only: serial 11231JEC207477 — never GOLDEN 11071JEC203839
Host: rom-dev01 — artifacts /srv/rom/artifacts/007-kernelsu/, logs /srv/rom/logs/007-build/
Managed profile: Island (current LAB/GOLDEN vehicle; historical “Insular” docs are workflow reference only)

Latest LAB results

2026-09-16: SusFS DEBUG bring-up PASS (matched vendor); banks still FAIL (Talsec -69 / root lock). Full write-up: docs/007-lab-results-20260916.md.

Hard-gates

Gate	Rule
Yuh (com.yuh)	PASS usable session in Island on the tested stack
Swissquote (com.swissquote.android)	PASS usable session in Island on the same stack
Root	Banks never receive root; hide/umount verified (not toggle-only)
Magisk	Not production

If either bank fails after SusFS/attestation experiments → cancel root (Phase 9): keep incomplete / withdraw KSU; pivot to native 008/009 + optional stock phone. Do not ship “root without both banks”.

Sequencing (constitution 0.2.1)

• 006 rootless PASS gate is deferred.
• Before first rooted flash: T039 rootless snapshot of this LAB ROM (pre-root/). FAIL allowed; record facts.
• Then KSU → verified hide → SusFS → attestation → both-bank PASS.
• Pins: always refresh to newest compatible ReSukiSU/manager (non-shallow); record tag + KSU_VERSION before mka. Never rebuild from a stale host copy.

002 KeyMint / Yuh evidence (index)

Source	What	Path / doc
GOLDEN AXP+Magisk	Yuh FAIL — HA / “certificate invalid”; KeyMint HARDWARE_TYPE_UNAVAILABLE	docs/002-golden-inventory.md §Compatibility; host refs under /srv/rom/references/axp/golden/… when present
LAB iodé A16 (no Magisk, BL locked)	Same KeyMint/RKP class on Yuh open	docs/002-lab-iodes-baseline.md; host …/lab/2026-09-13-iodes-baseline/yuh-…
Contracts	Hide + both-bank gate	specs/007-kernelsu-sunfish/contracts/

Manager UI is not in the ROM zip

Kernel root (KSU-Next / ReSukiSU) does not ship a visible Settings tile. After flash: install the matching spoofed manager APK (version ≤ kernel KSU_VERSION), then modules (TEESimulator-RS / Zygisk / PIF, etc.). Same on torukk’s MicroG zip — ResukiSU/KSU is kernel-only until the manager is installed (see XDA #41; our pin: .local-artifacts/007-kernelsu/ReSukiSU_*spoofed_*.apk).

Host policy

All heavy work on rom-dev01 only (kernel clone, integrate, mka, image staging). Laptop = thin client (adb/fastboot, Spec Kit, docs). Do not run kernel builds or multi‑GB clones on the laptop.

Long jobs must be detached on the host — never leave mka/ninja on a laptop SSH pipe (Wi‑Fi drops kill the build). Prefer tmux via /srv/rom/artifacts/bin/rom-detach (falls back to screen / nohup):

/srv/rom/artifacts/bin/rom-detach 007-boot -- bash -lc \
  'cd /srv/rom/src/lineage && source build/envsetup.sh && lunch lineage_sunfish-bp4a-userdebug && mka bootimage -j$(nproc)'
cat /srv/rom/artifacts/detach-007-boot.status
tmux ls   # attach: tmux attach -t 007-boot

Agents: start detached, then only poll detach-*.status / logs with short SSH.

Path on host	Role
/srv/rom/src/lineage/kernel/google/msm-4.14	Our LOS kernel (integrate here)
/srv/rom/src/lineage/kernel/google/msm-4.14/KernelSU-Next	setup.sh checkout @ a54e4fa…
/srv/rom/references/kernelsu-next/	KernelSU-Next legacy mirror (setup source)
/srv/rom/references/abu-msm-4.14-ksu/	abu-adm ksu-susfs-23.0 reference only
/srv/rom/artifacts/007-kernelsu/abu-reference/	Owner-supplied abu boot-abu.img + dtbo-abu.img + SHA256
/srv/rom/artifacts/007-kernelsu/	Our outs / evidence
/srv/rom/logs/007-build/	Build logs

Integration status (2026-09-16)

• Production root fork for LAB: ReSukiSU (symlink drivers/kernelsu → /srv/rom/references/resukisu/kernel, full non-shallow clone). KernelSU-Next remains historical learning only.
• Manual hooks (CONFIG_KSU_MANUAL_HOOK): fs/open.c, fs/exec.c, fs/stat.c, fs/read_write.c, drivers/input/input.c, kernel/sys.c (setresuid), kernel/reboot.c
• sunfish_defconfig: CONFIG_KSU=y, CONFIG_KSU_MANUAL_HOOK=y, all three AUTO_* hooks on for 4.14, SusFS options as addon (not XOR). See docs/007-abu-vs-ours-susfs.md.
• Our boots (use these — not Downloads):

Role	Artifact
Penúltimo (ReSukiSU, no SusFS)	boot-resukisu-our-20260915T183729Z.img / boot-resukisu-our-latest.img
Último (ReSukiSU + SusFS)	boot-resukisu-susfs-20260916T004038Z.img / …-susfs-latest.img (sha 455a77a6…)

• SusFS: built (API bridge 4.14 ↔ ReSukiSU ioctl). Not claimed on LAB — trial only; US2 hide not finished before build. See docs/session-20260916-handoff.md.

Community / abu — reference archive only

Same problem space (sunfish + microG + hide + banks). Not our flash path. Do not install abu/torukk ROMs or ~/Downloads/boot-sunfish-resukisu*.img as “our” kernel.

Topic	Useful reference	Our action
Root fork	ReSukiSU for hard banks (XDA)	We already build our ReSukiSU boot
Attestation	TEESimulator-RS	Prefer over TrickyStore when modules resume
Modules	Zygisk Next + PIF inject	Documented exception if bank gate needs it
SusFS / kernel	abu ksu-susfs trees, abu-reference/ imgs	Diff / port ideas only
Their full ROM	torukk 22.2 MicroG / abu A15	Ignore for day-to-day — restore always = our 23.2 bacon

Host refs: /srv/rom/references/abu-msm-4.14-ksu/, /srv/rom/artifacts/007-kernelsu/abu-reference/ (boot-abu / dtbo-abu).

# LAB — our penúltimo (preferred after ROM sideload)
# Always flash BOTH slots after a failed SusFS/bootloop trial — bootloader may
# mark the other slot unbootable and leave current-slot on the bad one.
fastboot flash boot_a .local-artifacts/007-kernelsu/boot-resukisu-our-20260915T183729Z.img
fastboot flash boot_b .local-artifacts/007-kernelsu/boot-resukisu-our-20260915T183729Z.img
fastboot --set-active=a   # or the slot that last ran our 23.2 bacon successfully
fastboot reboot
# host: /srv/rom/artifacts/007-kernelsu/boot-resukisu-our-20260915T183729Z.img

# Emergency (no KSU): bacon stock boot
# fastboot flash boot_a|boot_b .local-artifacts/007-kernelsu/boot-005-known-good.img

Slot lesson (2026-09-16): SusFS bootloop left current-slot:b and slot-unbootable:a:yes. Flashing only boot (→ active slot) could not revive LAB; boot-005 on both slots + --set-active=a recovered. Before any kernel trial: fastboot getvar current-slot / slot-unbootable:*. After failure: flash rollback to boot_a and boot_b, then set the known-good slot.

Pin table (2026-09-16)

Component	Revision	Status	Notes
ReSukiSU	host /srv/rom/references/resukisu (non-shallow; match manager)	active	record tag + KSU_VERSION before each mka
KernelSU-Next	a54e4fa… (legacy)	archived	learning only
LOS sunfish kernel	28f9290ae067… + dirty SusFS/hooks	tree	msm-4.14
SusFS	bridged in-tree (trial)	rebuild	T004038Z hung (no MANUAL_HOOK); T091211Z logo-reboot (MANUAL+SUSFS but AUTO_ hooks off*); next: AUTO_*=y + SusFS
Attestation stack	—	pending	TEESimulator-RS first candidate

Kernel inventory (T005)

Item	Value
Source	/srv/rom/src/lineage/kernel/google/msm-4.14
Device makefile	device/google/sunfish/BoardConfigLineage.mk → TARGET_KERNEL_SOURCE := kernel/google/msm-4.14
Defconfig	arch/arm64/configs/sunfish_defconfig
Boot image name	Image.lz4

KernelSU-Next choice (T006–T007) — amended by community 2026-08

Earlier decision: KernelSU-Next legacy + manual hooks for first in-tree POC.

Amended (owner + torukk XDA 2026-08-22): For hard-bank detection (Revolut-class; our gate is Yuh/Swissquote), community evidence favors ReSukiSU + TEESimulator-RS (+ Zygisk Next + PIF inject) over Next+TrickyStore. Keep Next work as learning / optional A/B; do not treat Next-only as the banking solution if ResukiSU PoC is available.

LAB PoC order (current, 2026-09-16):

1. Foreign ResukiSU / abu boots — reference only; wrong for our A16 tree
2. Done: our ReSukiSU → boot-resukisu-our-20260915T183729Z.img (penúltimo)
3. Done (build): SusFS trial → boot-resukisu-susfs-20260916T004038Z.img — flash/claim after US2; prefer penúltimo on LAB until then
4. Manager + TEESimulator-RS ± Zygisk/PIF → bank gate

Integration notes (T008)

Work on host tree; flash only our boot-resukisu-our-* / boot-resukisu-susfs-* artifacts (never ~/Downloads/boot-sunfish-resukisu*):

1. Wire ReSukiSU as drivers/kernelsu → /srv/rom/references/resukisu/kernel (full git clone lives outside the msm tree). Do not keep a KernelSU/ directory inside msm-4.14: this tree’s scripts/setlocalversion walks nested .git dirs and appends KernelSU-gHASH into uname -r (easy bank detection).
2. Always use a non-shallow ReSukiSU clone so KSU_VERSION = 30000 + rev-list + 700 matches the manager (≥35080). Shallow depth=1 produced bogus 30701.
3. Enable CONFIG_KSU=y + CONFIG_KSU_MANUAL_HOOK (+ AUTO_* on 4.14).
4. Patch syscall hook sites per https://resukisu.org/guide/manual-integrate.html.
5. Build mka bootimage; verify uname -r has no KernelSU string before bank testing.
6. SusFS: built as trial; do not claim until US1–US2 green and T019 boots clean.

References: ReSukiSU manual integrate; abu/XDA only as SusFS/module oracle (docs/reference-sources.md §8; docs/session-20260916-handoff.md).

Rootless snapshot (T039)

See /srv/rom/artifacts/007-kernelsu/pre-root/OUTCOMES.txt and preflight.txt.

Recorded on 23.2-20260915-UNOFFICIAL-sunfish: microG + Phonesky + spoof ON; Island user 10 present; no su. Yuh/Swissquote not installed at snapshot time (N/A outcomes). Reinstall via Aurora→Island before US5 banking gate.