iPhone-use 0.6.1

Precompiled macOS CLI and iOS Runner for Apple Silicon, under the MIT license.

Build

• Version: 0.6.1
• Source commit: 5c2566abd27aaa3dc42d5d7f366bbb0a96881810
• Archive: iphone-use-0.6.1-macos-arm64.tar.gz
• Archive SHA-256: 87910a91e8e523531e15156aa133d0552695a36fa6b6a2d1d58bae382a8175d7
• Automated checks: GitHub Actions (attempt 1)

Changes

• Correct the unfolded iPhone Duo bezel: use wider, dark inset hinge bridges and a small central rim seam at both ends of the fold. Static and folding views share the correction.
• No changes to automation, media transport, CLI commands, Runner behavior or plugin/skill content.

Upgrade and compatibility

Upgrade the CLI through Homebrew or replace the complete manual-install directory. An already-running preview process may still serve the previous frontend; explicitly stop and start that device preview when ready to load the new bundled page, then refresh its existing tab. Active previews are not automatically interrupted by upgrading.

Supported environment and existing limitations are unchanged from 0.6.0. npm/skill distributions remain at their existing independent version because their content did not change.

Automated checks — passed

• Swift, Python, and Node call-template tests.
• Self-contained Codex/Claude Code plugin, matching manifests and source skill, with ZIP and SHA-256.
• Archive integrity, relocated CLI version/help commands and Mac code signature verification.
• Homebrew installation and installed CLI/Runner file digests.

These checks ran on GitHub-hosted machines without a physical iPhone. They did not run device setup, connect to a phone or verify an app task.

Local device acceptance — passed

Maintainer-assisted device acceptance on 2026-11-01, Apple Silicon Mac with macOS 27.0 / Xcode 27.1 (27A9275), physical iPhone Duo on iOS 27.2, using existing Apple development signing.

• Downloaded the exact cloud archive, verified version 0.6.1, source commit 5c2566a and SHA-256 87910a91e8e523531e15156aa133d0552695a36fa6b6a2d1d58bae382a8175d7. Relocated the complete package outside the checkout; CLI signature, linked libraries, version/help and isolated mode preferences passed.
• Replaced the prior 0.6.0 capture/viewer with explicit maintainer permission. Both running executables were checked against the downloaded 0.6.1 package. The original viewer URL was retained and the acceptance page served unmodified candidate HTML.
• Maintainer confirmed fold/unfold automatic recovery, normal hinge motion and the corrected unfolded bezel. Media remained healthy.
• Standard mode connected with HID ready and no Runner, captured the inner display, opened the Probe app and accurately selected its ASCII sample. HID reported an unacknowledged action as designed; the attached screenshot visually confirmed the selected sample. Input was not replayed. Session cleanup passed and independent preview continued.
• Packaged Runner setup completed without compilation, including connection, screenshot capture and cleanup. Repeated setup reused the signed candidate artifact. Explicit Runner connection reported releaseVersion 0.6.1 and used the packaged/re-signed Runner.
• In Notes, created a separate version-labelled acceptance note containing Chinese, emoji and the explicit value 10:15–11:45. Ended editing, relaunched Notes, selected that note again and verified the complete saved text visually and in AX. Existing notes were preserved. Runner shutdown was acknowledged and the process exited; independent preview remained streaming.

Scope and limitations: this is a CSS-only patch. Full all-direction gesture, recording, lock/unlock and long-duration performance matrices were not repeated for 0.6.1. No new claim of stable 30 fps or removal of transient black frames is made. Fresh-Mac/Gatekeeper, Personal Team renewal, Intel and other OS/device combinations were not tested. Public download/Homebrew upgrade validation follows publication. Raw captures, device identifiers and signing details remain local.

Accepted archive SHA-256: 87910a91e8e523531e15156aa133d0552695a36fa6b6a2d1d58bae382a8175d7. Published without rebuilding.

Installation

Download the tar.gz and its .sha256 file together. Installation and iPhone setup instructions are in the package README and repository docs/install.md. The separate iphone-use-plugin ZIP contains Codex/Claude manifests, the DeepSeek Harness bundle, and the complete skill; it does not contain the CLI or signed Runner. Follow docs/plugins.md for each client installation path and docs/first-task.md for the first iPhone task.

Both modes require full Xcode. Standard mode currently requires macOS/iOS 27 and does not need Runner setup or development signing. Optional Runner mode requires your own Apple development certificate, private key and matching provisioning profile; setup re-signs the precompiled Runner locally. Free Personal Team onboarding and renewal are not yet validated. The Mac CLI is ad-hoc signed, without Developer ID signing or notarization.

Maintainer: publish the exact archive accepted locally. After a stable release is published, run the Homebrew Tap's Update iPhone-use workflow with the same version, then verify installation from the public download URL and Tap. Prereleases use manual installation. The attached iphone-use.rb contains the exact versioned download URL and archive checksum.

iPhone-use 0.6.0

Precompiled macOS CLI and iOS Runner for Apple Silicon, under the MIT license.

Build

• Version: 0.6.0
• Source commit: 097929c0d345c617bb44bace2af37b50f71eaf6d
• Archive: iphone-use-0.6.0-macos-arm64.tar.gz
• Archive SHA-256: 900e010585f3cde302a401825160989bba393eb2c63b628440ca412bc07e743a
• Automated checks: GitHub Actions (attempt 1)

Changes

• Add iPhone Duo display selection and matching HID touch-surface binding, Runner screenshot and gesture routing, supported orientation handling, and Duo preview frames with hinge transitions. Preserve legacy single-screen iPhone selection when an inactive wireless display is present.
• Separate live preview and recording capture from automation sessions. Preview can start independently and stays running when automation disconnects or fails. Recover recognized transient media failures after acknowledged cleanup while retaining the preview URL.
• Adapt preview JPEG resolution to the visible browser aperture multiplied by DPR, capped at the received media source size. Resume browser frame requests promptly after validated media recovery.
• Reset safely released recording-only preparation failures so a later explicit recording request can succeed without terminating preview or waiting for capture idle exit. Uncertain starts and unacknowledged cleanup remain blocked; no input or recording is automatically replayed.
• Include updated Runner artwork and plugin/portable-skill workflow 0.3.0.

Upgrade and compatibility

• Breaking behavior: disconnecting automation no longer stops independent preview. Stop it explicitly with preview --device DEVICE_ID --stop when finished.
• Upgrade the CLI and run its setup to install a matching Runner when required. Reconnecting automation does not replace a running older capture process. Deliberately retire old capture only after stopping its preview and recording consumers.
• Preview targets up to 30 fps; stable 30 fps is not guaranteed. Received media can be smaller than panel resolution. Folding can still show seconds of black/unavailable frames. Recording ends its fixed-geometry segment on display/orientation changes; seamless cross-screen recording is not claimed.
• Development acceptance covered Duo standard and Runner gestures across four inner and three outer orientations, plus ordinary iPhone regressions. This is separate from the exact cloud archive acceptance below.

Automated checks — passed

• Swift, Python, and Node call-template tests.
• Self-contained Codex/Claude Code plugin, matching manifests and source skill, with ZIP and SHA-256.
• Archive integrity, relocated CLI version/help commands and Mac code signature verification.
• Homebrew installation and installed CLI/Runner file digests.

These checks ran on GitHub-hosted machines without a physical iPhone. They did not run device setup, connect to a phone or verify an app task.

Local device acceptance — passed

Maintainer-assisted acceptance on 2026-10-31: Apple Silicon Mac, macOS 27.0, Xcode 27.1, wired iPhone Duo / iOS 27.2, existing Apple development signing configuration.

