@osfactory/har 0.62.1 → 0.63.0

package/dist/templates/agent-skills/setup-har.md

@@ -14,7 +14,21 @@ If missing, install it and re-check:
 npm install -g @osfactory/har
 ```
 
-## 2. Pick a harness profile
+## 2. Check Docker
+
+Docker is required: Mission Control runs as a container and harness infrastructure
+(databases, queues, browsers) starts through Docker Compose.
+
+```bash
+docker info
+```
+
+If the command fails, tell the user Docker must be installed and running
+(https://docs.docker.com/get-started/get-docker/). You can still scaffold the
+harness, but say clearly that Mission Control and containerized infra stay
+unavailable until Docker works.
+
+## 3. Pick a harness profile
 
 Inspect the repository and choose the profile that matches how agents will run it:
 
@@ -26,7 +40,7 @@ Inspect the repository and choose the profile that matches how agents will run i
 
 Tell the user which profile you picked and why before continuing.
 
-## 3. Initialize the harness
+## 4. Initialize the harness
 
 ```bash
 har env init --profile <profile>   # omit --profile for default
@@ -34,11 +48,11 @@ har env init --profile <profile>   # omit --profile for default
 
 If `.har/` already exists, stop and suggest `/har-maintain` instead.
 
-## 4. Perform the adaptation yourself
+## 5. Perform the adaptation yourself
 
 `har env init` prints an adaptation prompt and writes it to `.har/ADAPT-PROMPT.md`. Read that file and **execute its instructions yourself, now, in this session** — tailor `.har/` scripts (`launch.sh`, `verify.sh`, `setup-infra.sh`, `harness.env`, `stages.json`) and `AGENTS.md` to this repository's real stack, ports, and commands.
 
-## 5. Register the project's checks as stages
+## 6. Register the project's checks as stages
 
 Convert the repository's real check commands (test, lint, typecheck, whatever CI runs) into registered stages so they run in `verify --full` and are visible to every agent. Read `.har/STAGES.md` for the contract, then:
 
@@ -49,7 +63,7 @@ har env add-stage unit-tests --custom --kind test --command "npm test" --verific
 - Use `--command` for one-liner checks; use `--script` when a check needs the slot's env, ports, or artifacts (then implement the scaffolded `.har/stages/<id>.sh`).
 - Rich integrations ship as **plugins**: `har env add-plugin --list`, then e.g. `har env add-plugin playwright` (web) or `har env add-plugin rocketsim` (iOS). Plugins install stages; agents only talk to the stage registry.
 
