Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Fix incorrect version displayed for OTA-patched HomePod

Guilherme Rambo7a1cba175d2d
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index cec78b5f..ad5d986d 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -1,6 +1,6 @@
# Patch Comparison: Regular / Development / Jailbreak / Experimental
-> **HomePod 27.2 OTA and native Sound Glow (2026-10-23, offline candidate).**
+> **HomePod 27.2 OTA and native Sound Glow (2026-10-23, live verified).**
> The 27.0 donor lacks the artwork/color extraction and native media animation
> cases introduced in 27.2. `system-homepod-exp-ota_userland` stages the full
> Apple HomePod mini OTA over the same device's 27.0 IPSW, retaining its restore
@@ -23,7 +23,16 @@
> produce distinct native animated colors; pause fades to idle and resume works.
> A follow-up to the existing Siri speech patch uses a mixable, ducking auxiliary
> session with notify-on-deactivation after the live interruption test made
-> Music abandon the receiver. Its AirPlay handoff still needs live verification.
+> Music abandon the receiver. The owner confirmed full speech while Music stayed
+> on HomePod; native frames handed off to Siri and returned to colored music.
+> Successful installation now records the actual mounted HomePod SystemVersion
+> after disk commit, preserving cloudOS and variant. Preparing an OTA alone does
+> not promote the host label; full-install command/creator variant recording
+> retains HomePod identity. Restore-info tests cover this merge.
+> Opt-out removes the policy and injected load command and restores white native
+> playback. Re-enable plus cold boot restores audible music and colored native
+> animation, confirmed by the owner and changing valid RGB reports. Final live
+> bundle: `2.11.0-local.8e60e757`; original 27.0 VM and default bundle preserved.
> **HomePod Siri speech policy (2026-10-23, live speech verified).**
> New optional `system-homepod-exp-siri_speech` generates
diff --git a/Research/Firmware/homepod_mini_support.md b/Research/Firmware/homepod_mini_support.md
index 8337e9fe..c2bf0d75 100644
--- a/Research/Firmware/homepod_mini_support.md
+++ b/Research/Firmware/homepod_mini_support.md
@@ -129,12 +129,14 @@ also completed against the actual OTA: 51 payload chunks and 6,721 separate
hard-link destinations passed full path validation, both target-version
records identify 27.2/24K120, and the base IPSW manifest remains 27.0/24J361.
`fw patch` resolved the 27.2 HomePod preset and processed all 11 components,
-applying 241 patches without an undeclared patch warning. The stopped,
-unrestored candidate is under
-`.build/homepod-sound-glow-research/machines/homepod-27-2`; preparation and
-patch logs are beside it in the research artifact directory. No VM was
-launched and no privileged installation was performed during these checks.
-Boot, migration and native Sound Glow still need live validation.
+applying 241 patches without an undeclared patch warning. The candidate was
+then moved to `/Users/insidegui/.vphone/machines/homepod-27-2`, restored and
+installed through Launchpad. Live SystemVersion confirms 27.2 / 24K120.
+Music/AirPlay audio, native Sound Glow artwork colors, pause/resume, Siri
+interruption/return and patch opt-out are verified; the original 27.0 guest is
+preserved. See [Sound Glow](homepod_sound_glow.md) for evidence and build details.
+The host label now records the actual installed userland after disk commit,
+preserving cloudOS; preparation alone continues to report the restore base.
## Validation
diff --git a/Research/Firmware/homepod_sound_glow.md b/Research/Firmware/homepod_sound_glow.md
index 42052b0d..087bfd58 100644
--- a/Research/Firmware/homepod_sound_glow.md
+++ b/Research/Firmware/homepod_sound_glow.md
@@ -2,8 +2,9 @@
The candidate follows the Apple TV OTA approach: restore the HomePod mini's
27.0 IPSW, use the full 27.2 OTA for System, then apply the selected guest patches
-to that System. Nothing has been installed into the running 27.0 VM. Live boot
-and Sound Glow verification remain pending administrator availability.
+to that System. The separate 27.2 VM boots and plays native Sound Glow through
+Music/AirPlay, including artwork changes, pause/resume and Siri handoff. The
+original 27.0 VM remains intact. Live details and final checks appear below.
## Donor identity and acquisition
@@ -83,8 +84,10 @@ While enabled, the getter returns native value 1. The original setter still
receives Home updates; disabling policy exposes the actual setting again.
Deselection restores the backed-up native executable, reseals the app and
removes the policy. No Home account or accessory preferences are rewritten.
-There is no host scheduler, synthesized LED animation, artwork scraper, global
-MobileGestalt change or audio-session modification.
+The Sound Glow adapter uses no host scheduler, synthesized LED animation,
+artwork scraper, global MobileGestalt change or audio-session modification.
+The separate Siri session policy correction found during live interruption
+testing is described below.
## Verification boundary
@@ -95,12 +98,12 @@ resolution checks cover version gating, default selection, TV rejection and
missing prerequisites. Archive tests cover ZIP metadata ordering and rejection
of duplicate entries; existing archive path/size bounds remain in force.
-Static native control flow establishes the candidate's enable mechanism; it
-does not prove real AirPlay artwork delivery, brightness, animation timing or
-27.2 boot compatibility. A live candidate must establish all of those, then
-verify pause/resume, a change between distinctly colored album covers, Siri
-interruption and return to music, policy opt-out and restart persistence. The
-original 27.0 VM and its once-only welcome claim must remain recoverable.
+Static native control flow establishes the enable mechanism; runtime proof is
+recorded below. Live tests cover 27.2 boot, AirPlay artwork delivery, changing
+colored native frames, pause/resume and Siri interruption/return. Exact beat
+phase alignment has not been instrumented. Policy opt-out/re-enable is checked
+through the normal installer. The original 27.0 VM and its once-only welcome
+claim remain recoverable.
Analysis artifacts and saved REA snapshots live locally under
`.build/homepod-sound-glow-research/`. They are not shipped runtime resources.
@@ -128,13 +131,14 @@ Analysis artifacts and saved REA snapshots live locally under
- The production Mach-O injector successfully adds the weak guest adapter load
command to a separate copy of the 24K120 NowPlayingCap executable.
-The prepared candidate is
-`.build/homepod-sound-glow-research/machines/homepod-27-2`. Its Disk.img is a
-new, unrestored VM. Firmware preparation/patching and raw payload staging are
-complete; restore, CFW installation, boot and playback have **not** run. Logs
-are `prepare.log`, `patch.log`, `bundle-build.log` and `*-dry-run.log` beside it
-in the research artifact folder. The original running `homepod-mini` remains
-bound to `2.11.0-local.3f1d474e` and software 27.0; it was not stopped or updated.
+The candidate was prepared under
+`.build/homepod-sound-glow-research/machines/homepod-27-2` and moved to
+`/Users/insidegui/.vphone/machines/homepod-27-2` for live installation. Preparation
+logs remain in the research artifact folder, alongside restore, installation,
+build and native runtime evidence. The original `homepod-mini` retains bundle
+`2.11.0-local.3f1d474e` and software 27.0. It was stopped during these tests to
+avoid two identically named AirPlay receivers; its disk and welcome claim were
+not updated.
### Live continuation
@@ -172,15 +176,38 @@ the owner observed Music switching output back to the Mac at speech start.
The existing auxiliary Playback session used categoryOptions=0, interrupting
tvairplayd. Its policy now uses the public AVFAudio MixWithOthers|DuckOthers
options and NotifyOthersOnDeactivation, without touching the shared session.
-The native lifetime/error harness and complete bundle pass. Live verification
-of the AirPlay-preserving speech handoff remains pending that build's deploy.
-
-Install the prepared bundle through Launchpad when authorization is available.
-Use the returned installed version, preserving the default bundle and all other
-VM bindings. Restore and install the prepared 27.2 candidate as a separate VM,
-then verify boot, exact device/OS identity, audio and native top-cap delivery
-before sending Music/AirPlay to it. Confirm native artwork colors change with
-tracks and the animation reacts during playback, pauses/resumes, yields to Siri
-and returns to music. Exercise Sound Glow opt-out through the patch selection
-and environment update, then re-enable and reboot. Keep the original 27.0 VM
-until the candidate passes these live checks.
+The native lifetime/error harness and complete bundle pass. In build
+`2.11.0-local.b28f6d9a`, the owner confirmed full speech with Music staying on
+HomePod. Native playback state remained 1 before and after speech; the Siri
+bank acquired the display during speech and returned to the colored music bank
+afterward. Frame samples are saved in the local research evidence.
+
+The live list also exposed stale host bookkeeping: it retained the 27.0 restore
+base and generic iPhone device. The installer now reads SystemVersion from the
+mounted installed System after applying patches and records it only after
+disk commit, with invoking-user credentials. Full install, creator and
+environment redeploy share this installer path; subsequent variant recording
+keeps actual HomePod identity. It preserves cloudOS and the installed variant,
+and preparation/base restore do not promote the version. Nineteen restore-info
+tests pass, including the explicit installed-userland merge and later variant
+recording. The final build is `2.11.0-local.8e60e757`; its successful environment
+redeploy corrects Launchpad to 27.2 / 24K120, with cloudOS still 26.4 / 23E5207q.
+
+Opt-out via fw set-patches and cfw update-environment removes the policy and
+restores NowPlayingCap. A bounded read of all 62 Mach-O load commands from the
+live opted-out app confirms the guest adapter is absent.
+Music playback in that opted-out boot produces white native frames, with
+equal RGB channels and no rejected reports. Re-enabling through the preset and
+environment update reinstalls the policy, and the final build cold-boots with
+Enabled=true. The owner confirmed audible music and colored animation in that
+final boot. Native frame generations 1836, 1947 and 2071 contain unequal RGB
+channels with zero rejected reports, independently confirming colored motion
+after opt-out, re-enable and cold boot. The final candidate is left running on
+`2.11.0-local.8e60e757`; all changes remain uncommitted.
+
+The default bundle remains 2.10.1. The original homepod-mini remains stopped,
+bound to its original 27.0 bundle; only homepod-27-2 is bound to the final build.
+The two receivers share the native AirPlay name HomePod, so keep one stopped
+when selecting the other for playback. The original disk and durable welcome
+claim were not modified. No general migration of an existing 27.0 VM is claimed:
+these tests use a separately restored 27.2 OTA candidate.
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
index 5906fab1..55abb754 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
@@ -433,6 +433,7 @@ struct VPhoneCustomFirmwareInstaller {
// Resolved once the system volume is mounted (it needs the "was
// installed" signal there), then used again by the Preboot pass.
var priorGuest = Set<String>()
+ var installedHomePodUserland: VPhoneRestoreInfo.OSVersion?
do {
// Every descriptor on a guest volume lives in this scope, so none
// is left open to hold the volume busy when it is unmounted.
@@ -502,6 +503,18 @@ struct VPhoneCustomFirmwareInstaller {
environmentOnly: true,
)
}
+ if device.family == .homePod, liveGuest.contains(FirmwareGuestSystemPatchSet.homePodOTAUserland) {
+ // Read the installed bytes while the private System is still
+ // mounted. Preparation/base restore must never promote this
+ // host label before a successful OTA System installation.
+ let data = try systemRoot.readData("System/Library/CoreServices/SystemVersion.plist")
+ guard let version = try PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any],
+ let product = version["ProductVersion"] as? String,
+ let build = version["ProductBuildVersion"] as? String else {
+ throw ValidationError("Installed HomePod userland has no SystemVersion identity.")
+ }
+ installedHomePodUserland = .init(version: product, build: build)
+ }
}
// The selected Preboot identity can also reach an installed guest through
// an environment update, using its installed tree without a restore.
@@ -596,6 +609,21 @@ struct VPhoneCustomFirmwareInstaller {
in: bundleDirectory,
owner: invokingUser.map { ($0.uid, $0.gid) },
)
+ if let installedHomePodUserland {
+ let installedBundle = URL(fileURLWithPath: bundlePath, isDirectory: true)
+ let record: () throws -> Void = {
+ let vm = try VPhoneBundle.load(at: installedBundle)
+ let variant = VPhoneRestoreInfo.load(fromBundle: vm)?.variant ?? "jb"
+ _ = try VPhoneRestoreInfo.recordVariant(variant, toBundle: vm,
+ installedUserland: installedHomePodUserland)
+ }
+ do {
+ if let invokingUser { try invokingUser.withUserCredentials(record) }
+ else { try record() }
+ } catch {
+ fputs("warning: could not record installed HomePod userland: \(error)\n", stderr)
+ }
+ }
switch mode {
case .full:
if liveGuest.contains("system-vphoned-boot-install") {
diff --git a/VPhoneKit/VPhoneCoreKit/Restore/VPhoneRestoreInfo.swift b/VPhoneKit/VPhoneCoreKit/Restore/VPhoneRestoreInfo.swift
index 92b654c0..70bdcae3 100644
--- a/VPhoneKit/VPhoneCoreKit/Restore/VPhoneRestoreInfo.swift
+++ b/VPhoneKit/VPhoneCoreKit/Restore/VPhoneRestoreInfo.swift
@@ -82,17 +82,20 @@ public struct VPhoneRestoreInfo: Codable, Equatable, Sendable {
}
/// Set `variant` (and its device) on the bundle's restore-info.json, keeping
- /// the recorded versions. nil if no versions exist yet to preserve.
+ /// the recorded versions unless the completed installer supplies an actual
+ /// mounted System identity. nil if no versions exist yet to preserve.
@discardableResult
- public static func recordVariant(_ variant: String, toBundle bundle: VPhoneBundle) throws
+ public static func recordVariant(_ variant: String, toBundle bundle: VPhoneBundle,
+ installedUserland: OSVersion? = nil) throws
-> VPhoneRestoreInfo?
{
guard let base = load(fromBundle: bundle) else { return nil }
let merged = VPhoneRestoreInfo(
- ios: base.ios,
+ ios: installedUserland ?? base.ios,
cloudOS: base.cloudOS,
variant: variant,
- device: device(forVariant: variant),
+ device: bundle.manifest.guestDevice.family == .homePod
+ ? bundle.manifest.guestProductType : device(forVariant: variant),
)
try merged.write(toBundle: bundle)
return merged
diff --git a/VPhoneKit/VPhoneCoreKitTests/Restore/RestoreInfoTests.swift b/VPhoneKit/VPhoneCoreKitTests/Restore/RestoreInfoTests.swift
index fb86c4f4..4dd82cd5 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Restore/RestoreInfoTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Restore/RestoreInfoTests.swift
@@ -3,13 +3,14 @@ import Testing
@testable import VPhoneCoreKit
struct RestoreInfoTests {
- private func makeBundle() throws -> VPhoneBundle {
+ private func makeBundle(guestProductType: String? = nil) throws -> VPhoneBundle {
let root = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
let manifest = VPhoneVirtualMachineManifest(
cpuCount: 2,
memorySize: 1024 * 1024,
romImages: .init(avpBooter: "a", avpSEPBooter: "b"),
+ guestProductType: guestProductType,
)
return VPhoneBundle(url: root, manifest: manifest)
}
@@ -147,6 +148,23 @@ struct RestoreInfoTests {
#expect(try VPhoneRestoreInfo.recordVariant("jb", toBundle: b) == nil)
}
+ @Test func `installed HomePod userland preserves cloudOS and later variant recording`() throws {
+ let b = try makeBundle(guestProductType: "AudioAccessory5,1")
+ defer { try? FileManager.default.removeItem(at: b.url) }
+ let cloud = VPhoneRestoreInfo.OSVersion(version: "26.4", build: "23E5207q")
+ try VPhoneRestoreInfo(ios: .init(version: "27.0", build: "24J361"), cloudOS: cloud).write(toBundle: b)
+ // Preparation and base restore alone never promote the userland.
+ #expect(try VPhoneRestoreInfo.recordVariant("jb", toBundle: b)?.ios.version == "27.0")
+ let actual = VPhoneRestoreInfo.OSVersion(version: "27.2", build: "24K120")
+ let installed = try VPhoneRestoreInfo.recordVariant("jb", toBundle: b, installedUserland: actual)
+ #expect(installed?.ios == actual)
+ #expect(installed?.cloudOS == cloud)
+ #expect(installed?.device == "AudioAccessory5,1")
+ // The full-install command and creator both record the variant again.
+ let rerecorded = try VPhoneRestoreInfo.recordVariant("jb", toBundle: b)
+ #expect(rerecorded == installed)
+ }
+
@Test func `normal boot rejects an explicit old variant but DFU still parses`() throws {
let b = try makeBundle()
defer { try? FileManager.default.removeItem(at: b.url) }