phone-harness 0.1.1__tar.gz

phone_harness-0.1.1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.venv/

phone_harness-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shawn pana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

phone_harness-0.1.1/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: phone-harness
+Version: 0.1.1
+Summary: Control a real iPhone through macOS iPhone Mirroring: OCR eyes, CGEvent hands
+Project-URL: Homepage, https://phone-harness.com
+Project-URL: Repository, https://github.com/ShawnPana/phone-harness
+Project-URL: Issues, https://github.com/ShawnPana/phone-harness/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,automation,iphone,iphone-mirroring,macos
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pyobjc-framework-applicationservices
+Requires-Dist: pyobjc-framework-cocoa
+Requires-Dist: pyobjc-framework-quartz
+Requires-Dist: pyobjc-framework-vision
+Description-Content-Type: text/markdown
+
+# Phone Harness 📱
+
+**[phone-harness](https://phone-harness.com)** · let your agent control your phone.
+
+Connect an AI agent — Claude Code, Codex, or any LLM — directly to your real
+iPhone with a thin, editable harness. No jailbreak, no Xcode, no WebDriverAgent.
+
+The Mac's iPhone Mirroring window is the whole transport: `screencapture` +
+Vision-framework OCR for eyes, HID-level CGEvents for hands. Nothing between the
+agent and the phone. The agent writes what's missing during execution in
+`agent-workspace/agent_helpers.py`.
+
+```
+  ● agent: wants to open Weather
+  │
+  ● ocr() → "Weather" at (400, 468)
+  │
+  ● tap(400, 468) → wait_stable() → ocr() confirms the forecast
+  ✓ done
+```
+
+**Your phone, driven by an agent.**
+
+## Setup prompt
+
+Paste into Claude Code or Codex:
+
+```text
+Set up phone-harness for me. Clone https://github.com/ShawnPana/phone-harness
+into ~/.phone-harness (its canonical home) and read `install.md` first to install
+it and connect it to my real iPhone
+through the macOS iPhone Mirroring app — install it so `phone-harness` is a
+command on my PATH, and register it as an agent skill named phone-harness using
+`phone-harness skill` as the body, so you reach for it automatically. Then read
+`SKILL.md` for normal usage, and always read `src/phone_harness/helpers.py`
+because that is where the functions are. Whenever you capture or verify the
+screen, activate the iPhone Mirroring window so I can see what you're doing on
+the phone.
+
+Setup needs two things only I can do: pairing iPhone Mirroring with my phone
+once, and granting the terminal Accessibility + Screen Recording in System
+Settings — walk me through those and wait for me. Verify with
+`./phone-harness --doctor`.
+
+After it's installed, as a quick demo that interaction works, go to my Home
+Screen and — if the phone is connected and unlocked — ask me whether you should
+open the Weather app as a harmless test; only open it if I say yes. If the
+session is paused or the phone is locked, just tell me the doctor status instead.
+```
+
+The agent will walk you through the two things only you can do: **pairing**
+iPhone Mirroring with your phone once (the pairing prompts need the physical
+phone), and granting the terminal **Accessibility** (taps & keystrokes) and
+**Screen Recording** (seeing the phone) in System Settings → Privacy &
+Security. Screen Recording takes effect after the terminal restarts;
+Accessibility is immediate. Then `./phone-harness --doctor` verifies the whole
+chain.
+
+These are the permissions currently known to be required. A fresh machine may
+prompt for more the first time an action runs — if `--doctor` passes but taps or
+capture silently do nothing, watch for a macOS permission prompt. See
+[install.md](install.md) for details.
+
+## Why this works
+
+iPhone Mirroring (macOS Sequoia+) renders the phone as a Mac window and forwards
+real mouse and keyboard input as touches. That gives an agent everything it
+needs for real-device iOS automation:
+
+- **See** — capture just the mirroring window, OCR it with Apple's Vision
+  framework: every visible string with a tap-ready coordinate. The poor man's
+  DOM.
+- **Act** — CGEvents posted at the HID tap: taps, long-presses, drags/flicks,
+  scroll gestures, unicode typing, and the app's own shortcuts (Cmd+1 Home,
+  Cmd+2 App Switcher, Cmd+3 Spotlight).
+- **Verify** — screenshot again. No DOM means the capture is the ground truth.
+
+Things that do NOT work, learned the hard way: AppleScript `click at` (silently
+ignored — the window is a video stream with no accessibility tree), unicode key
+payloads (mirroring forwards raw HID keycodes, so typing must use keycodes), a
+slow touch-drag (barely moves an iOS list — use wheel scroll for lists, a fast
+flick for pages), and input while the window isn't frontmost (swallowed).
+
+## Usage
+
+```bash
+./phone-harness <<'PY'
+open_app("Notes")
+tap_text("New Note")
+type_text("hello from the harness")
+print([o["text"] for o in ocr()][:10])
+PY
+```
+
+Day-to-day workflow lives in [SKILL.md](SKILL.md), which [install.md](install.md)
+registers as an agent skill (`phone-harness skill` prints the body) so the agent
+reaches for it on its own.
+
+## Architecture
+
+- `SKILL.md` — day-to-day usage (the agent-facing product surface)
+- `install.md` — permissions bootstrap and troubleshooting
+- `src/phone_harness/` — protected core (~500 lines):
+  - `mirror.py` — window discovery, focus, capture, CGEvent input
+  - `ocr.py` — Vision-framework text recognition → screen-point boxes
+  - `helpers.py` — the primitives pre-imported into scripts
+  - `admin.py` — `--doctor`
+  - `run.py` — the CLI (`exec` stdin with helpers in scope)
+- `agent-workspace/agent_helpers.py` — helper code the agent edits; auto-loaded
+  into every script's namespace
+
+The mirror transport is stateless (window bounds and captures are re-queried per
+call), so there is no daemon — every invocation is self-contained.
+
+## Development
+
+From a checkout, use `./phone-harness` to run the working tree directly:
+
+```bash
+./phone-harness <<'PY'
+print(screen_info())
+PY
+```
+
+## Limits
+
+- One phone, one session; unlocking the physical phone pauses mirroring.
+- No multi-touch (no pinch), no camera/Face ID flows, DRM video renders black.
+- OCR sees text, not semantics — unlabeled icons need a screenshot + a
+  vision-capable model.

