Skip to content

Commit 2045a8b

Browse files
feat(remote): rn-iso ios --remote, a device that is not on this machine
The build stays here. The fingerprint, the shared cache and single-flight builds are the reason rn-iso is fast and none of them care where the device is, so `--remote` moves ONLY the device. The seam already existed. DEFAULT_DEPS in commands/ios.ts is documented as "the test seam. Every engine call goes through it", and five of its entries are the whole device surface. Remote mode replaces those and nothing else, so the local path is not refactored, every phase line is unchanged, and no existing test moved. engine/device-remote.ts supplies the replacements. The ordering property survives with opposite mechanics: locally the Metro gate sits between a cheap ensureOwnedDevice and a slow ensureBooted, and remote inverts which step is expensive, so ensureOwnedDevice records intent only and the billable session is created in ensureBooted, still after the gate. The token never reaches disk. The connection profile under .rn-iso/ carries routing only, per agent-device ADR 0007, and the token travels as an env var on each child. state.json holds the session id alone, and eas simulator:get re-reads the token when it is needed. stop DESTROYS a remote session, which is the one exception to "stop never deletes": a shut-down simulator costs nothing to keep, a cloud session bills until its cap. A failed stop keeps the record and exits non-zero, matching how a failed local teardown keeps its device record. rn-iso does not drive metro prepare. agent-device connect owns Metro preparation and disconnect stops the companion, so the cloud simulator reaches this laptop's bundler without rn-iso running a second tunnel. Because it is the same Metro process, the verify phase keeps working unchanged. The dev-client deep link is composed here rather than left to agent-device's Metro hint, which writes bare-RN RCT_jsLocation only and which a dev-client ignores (callstack/agent-device#1245). `open <app> <url>` runs simctl openurl verbatim, so rn-iso's own link works without the upstream fix. Scope: iOS only, and no native device logs. agent-device captures with --style compact while rn-iso's parser needs ndjson, so the collector cannot port until that is opt-in upstream. The Metro half of the timeline is local and unaffected. Known gap, recorded in CLAUDE.md and the spec: gc and worktree remove do not sweep remote sessions yet.
1 parent 4707493 commit 2045a8b

15 files changed

Lines changed: 1160 additions & 37 deletions

‎CLAUDE.md‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -342,7 +342,8 @@ composes, never one it inferred from a package.json script. Nothing reads
342342
fixed and it does not grow:
343343

344344
start --json --wait
345-
ios / android --json --no-metro-check
345+
ios --json --no-metro-check --remote
346+
android --json --no-metro-check
346347
logs --source --level --since --grep --tail --follow --errors --json
347348
stop --json --force
348349

@@ -353,6 +354,29 @@ same reason. A project needing something outside this set wraps rn-iso in a
353354
script of its own — one the repo writes and owns, since rn-iso no longer
354355
generates one.
355356

357+
`--remote` is the one deliberate addition since this list was written, and it
358+
is recorded here rather than left to drift. It does not reconstruct anything
359+
and it does not widen what rn-iso builds: the build, the fingerprint and the
360+
cache are identical, and the flag moves ONLY the device (see
361+
`docs/specs/2026-08-26-remote-device-backend-design.md`). It earns its place
362+
because the resource it relieves -- how many simulators one machine can host
363+
-- is the same class of contended resource as the Metro port, which rn-iso
364+
already brokers. Note the asymmetry with `android`, which does not have it
365+
yet.
366+
367+
**Remote is also the one exception to "`stop` never deletes."** A local device
368+
is shut down and kept, because keeping it costs nothing. A remote session
369+
bills until its max duration, so `stop` ENDS it. A failed stop keeps the
370+
record and exits non-zero, for the same reason a failed local teardown does:
371+
the record is the only handle left to retry with.
372+
373+
NOT YET DONE, and a real leak until it is: `gc` and `worktree remove` do not
374+
sweep remote sessions. `reclaim.js` is the shared path both go through and is
375+
where it belongs, alongside a `gc` sweep over
376+
`eas simulator:list --name rn-iso- --status new,in-progress`. Until that
377+
lands, a worktree removed without a `stop` first leaves a session billing
378+
until its two-hour cap.
379+
356380
`--base` is the counter-example worth remembering: it accepted only the two
357381
sentinels `fresh` and `head`, and widening it to any ref `git rev-parse`
358382
resolves is NOT the surface growing. The flag already existed, the plumbing

‎docs/specs/2026-08-26-remote-device-backend-design.md‎

Lines changed: 52 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -48,28 +48,42 @@ Worth stating first, because it is most of the system.
4848
provider, and single-flight builds. The `.app` is the same artifact.
4949
- The Metro supervisor and port reservation. Metro stays local.
5050
- `commands/ios.ts`'s phase sequence. Every phase keeps its name and its
51-
order. Only the callee behind three of them changes.
51+
order. Only the callee behind the device phases changes.
5252
- The state file, its lock, and the config lock.
5353

5454
## The seam
5555

5656
Three modules reach for a device today. They become one interface.
5757

58-
| Module | Local | Remote |
59-
| --- | --- | --- |
60-
| `engine/device.ts` `ensureOwnedDevice` | `simctl create` / `boot` | `eas sim` session create |
61-
| `engine/app-install.ts` `installIosApp` | `simctl install` | `agent-device install <path>` |
62-
| `engine/app-install.ts` `launchIosApp` | `simctl openurl` / `launch` | `agent-device open <app> <url>` |
63-
| `collector/ios.ts` | `simctl spawn log stream` | not in v1, see Logs |
64-
65-
`engine/device-backend.ts` declares the interface. The local implementation
66-
wraps today's functions and changes none of their behaviour. Selection is a
67-
`--remote` flag on `rn-iso ios`, plus an `ios.remote` key in settings, which
68-
must also be added to `KNOWN_SETTINGS` in `settings.ts` or it silently
69-
becomes a no-op.
70-
71-
The command surface stays closed at eleven commands. A remote device is a
72-
property of the device, not a new verb.
58+
| Module | Local | Remote |
59+
| --------------------------------------- | --------------------------- | ------------------------------- |
60+
| `engine/device.ts` `ensureOwnedDevice` | `simctl create` / `boot` | `eas sim` session create |
61+
| `engine/app-install.ts` `installIosApp` | `simctl install` | `agent-device install <path>` |
62+
| `engine/app-install.ts` `launchIosApp` | `simctl openurl` / `launch` | `agent-device open <app> <url>` |
63+
| `collector/ios.ts` | `simctl spawn log stream` | not in v1, see Logs |
64+
65+
**The seam already existed, so no new abstraction was added.** `DEFAULT_DEPS`
66+
in `commands/ios.ts` is documented as "the test seam. Every engine call goes
67+
through it", and four of its entries are the whole device surface:
68+
`checkDeviceCapacity`, `ensureOwnedDevice`, `ensureBooted`, `installIosApp`
69+
and `launchIosApp`. Remote mode replaces those and nothing else.
70+
`engine/device-remote.ts` supplies the replacements, each matching its local
71+
counterpart's signature exactly.
72+
73+
The consequence is that the local path is not refactored at all: every call
74+
site, every phase line and every existing test is untouched, so a regression
75+
there cannot be caused by this change. An earlier draft of this spec proposed
76+
extracting a `DeviceBackend` interface; that would have been a second way to
77+
say what the dep seam already says.
78+
79+
Selection is a `--remote` flag on `rn-iso ios`, plus an `ios.remote` key in
80+
settings, which must also be added to `KNOWN_SETTINGS` in `settings.ts` or it
81+
silently becomes a no-op.
82+
83+
The command surface stays closed. A remote device is a property of the
84+
device, not a new verb. The option surface does grow by one flag, which
85+
`CLAUDE.md` says must be a deliberate decision rather than a drift: it is
86+
recorded here and in that file's option-surface list.
7387

7488
## Session lifecycle
7589

@@ -111,9 +125,13 @@ rn-iso keeps owning Metro, and the cloud simulator reaches it through
111125
agent-device's companion tunnel. That tunnel is a detached local process
112126
which dials **outward** to the daemon and registers rn-iso's local Metro. The
113127
daemon exposes it to the simulator on a device-side port. No inbound firewall
114-
hole and no third-party tunnel service. rn-iso calls it with `reuseExisting`
115-
pointed at the reserved port, so agent-device never starts a competing
116-
bundler.
128+
hole and no third-party tunnel service.
129+
130+
rn-iso does NOT drive `metro prepare` itself. `agent-device connect` defers
131+
and then performs Metro preparation, and `disconnect` releases the lease and
132+
stops the companion it owns. rn-iso passes `metroProjectRoot` in the
133+
connection profile and lets agent-device own the tunnel; a second driver
134+
would fight it.
117135

118136
The consequence worth naming: **`verify` keeps working unchanged.** Its check
119137
is "did a bundle request reach _this workspace's_ Metro", and with the tunnel
@@ -169,10 +187,21 @@ implementation.
169187

170188
## Teardown, gc, doctor
171189

172-
`teardown.ts` gains `teardownRemoteSession(sessionId)` beside
173-
`teardownOwnedIosSim` and `teardownOwnedAvd`, returning the same
174-
`TeardownOutcome`, so `stop`, `worktree remove` and `gc` need no new branching
175-
beyond picking the function.
190+
`engine/device-remote.ts` exposes `endRecordedSession({root, sessionId})`,
191+
which resolves its own eas-cli because a teardown runs long after the `ios`
192+
that created the session, in a process with none of its context.
193+
194+
**Implemented: `stop`.** It reads the `remoteDevice` record from state.json,
195+
ends the session, and drops the record only on success. A failure keeps the
196+
record and exits non-zero, matching how a failed local teardown keeps its
197+
device record: the record is the only handle left to retry with.
198+
199+
**Not implemented, and a real leak until it is: `gc` and `worktree remove`.**
200+
`reclaim.ts` is the shared path both go through and is where this belongs,
201+
together with a `gc` sweep over
202+
`eas simulator:list --name rn-iso- --status new,in-progress` for sessions
203+
whose project is gone. Until then, a worktree removed without a `stop` first
204+
leaves a session billing until its cap.
176205

177206
**`stop` will delete, and today it never does.** The documented rule is that
178207
`stop` shuts a device down and never destroys it. A cloud session bills while

‎packages/rn-iso/skill/SKILL.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,21 @@ Ten commands: `doctor` (what is silently costing build time) · `worktree create
109109

110110
That is all of it. There is no `init` -- repo setup is the `rn-iso-init` skill applying `doctor`'s findings by hand, and the one safe generated edit (`.rn-iso/` in `.gitignore`) is self-ensured by `start`/`ios`/`android`. There is also no `up`, no `release`, no `shutdown`, no `config`, no `build-cache`, no `worktree list` -- `status` covers the last one, `ios`/`android` absorbed the build cache, settings are files (`guide settings`), and destruction consolidated into `worktree remove` and `gc --delete`. Run `npx rn-iso <command> --help` for flags, or `npx rn-iso guide` for the reference.
111111

112+
## A remote simulator (`--remote`)
113+
114+
`ios --remote` installs and launches on a simulator that is not on this machine. **The build still runs here** -- the fingerprint, the shared cache and single-flight builds are unchanged, and only the device moves. Reach for it when the machine runs out of simulators before it runs out of work, not as a default: a cloud session is billable, and a local device is faster.
115+
116+
It needs `agent-device` on PATH, plus one of:
117+
118+
- **`AGENT_DEVICE_DAEMON_BASE_URL` + `AGENT_DEVICE_DAEMON_AUTH_TOKEN` in the environment.** rn-iso uses that daemon and creates no session of its own. This is the `agent-device proxy` case, and it is also how you attach to a session someone else started.
119+
- **Nothing.** rn-iso creates an EAS Simulator session itself (`eas sim`, named `rn-iso-<label>`, bounded to two hours), which needs eas-cli and an account with EAS Simulator access.
120+
121+
`ios.remote: true` in settings does the same thing as the flag, per project or per repo.
122+
123+
**`stop` DESTROYS a remote session**, unlike a local device which it only shuts down. A session bills until its max duration, so leaving one running is the worse failure. If the stop fails, the command exits non-zero and keeps the record so you can retry -- do not ignore that.
124+
125+
**There are no device logs on a remote device yet.** `logs --source device` is empty because the collector is local-only. The Metro half -- JS errors, redboxes, bundling failures -- is unaffected and is where nearly everything useful comes from anyway. `--errors` still works and still means what it says.
126+
112127
## When things go wrong
113128

114129
- **A build failed.** Read the extracted diagnostic rn-iso printed, not the log. The full transcript is in `.rn-iso/logs/build-<platform>.ndjson` if you genuinely need it -- it holds this run only (each build starts the file over), and it is almost never worth the tokens. The failure carries a code (`RN_ISO_BUILD_FAILED`, `RN_ISO_DEPS_FAILED`, ...) -- `npx rn-iso guide errors` maps every one to a remedy.

‎packages/rn-iso/src/__tests__/agent-device.test.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -72,20 +72,20 @@ describe('argv', () => {
7272
// connection, which is exactly the collision rn-iso exists to prevent.
7373
for (const args of [
7474
connectArgs(profilePath),
75-
installArgs(profilePath, 'com.example.app', '/tmp/My App.app'),
75+
installArgs(profilePath, '/tmp/My App.app'),
7676
openArgs(profilePath, 'com.example.app', null),
7777
disconnectArgs(profilePath),
7878
]) {
7979
expect(args[args.indexOf('--remote-config') + 1]).toBe(profilePath);
8080
}
8181
});
8282

83-
test('install names the bundle id and the path as separate argv elements', () => {
84-
// A .app path with a space in it must reach the tool as one argument.
85-
const args = installArgs(profilePath, 'com.example.app', '/tmp/My App.app');
83+
test('install passes the .app path as one literal argv element', () => {
84+
// A .app path with a space in it must reach the tool as one argument,
85+
// and the bundle id is not repeated: the .app already carries it.
86+
const args = installArgs(profilePath, '/tmp/My App.app');
8687
expect(args[0]).toBe('install');
87-
expect(args[1]).toBe('com.example.app');
88-
expect(args[2]).toBe('/tmp/My App.app');
88+
expect(args[1]).toBe('/tmp/My App.app');
8989
});
9090

9191
test('open with a dev-client url passes it as the url positional', () => {

0 commit comments

Comments
 (0)