• Downloaded this exact cloud archive, matched source SHA and archive digest, verified signatures and resource hashes, and ran the relocated package outside the checkout. No local compilation substituted for the downloaded CLI or Runner.
• Fresh isolated configuration selected standard by default without setup or Runner startup. Screenshot and a Probe tap were visually verified; disconnect acknowledged cleanup.
• Package Runner was installed by setup without compilation. Explicit Runner connection, observation, navigation and cleanup passed. Repeated setup reused the matching Runner and passed handshake/capture/disconnect checks.
• A temporary manual CLI entry was changed from the installed public 0.5.0 executable to this exact 0.6.0 package; setup through that entry reused the already-installed matching 0.6.0 Runner and passed connection/capture/cleanup. This does not establish an old-public-Runner-to-new-Runner device migration; that combination was not exercised. Public Homebrew upgrade is checked after publication.
• Real-app result: created a Notes acceptance note with Chinese, English, emoji, multiple lines and a 10:00–11:00 time string. Returned to the list, reopened the saved note, and verified the exact complete content visually and through the element snapshot. The user completed Notes first-use onboarding manually.
• With explicit permission, retired the old development capture process and started capture from this exact package. Original preview URL was retained. External and internal screen frames were visually checked; the user confirmed automatic recovery and hinge animation on both unfold and fold without refreshing. Automation shutdown retained preview. The shared existing viewer/frontend proxy was not replaced, so this verifies package capture with the retained viewer, not a fresh viewer-process deployment.
• Package HEVC recording passed decoding validation. The inspected dynamic clip contained Notes followed by the test app: 53.583 seconds, 685 decoded frames, 1408×2048. Explicit stop preserved preview. This is functional recording acceptance, not sustained-30-fps acceptance.
• One standard Home request expired and another was rejected at pre-input validation; neither dispatched input. No uncertain input was replayed or safety guard bypassed. A separate app-open action succeeded and its recorded result was verified.

Remaining scope: seconds of black/unavailable frames during folding remain a known limitation; stable 30 fps and seamless recording across display/orientation changes are not claimed. The complete orientation/gesture matrix and ordinary-iPhone regression used development builds before packaging, and were not fully repeated on this archive. A previous public Runner migration, fresh viewer-process startup, clean-Mac provisioning, free-account renewal, additional OS/device combinations, browser/Gatekeeper first installation and fresh installs in every agent client are not covered. Private captures, signing details and device IDs remain local.

Accepted archive SHA-256: 900e010585f3cde302a401825160989bba393eb2c63b628440ca412bc07e743a. Published without rebuilding.

Public installation verification

After publication, an unauthenticated download matched the accepted archive SHA-256. Homebrew Tap update succeeded; local brew upgrade HughLee824/tap/iphone-use upgraded 0.5.0 to 0.6.0, and brew test passed the installed CLI/Runner digest checks. The Homebrew CLI established a standard connection on the same Duo (HID ready, no Runner started), then disconnected cleanly while retaining independent preview.

Installation

Download the tar.gz and its .sha256 file together. Installation and iPhone setup instructions are in the package README and repository docs/install.md. The separate iphone-use-plugin ZIP contains Codex/Claude manifests, the DeepSeek Harness bundle, and the complete skill; it does not contain the CLI or signed Runner. Follow docs/plugins.md for each client installation path and docs/first-task.md for the first iPhone task.

Both modes require full Xcode. Standard mode currently requires macOS/iOS 27 and does not need Runner setup or development signing. Optional Runner mode requires your own Apple development certificate, private key and matching provisioning profile; setup re-signs the precompiled Runner locally. Free Personal Team onboarding and renewal are not yet validated. The Mac CLI is ad-hoc signed, without Developer ID signing or notarization.

Maintainer: publish the exact archive accepted locally. After a stable release is published, run the Homebrew Tap's Update iPhone-use workflow with the same version, then verify installation from the public download URL and Tap. Prereleases use manual installation. The attached iphone-use.rb contains the exact versioned download URL and archive checksum.

iPhone-use 0.5.0

Precompiled macOS CLI and iOS Runner for Apple Silicon, under the MIT license.

Build

• Version: 0.5.0
• Source commit: 9cb875f301235481d6cd170f6b814570e6d33650
• Archive: iphone-use-0.5.0-macos-arm64.tar.gz
• Archive SHA-256: 8b148ab125b847996ca357e2ec28f07a6932868cc353cf6cc7fc79f885f97028
• Automated checks: GitHub Actions (attempt 1)

Changes

• Keep live preview connected during supported portrait and left/right landscape transitions. Verified per-frame orientation rotates the viewer without replacing the media stream; observation and input coordinate checks remain strict.
• Animate the device frame, live image and overlays together over 250 ms. New video frames continue during the transition, interrupted turns start from the visible transform, and the device stays within the viewport during diagonal rotation.
• Preserve the next rotation animation after returning to the foreground or disabling reduced motion. Backgrounding, reduced motion and stream replacement cancel obsolete motion.
• End fixed-orientation recordings before writing a frame with changed axes, while keeping preview available. Starting a new recording can still resynchronize stale display metadata and briefly pause preview.
• Upgrade Swift ArgumentParser to 1.8.2 and the isolated brand dependency to Pillow 13; strengthen CI artifact-transfer and dependency checks. Include the existing client plugin 0.2.1 compatibility and preview guidance.

Compatibility and upgrade

BREAKING CHANGE for source/brand maintainers: source builds require Swift 6+ (use the supported full Xcode 27 toolchain), and isolated brand tooling requires Python 3.11+. Recreate an older brand virtual environment. General release scripts and development tests retain Python 3.9+ support. Installed CLI users do not need Python or Pillow.

Upgrade the complete CLI package through Homebrew or the release archive. Existing standard/Runner requirements and CLI input contracts are unchanged. Use packaged setup if the new CLI requests an updated Runner. Plugin/portable-skill versioning remains independent; this release includes plugin 0.2.1 and does not republish npm packages.

Continuous preview rotation depends on recognized frame orientation and unchanged display geometry. Unknown metadata, display-source/size changes and decoder recovery may still interrupt preview. This release does not add iPhone Duo compatibility or promise sustained display FPS, all-device compatibility or continuous recording across orientations.

Automated checks — passed

• Swift, Python, and Node call-template tests.
• Self-contained Codex/Claude Code plugin, matching manifests and source skill, with ZIP and SHA-256.
• Archive integrity, relocated CLI version/help commands and Mac code signature verification.
• Homebrew installation and installed CLI/Runner file digests.

These checks ran on GitHub-hosted machines without a physical iPhone. They did not run device setup, connect to a phone or verify an app task.

Local device acceptance — passed

Accepted on 2026-10-29 on the maintainer's Apple Silicon Mac (macOS 27.0, Xcode 27.1) with an iPhone 12 Pro running iOS 27.0.1 and an existing paid Apple development signing profile. Cloud artifacts were built with Xcode 27.0.

• Downloaded and verified this exact archive, then ran its complete package from outside the source checkout. Version, source commit and SHA-256 match the Build section.
• Fresh isolated configuration selected standard mode without setup or an xctestrun; no Runner started. App launch, screenshot capture and a single ASCII Probe selection were visually verified (sample changed from none to ASCII, focus count became 1, keyboard appeared). Standard HID correctly reported an unacknowledged/unknown execution outcome; visual evidence, not the receipt alone, confirmed the result.
• Packaged Runner setup installed and verified the 0.5.0 Runner without compilation. Repeated setup reused its signed artifact. Explicit Runner connection, observation, app interaction and disconnect passed. Upgrade baseline used public 0.4.0; the changed 0.5.0 Runner was prepared with existing signing, then connected successfully.
• In Notes, created a new acceptance note with English, Chinese, an emoji, multiple lines and the literal text 10:00–11:00; returned to the list and reopened it. The saved text matched exactly. This was a text-persistence test, not a calendar scheduling test.
• Passive preview completed 15 portrait/left/right transitions over about 175 seconds: 849 samples, zero sampling errors and one preview generation throughout. Browser sampling observed intermediate parent-container rotation matrices while 289 frame sources advanced over a 12-second window. Fixed-orientation MP4 ended with display_changed, decoded all 261 written frames and retained media for preview.
• Owned standard and Runner sessions acknowledged media stop, receiver closure and tunnel release; Runner exit was confirmed. Private logs, images, device identifiers and signing details remain local.