phone_harness-0.1.1/README.md

@@ -0,0 +1,130 @@
+# Phone Harness 📱
+
+**[phone-harness](https://phone-harness.com)** · let your agent control your phone.
+
+Connect an AI agent — Claude Code, Codex, or any LLM — directly to your real
+iPhone with a thin, editable harness. No jailbreak, no Xcode, no WebDriverAgent.
+
+The Mac's iPhone Mirroring window is the whole transport: `screencapture` +
+Vision-framework OCR for eyes, HID-level CGEvents for hands. Nothing between the
+agent and the phone. The agent writes what's missing during execution in
+`agent-workspace/agent_helpers.py`.
+
+```
+  ● agent: wants to open Weather
+  │
+  ● ocr() → "Weather" at (400, 468)
+  │
+  ● tap(400, 468) → wait_stable() → ocr() confirms the forecast
+  ✓ done
+```
+
+**Your phone, driven by an agent.**
+
+## Setup prompt
+
+Paste into Claude Code or Codex:
+
+```text
+Set up phone-harness for me. Clone https://github.com/ShawnPana/phone-harness
+into ~/.phone-harness (its canonical home) and read `install.md` first to install
+it and connect it to my real iPhone
+through the macOS iPhone Mirroring app — install it so `phone-harness` is a
+command on my PATH, and register it as an agent skill named phone-harness using
+`phone-harness skill` as the body, so you reach for it automatically. Then read
+`SKILL.md` for normal usage, and always read `src/phone_harness/helpers.py`
+because that is where the functions are. Whenever you capture or verify the
+screen, activate the iPhone Mirroring window so I can see what you're doing on
+the phone.
+
+Setup needs two things only I can do: pairing iPhone Mirroring with my phone
+once, and granting the terminal Accessibility + Screen Recording in System
+Settings — walk me through those and wait for me. Verify with
+`./phone-harness --doctor`.
+
+After it's installed, as a quick demo that interaction works, go to my Home
+Screen and — if the phone is connected and unlocked — ask me whether you should
+open the Weather app as a harmless test; only open it if I say yes. If the
+session is paused or the phone is locked, just tell me the doctor status instead.
+```
+
+The agent will walk you through the two things only you can do: **pairing**
+iPhone Mirroring with your phone once (the pairing prompts need the physical
+phone), and granting the terminal **Accessibility** (taps & keystrokes) and
+**Screen Recording** (seeing the phone) in System Settings → Privacy &
+Security. Screen Recording takes effect after the terminal restarts;
+Accessibility is immediate. Then `./phone-harness --doctor` verifies the whole
+chain.
+
+These are the permissions currently known to be required. A fresh machine may
+prompt for more the first time an action runs — if `--doctor` passes but taps or
+capture silently do nothing, watch for a macOS permission prompt. See
+[install.md](install.md) for details.
+
+## Why this works
+
+iPhone Mirroring (macOS Sequoia+) renders the phone as a Mac window and forwards
+real mouse and keyboard input as touches. That gives an agent everything it
+needs for real-device iOS automation:
+
+- **See** — capture just the mirroring window, OCR it with Apple's Vision
+  framework: every visible string with a tap-ready coordinate. The poor man's
+  DOM.
+- **Act** — CGEvents posted at the HID tap: taps, long-presses, drags/flicks,
+  scroll gestures, unicode typing, and the app's own shortcuts (Cmd+1 Home,
+  Cmd+2 App Switcher, Cmd+3 Spotlight).
+- **Verify** — screenshot again. No DOM means the capture is the ground truth.
+
+Things that do NOT work, learned the hard way: AppleScript `click at` (silently
+ignored — the window is a video stream with no accessibility tree), unicode key
+payloads (mirroring forwards raw HID keycodes, so typing must use keycodes), a
+slow touch-drag (barely moves an iOS list — use wheel scroll for lists, a fast
+flick for pages), and input while the window isn't frontmost (swallowed).
+
+## Usage
+
+```bash
+./phone-harness <<'PY'
+open_app("Notes")
+tap_text("New Note")
+type_text("hello from the harness")
+print([o["text"] for o in ocr()][:10])
+PY
+```
+
+Day-to-day workflow lives in [SKILL.md](SKILL.md), which [install.md](install.md)
+registers as an agent skill (`phone-harness skill` prints the body) so the agent
+reaches for it on its own.
+
+## Architecture
+
+- `SKILL.md` — day-to-day usage (the agent-facing product surface)
+- `install.md` — permissions bootstrap and troubleshooting
+- `src/phone_harness/` — protected core (~500 lines):
+  - `mirror.py` — window discovery, focus, capture, CGEvent input
+  - `ocr.py` — Vision-framework text recognition → screen-point boxes
+  - `helpers.py` — the primitives pre-imported into scripts
+  - `admin.py` — `--doctor`
+  - `run.py` — the CLI (`exec` stdin with helpers in scope)
+- `agent-workspace/agent_helpers.py` — helper code the agent edits; auto-loaded
+  into every script's namespace
+
+The mirror transport is stateless (window bounds and captures are re-queried per
+call), so there is no daemon — every invocation is self-contained.
+
+## Development
+
+From a checkout, use `./phone-harness` to run the working tree directly:
+
+```bash
+./phone-harness <<'PY'
+print(screen_info())
+PY
+```
+
+## Limits
+
+- One phone, one session; unlocking the physical phone pauses mirroring.
+- No multi-touch (no pinch), no camera/Face ID flows, DRM video renders black.
+- OCR sees text, not semantics — unlabeled icons need a screenshot + a
+  vision-capable model.

