ios-sim-lease
Review or implement the planned cross-project iOS simulator lease design. Use when the user asks to build the lease helper or pool, or diagnose simulator collisions across concurrent agents. The helpe
SKILL.mdagent-marketplace/src/ios/skills/ios-sim-lease/SKILL.md
GitHubiOS Simulator Lease
Design only:
ios-sim-leaseis not implemented. Read TODO.md for implementation status and the plan. Until then, scaffolded projects use their own worktree helpers to isolate simulator state.
Current workflow
The repository-owned helper generated by ios-project-scaffold owns simulator
identities, locks, and mutable state under each project's build/ directory.
It isolates worktrees within that project, but does not coordinate simulators
across unrelated projects. For concurrent work across projects, assign separate
devices through each project's helper and report cross-project contention.
Do not introduce .ios-sim-udid; the scaffold audit rejects this retired path.
Planned design
Multiple agents may build, install, launch, and test apps on the same machine.
Without coordination, they can reuse one booted simulator and overwrite each
other's app or test state. xcrun simctl does not provide mutual exclusion.
The proposed service creates named simulator clones and leases one to each iOS
session. A shared JSON file records ownership; flock serializes access.
Pool
Create two clones for each device kind, initially supporting up to two phones and two tablets at once. Add clones if contention shows the pool is too small.
xcrun simctl create "Agents-iPhone-17-Pro-A" \
"com.apple.CoreSimulator.SimDeviceType.iPhone-17-Pro" \
"com.apple.CoreSimulator.SimRuntime.iOS-26-2"
xcrun simctl create "Agents-iPhone-17-Pro-B" \
"com.apple.CoreSimulator.SimDeviceType.iPhone-17-Pro" \
"com.apple.CoreSimulator.SimRuntime.iOS-26-2"
xcrun simctl create "Agents-iPad-Pro-13-A" \
"com.apple.CoreSimulator.SimDeviceType.iPad-Pro-13-inch-M5-12GB" \
"com.apple.CoreSimulator.SimRuntime.iOS-26-2"
xcrun simctl create "Agents-iPad-Pro-13-B" \
"com.apple.CoreSimulator.SimDeviceType.iPad-Pro-13-inch-M5-12GB" \
"com.apple.CoreSimulator.SimRuntime.iOS-26-2"
Only devices named Agents-* belong to this pool. Leave devices with other
names under human ownership.
Lease state
Store lease data and its lock at:
~/.agents/state/ios-sim-leases.json
~/.agents/state/ios-sim-leases.lock
The lock file is local runtime state and is not checked in. A lease entry has this shape:
{
"leases": [
{
"udid": "ABCD-1234-...",
"name": "Agents-iPhone-17-Pro-A",
"kind": "phone",
"owner": {
"agent": "codex",
"pid": 12345,
"cwd": "/Users/prateek/code/experiments/ios-silly-tavern",
"worktree": "ios-silly-tavern-app",
"started_at": "2026-04-10T14:05:00Z"
},
"last_heartbeat": "2026-04-10T14:12:30Z",
"ttl_minutes": 60
}
]
}
Helper interface
The planned ~/.agents/bin/ios-sim-lease Bash helper has five subcommands.
Agents use the helper; they do not edit the JSON file directly.
ios-sim-lease acquire --kind <phone|tablet> [--agent NAME] [--ttl MINUTES]
Acquire a free Agents-* device of the requested kind, boot it, and print its
UDID. Record the owner's pid, cwd, worktree, and lease times. Return exit 0 on
success or 75 (EX_TEMPFAIL) when the pool is exhausted.
ios-sim-lease release <udid>
Erase and shut down the device, then remove its lease.
ios-sim-lease heartbeat <udid>
Update last_heartbeat for an existing lease. A background process or shell
trap can call this once per minute.
ios-sim-lease list
Print current leases with their owner, age, and apparent staleness.
ios-sim-lease reap
Remove leases whose owner process is gone (kill -0) or whose heartbeat is
older than ttl_minutes; erase each reaped device. This command is intended for
a cron job or shell-startup hook.
Planned agent workflow
An agent acquires a device before iOS work and releases it afterward. Set an exit trap so an ordinary shell exit releases the lease:
UDID=$(ios-sim-lease acquire --kind phone --agent codex --ttl 60)
export IOS_SIM_UDID="$UDID"
trap 'ios-sim-lease release "$IOS_SIM_UDID"' EXIT
# ... make build / make run / make test / make audit ...
ios-sim-lease release "$UDID"
Makefile targets boot-lease and release-lease are planned wrappers, allowing
agents to run make boot-lease && make run && make release-lease.
Decisions
- Default lease TTL is 60 minutes. Reaping expired leases clears abandoned claims while preserving active long-running work.
- Release erases the simulator with
xcrun simctl erase, providing a clean session at an expected startup cost of about 2–5 seconds. - Pool devices use the
Agents-name prefix. Use hyphens; slashes confuse some simulator tools. - State lives in
~/.agents/state/. - Start with two phones and two tablets; grow the pool when contention appears.
- Use
flockonios-sim-leases.lockto serialize lease-file access.
Related material
- TODO.md tracks what exists and the implementation plan.
~/.agents/docs/ios.mdpoints to this skill for simulator leasing.ios-project-scaffoldgenerates the repository-owned worktree helper that a future global lease service must integrate with.