Observed limitations: an earlier tap on the Probe's bottom Rotation link produced no visible navigation and was not replayed; its cause is not established. An independently authorized single top-button test passed. UI stability checks sometimes reported dynamic_or_transitioning while the system screen-sharing indicator animated; outcomes were checked from images and saved content. No unacknowledged text or tap was automatically repeated.

Not tested: iPhone Duo/foldable geometry, upside-down orientation (unsupported by this fixture), additional devices/OS versions, Intel, free Personal Team provisioning/renewal, a clean Mac, browser/Gatekeeper first-download experience, or physical background/reduced-motion transitions on this archive (covered by automated preview tests). Public distribution verified after publication: unauthenticated archive download matched the accepted SHA-256 and passed full relocated-package verification; Tap update succeeded; local Homebrew upgrade from 0.4.0 to 0.5.0 and brew test passed; the installed CLI connected to the same physical iPhone in standard mode, captured a fresh screenshot and disconnected with media/receiver/tunnel cleanup acknowledged.

Accepted archive SHA-256: 8b148ab125b847996ca357e2ec28f07a6932868cc353cf6cc7fc79f885f97028. Published without rebuilding.

Installation

Download the tar.gz and its .sha256 file together. Installation and iPhone setup instructions are in the package README and repository docs/install.md. The separate iphone-use-plugin ZIP contains Codex/Claude manifests, the DeepSeek Harness bundle, and the complete skill; it does not contain the CLI or signed Runner. Follow docs/plugins.md for each client installation path and docs/first-task.md for the first iPhone task.

Both modes require full Xcode. Standard mode currently requires macOS/iOS 27 and does not need Runner setup or development signing. Optional Runner mode requires your own Apple development certificate, private key and matching provisioning profile; setup re-signs the precompiled Runner locally. Free Personal Team onboarding and renewal are not yet validated. The Mac CLI is ad-hoc signed, without Developer ID signing or notarization.

Maintainer: publish the exact archive accepted locally. After a stable release is published, run the Homebrew Tap's Update iPhone-use workflow with the same version, then verify installation from the public download URL and Tap. Prereleases use manual installation. The attached iphone-use.rb contains the exact versioned download URL and archive checksum.

iPhone-use 0.4.0

Precompiled macOS CLI and iOS Runner for Apple Silicon, under the MIT license.

Build