-## 6. Prove the harness works
+## 7. Prove the harness works
 
 ```bash
 har env launch 1
@@ -58,7 +72,7 @@ har env verify 1
 
 Fix the harness scripts until both pass. Then tear down or keep the slot as the user prefers (`har env teardown 1` keeps the branch).
 
-## 7. Commit
+## 8. Commit
 
 After the user confirms, commit the harness:
 

package/dist/templates/agent-skills/skills.manifest.json

@@ -10,7 +10,7 @@
           "name": "setup-har",
           "description": "Install the har CLI and scaffold the .har/ agent harness in this repository (init, adapt, launch, verify, commit). User-invoked onboarding.",
           "disable-model-invocation": true,
-          "allowed-tools": "Bash(har *) Bash(npm *) Bash(git *) Read Grep Glob Edit Write"
+          "allowed-tools": "Bash(har *) Bash(npm *) Bash(git *) Bash(docker *) Read Grep Glob Edit Write"
         }
       },
       "cursor": { "command": true },

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

@@ -586,9 +586,129 @@ provision_ruby() {
   append_path_prefix "$dir/vendor/bundle/bin"
 }
 
+# ── iOS Xcode project helpers ─────────────────────────────────────────────────
+# Tuist, XcodeGen and CocoaPods treat the .xcodeproj / .xcworkspace as a build
+# product rather than a tracked file, so a fresh worktree has nothing for
+# xcodebuild to open. Generate it here — and fail naming the missing generator,
+# instead of letting xcodebuild report an opaque "scheme not found" later.
+
+# First project file of a kind in the work dir. Runs from inside the dir so a dot
+# in the worktree path itself cannot trip the dotfile filter, and skips both the
+# project.xcworkspace every .xcodeproj carries inside it and whatever CocoaPods
+# generates under Pods/.
+har_ios_find_project_file() {
+  local dir="$1"
+  local pattern="$2"
+  local match=""
+  match="$(cd "$dir" 2>/dev/null && find . -maxdepth 2 -name "$pattern" \
+    ! -path "./.*" ! -path "*.xcodeproj/*" ! -path "*/Pods/*" 2>/dev/null | head -1)" || true
+  [ -n "$match" ] || return 1
+  echo "${match#./}"
+}
+
+# True when this worktree already has something xcodebuild can open. Adapt-time
+# HARNESS_XCODE_WORKSPACE / HARNESS_XCODE_PROJECT decide it when set: they name
+# the generated file, so a missing one means the generator still has to run.
+har_ios_has_project() {
+  local dir="$1"
+
+  if [ -n "${HARNESS_XCODE_WORKSPACE:-}" ] || [ -n "${HARNESS_XCODE_PROJECT:-}" ]; then
+    if [ -n "${HARNESS_XCODE_WORKSPACE:-}" ] && [ -e "$dir/$HARNESS_XCODE_WORKSPACE" ]; then
+      return 0
+    fi
+    if [ -n "${HARNESS_XCODE_PROJECT:-}" ] && [ -e "$dir/$HARNESS_XCODE_PROJECT" ]; then
+      return 0
+    fi
+    return 1
+  fi
+
+  if har_ios_find_project_file "$dir" '*.xcworkspace' >/dev/null; then return 0; fi
+  if har_ios_find_project_file "$dir" '*.xcodeproj' >/dev/null; then return 0; fi
+  return 1
+}
+
+# Generator this repo declares, or empty. A Podfile counts: `pod install` is what
+# writes the .xcworkspace for a CocoaPods project.
+har_ios_project_generator() {
+  local dir="$1"
+  if [ -f "$dir/Project.swift" ] || [ -f "$dir/Workspace.swift" ]; then echo tuist; return; fi
+  if [ -f "$dir/project.yml" ] || [ -f "$dir/project.yaml" ]; then echo xcodegen; return; fi
+  if [ -f "$dir/Podfile" ]; then echo pod; return; fi
+  echo ""
+}
+
+har_ios_generate_project() {
+  local dir="$1"
+  local generator=""
+
+  if har_ios_has_project "$dir"; then
+    return 0
+  fi
+
+  generator="$(har_ios_project_generator "$dir")"
+  if [ -z "$generator" ]; then
+    pt_log "No .xcodeproj/.xcworkspace found and no generator manifest (Project.swift, project.yml, Podfile) — set HARNESS_XCODE_PROJECT/HARNESS_XCODE_WORKSPACE or HARNESS_INSTALL_CMD in harness.env"
+    return 0
+  fi
+
+  if ! command -v "$generator" >/dev/null 2>&1; then
+    local label="$generator"
+    [ "$generator" = "pod" ] && label="CocoaPods (pod)"
+    pt_log "ERROR: this repo generates its Xcode project with ${label}, which is not on PATH."
+    pt_log "       Install ${label}, or set HARNESS_INSTALL_CMD in harness.env to provision the project another way."
+    return 1
+  fi
+
+  case "$generator" in
+    tuist)
+      pt_log "Generating the Xcode project with tuist..."
+      if ! (cd "$dir" && tuist generate --no-open); then
+        pt_log "tuist generate --no-open failed — retrying without the flag"
+        (cd "$dir" && tuist generate)
+      fi
+      ;;
+    xcodegen)
+      pt_log "Generating the Xcode project with xcodegen..."
+      (cd "$dir" && xcodegen generate)
+      ;;
+    pod)
+      # har_ios_pod_install writes the workspace right after this.
+      :
+      ;;
+  esac
+}
+
+# CocoaPods dependencies. Independent of project generation: a tracked
+# .xcworkspace still cannot build when Pods/ is missing in a fresh worktree.
+har_ios_pod_install() {
+  local dir="$1"
+
+  [ -f "$dir/Podfile" ] || return 0
+  [ -d "$dir/Pods" ] && return 0
+
+  if ! command -v pod >/dev/null 2>&1; then
+    pt_log "ERROR: this repo uses CocoaPods (Podfile, no Pods/) and pod is not on PATH."
+    pt_log "       Install CocoaPods, or set HARNESS_INSTALL_CMD in harness.env to provision the project another way."
+    return 1
+  fi
+
+  pt_log "Installing CocoaPods dependencies..."
+  (cd "$dir" && pod install)
+}
+
 provision_ios() {
   local dir="$1"
-  run_install_cmd "$dir" || true
+
+  # An explicit HARNESS_INSTALL_CMD owns provisioning outright: the default
+  # generators stay out of the way, and a failing override fails the launch
+  # rather than being papered over.
+  if [ -n "${HARNESS_INSTALL_CMD:-}" ]; then
+    run_install_cmd "$dir"
+  else
+    har_ios_generate_project "$dir"
+    har_ios_pod_install "$dir"
+  fi
+
   append_env "HARNESS_ECOSYSTEM" "ios"
   append_env "XCODEBUILD_BIN" "$(command -v xcodebuild 2>/dev/null || echo xcodebuild)"
   if [ -n "${HARNESS_XCODE_SCHEME:-}" ]; then

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

@@ -586,9 +586,129 @@ provision_ruby() {
   append_path_prefix "$dir/vendor/bundle/bin"
 }
 
+# ── iOS Xcode project helpers ─────────────────────────────────────────────────
+# Tuist, XcodeGen and CocoaPods treat the .xcodeproj / .xcworkspace as a build
+# product rather than a tracked file, so a fresh worktree has nothing for
+# xcodebuild to open. Generate it here — and fail naming the missing generator,
+# instead of letting xcodebuild report an opaque "scheme not found" later.
+
+# First project file of a kind in the work dir. Runs from inside the dir so a dot
+# in the worktree path itself cannot trip the dotfile filter, and skips both the
+# project.xcworkspace every .xcodeproj carries inside it and whatever CocoaPods
+# generates under Pods/.
+har_ios_find_project_file() {
+  local dir="$1"
+  local pattern="$2"
+  local match=""
+  match="$(cd "$dir" 2>/dev/null && find . -maxdepth 2 -name "$pattern" \
+    ! -path "./.*" ! -path "*.xcodeproj/*" ! -path "*/Pods/*" 2>/dev/null | head -1)" || true
+  [ -n "$match" ] || return 1
+  echo "${match#./}"
+}
+
+# True when this worktree already has something xcodebuild can open. Adapt-time
+# HARNESS_XCODE_WORKSPACE / HARNESS_XCODE_PROJECT decide it when set: they name
+# the generated file, so a missing one means the generator still has to run.
+har_ios_has_project() {
+  local dir="$1"
+
+  if [ -n "${HARNESS_XCODE_WORKSPACE:-}" ] || [ -n "${HARNESS_XCODE_PROJECT:-}" ]; then
+    if [ -n "${HARNESS_XCODE_WORKSPACE:-}" ] && [ -e "$dir/$HARNESS_XCODE_WORKSPACE" ]; then
+      return 0
+    fi
+    if [ -n "${HARNESS_XCODE_PROJECT:-}" ] && [ -e "$dir/$HARNESS_XCODE_PROJECT" ]; then
+      return 0
+    fi
+    return 1
+  fi
+
+  if har_ios_find_project_file "$dir" '*.xcworkspace' >/dev/null; then return 0; fi
+  if har_ios_find_project_file "$dir" '*.xcodeproj' >/dev/null; then return 0; fi
+  return 1
+}
+
+# Generator this repo declares, or empty. A Podfile counts: `pod install` is what
+# writes the .xcworkspace for a CocoaPods project.
+har_ios_project_generator() {
+  local dir="$1"
+  if [ -f "$dir/Project.swift" ] || [ -f "$dir/Workspace.swift" ]; then echo tuist; return; fi
+  if [ -f "$dir/project.yml" ] || [ -f "$dir/project.yaml" ]; then echo xcodegen; return; fi
+  if [ -f "$dir/Podfile" ]; then echo pod; return; fi
+  echo ""
+}
+
+har_ios_generate_project() {
+  local dir="$1"
+  local generator=""
+
+  if har_ios_has_project "$dir"; then
+    return 0
+  fi
+
+  generator="$(har_ios_project_generator "$dir")"
+  if [ -z "$generator" ]; then
+    pt_log "No .xcodeproj/.xcworkspace found and no generator manifest (Project.swift, project.yml, Podfile) — set HARNESS_XCODE_PROJECT/HARNESS_XCODE_WORKSPACE or HARNESS_INSTALL_CMD in harness.env"
+    return 0
+  fi
+
+  if ! command -v "$generator" >/dev/null 2>&1; then
+    local label="$generator"
+    [ "$generator" = "pod" ] && label="CocoaPods (pod)"
+    pt_log "ERROR: this repo generates its Xcode project with ${label}, which is not on PATH."
+    pt_log "       Install ${label}, or set HARNESS_INSTALL_CMD in harness.env to provision the project another way."
+    return 1
+  fi
+
+  case "$generator" in
+    tuist)
+      pt_log "Generating the Xcode project with tuist..."
+      if ! (cd "$dir" && tuist generate --no-open); then
+        pt_log "tuist generate --no-open failed — retrying without the flag"
+        (cd "$dir" && tuist generate)
+      fi
+      ;;
+    xcodegen)
+      pt_log "Generating the Xcode project with xcodegen..."
+      (cd "$dir" && xcodegen generate)
+      ;;
+    pod)
+      # har_ios_pod_install writes the workspace right after this.
+      :
+      ;;
+  esac
+}
+
+# CocoaPods dependencies. Independent of project generation: a tracked
+# .xcworkspace still cannot build when Pods/ is missing in a fresh worktree.
+har_ios_pod_install() {
+  local dir="$1"
+
+  [ -f "$dir/Podfile" ] || return 0
+  [ -d "$dir/Pods" ] && return 0
+
+  if ! command -v pod >/dev/null 2>&1; then
+    pt_log "ERROR: this repo uses CocoaPods (Podfile, no Pods/) and pod is not on PATH."
+    pt_log "       Install CocoaPods, or set HARNESS_INSTALL_CMD in harness.env to provision the project another way."
+    return 1
+  fi
+
+  pt_log "Installing CocoaPods dependencies..."
+  (cd "$dir" && pod install)
+}
+
 provision_ios() {
   local dir="$1"
-  run_install_cmd "$dir" || true
+
+  # An explicit HARNESS_INSTALL_CMD owns provisioning outright: the default
+  # generators stay out of the way, and a failing override fails the launch
+  # rather than being papered over.
+  if [ -n "${HARNESS_INSTALL_CMD:-}" ]; then
+    run_install_cmd "$dir"
+  else
+    har_ios_generate_project "$dir"
+    har_ios_pod_install "$dir"
+  fi
+
   append_env "HARNESS_ECOSYSTEM" "ios"
   append_env "XCODEBUILD_BIN" "$(command -v xcodebuild 2>/dev/null || echo xcodebuild)"
   if [ -n "${HARNESS_XCODE_SCHEME:-}" ]; then

package/dist/templates/har-boilerplate-ios/ADAPT-PROMPT.md

@@ -21,6 +21,12 @@ structure, then make the changes listed below. Commit when done.
 | `HARNESS_SIMULATOR_NAME` | Display name exactly as shown in `xcrun simctl list devices` (e.g. `iPhone 16`). |
 | `HARNESS_BUNDLE_ID` | App bundle identifier from the Xcode target (e.g. `com.example.myapp`). |
 
+If the project is generated (`Project.swift`, `project.yml`, or a `Podfile` with no
+tracked `.xcworkspace`), still set the path the generator produces — launch runs
+`tuist generate` / `xcodegen generate` / `pod install` when the file is absent from
+a fresh worktree. Use `HARNESS_INSTALL_CMD` only when that default is wrong; it then
+owns provisioning outright.
+
 Run `./.har/setup-infra.sh` after editing to confirm the simulator boots.
 
 ## 3 — Verify `.har/verify.sh` builds and tests correctly

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

@@ -21,7 +21,7 @@ Generated and maintained by [`har`](https://github.com/os-factory/har). Run `har
 | `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>` |
