Maestro Manager

Daemonless iOS Maestro test runner with a shared simulator pool. The CLI creates named simulator slots, leases them to concurrent test runs, and records run state under the current pool prefix.

Prerequisites

• macOS with Xcode command line tools and simulator support available through xcrun simctl.
• Bun >=1.4.0 and Node.js >=24.16.0.
• Maestro installed on PATH as maestro.
• A built iOS .app bundle and Maestro flow YAML files.

Install dependencies:

bun install

Configuration

Create maestro-manager.config.json at the repo root, pass it with --config <path>, or set MAESTRO_MANAGER_CONFIG=<path>. Without either override, the CLI walks up from the current directory until it finds the config.

Minimal shape:

{
  "pool": {
    "prefix": "my-project-e2e",
    "deviceType": "iPhone 16",
    "default": 2,
    "max": 4
  },
  "app": {
    "appId": "com.example.MyApp",
    "glob": "~/Library/Developer/Xcode/DerivedData/*/Build/Products/*-iphonesimulator/*.app",
    "searchDirs": ["~/Library/Developer/Xcode/DerivedData"]
  },
  "flowsDir": "maestro/flows",
  "warmupDeepLink": "myapp://e2e/warmup",
  "java": {
    "home": null,
    "autodetect": ["JAVA_HOME", "mise", "/usr/libexec/java_home"]
  },
  "recordingsDir": "recordings",
  "hooks": {
    "pruneAccounts": ""
  }
}

Notes:

• pool.prefix becomes part of simulator names and the state path. Keep it project-specific and safe: start with a letter or number, then use only letters, numbers, dots, underscores, and hyphens.
• pool.default is the normal warm pool size. pool.max is the hard concurrency cap and must be <= 8. Keep pool.max <= 4 until the downstream project has proved its backend is stable at the higher concurrency. Concurrent test runs may temporarily boot lanes through pool.max. When the final active run completes, the manager shuts down only idle overflow lanes until pool.default simulators remain warm. The slots stay available for later reuse.
• flowsDir, recordingsDir, and entries in app.searchDirs resolve relative to the config file directory, with ~ expanded.
• App resolution order is --app, then app.path, then app.glob, then scanning app.searchDirs for the newest .app matching app.appId. app.glob supports * and ? within path segments and ~ expansion.
• hooks.pruneAccounts is an optional shell command run by clean --prune-accounts.

Common Workflows

Warm the default simulator pool:

maestro-manager up --app path/to/MyApp.app

By default, simulators boot headless: Maestro can run against them without opening Simulator.app. Use --headed when you want to watch the pool or a run:

maestro-manager up --headed --app path/to/MyApp.app
maestro-manager test --headed --sims 2

--headless is also accepted explicitly and conflicts with --headed.

Show pool slots, active leases, and recent runs:

maestro-manager status

Run all configured flows on two simulators:

maestro-manager test --sims 2

If demand expands the pool above pool.default, passing and test-failing runs both trigger a final convergence pass. The pass defers while any lease, queued waiter, or full-suite reservation is active, so work in other worktrees is not interrupted. It does not replace clean --idle-shutdown: automatic convergence only shuts down idle overflow above pool.default, while explicit idle cleanup retains its configured age-based behavior.

Stop this worktree's active leases but keep the pool:

maestro-manager stop

Reclaim stale leases and shut down idle simulators:

maestro-manager clean --idle-shutdown 30

clean runs a stateless reaper, even with no flags:

• Reap orphaned runs. When a test worker is SIGKILLed or crashes, no signal trap fires, so its detached maestro process group — and the simulator's (often hung) app — keep running and burning CPU. The stale-lease reclaim deliberately refuses to reclaim such a slot while its maestro child is still alive (so it never yanks a simulator a live run is driving). clean detects this case — owner dead, heartbeat stale, maestro still alive — kills the orphaned maestro group, shuts the simulator down (killing the hung app), and reclaims the slot.
• Reclaim stale leases whose owner and maestro child are both dead, shutting those simulators down too.

Live-leased simulators (a live owner) are never touched.

Add --delete-unavailable to also run xcrun simctl delete unavailable, removing broken-runtime CoreSimulator devices left behind by Xcode upgrades, removed runtimes, or other tools. This is global — it is NOT scoped to this pool's prefix — so it is opt-in and off by default:

maestro-manager clean --idle-shutdown 30 --delete-unavailable

Stop all leases, delete pool simulators, and clear pool state:

maestro-manager down

test runs all .yaml and .yml files in flowsDir when no flow paths are provided. Use --include-tags and --exclude-tags for manager-side tag selection, and put Maestro passthrough arguments after a literal --.

State And Logs

State is scoped by pool.prefix under:

~/.maestro-manager/<prefix>

Important paths include:

• config-snapshot.json for the last config snapshot written by up.
• sims/<sim-name>/udid, lastused, and lease/record.json for pool slots and lease ownership.
• waiters/<runId>/ticket.json for queued work.
• runs/index.json, runs/<runId>/run.json, and runs/<runId>/<flow>.log for run history and per-flow Maestro output.

maestro-manager down runs stop --all, deletes all pool simulators it can resolve, then removes ~/.maestro-manager/<prefix>.

Verification

Production modules live under src/. Each executable suite mirrors its owning module under tests/ and adds the .test.ts suffix—for example, src/pool/convergence.ts is covered by tests/pool/convergence.test.ts. Reusable fixtures and helpers live under tests/support/.

Run the full local check:

bun run check

Run the no-excuse audit baseline check:

bash scripts/check-no-excuse-baseline.sh src