phone_harness-0.1.1/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: phone-harness
+description: "Control the user's iPhone through the Mac's iPhone Mirroring window: open apps, tap, type, swipe, read the screen."
+---
+
+# phone-harness
+
+Direct iPhone control via the iPhone Mirroring app — screenshots + Vision OCR
+for eyes, HID-level CGEvents for hands. For task-specific edits, use
+`agent-workspace/agent_helpers.py`. For setup or permission problems, read
+`install.md`.
+
+## When Not to Use
+
+If the task is doable on the Mac or the web — a website, an API, an app with a
+web equivalent — do it there and leave the phone alone. Use phone-harness only
+when the task genuinely needs the phone: iOS-only apps, things tied to the
+user's phone number or 2FA, testing how something looks on the phone.
+
+## Usage
+
+```bash
+phone-harness <<'PY'
+print(screen_info())
+PY
+```
+
+- Invoke as `phone-harness`. Use heredocs for multi-line commands.
+- Helpers are pre-imported. All coordinates are global screen points.
+- `ensure_mirroring()` launches and focuses the window; input helpers focus it
+  automatically before posting events.
+
+## Screen Workflow
+
+- Prefer `ocr()` over eyeballing screenshots: every visible string comes back
+  with a tap-ready center point — `[{text, confidence, x, y, w, h}]`. Filter
+  in Python before printing.
+- Tap by label: `tap_text("Weather")`. On failure it raises with what IS
+  visible, so read the exception before retrying.
+- Icons without labels: `screenshot()`, view the image, compute the point
+  (image px ÷ scale + window origin — `screen_info()` has both sizes), then
+  `tap(x, y)`.
+- **Verify after every action**: `wait_stable()` then `ocr()`/`screenshot()`.
+  There is no DOM to assert against; the capture is the ground truth.
+- Navigation: `home()`, `app_switcher()`, `open_app("Notes")` (Spotlight),
+  `swipe("up")`, `scroll()`, `type_text("...")`, `press("return")`,
+  `long_press(x, y)`.
+- **Scrolling a list**: use `scroll_collect(extract, key=...)` to walk a list
+  to its true end, de-duping as it goes — it returns `{items, stop, scrolls}`
+  where `stop` is `'reached-end'` or `'max-scrolls'`. Use `scroll_until(done)`
+  to stop when a predicate on the visible OCR is met. Both decide "done" from
+  whether the **screen actually moved**, not from whether your parser found
+  new rows — a dense screen or a missed OCR line will not end the scroll
+  early. Each step settles first so lazy-loaded content arrives before the
+  movement check. `scroll_screen()` is the single-step primitive if you need
+  it. These use wheel scrolling (a slow touch-drag barely moves an iOS list
+  and bounces back).
+- Raw Quartz is the escape hatch: `import Quartz` in your script for anything
+  the helpers don't cover.
+
+## Consent
+
+This is the user's real phone. Stop and ask before anything outward-facing or
+hard to reverse: sending a message, posting, purchasing, deleting, changing
+settings. Navigating and reading for the user's own task is fine, but don't
+linger in personal content (Messages, Photos, Mail) beyond what the task needs.
+
+## Connection is the user's job
+
+The harness never connects the phone for you. Connecting or resuming mirroring
+is a physical action — opening the app, approving the prompt, and (crucially)
+**locking the iPhone when it says "iPhone in Use"** — that only the user can do.
+
+`ensure_mirroring()` gates every task on this: if the phone isn't connected it
+raises a clear message (call `connection_state()` yourself to check —
+`ready` / `blocked` / `no-window` / `not-running`). When you hit that:
+
+- **STOP and relay the message. Ask the user to connect the phone themselves.**
+- **Never** tap `Connect` / `Continue`, and **never** loop-poll waiting for the
+  connection. Tapping Connect while the phone is unlocked does nothing, and
+  polling just burns time — the only fix is the user locking/connecting the
+  phone. Retry once *after they confirm they've done it*, not before.
+
+## Gotchas
+
+- **Unfocused input is swallowed silently.** The window must be frontmost;
+  helpers call `activate()` but if a click steals focus mid-task, re-activate.
+- **The window is a video stream.** macOS accessibility sees nothing inside
+  it; AppleScript `click at` fails silently. Only HID-level CGEvents work.
+- **The window moves.** Never cache coordinates across calls; `ocr()` and
+  `swipe()` re-query bounds every time.
+- **Unlocking the physical phone pauses the session** ("iPhone in Use"). Do not
+  tap through the resume screen — stop and ask the user to lock/connect the
+  phone (see "Connection is the user's job").
+- **`type_text` needs an iOS text field focused first** — tap the field, wait
+  for the keyboard, then type.
+- **Home-Screen labels are not tap targets.** `tap_text("Weather")` hits the
+  label and nothing happens; the icon is ~35 points above it. Use
+  `tap_icon("Weather")` (agent helper) on the Home Screen; `tap_text` works
+  fine for in-app buttons and list rows.
+- Mouse taps map to touches 1:1, but there is no multi-touch: no pinch, no
+  two-finger gestures.