+| `provision-toolchain.sh` | Generate the Xcode project when it is a build product (Tuist / XcodeGen / CocoaPods) and write Xcode 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) |
 | `agent-cli.sh` | Inspect slot status, run xcodebuild commands, install/launch app |

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

@@ -9,6 +9,12 @@ export HARNESS_AGENT_SLOT_MAX=3
 
 # Toolchain provisioning — launch writes Xcode/simulator paths into .env.agent.<id>
 export HARNESS_ECOSYSTEM="ios"
+# Generated projects: when the worktree has no .xcodeproj/.xcworkspace, launch runs
+# the generator this repo declares — tuist generate (Project.swift), xcodegen
+# generate (project.yml) — plus pod install when a Podfile is present and Pods/ is
+# missing. A missing generator fails the launch by name.
+# HARNESS_INSTALL_CMD owns provisioning outright: set it and no default generator
+# runs, and its failure fails the launch.
 # export HARNESS_INSTALL_CMD="xcodebuild -resolvePackageDependencies ..."
 # Node package manager: auto-detected from package.json "packageManager" and the
 # lockfile (bun.lock → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, else npm),

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

@@ -586,9 +586,129 @@ provision_ruby() {
   append_path_prefix "$dir/vendor/bundle/bin"
 }
 
+# ── iOS Xcode project helpers ─────────────────────────────────────────────────
+# Tuist, XcodeGen and CocoaPods treat the .xcodeproj / .xcworkspace as a build
+# product rather than a tracked file, so a fresh worktree has nothing for
+# xcodebuild to open. Generate it here — and fail naming the missing generator,
+# instead of letting xcodebuild report an opaque "scheme not found" later.
+
+# First project file of a kind in the work dir. Runs from inside the dir so a dot
+# in the worktree path itself cannot trip the dotfile filter, and skips both the
+# project.xcworkspace every .xcodeproj carries inside it and whatever CocoaPods
+# generates under Pods/.
+har_ios_find_project_file() {
+  local dir="$1"
+  local pattern="$2"
+  local match=""
+  match="$(cd "$dir" 2>/dev/null && find . -maxdepth 2 -name "$pattern" \
+    ! -path "./.*" ! -path "*.xcodeproj/*" ! -path "*/Pods/*" 2>/dev/null | head -1)" || true
+  [ -n "$match" ] || return 1
+  echo "${match#./}"
+}
+
+# True when this worktree already has something xcodebuild can open. Adapt-time
+# HARNESS_XCODE_WORKSPACE / HARNESS_XCODE_PROJECT decide it when set: they name
+# the generated file, so a missing one means the generator still has to run.
+har_ios_has_project() {
+  local dir="$1"
+
+  if [ -n "${HARNESS_XCODE_WORKSPACE:-}" ] || [ -n "${HARNESS_XCODE_PROJECT:-}" ]; then
+    if [ -n "${HARNESS_XCODE_WORKSPACE:-}" ] && [ -e "$dir/$HARNESS_XCODE_WORKSPACE" ]; then
+      return 0
+    fi
+    if [ -n "${HARNESS_XCODE_PROJECT:-}" ] && [ -e "$dir/$HARNESS_XCODE_PROJECT" ]; then
+      return 0
+    fi
+    return 1
+  fi
+
+  if har_ios_find_project_file "$dir" '*.xcworkspace' >/dev/null; then return 0; fi
+  if har_ios_find_project_file "$dir" '*.xcodeproj' >/dev/null; then return 0; fi
+  return 1
+}
+
+# Generator this repo declares, or empty. A Podfile counts: `pod install` is what
+# writes the .xcworkspace for a CocoaPods project.
+har_ios_project_generator() {
+  local dir="$1"
+  if [ -f "$dir/Project.swift" ] || [ -f "$dir/Workspace.swift" ]; then echo tuist; return; fi
+  if [ -f "$dir/project.yml" ] || [ -f "$dir/project.yaml" ]; then echo xcodegen; return; fi
+  if [ -f "$dir/Podfile" ]; then echo pod; return; fi
+  echo ""
+}
+
+har_ios_generate_project() {
+  local dir="$1"
+  local generator=""
+
+  if har_ios_has_project "$dir"; then
+    return 0
+  fi
+
+  generator="$(har_ios_project_generator "$dir")"
+  if [ -z "$generator" ]; then
+    pt_log "No .xcodeproj/.xcworkspace found and no generator manifest (Project.swift, project.yml, Podfile) — set HARNESS_XCODE_PROJECT/HARNESS_XCODE_WORKSPACE or HARNESS_INSTALL_CMD in harness.env"
+    return 0
+  fi
+
+  if ! command -v "$generator" >/dev/null 2>&1; then
+    local label="$generator"
+    [ "$generator" = "pod" ] && label="CocoaPods (pod)"
+    pt_log "ERROR: this repo generates its Xcode project with ${label}, which is not on PATH."
+    pt_log "       Install ${label}, or set HARNESS_INSTALL_CMD in harness.env to provision the project another way."
+    return 1
+  fi
+
+  case "$generator" in
+    tuist)
+      pt_log "Generating the Xcode project with tuist..."
+      if ! (cd "$dir" && tuist generate --no-open); then
+        pt_log "tuist generate --no-open failed — retrying without the flag"
+        (cd "$dir" && tuist generate)
+      fi
+      ;;
+    xcodegen)
+      pt_log "Generating the Xcode project with xcodegen..."
+      (cd "$dir" && xcodegen generate)
+      ;;
+    pod)
+      # har_ios_pod_install writes the workspace right after this.
+      :
+      ;;
+  esac
+}
+
+# CocoaPods dependencies. Independent of project generation: a tracked
+# .xcworkspace still cannot build when Pods/ is missing in a fresh worktree.
+har_ios_pod_install() {
+  local dir="$1"
+
+  [ -f "$dir/Podfile" ] || return 0
+  [ -d "$dir/Pods" ] && return 0
+
+  if ! command -v pod >/dev/null 2>&1; then
+    pt_log "ERROR: this repo uses CocoaPods (Podfile, no Pods/) and pod is not on PATH."
+    pt_log "       Install CocoaPods, or set HARNESS_INSTALL_CMD in harness.env to provision the project another way."
+    return 1
+  fi
+
+  pt_log "Installing CocoaPods dependencies..."
+  (cd "$dir" && pod install)
+}
+
 provision_ios() {
   local dir="$1"
-  run_install_cmd "$dir" || true
+
+  # An explicit HARNESS_INSTALL_CMD owns provisioning outright: the default
+  # generators stay out of the way, and a failing override fails the launch
+  # rather than being papered over.
+  if [ -n "${HARNESS_INSTALL_CMD:-}" ]; then
+    run_install_cmd "$dir"
+  else
+    har_ios_generate_project "$dir"
+    har_ios_pod_install "$dir"
+  fi
+
   append_env "HARNESS_ECOSYSTEM" "ios"
   append_env "XCODEBUILD_BIN" "$(command -v xcodebuild 2>/dev/null || echo xcodebuild)"
   if [ -n "${HARNESS_XCODE_SCHEME:-}" ]; then

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

@@ -58,12 +58,18 @@ xc_target_flags() {
   elif [ -n "${HARNESS_XCODE_PROJECT:-}" ] && [ -e "$WORK_DIR/${HARNESS_XCODE_PROJECT}" ]; then
     echo "-project $WORK_DIR/${HARNESS_XCODE_PROJECT}"
   else
-    # Auto-detect: prefer workspace (CocoaPods), then project
+    # Auto-detect: prefer workspace (CocoaPods), then project. Runs from inside
+    # WORK_DIR so a dot in the worktree path itself cannot trip the dotfile
+    # filter, and skips both the project.xcworkspace every .xcodeproj carries
+    # inside it and the CocoaPods project under Pods/ — either would point
+    # xcodebuild at the wrong target.
     local ws prj
-    ws="$(find "$WORK_DIR" -maxdepth 2 -name "*.xcworkspace" ! -path "*/\.*" 2>/dev/null | head -1 || true)"
-    prj="$(find "$WORK_DIR" -maxdepth 2 -name "*.xcodeproj" ! -path "*/\.*" 2>/dev/null | head -1 || true)"
-    if [ -n "$ws" ]; then echo "-workspace $ws"
-    elif [ -n "$prj" ]; then echo "-project $prj"
+    ws="$(cd "$WORK_DIR" && find . -maxdepth 2 -name "*.xcworkspace" \
+      ! -path "./.*" ! -path "*.xcodeproj/*" ! -path "*/Pods/*" 2>/dev/null | head -1 || true)"
+    prj="$(cd "$WORK_DIR" && find . -maxdepth 2 -name "*.xcodeproj" \
+      ! -path "./.*" ! -path "*/Pods/*" 2>/dev/null | head -1 || true)"
+    if [ -n "$ws" ]; then echo "-workspace $WORK_DIR/${ws#./}"
+    elif [ -n "$prj" ]; then echo "-project $WORK_DIR/${prj#./}"
     fi
   fi
 }

package/dist/templates/runtime-bundles/shared-kernel/provision-toolchain.sh

@@ -586,9 +586,129 @@ provision_ruby() {
   append_path_prefix "$dir/vendor/bundle/bin"
 }
 
+# ── iOS Xcode project helpers ─────────────────────────────────────────────────
+# Tuist, XcodeGen and CocoaPods treat the .xcodeproj / .xcworkspace as a build
+# product rather than a tracked file, so a fresh worktree has nothing for
+# xcodebuild to open. Generate it here — and fail naming the missing generator,
+# instead of letting xcodebuild report an opaque "scheme not found" later.
+
+# First project file of a kind in the work dir. Runs from inside the dir so a dot
+# in the worktree path itself cannot trip the dotfile filter, and skips both the
+# project.xcworkspace every .xcodeproj carries inside it and whatever CocoaPods
+# generates under Pods/.
+har_ios_find_project_file() {
+  local dir="$1"
+  local pattern="$2"
+  local match=""
+  match="$(cd "$dir" 2>/dev/null && find . -maxdepth 2 -name "$pattern" \
+    ! -path "./.*" ! -path "*.xcodeproj/*" ! -path "*/Pods/*" 2>/dev/null | head -1)" || true
+  [ -n "$match" ] || return 1
+  echo "${match#./}"
+}
+
+# True when this worktree already has something xcodebuild can open. Adapt-time
+# HARNESS_XCODE_WORKSPACE / HARNESS_XCODE_PROJECT decide it when set: they name
+# the generated file, so a missing one means the generator still has to run.
+har_ios_has_project() {
+  local dir="$1"
+
+  if [ -n "${HARNESS_XCODE_WORKSPACE:-}" ] || [ -n "${HARNESS_XCODE_PROJECT:-}" ]; then
+    if [ -n "${HARNESS_XCODE_WORKSPACE:-}" ] && [ -e "$dir/$HARNESS_XCODE_WORKSPACE" ]; then
+      return 0
+    fi
+    if [ -n "${HARNESS_XCODE_PROJECT:-}" ] && [ -e "$dir/$HARNESS_XCODE_PROJECT" ]; then
+      return 0
+    fi
+    return 1
+  fi
+
+  if har_ios_find_project_file "$dir" '*.xcworkspace' >/dev/null; then return 0; fi
+  if har_ios_find_project_file "$dir" '*.xcodeproj' >/dev/null; then return 0; fi
+  return 1
+}
+
+# Generator this repo declares, or empty. A Podfile counts: `pod install` is what
+# writes the .xcworkspace for a CocoaPods project.
+har_ios_project_generator() {
+  local dir="$1"
+  if [ -f "$dir/Project.swift" ] || [ -f "$dir/Workspace.swift" ]; then echo tuist; return; fi
+  if [ -f "$dir/project.yml" ] || [ -f "$dir/project.yaml" ]; then echo xcodegen; return; fi
+  if [ -f "$dir/Podfile" ]; then echo pod; return; fi
+  echo ""
+}
+
+har_ios_generate_project() {
+  local dir="$1"
+  local generator=""
+
+  if har_ios_has_project "$dir"; then
+    return 0
+  fi
+
+  generator="$(har_ios_project_generator "$dir")"
+  if [ -z "$generator" ]; then
+    pt_log "No .xcodeproj/.xcworkspace found and no generator manifest (Project.swift, project.yml, Podfile) — set HARNESS_XCODE_PROJECT/HARNESS_XCODE_WORKSPACE or HARNESS_INSTALL_CMD in harness.env"
+    return 0
+  fi
+
+  if ! command -v "$generator" >/dev/null 2>&1; then
+    local label="$generator"
+    [ "$generator" = "pod" ] && label="CocoaPods (pod)"
+    pt_log "ERROR: this repo generates its Xcode project with ${label}, which is not on PATH."
+    pt_log "       Install ${label}, or set HARNESS_INSTALL_CMD in harness.env to provision the project another way."
+    return 1
+  fi
+
+  case "$generator" in
+    tuist)
+      pt_log "Generating the Xcode project with tuist..."
+      if ! (cd "$dir" && tuist generate --no-open); then
+        pt_log "tuist generate --no-open failed — retrying without the flag"
+        (cd "$dir" && tuist generate)
+      fi
+      ;;
+    xcodegen)
+      pt_log "Generating the Xcode project with xcodegen..."
+      (cd "$dir" && xcodegen generate)
+      ;;
+    pod)
+      # har_ios_pod_install writes the workspace right after this.
+      :
+      ;;
+  esac
+}
+
+# CocoaPods dependencies. Independent of project generation: a tracked
+# .xcworkspace still cannot build when Pods/ is missing in a fresh worktree.
+har_ios_pod_install() {
+  local dir="$1"
+
+  [ -f "$dir/Podfile" ] || return 0
+  [ -d "$dir/Pods" ] && return 0
+
+  if ! command -v pod >/dev/null 2>&1; then
+    pt_log "ERROR: this repo uses CocoaPods (Podfile, no Pods/) and pod is not on PATH."
+    pt_log "       Install CocoaPods, or set HARNESS_INSTALL_CMD in harness.env to provision the project another way."
+    return 1
+  fi
+
+  pt_log "Installing CocoaPods dependencies..."
+  (cd "$dir" && pod install)
+}
+
 provision_ios() {
   local dir="$1"
-  run_install_cmd "$dir" || true
+
+  # An explicit HARNESS_INSTALL_CMD owns provisioning outright: the default
+  # generators stay out of the way, and a failing override fails the launch
+  # rather than being papered over.
+  if [ -n "${HARNESS_INSTALL_CMD:-}" ]; then
+    run_install_cmd "$dir"
+  else
+    har_ios_generate_project "$dir"
+    har_ios_pod_install "$dir"
+  fi
+
   append_env "HARNESS_ECOSYSTEM" "ios"
   append_env "XCODEBUILD_BIN" "$(command -v xcodebuild 2>/dev/null || echo xcodebuild)"
   if [ -n "${HARNESS_XCODE_SCHEME:-}" ]; then