Run a virtual iPhone on an Apple Silicon Mac.
Swift
Keep the Lock Screen lit while Auto-Lock is Never
Jacky44032381d227
diff --git a/Research/Guest/lock_screen_idle_timer.md b/Research/Guest/lock_screen_idle_timer.mdnew file mode 100644index 00000000..2bc0b11a--- /dev/null+++ b/Research/Guest/lock_screen_idle_timer.md@@ -0,0 +1,138 @@+# Auto-Lock "Never" and the Lock Screen++A guest with Settings › Display & Brightness › Auto-Lock set to Never still+went dark by itself. vphoned's `GuestLockScreenIdle`+(`VPhoneDaemon/Daemon/GuestLockScreenIdle.swift`) and its `display.auto_lock`+method rest on the measurements below, taken on 2026-10-03 against+`nettest-01` (iOS 27.0, 24A435) and `locktest-ipad` (iPadOS 26.6.2, 23G90)+over `vphone.sock` with `settings.get/set/delete`, `system.respring`,+`device.snapshot` (`lock.locked`, `lock.screen_off`) and `logs.syslog`+filtered to SpringBoard's `IdleTimer` category.++## What goes dark++The setting was in effect. On `ipad-mini-01`, `ipad-pro-13` (iPadOS 26.6.2)+and `nettest-01`,+`/var/mobile/Library/UserConfigurationProfiles/EffectiveUserSettings.plist`+held `restrictedValue.maxInactivity.value = 2147483647`, and SpringBoard logged,+for the Home Screen and for a foreground app:++```+dsc … <mode: Auto; …> reason:MCFeatureAutoLockTime (2.14748e+09) is gt MAX (3600)+-> dsc … <mode: Disabled; …> reason:after setup, shouldWarn is NO and expireInterval is <never>+```++An unlocked guest left alone stayed lit: 21 minutes on `ipad-mini-01`, 9 on+`nettest-01`, with no backlight or lock line in SpringBoard or backboardd.++The Lock Screen is the part that does not follow the setting.+`SBDashBoardIdleTimerProvider` asks for `duration: Default`, and the same+factory answers six seconds whatever Auto-Lock says:++```+idleTimerDescriptorForBehavior: <SBIdleTimerBehavior: …; duration: Default; mode: Inherit; warnMode: Inherit>+dsc … reason:MCFeatureAutoLockTime (2.14748e+09) is gt MAX (3600)+dsc … <…; total: 6.0s> reason:duration is Default+applying updated idle timer descriptor: <SBIdleTimerDescriptor: …; mode: Inherit; …; total: 6.0s> reason:SBDashBoardScreenOff+```++Waking a guest to the Lock Screen and leaving it, `lock.screen_off` turned+true 8 seconds later on `nettest-01` and 7 on `locktest-ipad`. A guest lands+on the Lock Screen after every boot, every SpringBoard restart+(`system.respring`, `setup.skip`, a crash) and every press of the side button,+and nobody is holding it. So it boots, shows the Lock Screen and is black a+few seconds later, which reads as the device going to standby on its own.++Nothing on the host does this. `vphone-vm` sends the power key only from the+Device menu, the Controls panel and the automation socket's `key` request.++## `SBMinimumLockscreenIdleTime`++SpringBoard reads `SBMinimumLockscreenIdleTime` from `com.apple.springboard`+(user mobile) and, when it is set, uses it in place of the six seconds:++```+dsc … <…; total: 6.0s> reason:duration is Default+dsc … <…; total: 2147483647.0s> reason:totalInterval (6) is gte 0+applying updated idle timer descriptor: <…; mode: Inherit; …; total: 2147483647.0s> reason:SBDashBoardScreenOff+```++Each row sets the key, then wakes the guest to the Lock Screen and reads the+descriptor SpringBoard applies.++| Change | Lock Screen timeout |+| --- | --- |+| key absent | 6 s |+| 600, then SpringBoard restarted | 600 s; lit after 40 s |+| 7200, then SpringBoard restarted | 7200 s |+| 2147483647, then SpringBoard restarted | 2147483647 s |+| the same value written again, no restart | unchanged |+| set while absent, no restart (integer or float) | 6 s |+| a different value while set, no restart | 6 s, until SpringBoard restarts |+| removed, no restart | 6 s |++The table is `nettest-01`. On `locktest-ipad` the absent, 2147483647 and+removed rows gave the same results (6 s and off after 7; lit after 45 s; off+after 7).++SpringBoard takes the value when it starts. A later change is not picked up,+and a change of an existing value drops the override for the rest of that+SpringBoard's life. Writing the value it already has is harmless.++The unlocked timeout is not affected: with the key at 2147483647 and+Auto-Lock at 30 seconds, the Home Screen went dark after 32 seconds.++## What vphoned does++`GuestLockScreenIdle` mirrors Auto-Lock into that key:++- Auto-Lock is Never and the key is not 2147483647: write 2147483647.+- Auto-Lock is anything else and the key is 2147483647: remove it. Any other+ value is someone else's and stays.++It runs first thing when vphoned starts, before the rest of startup, and again+on `com.apple.managedconfiguration.effectivesettingschanged`, the Darwin+notification profiled posts after rewriting `EffectiveUserSettings.plist`.++Settings does not commit Auto-Lock when a row is tapped. The file kept the old+value for 75 seconds with the new row checked, and changed within two seconds+of leaving Settings; vphoned's log line followed in the same two seconds.++Because SpringBoard reads the key once:++- A guest whose key is already in place boots to a Lock Screen that stays lit.+- Turning Never on in Settings writes the key once Settings commits, and it+ holds from the next SpringBoard start (reboot or `system.respring`).+- Turning Never off removes the key, and the Lock Screen is back to six+ seconds immediately.++Measured with the vphoned of this change, on both guests:++| Step | Result |+| --- | --- |+| Auto-Lock Never, key absent, guest started; the host replaces vphoned over HTTP about six seconds after boot | key written at startup; the Lock Screen of that same boot uses 2147483647 s and is lit after 40 s |+| Auto-Lock to 2 minutes (`locktest-ipad`) | key removed; Lock Screen off after 7 s |+| Auto-Lock back to Never, then `system.respring` (`locktest-ipad`) | key written; Lock Screen lit after 60 s |++The first row means vphoned's write beats SpringBoard's read on a normal boot+even when vphoned is first replaced by the host. That is an observation on+these two guests, not a guarantee.++`display.auto_lock` reports `{auto_lock_seconds, never,+lock_screen_minimum_seconds}`; capability `display_auto_lock`.++The side button still turns the screen off; that is a request, not a timeout.++## Reproducing++```sh+vphone-launchpad-cli guest rpc <vm> display.auto_lock+vphone-launchpad-cli guest send <vm> '{"t":"key","name":"power","screen":false}' # screen off+vphone-launchpad-cli guest send <vm> '{"t":"key","name":"power","screen":false}' # Lock Screen+# after 10 s and again after a minute:+vphone-launchpad-cli guest rpc <vm> device.snapshot # lock.screen_off+vphone-launchpad-cli guest rpc <vm> logs.syslog '{"seconds":6,"process":"SpringBoard","max_lines":5000}'+```++The `IdleTimer` line `applying updated idle timer descriptor` carries the+`total` SpringBoard uses.diff --git a/Research/README.md b/Research/README.mdindex 860b6ff3..8e898813 100644--- a/Research/README.md+++ b/Research/README.md@@ -20,7 +20,7 @@ This directory keeps the evidence behind firmware patches, restore and the self-| Other patches and captures | [Launchd jetsam](Patches/cfw_patch_launchd_jetsam.md), [user-mode hypervisor references](Patches/hv_vmm_present_usermode_xrefs.md), [reference capture](Patches/patch_reference_capture.md) || Restore | [DFU probe](Restore/virtual_dfu_probe.md), [in-process restore](Restore/native_restore_architecture.md) || Host and archives | [Binary split](Host/host_binary_split.md), [runtime dependency tiers](Host/runtime_dependency_tiers.md), [archive extraction contracts](Host/archive_extraction_contracts.md), [libarchive validation](Host/libarchive_xcframework_validation.md) |-| Guest interaction and VM identity | [DevMode XPC](Guest/devmode_xpc_protocol.md), [keyboard events](Guest/keyboard_event_pipeline.md), [machine identifier](Guest/machine_identifier_storage_analysis.md), [RootHide bootstrap base](Guest/roothide_bootstrap_base.md), [the Mac's .local name](Guest/mac_name_resolution.md) |+| Guest interaction and VM identity | [DevMode XPC](Guest/devmode_xpc_protocol.md), [keyboard events](Guest/keyboard_event_pipeline.md), [machine identifier](Guest/machine_identifier_storage_analysis.md), [Auto-Lock on the Lock Screen](Guest/lock_screen_idle_timer.md), [RootHide bootstrap base](Guest/roothide_bootstrap_base.md), [the Mac's .local name](Guest/mac_name_resolution.md) || Historical project records | [Migration ledger](History/intg_update_status.md), [manifest refactoring summary](History/manifest_and_refactoring_summary.md) |`KernelSymbols/` holds symbol datasets and indexes; `Reference/` holds source references when present. They are evidence inputs, not steps for running the distributed app. The files in `History/` are preserved snapshots and may describe scripts or variants that have since been removed.diff --git a/Research/vphoned_http_api.md b/Research/vphoned_http_api.mdindex b7f06c1d..e1f529d7 100644--- a/Research/vphoned_http_api.md+++ b/Research/vphoned_http_api.md@@ -270,7 +270,7 @@ request carries `"force": true`.| Area | Methods || --- | --- || Device | `device.snapshot`, `device.info` (snapshot plus network, screen, rotation, brightness, volume, low power, Developer Mode, agent), `device.screen`, `device.network`, `device.ioreg {plane}`, `device.environment`, `device.basebin {archive?}` |-| Display, audio | `display.brightness {value?}`, `display.rotation {orientation?}`, `display.orientation` (`{degrees, source}`: SpringBoard's interface orientation without a screen capture, for polling; capability `display_orientation`), `display.rotation_lock {locked}`, `audio.volume {value?, category?}`, `audio.state` |+| Display, audio | `display.brightness {value?}`, `display.rotation {orientation?}`, `display.orientation` (`{degrees, source}`: SpringBoard's interface orientation without a screen capture, for polling; capability `display_orientation`), `display.rotation_lock {locked}`, `display.auto_lock` (`{auto_lock_seconds, never, lock_screen_minimum_seconds}`: Auto-Lock and the Lock Screen timeout vphoned keeps in step with it, see below; capability `display_auto_lock`), `audio.volume {value?, category?}`, `audio.state` || Input | `input.touch`, `input.hid`, `input.button {name}`, `input.key {name}`, `input.type {text, delay_ms?}`, `input.paste {text}`, `input.tap`, `input.double_tap`, `input.long_press`, `input.swipe`, `input.drag {points}`, `input.touch_sequence {events}` — gesture coordinates are screen points || UI | `ui.tree` (alias `accessibility.tree`), `ui.element_at`, `ui.tap_element`, `ui.wait`, `ui.wait_gone`, `ui.ocr {languages?, min_confidence?}`, `ui.describe`, `screen.screenshot` || Processes | `processes.list {filter?}`, `processes.kill {pid, signal?}` **force**, `memory.jetsam`, `memory.pressure` (only the three kernel memory sysctls, for polling) |@@ -289,6 +289,16 @@ request carries `"force": true`.| Profile UDID | `udid.get`, `udid.set {udid}`, `udid.clear` — each returns `{udid, path}`, the UDID the guest gives its profile checks and the host (null: the guest's own) and the settings file it came from; `set` and `clear` also return `restarted_pids`, `usb_serial` and `usb_reenumerated` (see below) || Setup Assistant | `setup.status` (`{pending, running, pid, setup_done, setup_version, current_version}`), `setup.skip` **force** (sets `SetupDone`, `SetupFinishedAllSteps` and `SetupVersion` in `com.apple.purplebuddy`, restarts SpringBoard, returns the status plus `respring`); `/v1/health` carries `setup_pending` — see `Research/Guest/setup_assistant_skip.md` |+`display.auto_lock` reads Settings' Auto-Lock (`maxInactivity` in profiled's+`EffectiveUserSettings.plist`) and SpringBoard's `SBMinimumLockscreenIdleTime`.+SpringBoard honors Auto-Lock only while unlocked; on the Lock Screen it turns+the screen off after six seconds unless that key says otherwise. vphoned keeps+the key at "never" while Auto-Lock is Never and removes it when Auto-Lock is+anything else (`VPhoneDaemon/Daemon/GuestLockScreenIdle.swift`), at startup+and whenever the settings change. SpringBoard reads the key when it starts, so+a newly written one holds from the next boot or respring. Measurements:+`Research/Guest/lock_screen_idle_timer.md`.+`network.static_names.set` replaces the names the guest resolves locally, givenas `entries: [{address, names}]` (IPv4 only; an empty list withdraws them).vphoned registers each name as a LocalOnly, known-unique A record with the@@ -312,7 +322,7 @@ Account passwords, boot logo rendering and package installation, removal andrepository changes are deliberately not exposed. `/v1/health` lists the newareas in `capabilities` (`device_info`, `display`, `audio`, `input_gestures`,`ui_inspection`, `processes`, `services`, `logs`, `network_capture`,-`app_details`, `system_control`, `file_tools`, `packages`, `environment_update`, `udid_override`, `setup_skip`, `network_static_names`, `network_resolve`) so a host can hide+`app_details`, `system_control`, `file_tools`, `packages`, `environment_update`, `udid_override`, `setup_skip`, `network_static_names`, `network_resolve`, `display_auto_lock`) so a host can hidepanels an older agent cannot serve. icli failures reach the caller withicli's own error `code` (`failed`, `unavailable`, `device_locked`, …) andmessage.diff --git a/Skills/vphone-guest-control/references/rpc-methods.md b/Skills/vphone-guest-control/references/rpc-methods.mdindex d73885af..1673ce99 100644--- a/Skills/vphone-guest-control/references/rpc-methods.md+++ b/Skills/vphone-guest-control/references/rpc-methods.md@@ -52,6 +52,7 @@ invalid-request error, read the source named there instead of guessing keys.| `screen.screenshot` | none | Base64 JPEG with `mime_type`, `width`, `height` (1290×2796) || `display.brightness`, `audio.volume` | `value?` | Omit `value` to read || `display.rotation`, `display.orientation` | `orientation?` | |+| `display.auto_lock` | none | Auto-Lock in seconds (`never` when it is Never) and the Lock Screen timeout vphoned sets to match || `device.ioreg` | `plane` | e.g. `IODeviceTree` |## Inputdiff --git a/VPhoneDaemon/Daemon/GuestAPI+Device.swift b/VPhoneDaemon/Daemon/GuestAPI+Device.swiftindex 6ae70e6d..572e0382 100644--- a/VPhoneDaemon/Daemon/GuestAPI+Device.swift+++ b/VPhoneDaemon/Daemon/GuestAPI+Device.swift@@ -60,6 +60,8 @@ extension GuestAPI {throw GuestAPIError.invalidRequest("locked must be true or false")}return try setRotationLock(locked)+ case "display.auto_lock":+ return GuestLockScreenIdle.describe()case "audio.volume":let category = optionalString(params, "category") ?? "Audio/Video"if params["value"] != nil {diff --git a/VPhoneDaemon/Daemon/GuestAPI.swift b/VPhoneDaemon/Daemon/GuestAPI.swiftindex 2def68eb..22399e74 100644--- a/VPhoneDaemon/Daemon/GuestAPI.swift+++ b/VPhoneDaemon/Daemon/GuestAPI.swift@@ -82,6 +82,7 @@ enum GuestAPI {"device_info","display","display_orientation",+ "display_auto_lock","audio","input_gestures","ui_inspection",diff --git a/VPhoneDaemon/Daemon/GuestLockScreenIdle.swift b/VPhoneDaemon/Daemon/GuestLockScreenIdle.swiftnew file mode 100644index 00000000..05cb81d9--- /dev/null+++ b/VPhoneDaemon/Daemon/GuestLockScreenIdle.swift@@ -0,0 +1,94 @@+import Foundation+import IcliKit+import notify++/// Makes Auto-Lock "Never" hold on the Lock Screen too.+///+/// Settings › Display & Brightness › Auto-Lock sets `maxInactivity`, and+/// SpringBoard applies it only while the device is unlocked. On the Lock+/// Screen it uses its own six seconds whatever the setting says, so a guest+/// that has just booted, or whose SpringBoard has just restarted, goes dark+/// before anyone looks at it.+///+/// SpringBoard reads one more value there, `SBMinimumLockscreenIdleTime` in+/// `com.apple.springboard`, and replaces the six seconds with it. vphoned+/// keeps that key at the same "never" while Auto-Lock is Never, and removes+/// it again when Auto-Lock is anything else. A value some other tool put+/// there is left alone.+///+/// SpringBoard takes the key when it starts. Setting it later does nothing+/// until SpringBoard restarts, and changing or removing it puts the six+/// seconds back at once. So this runs before anything else at startup, to be+/// ahead of SpringBoard on a boot where the key is missing.+///+/// Measured on iOS 27.0 and iPadOS 26.6.2; see+/// Research/Guest/lock_screen_idle_timer.md.+enum GuestLockScreenIdle {+ /// profiled's merged settings for user mobile. It rewrites the file and+ /// then posts `changedNotification`; ManagedConfiguration's own clients+ /// re-read it on the same signal.+ private static let settingsPath = "/var/mobile/Library/UserConfigurationProfiles/EffectiveUserSettings.plist"+ private static let changedNotification = "com.apple.managedconfiguration.effectivesettingschanged"+ private static let domain = "com.apple.springboard"+ private static let key = "SBMinimumLockscreenIdleTime"+ /// What Settings stores for "Never", in seconds.+ private static let never = Int(Int32.max)+ private static let queue = DispatchQueue(label: "vphoned.lock-screen-idle", qos: .utility)++ static func startOnStartup() {+ queue.sync { apply(reason: "startup") }+ var token: Int32 = 0+ let status = notify_register_dispatch(changedNotification, &token, queue) { _ in+ apply(reason: "settings changed")+ }+ if status != 0 {+ NSLog("vphoned: lock screen idle: cannot observe Auto-Lock changes (notify status %u)", status)+ }+ }++ /// Auto-Lock in seconds, `never` for Never, nil when profiled has not+ /// written its settings yet.+ static func autoLockSeconds() -> Int? {+ guard let data = FileManager.default.contents(atPath: settingsPath),+ let plist = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any],+ let values = plist["restrictedValue"] as? [String: Any],+ let setting = values["maxInactivity"] as? [String: Any]+ else { return nil }+ return (setting["value"] as? NSNumber)?.intValue+ }++ static func lockScreenMinimum() -> Int? {+ let value = CFPreferencesCopyValue(key as CFString, domain as CFString, "mobile" as CFString, kCFPreferencesAnyHost)+ return (value as? NSNumber)?.intValue+ }++ static func describe() -> [String: Any] {+ let autoLock = autoLockSeconds()+ let minimum = lockScreenMinimum()+ return [+ "auto_lock_seconds": autoLock.map { $0 as Any } ?? NSNull(),+ "never": autoLock.map { $0 >= never } ?? false,+ "lock_screen_minimum_seconds": minimum.map { $0 as Any } ?? NSNull(),+ ]+ }++ private static func apply(reason: String) {+ guard let autoLock = autoLockSeconds() else {+ NSLog("vphoned: lock screen idle (%@): Auto-Lock is not readable, nothing changed", reason)+ return+ }+ let minimum = lockScreenMinimum()+ do {+ if autoLock >= never {+ guard minimum != never else { return }+ _ = try writePreference(domain: domain, key: key, value: .int(Int64(never)))+ NSLog("vphoned: lock screen idle (%@): Auto-Lock is Never, Lock Screen follows from the next SpringBoard start", reason)+ } else if minimum == never {+ _ = try deletePreference(domain: domain, key: key)+ NSLog("vphoned: lock screen idle (%@): Auto-Lock is %d s, Lock Screen is back to its own timeout", reason, autoLock)+ }+ } catch {+ NSLog("vphoned: lock screen idle (%@): %@", reason, String(describing: error))+ }+ }+}diff --git a/VPhoneDaemon/Daemon/main.swift b/VPhoneDaemon/Daemon/main.swiftindex db98c05a..c5002df5 100644--- a/VPhoneDaemon/Daemon/main.swift+++ b/VPhoneDaemon/Daemon/main.swift@@ -13,6 +13,8 @@ if mode != 1 {}guard vp_native_watch_proxy() == 0 else { exit(1) }+// First, so the Lock Screen timeout is in place before SpringBoard reads it.+GuestLockScreenIdle.startOnStartup()vp_vcam_start()// Multi-finger injection is resolved here so the first pinch is not the call// that pays for `dlopen`; a base without the symbols logs and stays a no-op.