Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
858a63e
test: iOS sources live in a folder as long as the device set, an owne…
V3RON Nov 15, 2026
914083a
feat(ios): sources live in an owned folder as long as the device set …
V3RON Nov 15, 2026
e145cf1
test: iOS is refused sources-path-unfit where no sources folder can h…
V3RON Nov 15, 2026
1da3680
feat(ios): iOS is refused sources-path-unfit where the sources folder…
V3RON Nov 15, 2026
607f90e
test: a seed or a leftover row naming another set is deleted there an…
V3RON Nov 15, 2026
8dbedb4
feat(ios): a seed in another set is deleted there and made again in t…
V3RON Nov 15, 2026
4818a31
test: converge stores a baseline's stale reason at startup (#1569)
V3RON Nov 15, 2026
73230b5
feat(core): an old baseline is stale from the first request after sta…
V3RON Nov 15, 2026
adc6b75
test: switching deviceSet with sources left in either setting's sourc…
V3RON Nov 15, 2026
1df9f4f
feat(ios): switching deviceSet refuses sources left in either setting…
V3RON Nov 15, 2026
86bb59a
feat(e2e): the slow lane's homes sit under $HOME/.sls and find the so…
V3RON Nov 15, 2026
2e5c072
refactor(ios): sources-folder and staleness helpers and their tests l…
V3RON Nov 15, 2026
3208f29
refactor(ios): sourcesFolderFor stays inside its file (#1569)
V3RON Nov 15, 2026
202be77
test(core): a baseline's stale reason is stored before the warm pool …
V3RON Nov 15, 2026
701deb2
fix(ios): own seeds never read as the other setting's leftovers, old-…
V3RON Nov 15, 2026
3a08797
refactor(ios): the earlier-sources-folder check lives in sources-fold…
V3RON Nov 15, 2026
2c6d716
fix(e2e): a connected agent-device agent names its session (agent-dev…
V3RON Nov 15, 2026
7e4bb3d
Merge remote-tracking branch 'origin/feature/1561-adr' into HEAD
V3RON Nov 15, 2026
086c5f4
chore(hygiene): the iOS driver index may be 2702 lines (#1569)
V3RON Nov 15, 2026
262f004
fix(e2e): the lane home's restore keeps the adb server's record, so t…
V3RON Nov 15, 2026
7f69b7f
test: the first provision of a kind makes its seed from a throwaway (…
V3RON Nov 16, 2026
559c6de
feat(ios): a seed is copied unbooted from a throwaway that booted onc…
V3RON Nov 16, 2026
98fd35a
test: a seed's throwaway under the default set carries marks and Devi…
V3RON Nov 16, 2026
2eb80b9
feat(ios): under the default set a seed's throwaway carries marks and…
V3RON Nov 16, 2026
07abda9
test: a failed seed make deletes its throwaway and a stray log folder…
V3RON Nov 16, 2026
c0e9c78
test: listManaged leaves out a throwaway a making row names (#1569)
V3RON Nov 16, 2026
680e6ff
feat(ios): listManaged leaves out a throwaway a making row names (#1569)
V3RON Nov 16, 2026
64fc83b
test: a restart mid-make deletes the throwaway, its log folder, the s…
V3RON Nov 16, 2026
c2a1811
test: baseline.save deletes the saved-from lease's log folder (#1569)
V3RON Nov 16, 2026
c510c5b
feat(ios): baseline.save deletes the saved-from lease's log folder (#…
V3RON Nov 16, 2026
ce017e1
test: a seed table's upgrade test follows its owner's version (#1569)
V3RON Nov 16, 2026
41b38a8
chore: supersede the closed #1573 design on this branch (#1569)
V3RON Nov 16, 2026
dcbbc6a
Merge remote-tracking branch 'origin/feature/1561-adr' into task/1569
V3RON Nov 16, 2026
9862f55
test: a failed seed make is proven to delete the seed clone (#1569)
V3RON Nov 16, 2026
0dcd651
fix: a throwaway UDID that is not a UDID is refused before its log fo…
V3RON Nov 16, 2026
31359f6
docs(ios): the iOS driver manual fits its size limit (#1569)
V3RON Nov 16, 2026
6167890
refactor(ios): a failed seed make's undo is its own helper (#1569)
V3RON Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/daemon/driver-discovery.ts
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,7 @@ async function discoverIosDriver(
idGenerator: options.idGenerator,
instanceId: options.instanceId,
logger: logger.child("ios"),
logsRoot: `${homedir()}/Library/Logs/CoreSimulator`,
onSilenceFailed: logSilenceFailure(logger),
onWindowFailed: logWindowFailure(logger),
onSlimmed: emitSlimDiagnostic(options.eventBus),
Expand Down
2 changes: 1 addition & 1 deletion src/daemon/state-owners.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ describe("the seed tables' one-ready-seed-per-kind index (#1367)", () => {
state.database
.prepare("SELECT version FROM schema_versions WHERE owner = ?")
.get(owner.name),
).toEqual({ version: 2 });
).toEqual({ version: owner.version });
expect(
state.database
.prepare(`SELECT source_id, kind, state FROM ${table} ORDER BY source_id`)
Expand Down
50 changes: 25 additions & 25 deletions src/drivers/ios/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# iOS driver

Does: simulators in an owned `simctl` device set, slimmed on request, and USB iPhones and iPads through `devicectl`.
Does: simulators in an owned `simctl` device set, slimmed on request, and USB iPhones and iPads via `devicectl`.
Flows: [device selection](../../../docs/internal/flows/device-selection.md), [drivers](../AGENTS.md), [input](input/AGENTS.md).

## Rules
Expand All @@ -9,55 +9,55 @@ The device set:

- Under `drivers.ios.deviceSet: simlock`, never `simctl` without `--set`, except three unscoped calls: `findLegacy`, `destroyLegacy`, and the read-only `simctl list -j devices` of `listComponents`.
- Under `default` (ADR 0048) the set is Xcode's own: never `--set`, no owned root, and never act on a device whose durable mark does not name this instance. `listManaged` lists only those, and `findLegacy` answers `undefined`.
- `ios.simulator.headless: false` needs `default`: the `simlock` set has no DeviceHub, so iOS is refused (`invalid-device-set`). Simulators left in the set being given up refuse iOS too (`device-set-changed`); that check reads files only, never `simctl`.
- The erasable mark is written before the durable one, never both at once. Under `default` a failed mark write deletes the new simulator before the error is rethrown.
- `ios.simulator.headless: false` needs `default`: the `simlock` set has no DeviceHub, so iOS is refused (`invalid-device-set`). Simulators left in the set given up refuse iOS too (`device-set-changed`); that check reads files only.
- The erasable mark is written before the durable one, never both at once. Under `default` a failed mark write deletes the new simulator first.

Resolve and boot:

- A slim spec is returned only for a slim request the driver will slim. The registry is the only record of a device's mode.
- A slim spec is returned only for a slim request the driver will slim. The registry alone records a device's mode.
- `RuntimeMissingError` is only for what a download can fix: an OS outside the device type's range, an installed runtime not paired with the type, and anything below iOS 16 are refused instead.
- A boot is `simctl boot`, `bootstatus -b`, then `listapps` until it succeeds, on one deadline: bootstatus can finish before the installer accepts requests.
- Slim (ADR 0060), on `prepare` of a slim spec only: the managed labels are merged into the simulator's `disabled.plist` before the boot (other entries kept; a failed write is logged and the boot goes on), and `launchctl print-disabled system` is read back after it. A label not as written returns `full`; a readback that fails returns `slim`; both call `onSlimSkipped`, logged only. Every label as written and the write ok: `slim`, and `onSlimmed` becomes `device.slimmed`.
- Slim `except` (ADR 0066, `slim-except.ts`): an excepted category's labels are written `false`; an unknown name is `BAD_REQUEST`; a kept label not read back throws `KeptCategoriesError`.
- A recovery boot writes no slim overrides and reads nothing back. DeviceHub clipboard isolation is configured before preparation and recovery boots; ready default-set simulators reboot under the lease claim before a grant. Active leases at upgrade are not interrupted and may retain clipboard sync until a later boot or lease end.
- A recovery boot writes no slim overrides and reads nothing back. DeviceHub clipboard isolation is configured before preparation and recovery boots; ready default-set simulators reboot under the lease claim before a grant. Active leases at upgrade keep clipboard sync until a later boot or lease end.
- The overrides folder lives outside the device set (`launchdOverridesRoot`), so `destroy` removes it itself after `simctl delete`.
- After every boot and before the readback, `runAfterBoot` (`boot-courtesies.ts`) runs the volume step, then the window step. Each only reports its failure (`onSilenceFailed`, `onWindowFailed`), and the device stays in use.
- Volume (`ios.simulator.audio: false`): Apps keep playing at volume 0. A baseline source is not silenced.
- Window (`ios.simulator.headless: false`): DeviceHub is opened in the background, so the front app stays in front, and is told not to shut down started devices when it quits. Only a non-zero exit of that open means DeviceHub is missing: Simulator.app is then opened instead, detached, so quitting it leaves the simulator running.
- After every boot and before the readback, `runAfterBoot` (`boot-courtesies.ts`) runs the volume step, then the window step. Each only reports its failure (`onSilenceFailed`, `onWindowFailed`).
- Volume (`ios.simulator.audio: false`): apps play at volume 0. A baseline source is not silenced.
- Window (`ios.simulator.headless: false`): DeviceHub is opened in the background (the front app stays in front) and told not to shut down started devices when it quits. Only a non-zero exit of that open means DeviceHub is missing: Simulator.app is then opened instead, detached, so quitting it leaves the simulator running.

Seeds (ADR 0061):

- A simulator is a clone of its kind's seed. A seed is known by its `ios_source_data` row, never by name, and lives in the sources set: `sources` in the owned set, an owned root of its own under `default`. It is in no `listManaged` or `simlock simctl list`.
- Every clone (a seed's copy, `saveSource`'s own clone, a `provision` with `source`) has its `data/var/db/lsd/com.apple.LaunchServices-*.csstore` deleted before its first boot: it records each app, system apps included, under the original device's folder. A clone whose drop fails is deleted.
- A seed is made from a throwaway (ADR 0076): `simlock-seed-<id>` is booted once, shut down, cloned unbooted into the sources set, then deleted with its log folder (`logsRoot`); `saveSource` deletes the saved-from lease's log folder too. A log folder that cannot be deleted is logged and the make or save goes on; a throwaway that cannot be deleted fails the make. Only its `making` row (`throwaway_udid`) deletes a throwaway, at the first `listSources` of a later process or the next make of its kind.
- Every clone (a seed's copy, `saveSource`'s own clone, a `provision` with `source`) has its `data/var/db/lsd/com.apple.LaunchServices-*.csstore` deleted before its first boot: it records each app under the original device's folder. A clone whose drop fails is deleted.
- Two provisions of a kind make one seed; clones of a seed and its deletion take turns.
- A `clone` or `create` waits `ios.simulator.createTimeoutMs`. At the limit it fails but `simctl` runs on: the UDID it later prints is deleted, the seed's deletion waits for it, and one silent 5 minutes more is killed and logged.
- A `making` row of another process is swept at the first `listSources`; one of this process, once older than any make takes, at the next make of its kind.
- A seed that `simctl delete` reports as `Invalid device` is already gone, so its row is dropped.
- `removeComponent` deletes the runtime's seeds first.
- A seed that `simctl delete` calls `Invalid device` is already gone: its row is dropped. `removeComponent` deletes the runtime's seeds first.

Physical, passthrough, screen:

- `devicectl` over `device.exec` is an allow-list (`devicectlExecCommand`): what is not on the reviewed list is refused, and so is every option that names a host path.
- Screen (`screen-capture.ts`): stdout is the frames, stdin the program's liveness, and closing stdin is the stop. Key frames keep coming on a still screen. The daemon's own `SIMLOCK_IOS_DEVICE_SET` and `SIMLOCK_COREDEVICE_INFO_PLIST` reach neither program; the driver sets the first for a simulator under `simlock` only.
- An iPhone below iOS 27 is `ScreenUnavailableError`; an unreadable version goes on. The iPhone program enforces its CoreDevice pin itself: another major exits 69 with the reason, a 503 for the viewer.
- Screen (`screen-capture.ts`): stdout is the frames, stdin the program's liveness, and closing stdin is the stop. Key frames keep coming on a still screen. The daemon's own `SIMLOCK_IOS_DEVICE_SET` and `SIMLOCK_COREDEVICE_INFO_PLIST` reach neither program; the driver sets the first for a `simlock`-set simulator only.
- An iPhone below iOS 27 is `ScreenUnavailableError`; an unreadable version goes on. The iPhone program enforces its CoreDevice pin: another major exits 69, a 503 for the viewer.

Tunnels (`device-tcp.ts`):

- A simulator has no network of its own: its sockets are the worker's loopback sockets. A listener is the lease's only when a word of its process's environment is exactly `SIMULATOR_UDID=<the lease's UDID>`, checked on every connection.
- `reverse` listens on the device port itself on both loopbacks, and is refused `TUNNEL_PORT_IN_USE` when anything already answers on either, a wildcard listener included.
- `reverse` listens on the device port itself on both loopbacks, and is refused `TUNNEL_PORT_IN_USE` when anything answers on either, a wildcard listener included.
- No rule sits on a simulator: `sweep` does nothing, and a `reverse`'s `close` sets `holdsDeviceRule: false`, so a lease end with an aborted signal still runs it.

## Known gaps

- **A restart between `simctl clone` and the durable mark under `default` (#968)** leaves one unlisted `simlock-<id>` simulator in Xcode's set. Delete it with `xcrun simctl delete <udid>`.
- **Runtime downloads outlive deletion (#79).** Simlock reports retained assets; reclaim them in Xcode → Settings → Platforms.
- **Slim costs (#87, #172).** Below iOS 18.5 a slim request gets `full`. Slim devices lose push, Spotlight, StoreKit, universal links, Siri, iCloud sync. Use `--mode full` when a test needs them.
- **The overrides file is an undocumented CoreSimulator file.** If Apple ignores it, the readback grants `full`.
- **A recovered slim device runs full but its record says `slim` (#174)** until its next `makeReady`.
- **A restart between `simctl clone` and the durable mark under `default` (#968)** leaves one unlisted `simlock-<id>` simulator in Xcode's set. Delete it with `simctl delete`.
- **Runtime downloads outlive deletion (#79).** Reclaim them in Xcode → Settings → Platforms.
- **Slim costs (#87, #172).** Below iOS 18.5 a slim request gets `full`. Slim devices lose push, Spotlight, StoreKit, universal links, Siri, iCloud sync; use `--mode full` for them.
- **The overrides file is undocumented.** If Apple ignores it, the readback grants `full`.
- **A recovered slim device runs full but is recorded `slim` (#174)** until its next `makeReady`.
- **A cold slim lease takes a full cold boot.** MCP clients need a longer timeout.
- **A screen stream can freeze after a reboot under its lease.** The capture checks the simulator is booted only at start, so after a crash reboot the viewer sees the old picture until the Screen tab is reopened.
- **An iPhone's rotation has not run on hardware**; only a Duo's panel switch is proven. A silent iPhone shows its last picture until the lease ends.
- **A foldable's stream follows SpringBoard's `DisplayContentMode` log** (ADR 0075): another wording leaves it on the panel picked at open, and taps with it; a tap sent between a fold and the new size lands on the panel left.
- **A capture killed by SIGKILL cannot stop its CoreDevice stream**; CoreDevice is left to notice its client is gone. The same for a stop while `startMediaStream` is still running past its limit.
- **A new Xcode major turns iPhone streams off** until `vendor/screen-capture/Stubs/` is checked against that release and the pin moves.
- **Untested on an iPhone:** DeviceHub or Xcode showing the same device during a stream; the holder's `devicectl` commands during one; the source ending after the first picture; `stop()` really stopping the stream.
- **A screen stream can freeze after a reboot under its lease.** The capture checks the boot only at start: after a crash reboot the old picture stays until the Screen tab is reopened.
- **An iPhone's rotation has not run on hardware**; only a Duo's panel switch is proven. A silent iPhone keeps its last picture.
- **A foldable's stream follows SpringBoard's `DisplayContentMode` log** (ADR 0075): another wording leaves it, and taps, on the panel picked at open; a tap between a fold and the new size lands on the old panel.
- **A capture killed by SIGKILL cannot stop its CoreDevice stream**, and neither can a stop while `startMediaStream` runs past its limit.
- **A new Xcode major turns iPhone streams off** until `vendor/screen-capture/Stubs/` is checked against it and the pin moves.
- **Untested on an iPhone:** DeviceHub or Xcode showing the same device during a stream; the holder's `devicectl` commands during one; the source ending after the first picture; `stop()` ending the stream.
2 changes: 2 additions & 0 deletions src/drivers/ios/driver-options.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ export interface IosSimctlDriverOptions {
/** why: the daemon's pid is named in the staging directory of a new root. */
readonly pid?: number;
readonly coreSimulatorRoot?: string;
// why: where CoreSimulator keeps each simulator's log folder, which `simctl delete` leaves behind; with none given the driver deletes no log folder.
readonly logsRoot?: string;
// why: where launchd_sim keeps each simulator's overrides folder; a test points it elsewhere.
readonly launchdOverridesRoot?: string;
readonly onSlimmed?: (fact: SlimmedFact) => void;
Expand Down
23 changes: 15 additions & 8 deletions src/drivers/ios/index-device-set.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ import {
seededDatabase,
simctlPassthrough,
spec,
throwawayUdid,
} from "./test-index.js";

describe("IosSimctlDriver device set", () => {
Expand Down Expand Up @@ -75,13 +76,18 @@ describe("IosSimctlDriver device set", () => {
{
args: ["create", "simlock-seed-device-1", driverData.deviceTypeId, driverData.runtimeId],
scoped: true,
sources: true,
stdout: `${throwawayUdid}\n`,
},
{ args: ["boot", throwawayUdid], scoped: true },
{ args: ["bootstatus", throwawayUdid, "-b"], scoped: true },
{ args: ["listapps", throwawayUdid], scoped: true },
{ args: ["shutdown", throwawayUdid], scoped: true },
{
args: ["clone", throwawayUdid, "simlock-seed-device-1", sourcesSet],
scoped: true,
stdout: `${seedUdid}\n`,
},
{ args: ["boot", seedUdid], scoped: true, sources: true },
{ args: ["bootstatus", seedUdid, "-b"], scoped: true, sources: true },
{ args: ["listapps", seedUdid], scoped: true, sources: true },
{ args: ["shutdown", seedUdid], scoped: true, sources: true },
{ args: ["delete", throwawayUdid], scoped: true },
{
args: ["clone", seedUdid, driverData.name, devicesDir],
scoped: true,
Expand Down Expand Up @@ -109,9 +115,9 @@ describe("IosSimctlDriver device set", () => {
: ["simctl", ...step.args];
const runner = new ScriptedProcessRunner(
steps.flatMap((step) => [
...(!scoped && step.args[0] === "boot" && step.sources !== true
...(!scoped && step.args[0] === "boot" && step.args[1] !== seedUdid
? deviceHubEdit(
`Set :DevicePreferences:${driverData.udid}:pasteboardSyncEnabled false`,
`Set :DevicePreferences:${String(step.args[1])}:pasteboardSyncEnabled false`,
).map((match) => ({ match }))
: []),
{
Expand All @@ -121,14 +127,15 @@ describe("IosSimctlDriver device set", () => {
: { result: { code: 0, stderr: "", stdout: step.stdout } }),
},
...(!scoped && step.args[0] === "delete"
? deviceHubEdit(`Delete :DevicePreferences:${driverData.udid}`).map((match) => ({
? deviceHubEdit(`Delete :DevicePreferences:${String(step.args[1])}`).map((match) => ({
match,
}))
: []),
]),
);
const filesystem = new MemoryFilesystem();
await plantDevice(filesystem, devicesDir);
await filesystem.mkdirp(`${devicesDir}/${throwawayUdid}/data`);
if (scoped) await plantManagedDevice(filesystem);
const driver = await IosSimctlDriver.create({
database: await memorySourceDatabase(),
Expand Down
Loading
Loading