• Version: 0.4.0; plugin/portable skill: 0.2.0
• Source commit: dca4ab9c03b894e3a01bdab32bad079a98267ba6 (PR #49)
• Archive: iphone-use-0.4.0-macos-arm64.tar.gz
• Archive SHA-256: 95072c5af8efe7ba246816bbc693e9ab56a7f5ff96271248683ac32ec6c5c751
• PR CI: passed
• Main CI: passed
• Candidate built locally from clean merged main with the repository release scripts. This replaces the previous unpublished candidate; it was not built by the earlier Draft release workflow.

Changes

• Fix verified-release notes parsing for pending, passed and scoped acceptance headings. Reject missing or duplicate sections and preserve neighboring release notes.

• Setup now reuses early CoreDevice preview during Runner authorization and streams signing, installation, observation and cleanup progress. Interactive terminals default to progress and preview; scripts opt in with setup --progress --preview. The original device-bound tab is reused and its image clears when setup finishes.

• Reuse a device-bound, read-only preview URL across explicitly enabled sessions on the same configuration directory and port. An already loaded tab clears on disconnect and resumes when that same device reconnects and preview is enabled again.

• Isolate old sources, late HTTP responses and decoded frames across reconnects, replacement and revocation. Another device cannot take over an existing device's preview entry.

• Add preview-revoke and preview-service-stop. Serialize concurrent service startup, reject registrations during shutdown, distinguish an accepted stop from confirmed process exit, and bound cleanup of a child launched by a failed startup attempt.

• Resolve Runner targets by the complete chain of native AX identities using fresh snapshots. Allow normal sibling reordering and layout changes, reject replaced/reparented/ambiguous identities, and remove the fixed 200-node capture cutoff while keeping display compact.

• Make Runner focus, clear, literal insertion and editing keys explicit primitives. Preserve event acknowledgement independently from verification and capture; never automatically replay input. Clear rejects unreadable/nil values before Delete and revalidates identity before accepting nil after a previously readable field is cleared.

• Add regression coverage for multi-level identity replacement, focus-changing keys and their actual modifiers, lost replies, and single-delete/non-replay boundaries.

• Recover touch-paste staging after failures before a clipboard write was attempted, discard the failed transport and retain sanitized Apple error details.

• Use captured-frame evidence for preview availability while retaining capture safety checks.

• Organize Core and tests by responsibility, extract statically linked Runner support, remove obsolete recording experiments, and strengthen engineering checks with SwiftLint, Actionlint, acceptance-tool builds and reproducible brand assets.

• Update plugin instructions for reusing the original preview tab and explicitly handling persistent preview credentials. Plugin, portable skill and Harness publications remain separate from the CLI release.

Upgrade and compatibility

Preview URL and access lifetime

This release changes preview URL lifetime. A /v/<token>/ URL persists across disconnects for the same device, configuration directory and port. Disconnecting clears the source and displayed image but does not revoke the URL's access to future explicitly enabled previews. Treat the URL as a local read credential. Do not share or forward it. Revoke it explicitly when that future access should end:

iphone-use preview-revoke --device <HARDWARE_UDID> --port <PORT>

Revocation invalidates the entry and its active source binding, not the control session or an independent recording. Explicitly stop/start preview afterward to obtain a new URL. Open that new URL in the existing tab. A different port or configuration directory uses a different entry.

Upgrade the legacy temporary URL to the new returned stable URL once in the original tab. Subsequent same-device reconnects use preview --no-open to enable preview without invoking a browser opener. Plain connect does not automatically restore a source; Runner also supports explicit connect --progress --preview. A service restart loses its in-memory sources, so a lost binding requires explicit preview stop/start.

The viewer remains loopback-only and read-only. Browser traffic does not extend the device session's idle timeout. A loaded page can recover after the service returns; refreshing while the service is absent can instead show the browser's connection error page.

Breaking change: explicit Runner actions

CLI 0.4.0 uses Runner action protocol 13 and host action protocol 2. Disconnect old sessions, install the complete matching package, run its setup for Runner mode, and reconnect. Upgrade the independently distributed plugin/portable skill to 0.2.0 and start a fresh agent session.

Runner type inserts literal text only at the current focused caret/selection. It no longer implicitly focuses, clears, replaces or appends; Runner --mode replace/append is rejected. For replacement, explicitly focus, select all, inspect the selection, clear once, verify the empty field, then type and inspect. For append, focus, request End, verify the caret and unchanged prefix, then insert only the suffix. Use a fresh observation/reference between steps. Standard mode retains its separately documented text contract.

Read inputAction.eventAttempted, eventAcknowledged and verification separately from execution and observation. Nil before clear is unreadable, not proof of emptiness; a readable field may report nil after one Delete only after its identity chain is revalidated. Return/Tab may move focus or navigate; inspect before the next action. Never repeat input to repair unknown, unconfirmed or unavailable results. Platform identity reuse, the final check-to-event race and Apple's internal event processing remain limits.

Installation and Runner

1. Finish or deliberately stop recordings and disconnect active sessions before changing the CLI installation.
2. Install the complete matched 0.4.0 package, including its bundled Runner and preview resources. After public publication, Homebrew users can run brew update and brew upgrade HughLee824/tap/iphone-use. During candidate acceptance, use only the exact downloaded draft archive, outside the source checkout.
3. Runner users should run the new package's iphone-use setup --device <HARDWARE_UDID> before connecting. This release changes Runner code; an older signed Runner must not stand in for the candidate's Runner. Existing signing configuration can be reused when valid; setup decides whether a signed artifact is reusable. Do not mix a new CLI with an old explicit --xctestrun.
4. Reconnect and explicitly enable preview, then update the original tab to the returned URL once. Standard mode does not require Runner setup.
5. Update the client skill/plugin to 0.2.0 through its own channel and start a fresh agent session. CLI/Homebrew upgrades do not update client plugins. Keep only one enabled copy of the device skill.

If upgrading from a development build that already has the independent viewer service, explicitly stop that old service on its configured port before starting the new one, coordinating with other users of that port. Refresh the page once to load the new viewer script. Public 0.3.17 used the earlier session-scoped viewer and does not provide preview-service-stop.

Setup output in terminals and scripts

Interactive setup enables progress and preview by default; --no-preview disables video and --no-progress preserves single-result output. Piped output remains a single final JSON unless explicitly enabled. Agents and scripts that need the authorization preview should use setup --progress --preview, consume NDJSON progress while the command is pending and parse the final result separately. --preview requires progress; --port requires preview. Setup does not open a browser or change saved preferences.

Preview failure is reported separately and does not automatically retry setup or block phone-side verification. Setup owns its temporary verification session, captures once and disconnects once, including observation failure. Keep the existing viewer tab for a later explicitly enabled connection. An uncertain cleanup remains a failure requiring inspection.

Stop receipts and automation

For preview-service-stop, ok=true means the stop request was accepted. Only result.exited=true with result.state=stopped confirms process exit. An unconfirmed exit returns state=stop_requested, exited=false and a reason such as exit_wait_timeout or exit_observation_unavailable. Stopping the viewer service does not disconnect device control or stop recording. It pauses all preview pages using that service port.

Startup contention returns preview_service_busy after a bounded wait. preview_service_cleanup_pending means termination was requested for the newly launched child but its exit was not confirmed. Do not interpret either outcome as permission to kill an unrelated process or replay an uncertain device action.

Supported environment

The release target remains Apple Silicon macOS with full Xcode. Standard mode currently requires macOS/iOS 27; optional Runner mode requires the user's development signing. The Runner's build deployment target is not a claim that every older iOS version was validated. The CLI remains ad-hoc signed, without Developer ID signing or notarization. No new claims are made for Intel, clean-Mac provisioning, free-account renewal or other device/OS combinations...

iPhone-use 0.3.17

Precompiled macOS CLI and iOS Runner for Apple Silicon, under the MIT license.

Build

• Version: 0.3.17
• Source commit: d142853baa953bcb03a7d6fff6e4d0227a2a4a15
• Archive: iphone-use-0.3.17-macos-arm64.tar.gz
• Archive SHA-256: e6bd07b0c17dc3cee536b1fb30340ae5f267d5fc2d08aaa5c02fc32e61e7a0f8
• Automated checks: GitHub Actions (attempt 1)

Changes

• Keep live preview available when CoreDevice reports an unlocked display as activeDimmed; inactive and unknown states remain rejected.
• Accept the narrowly defined two-row native video height alignment seen on iPhone 16 Pro, retain canvas bounds checks, and crop to the actual display dimensions.
• Add regression coverage for display state, geometry boundaries, and portrait/landscape cropping.

Upgrade with brew upgrade HughLee824/tap/iphone-use, or replace the complete manual installation. Disconnect an existing session before changing its CLI installation, then reconnect. Runner mode uses iphone-use setup --device <device> when the CLI requests it; standard mode does not require setup. The plugin version remains 0.1.19.

The original isolated host_start_failed exit cause was not established. These changes address the separately reproduced preview failures; they do not claim to diagnose every host startup failure.

Automated checks — passed

• Swift, Python, and Node call-template tests.
• Self-contained Codex/Claude Code plugin, matching manifests and source skill, with ZIP and SHA-256.
• Archive integrity, relocated CLI version/help commands and Mac code signature verification.
• Homebrew installation and installed CLI/Runner file digests.

These checks ran on GitHub-hosted machines without a physical iPhone. They did not run device setup, connect to a phone or verify an app task.

Local device acceptance — passed

Accepted on 2026-10-23 with agent-assisted physical-device checks of this exact GitHub-built archive, installed outside the source checkout. Source d142853; Apple Silicon, macOS 27.0, Xcode 27.0, iPhone 16 Pro on iOS 27.0.1, existing developer signing. Archive checksums, clean source identity, relocation, signatures, system dependencies and isolated mode preferences passed.

• Standard mode: a fresh isolated configuration selected standard without setup or xctestrun; controlAvailable=true and runnerStarted=false. Opened the local Text Probe, tapped ASCII once, dismissed its wireless-data prompt with Don't Allow, and visually verified the selected sample and focused editor. Native input returned an unacknowledged outcome; the actual screenshots established the result and no input was replayed. The browser preview showed the correct iPhone 16 Pro frame and screen. Final status reported streaming, 1,585 encoded frames and zero decode errors.
• Runner mode: setup and repeat setup both returned reused=true and compiled=false, with connection/capture/disconnect verification. The packaged Runner content version matches the previous public 0.3.16 package, and the existing signed Runner was reused. Explicit Runner connect, observations and browser preview passed. A separate connect --reuse process retained the same host/session, preview URL and 3,600-second timeout despite a 10-second requested timeout. Status reported streaming, 5,592 encoded frames and zero decode errors.
• Local app result: inserted the exact value "预览发布验证 0.3.17🙂" and verified screenshot plus accessibility text. An attempted End editing button tap hit the keyboard candidate area because the button was obscured; the added ellipsis was detected, the disposable field was replaced with the intended value, and returning Home then reopening the app confirmed the exact complete value remained. This verifies an in-memory editor result across background/foreground, not a saved document, process-relaunch persistence or external submission. Dismissing a system alert returned an XCTest snapshot error after input; its attached screenshot confirmed dismissal. That input was not replayed. These observations are retained as acceptance limitations, not claimed fixes in this release.
• Both sessions disconnected cleanly: media/tunnel shutdown, Runner exit where applicable, host exit, socket removal and observation-cache removal were checked. Raw receipts and screenshots remain local.
• PR CI, merged main CI and the cloud Draft release checks passed. Automated regressions cover activeDimmed versus inactive states, exact-width/bounded-height geometry, encoded-canvas bounds and portrait/landscape cropping.

Limitations: only the device/OS/signing combination above was tested for this archive. Free-account or clean-Mac provisioning, Intel, other OS/Xcode combinations, browser-download Gatekeeper behavior and authentication after reboot were not retested. The original isolated host_start_failed cause remains unconfirmed; subsequent acceptance connections succeeded. Public anonymous download and the actual Homebrew 0.3.16-to-0.3.17 upgrade are verified separately after publication. No Notes content was searched, read or written.

Accepted archive SHA-256: e6bd07b0c17dc3cee536b1fb30340ae5f267d5fc2d08aaa5c02fc32e61e7a0f8. Published without rebuilding.

Installation

Download the tar.gz and its .sha256 file together. Installation and iPhone setup instructions are in the package README and repository docs/install.md. The separate iphone-use-plugin ZIP contains Codex/Claude manifests, the DeepSeek Harness bundle, and the complete skill; it does not contain the CLI or signed Runner. Follow docs/plugins.md for each client installation path and docs/first-task.md for the first iPhone task.

Both modes require full Xcode. Standard mode currently requires macOS/iOS 27 and does not need Runner setup or development signing. Optional Runner mode requires your own Apple development certificate, private key and matching provisioning profile; setup re-signs the precompiled Runner locally. Free Personal Team onboarding and renewal are not yet validated. The Mac CLI is ad-hoc signed, without Developer ID signing or notarization.

Maintainer: publish the exact archive accepted locally. After a stable release is published, run the Homebrew Tap's Update iPhone-use workflow with the same version, then verify installation from the public download URL and Tap. Prereleases use manual installation. The attached iphone-use.rb contains the exact versioned download URL and archive checksum.

Public installation verification — passed

After publication on 2026-10-23, anonymous downloads of the archive, checksum and formula matched the accepted draft byte for byte. The public archive passed the executable relocation/integrity checks; the public tag points to d142853. The Tap update workflow succeeded and its formula matches the release asset.

The existing local Homebrew installation upgraded from 0.3.16 to 0.3.17. brew test HughLee824/tap/iphone-use passed, including the installed CLI/Runner digests. The installed /opt/homebrew/bin/iphone-use connected to the same iPhone 16 Pro using the existing Runner without setup or reinstallation, captured a fresh screenshot, streamed a healthy browser preview and reused the same session/URL with its 60-minute idle timeout. At the final reuse check the preview had 923 encoded frames and zero decode errors. The connection and preview were intentionally retained at the user's request.

iPhone-use 0.3.16

Precompiled macOS CLI and iOS Runner for Apple Silicon, under the MIT license.

Build

• Version: 0.3.16
• Source commit: 9523fa0c0667c34dde0f4b96e35e8ceec24481a1
• Archive: iphone-use-0.3.16-macos-arm64.tar.gz
• Archive SHA-256: 5ed5d46b1be46128a0fbfd2bc2ac5429526840d1dc39c190ab9ea4ec2e99f1b0
• Automated checks: GitHub Actions (attempt 1)

Changes

Pending: describe this version's changes, compatibility changes and upgrade steps.

Changes

• Continue an existing healthy device connection with connect --device UDID --reuse, preserving its host, preview URL and idle timeout. sessions lists endpoints in the selected state directory.
• Refuse ambiguous endpoints, mode or explicit connection-setting conflicts, unavailable control, host-reported work in progress and unfinished clipboard transactions. Reuse is intended for sequential tasks, not concurrent control.
• Report whether a connection was created or borrowed. Agent workflow 0.1.19 retains borrowed connections and previews at task completion, and uses fresh observations in the new task.

Upgrade through Homebrew or replace the complete manual installation. Both chats must use the same state directory. Existing Runner setup remains reusable when its packaged content and signing are valid. Client plugin and portable skill versions are 0.1.19; older CLIs retain the previous connection workflow through capability detection.

Automated checks — passed

• Swift, Python, and Node call-template tests.
• Self-contained Codex/Claude Code plugin, matching manifests and source skill, with ZIP and SHA-256.
• Archive integrity, relocated CLI version/help commands and Mac code signature verification.
• Homebrew installation and installed CLI/Runner file digests.

These checks ran on GitHub-hosted machines without a physical iPhone. They did not run device setup, connect to a phone or verify an app task.

Local device acceptance — passed

Accepted on 2026-10-23 with agent-assisted physical-device checks using the exact GitHub-built 0.3.16 archive, installed outside the source checkout. Source 9523fa0; Apple Silicon, macOS 27.0, Xcode 27.0, iPhone 12 Pro on iOS 27.0.1, existing developer signing. Archive identity, checksums, relocation, signatures, system dependencies and isolated mode preferences passed.

• Standard: fresh isolated configuration selected standard without setup or xctestrun; runnerStarted=false. A second independent CLI process used connect --reuse and returned the same session and host PID, original preview URL and 1800-second timeout with borrowed ownership. Opened the local Text Probe and tapped ASCII once; the attached screenshot confirmed the fixture selection, focused empty editor and keyboard. Native input reports no acknowledgement, so the result was verified visually without replay. A conflicting runner reuse request was rejected without replacing the host.
• Runner: setup and repeat setup reused the packaged Runner with compiled=false. Explicit Runner connection and native preview passed using existing authorization. A new CLI process reused the same host, Runner session and preview. An additional reuse request with --idle-timeout 10s retained the existing 1800-second timeout. Preview remained streaming with 3,114 decoded frames and zero decoder errors at the final status.
• Local app result: inserted the exact text "会话复用验证 0.3.16🙂", ended editing and verified the complete retained value in both the screenshot and accessibility snapshot. An initial replace on the empty field was safely rejected as replace_value_unavailable before any input; insert was then explicitly selected for the visibly empty field. This validates a local editor result, not persistence after app relaunch or an external submission. Transient status-bar/keyboard changes produced non-stable flags; results were judged from the actual attached screenshots and no input was replayed.
• Both previews displayed the actual iPhone model/bezel and became the plain opaque cover on disconnect. Standard media/tunnel cleanup, Runner shutdown and media cleanup, host exit records, socket removal and observation-cache removal passed. No acceptance session remains active.
• PR CI, exact main CI and Draft release checks passed. Local checks: 542 Swift tests (2 opt-in skips), 88 Python tests and 73 Node passes (1 optional integration skip). Deterministic tests cover unavailable/busy hosts, ambiguity, configuration conflicts, clipboard transactions and real local IPC discovery/reuse; those failure conditions were not all induced on the physical device.

Limitations: sequential independent CLI-process reuse was verified; no separate client-model/chat automation acceptance, free-account or clean-Mac provisioning, Intel, additional OS/Xcode combinations, or browser-download Gatekeeper validation. System authorization after reboot was not retested. Public download and Homebrew upgrade are verified separately after publication.

Accepted archive SHA-256: 5ed5d46b1be46128a0fbfd2bc2ac5429526840d1dc39c190ab9ea4ec2e99f1b0. Published without rebuilding.

Post-publication verification

All five public assets were downloaded anonymously and matched the accepted draft digests. The public CLI archive passed relocation, signature and isolated-preference verification again. Homebrew Tap update, local upgrade from 0.3.15 to 0.3.16, and brew test passed. The installed Homebrew CLI connected in standard mode, captured the retained Probe text, displayed healthy live video with the iPhone 12 Pro bezel and cleaned up successfully. No test session remains active.

iphone-use-skill 0.1.19 and dsh-iphone-use 0.1.19 were published by their GitHub Actions workflows from the same main commit. Both registry-integrity and public-installation checks passed. Public registry metadata confirms both versions. No local npm publication was used.

Installation

Download the tar.gz and its .sha256 file together. Installation and iPhone setup instructions are in the package README and repository docs/install.md. The separate iphone-use-plugin ZIP contains Codex/Claude manifests, the DeepSeek Harness bundle, and the complete skill; it does not contain the CLI or signed Runner. Follow docs/plugins.md for each client installation path and docs/first-task.md for the first iPhone task.

Both modes require full Xcode. Standard mode currently requires macOS/iOS 27 and does not need Runner setup or development signing. Optional Runner mode requires your own Apple development certificate, private key and matching provisioning profile; setup re-signs the precompiled Runner locally. Free Personal Team onboarding and renewal are not yet validated. The Mac CLI is ad-hoc signed, without Developer ID signing or notarization.

Maintainer: publish the exact archive accepted locally. After a stable release is published, run the Homebrew Tap's Update iPhone-use workflow with the same version, then verify installation from the public download URL and Tap. Prereleases use manual installation. The attached iphone-use.rb contains the exact versioned download URL and archive checksum.

iPhone-use 0.3.15

Precompiled macOS CLI and iOS Runner for Apple Silicon, under the MIT license.

Build

• Version: 0.3.15
• Source commit: c54800dca9a99445b4e90e640ad2a0eb20c3019a
• Archive: iphone-use-0.3.15-macos-arm64.tar.gz
• Archive SHA-256: 50fb6e8c8ffe55f7d5a7e9f9fe32048b4ce3a12b14dd2b6896d3014ef7f1c8ab
• Automated checks: GitHub Actions (attempt 1)

Changes

• Keep an already healthy preview and recording alive when a read-only CoreDevice display/status query briefly times out. The next scheduled poll checks again without replacing the video stream or preview URL. Confirmed device lock, unhealthy media, cancellation and refresh failures still stop normally.
• Use one plain opaque screen cover when video is unavailable, inside the real device bezel. Missing frames do not imply a UI Automation authorization request; only confirmed authorization evidence updates the footer status.
• Reveal the first decoded frame immediately. A delayed health response that started before that frame cannot restore the cover over it.

Upgrade through Homebrew or replace the complete manual installation. Existing Runner setup can be reused when its packaged content and signing remain valid. Client plugin and npm skill versions remain 0.1.18; this release does not change their contents.

Automated checks — passed

• Swift, Python, and Node call-template tests.
• Self-contained Codex/Claude Code plugin, matching manifests and source skill, with ZIP and SHA-256.
• Archive integrity, relocated CLI version/help commands and Mac code signature verification.
• Homebrew installation and installed CLI/Runner file digests.

These checks ran on GitHub-hosted machines without a physical iPhone. They did not run device setup, connect to a phone or verify an app task.

Local device acceptance — passed

Accepted on 2026-10-23 by the maintainer with agent-assisted checks, using the exact GitHub-built 0.3.15 archive installed outside the source checkout. Source c54800d; Apple Silicon, macOS 27.0, Xcode 27.0, iPhone 12 Pro on iOS 27.0.1, existing paid developer signing. Archive digest, relocation, signatures, system dependencies and isolated mode preferences passed.

• Standard mode: fresh isolated configuration selected standard by default without setup or xctestrun; no Runner started. Connected, opened the local Text Probe, tapped the ASCII fixture and verified the selected fixture and focused empty editor in the returned screenshot. Native input reports no device acknowledgement, so success was judged from the changed screenshot, with no replay. Preview remained healthy through cleanup (1,984 decoded frames, zero decoder errors).
• Runner: setup and repeated setup both reused the packaged Runner with compiled=false. Explicit Runner connection and independent native preview passed. Existing authorization was reused; this candidate was not tested after reboot and did not repeat the system authorization prompt.
• Local app result: inserted the exact text "发布验证 0.3.15🙂", ended editing and verified the complete retained value in the screenshot and accessibility snapshot. This is a retained local editor result, not an external submission or persistence-after-relaunch claim.
• Runner preview remained on the same URL and healthy 80.5 seconds after readiness during the app checks, with 2,527 decoded frames and zero decoder errors at the recorded status. Both modes displayed the actual iPhone 12 Pro bezel and model capsule; disconnect showed only the plain opaque cover. Media/tunnel and Runner cleanup, host exit records and observation-cache removal passed.
• Final main CI passed: 536 Swift tests (2 skipped), 83 Python tests and 73 Node tests (1 skipped), plus Runner host-runtime checks and unsigned build. Browser tests cover first-frame/late-health races, quiet retained frames, cover geometry and exact authorization evidence. Deterministic tests cover repeated healthy-stream query timeouts and ensure locks, unhealthy media, cancellation and refresh failures remain terminal. A real CoreDevice timeout was not induced during this candidate's device checks.

Limitations: no new free-account, clean-Mac provisioning, Intel, additional OS/Xcode, browser-download Gatekeeper, or separate client-model task acceptance. Client plugin/npm packages remain unchanged at 0.1.18. Public download and Homebrew upgrade are verified separately after publication.

Accepted archive SHA-256: 50fb6e8c8ffe55f7d5a7e9f9fe32048b4ce3a12b14dd2b6896d3014ef7f1c8ab. Published without rebuilding.

Post-publication verification

All five public assets were downloaded anonymously and matched the exact accepted draft digests. The public archive passed relocation/signature/configuration verification again. Homebrew Tap update completed; local upgrade from 0.3.14 to 0.3.15 and brew test passed. The installed Homebrew CLI connected in standard mode, captured the expected retained Text Probe result, displayed healthy real-device video with the iPhone 12 Pro bezel, and showed the plain opaque cover on disconnect. Media/tunnel cleanup and observation-cache removal passed. No test session remains active.

Installation

Download the tar.gz and its .sha256 file together. Installation and iPhone setup instructions are in the package README and repository docs/install.md. The separate iphone-use-plugin ZIP contains Codex/Claude manifests, the DeepSeek Harness bundle, and the complete skill; it does not contain the CLI or signed Runner. Follow docs/plugins.md for each client installation path and docs/first-task.md for the first iPhone task.

Both modes require full Xcode. Standard mode currently requires macOS/iOS 27 and does not need Runner setup or development signing. Optional Runner mode requires your own Apple development certificate, private key and matching provisioning profile; setup re-signs the precompiled Runner locally. Free Personal Team onboarding and renewal are not yet validated. The Mac CLI is ad-hoc signed, without Developer ID signing or notarization.

Maintainer: publish the exact archive accepted locally. After a stable release is published, run the Homebrew Tap's Update iPhone-use workflow with the same version, then verify installation from the public download URL and Tap. Prereleases use manual installation. The attached iphone-use.rb contains the exact versioned download URL and archive checksum.

iPhone-use 0.3.14

Precompiled macOS CLI and iOS Runner for Apple Silicon, under the MIT license.

Build

• Version: 0.3.14
• Source commit: b83de56a75630e1c520252f67d6ef61f0ddf2f1c
• Archive: iphone-use-0.3.14-macos-arm64.tar.gz
• Archive SHA-256: 48ec133a664808f53fe29852b93bbdc8d98df4d8905d75193deec246c613f157
• Automated checks: GitHub Actions (attempt 1)

Changes

• Start independent CoreDevice video before Runner UI Automation authorization, so the real system authentication screen can appear in the preview. Keep the same video connection and URL when Runner becomes ready.
• Use the actual device model and bezel from the first preview frame, through authorization, live playback and disconnection.
• Keep authorization instructions as a fallback only when usable video is unavailable. Healthy video stays visible; control readiness remains in the status capsule below the phone.
• A startup media failure keeps the preview diagnostics and does not prevent Runner authorization or silently retry media.
• Update the shared client instructions and plugin/portable skill packages to 0.1.18.

Upgrade the CLI through Homebrew or replace the complete manual installation. Update the installed client plugin separately to pick up the revised instructions. The existing requirements remain: full Xcode; macOS/iOS 27 for CoreDevice video; valid local Apple development signing for Runner.

Post-publication verification and known issue

All five public assets were downloaded anonymously and matched the accepted draft SHA-256 digests. Homebrew 0.3.13 → 0.3.14 upgrade and brew test passed; installed standard-mode connection, screenshot, and cleanup passed. Installed Runner connection reused the existing setup and initially reported healthy, decoded video; cleanup passed.

Intermittent preview timeout remains unresolved: during later Homebrew installation checks, standard and Runner previews stopped after a CoreDevice state-check timeout. A further user-requested retry rendered the real iPhone 12 Pro preview correctly and remained healthy for 131 seconds after readiness (4,434 decoded frames, zero decoder errors), then device info lockState exceeded its 5-second timeout. The Mac was still heavily loaded, making host contention a plausible contributor; it has not been established as the sole cause. The already-open page correctly switched to the solid disconnected cover with the same bezel. These later failures are recorded separately from the successful exact-archive authorization/video acceptance. All test sessions were disconnected and owned-resource cleanup was verified.

The npm packages iphone-use-skill@0.1.18 and dsh-iphone-use@0.1.18 subsequently passed OIDC/provenance publication and registry-integrity/public-installation verification from commit 0729e73c54a65bd6f63c36cde63389ab6237da9a (portable skill, DeepSeek Harness plugin). That follow-up corrects repository-name casing in package metadata and setup documentation; it does not change the CLI or replace any assets attached here.

Automated checks — passed

• Swift, Python, and Node call-template tests.
• Self-contained Codex/Claude Code plugin, matching manifests and source skill, with ZIP and SHA-256.
• Archive integrity, relocated CLI version/help commands and Mac code signature verification.
• Homebrew installation and installed CLI/Runner file digests.

These checks ran on GitHub-hosted machines without a physical iPhone. They did not run device setup, connect to a phone or verify an app task.

Local device acceptance — passed

Accepted on 2026-10-22 by the maintainer with agent-assisted checks, using the exact GitHub-built 0.3.14 archive installed outside the source tree. Source b83de56; Apple Silicon, macOS 27.0, Xcode 27.0, iPhone 12 Pro on iOS 27.0.1, existing paid developer signing. Package digest, relocation, signatures, system library dependencies and isolated mode preferences passed.

• Standard mode: fresh isolated configuration, default connect without setup or xctestrun, no Runner started; observed the local Text Probe, performed a fixture tap and confirmed its changed value in the next screenshot. Disconnect and host/cache cleanup passed.
• Runner: setup and repeated setup reused the valid packaged Runner with compiled=false. After a physical phone restart, the real system Enable UI Automation/passcode screen was visible in the independent native video stream before Runner authorization. The same preview URL and stream continued to the home screen after the user authenticated; the actual iPhone 12 Pro bezel remained throughout. Screenshot and local app interaction passed.
• Local task result: focused the Text Probe editor, inserted the exact text “发布验证 0.3.14🙂”, ended editing, and verified the complete retained value in both the screenshot and accessibility snapshot. This is a local retained editor result, not an external save/submission claim. Initial replacement of an unreadable empty value was rejected before dispatch; an unfocused insert returned a keyboard-focus error and the resulting observation confirmed no text was entered. Explicit focus followed by insertion passed.
• Final standard and Runner disconnects acknowledged media/tunnel and Runner cleanup, with host exit and observation-cache removal independently checked. The disconnected preview is an opaque solid cover with the same real device bezel and model pill. An earlier Runner attempt was interrupted by the user rebooting the phone: context guarding prevented text dispatch, local cleanup completed, but remote shutdown acknowledgement was unavailable during reboot; the fresh post-reboot session then completed and cleaned up normally.

Limitations: no new free-account, clean-Mac provisioning, Intel, additional OS/Xcode, browser-download Gatekeeper or separate client-model task acceptance. Codex and Claude Git plugin installations updated to 0.1.18; npm channels and public Homebrew upgrade are verified separately. No broader compatibility is inferred.

Accepted archive SHA-256: 48ec133a664808f53fe29852b93bbdc8d98df4d8905d75193deec246c613f157. Published without rebuilding.

Installation

Download the tar.gz and its .sha256 file together. Installation and iPhone setup instructions are in the package README and repository docs/install.md. The separate iphone-use-plugin ZIP contains Codex/Claude manifests, the DeepSeek Harness bundle, and the complete skill; it does not contain the CLI or signed Runner. Follow docs/plugins.md for each client installation path and docs/first-task.md for the first iPhone task.

Both modes require full Xcode. Standard mode currently requires macOS/iOS 27 and does not need Runner setup or development signing. Optional Runner mode requires your own Apple development certificate, private key and matching provisioning profile; setup re-signs the precompiled Runner locally. Free Personal Team onboarding and renewal are not yet validated. The Mac CLI is ad-hoc signed, without Developer ID signing or notarization.

Maintainer: publish the exact archive accepted locally. After a stable release is published, run the Homebrew Tap's Update iPhone-use workflow with the same version, then verify installation from the public download URL and Tap. Prereleases use manual installation. The attached iphone-use.rb contains the exact versioned download URL and archive checksum.

iPhone-use 0.3.13

Precompiled macOS CLI and iOS Runner for Apple Silicon, under the MIT license.

Build

• Version: 0.3.13
• Source commit: 039d3fb7c060771c7825d67fa0fc5f2514fa6303
• Archive: iphone-use-0.3.13-macos-arm64.tar.gz
• Archive SHA-256: f09f6856817f69fda79bbf00baa1653e2ece1f3139f084757a02004ad9beb710
• Automated checks: GitHub Actions (attempt 1)

Changes

• Disconnected previews use an opaque solid screen cover. The UI Automation authorization state uses a small lock, concise instructions and system light/dark colors.
• Device name and connection status are grouped in a small capsule below the phone. The fullscreen button and floating top controls are removed; the development-only appearance comparison control remains outside the capsule.
• Runner replace/append no longer depend on Command-A, which can silently fail on iOS. The Runner requests the document end, applies bounded backward deletion based on the readable source value, then confirms the field is empty before entering the replacement. An unconfirmed clear fails without entering replacement text. Empty replacement clears the field; secure/unreadable/ambiguous/oversized source values are rejected before input. No automatic input replay was added.
• Includes skill/plugin 0.1.17 unchanged. CLI and skill/plugin upgrades are separate.

Runner payload changed in this version, so existing Runner users may need to run setup again. Standard mode does not require setup. A successful input receipt confirms event execution, not the app's final business result; agents must inspect the attached post-action image.

Automated checks — passed

• Swift, Python, and Node call-template tests.
• Self-contained Codex/Claude Code plugin, matching manifests and source skill, with ZIP and SHA-256.
• Archive integrity, relocated CLI version/help commands and Mac code signature verification.
• Homebrew installation and installed CLI/Runner file digests.

These checks ran on GitHub-hosted machines without a physical iPhone. They did not run device setup, connect to a phone or verify an app task.

Local device acceptance — passed

Accepted on 2026-10-22 using the exact cloud-built archive above, installed as a complete package outside the source checkout. Environment: Apple Silicon, macOS 27.0 (26A428), Xcode 27.0 (27A266a), iPhone 12 Pro / iOS 27.0.1, existing paid Apple development signing. Checks executed locally by Codex for the maintainer; private evidence retained locally.

• Package verification, relocation, isolated mode preferences, CLI signature and all CLI/Runner digests passed.
• Fresh isolated configuration selected standard mode without setup or Runner launch. Connect, observe, one offline Probe fixture tap, screenshot verification and disconnect passed. The standard action reported its documented unknown acknowledgment; the changed fixture was visually confirmed without replay.
• Live preview showed the device/status capsule below the phone and no fullscreen control. Stopping preview produced an opaque solid cover without notice text.
• Runner upgrade correctly required setup for the changed payload. Setup used the packaged precompiled Runner without compilation; repeated setup reused the valid signed artifact. Explicit Runner connect and preview passed without reinstalling.
• In the offline native text Probe, replacing the middle selection in 头🙂尾 produced exactly 替换🙂; append with a non-end selection produced exactly 头🙂尾追加. UTF-8 results were confirmed by the app and post-action screenshots. Multiline Chinese, emoji and a combining accent round-tripped exactly; replacing that multiline value produced exactly 验证🙂. Empty replacement cleared all text; ending editing preserved the empty result. This is an in-memory editor outcome check, not a persistence or external submission claim.
• Standard, both setup verification sessions and Runner sessions disconnected cleanly; host processes exited and observation caches were removed. Runner shutdown and media cleanup were acknowledged.
• The first unpublished candidate failed the selected-text replacement test and was rejected. PR #34 corrected document-end/deletion behavior and empty-field confirmation; a fresh cloud archive from the final commit was built and all checks above repeated. The rejected archive was never published.

Scope: one existing Mac/iPhone and paid-signing environment. Free accounts, fresh-Mac provisioning, other OS/device combinations, Intel, browser-download/Gatekeeper onboarding and authorization-wait UI on this final archive were not newly validated. CLI remains ad-hoc signed and not notarized. Public distribution checks also passed as recorded below.

Accepted archive SHA-256: f09f6856817f69fda79bbf00baa1653e2ece1f3139f084757a02004ad9beb710. Published without rebuilding.

Public distribution — passed

• Verified publication workflow published the accepted archive without rebuilding. Public tag v0.3.13 resolves to the source commit above.
• Anonymous downloads of all five public assets match the accepted candidate byte-for-byte. The public archive passed full integrity, relocated execution, isolated preferences and signature checks.
• Homebrew Tap update passed. An existing installation was upgraded from 0.3.12 to 0.3.13 via the public Tap; brew test passed. Installed CLI and all 12 Runner file hashes match the accepted package manifest.
• The public Homebrew binary completed standard-mode connection, a fresh phone screenshot, live preview and disconnect on the same physical iPhone. Runner was not launched; media/control cleanup succeeded, the host exited and observation cache was removed.
• Plugin/skill remains 0.1.17; this CLI release does not require a new plugin/npm publication. Existing compatibility and signing limitations above remain unchanged.

Installation

Download the tar.gz and its .sha256 file together. Installation and iPhone setup instructions are in the package README and repository docs/install.md. The separate iphone-use-plugin ZIP contains Codex/Claude manifests, the DeepSeek Harness bundle, and the complete skill; it does not contain the CLI or signed Runner. Follow docs/plugins.md for each client installation path and docs/first-task.md for the first iPhone task.

Both modes require full Xcode. Standard mode currently requires macOS/iOS 27 and does not need Runner setup or development signing. Optional Runner mode requires your own Apple development certificate, private key and matching provisioning profile; setup re-signs the precompiled Runner locally. Free Personal Team onboarding and renewal are not yet validated. The Mac CLI is ad-hoc signed, without Developer ID signing or notarization.

Maintainer: publish the exact archive accepted locally. After a stable release is published, run the Homebrew Tap's Update iPhone-use workflow with the same version, then verify installation from the public download URL and Tap. Prereleases use manual installation. The attached iphone-use.rb contains the exact versioned download URL and archive checksum.

iPhone-use 0.3.12

Precompiled macOS CLI and iOS Runner for Apple Silicon, under the MIT license.

Build

• Version: 0.3.12
• Source commit: bd8eeb74cd7b8df18f4a9ec250c09629758121a3
• Archive: iphone-use-0.3.12-macos-arm64.tar.gz
• Archive SHA-256: 35e2214bdba58a3594ea433666d0d99286095387937ee0a64a5029d2cafbe916
• Automated checks: GitHub Actions (attempt 1)

Changes

• Runner connections can stream connection_progress JSON events with connect --progress, allowing agents to relay confirmed UI Automation authentication requests while connection is still pending. Without the flag, the single-JSON contract is unchanged.
• connect --progress --preview opens a read-only loopback preview before Runner authentication, using the configured/default port. The same URL automatically displays live video after the connection becomes ready; --port can override this start.
• Authorization and connection states are presented inside the phone screen with concise Chinese/English guidance. The dedicated Enable UI Automation screen requires exact, session-associated Automation Mode evidence. Face ID and other app prompts remain in the real phone image.
• A bounded, isolated device-log monitor adds no raw log persistence. Unsupported log formats, unavailable monitoring, ordinary timeouts and media failures do not establish an authorization request. Pending startup can be cancelled and owned monitoring/media/control resources are released.
• Includes skill/plugin workflow 0.1.17 for capability detection, immediate human-action guidance and NDJSON result handling. CLI and skill upgrades remain separate.

No Runner payload changes, generic permission detector or new frame-pacing claim are included. Development acceptance covered a genuine UI Automation wait and recovery on one iPhone 12 Pro / iOS 27.0.1, plus WeChat Face ID remaining visible; exact-archive acceptance is recorded below separately.

Automated checks — passed

• Swift, Python, and Node call-template tests.
• Self-contained Codex/Claude Code plugin, matching manifests and source skill, with ZIP and SHA-256.
• Archive integrity, relocated CLI version/help commands and Mac code signature verification.
• Homebrew installation and installed CLI/Runner file digests.

These checks ran on GitHub-hosted machines without a physical iPhone. They did not run device setup, connect to a phone or verify an app task.

Local device acceptance — passed

Local acceptance, 2026-10-21, assisted by Codex on the maintainer's Apple Silicon Mac: macOS 27.0, Xcode 27.0, iPhone 12 Pro / iOS 27.0.1, existing development signing.

• Downloaded this exact cloud-built draft archive, verified version/source/SHA-256, integrity, relocated execution, signature, linked libraries and isolated preferences. Used the complete package installed outside the source checkout for all candidate device checks.
• A new isolated configuration selected Standard mode without setup or Runner launch. After releasing an unrelated client's media channel, connection and preview at port 8765 passed. A single tap in the offline Text Probe changed Sample from none to 起始 and Focus from 0 to 1; the after-screenshot and live browser image both showed the result. HID returned unknown as documented; input was not replayed. Disconnect acknowledged media/control cleanup with zero display refreshes. The initial native_media_busy was reported as a media error, not an authorization request.
• Explicit Runner connect with --progress --preview reused the existing installed Runner without installation. The downloaded binary emitted a session-associated UI Automation request (evidence=device_log_exact_runner_pid), authorization enabled, then ready; the same preview URL streamed live video. Authentication completed before the page was inspected, so this candidate run does not claim a captured waiting-screen image. Earlier source-build evidence separately covers the full wait, on-screen guidance, human authentication and recovery sequence, plus WeChat Face ID remaining visible without a UI Automation overlay.
• Runner observation and one element tap on End editing (no submit) passed: Active changed from true to false and the keyboard disappeared in both the screenshot and live preview. The selected sample was retained across the Standard-to-Runner reconnect. No external account data was changed.
• Setup and repeated setup both passed without compilation, reused valid signing, and verified connection, observation capture and disconnect. All 12 packaged Runner file digests and the Runner content version match 0.3.11. Upgrade connection did not require reinstalling Runner.
• All candidate sessions and preview tabs were closed; Runner, authorization monitor and media cleanup were acknowledged. Private device identifiers, signing information and raw receipts remain local.

Limitations: no new frame-pacing claim, clean-Mac onboarding, free Personal Team signing, Intel or other OS/device combinations were validated. Public Homebrew upgrade and npm distribution checks follow publication and are reported separately.

Accepted archive SHA-256: 35e2214bdba58a3594ea433666d0d99286095387937ee0a64a5029d2cafbe916. Published without rebuilding.

Public distribution verification

• All five public Release assets were downloaded anonymously and matched the accepted draft assets byte for byte; the tag points to the accepted source commit.
• Homebrew Tap update passed. On the acceptance Mac, the public formula upgraded 0.3.11 to 0.3.12; brew test, the CLI digest and all 12 Runner file digests matched the accepted package. The installed CLI connected to the iPhone, displayed a live browser preview, then disconnected with media cleanup acknowledged.
• Portable skill (iphone-use-skill) and DeepSeek Harness plugin (dsh-iphone-use) 0.1.17 publication, registry integrity and public installation verification passed. CLI and skill/plugin upgrades remain separate.

Installation

Download the tar.gz and its .sha256 file together. Installation and iPhone setup instructions are in the package README and repository docs/install.md. The separate iphone-use-plugin ZIP contains Codex/Claude manifests, the DeepSeek Harness bundle, and the complete skill; it does not contain the CLI or signed Runner. Follow docs/plugins.md for each client installation path and docs/first-task.md for the first iPhone task.

Both modes require full Xcode. Standard mode currently requires macOS/iOS 27 and does not need Runner setup or development signing. Optional Runner mode requires your own Apple development certificate, private key and matching provisioning profile; setup re-signs the precompiled Runner locally. Free Personal Team onboarding and renewal are not yet validated. The Mac CLI is ad-hoc signed, without Developer ID signing or notarization.

Maintainer: publish the exact archive accepted locally. After a stable release is published, run the Homebrew Tap's Update iPhone-use workflow with the same version, then verify installation from the public download URL and Tap. Prereleases use manual installation. The attached iphone-use.rb contains the exact versioned download URL and archive checksum.