@osfactory/har 0.54.0 → 0.55.0

package/dist/templates/har-boilerplate/agent-slot.sh

@@ -326,6 +326,49 @@ har_regenerate_agent_env_file() {
   fi
 }
 
+# Untracked (not ignored) paths stay in the main checkout when a session
+# worktree is created from HEAD. Advisory — never fails the launch.
+har_warn_untracked_worktree() {
+  case "${USE_WORKTREE:-${HARNESS_USE_WORKTREE:-true}}" in
+    true|TRUE|yes|YES|1) ;;
+    *) return 0 ;;
+  esac
+  local root="${REPO_ROOT:-}"
+  if [ -z "$root" ] && [ -n "${SCRIPT_DIR:-}" ]; then
+    root="$(cd "$SCRIPT_DIR/.." && pwd)"
+  fi
+  [ -n "$root" ] || return 0
+  git -C "$root" rev-parse --is-inside-work-tree >/dev/null 2>&1 || return 0
+
+  local paths=()
+  local entry
+  while IFS= read -r -d '' entry; do
+    paths+=("$entry")
+  done < <(git -C "$root" --literal-pathspecs ls-files --others --exclude-standard --directory -z 2>/dev/null || true)
+
+  local count="${#paths[@]}"
+  [ "$count" -gt 0 ] || return 0
+
+  local max=8
+  local listed=""
+  local i
+  for ((i = 0; i < count && i < max; i++)); do
+    [ -n "$listed" ] && listed+=", "
+    listed+="${paths[$i]}"
+  done
+  if [ "$count" -gt "$max" ]; then
+    listed+=" (+$((count - max)) more)"
+  fi
+
+  local noun="paths"
+  local them="They are"
+  if [ "$count" -eq 1 ]; then
+    noun="path"
+    them="It is"
+  fi
+  echo "WARN: ${count} untracked ${noun} will not appear in the session worktree: ${listed}. ${them} only in the main checkout — track them, or launch with --no-worktree." >&2
+}
+
 # har_launch_preflight <agent_id> [resume]
 # Exit 0 when ready; 2 when occupied (free the slot first) or not resumable; 1 on machine blockers.
 # Sets FE_PORT/API_PORT/DEBUG_PORT when this harness uses PM2.
@@ -364,6 +407,7 @@ har_launch_preflight() {
       fi
     done
   fi
+  har_warn_untracked_worktree
   return 0
 }
 
