fix: api/cli/registry correctness, CI hardening & docs alignment sweep

[Xiddoc]

Summary

Third sweep batch — 25 fixes across the api/cli/registry/settings surface plus CI workflows, scripts, and docs. Implemented by 9 file-disjoint parallel agents, each gate-verified, integrated cleanly (no cross-patch conflicts).

Fixes by area

api / lifecycle

• Instance.up() self-heal re-stages the ports override without the cross-instance collision precheck apply() enforces; restart() skips the self-heal entirely #166 up() self-heal runs the cross-instance port-collision precheck; restart() self-heals a missing override — neither boots with a colliding/zero-port mapping
• apply() reconciles the registry backend kind only after network staging, so a transient frida/module fetch failure leaves a binder:vm config dispatching the redroid backend #182 apply() flips the registry backend kind before network staging, so a transient fetch failure can't strand a binder: vm config on the redroid backend
• adb-backend GMS denylist check hardcodes enrolled=True, so an adopted device that legitimately doesn't denylist GMS reports fail instead of skip #201 adb doctor reports skip (not a phantom fail) for the GMS denylist on adopted devices
• up()/restart() self-heal only the compose override, not .env; a hand-deleted .env breaks compose up and makes ps_status misreport a running instance #219 up()/restart() re-stage a hand-deleted .env, not just the override

cli / error contract

• beetroot apply emits a raw traceback on Frida download/resolve failure: FridaFetchError is caught nowhere (apply catches only ValueError; main() omits it) #167 map FridaFetchError and create --from-data: a non-FileNotFoundError OSError from rmtree/copytree escapes cli.main() uncaught, breaking the error:/exit-1 contract #180 --from-data OSError to the friendly error/exit-1 contract
• build --from-source and --android-version silently no-op without --vm-kernel, while --check is guarded (inconsistent) #198 guard --from-source/--android-version without --vm-kernel
• create --from-data copies the data dir before instance-name grammar validation, orphaning a populated <name>/data/ tree when the name is rejected #199 validate the instance name before the --from-data copy
• adopt --help and examples/adb-device.yaml reference a non-existent beetroot install_frida verb, leaving adb-adopted devices no CLI path to install frida-server #205 new install-frida verb the adopt hint already advertised (Feature)
• reset (vm/adb) and destroy (adb) show the destructive data-wipe confirmation before the backend-capability gate, authorizing a wipe the backend then refuses #206 gate backend capability before the destructive-wipe confirm
• beetroot shell propagates raw negative subprocess returncode to typer.Exit, yielding non-conventional exit codes (254/241) on signal death #217 normalize a signal-killed shell to POSIX 128+N exit codes

registry / ports / settings

• _write() does not fsync the tmp file or parent dir before/after os.replace, so a power loss racing a registry write can silently reset instances.json to empty #203 fsync the registry write (temp + parent dir) so a crash can't empty instances.json
• all_resolved_host_ports() fallback discards a poisoned instance's pinned host ports and substitutes phantom stride defaults, producing a wrong collision precheck #216 keep a poisoned instance's pinned host ports in the collision precheck
• Privileged-port advisory re-emits once per privileged-port instance on every cross-instance port scan (resolve_ports side-effect leaks through read-only scan) #224 suppress the privileged-port advisory on the read-only cross-instance scan
• Timeout settings (http_timeout, vm_adb_connect_timeout) accept 0/negative with no validation; BEETROOT_HTTP_TIMEOUT=0 turns downloads into instant failures #196 reject non-positive timeout settings at startup

CI / scripts / docs

• rootfs-release.yml installs uv via unpinned pipx install uv, the only workflow bypassing the SHA-pinned setup-uv path #209 SHA-pin uv in rootfs-release.yml (Security); e2e pull_request trigger omits opened, so a PR opened already carrying the e2e label never starts the e2e tiers #210 add opened to the e2e trigger; Several CI install steps run apt-get install with no preceding apt-get update, so a stale runner index can 404 and fail the job #211 apt-get update before installs
• Changelog linter validates only the first beetroot invocation per line, missing the second verb in &&/;/| command chains #212 changelog linter checks every verb in a chained example; Benchmark regression alert compares absolute wall-time, not the host-normalized ratio the module docstring says to trend #188 benchmark alert uses the host-normalized ratio; lsposed-hook-e2e check grep requires a non-empty middle token, contradicting the empty-<…> form implied by the contract #236 loosen the lsposed-hook grep
• Migration docs are stale at api_version 6 (live is 8): missing 6->7 gapps and 7->8 ports walkthroughs and instruct 'set api_version: 6' #213 refresh migration docs to api_version 8; architecture.md lists removed ADB_PORT/FRIDA_PORT tokens as compose-template env-file substitutions (ports moved to compose.override.yaml in v8) #214 fix architecture.md compose tokens; entrypoint.sh / flash-modules.sh / CLAUDE.md comments wrongly claim the trailing wait keeps the container alive (init is PID 1, not the entrypoint) #240 correct the wait comments; IMAGE_SIZE_MB knob/field is spelled MB but mke2fs treats the M suffix as MiB #233 document IMAGE_SIZE_MB as MiB

Testing

Full local gate green: ruff, ruff format --check, mypy --strict (src+tests), pytest -p no:randomly at 100% line+branch coverage (1887 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