@osfactory/har 0.48.0 → 0.49.0

package/README.md

@@ -14,7 +14,7 @@ HAR is an open-source, agent-agnostic framework for building multi-agent coding
   <tr>
     <td align="center">
       <a href="https://youtu.be/XKl4ZzWy7mQ">
-        <img src="https://img.youtube.com/vi/XKl4ZzWy7mQ/maxresdefault.jpg" alt="HAR introduction demo" width="540">
+        <img src="http://img.youtube.com/vi/XKl4ZzWy7mQ/maxresdefault.jpg" alt="HAR introduction demo" width="600"/>
       </a>
     </td>
   </tr>
@@ -108,7 +108,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup, the dogfood harness lo
 
 ## Sponsors
 
-HAR is sponsored by [Kerno](https://kerno.io), runtime code and security review for coding agents.
+HAR is sponsored by [Kerno](https://kerno.io), runtime code and security tester for coding agents.
 
 <p align="left">
   <a href="https://kerno.io">

package/dist/templates/har-boilerplate/provision-toolchain.sh

@@ -30,7 +30,9 @@ pt_log() {
 append_env() {
   local key="$1"
   local value="$2"
-  printf '%s=%s\n' "$key" "$value" >> "$HAR_ENV_FILE"
+  # %q, not a raw value: an unquoted value with spaces (an Xcode scheme, a
+  # simulator name, a path under /Applications) breaks `source .env.agent.<id>`.
+  printf '%s=%q\n' "$key" "$value" >> "$HAR_ENV_FILE"
 }
 
 append_path_prefix() {
@@ -235,9 +237,8 @@ provision_ios() {
   if [ -n "${HARNESS_XCODE_SCHEME:-}" ]; then
     append_env "HARNESS_XCODE_SCHEME" "$HARNESS_XCODE_SCHEME"
   fi
-  if [ -n "${HARNESS_SIMULATOR_NAME:-}" ]; then
-    append_env "HARNESS_SIMULATOR_NAME" "$HARNESS_SIMULATOR_NAME"
-  fi
+  # The simulator is not recorded here: launch.sh writes the device reserved for
+  # this slot, and harness.env already carries the shared one.
   if [ -n "${HARNESS_BUNDLE_ID:-}" ]; then
     append_env "HARNESS_BUNDLE_ID" "$HARNESS_BUNDLE_ID"
   fi

package/dist/templates/har-boilerplate-cli/provision-toolchain.sh

@@ -30,7 +30,9 @@ pt_log() {
 append_env() {
   local key="$1"
   local value="$2"
-  printf '%s=%s\n' "$key" "$value" >> "$HAR_ENV_FILE"
+  # %q, not a raw value: an unquoted value with spaces (an Xcode scheme, a
+  # simulator name, a path under /Applications) breaks `source .env.agent.<id>`.
+  printf '%s=%q\n' "$key" "$value" >> "$HAR_ENV_FILE"
 }
 
 append_path_prefix() {
@@ -235,9 +237,8 @@ provision_ios() {
   if [ -n "${HARNESS_XCODE_SCHEME:-}" ]; then
     append_env "HARNESS_XCODE_SCHEME" "$HARNESS_XCODE_SCHEME"
   fi
-  if [ -n "${HARNESS_SIMULATOR_NAME:-}" ]; then
-    append_env "HARNESS_SIMULATOR_NAME" "$HARNESS_SIMULATOR_NAME"
-  fi
+  # The simulator is not recorded here: launch.sh writes the device reserved for
+  # this slot, and harness.env already carries the shared one.
   if [ -n "${HARNESS_BUNDLE_ID:-}" ]; then
     append_env "HARNESS_BUNDLE_ID" "$HARNESS_BUNDLE_ID"
   fi

package/dist/templates/har-boilerplate-ios/CLAUDE.agent.md

@@ -8,7 +8,7 @@
 |--|--|
 | **Agent ID** | ${AGENT_ID} |
 | **Work dir** | Fresh session worktree per launch — see the launch output or `.har/slots/agent-${AGENT_ID}.json` |
-| **Simulator** | Configured in `.har/harness.env` — `HARNESS_SIMULATOR_NAME` |
+| **Simulator** | Created for this slot at launch — `HARNESS_SIMULATOR_UDID` in `.env.agent.${AGENT_ID}` |
 | **Scheme** | Configured in `.har/harness.env` — `HARNESS_XCODE_SCHEME` |
 
 **Never edit the main checkout** — launch FIRST, then make ALL file edits under the work dir from the launch output. An occupied slot always blocks a new launch — run `har env teardown <id>` (or `complete <id>`) first, then launch again.
@@ -50,21 +50,25 @@ Stages are the harness's single vocabulary for checks: templates and custom stag
 
 ## Project commands
 
+Target **this slot's** simulator, never `booted` — another agent's device may also
+be booted. `HARNESS_IOS_DESTINATION` and `HARNESS_SIMULATOR_UDID` come from
+`.env.agent.${AGENT_ID}`.
+
 ```bash
+source .env.agent.${AGENT_ID}
+
 # Build
-xcodebuild build -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16' CODE_SIGNING_ALLOWED=NO
+xcodebuild build -scheme MyApp -destination "$HARNESS_IOS_DESTINATION" CODE_SIGNING_ALLOWED=NO
 
 # Run unit tests
-xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16' CODE_SIGNING_ALLOWED=NO
-
-# Install app on booted simulator
-xcrun simctl install booted path/to/MyApp.app
+xcodebuild test -scheme MyApp -destination "$HARNESS_IOS_DESTINATION" CODE_SIGNING_ALLOWED=NO
 
-# Launch app
-xcrun simctl launch booted com.example.myapp
+# Install and launch on this slot's device
+./.har/agent-cli.sh ${AGENT_ID} install path/to/MyApp.app
+./.har/agent-cli.sh ${AGENT_ID} launch-app
 ```
 
-Adapt for your scheme and simulator — see `.har/harness.env`.
+Adapt for your scheme — see `.har/harness.env`.
 
 ## User-flow validation (RocketSim)
 

package/dist/templates/har-boilerplate-ios/README.md

@@ -18,8 +18,9 @@ Generated and maintained by [`har`](https://github.com/os-factory/har). Run `har
 | `runs/` | Run history from `har env` / MCP — gitignored |
 | `artifacts/` | Stage outputs: test results, screenshots, logs |
 | `agent-slot.sh` | Shared agent-id validation and slot registry helpers |
-| `setup-infra.sh` | Boot the iOS Simulator; start optional Docker services |
-| `launch.sh` | Launch one agent slot (git worktree, toolchain provisioning, env file) |
+| `setup-infra.sh` | Check the toolchain; start optional Docker services |
+| `simulator.sh` | Create, boot and delete one iOS Simulator per agent slot |
+| `launch.sh` | Launch one agent slot (git worktree, toolchain provisioning, simulator, env file) |
 | `provision-toolchain.sh` | Write Xcode/simulator paths (`XCODEBUILD_BIN`, …) to `.env.agent.<id>` |
 | `verify.sh` | Verification pipeline (build smoke by default; --full adds tests, lint, flows) |
 | `teardown.sh` | Tear down one agent slot (worktree + env file) |
@@ -82,9 +83,37 @@ dev setup and add a readiness command when agents need a real workflow to pass.
 Edit **`harness.env`** to set:
 - `HARNESS_XCODE_SCHEME` — your app's shared Xcode scheme
 - `HARNESS_XCODE_WORKSPACE` or `HARNESS_XCODE_PROJECT` — path to the project file
-- `HARNESS_SIMULATOR_NAME` — target simulator (must be listed in `xcrun simctl list devices`)
+- `HARNESS_SIMULATOR_NAME` — preferred simulator, matched by exact name
 - `HARNESS_BUNDLE_ID` — app bundle identifier
 
+## Simulators
+
+Slots do not share a simulator. Each launch **creates**
+`har-<project>-agent-<id>-<model>` — `har-storefront-agent-2-iPhone-17`, say — and
+teardown deletes it, so two agents never collide on a destination, on an installed
+bundle id, or on a UI session, and the simulators you use by hand are never touched.
+Every launch also starts from a pristine device: no app installed, no leftover
+store, nothing carried over from the previous session.
+
+| Setting | Effect |
+|---------|--------|
+| `HARNESS_SIMULATOR_NAME` | The model to create — `iPhone 16`, `iPhone 17 Pro`, `iPad Air 11-inch (M2)`. Empty means the newest model of the family. See `xcrun simctl list devicetypes`. |
+| `HARNESS_SIMULATOR_FAMILY` | `auto` (read from the name) \| `iPhone` \| `iPad`. An iPad is only created when this resolves to iPad. |
+| `HARNESS_SIMULATOR_UDID` | Run every slot on one existing device instead. Slots then share it — for one-off debugging. |
+| `HARNESS_SIMULATOR_SHARED` | `true` restores one shared simulator for all slots, booted by `setup-infra.sh`. |
+
+The runtime is the newest installed iOS that supports the model — a model retired
+from recent runtimes still resolves against an older one. When nothing matches,
+launch fails and lists the models this machine can create.
+
+If `HARNESS_SIMULATOR_NAME` is not a model but names an existing device, that
+device is used as-is and never deleted — how a hand-renamed simulator is targeted.
+
+The device lands in `.env.agent.<id>` as `HARNESS_SIMULATOR_UDID`,
+`HARNESS_SIMULATOR_DEVICE_NAME` and `HARNESS_IOS_DESTINATION` — the model stays in
+`HARNESS_SIMULATOR_NAME`, so the two never mean the same thing in one place; what a slot holds is tracked in `.har/simulators/`.
+Use `./.har/agent-cli.sh <id> simulator` to see it.
+
 ## Port & shared services (iOS profile)
 
 Pure iOS apps have **no per-slot TCP ports** — agents build and run on a shared iOS Simulator. Optional backend containers (mock API, etc.) use the same shared-infra model as other profiles.
@@ -94,7 +123,7 @@ Pure iOS apps have **no per-slot TCP ports** — agents build and run on a share
 | Layer | Scope | Rule | On conflict |
 |-------|-------|------|-------------|
 | Optional backend (compose) | Per machine | `HARNESS_*_PORT_DEFAULT` for that service | Scan configured ranges in `harness.env` |
-| iOS Simulator | Shared | No harness port — one booted simulator for all slots | N/A |
+| iOS Simulator | Per slot | One device created per agent — no harness port | None: `har-<project>-agent-<id>-<model>` is unique per slot |
 
 When your app talks to a local backend, read the resolved host port from `.env.agent.<id>` (set by `setup-infra.sh`) — never hardcode `15432` or similar in tests or flow scripts.
 
@@ -102,7 +131,7 @@ When your app talks to a local backend, read the resolved host port from `.env.a
 
 | Resource | Model | Configuration |
 |----------|-------|---------------|
-| iOS Simulator | One booted simulator shared by all slots | `HARNESS_SIMULATOR_NAME`, `setup-infra.sh` |
+| iOS Simulator | One device created per slot, deleted at teardown | `HARNESS_SIMULATOR_*`, `launch.sh` |
 | Optional backend | One shared compose service | `HARNESS_INFRA_SERVICES` (e.g. `"mock-server"`) |
 | Application code | Isolated git worktree per slot | `HARNESS_USE_WORKTREE=true` |
 

package/dist/templates/har-boilerplate-ios/agent-cli.sh

@@ -11,6 +11,8 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 source "$SCRIPT_DIR/harness.env"
 # shellcheck source=/dev/null
 source "$SCRIPT_DIR/agent-slot.sh"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/simulator.sh"
 
 AGENT_ID="${1:?Usage: agent-cli.sh <agent-id> <command> [args...]}"
 COMMAND="${2:?Usage: agent-cli.sh <agent-id> <command> [args...]}"
@@ -19,6 +21,18 @@ validate_agent_id "$AGENT_ID"
 
 WORKTREE_DIR="$(existing_slot_worktree "$AGENT_ID")"
 
+# simctl target for this slot: its own device when one is reserved, else whatever
+# is booted — never another slot's simulator.
+slot_sim_target() {
+  local claim udid
+  claim="$(har_sim_claim_file "$AGENT_ID")"
+  if [ -f "$claim" ]; then
+    udid="$(read_slot_field "$claim" udid || true)"
+    [ -n "$udid" ] && { echo "$udid"; return; }
+  fi
+  echo "booted"
+}
+
 resolve_work_dir() {
   local env_file
   env_file="$(resolve_agent_env_file "$AGENT_ID" "$REPO_ROOT")" || {
@@ -42,7 +56,7 @@ case "$COMMAND" in
       echo "  Work dir:  $(resolve_agent_work_dir "$ENV_FILE" "$AGENT_ID")"
       [ -n "$WORKTREE_DIR" ] && [ -d "$WORKTREE_DIR" ] && echo "  Worktree:  $WORKTREE_DIR"
       echo "  Scheme:    ${HARNESS_XCODE_SCHEME:-not set}"
-      echo "  Simulator: ${HARNESS_SIMULATOR_NAME:-not set}"
+      echo "  Simulator: ${HARNESS_SIMULATOR_DEVICE_NAME:-${HARNESS_SIMULATOR_NAME:-not set}} ($(slot_sim_target))"
       echo "  Bundle ID: ${HARNESS_BUNDLE_ID:-not set}"
     else
       echo "No active environment for agent ${AGENT_ID}"
@@ -51,14 +65,22 @@ case "$COMMAND" in
     ;;
 
   simulator)
-    # Show simulator state and UDID for the configured device.
-    SIM_NAME="${HARNESS_SIMULATOR_NAME:-iPhone 16}"
-    echo "Simulator: ${SIM_NAME}"
-    xcrun simctl list devices available 2>/dev/null \
-      | grep "${SIM_NAME}" \
-      | grep -E '\([A-F0-9-]{36}\)' \
-      | head -5 \
-      || echo "  (no matching simulator found — check HARNESS_SIMULATOR_NAME in harness.env)"
+    # Show the device reserved for this slot, or the configured one when idle.
+    TARGET="$(slot_sim_target)"
+    if [ "$TARGET" != "booted" ]; then
+      echo "Simulator: $(har_sim_device_name "$TARGET") (${TARGET})"
+      echo "State:     $(har_sim_device_state "$TARGET")"
+      echo "Reserved:  $(har_sim_claim_file "$AGENT_ID")"
+    else
+      SIM_NAME="${HARNESS_SIMULATOR_NAME:-iPhone 16}"
+      echo "Simulator: ${SIM_NAME} (no device reserved — the slot is not launched)"
+      RESOLVED="$(har_sim_resolve_configured)"
+      if [ -n "$RESOLVED" ]; then
+        echo "Configured device: ${RESOLVED#*$'\t'} (${RESOLVED%%$'\t'*})"
+      else
+        echo "  (no matching simulator found — check HARNESS_SIMULATOR_NAME in harness.env)"
+      fi
+    fi
     ;;
 
   logs)
@@ -70,7 +92,7 @@ case "$COMMAND" in
   restart)
     echo "iOS profile has no managed processes to restart." >&2
     echo "Relaunch the slot or reinstall the app with:" >&2
-    echo "  ./.har/agent-cli.sh ${AGENT_ID} exec xcrun simctl install booted <path-to.app>" >&2
+    echo "  ./.har/agent-cli.sh ${AGENT_ID} install <path-to.app>" >&2
     exit 1
     ;;
 
@@ -80,8 +102,9 @@ case "$COMMAND" in
       echo "Usage: agent-cli.sh ${AGENT_ID} install <path-to.app>" >&2
       exit 1
     fi
-    echo "==> Installing ${APP_PATH} on simulator..."
-    xcrun simctl install booted "$APP_PATH"
+    TARGET="$(slot_sim_target)"
+    echo "==> Installing ${APP_PATH} on ${TARGET}..."
+    xcrun simctl install "$TARGET" "$APP_PATH"
     echo "✓ Installed"
     ;;
 
@@ -92,8 +115,9 @@ case "$COMMAND" in
       echo "       or set HARNESS_BUNDLE_ID in harness.env" >&2
       exit 1
     fi
-    echo "==> Launching ${BUNDLE} on simulator..."
-    xcrun simctl launch booted "$BUNDLE"
+    TARGET="$(slot_sim_target)"
+    echo "==> Launching ${BUNDLE} on ${TARGET}..."
+    xcrun simctl launch "$TARGET" "$BUNDLE"
     ;;
 
   url)
@@ -101,7 +125,7 @@ case "$COMMAND" in
     echo "Work dir:  $WORK_DIR"
     [ -d "$WORKTREE_DIR" ] && echo "Worktree:  $WORKTREE_DIR"
     echo "Scheme:    ${HARNESS_XCODE_SCHEME:-not set}"
-    echo "Simulator: ${HARNESS_SIMULATOR_NAME:-not set}"
+    echo "Simulator: ${HARNESS_SIMULATOR_DEVICE_NAME:-${HARNESS_SIMULATOR_NAME:-not set}} ($(slot_sim_target))"
     echo "Bundle ID: ${HARNESS_BUNDLE_ID:-not set}"
     har_infra_enabled mock-server && echo "Mock:      check docker-compose.agent.yml for port"
     ;;

package/dist/templates/har-boilerplate-ios/gitignore.template

@@ -13,6 +13,7 @@ AGENT.md.proposed.meta.json
 maintain/
 ADAPT-PROMPT.md
 slots/
+simulators/
 
 # Generated by launch.sh
 .env.agent.*

package/dist/templates/har-boilerplate-ios/harness.env

@@ -19,14 +19,38 @@ export HARNESS_XCODE_PROJECT=""       # e.g. MyApp.xcodeproj (relative to repo r
 # Xcode scheme to build and test (must be marked as shared in Xcode).
 export HARNESS_XCODE_SCHEME="MyApp"
 
-# iOS Simulator to target. Use: xcrun simctl list devices | grep Booted
-# Common values: "iPhone 16", "iPhone 16 Pro", "iPhone SE (3rd generation)"
+# Simulator model each slot runs on, e.g. "iPhone 16", "iPhone 16 Pro", "iPad Air 11-inch (M2)".
+# Use: xcrun simctl list devicetypes. Leave empty for the newest model of the family.
 export HARNESS_SIMULATOR_NAME="iPhone 16"
 
-# Bundle ID of the app under test. Used by setup-infra.sh / RocketSim flows.
+# Bundle ID of the app under test. Used by agent-cli.sh / RocketSim flows.
 export HARNESS_BUNDLE_ID="com.example.myapp"
 
-# Derived xcodebuild destination string — override only if targeting a specific UDID.
+# ── Simulator allocation ──────────────────────────────────────────────────────
+# Every slot gets its own simulator, "har-<project>-agent-<id>-<model>", created
+# at launch from HARNESS_SIMULATOR_NAME and deleted at teardown. Concurrent agents
+# therefore never share a destination, an installed bundle id, or a UI session,
+# each launch starts from a pristine device, and the simulators you use by hand
+# are never touched. launch.sh writes the device into .env.agent.<id>.
+#
+# The runtime is the newest installed iOS that supports the model; launch fails
+# with the list of available models when none does.
+
+# Family used when HARNESS_SIMULATOR_NAME is empty, and enforced when it is set:
+# auto (infer from the name) | iPhone | iPad. An iPad is only ever created when
+# this resolves to iPad.
+export HARNESS_SIMULATOR_FAMILY="auto"
+
+# Run every slot on one existing device instead of creating any (bypasses model
+# resolution — no fallback). Slots then share it, so use it for one-off debugging.
+# export HARNESS_SIMULATOR_UDID=""
+
+# Set true to go back to one shared simulator for all slots, resolved by exact
+# name from HARNESS_SIMULATOR_NAME and booted by setup-infra.sh.
+export HARNESS_SIMULATOR_SHARED=false
+
+# Destination used when slots share a simulator; per-slot launches override it
+# with the reserved device's UDID.
 export HARNESS_IOS_DESTINATION="platform=iOS Simulator,name=${HARNESS_SIMULATOR_NAME}"
 
 # Optional SwiftLint path (leave empty to use system-installed swiftlint).

package/dist/templates/har-boilerplate-ios/launch.sh

@@ -14,6 +14,8 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 source "$SCRIPT_DIR/harness.env"
 # shellcheck source=/dev/null
 source "$SCRIPT_DIR/agent-slot.sh"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/simulator.sh"
 
 AGENT_ID="${1:-}"
 USE_WORKTREE="${HARNESS_USE_WORKTREE:-true}"
@@ -86,7 +88,9 @@ fi
 # whose .gitignore doesn't know about har (applies to all worktrees too).
 GIT_EXCLUDE="$(git -C "$REPO_ROOT" rev-parse --git-common-dir 2>/dev/null)/info/exclude"
 if [ -n "$GIT_EXCLUDE" ] && [ -d "$(dirname "$GIT_EXCLUDE")" ]; then
-  for pattern in '.env.agent.*' 'ecosystem.agent.*.config.cjs' '.har/venv'; do
+  # .har/simulators covers harnesses scaffolded before it reached
+  # gitignore.template, which only lands on init or maintain.
+  for pattern in '.env.agent.*' 'ecosystem.agent.*.config.cjs' '.har/venv' '.har/simulators'; do
     grep -qxF "$pattern" "$GIT_EXCLUDE" 2>/dev/null || echo "$pattern" >> "$GIT_EXCLUDE"
   done
 fi
@@ -107,6 +111,7 @@ mark_slot_failed() {
   if [ "$exit_code" != "0" ] && [ "$REGISTRY_WRITTEN" = true ]; then
     log "Launch failed after creating the session. Recording failed slot state..."
     set +e
+    har_sim_release "$AGENT_ID"
     SLOT_AGENT_ID="$AGENT_ID" \
     SLOT_MODE="$([ "$USE_WORKTREE" = true ] && echo worktree || echo root)" \
     SLOT_WORK_DIR="$WORK_DIR" \
@@ -147,6 +152,30 @@ HAR_REL_PREFIX="${REL_PREFIX:-}" \
 HAR_AGENT_ID="$AGENT_ID" \
   "$SCRIPT_DIR/provision-toolchain.sh"
 
+# Give this slot its own simulator. Written after provision-toolchain.sh so the
+# per-slot device wins over the shared default when verify.sh sources the file.
+if har_sim_per_slot_enabled; then
+  log "Preparing this slot's simulator..."
+  SIM_RESULT=""
+  SIM_RESULT="$(har_sim_acquire "$AGENT_ID")" || {
+    log "Could not prepare a simulator — see the messages above."
+    exit 1
+  }
+  SIM_UDID="${SIM_RESULT%%$'\t'*}"
+  SIM_NAME="${SIM_RESULT#*$'\t'}"
+  # The device name goes under its own key: HARNESS_SIMULATOR_NAME means "model
+  # to create" in harness.env, and overwriting it here would make its meaning
+  # depend on which file was sourced last.
+  {
+    printf 'HARNESS_SIMULATOR_UDID=%q\n' "$SIM_UDID"
+    printf 'HARNESS_SIMULATOR_DEVICE_NAME=%q\n' "$SIM_NAME"
+    printf 'HARNESS_IOS_DESTINATION=%q\n' "platform=iOS Simulator,id=${SIM_UDID}"
+  } >> "$ENV_FILE"
+  log "Simulator: ${SIM_NAME} (${SIM_UDID})"
+else
+  log "Shared simulator mode (HARNESS_SIMULATOR_SHARED=true) — slots share ${HARNESS_SIMULATOR_NAME:-the configured device}."
+fi
+
 # Record the session in the slot registry — the source of truth for where
 # this slot's code lives (status/verify/teardown resolve through it).
 SLOT_AGENT_ID="$AGENT_ID" \
@@ -167,6 +196,9 @@ log "    ${WORK_DIR}"
 if [ "$USE_WORKTREE" = true ]; then
   log "  Branch:    ${BRANCH} (based on ${BASE_BRANCH} @ ${BASE_COMMIT})"
 fi
+if [ -n "${SIM_NAME:-}" ]; then
+  log "  Simulator: ${SIM_NAME} (${SIM_UDID})"
+fi
 log ""
 log "  Verify:    ./.har/verify.sh $AGENT_ID"
 log "  Teardown:  ./.har/teardown.sh $AGENT_ID   (keeps the branch)"

package/dist/templates/har-boilerplate-ios/provision-toolchain.sh

@@ -30,7 +30,9 @@ pt_log() {
 append_env() {
   local key="$1"
   local value="$2"
-  printf '%s=%s\n' "$key" "$value" >> "$HAR_ENV_FILE"
+  # %q, not a raw value: an unquoted value with spaces (an Xcode scheme, a
+  # simulator name, a path under /Applications) breaks `source .env.agent.<id>`.
+  printf '%s=%q\n' "$key" "$value" >> "$HAR_ENV_FILE"
 }
 
 append_path_prefix() {
@@ -235,9 +237,8 @@ provision_ios() {
   if [ -n "${HARNESS_XCODE_SCHEME:-}" ]; then
     append_env "HARNESS_XCODE_SCHEME" "$HARNESS_XCODE_SCHEME"
   fi
-  if [ -n "${HARNESS_SIMULATOR_NAME:-}" ]; then
-    append_env "HARNESS_SIMULATOR_NAME" "$HARNESS_SIMULATOR_NAME"
-  fi
+  # The simulator is not recorded here: launch.sh writes the device reserved for
+  # this slot, and harness.env already carries the shared one.
   if [ -n "${HARNESS_BUNDLE_ID:-}" ]; then
     append_env "HARNESS_BUNDLE_ID" "$HARNESS_BUNDLE_ID"
   fi

package/dist/templates/har-boilerplate-ios/setup-infra.sh

@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 # Sets up shared infrastructure for all iOS agent slots.
-# Boots the target iOS Simulator if not already running. No Docker required
-# for pure iOS apps — extend only when a local backend container is needed.
-# Idempotent — safe to run multiple times.
+# Checks the toolchain, and boots the configured simulator when slots share one
+# (HARNESS_SIMULATOR_SHARED=true) — otherwise launch.sh boots each slot's own
+# device. No Docker required for pure iOS apps — extend only when a local
+# backend container is needed. Idempotent — safe to run multiple times.
 #
 # Usage: ./.har/setup-infra.sh
 set -euo pipefail
@@ -11,6 +12,10 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # shellcheck source=/dev/null
 source "$SCRIPT_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/agent-slot.sh"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/simulator.sh"
 
 log() { echo "==> $*" >&2; }
 
@@ -26,46 +31,55 @@ log "Found: $XCODE_VERSION"
 # ── Simulator ─────────────────────────────────────────────────────────────────
 SIMULATOR_NAME="${HARNESS_SIMULATOR_NAME:-iPhone 16}"
 
-log "Checking simulator: ${SIMULATOR_NAME}"
-
-UDID="$(xcrun simctl list devices available 2>/dev/null \
-  | grep "${SIMULATOR_NAME}" \
-  | grep -E '\([A-F0-9-]{36}\)' \
-  | head -1 \
-  | grep -oE '[A-F0-9-]{36}' \
-  | head -1 || true)"
-
-if [ -z "$UDID" ]; then
-  echo "Error: Simulator '${SIMULATOR_NAME}' not found in available devices." >&2
-  echo "  Available simulators:" >&2
-  xcrun simctl list devices available 2>/dev/null | grep -E 'iPhone|iPad' | head -20 >&2
-  echo "  Update HARNESS_SIMULATOR_NAME in .har/harness.env." >&2
-  exit 1
-fi
+if har_sim_per_slot_enabled; then
+  # Each slot creates and boots its own device at launch — booting a shared one
+  # here would only waste a device no slot is going to use. Resolve the model now
+  # so a missing runtime is reported before any worktree is created.
+  FAMILY="$(har_sim_preferred_family)"
+  PLAN="$(har_sim_plan_creation "${HARNESS_SIMULATOR_NAME:-}" "$FAMILY")"
+  PLAN_STATUS="${PLAN%%$'\t'*}"
+  if [ "$PLAN_STATUS" = "OK" ]; then
+    log "Per-slot simulators: launch creates one $(printf '%s' "$PLAN" | cut -f3) per agent."
+  elif [ "$PLAN_STATUS" = "NO_MODEL" ] && [ -n "$(har_sim_device_by_name "${HARNESS_SIMULATOR_NAME:-}")" ]; then
+    # Supported fallback: the name is an existing device rather than a model.
+    log "Per-slot simulators: launch reuses the existing device '${SIMULATOR_NAME}'."
+  else
+    # Fail here rather than at launch, which would already have created a
+    # worktree, a branch and an env file the user then has to tear down.
+    echo "Error: no simulator can be prepared for '${SIMULATOR_NAME}'." >&2
+    if [ "$PLAN" != "$PLAN_STATUS" ]; then
+      echo "  Available ${FAMILY} models: ${PLAN#*$'\t'}" >&2
+    else
+      echo "  No iOS runtime is installed — add one in Xcode → Settings → Components." >&2
+    fi
+    echo "  Update HARNESS_SIMULATOR_NAME in .har/harness.env." >&2
+    exit 1
+  fi
+else
+  log "Checking simulator: ${SIMULATOR_NAME}"
 
-STATE="$(xcrun simctl list devices 2>/dev/null \
-  | grep "$UDID" \
-  | grep -oE 'Booted|Shutdown|Unavailable' \
-  | head -1 || echo "unknown")"
+  # Exact name match: a substring match on "iPhone 16" also hits "iPhone 16 Pro Max".
+  RESOLVED="$(har_sim_resolve_configured)"
+  UDID="${RESOLVED%%$'\t'*}"
 
-if [ "$STATE" = "Booted" ]; then
-  log "Simulator '${SIMULATOR_NAME}' ($UDID) is already booted."
-else
-  log "Booting simulator '${SIMULATOR_NAME}' ($UDID)..."
-  xcrun simctl boot "$UDID" 2>/dev/null || true
+  if [ -z "$UDID" ]; then
+    echo "Error: Simulator '${SIMULATOR_NAME}' not found in available devices." >&2
+    echo "  Available simulators:" >&2
+    xcrun simctl list devices available 2>/dev/null | grep -E 'iPhone|iPad' | head -20 >&2
+    echo "  Update HARNESS_SIMULATOR_NAME in .har/harness.env." >&2
+    exit 1
+  fi
 
-  log "Waiting for simulator to become ready..."
-  for i in $(seq 1 30); do
-    CURRENT="$(xcrun simctl list devices 2>/dev/null | grep "$UDID" | grep -oE 'Booted' | head -1 || true)"
-    if [ "$CURRENT" = "Booted" ]; then
+  if [ "$(har_sim_device_state "$UDID")" = "Booted" ]; then
+    log "Simulator '${SIMULATOR_NAME}' ($UDID) is already booted."
+  else
+    log "Booting simulator '${SIMULATOR_NAME}' ($UDID)..."
+    if har_sim_boot "$UDID"; then
       log "Simulator is ready."
-      break
+    else
+      echo "Warning: Simulator did not reach Booted state." >&2
     fi
-    if [ "$i" = "30" ]; then
-      echo "Warning: Simulator did not reach Booted state within 30 seconds." >&2
-    fi
-    sleep 1
-  done
+  fi
 fi
 
 # ── Optional Docker infra ─────────────────────────────────────────────────────
@@ -79,6 +93,9 @@ fi
 
 log ""
 log "Infrastructure is ready."
-log "  Simulator: ${SIMULATOR_NAME} ($UDID)"
+# In per-slot mode the device is reported by launch, once it exists.
+if [ -n "${UDID:-}" ]; then
+  log "  Simulator: ${SIMULATOR_NAME} ($UDID)"
+fi
 har_infra_enabled mock-server && log "  Mock server: running (see docker-compose.agent.yml)"
 exit 0

package/dist/templates/har-boilerplate-ios/simulator.sh

@@ -0,0 +1,400 @@
+#!/usr/bin/env bash
+# Per-slot iOS Simulator allocation.
+#
+# One booted simulator shared by every agent slot means concurrent xcodebuild
+# destinations, installs of the same bundle id, and UI flows collide. Each slot
+# instead gets a simulator of its own, created at launch and deleted at teardown:
+# unique by construction, pristine on every launch, and never a device the
+# developer is using by hand.
+#
+# Source AFTER harness.env and agent-slot.sh — read_slot_field, slot_registry_file
+# and SCRIPT_DIR come from there.
+#
+# What a slot holds is recorded in .har/simulators/agent-<id>.json, so teardown
+# knows whether the device was HAR's to delete.
+
+# ── Configuration ─────────────────────────────────────────────────────────────
+
+# Preferred device family: auto (infer from HARNESS_SIMULATOR_NAME) | iPhone | iPad
+har_sim_preferred_family() {
+  local configured="${HARNESS_SIMULATOR_FAMILY:-auto}"
+  case "$configured" in
+    iPhone|iPad) echo "$configured"; return ;;
+  esac
+  case "${HARNESS_SIMULATOR_NAME:-}" in
+    iPad*|iPAD*|ipad*) echo "iPad" ;;
+    *) echo "iPhone" ;;
+  esac
+}
+
+har_sim_per_slot_enabled() {
+  [ "${HARNESS_SIMULATOR_SHARED:-false}" != "true" ]
+}
+
+har_sim_log() { echo "==> simulator: $*" >&2; }
+
+# "iPad Air 11-inch (M4)" → "iPad-Air-11-inch-M4"
+har_sim_slug() {
+  printf '%s' "$1" | tr -c 'A-Za-z0-9._-' '-' | tr -s '-' | sed 's/^-//; s/-$//'
+}
+
+# Short digest of the repository path. Two checkouts can share a folder name,
+# and therefore HARNESS_PROJECT_NAME, but not a path — without it the prefix
+# sweep below would delete the other checkout's live device.
+har_sim_repo_digest() {
+  local repo
+  # -P so the same checkout reached through a symlink yields the same digest.
+  repo="$(cd -P "${SCRIPT_DIR}/.." 2>/dev/null && pwd -P || echo "${SCRIPT_DIR}")"
+  node -e 'process.stdout.write(require("crypto").createHash("sha1").update(process.argv[1]).digest("hex").slice(0, 6))' "$repo"
+}
+
+# Stable part of a slot's device name. The model is appended after it, so a
+# device left over from a launch on another model is still recognised as this
+# slot's and cleaned up.
+har_sim_device_label_prefix() {
+  echo "har-$(har_sim_slug "${HARNESS_PROJECT_NAME:-har}")-$(har_sim_repo_digest)-agent-${1}"
+}
+
+har_sim_device_label() {
+  local prefix model
+  prefix="$(har_sim_device_label_prefix "$1")"
+  model="$(har_sim_slug "${2:-}")"
+  [ -n "$model" ] && echo "${prefix}-${model}" || echo "$prefix"
+}
+
+# ── Claims ────────────────────────────────────────────────────────────────────
+# Slots never compete for a device, so a claim only records what teardown must
+# release — no locking, no cross-slot exclusion.
+
+har_sim_claims_dir() { echo "${SCRIPT_DIR}/simulators"; }
+har_sim_claim_file() { echo "$(har_sim_claims_dir)/agent-${1}.json"; }
+
+har_sim_write_claim() {
+  local agent_id="$1" udid="$2" name="$3" created="$4" file
+  file="$(har_sim_claim_file "$agent_id")"
+  mkdir -p "$(dirname "$file")"
+  node -e '
+const fs = require("fs");
+const [file, agentId, udid, name, created] = process.argv.slice(1);
+fs.writeFileSync(file, JSON.stringify({
+  agentId: Number(agentId),
+  udid,
+  name,
+  createdByHar: created === "true",
+  claimedAt: new Date().toISOString(),
+}, null, 2) + "\n");
+' "$file" "$agent_id" "$udid" "$name" "$created"
+}
+
+# Agent id of another live slot holding this udid, if any. Only a pinned
+# HARNESS_SIMULATOR_UDID can produce that overlap.
+har_sim_claim_owner_of() {
+  local udid="$1" self="$2" dir file id
+  dir="$(har_sim_claims_dir)"
+  [ -d "$dir" ] || return 0
+  for file in "$dir"/agent-*.json; do
+    [ -f "$file" ] || continue
+    id="$(basename "$file")"
+    id="${id#agent-}"
+    id="${id%.json}"
+    [ "$id" = "$self" ] && continue
+    [ -f "$(slot_registry_file "$id")" ] || continue
+    if [ "$(read_slot_field "$file" udid || true)" = "$udid" ]; then
+      echo "$id"
+      return 0
+    fi
+  done
+}
+
+# ── Device discovery ──────────────────────────────────────────────────────────
+
+# Unavailable devices are skipped: a device whose runtime was uninstalled must
+# not pass validation only to fail at boot.
+har_sim_device_field() {
+  xcrun simctl list devices --json 2>/dev/null | node -e '
+const data = JSON.parse(require("fs").readFileSync(0, "utf8"));
+const [want, field] = process.argv.slice(1);
+const device = Object.values(data.devices || {})
+  .flat()
+  .filter((entry) => entry && entry.isAvailable !== false)
+  .find((entry) => entry.udid === want);
+if (device && device[field]) process.stdout.write(String(device[field]));
+' "$1" "$2" 2>/dev/null || true
+}
+
+har_sim_device_state() { har_sim_device_field "$1" state; }
+har_sim_device_name() { har_sim_device_field "$1" name; }
+
+# UDID of an existing device with this exact name, newest runtime first.
+# A substring match would resolve "iPhone 16" to "iPhone 16 Pro Max".
+har_sim_device_by_name() {
+  local want="${1:-}"
+  [ -n "$want" ] || return 0
+  xcrun simctl list devices available --json 2>/dev/null | node -e '
+const data = JSON.parse(require("fs").readFileSync(0, "utf8"));
+const want = process.argv[1];
+const rows = [];
+for (const [runtime, devices] of Object.entries(data.devices || {})) {
+  if (!runtime.includes("SimRuntime.iOS-")) continue;
+  const parts = runtime.match(/iOS-(\d+)(?:-(\d+))?/);
+  const version = parts ? Number(parts[1]) * 1000 + Number(parts[2] || 0) : 0;
+  for (const device of devices || []) {
+    if (!device.udid || device.isAvailable === false) continue;
+    if (device.name !== want) continue;
+    rows.push({ udid: device.udid, version });
+  }
+}
+rows.sort((a, b) => b.version - a.version);
+if (rows[0]) process.stdout.write(rows[0].udid);
+' "$want" 2>/dev/null || true
+}
+
+# The shared-mode device, as "<udid>\t<name>".
+har_sim_resolve_configured() {
+  local udid
+  udid="$(har_sim_device_by_name "${HARNESS_SIMULATOR_NAME:-}")"
+  [ -n "$udid" ] || return 0
+  printf '%s\t%s' "$udid" "${HARNESS_SIMULATOR_NAME}"
+}
+
+# `simctl list` is a subprocess and a JSON parse; neither answer changes during
+# a launch, so each is fetched at most once per process.
+har_sim_devicetypes_json() {
+  if [ -z "${_HAR_SIM_TYPES_JSON:-}" ]; then
+    _HAR_SIM_TYPES_JSON="$(xcrun simctl list devicetypes --json 2>/dev/null || echo '{}')"
+  fi
+  printf '%s' "$_HAR_SIM_TYPES_JSON"
+}
+
+har_sim_runtimes_json() {
+  if [ -z "${_HAR_SIM_RUNTIMES_JSON:-}" ]; then
+    _HAR_SIM_RUNTIMES_JSON="$(xcrun simctl list runtimes --json 2>/dev/null || echo '{}')"
+  fi
+  printf '%s' "$_HAR_SIM_RUNTIMES_JSON"
+}
+
+# Model and runtime to create this slot's device from. Failures carry the models
+# this machine can create, so the caller never has to re-derive that list.
+# Prints one of:
+#   OK <deviceTypeId> <deviceTypeName> <runtimeId> <runtimeVersion>
+#   NO_RUNTIME                        no iOS runtime installed
+#   NO_MODEL <models>                 HARNESS_SIMULATOR_NAME is not a device model
+#   NO_RUNTIME_FOR_MODEL <models>     model exists, no installed runtime supports it
+har_sim_plan_creation() {
+  local types runtimes
+  types="$(har_sim_devicetypes_json)"
+  runtimes="$(har_sim_runtimes_json)"
+  node -e '
+const [typesRaw, runtimesRaw, wantName, family] = process.argv.slice(1);
+const types = JSON.parse(typesRaw).devicetypes || [];
+const version = (value) => {
+  const [major = 0, minor = 0] = String(value || "0").split(".").map(Number);
+  return major * 1000 + minor;
+};
+const runtimes = (JSON.parse(runtimesRaw).runtimes || [])
+  .filter((runtime) => runtime.isAvailable !== false)
+  .filter((runtime) => String(runtime.identifier || "").includes("SimRuntime.iOS-"))
+  .sort((a, b) => version(b.version) - version(a.version));
+
+const isPad = (entry) => /ipad/i.test(entry.productFamily || entry.name || "");
+const inFamily = (entry) => (family === "iPad" ? isPad(entry) : !isPad(entry));
+
+// Models the newest runtime could create, named so an error can list them.
+// Truncation is stated rather than silent — a model cut off the list still exists.
+function availableModels() {
+  const runtime = runtimes[0];
+  const supported =
+    runtime && Array.isArray(runtime.supportedDeviceTypes) && runtime.supportedDeviceTypes.length
+      ? runtime.supportedDeviceTypes
+      : types;
+  const names = supported.filter(inFamily).map((entry) => entry.name);
+  const shown = names.slice(0, 8).join(", ");
+  return names.length > 8 ? `${shown}, … (${names.length - 8} more)` : shown;
+}
+
+function plan() {
+  if (!runtimes.length) return "NO_RUNTIME";
+  if (wantName && !types.some((type) => type.name === wantName)) {
+    return `NO_MODEL\t${availableModels()}`;
+  }
+
+  for (const runtime of runtimes) {
+    const supported =
+      Array.isArray(runtime.supportedDeviceTypes) && runtime.supportedDeviceTypes.length
+        ? runtime.supportedDeviceTypes
+        : types;
+    // Apple lists supported device types newest first within each family.
+    const pool = supported.filter(inFamily);
+    const chosen = wantName ? pool.find((type) => type.name === wantName) : pool[0];
+    if (chosen) {
+      return `OK\t${chosen.identifier}\t${chosen.name}\t${runtime.identifier}\t${runtime.version}`;
+    }
+  }
+  return wantName ? `NO_RUNTIME_FOR_MODEL\t${availableModels()}` : "NO_RUNTIME";
+}
+
+process.stdout.write(plan());
+' "$types" "$runtimes" "${1:-}" "${2:-iPhone}" 2>/dev/null || true
+}
+
+# Every device whose name is <prefix> or starts with "<prefix>-", so a slot's
+# leftovers are found whatever model they were created from.
+har_sim_devices_with_prefix() {
+  xcrun simctl list devices --json 2>/dev/null | node -e '
+const data = JSON.parse(require("fs").readFileSync(0, "utf8"));
+const prefix = process.argv[1];
+const matches = Object.values(data.devices || {})
+  .flat()
+  .filter((device) => device && device.udid)
+  .filter((device) => device.name === prefix || String(device.name || "").startsWith(`${prefix}-`))
+  .map((device) => device.udid);
+process.stdout.write(matches.join("\n"));
+' "$1" 2>/dev/null || true
+}
+
+har_sim_delete_devices_with_prefix() {
+  local udid
+  while read -r udid; do
+    [ -n "$udid" ] || continue
+    xcrun simctl delete "$udid" >/dev/null 2>&1 || true
+  done <<< "$(har_sim_devices_with_prefix "$1")"
+}
+
+# ── Boot ──────────────────────────────────────────────────────────────────────
+
+har_sim_boot() {
+  local udid="$1" i
+  xcrun simctl boot "$udid" >/dev/null 2>&1 || true
+  if xcrun simctl bootstatus "$udid" -b >/dev/null 2>&1; then
+    return 0
+  fi
+  # Fallback for a toolchain without bootstatus: the plain listing is one
+  # subprocess, where the JSON form costs xcrun plus node on every poll.
+  for i in $(seq 1 30); do
+    if xcrun simctl list devices 2>/dev/null | grep -q "${udid}.*Booted"; then
+      return 0
+    fi
+    sleep 2
+  done
+  return 1
+}
+
+# ── Acquire / release ─────────────────────────────────────────────────────────
+
+# Prints "<udid>\t<name>\t<createdByHar>".
+_har_sim_select() {
+  local agent_id="$1"
+  local want="${HARNESS_SIMULATOR_NAME:-}"
+  local family owner name plan status models device_type model runtime label udid
+
+  # An explicit UDID is a deliberate override — never fall back off it.
+  if [ -n "${HARNESS_SIMULATOR_UDID:-}" ]; then
+    name="$(har_sim_device_name "$HARNESS_SIMULATOR_UDID")"
+    if [ -z "$name" ]; then
+      har_sim_log "HARNESS_SIMULATOR_UDID=${HARNESS_SIMULATOR_UDID} is not a known device"
+      return 1
+    fi
+    owner="$(har_sim_claim_owner_of "$HARNESS_SIMULATOR_UDID" "$agent_id")"
+    if [ -n "$owner" ]; then
+      har_sim_log "warning: agent ${owner} already holds ${name} — a pinned HARNESS_SIMULATOR_UDID"
+      har_sim_log "         gives every slot the same device; unset it to get one per slot."
+    fi
+    printf '%s\t%s\t%s' "$HARNESS_SIMULATOR_UDID" "$name" "false"
+    return 0
+  fi
+
+  family="$(har_sim_preferred_family)"
+  plan="$(har_sim_plan_creation "$want" "$family")"
+  status="${plan%%$'\t'*}"
+  # Failure statuses carry the creatable models after the first tab.
+  models=""
+  [ "$plan" != "$status" ] && models="${plan#*$'\t'}"
+
+  if [ "$status" = "OK" ]; then
+    IFS=$'\t' read -r _ device_type model runtime _ <<< "$plan"
+    label="$(har_sim_device_label "$agent_id" "$model")"
+    # A crashed launch can leave the slot's device behind — start from scratch,
+    # including a device this slot created from a different model.
+    har_sim_delete_devices_with_prefix "$(har_sim_device_label_prefix "$agent_id")"
+    har_sim_log "creating ${label} (${model}, ${runtime##*SimRuntime.})"
+    udid="$(xcrun simctl create "$label" "$device_type" "$runtime" 2>/dev/null | tr -d '[:space:]')"
+    if [ -z "$udid" ]; then
+      har_sim_log "xcrun simctl create failed for ${label} (${device_type}, ${runtime})"
+      return 1
+    fi
+    printf '%s\t%s\t%s' "$udid" "$label" "true"
+    return 0
+  fi
+
+  # Not a model: fall back to an existing device carrying that name, which is
+  # how a hand-renamed simulator is targeted.
+  if [ "$status" = "NO_MODEL" ]; then
+    udid="$(har_sim_device_by_name "$want")"
+    if [ -n "$udid" ]; then
+      har_sim_log "'${want}' is not a device model — using the existing device with that name"
+      printf '%s\t%s\t%s' "$udid" "$want" "false"
+      return 0
+    fi
+    har_sim_log "HARNESS_SIMULATOR_NAME='${want}' is neither a device model nor an existing device"
+    har_sim_log "  available ${family} models: ${models}"
+    return 1
+  fi
+
+  if [ "$status" = "NO_RUNTIME_FOR_MODEL" ]; then
+    har_sim_log "no installed iOS runtime supports '${want}'"
+    har_sim_log "  install a newer runtime in Xcode → Settings → Components, or pick another model"
+    har_sim_log "  available ${family} models: ${models}"
+    return 1
+  fi
+
+  har_sim_log "no iOS simulator runtime is installed"
+  har_sim_log "  install one in Xcode → Settings → Components"
+  return 1
+}
+
+# Reserve a simulator for a slot, boot it, and record the claim.
+# Prints "<udid>\t<name>" on success.
+har_sim_acquire() {
+  local agent_id="$1" udid name created
+  local result="" rc=0
+  # `|| rc=$?` keeps a failed selection from tripping `set -e` in the caller.
+  result="$(_har_sim_select "$agent_id")" || rc=$?
+  [ "$rc" -eq 0 ] || return "$rc"
+
+  udid="$(printf '%s' "$result" | cut -f1)"
+  name="$(printf '%s' "$result" | cut -f2)"
+  created="$(printf '%s' "$result" | cut -f3)"
+  if [ -z "$udid" ]; then
+    har_sim_log "no simulator could be selected"
+    return 1
+  fi
+  har_sim_write_claim "$agent_id" "$udid" "$name" "$created"
+
+  if ! har_sim_boot "$udid"; then
+    har_sim_log "device ${name} (${udid}) did not reach Booted state"
+    return 1
+  fi
+  printf '%s\t%s' "$udid" "$name"
+}
+
+# Drop a slot's claim. Devices HAR created are deleted; a device the developer
+# owns is left alone, and never even shut down.
+har_sim_release() {
+  local agent_id="$1" file udid created
+  file="$(har_sim_claim_file "$agent_id")"
+  if [ -f "$file" ]; then
+    udid="$(read_slot_field "$file" udid || true)"
+    created="$(read_slot_field "$file" createdByHar || true)"
+    rm -f "$file"
+    if [ "$created" = "true" ] && [ -n "$udid" ]; then
+      xcrun simctl shutdown "$udid" >/dev/null 2>&1 || true
+      xcrun simctl delete "$udid" >/dev/null 2>&1 || true
+      echo "✓ Deleted simulator created for this slot ($udid)"
+    fi
+  fi
+
+  # A launch killed between `simctl create` and the claim leaves a device no
+  # claim points at. Only HAR creates devices under this prefix, so sweeping it
+  # can never remove one of the developer's.
+  har_sim_delete_devices_with_prefix "$(har_sim_device_label_prefix "$agent_id")"
+}

package/dist/templates/har-boilerplate-ios/teardown.sh

@@ -13,6 +13,8 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 source "$SCRIPT_DIR/harness.env"
 # shellcheck source=/dev/null
 source "$SCRIPT_DIR/agent-slot.sh"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/simulator.sh"
 
 AGENT_ID="${1:?Usage: teardown.sh <agent-id> [--delete-branch]}"
 DELETE_BRANCH=false
@@ -59,6 +61,8 @@ if [ -n "$BRANCH" ]; then
   fi
 fi
 
+har_sim_release "$AGENT_ID"
+
 remove_slot_registry "$AGENT_ID"
 
 echo "✓ Agent ${AGENT_ID} torn down"

package/dist/templates/plugins/rocketsim/.har/stages/ROCKETSIM.md

@@ -17,7 +17,9 @@ The runner sets these environment variables for each flow:
 | `FLOW_ARTIFACT_DIR` | Directory for screenshots and output of this flow |
 | `WORK_DIR` | Path to the agent's session worktree |
 | `HARNESS_BUNDLE_ID` | App bundle identifier (from `harness.env`) |
-| `HARNESS_SIMULATOR_NAME` | Target simulator name (from `harness.env`) |
+| `HARNESS_SIMULATOR_NAME` | Simulator model configured in `harness.env` |
+| `HARNESS_SIMULATOR_DEVICE_NAME` | Name of the device created for this slot |
+| `HARNESS_SIMULATOR_UDID` | UDID of that device — target it rather than `booted` |
 | `AGENT_ID` | Active agent slot id |
 
 ## Key RocketSim CLI commands

package/dist/templates/plugins/rocketsim/.har/stages/rocketsim-flows.sh

@@ -130,6 +130,8 @@ for FLOW_SCRIPT in "${FLOW_SCRIPTS[@]}"; do
     FLOW_ARTIFACT_DIR="$FLOW_ARTIFACT_DIR" \
     HARNESS_BUNDLE_ID="${HARNESS_BUNDLE_ID:-}" \
     HARNESS_SIMULATOR_NAME="${HARNESS_SIMULATOR_NAME:-}" \
+    HARNESS_SIMULATOR_DEVICE_NAME="${HARNESS_SIMULATOR_DEVICE_NAME:-}" \
+    HARNESS_SIMULATOR_UDID="${HARNESS_SIMULATOR_UDID:-}" \
     bash "$FLOW_SCRIPT" 2>&1
   )
   FLOW_EXIT=$?

package/dist/templates/plugins/rocketsim/flows/README.md

@@ -32,5 +32,7 @@ The runner (`rocketsim-flows.sh`) sets these variables for every flow:
 |----------|-------------|
 | `FLOW_ARTIFACT_DIR` | Save screenshots here (`$FLOW_ARTIFACT_DIR/success.png`, `failure.png`) |
 | `HARNESS_BUNDLE_ID` | App bundle ID from `harness.env` |
-| `HARNESS_SIMULATOR_NAME` | Simulator name from `harness.env` |
+| `HARNESS_SIMULATOR_NAME` | Simulator model configured in `harness.env` |
+| `HARNESS_SIMULATOR_DEVICE_NAME` | Name of the device created for this slot |
+| `HARNESS_SIMULATOR_UDID` | UDID of that device — target it instead of `booted`, which may be another slot's |
 | `WORK_DIR` | Path to the session worktree |

package/dist/templates/plugins/rocketsim/flows/example-smoke.sh

@@ -12,10 +12,10 @@ set -euo pipefail
 log() { echo "==> [example-smoke] $*" >&2; }
 
 # ── Preflight ─────────────────────────────────────────────────────────────────
-# The app must be running on the simulator. Install and launch it before running
-# this flow. Example:
-#   xcrun simctl install booted path/to/MyApp.app
-#   xcrun simctl launch booted "${HARNESS_BUNDLE_ID}"
+# The app must be running on THIS slot's simulator. Install and launch it before
+# running this flow — target the reserved device, not `booted`. Example:
+#   xcrun simctl install "${HARNESS_SIMULATOR_UDID:-booted}" path/to/MyApp.app
+#   xcrun simctl launch "${HARNESS_SIMULATOR_UDID:-booted}" "${HARNESS_BUNDLE_ID}"
 
 log "Checking simulator focus..."
 FOCUSED=$(rocketsim simulator focused 2>/dev/null || echo "")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osfactory/har",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Open harness for reproducible multi-agent coding workflows",
   "keywords": [
     "har",