@@ -445,6 +489,35 @@ try {
 #   optional: SLOT_SUFFIX, SLOT_WORKTREE_PATH, SLOT_BRANCH, SLOT_BASE_BRANCH,
 #             SLOT_BASE_COMMIT, SLOT_PORTS_JSON, SLOT_PREVIEW_URLS_JSON,
 #             SLOT_STATUS, SLOT_LAST_ERROR, SLOT_WORK_UNIT_ID, SLOT_ATTEMPT_ID
+# Mission Control re-reads slot state only when something syncs, and a sync takes
+# about twenty seconds — too long to make a slot change wait for it. Detached, and
+# coalesced so a run of slot changes leaves one sync going, then one more if needed.
+har_notify_control() {
+  local root bin lock
+  root="$(cd "${SCRIPT_DIR}/.." && pwd)"
+  bin="$(command -v har 2>/dev/null || echo "${root}/node_modules/.bin/har")"
+  [ -x "$bin" ] || return 0
+
+  lock="${TMPDIR:-/tmp}/har-control-sync.$(id -u)"
+  : > "${lock}.pending"
+  mkdir "$lock" 2>/dev/null || return 0
+  (
+    trap "" HUP
+    trap 'rmdir "$lock" 2>/dev/null || true' EXIT
+    cd "$root" || exit 0
+    while [ -f "${lock}.pending" ]; do
+      rm -f "${lock}.pending"
+      if command -v timeout >/dev/null 2>&1; then
+        timeout 120 "$bin" control sync || true
+      else
+        "$bin" control sync || true
+      fi
+    done
+  # Redirected as a whole, not per command: a background job that keeps the inherited
+  # stdout open makes any caller reading that pipe wait for it.
+  ) >/dev/null 2>&1 &
+}
+
 write_slot_registry() {
   local file
   file="$(slot_registry_file "$SLOT_AGENT_ID")"
@@ -474,10 +547,12 @@ for (const [key, env] of [["ports", "SLOT_PORTS_JSON"], ["previewUrls", "SLOT_PR
 }
 fs.writeFileSync(process.argv[1], JSON.stringify(entry, null, 2) + "\n");
 ' "$file"
+  har_notify_control
 }
 
 remove_slot_registry() {
   rm -f "$(slot_registry_file "$1")"
+  har_notify_control
 }
 
 # Exit 0 when the worktree has uncommitted or untracked changes.

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

@@ -310,6 +310,49 @@ EOF
   fi
 }
 
+# Untracked (not ignored) paths stay in the main checkout when a session
+# worktree is created from HEAD. Advisory — never fails the launch.
+har_warn_untracked_worktree() {
+  case "${USE_WORKTREE:-${HARNESS_USE_WORKTREE:-true}}" in
+    true|TRUE|yes|YES|1) ;;
+    *) return 0 ;;
+  esac
+  local root="${REPO_ROOT:-}"
+  if [ -z "$root" ] && [ -n "${SCRIPT_DIR:-}" ]; then
+    root="$(cd "$SCRIPT_DIR/.." && pwd)"
+  fi
+  [ -n "$root" ] || return 0
+  git -C "$root" rev-parse --is-inside-work-tree >/dev/null 2>&1 || return 0
+
+  local paths=()
+  local entry
+  while IFS= read -r -d '' entry; do
+    paths+=("$entry")
+  done < <(git -C "$root" --literal-pathspecs ls-files --others --exclude-standard --directory -z 2>/dev/null || true)
+
+  local count="${#paths[@]}"
+  [ "$count" -gt 0 ] || return 0
+
+  local max=8
+  local listed=""
+  local i
+  for ((i = 0; i < count && i < max; i++)); do
+    [ -n "$listed" ] && listed+=", "
+    listed+="${paths[$i]}"
+  done
+  if [ "$count" -gt "$max" ]; then
+    listed+=" (+$((count - max)) more)"
+  fi
+
+  local noun="paths"
+  local them="They are"
+  if [ "$count" -eq 1 ]; then
+    noun="path"
+    them="It is"
+  fi
+  echo "WARN: ${count} untracked ${noun} will not appear in the session worktree: ${listed}. ${them} only in the main checkout — track them, or launch with --no-worktree." >&2
+}
+
 # har_launch_preflight <agent_id> [resume]
 # Exit 0 when ready; 2 when occupied (free the slot first) or not resumable; 1 on machine blockers.
 har_launch_preflight() {
@@ -346,6 +389,7 @@ har_launch_preflight() {
       fi
     done
   fi
+  har_warn_untracked_worktree
   return 0
 }
 
@@ -427,6 +471,35 @@ try {
 #   optional: SLOT_SUFFIX, SLOT_WORKTREE_PATH, SLOT_BRANCH, SLOT_BASE_BRANCH,
 #             SLOT_BASE_COMMIT, SLOT_PORTS_JSON, SLOT_PREVIEW_URLS_JSON,
 #             SLOT_STATUS, SLOT_LAST_ERROR, SLOT_WORK_UNIT_ID, SLOT_ATTEMPT_ID
+# Mission Control re-reads slot state only when something syncs, and a sync takes
+# about twenty seconds — too long to make a slot change wait for it. Detached, and
+# coalesced so a run of slot changes leaves one sync going, then one more if needed.
+har_notify_control() {
+  local root bin lock
+  root="$(cd "${SCRIPT_DIR}/.." && pwd)"
+  bin="$(command -v har 2>/dev/null || echo "${root}/node_modules/.bin/har")"
+  [ -x "$bin" ] || return 0
+
+  lock="${TMPDIR:-/tmp}/har-control-sync.$(id -u)"
+  : > "${lock}.pending"
+  mkdir "$lock" 2>/dev/null || return 0
+  (
+    trap "" HUP
+    trap 'rmdir "$lock" 2>/dev/null || true' EXIT
+    cd "$root" || exit 0
+    while [ -f "${lock}.pending" ]; do
+      rm -f "${lock}.pending"
+      if command -v timeout >/dev/null 2>&1; then
+        timeout 120 "$bin" control sync || true
+      else
+        "$bin" control sync || true
+      fi
+    done
+  # Redirected as a whole, not per command: a background job that keeps the inherited
+  # stdout open makes any caller reading that pipe wait for it.
+  ) >/dev/null 2>&1 &
+}
+
 write_slot_registry() {
   local file
   file="$(slot_registry_file "$SLOT_AGENT_ID")"
@@ -456,10 +529,12 @@ for (const [key, env] of [["ports", "SLOT_PORTS_JSON"], ["previewUrls", "SLOT_PR
 }
 fs.writeFileSync(process.argv[1], JSON.stringify(entry, null, 2) + "\n");
 ' "$file"
+  har_notify_control
 }
 
 remove_slot_registry() {
   rm -f "$(slot_registry_file "$1")"
+  har_notify_control
 }
 
 # Exit 0 when the worktree has uncommitted or untracked changes.

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

@@ -109,6 +109,24 @@ 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.
 
+### Running from an agent sandbox
+
+`xcrun simctl` reaches CoreSimulatorService over XPC. Coding agents that sandbox
+their shell (Codex, Claude Code and others) usually deny that lookup, so `simctl`
+fails while `xcodebuild` keeps working — every simulator command then dies with
+`CoreSimulatorService connection became invalid`. Nothing is missing on the machine.
+
+Launch and teardown say so when it happens. Either run `har env launch <id>` and
+`har env teardown <id>` from a normal terminal and let the agent work in the
+worktree, or grant the agent unsandboxed access to `xcrun simctl` — the escalation
+must cover every subcommand the harness uses (`list`, `create`, `boot`,
+`bootstatus`, `shutdown`, `delete`), not just `list`.
+
+The same messages distinguish a second cause: if `xcrun simctl` is missing from
+the selected developer directory — no Xcode, or `xcode-select` pointing at the
+Command Line Tools — they say so and print the current selection instead of
+blaming a sandbox.
+
 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/`.

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

@@ -95,6 +95,35 @@ try {
 #   optional: SLOT_SUFFIX, SLOT_WORKTREE_PATH, SLOT_BRANCH, SLOT_BASE_BRANCH,
 #             SLOT_BASE_COMMIT, SLOT_PORTS_JSON, SLOT_PREVIEW_URLS_JSON,
 #             SLOT_STATUS, SLOT_LAST_ERROR, SLOT_WORK_UNIT_ID, SLOT_ATTEMPT_ID
+# Mission Control re-reads slot state only when something syncs, and a sync takes
+# about twenty seconds — too long to make a slot change wait for it. Detached, and
+# coalesced so a run of slot changes leaves one sync going, then one more if needed.
+har_notify_control() {
+  local root bin lock
+  root="$(cd "${SCRIPT_DIR}/.." && pwd)"
+  bin="$(command -v har 2>/dev/null || echo "${root}/node_modules/.bin/har")"
+  [ -x "$bin" ] || return 0
+
+  lock="${TMPDIR:-/tmp}/har-control-sync.$(id -u)"
+  : > "${lock}.pending"
+  mkdir "$lock" 2>/dev/null || return 0
+  (
+    trap "" HUP
+    trap 'rmdir "$lock" 2>/dev/null || true' EXIT
+    cd "$root" || exit 0
+    while [ -f "${lock}.pending" ]; do
+      rm -f "${lock}.pending"
+      if command -v timeout >/dev/null 2>&1; then
+        timeout 120 "$bin" control sync || true
+      else
+        "$bin" control sync || true
+      fi
+    done
+  # Redirected as a whole, not per command: a background job that keeps the inherited
+  # stdout open makes any caller reading that pipe wait for it.
+  ) >/dev/null 2>&1 &
+}
+
 write_slot_registry() {
   local file
   file="$(slot_registry_file "$SLOT_AGENT_ID")"
@@ -124,10 +153,12 @@ for (const [key, env] of [["ports", "SLOT_PORTS_JSON"], ["previewUrls", "SLOT_PR
 }
 fs.writeFileSync(process.argv[1], JSON.stringify(entry, null, 2) + "\n");
 ' "$file"
+  har_notify_control
 }
 
 remove_slot_registry() {
   rm -f "$(slot_registry_file "$1")"
+  har_notify_control
 }
 
 # Exit 0 when the worktree has uncommitted or untracked changes.
@@ -208,6 +239,49 @@ print_slot_occupied_warning() {
   echo "" >&2
 }
 
+# Untracked (not ignored) paths stay in the main checkout when a session
+# worktree is created from HEAD. Advisory — never fails the launch.
+har_warn_untracked_worktree() {
+  case "${USE_WORKTREE:-${HARNESS_USE_WORKTREE:-true}}" in
+    true|TRUE|yes|YES|1) ;;
+    *) return 0 ;;
+  esac
+  local root="${REPO_ROOT:-}"
+  if [ -z "$root" ] && [ -n "${SCRIPT_DIR:-}" ]; then
+    root="$(cd "$SCRIPT_DIR/.." && pwd)"
+  fi
+  [ -n "$root" ] || return 0
+  git -C "$root" rev-parse --is-inside-work-tree >/dev/null 2>&1 || return 0
+
+  local paths=()
+  local entry
+  while IFS= read -r -d '' entry; do
+    paths+=("$entry")
+  done < <(git -C "$root" --literal-pathspecs ls-files --others --exclude-standard --directory -z 2>/dev/null || true)
+
+  local count="${#paths[@]}"
+  [ "$count" -gt 0 ] || return 0
+
+  local max=8
+  local listed=""
+  local i
+  for ((i = 0; i < count && i < max; i++)); do
+    [ -n "$listed" ] && listed+=", "
+    listed+="${paths[$i]}"
+  done
+  if [ "$count" -gt "$max" ]; then
+    listed+=" (+$((count - max)) more)"
+  fi
+
+  local noun="paths"
+  local them="They are"
+  if [ "$count" -eq 1 ]; then
+    noun="path"
+    them="It is"
+  fi
+  echo "WARN: ${count} untracked ${noun} will not appear in the session worktree: ${listed}. ${them} only in the main checkout — track them, or launch with --no-worktree." >&2
+}
+
 git_common_dir() {
   local cwd="$1"
   local out

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

@@ -56,6 +56,8 @@ if slot_is_occupied "$AGENT_ID"; then
   exit 2
 fi
 
+har_warn_untracked_worktree
+
 "$SCRIPT_DIR/setup-infra.sh"
 
 # Session worktree (default — use --no-worktree to work in repo root).

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

@@ -19,6 +19,14 @@ source "$SCRIPT_DIR/simulator.sh"
 
 log() { echo "==> $*" >&2; }
 
+# simctl could not be asked, so nothing it did not return is evidence of anything
+# missing on this machine. The wording lives in simulator.sh so launch and this
+# script cannot drift apart on which of the two causes they name.
+fail_simctl_unavailable() {
+  har_sim_log_simctl_unavailable
+  exit 1
+}
+
 # ── Xcode check ───────────────────────────────────────────────────────────────
 if ! command -v xcodebuild >/dev/null 2>&1; then
   echo "Error: xcodebuild not found — install Xcode from the App Store." >&2
@@ -40,6 +48,8 @@ if har_sim_per_slot_enabled; then
   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" = "SIMCTL_UNAVAILABLE" ]; then
+    fail_simctl_unavailable
   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}'."
@@ -63,6 +73,7 @@ else
   UDID="${RESOLVED%%$'\t'*}"
 
   if [ -z "$UDID" ]; then
+    har_sim_simctl_available || fail_simctl_unavailable
     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

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

@@ -108,10 +108,25 @@ har_sim_claim_owner_of() {
 
 # ── Device discovery ──────────────────────────────────────────────────────────
 
+# Every simctl call goes through here, so "simctl could not be asked" stays
+# distinguishable from "simctl answered, and the answer is empty" at the one place
+# that still knows the difference. Non-zero means the first; callers check it
+# instead of reading an empty list as a fact about the machine.
+har_sim_simctl() {
+  local out rc=0
+  out="$(xcrun simctl "$@" 2>/dev/null)" || rc=$?
+  if [ "$rc" -ne 0 ] || [ -z "$out" ]; then
+    return 1
+  fi
+  printf '%s' "$out"
+}
+
 # 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 '
+  local devices
+  devices="$(har_sim_simctl list devices --json)" || return 1
+  printf '%s' "$devices" | node -e '
 const data = JSON.parse(require("fs").readFileSync(0, "utf8"));
 const [want, field] = process.argv.slice(1);
 const device = Object.values(data.devices || {})
@@ -128,9 +143,10 @@ 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:-}"
+  local want="${1:-}" devices
   [ -n "$want" ] || return 0
-  xcrun simctl list devices available --json 2>/dev/null | node -e '
+  devices="$(har_sim_simctl list devices available --json)" || return 1
+  printf '%s' "$devices" | node -e '
 const data = JSON.parse(require("fs").readFileSync(0, "utf8"));
 const want = process.argv[1];
 const rows = [];
@@ -157,22 +173,66 @@ har_sim_resolve_configured() {
   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.
+# `simctl list` is a subprocess and a JSON parse, so each answer is cached — but in
+# the calling shell, not the process: `$(har_sim_runtimes_json)` fetches, then throws
+# the cache and the availability flag away with the subshell that held them. Call
+# these directly and read the variable whenever either one matters.
 har_sim_devicetypes_json() {
   if [ -z "${_HAR_SIM_TYPES_JSON:-}" ]; then
-    _HAR_SIM_TYPES_JSON="$(xcrun simctl list devicetypes --json 2>/dev/null || echo '{}')"
+    _HAR_SIM_TYPES_JSON="$(har_sim_simctl list devicetypes --json)" || _HAR_SIM_TYPES_JSON='{}'
   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 '{}')"
+    if _HAR_SIM_RUNTIMES_JSON="$(har_sim_simctl list runtimes --json)"; then
+      _HAR_SIM_SIMCTL_OK=true
+    else
+      _HAR_SIM_RUNTIMES_JSON='{}'
+      _HAR_SIM_SIMCTL_OK=false
+      # A second call, but only ever when simctl is already failing — and failing
+      # is the fast path. Its stderr is the only thing that tells the causes apart.
+      _HAR_SIM_SIMCTL_ERROR="$(xcrun simctl list runtimes --json 2>&1 >/dev/null || true)"
+    fi
   fi
   printf '%s' "$_HAR_SIM_RUNTIMES_JSON"
 }
 
+# Ask simctl once, recording in this shell whether it answered and why not.
+har_sim_probe_simctl() {
+  har_sim_runtimes_json >/dev/null
+}
+
+har_sim_simctl_available() {
+  har_sim_probe_simctl
+  [ "${_HAR_SIM_SIMCTL_OK:-true}" = "true" ]
+}
+
+# Two unrelated problems make simctl unusable — a sandbox denying the
+# CoreSimulatorService lookup, and a developer directory with no simctl in it.
+# Naming the wrong one costs the reader the hunt this check exists to prevent.
+har_sim_log_simctl_unavailable() {
+  # Teardown hits two failures in a row; the cause only needs saying once.
+  [ -z "${_HAR_SIM_SIMCTL_CAUSE_REPORTED:-}" ] || return 0
+  _HAR_SIM_SIMCTL_CAUSE_REPORTED=1
+  # For a launch the failing call happened inside the command substitution around
+  # har_sim_plan_creation, so the reason died with that subshell — ask again here.
+  har_sim_probe_simctl
+  case "${_HAR_SIM_SIMCTL_ERROR:-}" in
+    *"not a developer tool"*|*"unable to find utility"*|*"command not found"*)
+      har_sim_log "'xcrun simctl' is not in the selected developer directory"
+      har_sim_log "  install Xcode, then point the toolchain at it:"
+      har_sim_log "    sudo xcode-select -s /Applications/Xcode.app"
+      har_sim_log "  current selection: $(xcode-select -p 2>/dev/null || echo 'none')"
+      return
+      ;;
+  esac
+  har_sim_log "cannot reach CoreSimulatorService — 'xcrun simctl' is unusable here"
+  har_sim_log "  this usually means the command is running inside an agent sandbox"
+  har_sim_log "  run it from a normal terminal, or let the agent run 'xcrun simctl' unsandboxed"
+}
+
 # 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:
@@ -180,10 +240,18 @@ har_sim_runtimes_json() {
 #   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
+#   SIMCTL_UNAVAILABLE                simctl could not be asked at all
 har_sim_plan_creation() {
   local types runtimes
   types="$(har_sim_devicetypes_json)"
-  runtimes="$(har_sim_runtimes_json)"
+  # Not `$(...)`: that would discard the availability flag with the subshell.
+  har_sim_runtimes_json >/dev/null
+  runtimes="$_HAR_SIM_RUNTIMES_JSON"
+  # Checked before the empty lists are read as an answer about the machine.
+  if ! har_sim_simctl_available; then
+    printf 'SIMCTL_UNAVAILABLE'
+    return
+  fi
   node -e '
 const [typesRaw, runtimesRaw, wantName, family] = process.argv.slice(1);
 const types = JSON.parse(typesRaw).devicetypes || [];
@@ -240,7 +308,9 @@ process.stdout.write(plan());
 # 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 '
+  local devices
+  devices="$(har_sim_simctl list devices --json)" || return 1
+  printf '%s' "$devices" | node -e '
 const data = JSON.parse(require("fs").readFileSync(0, "utf8"));
 const prefix = process.argv[1];
 const matches = Object.values(data.devices || {})
@@ -252,12 +322,19 @@ process.stdout.write(matches.join("\n"));
 ' "$1" 2>/dev/null || true
 }
 
+# Returns 0 even when it could not look: teardown.sh runs under `set -e`, and
+# aborting there would leave the slot registry behind on top of the device.
 har_sim_delete_devices_with_prefix() {
-  local udid
+  local udid list
+  if ! list="$(har_sim_devices_with_prefix "$1")"; then
+    har_sim_log "cannot check for leftover devices named ${1}* — none were removed"
+    har_sim_log_simctl_unavailable
+    return 0
+  fi
   while read -r udid; do
     [ -n "$udid" ] || continue
     xcrun simctl delete "$udid" >/dev/null 2>&1 || true
-  done <<< "$(har_sim_devices_with_prefix "$1")"
+  done <<< "$list"
 }
 
 # ── Boot ──────────────────────────────────────────────────────────────────────
@@ -289,7 +366,11 @@ _har_sim_select() {
 
   # 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")"
+    # A failed lookup is "could not ask"; an empty one is "no such device".
+    name="$(har_sim_device_name "$HARNESS_SIMULATOR_UDID")" || {
+      har_sim_log_simctl_unavailable
+      return 1
+    }
     if [ -z "$name" ]; then
       har_sim_log "HARNESS_SIMULATOR_UDID=${HARNESS_SIMULATOR_UDID} is not a known device"
       return 1
@@ -310,6 +391,11 @@ _har_sim_select() {
   models=""
   [ "$plan" != "$status" ] && models="${plan#*$'\t'}"
 
+  if [ "$status" = "SIMCTL_UNAVAILABLE" ]; then
+    har_sim_log_simctl_unavailable
+    return 1
+  fi
+
   if [ "$status" = "OK" ]; then
     IFS=$'\t' read -r _ device_type model runtime _ <<< "$plan"
     label="$(har_sim_device_label "$agent_id" "$model")"
@@ -388,8 +474,14 @@ har_sim_release() {
     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)"
+      if xcrun simctl delete "$udid" >/dev/null 2>&1; then
+        echo "✓ Deleted simulator created for this slot ($udid)"
+      else
+        # Naming it is the whole remedy left: the claim is gone, so only the name
+        # prefix sweep at the next launch can still find this device.
+        har_sim_log "could not delete ${udid}, created for agent ${agent_id} — it is still on this machine"
+        har_sim_simctl_available || har_sim_log_simctl_unavailable
+      fi
     fi
   fi
 

package/package.json

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