Skip to content

install-phone, install-guided, bundle-manifest: install on the running slot (manifest format 2, ACTIVE-SLOT-PLAN §7 steps 6-9) - #848

Merged
derekross merged 6 commits into
mainfrom
active-slot-tools
Nov 16, 2026
Merged

derekross merged 6 commits into
mainfrom
active-slot-tools

Conversation

@derekross

@derekross derekross commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Steps 6-9 of ACTIVE-SLOT-PLAN §7 (approved 2026-11-16), behind a descriptor line no device has. Every existing release stays format 1, byte for byte.

6. Descriptor keys. INSTALL_SLOT=active|b (absent = b) and INSTALL_ACTIVE_SLOTS (a, b, a b; required with active, refused without it), checked with the same rules and words in bin/omamobile load_device, lib/descriptor.sh, tools/install-phone, tools/install-guided and tools/bundle-manifest. New tests/install-slot-descriptor holds all five to one verdict on 19 descriptors.

7. make-bundle / bundle-manifest. INSTALL_SLOT=active produces the shared contract's format 2 install object (image writes, accept_current_slots, after: ["reboot"], storage_guard with the marker, no require_matching_bootloader_slots). The bundle is refused unless the ramdisk image's initramfs holds /etc/omamobile-ufs-rw-slot = running. In that case README.txt gives Google's Flash Tool / flash-all as the way back. Format 1: tests/make-bundle pins the install object and README paragraphs. A cheetah bundle built with origin/main's tools and with this branch's has a byte-identical README.txt, and the manifest.json differs only in the checksums of the two changed tools.

8. install-phone. With format 2:

  • The target is the phone's current-slot from the accepted list. Otherwise it stops with current-slot-not-accepted and gives no --set-active advice.
  • Just before the first flash it reads the serial and slot again, and stops if either changed.
  • flash() allows only <image>_<target> and userdata. The other slot is refused, and in both formats BOOT_IMAGES and UFS_RW may hold only the five boot images (UFS_RW: their _b names and userdata), so vbmeta, abl or modem are refused before the phone is contacted.
  • It writes SLOT=<target> into boot-update.conf, on its own line before AUTO_WRITE=yes.
  • No --set-active, no slot probe and no bootloader-slot comparison. --reinstall, --bootloader-slots-match and --measure-other-slot are not used.
  • The guard marker is checked, also by --verify-only.
  • New plan, failure and done texts.

9. install-guided. Format 2 has no slot-B question and no slot check. A phone running from a slot the release doesn't accept stops before the unlock steps. Android-replaced texts throughout, and no "update Android" advice when the update would move the phone to an unaccepted slot. The radio backup was already a new folder per install; a test now holds that.

Docs: RELEASES §6 and INSTALL-GUIDED §6/§7 describe format 2 as built and not yet used by any device.

Tests run locally: tests/install-phone, tests/install-phone-initramfs (needs dtc), tests/install-guided, tests/make-bundle, tests/install-slot-descriptor, tests/boot-update-parity, tests/tools-help, tests/build-rootfs, packages/omamobile-boot-update/test/all, tools/pr-check origin/main. No phone touched.

Not in this PR: tools/release-upload still refuses any manifest format but 1. lib/descriptor.sh changes ship with #847's omamobile-boot-update 0.2.0: merge #847 first, then this one; no separate version bump here.

🤖 Generated with Claude Code

derekross and others added 6 commits November 16, 2026 10:31
…y reader

ACTIVE-SLOT-PLAN §7 step 6: where a release installs. INSTALL_SLOT=b (the
default) keeps manifest format 1, slot B; INSTALL_SLOT=active with
INSTALL_ACTIVE_SLOTS (a, b or a b) selects format 2, the slot the phone
runs from. No device sets either line yet.

bin/omamobile's load_device and omamobile-boot-update's lib/descriptor.sh
check them with the same rules and words, as the installers and
bundle-manifest will (their own commits follow; tests/install-slot-descriptor,
added with the last of them, holds all five to one verdict).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ACTIVE-SLOT-PLAN §7 step 7. A descriptor with INSTALL_SLOT=active gets the
shared contract's format 2 install object: writes naming images, the
accepted current slots, after ["reboot"], no
require_matching_bootloader_slots, and a storage_guard for the running
slot. bundle-manifest refuses such a bundle unless the ramdisk image's
initramfs holds /etc/omamobile-ufs-rw-slot reading "running", and
README.txt's way back becomes Google's factory image.

