- Decision
- ADR-043
- Date
- 2026-08-23
- Status
- AcceptedAccepted
- Mentions
- ADR-041
1Decision
Resolve ADR-041's flagged "real success path unexecuted" and "real disk capacity unmeasured" revisit triggers: the real ceremony against candidate 2026081901 ran end to end for the first time and published a genuine signed OTA, independently verified on two separate machines.
2Why and evidence
The 2026-08-20 storage design (docs/superpowers/specs/2026-08-20-the signing host-ceremony-storage-design.md) proved insufficient by roughly an order of magnitude when actually executed: real attempts against the built candidate consumed ~20-23GB inside sign_target_files_apks alone and were repeatedly killed by the disk-safety watchdog, never reaching later stages.
Root-cause investigation (full account: docs/superpowers/specs/2026-08-21-the signing host-storage-rootcause-report.md) found this was not a bug but GrapheneOS's own sign_target_files_apks unpacking the entire uncompressed target-files tree (measured: 8.28GB uncompressed from a 3.76GB zip, 8,705 files) plus 44 separate APEX payload re-signs, all before any interim cleanup — inherent to the tooling, not fixable by AegisOS-side scripting.
Two real defects were found and fixed in tools/signing/sign-ota.sh along the way: (1) sign_target_files_apks's and, later, check_ota_package_signature.py's own common.MakeTempDir()/common.MakeTempFile() calls are bare tempfile.mkdtemp() with no dir= argument, silently defaulting to /tmp on the signing host's tiny root filesystem instead of the relocated pool, invisible to the watchdog — fixed by exporting TMPDIR to match the convention GrapheneOS's own multi-device batch wrapper (generate-releases.sh) already used; (2) a missing PATH entry for the delta_generator host binary in the same later verification step, since generate-release.sh's own PATH export dies with its process — fixed by adding the correct otatools-unpacked bin/ directory to PATH for that one command.
A minimal, independently-reviewed patch (tools/signing/generate-release-ota-only.patch, applied to the signing host's vendored generate-release.sh since the signing host has neither git nor patch installed) makes the ceremony stop right after the real OTA and its metadata exist, skipping GrapheneOS's separate factory-image/img_from_target_files/ssh-keygen tail this pipeline never consumed — confirmed via real upstream GrapheneOS source that ota_from_target_files and img_from_target_files are mutually independent, so skipping the latter cannot affect OTA correctness.
The owner separately grew the hypervisor-backed storage behind the build-signed/build-unsigned virtiofs pool from 70G to 129G total (24G to 81G real available headroom, confirmed identically from both VMs), which is what actually let a real run get far enough to expose the two TMPDIR/PATH defects above — neither would have been found by code review alone.
3Consequences
tools/signing/sign-ota.sh (final hash 27556ea6cb7f3f96816e1a25362898aa) and the vendored, patched generate-release.sh on the signing host are deployed and proven against real hardware, not merely reviewed.
First real signed alpha OTA: <build-root>/signed/2026081901/lynx-ota_update-20260823134826.zip, SHA-256 615858baaf9db0608926d4acc8caa1b3c112a125b077a2712177c3c5ff90dba2, signed-data digest 1dda2783ae4b3bd76f27ab258da8781c312524865d537b39b34e0401f9882906 confirmed identically by independent check_ota_package_signature.py runs on both the signing host and the build host (separate Python/OS environments, only the public certificate relayed between them, no private key material left the vault).
Real peak disk usage for this first complete run was not precisely captured (live monitoring did not cover the run continuously through to publish) — bounded as "stayed under ~81G, watchdog never fired" but not measured exactly.
4Review when
Revisit if a future candidate (a different device, or a lynx build with a substantially larger target-files tree or APEX count) approaches the new ~81G headroom — re-run with continuous monitoring through to publish first to get a real peak number before assuming margin is adequate. Revisit the generate-release-ota-only.patch if GrapheneOS's own script repository changes generate-release.sh's structure around the patched insertion point (the patch's context-line match will fail closed rather than silently misapply, per its own dry-run-first deployment instructions).
Read from docs/governance/decision-log.md, entry ADR-043.