Run a virtual iPhone on an Apple Silicon Mac.
Swift
Wake and unlock a guest with screen.unlock
Jackyaa985d5ce507
diff --git a/Documents/Guides/launchpad-cli.md b/Documents/Guides/launchpad-cli.mdindex 0fb46627..0b30134c 100644--- a/Documents/Guides/launchpad-cli.md+++ b/Documents/Guides/launchpad-cli.md@@ -114,6 +114,7 @@ version while a machine is bound to it; rebind or delete those machines first.| `cfw update-environment <name>` | Redeploy the machine's own bundle's guest resources (vphoned, hook dylibs) into it while stopped, through the helper; nothing else changes || `guest send <name> <json>` | One raw `vphone.sock` request (tap, swipe, key, screenshot) || `guest rpc <name> <method> [params]` | Any vphoned method, see `Research/vphoned_http_api.md` |+| `guest unlock <name> [--passcode <code>] [--timeout <seconds>]` | Turn the screen on and unlock the guest, whatever state it was in (vphoned `screen.unlock`). `--passcode` is needed only when the guest has one || `exec [--bundle <version>] <vphone-cli arguments>` | Run the default bundle's `vphone-cli`, or that version's, streaming its output. `--bundle` must come first |Machine commands take `--root <library>` when two libraries hold a machinediff --git a/Research/Guest/screen_unlock.md b/Research/Guest/screen_unlock.mdnew file mode 100644index 00000000..e9b4d4ac--- /dev/null+++ b/Research/Guest/screen_unlock.md@@ -0,0 +1,105 @@+# Turning the screen on and unlocking++vphoned's `screen.unlock` (`VPhoneDaemon/Daemon/GuestScreenUnlock.swift`,+`VPhoneDaemon/Native/vphoned_unlock.m`) and `vphone-launchpad-cli guest unlock`.+Measured on 2026-10-04 against `unlocktest-iphone` (iPhone17,3, iOS 27.0+24A435, no passcode), with the 26.6.2 dyld shared cache for the static read.++## Why a method++A guest is at the Lock Screen after every boot, every SpringBoard restart and+every press of the side button, and it is dark a few seconds later+(`lock_screen_idle_timer.md`). A locked or dark screen swallows taps, and+`apps.launch` answers `device_locked`.++The hardware keys only toggle. `power` wakes a dark guest and darkens a lit+one; `home` wakes, and on a lit Lock Screen without a passcode it dismisses to+the Home Screen. A script has to read `device.screen` first and choose. The+method does that reading and does only what each state needs.++## What SpringBoard's own unlock request does, and why it is not used++SpringBoardServices has `-[SBSLockScreenService+requestPasscodeUnlockUIWithOptions:withCompletion:]` (`0x191f505c8` in the+26.6.2 cache), the request an app makes when it needs an unlocked device.+Served to a caller with `com.apple.springboard.requestDeviceUnlock` (the+authenticator in `-[SBLockScreenService init]` is built with that entitlement+string, at `0x224be0ae4`).++Granting vphoned that entitlement and calling the request was tried first. The+guest log shows why it does not unlock a passcode-free device:++```+unlockUIFromSource:ExternalRequest options:({SBUIUnlockOptionsTurnOnScreenFirstKey: 1}) screenWasOff:YES+Bailing from UIUnlock because: turnOnScreenFirst = 1; autoUnlock = 0; shouldTurnOnScreen = 1+```++Asked while the screen is off, SpringBoard treats the request as *turn the+screen on first*: it lights the backlight and bails out of the unlock+(`autoUnlock = 0`), leaving the Lock Screen up. A second request, with the+screen now on, did not dismiss it either. The request is the wrong tool for a+passcode-free guest, and it needs a private entitlement. Both were dropped.++## What `screen.unlock` does++1. Reads `com.apple.springboard.lockstate` and+ `com.apple.springboard.hasBlankedScreen` (IcliKit's `lockState()`). Until+ `com.apple.springboard.finishedstartup` is non-zero these read+ "unlocked, lit" no matter what will show, so at startup it waits for that+ notification before trusting them.+2. Not locked, only dark: `SBSUndimScreen`, and done. This lights the display+ with no toggle and needs no entitlement (it is what icli's `wake` calls).+3. Locked: if dark, `SBSUndimScreen` first so the next step lands on a live+ Lock Screen. Then press Home.+ - No passcode: Home dismisses the Lock Screen. Repeated until unlocked or+ the deadline, in case the first press landed while the display was still+ coming up.+ - Passcode: Home raises the passcode pad; `passcode` is typed (digits as+ keyboard number keys `0x1E`–`0x27`, anything else as text), with Return+ if the pad has not submitted after a second.+4. Polls the two notify states every 100 ms until lit and (if it was locked)+ unlocked, or `timeout` (10 s by default, 1–60) runs out.++Result: `{locked, screen_off, was_locked, was_screen_off}`; capability+`screen_unlock`. No private entitlement.++## Live results (no-passcode guest)++All on `unlocktest-iphone`, each followed by `device.screen` and+`apps.foreground`:++| State before | `guest unlock` | After |+| --- | --- | --- |+| just booted, dark Lock Screen | ok, `was_screen_off:true was_locked:true` | Home Screen, lit |+| lit, unlocked | ok, all `false` | unchanged |+| `power` → dark + locked | ok | Home Screen, lit |+| same, repeated | ok | Home Screen, lit |+| lit Lock Screen (`was_screen_off:false`) | ok | unlocked; `apps.launch` Settings then `frontmost_verified:true` |+| after `system.respring` → Lock Screen | ok | Home Screen, lit |++So the device is actually usable afterwards, not merely reporting unlocked.++## Not yet measured++- **Passcode guests.** Setting a passcode on a research guest is not+ automated, so the Home-raises-the-pad-then-type path is unrun. It is written+ to the behavior of a real device (Home/menu raises passcode entry); treat it+ as untested until a passcode guest is available.+- iPadOS, and iOS 27.0.1 (its guests kernel-panic at first boot, separate+ issue).++## Reproducing++```sh+vphone-launchpad-cli guest send <vm> '{"t":"key","name":"power","screen":false}' # dark + locked+vphone-launchpad-cli guest rpc <vm> device.screen # locked, screen_off+vphone-launchpad-cli guest unlock <vm>+vphone-launchpad-cli guest rpc <vm> device.screen+vphone-launchpad-cli guest rpc <vm> apps.foreground+```++The `Bailing from UIUnlock` evidence, if the request path is revisited:++```sh+vphone-launchpad-cli guest rpc <vm> logs.syslog '{"seconds":8,"process":"SpringBoard","max_lines":5000}'+```diff --git a/Research/vphoned_http_api.md b/Research/vphoned_http_api.mdindex 92566d45..f3eee25f 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}`, `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` |+| 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`), `screen.unlock {passcode?, timeout?}` (`{locked, screen_off, was_locked, was_screen_off}`: the display on and the Lock Screen passed, see below; capability `screen_unlock`), `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) |@@ -299,6 +299,16 @@ and whenever the settings change. SpringBoard reads the key when it starts, soa newly written one holds from the next boot or respring. Measurements:`Research/Guest/lock_screen_idle_timer.md`.+`screen.unlock` reads the lock state, then turns the display on with+`SBSUndimScreen` (no toggle, unlike a power press) and presses Home to dismiss+the Lock Screen: a passcode-free guest goes to the Home Screen, a guest with a+passcode gets the passcode pad, into which `passcode` is typed+(`VPhoneDaemon/Daemon/GuestScreenUnlock.swift`). A lit, unlocked guest returns+at once; a dark but unlocked one is only woken. A guest with a passcode needs+`passcode`, entered once and never retried; without it the call fails before+any key is sent. It needs no private entitlement. `timeout` is 1–60 seconds,+10 by default. Measurements: `Research/Guest/screen_unlock.md`.+`network.ipv4.get` and `network.ipv4.set` read and write the IPv4 settings ofone interface (default `en0`) in configd's network preferences,`/var/preferences/SystemConfiguration/preferences.plist`, through SCPreferences@@ -345,7 +355,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_ipv4`, `network_hostname`, `network_static_names`, `network_resolve`, `display_auto_lock`) so a host can hide+`app_details`, `system_control`, `file_tools`, `packages`, `environment_update`, `udid_override`, `setup_skip`, `network_ipv4`, `network_hostname`, `network_static_names`, `network_resolve`, `display_auto_lock`, `screen_unlock`) 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/guest-socket.md b/Skills/vphone-guest-control/references/guest-socket.mdindex 83f6607e..d8631319 100644--- a/Skills/vphone-guest-control/references/guest-socket.md+++ b/Skills/vphone-guest-control/references/guest-socket.md@@ -74,7 +74,9 @@ paste for long or non-ASCII text.## Patterns that work-- **Wake and unlock check:** `ping`, then `screenshot` to a file and look at it.+- **Wake and unlock:** `vphone-launchpad-cli guest unlock myphone` (add+ `--passcode` when the guest has one). It works from any state; the keys only+ toggle. Check with `ping`, then `screenshot` to a file and look at it.- **Home:** `{"t":"key","name":"home"}`; **power** wakes or locks.- **Open an app without hunting for its icon:** `apps.launch` with the bundle id.- **Scroll a list:** swipe from lower to upper y, e.g. 2600 → 1400 at x 645.diff --git a/Skills/vphone-guest-control/references/rpc-methods.md b/Skills/vphone-guest-control/references/rpc-methods.mdindex f533b820..86bec2eb 100644--- a/Skills/vphone-guest-control/references/rpc-methods.md+++ b/Skills/vphone-guest-control/references/rpc-methods.md@@ -53,6 +53,7 @@ invalid-request error, read the source named there instead of guessing keys.| `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 |+| `screen.unlock` | `passcode?`, `timeout?` (10) | Display on and Lock Screen passed, from any state; `guest unlock <machine>` calls it. `passcode` only for a guest that has one, entered once || `device.ioreg` | `plane` | e.g. `IODeviceTree` |## Inputdiff --git a/Skills/vphone-guest-control/references/troubleshooting.md b/Skills/vphone-guest-control/references/troubleshooting.mdindex 98d19da9..89c60275 100644--- a/Skills/vphone-guest-control/references/troubleshooting.md+++ b/Skills/vphone-guest-control/references/troubleshooting.md@@ -59,7 +59,8 @@ notes.machine and run `cfw update-environment <name>`.- **`ok` but nothing changed on screen:** inputs are asynchronous; wait for theattached `image` or take a screenshot. A locked or asleep screen swallows- taps: press `power`, then `home`.+ taps: run `guest unlock <name>`, or on an older vphoned press `power`, then+ `home`.- **Taps land in the wrong place:** the socket takes pixels (1290×2796); the`input.*` RPCs take points. Use `ui.tree` / `ui.tap_element` instead.- **Port 22 refused over iproxy:** no sshd yet. Use RPC; see@@ -84,7 +85,8 @@ migration is hung, not that the display is broken.## Apps and the bootstrap-- **"Press home to continue" lock screen:** `{"t":"key","name":"home"}`.+- **"Press home to continue" lock screen:** `guest unlock <name>`, or+ `{"t":"key","name":"home"}`.- **App crashes with `EXC_GUARD` / Mach port guard:** a known kernel-patchscope limit on 26.x bases; see `Documents/Guides/troubleshooting.md`.- **`dyld ... @loader_path/.jbroot/...` crash** after installing a package:diff --git a/VPhoneDaemon/Daemon/GuestAPI+Device.swift b/VPhoneDaemon/Daemon/GuestAPI+Device.swiftindex 3020c2f2..9826bf07 100644--- a/VPhoneDaemon/Daemon/GuestAPI+Device.swift+++ b/VPhoneDaemon/Daemon/GuestAPI+Device.swift@@ -72,6 +72,11 @@ extension GuestAPI {return try setRotationLock(locked)case "display.auto_lock":return GuestLockScreenIdle.describe()+ case "screen.unlock":+ return try GuestScreenUnlock.unlock(+ passcode: optionalString(params, "passcode"),+ timeout: number(params, "timeout", default: 10),+ )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 57a37164..667d6e35 100644--- a/VPhoneDaemon/Daemon/GuestAPI.swift+++ b/VPhoneDaemon/Daemon/GuestAPI.swift@@ -100,6 +100,7 @@ enum GuestAPI {"display","display_orientation","display_auto_lock",+ "screen_unlock","audio","input_gestures","ui_inspection",diff --git a/VPhoneDaemon/Daemon/GuestScreenUnlock.swift b/VPhoneDaemon/Daemon/GuestScreenUnlock.swiftnew file mode 100644index 00000000..d4e99c09--- /dev/null+++ b/VPhoneDaemon/Daemon/GuestScreenUnlock.swift@@ -0,0 +1,166 @@+import Foundation+import IcliKit+import notify+import VphonedNative++/// `screen.unlock`: turn the display on and get past the Lock Screen.+///+/// A guest is at the Lock Screen, dark, after every boot, every SpringBoard+/// restart and every press of the side button, and a locked or dark screen+/// swallows taps and refuses app launches. The hardware keys only toggle, so a+/// script cannot tell what a press will do; this reads the state first and+/// does only what is needed.+///+/// The display comes on through `SBSUndimScreen`, which lights it without the+/// toggle a power press has. The Home button then dismisses the Lock Screen:+/// on a device without a passcode it goes straight to the Home Screen, and on+/// one with a passcode it raises the passcode pad, into which the passcode is+/// typed as keyboard events. SpringBoard's own `requestPasscodeUnlock` request+/// is not used: on a passcode-free device it lights the screen but leaves the+/// Lock Screen up (`autoUnlock = 0`), so it cannot replace the Home press.+///+/// See Research/Guest/screen_unlock.md.+enum GuestScreenUnlock {+ /// Two unlocks at once would press Home and type over each other.+ private static let exclusive = NSLock()+ private static let pollInterval = 0.1+ /// How long SpringBoard takes to raise the passcode pad after Home.+ private static let padDelay = 1.0++ static func unlock(passcode: String?, timeout: Double) throws -> [String: Any] {+ guard timeout.isFinite, (1 ... 60).contains(timeout) else {+ throw GuestAPIError.invalidRequest("timeout must be 1–60 seconds")+ }+ exclusive.lock()+ defer { exclusive.unlock() }++ let deadline = Date().addingTimeInterval(timeout)+ let before = startingState(until: deadline)++ if before.locked {+ let lock = try collectDeviceSnapshot()["lock"] as? [String: Any]+ let hasPasscode = lock?["passcode_enabled"] as? Bool ?? false+ if hasPasscode, passcode == nil {+ throw GuestAPIError.operationFailed("the device has a passcode; pass it as passcode")+ }+ try unlock(hasPasscode: hasPasscode, passcode: passcode, deadline: deadline)+ } else if before.screenOff {+ // Lit screen, already unlocked: just wake it.+ _ = vp_screen_undim()+ }++ guard wait(until: deadline, for: { !$0.screenOff }) else {+ throw GuestAPIError.operationFailed("the display did not turn on within \(Int(timeout)) s")+ }++ let after = state()+ return [+ "locked": after.locked,+ "screen_off": after.screenOff,+ "was_locked": before.locked,+ "was_screen_off": before.screenOff,+ ]+ }++ // MARK: - Lock Screen++ private static func unlock(hasPasscode: Bool, passcode: String?, deadline: Date) throws {+ // Light the screen first so the Home press lands on a live Lock+ // Screen rather than only waking it.+ if state().screenOff {+ _ = vp_screen_undim()+ _ = wait(until: min(Date().addingTimeInterval(1), deadline), for: { !$0.screenOff })+ }++ if hasPasscode, let passcode {+ _ = try pressButton("home")+ try enter(passcode, deadline: deadline)+ guard wait(until: deadline, for: { !$0.locked }) else {+ throw GuestAPIError.operationFailed("the device is still locked; the passcode was not accepted")+ }+ return+ }++ // No passcode: a Home press dismisses the Lock Screen. It is repeated+ // in case the first one landed while the display was still coming up.+ while state().locked {+ guard Date() < deadline else {+ throw GuestAPIError.operationFailed("the Lock Screen did not dismiss in time")+ }+ _ = try pressButton("home")+ _ = wait(until: min(Date().addingTimeInterval(0.6), deadline), for: { !$0.locked })+ }+ }++ /// Types the passcode into the pad Home raised. Digits go as the number+ /// keys of a hardware keyboard, which the numeric pad takes; anything else+ /// as text. A numeric pad submits on its last digit; a custom or+ /// alphanumeric one waits for Return.+ private static func enter(_ passcode: String, deadline: Date) throws {+ Thread.sleep(forTimeInterval: padDelay)+ guard state().locked else { return }+ let digits = passcode.unicodeScalars.map { ("0" ... "9").contains($0) ? Int($0.value) - 0x30 : -1 }+ if digits.allSatisfy({ $0 >= 0 }) {+ for digit in digits {+ // Keyboard page: 1…9 are 0x1E…0x26, 0 is 0x27.+ _ = try hidPress(page: 0x07, usage: digit == 0 ? 0x27 : 0x1D + digit)+ Thread.sleep(forTimeInterval: 0.06)+ }+ } else {+ _ = try typeText(passcode, delayMS: 60)+ }+ let submitted = min(Date().addingTimeInterval(1), deadline)+ if wait(until: submitted, for: { !$0.locked }) {+ return+ }+ _ = try pressKey("return")+ }++ // MARK: - State++ private struct State {+ let locked: Bool+ let screenOff: Bool+ }++ private static func state() -> State {+ let state = lockState()+ return State(+ locked: state["locked"] as? Bool ?? false,+ screenOff: state["screen_off"] as? Bool ?? false,+ )+ }++ /// The state to start from. Until SpringBoard has finished starting, the+ /// two notify states read "unlocked and lit" whatever the screen will+ /// show, so that reading is trusted only once SpringBoard says it is up.+ private static func startingState(until deadline: Date) -> State {+ while true {+ let now = state()+ if now.locked || now.screenOff || springBoardStarted() || Date() >= deadline {+ return now+ }+ Thread.sleep(forTimeInterval: pollInterval)+ }+ }++ /// SpringBoard stores a non-zero state under this name when its startup+ /// is over.+ private static func springBoardStarted() -> Bool {+ var token: Int32 = 0+ guard notify_register_check("com.apple.springboard.finishedstartup", &token) == 0 else { return true }+ defer { notify_cancel(token) }+ var value: UInt64 = 0+ return notify_get_state(token, &value) != 0 || value != 0+ }++ private static func wait(until deadline: Date, for condition: (State) -> Bool) -> Bool {+ while true {+ if condition(state()) {+ return true+ }+ guard Date() < deadline else { return false }+ Thread.sleep(forTimeInterval: pollInterval)+ }+ }+}diff --git a/VPhoneDaemon/Native/Include/VphonedNative.h b/VPhoneDaemon/Native/Include/VphonedNative.hindex 906aec95..ac4510c4 100644--- a/VPhoneDaemon/Native/Include/VphonedNative.h+++ b/VPhoneDaemon/Native/Include/VphonedNative.h@@ -26,6 +26,10 @@ bool vp_hid_load(void);/// `touchSequence` can carry two fingers at once, which is why this exists.void vp_hid_touch2(int phase, double x1, double y1, double x2, double y2);+/// Turn the display on without pressing a button. False when+/// SpringBoardServices has no SBSUndimScreen.+bool vp_screen_undim(void);+typedef struct {int32_t pid;int32_t ppid;diff --git a/VPhoneDaemon/Native/vphoned_unlock.m b/VPhoneDaemon/Native/vphoned_unlock.mnew file mode 100644index 00000000..ba56140a--- /dev/null+++ b/VPhoneDaemon/Native/vphoned_unlock.m@@ -0,0 +1,27 @@+/*+ * vphoned_unlock — turn the guest display on.+ *+ * SpringBoardServices' SBSUndimScreen lights the display without the toggle a+ * power-key press has. It is the same call icli's `wake` uses, and needs no+ * entitlement. Getting past the Lock Screen itself is a Home press, driven+ * from Swift (GuestScreenUnlock).+ *+ * The symbol is resolved at run time, so a base without it still starts and+ * the call reports false instead.+ */++#import "Include/VphonedNative.h"++#include <dlfcn.h>++bool vp_screen_undim(void) {+ static void *handle;+ static dispatch_once_t once;+ dispatch_once(&once, ^{+ handle = dlopen("/System/Library/PrivateFrameworks/SpringBoardServices.framework/SpringBoardServices", RTLD_NOW);+ });+ void (*undim)(void) = handle ? dlsym(handle, "SBSUndimScreen") : NULL;+ if (!undim) return false;+ undim();+ return true;+}diff --git a/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift b/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swiftindex 47b1f276..e8ed17dd 100644--- a/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift+++ b/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift@@ -61,6 +61,7 @@ struct VPhoneLaunchpadControlCommands {case "cfw.update-environment": return try await updateGuestEnvironment(request, emit: emit)case "guest.send": return try await sendToGuest(request)case "guest.rpc": return try await callGuest(request)+ case "guest.unlock": return try await unlockGuest(request)case "exec": return try await exec(request, emit: emit)default: throw VPhoneLaunchpadError("\(command.name) is not handled by this Launchpad.")}@@ -723,6 +724,33 @@ struct VPhoneLaunchpadControlCommands {return try await VPhoneLaunchpadGuestSocket.send(object, socketPath: Self.controlSocket(machine))}+ /// vphoned's `screen.unlock`: the display on and the Lock Screen passed,+ /// whatever state the guest was in.+ private func unlockGuest(_ request: VPhoneLaunchpadControlRequest) async throws -> Any {+ let machine = try await machine(request)+ var params: [String: Any] = [:]+ if let passcode = request.option("passcode") {+ params["passcode"] = passcode+ }+ if let text = request.option("timeout") {+ guard let seconds = Double(text), (1 ... 60).contains(seconds) else {+ throw VPhoneLaunchpadError("--timeout takes 1 to 60 seconds.")+ }+ params["timeout"] = seconds+ }+ let object: [String: Any] = ["t": "rpc", "method": "screen.unlock", "params": params]+ do {+ return try await VPhoneLaunchpadGuestSocket.send(object, socketPath: Self.controlSocket(machine))+ } catch let error as VPhoneLaunchpadError where error.detail?.contains("Unknown method") == true {+ // The guest environment is its own layer; an older vphoned stays+ // in a machine until it is redeployed.+ throw VPhoneLaunchpadError(+ "The vphoned in \(machine.name) cannot unlock the screen.",+ detail: "Its guest environment is older than screen.unlock. Stop the machine and run cfw update-environment with a Core Bundle that has it.",+ )+ }+ }+// MARK: - vphone-cli/// Runs the default bundle's `vphone-cli`, or that of `--bundle`. Adiff --git a/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift b/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swiftindex ee449d68..6aaea4bb 100644--- a/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift+++ b/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift@@ -182,6 +182,8 @@ nonisolated struct VPhoneLaunchpadControlCommand: Sendable {summary: "Send one raw vphone.sock request, such as {\"t\":\"tap\",\"x\":645,\"y\":1398}."),Self(name: "guest.rpc", arguments: ["name", "method", "params..."], options: ["root"], flags: ["screen"],summary: "Call a vphoned method; params is one JSON object."),+ Self(name: "guest.unlock", arguments: ["name"], options: ["root", "passcode", "timeout"], flags: [],+ summary: "Turn the screen on and unlock the guest (vphoned screen.unlock). --passcode enters the passcode of a guest that has one; --timeout is in seconds, 10 by default."),Self(name: "exec", arguments: ["arguments..."], options: ["bundle"], flags: [],summary: "Run vphone-cli with these arguments and stream its output: the default bundle's, or that of --bundle <version> given before the arguments."),