phone_harness-0.1.1/install.md

@@ -0,0 +1,93 @@
+# phone-harness install
+
+Use once. For phone work, read `SKILL.md`.
+
+## Requirements
+
+- macOS Sequoia+ with iPhone Mirroring paired to the phone (open the app once
+  manually to pair — pairing prompts need the physical phone).
+- Python 3.12+ with pyobjc (`pip install pyobjc-framework-Quartz
+  pyobjc-framework-Vision pyobjc-framework-AppKit`).
+- The terminal app needs two permissions in System Settings > Privacy &
+  Security. **The toggles require the user:**
+  - **Accessibility** — taps and keystrokes. Takes effect immediately.
+  - **Screen Recording** — seeing the phone. Takes effect after the terminal
+    app restarts.
+
+Open the panes directly:
+
+```bash
+open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
+open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
+```
+
+> **Heads up — you may need to grant more than these two.** Accessibility and
+> Screen Recording are the permissions we *know* are required, and they're all
+> `--doctor` currently checks. But this was built on a machine that was already
+> permissive, so a fresh Mac may prompt for additional approvals the first time
+> an action runs. If `--doctor` passes but taps, typing, or capture silently do
+> nothing, watch for a macOS permission prompt and check System Settings >
+> Privacy & Security for a pane asking to approve your terminal. As we pin down
+> exactly which extra permissions a clean install needs, they'll get added to
+> `--doctor` as proper prerequisites.
+
+## Fast Path
+
+```bash
+git clone https://github.com/ShawnPana/phone-harness ~/.phone-harness   # canonical home
+cd ~/.phone-harness
+pip install pyobjc-framework-Quartz pyobjc-framework-Vision pyobjc-framework-AppKit
+pip install -e . --no-deps            # installs the global `phone-harness` command
+
+# register as an agent skill so Claude Code / Codex auto-use it (see below)
+mkdir -p ~/.claude/skills/phone-harness
+phone-harness skill > ~/.claude/skills/phone-harness/SKILL.md
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/phone-harness"
+phone-harness skill > "${CODEX_HOME:-$HOME/.codex}/skills/phone-harness/SKILL.md"
+
+phone-harness --doctor
+phone-harness <<'PY'
+print(screen_info())
+PY
+```
+
+If `screen_info()` prints window bounds, you're done.
+
+`~/.phone-harness` is the canonical home — a hidden folder in your home
+directory (like `~/.oh-my-zsh` or `~/.nvm`), so the code, `helpers.py`,
+`SKILL.md`, and your `agent-workspace/` always live at a path the agent knows,
+on any machine. `pip install -e .` keeps that source editable while giving you a
+`phone-harness` command on PATH, which is what lets the skill call
+`phone-harness` from any directory. Because the install is editable it's bound
+to that location, so keep the folder at `~/.phone-harness` (or re-run `pip
+install -e .` if you relocate it). If your Python can't reach PyPI to resolve the
+pyobjc deps, `--no-deps` skips them (they're installed by the line above).
+
+## Register as a skill
+
+So the agent reaches for phone-harness on its own, register `SKILL.md` as a
+skill named `phone-harness` with `phone-harness skill` as its body (the Fast
+Path does this for both Claude Code and Codex). The skill's trigger is:
+
+```text
+Control the user's iPhone through the Mac's iPhone Mirroring window: open apps,
+tap, type, swipe, read the screen.
+```
+
+Re-run the `phone-harness skill > …/SKILL.md` lines after pulling updates so the
+registered copy stays current.
+
+## If It Fails
+
+`--doctor` walks the ladder in order: pyobjc → Accessibility → Screen
+Recording → app installed → app running → window found → capture works → OCR
+works. Fix the first FAIL; later checks depend on earlier ones.
+
+Common cases:
+
+- **Capture is blank/black**: Screen Recording was granted but the terminal
+  hasn't restarted since.
+- **Window not found**: the phone isn't paired, isn't in range, or iPhone
+  Mirroring shows a connect screen — open the app manually once.
+- **Taps do nothing**: Accessibility missing, or another window stole focus —
+  events land only when the mirroring window is frontmost.

phone_harness-0.1.1/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "phone-harness"
+version = "0.1.1"
+description = "Control a real iPhone through macOS iPhone Mirroring: OCR eyes, CGEvent hands"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = ["iphone", "automation", "agent", "iphone-mirroring", "macos"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: MacOS X",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "pyobjc-framework-Quartz",
+    "pyobjc-framework-Vision",
+    "pyobjc-framework-Cocoa",
+    "pyobjc-framework-ApplicationServices",
+]
+
+[project.urls]
+Homepage = "https://phone-harness.com"
+Repository = "https://github.com/ShawnPana/phone-harness"
+Issues = "https://github.com/ShawnPana/phone-harness/issues"
+
+[project.scripts]
+phone-harness = "phone_harness.run:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/phone_harness"]
+
+# The skill text ships inside the package so `phone-harness skill` works
+# from an installed wheel, not only from a checkout.
+[tool.hatch.build.targets.wheel.force-include]
+"SKILL.md" = "phone_harness/SKILL.md"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/phone_harness", "SKILL.md", "README.md", "LICENSE", "install.md"]