Without the line the output is unchanged: tests/make-bundle pins format
1's install object and README paragraphs, and a cheetah bundle built with
origin/main's tools and with these has a byte-identical README.txt and the
same manifest.json but for the changed tools' own checksums.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ACTIVE-SLOT-PLAN §7 step 8. With INSTALL_SLOT=active the target is the
phone's current-slot, which must be one of INSTALL_ACTIVE_SLOTS (else the
current-slot-not-accepted stop, with no advice to switch slots). The phone
is read again just before the first flash and a changed serial or slot
stops it; flash() accepts only <image>_<target> (slot-B name on UFS_RW)
and userdata; boot-update.conf gets SLOT=<target>; no --set-active, no
slot probe, no bootloader-slot comparison; a read-only read-back before
reboot. The ramdisk must carry the guard's running-slot marker (checked by
--verify-only too), and a format 2 manifest.json must match the contract
exactly. The plan, failure and done texts say Android is replaced and the
way back is Google's factory image. Format 1 is unchanged.

Tests: fake fastboot reporting slot a, slot b (refused, then accepted),
a slot change between the first look and the gate, the slot-B options
ignored, a missing marker, bad descriptor keys and format 2 manifests
edited every way; tests/install-phone-initramfs shows a format 2 bundle
flashes the hook's own images to slot a or b.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ACTIVE-SLOT-PLAN §7 step 9. For INSTALL_SLOT=active step 3 only checks
that the phone runs from an accepted slot (current-slot-not-accepted
before the unlock steps otherwise, never advising a slot switch), each
file is checked against the running slot's partition, and the warning,
the words after the dry run, the failed-write stop and the check say
Android is written over and the way back is Google's factory image. An
Android update is not advised when it would move the phone to a slot the
release doesn't accept. The radio backup already goes into a new folder
on every install; a test now holds that.

tests/install-slot-descriptor holds bin/omamobile, lib/descriptor.sh,
install-phone, install-guided and bundle-manifest to one verdict, in the
same words, on 19 descriptors, and checks that no device sets the keys.

INSTALL-GUIDED and RELEASES describe format 2 as built and not yet used
by any device.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The install link's patch checks that boot-update.conf ends with
"AUTO_WRITE=yes\n" (found by the phone-side branch, #847), so a format 2
install writes SLOT=<target> on its own line before it. Format 1's file is
unchanged; the test checks the order and the file's last line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review of #848, round 1.

B1: a descriptor naming vbmeta (or abl, modem) in BOOT_IMAGES with its _b
on UFS_RW made a format 2 install flash vbmeta_a, stock's live image.
install-phone now holds BOOT_IMAGES to boot, init_boot, vendor_boot,
vendor_kernel_boot and dtbo and UFS_RW to their _b names and userdata
(bin/omamobile's UFS_RW_ALLOWED), in both formats, before the phone is
contacted; bundle-manifest's format 2 branch holds the same list of its
own. Tests: vbmeta refused before any fastboot call in both formats, and
by bundle-manifest.

N1: tests for the gate's serial check and its still-listed check, the
read-back's no-restart stop and flash()'s UFS_RW condition (flash() run
on its own); each was checked to fail with that check removed.

N2: SLOT= stays before AUTO_WRITE=, but the earlier reason was wrong (the
install link's check is a test of its own write): the order is harmless
either way and kept first for readability.

N4: a format 2 write that fails says plainly not to restart the phone and
to run the install again from Fastboot Mode (install-phone and the guided
install's stop).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@derekross derekross changed the title Active slot, steps 6-9: descriptor keys, manifest format 2, install-phone and install-guided on the running slot install-phone, install-guided, bundle-manifest: install on the running slot (manifest format 2, ACTIVE-SLOT-PLAN §7 steps 6-9) Nov 16, 2026
@derekross
derekross merged commit c462357 into main Nov 16, 2026
2 checks passed
@derekross
derekross deleted the active-slot-tools branch November 16, 2026 16:25
derekross pushed a commit that referenced this pull request Nov 18, 2026
…s and userdata, in format 1 too

Since #848 bundle-manifest checked BOOT_IMAGES against boot, init_boot, vendor_boot, vendor_kernel_boot and dtbo, and UFS_RW against their slot-form names and userdata, only for a format 2 release, which no device builds yet. A format 1 descriptor naming modem or vbmeta, with its _b name on its own UFS_RW, still gave a manifest whose install plan wrote that partition. The same two checks now run for both formats, before make-bundle moves the new bundle in, so a refusal keeps the earlier bundle; every descriptor in the tree is inside the set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant