Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
135aab2
omamobile-fingerprint 0.1.14: consent, read-only copies, TDP guard, o…
derekross Nov 2, 2026
b477983
install-phone: the wipe warning names fingerprint's secure-storage wr…
derekross Nov 2, 2026
b286997
omamobile-firstboot 0.1.4: the install acknowledgement becomes finger…
derekross Nov 2, 2026
b8d98a6
phone-provision: --fingerprint restores TD only with an explicit --re…
derekross Nov 2, 2026
67c3083
omamobile-shell 0.2.85: onboarding offers "Add a fingerprint" after t…
derekross Nov 2, 2026
6d8501f
FINGERPRINT-PLAN: F19, the reinstall's run, the storage crash, and fi…
derekross Nov 2, 2026
864c444
AGENTS.md: the install acknowledgement is the go for fingerprint's fi…
derekross Nov 2, 2026
74cb007
INSTALL, DEVICES, release notes: fingerprint works out of the box aft…
derekross Nov 2, 2026
f2ff31a
Merge origin/main into fingerprint-out-of-the-box
derekross Nov 2, 2026
dfbebe7
omamobile-fingerprint 0.1.14: on by default, no consent step; the dat…
derekross Nov 2, 2026
59581a7
install-phone, omamobile-firstboot: no fingerprint acknowledgement af…
derekross Nov 2, 2026
4f2ecc2
omamobile-shell 0.2.89: onboarding says when fingerprint is unavailab…
derekross Nov 2, 2026
684f751
FINGERPRINT-PLAN, AGENTS, INSTALL: fingerprint starts by default, the…
derekross Nov 2, 2026
a471e1a
Merge origin/main into fingerprint-out-of-the-box
derekross Nov 2, 2026
b2ba7ee
omamobile-fingerprint 0.1.14: CI-safe namespace test, tighter markers…
derekross Nov 3, 2026
a606548
omamobile-shell 0.2.89: onboarding names a data-check refusal
derekross Nov 3, 2026
da99205
AGENTS, INSTALL, FINGERPRINT plans: mask to turn fingerprint off, gua…
derekross Nov 3, 2026
b3019c7
Merge origin/main into fingerprint-out-of-the-box
derekross Nov 3, 2026
03907ab
Merge origin/main into fingerprint-out-of-the-box
derekross Nov 3, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Omarchy Mobile runs native Omarchy (Arch Linux ARM, Hyprland, Omarchy's packages

## 1. Safety rules (non-negotiable)

- **Ask the human before every reboot, flash, `push`, overlay boot or irreversible write.** That includes RPMB writes, a first `storageproxyd` run, `devinfo` and anything under `/dev/sd*`. The phone is real hardware with calibration data that can't be replaced, and a human has to be ready to recover it.
- **Ask the human before every reboot, flash, `push`, overlay boot or irreversible write.** That includes RPMB writes, a first `storageproxyd` run, `devinfo` and anything under `/dev/sd*`. The one exception is `omamobile-fp`'s own start at boot (fingerprint below): its storageproxyd runs by default. The phone is real hardware with calibration data that can't be replaced, and a human has to be ready to recover it.
- **The phone is shared with a human. Announce anything that affects the screen or the feel of the phone before you run it**: DPMS, display modes and refresh rate, brightness, `bl_power`, haptics, the torch, the shell restarting, rotation. Otherwise they think the phone is broken, or it buzzes in their hand.
- **Only slot B and `userdata` are ours.** Write only `boot_b`, `init_boot_b`, `vendor_boot_b`, `vendor_kernel_boot_b` and `dtbo_b`, and only through `bin/omamobile flash|push` or, on a phone whose `/etc/omamobile/boot-update.conf` says `AUTO_WRITE=yes` (only `tools/install-phone` writes it, for a release install, or a human by hand in an approved runbook), `linux-omamobile`'s pacman hook `omamobile-boot-update` ([RELEASES](docs/RELEASES.md) §5.3, §12 decisions 3 and 10): it writes only `<image>_b` for the descriptor's `BOOT_IMAGES`, each found by GPT name on the main LUN, on `UFS_RW` and left `ro` 0 by the storage guard, read back by sha256, and never reboots. A development phone has no such file, so `push` stays its only writer. Never touch bootloader, radio, `devinfo`, `persist`, `efs*`, `modem*` or `vbmeta`, and never run an unsuffixed `fastboot flash`, with one exception: `userdata`, and only through `tools/install-phone` (serial pinned, codename typed, allowlist, dry run first). Slot A's stock Android is the way back.
- **Qualcomm A/B phones (Pixel 4 family) keep the slot flags in GPT attributes,** so slot B can only be marked bootable by writing the partition table. That write is a narrow, named exception, never automatic: by hand, once per install of slot B's boot image, and only for a device whose entry in [CONTRIBUTING](CONTRIBUTING.md) §3.1 names the LUN, the four sectors (LBAs 1, 2, last-1 and last), the attribute bit and the CRCs it rewrites. That device's plan must also record the slot flags before and after, the rollback for a corrupted GPT, and the way back: stock restored on slot A first, or the owner's explicit acceptance of buttons-only recovery. The storage guard can't block this write, so it never runs from a service or at boot.
Expand Down Expand Up @@ -103,7 +103,7 @@ tools/phone-ssh CMD -> run anything; stream files with ssh 'cat > f' < f
| `tools/build-packages`, `tools/build-rootfs` | aarch64 packages (signed, `out/repo`) and the root image, built on the laptop in an Arch Linux ARM container (qemu-user); no phone |
| `tools/install-phone` | The installer: fastboot checks, the owner's answers into a local image copy, then only slot B's images and `userdata`. Asks the human to type the codename; `--dry-run` first. Never run it without the human's go |
| `tools/nv-backup DIR`, `--check DIR` | The read-only backup of the radio and calibration partitions (the descriptor's `NV_PARTS` and `NV_BACKUP_EXTRA`) over USB SSH, found by `PARTNAME`, refused unless all are read-only and unmounted, each copy verified against a second read on the phone; `--check` is the checksum check of section 1 against such a backup. The output holds the IMEI: never commit or share it |
| `tools/phone-provision` | After a fresh install: Google's files from the user's factory image and the phone's own data from the backup. `--fingerprint` copies Trusty's state but never starts the service |
| `tools/phone-provision` | After a fresh install: Google's files from the user's factory image and the phone's own data from the backup. `--fingerprint` copies only the calibration and `persist:/ss` copies (the runner makes both itself on a new install), `--restore-td` also Trusty's TD and the enrolled fingers, valid only if no storageproxyd ran since the backup; it never starts the service |
| `tools/build-packages`, `tools/repo-push` | Maintainer only: the signed `[omamobile]` repository, built on the laptop with no phone (needs `keys/`, never committed); the release key's layout is in [RELEASES](docs/RELEASES.md) §10 (`tools/release-key-init`, run once); `tools/repo-publish` publishes to `pkgs.omamobile.org` (development daily from `origin/main`, stable on the maintainer's go). `tools/repo-build` builds on a connected phone instead: an opt-in shortcut for Mesa, Hyprland and libcamera, never a requirement |
| `tools/release-upload [--dry-run] [--full] [--latest] BUNDLE` | Maintainer only: upload a signed bundle and its root image to `pkgs.omamobile.org/releases/<codename>/<version>/` ([RELEASES](docs/RELEASES.md) §6). It checks the signature, the checksums and `manifest.json` first, uploads into a staging directory that is renamed into place, never overwrites a version, and reads every file back over HTTPS. The server side (CORS, MIME types, caching) is `tools/server/releases-nginx.sh`, which the maintainer runs with sudo on the server. Never run either without the human's go |
| `tools/release [--dry-run] [--version YYYY.MM.DD] STAGE` | Maintainer only: [RELEASES](docs/RELEASES.md) §11 as stages run in order (`status`, `kernel`, `build`, `images`, `packages`, `rootfs`, `bundle`, `test-install`, `identifiers`, `verify`, `upload`, `promote`, `tag`), each checking what the ones before it recorded in `out/release/<version>/state`. It builds the release kernel into its own `$KERNEL_BASE/out-kernel-release` and refuses a directory holding a development build; the steps that push, upload, promote or need the attended install stop and print the command. `scan` and `check-bundle` run the identifier and bundle checks alone. Never run a stage that builds or publishes without the human's go; `--dry-run` first |
Expand Down Expand Up @@ -156,7 +156,7 @@ Each entry gives the gotcha, then the reason or the fix. Details are in the link
- **ACPM reads its channel table from APM SRAM, and some channels are unusable** (a type-2 buffer channel with queues in DRAM): skip them rather than failing the probe. DVFS is channel 0, PMIC 2, thermal 9. Upstream supports polling only. [ACPM-PLAN](device/cheetah/ACPM-PLAN.md)
- **The regulator core turns off unused rails that have constraints about 30 s after late init:** load PMIC regulator modules after that, or make sure the rails are claimed. Since #227 the shared kernel builds `sec_acpm` in (the Pixel 9a's USB PHY needs its S2MPG14 rails at boot), so on the 7 Pro the S2MPG13 rails in the DT register before that cleanup and a `blacklist sec_acpm` does nothing; LDO9S-11S are GNSS-only, and LDO15S (`vdd_udfps`, the fingerprint sensor) and LDO12S (`vddio_cam`, camera I/O) are claimed by their drivers when those load, so the cleanup only turns off rails with no consumer yet. The fingerprint and camera starts' `modprobe sec_acpm` is a no-op there too. [GNSS-PLAN](device/cheetah/GNSS-PLAN.md)
- **The AoC starts only through Trusty** (`com.android.trusty.gsa.hwmgr.aoc`). The GSA mailbox `START` leaves the A32 held. So Trusty is a dependency of audio and sensors, not just of fingerprint, and it runs at every boot on the integration kernel.
- **Fingerprint: nothing writes `persist` or the RPMB without the human's explicit go.** The first `storageproxyd` run (FINGERPRINT-PLAN F4) is irreversible, and `omamobile-fp.service` ships disabled because its first run writes Trusty's secure storage. [FINGERPRINT-PLAN](device/cheetah/FINGERPRINT-PLAN.md)
- **Fingerprint: `omamobile-fp` starts by default** (omamobile-fingerprint 0.1.14 enables it with a vendor wants link; it is inert until `tools/phone-provision` has pushed Google's files). Its storageproxyd can write Trusty's TD superblocks to the RPMB at every start, the first time like an Android factory reset. What keeps stock's persistent data safe is the runner's guards. On the 7 Pro: read-only copies of `mfg_data` and `persist:/ss` (debugfs, `persist` never mounted), their recorded hashes, and a refusal to start when the TDP copy is missing or differs from its record or `persist:/ss/0` changed. On the 9a: only that the TDP image (`tdp.img`) exists. On both: one storage proxy per boot. Never write `persist` or `mfg_data`, never weaken those guards, and never stop and start `omamobile-fp` (or any storageproxyd) in the same boot: Trusty keeps its storage state until a reboot, and a restart between TD's clear and its first commit crashed Trusty's storage app (F19), so reboot instead (the runner refuses a second start). To keep it off, `systemctl mask omamobile-fp` (`disable` doesn't, because of the vendor link). Never restore an old TD (`phone-provision --restore-td` only if no storageproxyd ran since the backup). Starting the stack by hand where it isn't running (stage starts, runbooks) is still the human's call. [FINGERPRINT-PLAN](device/cheetah/FINGERPRINT-PLAN.md) F19
- **Set the Bluetooth address only after powering the controller on:** set on a never-powered controller, the kernel withdrew the index for good.
- **spi-s3c64xx with automatic chip select dropped bits between transfers before linux-omarchy-mobile#150 (merged 2026-10-31):** its FIFO flush cleared the packet count before turning the channels off, so the controller clocked a few bits with the slave still selected. A slave that restarts per chip-select cycle (touch) doesn't notice; one that streams across cycles (the 9a's GNSS core, CHPP) loses 2-6 bits per transfer, and every read lands at a different bit offset. [tegu MODEM-PLAN](device/tegu/MODEM-PLAN.md) "G3, GNSS gets a fix"
- **A node without pinctrl runs on the bootloader's pins, and a pin change tested next to another fix proves nothing on its own.** The 9a's GNSS SPI has no pin group and runs at the bootloader's drive 0; raising the drive looked like it cleaned the data, but it was tested together with the SPI flush fix, and with the flush fix alone at drive 0 the data was just as clean (linux-omarchy-mobile#151 closed). Read the bank's CON/PUD/DRV in `/sys/kernel/debug/pinctrl/<controller>/pins` (one controller at a time, as the gs101 note above says) before changing anything, then change one thing per boot, and check whose pins they are in the vendor tree before claiming them (gpp22 is the eSE's). [tegu MODEM-PLAN](device/tegu/MODEM-PLAN.md) "G3, GNSS gets a fix"
Expand Down
Loading