phone_harness-0.1.1/src/phone_harness/admin.py

@@ -0,0 +1,70 @@
+"""Diagnostics: `phone-harness --doctor` walks the permission/session ladder."""
+import os, subprocess, sys, tempfile
+from pathlib import Path
+
+
+def _check(label, ok, hint=""):
+    mark = "PASS" if ok else "FAIL"
+    print(f"  [{mark}] {label}" + (f" — {hint}" if not ok and hint else ""))
+    return ok
+
+
+def run_doctor():
+    print("phone-harness doctor\n")
+    ok = True
+
+    try:
+        import Quartz, Vision, AppKit  # noqa: F401
+        ok &= _check("pyobjc frameworks (Quartz, Vision, AppKit)", True)
+    except ImportError as e:
+        _check("pyobjc frameworks", False,
+               f"pip install pyobjc-framework-Quartz pyobjc-framework-Vision ({e})")
+        return 1
+
+    from ApplicationServices import AXIsProcessTrusted
+    ok &= _check(
+        "Accessibility permission (taps & keystrokes)", AXIsProcessTrusted(),
+        "System Settings > Privacy & Security > Accessibility: enable your terminal")
+
+    import Quartz as Q
+    ok &= _check(
+        "Screen Recording permission (seeing the phone)",
+        bool(Q.CGPreflightScreenCaptureAccess()),
+        "System Settings > Privacy & Security > Screen Recording: enable your terminal")
+
+    from . import mirror
+    ok &= _check(f"{mirror.APP_NAME} installed", Path(mirror.APP_PATH).exists(),
+                 "requires macOS Sequoia+ with a paired iPhone")
+
+    running = mirror.running_app() is not None
+    _check(f"{mirror.APP_NAME} running", running,
+           "will auto-launch on first use — not fatal")
+
+    win = mirror.find_window()
+    _check("mirroring window found", win is not None,
+           "open iPhone Mirroring once manually to pair the phone")
+
+    if win:
+        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
+            path = f.name
+        try:
+            subprocess.run(
+                ["screencapture", "-x", "-o", "-l", str(win["id"]), path],
+                check=True)
+            size = os.path.getsize(path)
+            ok &= _check(f"window capture works ({size} bytes)", size > 20_000,
+                         "capture is blank — Screen Recording permission "
+                         "needs a terminal restart to take effect")
+            if size > 20_000:
+                from . import ocr
+                n = len(ocr.recognize(path, win))
+                _check(f"Vision OCR works ({n} text boxes)", True)
+        finally:
+            os.unlink(path)
+
+    print("\nall clear" if ok else "\nfix the FAILs above, then re-run")
+    print("\nnote: these are the permissions currently known to be required. A "
+          "fresh\nmachine may still prompt for more the first time an action "
+          "runs — approve\nthem in System Settings if a step silently does "
+          "nothing despite this passing.")
+    return 0 if ok else 1