sim-mirror 2.0.0__tar.gz → 2.0.1__tar.gz

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: sim-mirror
-Version: 2.0.0
-Summary: Mirror and drive the iOS Simulator from Claude Code, CLI agents and the browser.
+Version: 2.0.1
+Summary: Mirror and drive iOS Simulators and real iPhones from Claude Code, CLI agents and the browser.
 Project-URL: Homepage, https://github.com/AndrewKochulab/sim-mirror
 Project-URL: Documentation, https://github.com/AndrewKochulab/sim-mirror/tree/main/docs
 Project-URL: Issues, https://github.com/AndrewKochulab/sim-mirror/issues
@@ -39,7 +39,7 @@ Description-Content-Type: text/markdown
 
 # SimMirror
 
-**Mirror and drive the iOS Simulator from Claude Code, CLI agents and the browser.**
+**Mirror and drive iOS Simulators and real iPhones from Claude Code, CLI agents and the browser.**
 
 [![CI](https://github.com/AndrewKochulab/sim-mirror/actions/workflows/ci.yml/badge.svg)](https://github.com/AndrewKochulab/sim-mirror/actions/workflows/ci.yml)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
@@ -52,9 +52,10 @@ through its notes, then fills in and saves a new one, the agent's cursor gliding
 *A real session, sped up four times. [The whole recording](https://github.com/AndrewKochulab/sim-mirror/releases/download/v1.2.0/sim-mirror-plugin-demo.mp4)
 runs 1m 39s.*
 
-A live iOS Simulator in any browser tab or web page, an animated cursor that shows exactly what your AI agent is about
-to tap, and token-efficient UI snapshots so agents read the screen as compact text instead of screenshots. Works with
-Claude Code, Codex, Cursor and any other MCP client.
+A live iOS Simulator -- or your own iPhone, over its cable -- in any browser tab or web page, an animated cursor that
+shows exactly what your AI agent is about to tap, and token-efficient UI snapshots so agents read the screen as compact
+text instead of screenshots. Record any screen as an MP4 or a GIF for a pull request. Works with Claude Code, Codex,
+Cursor and any other MCP client.
 
 > **Status: 2.0.** The agent tools, the viewer, the protocol and the embedding API are stable, and a check holds every
 > release to [what SimMirror promises not to break](docs/stability.md). 2.0 brings real iPhones and iPads beside the
@@ -71,6 +72,9 @@ Claude Code, Codex, Cursor and any other MCP client.
   in batches with waits, and reach for a screenshot only when a question is visual.
 - **Read screens accessibility cannot.** A game or a canvas reads from its pixels, and an app under development can
   share its own views, so icon-only buttons and hand-drawn controls read by name.
+- **Test on a real iPhone.** Plug it in and it sits beside the simulators: live over the cable at up to 60 fps, touched
+  and typed on from the browser or by an agent, and given back everything SimMirror changed on it.
+- **Show what happened.** Record a flow as an MP4 or a GIF with every touch drawn in, and put it in a pull request.
 
 ## Install
 
@@ -84,7 +88,7 @@ Claude Code, Codex, Cursor and any other MCP client.
 **Any MCP client**, as a stdio server:
 
 ```sh
-claude mcp add sim-mirror -- uvx --from sim-mirror==2.0.0 sim-mirror mcp
+claude mcp add sim-mirror -- uvx --from sim-mirror==2.0.1 sim-mirror mcp
 ```
 
 Configurations for [Codex](docs/clients/codex.md), [Cursor](docs/clients/cursor.md) and
@@ -93,7 +97,7 @@ Configurations for [Codex](docs/clients/codex.md), [Cursor](docs/clients/cursor.
 **The command**, for `sim-mirror open`, `doctor` and the rest:
 
 ```sh
-uv tool install sim-mirror==2.0.0
+uv tool install sim-mirror==2.0.1
 # or
 brew install andrewkochulab/tap/sim-mirror
 ```
@@ -103,8 +107,8 @@ brew install andrewkochulab/tap/sim-mirror
 [on PyPI](https://pypi.org/project/sim-mirror/) and in a [Homebrew tap](https://github.com/AndrewKochulab/homebrew-tap).
 
 **Requirements:** an Apple Silicon Mac, Xcode 26 or later, and [uv](https://docs.astral.sh/uv/) or Homebrew. Nothing
-else: SimMirror drives a simulator with its own helper, which comes in the package. Details in
-[Installation](docs/installation.md).
+else: SimMirror drives a simulator with its own helper, which comes in the package. A real iPhone needs Developer Mode,
+and an Apple development team to be touched. Details in [Installation](docs/installation.md).
 
 ## Quickstart
 
@@ -118,6 +122,12 @@ Then ask your agent:
 > Open Settings → General → About and tell me which iOS version this simulator runs. Use sim_snapshot rather than
 > screenshots.
 
+With an iPhone plugged in, unlocked and in Developer Mode:
+
+> Switch to my iPhone, build and run the app on it, walk through sign-up and record it as a GIF.
+
+The first time, press **Set up touch** in the viewer: it builds WebDriverAgent with your project's own signing team.
+
 [Getting started](docs/getting-started.md) explains what happens along the way.
 
 ## Features
@@ -143,10 +153,11 @@ in a Debug build on the simulator it shares its own UIKit and SwiftUI views, so
 gesture or a hand-drawn control reads by name, and `.simMirror("Settings")` names a SwiftUI view. Optional, and nothing
 of it is in a Release build. See [The app SDK](docs/app-sdk.md).
 
-**Real devices.** A cabled iPhone or iPad shows up beside the simulators: its live screen over the cable, its apps,
-logs, look and location through Xcode's `devicectl`, and touching, typing and its element tree through a WebDriverAgent
-you build with your own team. What SimMirror changes on it is put back when it is let go. See
-[Real devices](docs/real-devices.md).
+**Real devices.** A cabled iPhone or iPad shows up beside the simulators, and an agent can switch to it
+(`sim_device list` and `choose`): its live screen over the cable, at about 55 frames a second; its apps, logs, look and
+location through Xcode's `devicectl`; and touching, typing and its element tree through WebDriverAgent, set up once
+with a click and signed by your project's own team -- a tap lands in about a third of a second. It is reached only over
+the cable, and what SimMirror changes on it is put back when it is let go. See [Real devices](docs/real-devices.md).
 
 **Recording.** The viewer's Record button, `sim_record` or `sim-mirror record` keep a device's screen as an MP4, a GIF
 or both, with each touch drawn where it landed and a 9:41 status bar. See [Recording](docs/recording.md).
@@ -206,8 +217,8 @@ an image at about 750 pixels a token).
 Rows checked on real hardware are marked verified, with the date, in [Compatibility](docs/compatibility.md).
 
 From 1.0 the tools, the protocol, the embedding API, the viewer package, settings and the command line are held to
-[what SimMirror promises not to break](docs/stability.md): a release adds, and never breaks; 2.0 broke nothing. Connectors are the
-exception, and pin a minor version.
+[what SimMirror promises not to break](docs/stability.md): a release adds, and never breaks; 2.0 broke nothing.
+Connectors are the exception, and pin a minor version.
 
 ## Documentation
 

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/README.md

@@ -2,7 +2,7 @@
 
 # SimMirror
 
-**Mirror and drive the iOS Simulator from Claude Code, CLI agents and the browser.**
+**Mirror and drive iOS Simulators and real iPhones from Claude Code, CLI agents and the browser.**
 
 [![CI](https://github.com/AndrewKochulab/sim-mirror/actions/workflows/ci.yml/badge.svg)](https://github.com/AndrewKochulab/sim-mirror/actions/workflows/ci.yml)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
@@ -15,9 +15,10 @@ through its notes, then fills in and saves a new one, the agent's cursor gliding
 *A real session, sped up four times. [The whole recording](https://github.com/AndrewKochulab/sim-mirror/releases/download/v1.2.0/sim-mirror-plugin-demo.mp4)
 runs 1m 39s.*
 
-A live iOS Simulator in any browser tab or web page, an animated cursor that shows exactly what your AI agent is about
-to tap, and token-efficient UI snapshots so agents read the screen as compact text instead of screenshots. Works with
-Claude Code, Codex, Cursor and any other MCP client.
+A live iOS Simulator -- or your own iPhone, over its cable -- in any browser tab or web page, an animated cursor that
+shows exactly what your AI agent is about to tap, and token-efficient UI snapshots so agents read the screen as compact
+text instead of screenshots. Record any screen as an MP4 or a GIF for a pull request. Works with Claude Code, Codex,
+Cursor and any other MCP client.
 
 > **Status: 2.0.** The agent tools, the viewer, the protocol and the embedding API are stable, and a check holds every
 > release to [what SimMirror promises not to break](docs/stability.md). 2.0 brings real iPhones and iPads beside the
@@ -34,6 +35,9 @@ Claude Code, Codex, Cursor and any other MCP client.
   in batches with waits, and reach for a screenshot only when a question is visual.
 - **Read screens accessibility cannot.** A game or a canvas reads from its pixels, and an app under development can
   share its own views, so icon-only buttons and hand-drawn controls read by name.
+- **Test on a real iPhone.** Plug it in and it sits beside the simulators: live over the cable at up to 60 fps, touched
+  and typed on from the browser or by an agent, and given back everything SimMirror changed on it.
+- **Show what happened.** Record a flow as an MP4 or a GIF with every touch drawn in, and put it in a pull request.
 
 ## Install
 
@@ -47,7 +51,7 @@ Claude Code, Codex, Cursor and any other MCP client.
 **Any MCP client**, as a stdio server:
 
 ```sh
-claude mcp add sim-mirror -- uvx --from sim-mirror==2.0.0 sim-mirror mcp
+claude mcp add sim-mirror -- uvx --from sim-mirror==2.0.1 sim-mirror mcp
 ```
 
 Configurations for [Codex](docs/clients/codex.md), [Cursor](docs/clients/cursor.md) and
@@ -56,7 +60,7 @@ Configurations for [Codex](docs/clients/codex.md), [Cursor](docs/clients/cursor.
 **The command**, for `sim-mirror open`, `doctor` and the rest:
 
 ```sh
-uv tool install sim-mirror==2.0.0
+uv tool install sim-mirror==2.0.1
 # or
 brew install andrewkochulab/tap/sim-mirror
 ```
@@ -66,8 +70,8 @@ brew install andrewkochulab/tap/sim-mirror
 [on PyPI](https://pypi.org/project/sim-mirror/) and in a [Homebrew tap](https://github.com/AndrewKochulab/homebrew-tap).
 
 **Requirements:** an Apple Silicon Mac, Xcode 26 or later, and [uv](https://docs.astral.sh/uv/) or Homebrew. Nothing
-else: SimMirror drives a simulator with its own helper, which comes in the package. Details in
-[Installation](docs/installation.md).
+else: SimMirror drives a simulator with its own helper, which comes in the package. A real iPhone needs Developer Mode,
+and an Apple development team to be touched. Details in [Installation](docs/installation.md).
 
 ## Quickstart
 
@@ -81,6 +85,12 @@ Then ask your agent:
 > Open Settings → General → About and tell me which iOS version this simulator runs. Use sim_snapshot rather than
 > screenshots.
 
+With an iPhone plugged in, unlocked and in Developer Mode:
+
+> Switch to my iPhone, build and run the app on it, walk through sign-up and record it as a GIF.
+
+The first time, press **Set up touch** in the viewer: it builds WebDriverAgent with your project's own signing team.
+
 [Getting started](docs/getting-started.md) explains what happens along the way.
 
 ## Features
@@ -106,10 +116,11 @@ in a Debug build on the simulator it shares its own UIKit and SwiftUI views, so
 gesture or a hand-drawn control reads by name, and `.simMirror("Settings")` names a SwiftUI view. Optional, and nothing
 of it is in a Release build. See [The app SDK](docs/app-sdk.md).
 
-**Real devices.** A cabled iPhone or iPad shows up beside the simulators: its live screen over the cable, its apps,
-logs, look and location through Xcode's `devicectl`, and touching, typing and its element tree through a WebDriverAgent
-you build with your own team. What SimMirror changes on it is put back when it is let go. See
-[Real devices](docs/real-devices.md).
+**Real devices.** A cabled iPhone or iPad shows up beside the simulators, and an agent can switch to it
+(`sim_device list` and `choose`): its live screen over the cable, at about 55 frames a second; its apps, logs, look and
+location through Xcode's `devicectl`; and touching, typing and its element tree through WebDriverAgent, set up once
+with a click and signed by your project's own team -- a tap lands in about a third of a second. It is reached only over
+the cable, and what SimMirror changes on it is put back when it is let go. See [Real devices](docs/real-devices.md).
 
 **Recording.** The viewer's Record button, `sim_record` or `sim-mirror record` keep a device's screen as an MP4, a GIF
 or both, with each touch drawn where it landed and a 9:41 status bar. See [Recording](docs/recording.md).
@@ -169,8 +180,8 @@ an image at about 750 pixels a token).
 Rows checked on real hardware are marked verified, with the date, in [Compatibility](docs/compatibility.md).
 
 From 1.0 the tools, the protocol, the embedding API, the viewer package, settings and the command line are held to
-[what SimMirror promises not to break](docs/stability.md): a release adds, and never breaks; 2.0 broke nothing. Connectors are the
-exception, and pin a minor version.
+[what SimMirror promises not to break](docs/stability.md): a release adds, and never breaks; 2.0 broke nothing.
+Connectors are the exception, and pin a minor version.
 
 ## Documentation
 

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/examples/claude-code-cli/README.md

@@ -16,7 +16,7 @@ Its tools are named `mcp__plugin_sim-mirror_sim-mirror__sim_snapshot` and so on.
 ## Without the plugin
 
 ```sh
-claude mcp add sim-mirror -- uvx --from sim-mirror==2.0.0 sim-mirror mcp
+claude mcp add sim-mirror -- uvx --from sim-mirror==2.0.1 sim-mirror mcp
 ```
 
 Add `--scope project` before the name to write it to the project's `.mcp.json` for everyone working on it. Its tools
@@ -30,7 +30,7 @@ simulator (its scope) and this folder as the only place builds and installs may
 ## Watch it
 
 ```sh
-uvx --from sim-mirror==2.0.0 sim-mirror open
+uvx --from sim-mirror==2.0.1 sim-mirror open
 ```
 
 opens this folder's viewer in your browser. Every gesture the agent makes is drawn there as a cursor just before it

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/examples/codex/README.md

@@ -6,7 +6,7 @@ Add [config.toml](config.toml)'s table to `~/.codex/config.toml`, then start Cod
   and installs may reach. The commented `args` pin a project by name and path instead.
 - `tool_timeout_sec` is raised because `sim_build_run` and `sim_test` can take minutes (they are there only when build
   tools are switched on).
-- Watch and take over in a browser: `uvx --from sim-mirror==2.0.0 sim-mirror open`
+- Watch and take over in a browser: `uvx --from sim-mirror==2.0.1 sim-mirror open`
   in the same folder.
 
 The tools are the same for every client; see [claude-code-cli](../claude-code-cli/) for a first prompt to try.

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/examples/cursor/README.md

@@ -6,7 +6,7 @@ one), and enable the server in Cursor's MCP settings.
 - `sim-mirror mcp` gives the agent the simulator of the folder it starts in, and that folder as the only place builds
   and installs may reach. If the tools act on the wrong project, append `"--scope", "my-app", "--root",
   "/absolute/path/to/my-app"` to `args`.
-- Watch and take over in a browser: `uvx --from sim-mirror==2.0.0 sim-mirror open`
+- Watch and take over in a browser: `uvx --from sim-mirror==2.0.1 sim-mirror open`
   in the same folder.
 
 The tools are the same for every client; see [claude-code-cli](../claude-code-cli/) for a first prompt to try.

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/examples/fastapi-embed/README.md

@@ -5,7 +5,7 @@ A Python application with SimMirror inside it: [app.py](app.py). No daemon runs;
 
 ```sh
 cd examples/fastapi-embed
-EXAMPLE_KEY=change-me uv run --with "sim-mirror==2.0.0" \
+EXAMPLE_KEY=change-me uv run --with "sim-mirror==2.0.1" \
   uvicorn --factory app:create_app --port 7484
 ```
 

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/helper/Sources/HelperCore/Wire.swift

@@ -3,7 +3,7 @@ import Foundation
 
 /// The helper's version, which is SimMirror's: SimMirror refuses a helper of another version.
 public enum HelperVersion {
-    public static let current = "2.0.0"
+    public static let current = "2.0.1"
 }
 
 /// What a frame on the socket is.

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "sim-mirror"
 dynamic = ["version"]
-description = "Mirror and drive the iOS Simulator from Claude Code, CLI agents and the browser."
+description = "Mirror and drive iOS Simulators and real iPhones from Claude Code, CLI agents and the browser."
 readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE", "THIRD_PARTY_LICENSES.md"]

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/src/sim_mirror/_version.py

@@ -1,4 +1,4 @@
 # SPDX-License-Identifier: Apache-2.0
 """The package version, read by the build backend and by `sim-mirror version`."""
 
-__version__ = "2.0.0"
+__version__ = "2.0.1"

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/src/sim_mirror/cli/context.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 import asyncio
 import copy
 import os
+import signal
 import sys
 import webbrowser
 from collections.abc import Awaitable, Callable, Coroutine, Mapping, Sequence
@@ -80,6 +81,8 @@ class CliContext:
     opener: relay.Opener | None = None
     open_url: Callable[[str], bool] = webbrowser.open
     spawn: Spawn = process.spawn
+    #: How a process is signalled: ``os.kill``, or a test's.
+    kill: Callable[[int, int], None] = os.kill
     serve: Serve = serve_with_uvicorn
     run: Runner = process.run
     xcrun: XcrunRunner = run_xcrun
@@ -122,6 +125,15 @@ class CliContext:
     def client(self, url: str | None = None) -> DaemonClient:
         return DaemonClient(url or self.daemon_url(), self.tokens().admin_token(), opener=self.opener)
 
+    def retire_daemon(self) -> bool:
+        """Ask the daemon this user runs to stop, as ``Ctrl-C`` would: its devices keep running. Whether one was
+        running to ask."""
+        info = read_info(self.state.run_dir())
+        if info is None:
+            return False
+        self.kill(info.pid, signal.SIGTERM)
+        return True
+
     def start_daemon(self, *arguments: str) -> int:
         """Start ``sim-mirror serve`` detached, its output in the log folder. Answers its pid."""
         argv = [self.python, "-m", "sim_mirror", "serve", "--foreground", *arguments]

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/src/sim_mirror/cli/mcp.py

@@ -27,6 +27,7 @@ def run(args: argparse.Namespace, ctx: CliContext) -> int:
         roots,
         client=ctx.client(),
         start_daemon=ctx.start_daemon,
+        retire_daemon=ctx.retire_daemon,
         env=ctx.env,
         stdin=ctx.stdin,
         stdout=ctx.stdout,

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/src/sim_mirror/connectors/iphone/wda_roles.py

@@ -30,6 +30,10 @@ from sim_mirror.core.gestures import CHARACTER_KEYS, COMMAND_KEY, KEYS, SHIFT_KE
 
 #: How long the device's orientation is trusted before it is asked again.
 ORIENTATION_TTL_S = 2.0
+#: How long the element tree is waited for. A screen WebDriverAgent cannot read quickly -- a busy web page in Safari
+#: took over 30 s on an iPhone 14 Pro -- is read from its pixels instead, and a wait for it to settle is not spent
+#: waiting on one request.
+SOURCE_TIMEOUT_S = 5.0
 #: The most points a finger's stroke is sent with. WebDriverAgent looks each point up against the app on screen -- an
 #: accessibility round trip of about 240 ms -- so a stroke's points cost more than its length: measured on an iPhone 14
 #: Pro, a 0.4 s swipe took 7 to 11 s with 25 points, and 1.3 to 1.6 s with 2.
@@ -266,7 +270,7 @@ class WdaReader:
         self._screen = screen
 
     async def accessibility(self) -> dict[str, Any]:
-        source = await self._client.call("GET", "/source?format=json")
+        source = await self._client.call("GET", "/source?format=json", timeout_s=SOURCE_TIMEOUT_S)
         turn = await self._orientation.turn()
         return {
             "backend": "wda",

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/src/sim_mirror/core/actions.py

@@ -125,6 +125,9 @@ class Gesture:
 @dataclass
 class _Memory:
     snapshot: Snapshot | None = None
+    #: Whether a step played since the snapshot was taken, so what it shows may have moved or gone -- a keyboard
+    #: opened over it, a screen pushed -- and a ref is read again before it is touched.
+    stale: bool = False
     ids: itertools.count[int] = field(default_factory=lambda: itertools.count(1))
 
 
@@ -282,6 +285,7 @@ class AgentActions:
         memory.snapshot = build(
             tree, device=instance.runtime, screen=instance.screen, max_elements=max_elements, previous=memory.snapshot
         )
+        memory.stale = False
         return memory.snapshot
 
     def _announce(self, instance: DeviceInstance, caller: Caller, gesture: Gesture, lead_ms: int) -> str:
@@ -454,7 +458,8 @@ class AgentActions:
         screen = instance.screen
         assert screen is not None
         if isinstance(value, str):
-            snapshot = self._remembered(instance, caller).snapshot
+            memory = self._remembered(instance, caller)
+            snapshot = None if memory.stale else memory.snapshot
             element = snapshot.element(value) if snapshot is not None else None
             if element is None:
                 snapshot = await self._read(instance, caller, max_elements)
@@ -617,6 +622,9 @@ class AgentActions:
                 try:
                     gesture = await self._gesture(instance, caller, kind, what, step, max_elements)
                     await self._play(instance, caller, gesture, lead_ms if cursor else 0)
+                    # A ref in a later step is where the screen now has it: a step can open a keyboard over it, or
+                    # take it away, and a ref touched where it was would touch whatever is there now.
+                    self._remembered(instance, caller).stale = gesture.kind != "pause"
                 except ActionError as exc:
                     lines.append(f"error step {number}: {exc}")
                     failed = True

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/src/sim_mirror/core/recordings.py

@@ -49,6 +49,8 @@ logger = logging.getLogger(__name__)
 Format = Literal["mp4", "gif", "both"]
 FORMATS: tuple[Format, ...] = ("mp4", "gif", "both")
 SPEEDS = ("1", "1.5", "2", "4")
+#: The largest GIF GitHub shows inline in a pull request or an issue, in bytes; a larger one is only a download.
+GIF_INLINE_MAX = 10_000_000
 #: A kept recording's file name: when it began, the device's name made safe for a file, and what it is.
 FILE_NAME = re.compile(r"\A[0-9]{8}-[0-9]{6}-[a-z0-9-]{1,64}\.(mp4|gif)\Z")
 _SLUG = re.compile(r"[^a-z0-9]+")
@@ -400,6 +402,7 @@ class Recordings:
         finally:
             _forget(run.source.raw)
         files: list[RecordingFile] = [_file(made) for made in rendered]
+        notes = [*notes, *filter(None, (_too_big(file, run.options) for file in files))]
         kept: Recording = {
             "id": run.id,
             "device": run.instance.name,
@@ -490,6 +493,19 @@ def _file(made: Rendered) -> RecordingFile:
     }
 
 
+def _too_big(file: RecordingFile, options: RecordingOptions) -> str:
+    """What to do about a GIF too big for GitHub to show inline, where a recording is most often put -- or "" when it
+    is not too big."""
+    if file["format"] != "gif" or file["bytes"] <= GIF_INLINE_MAX:
+        return ""
+    faster = [speed for speed in SPEEDS if float(speed) > options.speed]
+    how = f"speed {faster[-1]}" if faster else "a shorter take"
+    return (
+        f"{file['name']} is {file['bytes'] / 1_000_000:.1f} MB, over the 10 MB GitHub shows inline: record again with "
+        f"{how} or a smaller recording.gif_width, or put the MP4 in a pull request instead"
+    )
+
+
 async def _own_status_bar(instance: DeviceInstance, control: StatusBar) -> None:
     try:
         await control.clear_status_bar(instance.udid)

{sim_mirror-2.0.0 → sim_mirror-2.0.1}/src/sim_mirror/mcp/launcher.py

@@ -3,7 +3,9 @@
 
 1. **The daemon**: asked whether it is up (``/healthz``) -- with a fresh nonce and no credential, and believed only when
    it proves it holds the admin token (`daemon.health`). When nothing answers, it is started detached and waited for,
-   up to `HEALTH_WAIT_S`; when something else answers on its port, that is refused and sent nothing.
+   up to `HEALTH_WAIT_S`; when something else answers on its port, that is refused and sent nothing. A daemon of an
+   older SimMirror -- still running after the plugin was updated -- is stopped and this version's started in its place,
+   so the tools the client is offered are this version's; its viewers and other clients reconnect by themselves.
 2. **A token**: the CLI runs as the person who installed SimMirror, so it reads the admin token and mints an agent token
    for this project's scope -- naming the folders its builds and installs may reach (``--root``). The token reaches the
    relay in its environment, never argv, and is revoked when the client goes.
@@ -25,6 +27,7 @@ from pathlib import Path
 from typing import IO, Any
 from urllib.parse import quote
 
+from sim_mirror._version import __version__
 from sim_mirror.daemon import health
 from sim_mirror.daemon.lease import RENEW_S
 from sim_mirror.mcp import relay
@@ -40,6 +43,23 @@ TOKEN_HEADER, SCOPE_HEADER, CLIENT_HEADER = "X-SimMirror-Token", "X-SimMirror-Sc
 OURS, OTHER, NOTHING = "ours", "other", "nothing"
 
 
+def version_of(server: object) -> tuple[int, ...] | None:
+    """A SimMirror version from what a daemon calls itself -- ``sim-mirror/2.0.0`` -- or None."""
+    if not isinstance(server, str) or not server.startswith("sim-mirror/"):
+        return None
+    try:
+        return tuple(int(part) for part in server.removeprefix("sim-mirror/").split("+")[0].split("."))
+    except ValueError:
+        return None
+
+
+def older(server: object, mine: str = __version__) -> bool:
+    """Whether a daemon calling itself `server` runs an older SimMirror than this one. One that says no version is
+    not called older: it is left as it is."""
+    theirs, ours = version_of(server), version_of(f"sim-mirror/{mine}")
+    return theirs is not None and ours is not None and theirs < ours
+
+
 class DaemonUnavailable(Exception):
     """The daemon could not be reached or started, said so a person knows what to do."""
 
@@ -70,6 +90,8 @@ class DaemonClient:
         self._token_id = token_id
         self._open = opener or relay.direct_opener()
         self._ours = False
+        #: What the daemon called itself when it last proved it is this user's: ``sim-mirror/<version>``.
+        self.server: str | None = None
 
     def _send(self, method: str, path: str, payload: object, headers: Mapping[str, str]) -> Any:
         data = None if payload is None else json.dumps(payload).encode("utf-8")
@@ -104,6 +126,9 @@ class DaemonClient:
             self._ours = health.proves(self._token, nonce, data.get("proof"))
         else:
             self._ours = health.token_proves(self._token, nonce, data.get("token_proof"))
+        if self._ours:
+            server = data.get("server")
+            self.server = server if isinstance(server, str) else None
         return OURS if self._ours else OTHER
 
     def healthy(self) -> bool:
@@ -174,10 +199,22 @@ def ensure_daemon(
     poll_s: float = HEALTH_POLL_S,
     clock: Callable[[], float] = time.monotonic,
     sleep: Callable[[float], None] = time.sleep,
+    retire: Callable[[], object] | None = None,
 ) -> None:
     """This user's daemon, running: started when nothing answers, and waited for. Something else on its port is
-    refused rather than started over or trusted."""
+    refused rather than started over or trusted. With `retire`, a daemon of an older SimMirror is stopped by it and
+    this version's started instead; a newer one is used as it is."""
     found = client.probe()
+    if found == OURS and retire is not None and older(client.server):
+        retire()
+        deadline = clock() + wait_s
+        while (found := client.probe()) == OURS:
+            if clock() >= deadline:
+                raise DaemonUnavailable(
+                    f"the older SimMirror daemon ({client.server}) did not stop within {wait_s:g}s; stop it, and "
+                    "this version starts in its place"
+                )
+            sleep(poll_s)
     if found == OURS:
         return
     if found == OTHER:
@@ -223,6 +260,7 @@ def run(
     *,
     client: DaemonClient,
     start_daemon: Callable[[], object],
+    retire_daemon: Callable[[], object] | None = None,
     env: Mapping[str, str] | None = None,
     stdin: IO[str] | None = None,
     stdout: IO[str] | None = None,
@@ -230,7 +268,7 @@ def run(
     opener: relay.Opener | None = None,
 ) -> int:
     """Serve MCP for this scope until the client closes stdin."""
-    ensure_daemon(client, start_daemon)
+    ensure_daemon(client, start_daemon, retire=retire_daemon)
     label = f"sim-mirror mcp (pid {os.getpid()})"
     token_id, token = client.mint_agent_token(scope.id, [str(root) for root in roots], label)
     stop = threading.Event()