fix: config validation, download hardening, builder robustness & isolated bug sweep

[Xiddoc]

Summary

Second batch of the automated codebase sweep — 27 fixes across config/ports validation, the download path, the redroid/vm builder, and several isolated correctness bugs. Implemented by 9 file-disjoint parallel agents, each gate-verified, then integrated with two hand-completed fixes (#200, #223) that crossed agent file-ownership boundaries.

Fixes by area

Config & ports validation

• Well-known port mapping with a non-canonical guest port validates clean but publishes host->dead guest port; frida required but frida_control not #195 reject a well-known ports: mapping with a non-canonical guest port; require frida_control alongside frida
• v8 ports-migration / legacy-ports-mapping note lacks the per-path dedup guard, re-firing on every load_yaml (regresses the CR #2 noise fix) #202 dedup the legacy ports-migration note per resolved path (no re-print on fleet scans)
• memswap_limit rejects Docker's documented -1 (unlimited swap), with no way to express it #215 accept Docker's documented memswap_limit: -1 (unlimited swap)
• _warn_on_inert_vm_config omits modules:, yet vm _stage() still wipes+restages modules the plain-redroid guest never flashes #200 flag a non-empty modules: list as inert under binder: vm
• frida.sha256 / module.sha256 accept any string (no 64-char-hex check), so a fat-fingered digest fails late with a misleading hostile-mirror message #194 validate frida.sha256 as 64-char hex at load time (Module.sha256 half tracked as follow-up)
• Pinned gapps_vendor silently overrides the minimal/full intent (intent collapses to one image/flag per vendor) with no warning #220 warn when a pinned gapps_vendor overrides the minimal/full intent
• Dead constant _MIGRATION_REQUIRED_VERSIONS is empty but its comment describes a live migration actually enforced by a validator #242 remove the dead _MIGRATION_REQUIRED_VERSIONS constant
• Magisk exit status masked by the awk pipe in the zygisk read/verify, so a post-liveness daemon flap churns zygote or aborts boot with a misleading message #239 magisk-config.sh: observe the magisk --sqlite exit status under set -eu

Download hardening

• Concurrent downloads of the same cached artifact race on a fixed .tmp path (frida/module/kernel), poisoning the user-global cache with a corrupt file #185 stage into a process-unique temp file before the atomic rename (concurrent-fetch cache poisoning)
• frida-server / module downloads buffer the full payload (and full decompressed binary) in RAM instead of stream-decompressing like rootfs_download #227 stream-decompress frida/modules instead of buffering full payloads in RAM
• frida_download.download() decompresses the entire .xz with no max-output cap (unbounded-decompression / OOM hardening gap) #228 bound frida .xz decompression output (OOM / zip-bomb hardening) — Security
• Module URL with a query string or fragment stages a filename the redroid *.zip flash glob never matches, so the module is silently never flashed #168 strip query/fragment from module-URL basenames so the *.zip flash glob matches

Builder & rootfs robustness

• Guest-kernel source tarball fetched from cdn.kernel.org with no sha256/GPG verification before compile+publish as a trusted prebuilt bzImage #184 pinned-sha256 verify the kernel source tarball before compiling — Security
• fetch_prebuilt writes the .android-version marker non-atomically after the image rename, so a crash leaves a valid rootfs with no marker (skew check skipped) #234 / rootfs .android-version marker records --android-version, not the actually-baked REDROID_IMAGE version, defeating the binder:vm skew warning #187 write the rootfs .android-version marker before the image rename; record the actually-baked image version
• REDROID_TAR existence is never validated; a missing/typo'd tarball passes --vm-kernel --check preflight then aborts mid-bake at docker load #186 validate REDROID_TAR exists in preflight
• beetroot build (redroid base image) has no Docker-daemon preflight, giving a generic command-failed error on a daemonless host #193 docker-daemon preflight for beetroot build
• Kernel source-compile sh -c interpolates --build-context-derived paths unquoted, breaking on paths with spaces/metacharacters #208 shell-quote build-context paths in the kernel compile
• Dockerfile relies on BuildKit-only COPY --chmod but beetroot build never forces BuildKit, aborting on a BuildKit-disabled host #229 force BuildKit for the COPY --chmod Dockerfile
• Local rootfs bake spawns a staging dockerd (needs root) but vm_bake_preflight never checks euid, masking a privilege failure as a generic ~60s dockerd timeout #231 euid preflight for the local rootfs bake
• beetroot build uses a single fixed per-user clone dir with rm -rf + clone and no lock, so concurrent builds corrupt each other #232 fcntl.flock the shared clone dir against concurrent builds
• No .dockerignore: beetroot build ships the entire repo root (.venv, .git, instance dirs) as build context for a ~20 KB COPY set #207 add a repo-root .dockerignore

Isolated bugs

• Mid-batch offline-abort module row discards the underlying adb error text and hardcodes a stage-agnostic "mid-install" detail #223 adb mid-batch offline-abort row is stage-neutral and retains the adb error
• beetroot ls/modes rich table clips load-bearing cells at the 80-col non-TTY default; console docstrings wrongly claim piped output stays readable #204 render ls/modes tables losslessly off-TTY
• compose.logs() silently ignores a non-zero docker compose exit, unlike every sibling wrapper #218 compose.logs() raises on a non-zero exit in non-follow mode
• user_config_dir/registry_file/cache_dir return relative paths for relative XDG_*_HOME, violating the absolute-path contract and fragmenting the registry across cwds #225 absolute-path contract for config/registry/cache dirs on a relative $XDG_*_HOME
• Non-atomic write_bytes to the process-global materialised compose.yaml / vm-asset cache can hand docker compose a truncated file under concurrent installs #226 atomic write for the materialised compose / vm-asset cache
• restore() always registers RedroidBackendConfig and never reconciles the archived YAML's binder mode, restoring a binder:vm config to the wrong backend silently #171 / restore into a non-existent descendant path of a registered instance skips the cross-instance overlap guard and registers a nested instance with no --force #172 / snapshot self-inclusion guard only checks top-level entries, so running snapshot from a subdir (cwd inside data/) packs the archive into itself mid-write #173 snapshot/restore: backend reconcile, overlap guard on a non-existent target, self-inclusion guard at any depth

Deferred (tracked, not in this PR)

• Denylist writes the GMS unstable/DroidGuard process as a bogus package_name, so vanilla (non-Shamiko) Magisk denylist never hides root in the Play Integrity process #170 (denylist (package, process) remodel) — genuinely cross-cutting (env format consumed by api.py/vm.py and asserted in multiple tests); needs a focused PR.
• frida.sha256 / module.sha256 accept any string (no 64-char-hex check), so a fat-fingered digest fails late with a misleading hostile-mirror message #194 module.sha256 validation — bogus-digest test fixtures need updating first.

Testing

Full local gate green: ruff check (src+tests), ruff format --check, mypy --strict (src+tests), pytest -p no:randomly with 100% line+branch coverage (1828 passed, 6 docker-daemon skips), shellcheck/shfmt, yamllint, actionlint, zizmor, codespell, deptry, uv lock --check, changelog lint.

🤖 Generated with Claude Code

https://claude.ai/code/session_01P1YsNMpGizhSDDPCBu5cut

---

Generated by Claude Code