Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Merge firmware and watch guest support stack for integration

Lakrb327eb3175d1
diff --cc Research/0_binary_patch_comparison.md
index fd356996,1f27af4d..7d653a7a
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@@ -3322,96 -3263,393 +3323,487 @@@ before keep Apple's SEP ROM; `vm confi
without a restore. `Firmware/opensep_sep_rom.md` has the contract and the
validation.
+## Guest Metal caches survive a reboot (2026-10-19)
+
+Row 29. `system-systemhook-cfw-metal_cache_reuse`, declared in the Guest
+System set, is on in `standard` and `experimental` and blocked in both Apple TV
+presets (they carry no SystemHook). Its target is the marker
+`/usr/lib/vphone-metal-cache-reuse`: `cfw install` and `cfw update-environment`
+write it when the patch is selected and remove it when it is not, so it is
+revertible. While the marker exists, SystemHook's constructor sets
+`FS_CACHE_REUSE_ON_REBOOT=1` before anything else unless the variable already
+has an explicit value, so `libCoreFSCache` can keep
+each Metal cache stamped by an earlier boot instead of resetting it. No system
+binary, shared cache or kernel byte changes.
+
+Verified on `Lychee` (iPhone, iOS 27.0.1, cloudOS 26.4) with real reboots:
+backboardd's `functions.list` keeps its boot UUID header and size across three
+boots, guest compiles for backboardd during five Settings rounds fall from
+about 145 to 0, no GPU restart, and the first go-home goes from about 31% to
+37–44% on time. Numbers and method: `Guest/gpu_acceleration.md`, "Real reboots
+with the patch (2026-10-19)".
+
+Host cache storage (2026-10-20): the launcher keeps a durable whole-directory
+snapshot in `<machine>/ShaderCache`, seeds Apple's normal ECID working cache
+before boot, and checkpoints after guest shutdown and again in the parent CLI
+after vphone-vm exits. A symlink experiment was rejected after sandbox denials
+and repeated compilation; the working root remains a real directory. This adds
+no binary patch and changes no Task3 key bytes. Index/data pairs stay together;
+copies are staged before whole-directory replacement and never merged across
+independent trees. Permissions use the shared symlink-safe host-file walker.
+The final bundle passed two Settings/Camera boot cycles with zero host GPU task
+compiles and zero GPU resets, including restoration after moving aside Apple's
+working directory. All 14 cache file checksums matched after each shutdown.
+Migration checks and runtime evidence are in `Guest/gpu_acceleration.md`,
+"Cache location and migration".
+
+Deletion correction: a missing machine snapshot now clears an already managed
+host working copy on the next boot, instead of importing it again. A shutdown
+checkpoint does not recreate a deleted snapshot. The working copy's existing
+`.host-ecid` marker distinguishes this reset from the first-use import. This
+resets host caches only; guest caches inside `Disk.img` remain. Frame-counter
+gaps in the earlier measurements do not independently demonstrate visible
+animation stutter; the user reports smooth warmed animations.
+The corrected bundle's reset/reboot test recorded 607 then seven host GPU task
+compilation events (129 then one during Settings), with zero GPU resets on both
+boots. Fourteen cache/permission tests and the complete bundle build pass.
+
+Standard promotion (2026-10-20): JB-32 is now enabled by Standard as
+`kernel-cfw-paravirt_gpu_task3`; all four record suffixes and kernel writes are
+unchanged. The shipped plist and catalog fallback agree. tvOS presets retain
+an explicit block. The old `kernel-exp-paravirt_gpu_task3` identifier migrates
+in VM selections, plans and receipts, including explicit opt-outs. New template
+keys include the enabled kernel patch, so a pre-Task3 template cannot satisfy
+the new Standard plan. Existing VMs bind the new bundle and run
+`cfw update-environment` and `cfw update-kernel` while stopped, keeping data.
+See `Documents/Guides/shader-cache.md` and the Standard promotion section in
+`Guest/gpu_acceleration.md`. The previous opt-in notes describe development
+validation; older host compatibility remains untested.
+Promotion validation: 62 focused tests passed, as did the full `VPhone` bundle
+build and admission check. The built CLI recognized Lychee's old Task3 receipt
+under the new name as applied, enabled by its preset and not pending.
+
+Review fixes (2026-10-21): JB-32 is declared for cloudOS 26.4 only. On the
+cloudOS 26.1, 26.2 and 26.3 research kernels the owning-task anchor in the
+superclass initializer does not resolve, and an ungated Standard patch made
+`fw patch` and `cfw update-kernel` abort for every iOS 18.6.2–26.3.1 machine.
+The `.features` site no longer loads a fixed 245: it branches to
+`.features_code` (`sub x0,xV,#246; tbnz x0,#63; tbnz wV,#31; mov w0,#245`,
+else `mov x0,xV`), which passes the granted version through when it is the
+kext's own or lower, and a refusal unchanged. A host that does not know the
+requested version grants its own maximum without the refusal bit
+(`-[_PGDevice setBinaryVersion:]`: macOS 15.6.1 → 209, 26.0 → 233,
+26.4 → 245, 27.0.1 → 252), so the fixed 245 had claimed 8 feature flags on a
+15.6.1 host and 4 on 26.0 that the host never enabled. The clamp uses only
+existing Keystone-checked encoders; the Task3 fixture test executes it for
+252, 246, 245, 233, 209 and a refusal. The persistent host shader cache is no
+longer required to launch: a VM that cannot prepare one logs a warning and
+boots without it.
+## Apply selected Preboot identity during guest updates (2026-10-21)
+
+`preboot-exp-devicetree_identity` was advertised as an `update-environment`
+guest patch but its installer call enabled identity only for full installs.
+Launchpad's Apply to Guest therefore completed with the identity still pending.
+Environment updates now run the existing identity rewrite when the current
+resolved plan selects it, using the installed tree without a restore directory.
+The patch bytes, presets, board-presenting guest guard, post-identity repair
+backup and existing off-state behavior are unchanged. This fixes the same
+delivery path for CLI updates, bundle changes and template guest-patch steps;
+other Preboot repairs already used it. It does not enable the eight firmware
+DeviceTree identity edits or establish that Apple will deliver Photos models.
+
+Validation on `upstream/main` `047642f8` (2.10.1): 77 existing tests in eight
+suites pass, covering guest device trees, patch resolution/catalogue/drift,
+board audio, microphone-array removal, iPhone product properties and haptics.
+The complete `VPhone` Debug build and bundle admission also pass.
++
+ ## The `minimal` preset: a restore image instead of patches (2026-10-19)
+
+ The patchless variant (`FirmwarePipeline.Variant.less`) was unreachable: every
+ caller passed `.jb`. It is a preset now, `minimal`, and the variant is
+ gone. The preset names three sets:
+
+ - `com.vphone.patchset.bootchain`, allowing only iBEC's and LLB's patches,
+ which the old `.less` variant applied too ("for the serial logs"). AVPBooter,
+ iBSS, TXM and the restore ramdisk stay stock, and the pipeline builds no
+ patcher for a boot chain component none of whose patches is on. A stock LLB
+ does not get the restored guest to its kernel: on 26.6 with cloudOS
+ 23E5207q it restarts right after its banner, with Apple's ROMs as with
+ OpenAVB and OpenSEP (2026-10-19). Which of LLB's patches it needs is open.
+ - `com.vphone.patchset.devicetree`, allowing only the board presentation
+ (`devicetree-cfw-serial_number`, `-home_button_type`,
+ `-artwork_device_subtype`, `-island_notch_location`) and the haptics and
+ microphone-array removals. They change no code.
+ - `com.vphone.patchset.restore.image` (`FirmwareRestoreImagePatchSet`), new,
+ named by no other preset:
+
+ | Identifier | What `fw patch` does |
+ | --- | --- |
+ | `filesystem-boot-cryptex_merge` | Merges the AppOS and SystemOS cryptexes into the OS image, adds the dyld symlinks, then rebuilds the static trust cache, the mtree and the digest database and root hash (`apfs_sealvolume`) |
+ | `filesystem-boot-gpu_driver` | Installs the PCC paravirtual GPU driver `fw prepare` staged |
+ | `filesystem-boot-mobileactivationd_should_hactivate` | The `should_hactivate` patch, in the image |
+ | `filesystem-boot-vphoned` | vphoned and its launch daemon, in the image |
+ | `filesystem-boot-launchd_cache_loader_unsecure_cache_gate` | Lets launchd read the launch daemons from the volume |
+ | `manifest-boot-digest_rehash` | Rewrites every BuildManifest digest to the files the restore now sends; for an AEA archive, the digest of its decrypted image, which is what Apple's manifests hold and what an 18.x restore checks the written image against |
+
+ The kernel and TXM stay stock, and the restore installs a system whose seal
+ the stock kernel verifies. `CryptexFilesystemPatcher` and `ManifestHashPatcher` used
+ to emit `filesystem.cryptex.merge` and `manifest.hash`, which no set declared;
+ they emit the identifiers above, and the pipeline builds each patcher only when
+ its patch is enabled.
+
+ Nothing may write the System volume after the restore, because that breaks the
+ seal. So for a VM whose plan enables `filesystem-boot-cryptex_merge`:
+
+ - `cfw install` touches no disk: it records an empty `Guest` receipt part and
+ the install, so the boot gate (`restore-info.json`) passes as for any VM.
+ `cfw update-environment` and `cfw update-kernel` refuse.
+ - `vm create` builds without a template (the offline trim and setup boot write
+ the system) and refuses `--template` and the slimming switches, as for an
+ Apple TV.
+ - `fw patch` needs root for the merge (owner-preserving copies on a mounted
+ image) and says so. Launchpad runs it through its helper's new
+ `patchRestoreImage` verb, which runs `fw patch <vm> --restore-image-only`
+ from the receipt-checked store bundle; that flag refuses any selection that
+ does not merge the restore image.
+ - `fw prepare` stages `apfs_sealvolume_<iOS version>` into `<restore>/.tools`
+ (the `fw seal-tool` fetch; iOS 18.x.y takes macOS 15.x.y, or without a twin
+ the newest macOS 15 below it) and the GPU driver for
+ `filesystem-boot-gpu_driver` as for `system-extensions-boot-gpu_bundle`.
+ `vm create` and Launchpad now record the preset before `fw prepare`, which
+ read `standard` before: the GPU staging followed the wrong selection for any
+ other preset as well.
+
+ The merged image must not carry the host's `.fseventsd`. `diskutil image
+ attach` mounts it browsable, so fseventsd starts a log on every writable
+ mount, and Apple's system volumes have none. With the log in the image, the
+ mtree listed `.fseventsd`, the restore wrote `.fseventsd/.ramdisk-boot-done`
+ into the restored volume, and `seal_system_volume` failed ("mtree: cannot
+ generate the XML dictionary", 26.6 on cloudOS 23E5207q, 2026-10-19). Each
+ writable mount now deletes the directory before it unmounts, which also stops
+ fseventsd writing it again for that mount.
+
+ The root hash `fw patch` computes has to be the one the restore computes, and
+ it was not ("Invalid root hash", `apfs_sealvolume` exit 65 in
+ `seal_system_volume`):
+
+ - The remap's `MODIFICATION` was the time of `/private/var` in the mtree,
+ on the assumption that `removeSpecificSystemFiles` changes it last. The
+ restore's own `mtree -m` sets it from the root entry (`.`), not from the
+ newest one: run on 2026-10-19, the device took the root's
+ `1792405582.069334279` while `/private/var` said `…582.936736187`. The
+ remap takes the root's time now.
+ - `createDigestAndHash` mounted the image writable only to unmount it again
+ for `apfs_sealvolume`, which needs the device; the mount changed the volume
+ after the mtree described it. It attaches the image with `-noMount` now.
+
+ The binaries the merge patches (`launchd_cache_loader`, `mobileactivationd`)
+ are re-signed in Apple's ad-hoc shape (`VPhoneSignOptions.Style.appleAdHoc`),
+ like the stock binaries around them. The guest's TXM is stock here: it takes
+ an ad-hoc binary from the static trust cache the merge rebuilds, but rejected
+ ldid's signature (no ad-hoc flag, empty CMS blob), and launchd panicked at its
+ first boot task ("launchd_cache_loader - posix_spawn: 85: Bad executable").
+ vphoned, its launch daemon plist and the rewritten `launchd.plist` belong to
+ root:wheel, as the system's own; they kept the host user's owner and group.
+
+ ## The research board stands in for vphone600 (2026-10-19)
+
+ Only the 26.1–26.4 beta cloudOS releases (up to 23E5207q) carry a vphone600ap
+ build identity. The 26.4 release and every one up to 26.7, and the 18.x
+ releases, have the research board alone (vresearch101ap). `FirmwareManifest`
+ now takes the research identities for the vphone600 components when there is
+ no vphone600ap, and leaves `RecoveryMode` out when the identity has none.
+ The new set `com.vphone.patchset.research.board` turns those components into
+ vphone600's. Every shipped preset names it. When the restore tree's
+ `RestoreDeviceTree` is not the research board's, `fw patch` records its patches
+ as not applicable (`FirmwarePipeline.resolveFirmwareApplicability`), so a
+ cloudOS with vphone600 components builds no SEP component, converts nothing
+ and stays byte-identical, and receipts do not claim the patches.
+
+ **`devicetree-boot-vresearch101_conversion`**
+ (`DeviceTreeResearchBoardConversion.swift`) rewrites the research tree before
+ any other device tree patch runs, whatever the selection, because those are
+ written against vphone600 paths and values. It finds the research tree by its
+ root `target-type` (`VRESEARCH101`) and then:
+
+ - sets the root identity (`VPHONE600AP`, `iPhone99,11`);
+ - adds the seven nodes the research board lacks: `/buttons`,
+ `/arm-io/multi-touch`, `/arm-io/bluetooth`,
+ `/product/vphone600-gestalt-variants` with its `d47vm2025vre-variant`,
+ `/product/maps` and `/product/haptics`. Each goes where vphone600 has it and
+ gets an unused `AAPL,phandle`;
+ - sets the phone's `/product`, `/defaults`, `/filesystems` and gestalt
+ variant properties, most of them `syscfg/` placeholders (flag 0x8000);
+ - removes `/defaults/pmap-max-asids` and `/product/kernel-core-dump-location`.
+
+ Existing phandles are kept, so `interrupt-parent`, `device-interrupt-parent`
+ and `serial-device` keep naming the nodes they named. The earlier port
+ renumbered every node and repaired those three references by hand, which
+ would have broken any other reference.
+
+ Checked against Apple: converting the vresearch101 tree of cloudOS 26.1
+ (`399b664d`) and of the 26.4 beta (`c0ecdb4b`) gives their vphone600 tree
+ property for property. The only differences are the build `time-stamp`, the
+ order properties are stored in, and the phandle numbers, which are compared
+ through the node each reference names. `DeviceTreeResearchBoardTests` runs
+ that comparison whenever an IPSW in `ipsws/` carries both trees.
+
+ **`sep-boot-vresearch101_sepd_dispatch`** (`SEPResearchBoardPatcher.swift`)
+ patches SEPD in the research board's SEP firmware. On the 26.4 beta, which
+ carries both, vphone600's SEPD sends operation 0x31 to the handler it shares
+ with 0x12 and others, which zeroes the reply; vresearch101's gives 0x31 a
+ handler of its own, which replies with a constant from `__const`. The patch
+ copies 0x12's switch table entry into 0x31's. The table is found on decoded
+ operands, as the bounds-checked switch (`cmp`, `csel ls`, `adrp` + `add` or
+ `adr` + `nop`, `ldrsw … lsl #2`, `adr`, `add`, `br`) whose bound covers 0x31,
+ and must be the only one. SEPD is found through the root argument object after
+ the "Built by legion2P" banner. The table lies in `__text`, and from 26.4 on SEPD
+ carries `__TEXT,__fipspost_hmac`, an HMAC-SHA256 of `__text` with an all-zero
+ key (both stock 26.4 SEPDs match it), which is recomputed. 26.1's SEPD has no
+ such section. A rebuilt `sepi` container keeps its `PAYP` load properties
+ (`arms`, `tz0s`): `IM4PHandler` now finds the `PAYP` element by its DER length,
+ which gives the same 10-byte header for TXM and the kernel as before and 6
+ bytes for the SEP image. `SEPResearchBoardTests` checks all of this against
+ Apple's 26.1 and 26.4 beta images when an IPSW in `ipsws/` carries both.
+
+ ### The research board's kernelcache
+
+ **`kernel-boot-vresearch101_kext_mix`** (`KernelCacheMixer`) gives the research
+ board's kernelcache the iPhone virtualisation kexts it lacks (paravirtual GPU,
+ touch, audio, FairPlay, ...). For the cloudOS's `kernelcache.release.vresearch101`
+ it finds the recipe in `Contents/Resources/kernelcache_recipes` by SHA-256, then:
+
+ 1. extracts the donor, the vphone600 kernelcache of the 26.4 beta (23E5207q,
+ read once from its cloudOS IPSW), and the base into KDKs with
+ `ipsw kernel extract --kdk --symbols`, naming the stripped symbols from the
+ recipe's maps;
+ 2. keeps the recipe's bundle list: the base without its research-board-only
+ kexts, plus the donor kexts that link against the base kernel;
+ 3. stages the bundles as a root-owned volume (kmutil reads no other kexts and
+ takes the host's own in their place without a word) and links it with
+ `kmutil create -a arm64e -n boot -s all -z -x --compress --img4-encode
+ --split-ro-rx-tags`;
+ 4. puts back Apple's CPU subtype if the builder wrote another, and checks that
+ every requested bundle was linked.
+
+ The mix replaces both `KernelCache` and `RestoreKernelCache`, so restore boots
+ it too. The pipeline keeps kmutil's container (its `PAYP` properties describe
+ the new layout) and saves the preset's kernel patches into it
+ (`ComponentDescriptor.replacement`); `minimal` adds none. The shipped kernels stay
+ in `FirmwareOriginals`. Mixes are cached in `~/.vphone/kernelcache/mix`, keyed
+ by the kernelcaches, the maps and bundle list and the builder layout.
+
+ Only the link needs root, and root runs no `ipsw`. `fw kernelcache <vm>` stages
+ the mix as the user (both extractions and the volume) and links it under sudo:
+ root copies the staged volume into a fresh root-only directory, walking it by
+ descriptor, refusing every symbolic link but the KDK's pointer to the volume's
+ extensions and normalising modes (kmutil skips a kext with a group- or
+ world-writable file as silently as one root does not own), and runs kmutil on
+ the copy. The Launchpad helper's link runs with `--link-only`, which never
+ stages. kmutil records the absolute path of every codeless kext, which moves
+ the end of `__PRELINK_INFO`: the volume path takes the length of the build root
+ Apple linked the base in, read from the base's own prelink info, so a mix no
+ longer depends on where it is built. The 26.6 mix then has the segment layout
+ of the hand-built research mix that booted.
+
+ Requirements: an `ipsw` with `kernel extract --kdk`, named by `VPHONE_IPSW`
+ (vphone-cli does not ship it); root; and for every base here (26.4–26.7, all
+ `kernel-last`) the kmutil of macOS 26.4 or later. `fw prepare` now pairs a
+ cloudOS without vphone600ap and refuses one whose kernelcache no recipe covers.
+ `cfw update-kernel` refuses on a mixed kernel, whose originals are the research
+ board's.
+
+ Checked on 2026-10-19: a `minimal` VM of iOS 26.6 on cloudOS 26.6 (23G71) restores
+ and boots, and vphoned answers. Checked on 2026-10-20 with the standard preset:
+ iOS 26.5 (23F77) on cloudOS 26.5 (23F75) and iOS 26.4 (23E246) on cloudOS 26.4
+ (23E244) restore and boot the same way, their GPU driver taken from a temporary
+ cloudOS restore. The 26.7 recipe is one the research workflow built and
+ validated statically; it has not run through this pipeline yet (26.7 has no
+ iPhone release to pair it with).
+
+ ## Apple Watch guests (2026-10-20)
+
+ A Watch7,18 (Apple Watch Series 11, N227b) IPSW restores as a guest of its own
+ family (`VPhoneGuestDevice.watch7_18`, 416x496 at 330 ppi, scale 2). No
+ cloudOS ships a kernel for a watch VM, and the vphone600 kexts are iOS builds,
+ so the watch boots the 26.4 research board kernel (23E244) rebuilt with the
+ watchOS kexts of its own IPSW. It takes the `watchos` preset: `minimal` with the
+ watch board's device tree in place of the iPhone17,3 identity, and activation
+ stock (`filesystem-boot-mobileactivationd_should_hactivate` is off; pairing
+ needs it).
+
+ ### The watch kernelcache
+
+ `kernel-boot-vresearch101_kext_mix` with the recipe `watch_26.4_23T240`. A
+ recipe now names the guest family it is for (`guest`) and its kext sources in
+ order (`sources`); each kext comes from the first source that has it, the KPI
+ bundles (System.kext) always from the base, so the base kernel resolves them.
+ A donor without a cloudOS URL is read from the guest's own restore tree.
+
+ | Source | Kexts |
+ | --- | --- |
+ | `watch7c_26.4_23T240`: `kernelcache.release.watch7c` of the Watch7,18 IPSW | 105: the watchOS families and drivers a vphone600 target built with `OSPRODUCT=WatchOS` takes, per the KDK's KernelCacheBuilder makefiles |
+ | base: 23E244 `kernelcache.release.vresearch101` | 11: ARMGIC, PVPanic, ParavirtGPU, VPIOP, VirtIO, VirtualPlatform, usb.cdc, ParavirtIOSurface, VirtIOStorage, and AppleUSBXHCI/XHCIPCI for the VM's USB touch screen; plus the 7 KPI bundles |
+ | `vphone600_26.4_23E5207q` | 6: VideoToolboxParavirtualization, AvpFairPlayDriver, driverkit.serial, usb.cdc.acm, usb.serial, VirtIONeuralEngineDevice |
+
+ The 23E244 kernel was chosen because its KPI symbol sets, C++ class sizes and
+ syscall, Mach trap and MIG tables equal the watch kernel's. Both maps are the
+ research results: the watch kernelcache symbolicated with BinDiff against the
+ 23E5207i KDK, and the 23E244 map of the iPhone recipe with about 2,400 fixes the
+ watch kexts' imports need (70 kernel-import binds resolved by three-way
+ alignment against the macOS 26.5.1 vmapple kernel, every `__ZTV`/MetaClass
+ label from `ipsw kernel cpp`, and IOSurface getters labelled 0x14 before their
+ entry, which failed PAC on `retab`). On 2026-10-20 the staged volume's kernel
+ and all 124 kext executables were byte-identical to the research mix that
+ booted to Setup with working touch.
+
+ ### Device tree
+
+ The installed tree presents N227b through the board copy iPad and Apple TV
+ guests use (`devicetree-cfw-ipad_*`). A watch needs two more:
+
+ | Patch | Change |
+ | --- | --- |
+ | `devicetree-cfw-watch_presentation` | `/product` `artwork-display-gamut`, `artwork-dynamic-displaymode` and `framebuffer-identifier` from N227b; the `vphone600-gestalt-variants/d47vm2025vre-variant` tags MobileGestalt reads in place of syscfg on the VM (`tag-ards`, `-arsf`, `-codf`, `-tprt`, `-crid`, `-dcrd`, `-fbid`, `-prde` from the matching N227b properties, `-isnl` and `-waco` 0). With the D47's values the watch UI finds no screen class ("unsupported screen class, no apple logo found") and stays black. |
+ | `devicetree-cfw-watch_driverkit` | `/product/supports-driverkit = 1`. The VM's touch screen is a USB device behind XHCI whose HID driver is the dext `com.apple.AppleUserHIDDrivers`; launchd starts driverkitd only on a tree that says so, and N227b's does not (a watch has no USB touch screen). |
+
+ ### Restore image
+
+ A watchOS image has no cryptexes: its dyld caches (arm64_32 and arm64e) are in
+ the OS image. For a watch `filesystem-boot-cryptex_merge` skips the cryptex
+ copies and dyld symlinks and only reseals the image with the guest payload.
+ `filesystem-boot-gpu_driver` marks the iOS driver and its compiler plugin
+ watchOS (`MachOBuildPlatform.watchOS`, re-signed, bundle resealed), as the
+ tvOS installer does; all its imports are in the watchOS 26.4 arm64e cache.
+ `filesystem-boot-launchd_cache_loader_unsecure_cache_gate` thins the universal
+ binary to its arm64e slice first (`MachOFatSlice`). vphoned is the arm64 daemon
+ marked watchOS (`vphoned-watchos`); its HID presses reach the crown as Home
+ (consumer 0x40). The side button is consumer Help (0x0C/0x95), not Power:
+ N227b's `/buttons` node names two buttons, `help` and `menu`, and Carousel's
+ `-[CSLHIDEventStreamWriter _eventForUsagePage:usage:down:]` maps 0x0C/0x40 to
+ the crown, 0x0C/0x95 to the side button (to the Action button only when
+ `shouldSimulateSting`) and vendor 0xFF01/0x200 to the Action button, which a
+ Series 11 lacks. `-[CSLUIHIDHandler init]` reads consumer Power (0x30) as the
+ separate `power` mask, which only sleeps or wakes the display. The VM window's
+ Device › Side Button (watch guests only) and the host automation key `side`
+ send 0x95; on 2026-10-20 it woke the `pair-watch` guest and opened Control
+ Center from the watch face, where 0x30 turned the display off.
+
+ vphoned links Vision (IcliKit's OCR) weakly: watchOS ships no Vision, and dyld
+ refused the daemon. Every other library it links strongly, and every symbol it
+ imports from them, is in the watchOS 26.4 arm64e cache; `ui.ocr` and
+ `ui.describe` report that the guest has no text recognition.
+
+ Checked on 2026-10-20: `vm create --device Watch7,18` with the Watch7,18 26.4
+ (23T240) IPSW and cloudOS 26.4 (23E244) links the mix, restores, boots, and
+ vphoned answers the first-boot ping.
+
+ ### Pairing with a phone
+
+ See `Research/Guest/watch_pairing.md`. The watch preset now patches activation
+ (`filesystem-boot-mobileactivationd_should_hactivate`, on the arm64e slice of
+ the universal binary), and three patches are new:
+
+ | Patch | Target | Change |
+ | --- | --- | --- |
+ | `devicetree-cfw-watch_companion` | an iPhone guest's tree | `/product/watch-companion = 1`, added where the board copy removed a placeholder. vphone600's `syscfg/waco` has no syscfg value on a VM, so iBoot drops it and the phone pairs with no watch. |
+ | `system-bluetoothd-cfw-btvc_le_connection` | `/System/Library/FeatureFlags/Domain/BluetoothFeatures.plist`, `cfw install`, iOS 26+ | `EnableBTVCLeConnection.Enabled = true`: bluetoothd's virtual LE controller may connect. Reverted from the `.bak` when turned off; blocked for tvOS. |
+ | `filesystem-exp-btvc_le_connection` | the same file in the restore image (`minimal`, `watchos`) | The same flag, written before the seal. |
+
+ ## iOS 18 guests on the research board (2026-10-21)
+
+ iOS 18.1 to 18.7.2 run on their own release's research board kernel, rebuilt
+ with the vphone600 kexts of the public cloudOS 26.1 (23B78), which still ships
+ vphone600 components. The userland comes from the iPhone XS family's IPSWs
+ (iPhone11,2/4/6), the only ones carrying every 18.x release, 18.7.x included.
+ Only `minimal` boots these kernels: `standard`'s kernel patches panic them early
+ in `kmem_init` (not investigated).
+
+ ### The kernelcache
+
+ `kernel-boot-vresearch101_kext_mix` with the bases `18.1_22B83` to
+ `18.7.2_22H124` and the donor `vphone600_26.1_23B78`. Across versions an
+ import cannot be bound by name, so every donor import was resolved by code
+ identity, from 26.1 to 18.7.2 and from 18.7.2 to each release, checked against
+ the Apple-symbolicated macOS 26.1 (25B5062e) and 15.7.3 (24G419) KDKs; both
+ maps carry the names those targets have. The 26.1 map and the 18.x maps had
+ given 60 donor imports a neighbour's name, consistently on both sides, so the
+ research builds bound them correctly: the `IORegistryEntry` twins below, and
+ 54 `OSMetaClass`, `IORegistryEntry`, `IOService`, `IOUserClient`,
+ `IOHIDDevice`, `IOHIDEventService` and `IOSCSIProtocolServices` virtuals
+ (the SCSI task management run was three slots off). The recipes give them
+ their real names. Every virtual one is proven by its vtable slot: the PAC
+ discriminator a donor kext signs the slot with is the
+ `ptrauth_string_discriminator` of the method's mangled name, the same slot in
+ both KDKs carries it, and each of the eight kernelcaches holds a signed
+ pointer with it to the renamed address. The `IORegistryEntry` twins also
+ have code markers:
+
+ | Function | Marker |
+ | --- | --- |
+ | `setLocation(const char *, plane)` | `OSSymbol::withCString`, then a virtual call with PAC diversifier 0x3025 |
+ | `setName(const char *, plane)` | the same, diversifier 0x848a |
+ | `setLocation(const OSSymbol *, plane)` | `plane + 0x30` (pathLocationKey), else `gIOLocationKey` |
+ | `setName(const OSSymbol *, plane)` | `plane + 0x28` (pathNameKey), else `gIONameKey`, and a `kernel_debug_string` call |
+ | `applyToChildren` / `applyToParents` | the same code but `ldr x1, [plane, #0x20]` (childKey) or `#0x18` (parentKey) |
+
+ `setName(const OSSymbol *)` had carried an extraction placeholder
+ (`_IOFreeDataSharable`, an unused KPI name of the 26.1 kernel) that no 18.x
+ symbol set lists; with the real names every donor import is a name the base's
+ own `com.apple.kpi.iokit` lists, and the symbol sets stay as Apple built them.
+ One import had been bound wrongly in every 18.x map: the donor's
+ `AppleEmbeddedHIDEventService::dispatchBiometricEvent` went to the base's
+ `IOHIDEventService` version (15 vtable slots in AppleEmbeddedLightSensor and
+ AppleSPU); in 18.7.2 the two are instruction-identical, and the recipes bind it
+ to the base's own `AppleEmbeddedHIDEventService` override.
+ 18.5 to 18.7.2 take 18 donor kexts (the 16 of the 26.x recipes plus
+ IISAudioIsolatedStreamECProxy and ExclavesAudioKext, which the 26.1
+ AppleARMIISAudio needs); 18.1 to 18.3.1 take 15, without those three: 18.1
+ lacks the tightbeam API they import, and its addresses in 18.2.1 and 18.3.1
+ are not mapped reliably.
+
+ The 18.x kernels are kernel-first. On macOS 26.4 and later the mix is linked
+ on another Mac or macOS VM with an older kmutil over ssh (`VPHONE_KMUTIL_SSH`,
+ `RemoteKernelCollectionBuilder`): the staged volume goes into a fresh
+ directory of the remote `/private/var/tmp`, at a path as long as the base's
+ build root, root links it there, and the result comes back. Linked with the
+ kmutil of macOS 15.6.1, the 18.7.2 mix differs from the research build that
+ booted only in the 15 rebound pointers and the symbol sets that build had
+ extended.
+
+ ### The iPhone XS Max guest
+
+ `VPhoneGuestDevice.iPhone11_6` (1242x2688 at 458 ppi, scale 3; iPhone11,4
+ maps onto it) keeps the iPhone17,3 presentation of the converted tree, with
+ two changes its userland needs. Its asset catalogs only carry 2436 and 2688
+ artwork and its SpringBoard has no Dynamic Island, so
+ `devicetree-cfw-artwork_device_subtype` writes 2688 and
+ `devicetree-cfw-island_notch_location` removes `island-notch-location`
+ instead of setting it; without them Hello and the wallpaper stay empty and the
+ home gesture breaks.
+
+ ### Restore image
+
+ | Patch | Target | Change |
+ | --- | --- | --- |
+ | `filesystem-boot-ios18_surface_compression` | the image's `/private/var/preferences/.GlobalPreferences.plist`, iOS 18 only | `CAEnableIOSurfaceCompression`, `CAEnableFramebufferCompression` and `CAEnableDeepFramebuffer` = false. iOS 18's AppleParavirtIOSurface maps only address format 0 and rejects the compressed surfaces CoreAnimation asks for ("invalid address format (3)"); backboardd retries its framebuffer allocation forever and the screen stays black. A backboardd restart comes up without the keys too; only a reboot shows the fix. |
+
+ The GPU driver is the cloudOS's own, as for 26.x: 26.x drivers do not load on
+ iOS 18 (`_OBJC_IVAR_$_IOGPUMetalHeap._device` is missing). cloudOS 18.7.2
+ ships the 18.7 driver, so a driver now has to be of the cloudOS's release
+ (major and minor version), not its exact version. The compiler plugin is the
+ bundle's own, as for every guest.
+
+ Touch: iOS 18 guests take every touch through vphoned; a touch that starts at
+ an edge carries the digitizer edge flags (the edge swipe fix), so SpringBoard's
+ home gesture works there too.
+
+ Checked on 2026-10-21: `vm create --device iPhone11,6` with the XS family's
+ 18.7.2 (22H124) IPSW and cloudOS 18.7.2 (22H43) recovered the GPU driver in a
+ temporary cloudOS restore, linked the mix over ssh with the kmutil of macOS
+ 15.6.1, restored, booted, and vphoned answered. Setup's Hello screen and the
+ lock screen show their artwork, the bottom-edge swipe unlocks, and from
+ Settings it returns to the home screen. 18.1 (22B83) on cloudOS 18.1, the
+ oldest base and one of the three with 15 donor kexts, and 18.5 (22F76) on
+ cloudOS 18.5 passed the same checks. The other four recipes resolve every
+ donor import but have not been booted yet.
diff --cc VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
index 38747a3e,8275d6c8..abf2b4de
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
@@@ -227,8 -224,8 +234,9 @@@ public enum FirmwarePatchSetCatalog
/// plain-arm64 HD cannot load it), debugserver, the environment hooks, and
/// the iPhone 19 ARM64E_X1 boot path.
public static let tvOSBlockedPatches: Set<String> = [
+ paravirtTask3Patch,
FirmwareGuestSystemPatchSet.arm64eX1CacheBootstrap,
+ FirmwareGuestSystemPatchSet.virtualBluetooth,
"dyld-boot-iomfb_force_kern",
"dyld-boot-iomfb_swapend",
"dyld-boot-lockdown_mode",
diff --cc VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift
index f04f9cb0,5f2b421b..d03d608c
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift
@@@ -12,11 -12,9 +12,12 @@@ struct VPhoneFirmwareCommand: ParsableC
subcommands: [
VPhoneFirmwareCatalogCommand.self,
VPhoneFirmwareInspectCommand.self,
+ VPhoneFirmwareOTAStageCommand.self,
+ VPhoneFirmwareOTAPreflightCommand.self,
+ VPhoneFirmwareOTACommand.self,
VPhoneFirmwarePrepareCommand.self,
VPhoneFirmwarePatchCommand.self,
+ VPhoneFirmwareKernelcacheCommand.self,
VPhoneFirmwarePatchesCommand.self,
VPhoneFirmwareSetPatchesCommand.self,
VPhoneFirmwareManifestCommand.self,
diff --cc VPhoneLaunchpad/Configuration/Version.xcconfig
index 303cd3f7,47463f40..1add1472
--- a/VPhoneLaunchpad/Configuration/Version.xcconfig
+++ b/VPhoneLaunchpad/Configuration/Version.xcconfig
@@@ -1,4 -1,4 +1,4 @@@
- MARKETING_VERSION = 2.11.0
-MARKETING_VERSION = 2.10.1
++MARKETING_VERSION = 2.12.0
// Bump whenever the helper changes. The app blesses the helper again when the
// installed helper's version or bytes differ from the copy it embeds.
- CURRENT_PROJECT_VERSION = 18
-CURRENT_PROJECT_VERSION = 19
++CURRENT_PROJECT_VERSION = 20