@osfactory/har 0.56.1 → 0.58.0

package/dist/templates/profiles/cli/profile.manifest.json

@@ -0,0 +1,8 @@
+{
+  "id": "cli",
+  "description": "CLI/library — shared kernel + CLI overlay (no PM2)",
+  "bundles": [
+    { "id": "shared-kernel", "path": "runtime-bundles/shared-kernel" },
+    { "id": "runtime-cli", "path": "har-boilerplate-cli" }
+  ]
+}

package/dist/templates/profiles/default/profile.manifest.json

@@ -0,0 +1,9 @@
+{
+  "id": "default",
+  "description": "Web app — shared kernel + PM2 runtime + Docker infra",
+  "bundles": [
+    { "id": "shared-kernel", "path": "runtime-bundles/shared-kernel" },
+    { "id": "pm2-runtime", "path": "runtime-bundles/pm2-runtime" },
+    { "id": "runtime-default", "path": "har-boilerplate" }
+  ]
+}

package/dist/templates/profiles/ios/profile.manifest.json

@@ -0,0 +1,9 @@
+{
+  "id": "ios",
+  "description": "iOS — shared kernel + Xcode/Simulator overlay",
+  "bundles": [
+    { "id": "shared-kernel", "path": "runtime-bundles/shared-kernel" },
+    { "id": "xcode-sim", "path": "runtime-bundles/xcode-sim" },
+    { "id": "runtime-ios", "path": "har-boilerplate-ios" }
+  ]
+}

package/dist/templates/runtime-bundles/pm2-runtime/README.md

@@ -0,0 +1,4 @@
+# pm2-runtime
+
+Runtime bundle for web/SaaS profiles: PM2 ecosystem template, env.template, and attach.sh.
+Presence of `ecosystem.agent.template.cjs` is the capability marker (`harnessUsesPm2`).

package/dist/templates/runtime-bundles/pm2-runtime/attach.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Attach to the tmux session for an agent.
+#
+# Usage: ./.har/attach.sh <agent-id>
+set -euo pipefail
+
+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"
+
+AGENT_ID="${1:?Usage: attach.sh <agent-id>}"
+SESSION="$(har_tmux_session "$AGENT_ID")"
+
+if ! tmux has-session -t "$SESSION" 2>/dev/null; then
+  echo "No tmux session found: $SESSION" >&2
+  echo "Launch with: ./.har/launch.sh ${AGENT_ID} --claude" >&2
+  exit 1
+fi
+
+exec tmux attach -t "$SESSION"

package/dist/templates/runtime-bundles/pm2-runtime/ecosystem.agent.template.cjs

@@ -0,0 +1,46 @@
+/**
+ * PM2 Ecosystem Configuration for Agent ${AGENT_ID}
+ *
+ * Auto-generated by launch.sh — do not edit manually.
+ * Customize ecosystem.agent.template.cjs in .har/ to change processes.
+ */
+
+// launch.sh writes this file (and .env.agent.N) to the work dir root,
+// so __dirname IS the work dir — repo root or the agent's git worktree.
+const path = require('path');
+const dotenv = require('dotenv');
+
+const agentEnvPath = path.resolve(__dirname, '.env.agent.${AGENT_ID}');
+const env = dotenv.config({ path: agentEnvPath }).parsed || {};
+
+module.exports = {
+  apps: [
+    // TODO: Replace with the PRIMARY application's dev processes — the ONE app
+    // agents modify (HARNESS_PRIMARY_APP in harness.env). In a monolith or
+    // monorepo with several services, do NOT start them all here: supporting
+    // services the agent depends on but does not change run ONCE for all slots,
+    // either as compose services in docker-compose.agent.yml or via an optional
+    // .har/ecosystem.shared.config.cjs (started by setup-infra.sh, processes
+    // named "har-shared-<name>", fixed ports). A primary app may still need two
+    // processes (e.g. api + frontend) — add one entry per process.
+    // Example Node dev process. Replace with this repo's actual primary app
+    // command (Rails, Django, Go, Java, etc. should not keep this npm entry).
+    {
+      name: 'har-${HARNESS_PROJECT_NAME}-agent-${AGENT_ID}-api',
+      script: 'npm',
+      args: 'run dev',
+      interpreter: 'none',
+      cwd: __dirname,
+      env: {
+        ...env,
+        NODE_ENV: 'development',
+        PORT: env.API_PORT || env.PORT,
+      },
+      watch: false,
+      autorestart: true,
+      kill_timeout: 5000,
+      merge_logs: true,
+      time: true,
+    },
+  ],
+};

package/dist/templates/runtime-bundles/pm2-runtime/env.template

@@ -0,0 +1,40 @@
+# Agent environment — generated by launch.sh from env.template
+# DO NOT EDIT — regenerated on every launch
+AGENT_ID=${AGENT_ID}
+
+# Ports (allocated at launch — may differ from BASE + AGENT_ID × STEP when busy)
+PORT=${API_PORT}
+FE_PORT=${FE_PORT}
+API_PORT=${API_PORT}
+DEBUG_PORT=${DEBUG_PORT}
+
+# PostgreSQL
+PGHOST=localhost
+PGPORT=${DB_PORT}
+PGDATABASE=agent_${AGENT_ID}
+PGUSER=postgres
+PGPASSWORD=password
+DATABASE_URL=postgresql://postgres:password@localhost:${DB_PORT}/agent_${AGENT_ID}
+
+# Application
+NODE_ENV=development
+SITE_URL=http://localhost:${API_PORT}
+CORS_ORIGIN=http://localhost:${FE_PORT}
+
+# MinIO / S3 (if enabled)
+S3_ENDPOINT=http://localhost:${MINIO_PORT}
+S3_ACCESS_KEY=minioadmin
+S3_SECRET_KEY=minioadmin
+S3_BUCKET=agent-${AGENT_ID}
+S3_REGION=us-east-1
+S3_FORCE_PATH_STYLE=true
+
+# Headless browser (if enabled)
+HEADLESS_BROWSER_URL=http://localhost:${BROWSER_PORT}
+
+# Toolchain paths — appended by provision-toolchain.sh during launch
+# NODE_BIN=  NPM_BIN=  PYTHON_BIN=  VIRTUAL_ENV=  GO_BIN=  CARGO_BIN=  JAVA_HOME=
+
+# Mail (if enabled)
+SMTP_HOST=localhost
+SMTP_PORT=11025

package/dist/templates/runtime-bundles/shared-kernel/README.md

@@ -0,0 +1,3 @@
+# shared-kernel
+
+Runtime bundle shared by every HAR profile: toolchain provisioning and the stages authoring guide.

package/dist/templates/runtime-bundles/shared-kernel/STAGES.md

@@ -0,0 +1,99 @@
+# HAR Stages — authoring guide
+
+Stages are the harness's single vocabulary for runnable checks and lifecycle
+actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`, `gitleaks`, `trivy`, `semgrep`), your
+project's test/lint commands, bespoke validation scripts — registers in
+`.har/stages.json` with the same schema, and agents interact with stages only
+through that registry (CLI `har env verify`, MCP `har_run_stage` /
+`har_run_verification`), never through stack-specific tooling.
+
+Philosophy: *plugins install stages; agents only talk to the stage registry.*
+
+## The registry: `.har/stages.json`
+
+```jsonc
+{
+  "verificationStages": ["typecheck", "unit-tests", "api-health", "browser-e2e"],
+  "stages": [
+    {
+      "id": "browser-e2e",              // stable, shell-friendly slug
+      "kind": "test",                   // setup | launch | verify | test | inspect | reset | teardown | custom
+      "description": "Playwright E2E",
+      "script": "stages/browser-e2e.sh", // relative to .har/ — OR use "command"
+      "requiresAgentId": true,           // default true for test/verify/custom kinds
+      "artifacts": [{ "path": ".har/artifacts/browser-e2e", "kind": "directory" }]
+    },
+    {
+      "id": "unit-tests-fast",
+      "kind": "test",
+      "command": "npm test -- --agent {agentId}"   // {agentId} is substituted at run time
+    }
+  ]
+}
+```
+
+Optional stage fields: `cwd` (working directory), `env` (extra env vars),
+`group`, `acceptsArgs` (extra CLI args the stage accepts, e.g. `["--full"]`).
+
+## Two ways to define a stage
+
+**Command stages** — the default for simple checks (`npm test`, `swiftlint`,
+`make check`). One JSON entry, zero files:
+
+```bash
+har env add-stage unit-tests-fast --custom --kind test --command "npm test" --verification
+```
+
+**Script stages** — for anything that needs the slot's env, ports, or
+artifacts. Scaffold a contract-compliant skeleton:
+
+```bash
+har env add-stage db-integrity --custom --script --description "Check DB invariants"
+```
+
+then implement the TODO block in `.har/stages/db-integrity.sh`.
+
+## The stage script contract
+
+Every script under `.har/stages/` must:
+
+1. Source `harness.env` and `agent-slot.sh` from `.har/`. Before sourcing,
+   set `SCRIPT_DIR` to the `.har/` directory (not `stages/`) — `agent-slot.sh`
+   resolves the slot registry via `$SCRIPT_DIR/slots/...`.
+2. Take the agent slot id as `$1` (validate with `validate_agent_id`); extra
+   args may follow.
+3. Load the slot env via `resolve_agent_env_file` and run checks from the
+   agent's work dir (`resolve_agent_work_dir`).
+4. Write artifacts (reports, screenshots, logs) under `.har/artifacts/<id>/`.
+5. Print **only** the normalized JSON result object on stdout
+   (`status`, `stageId`, `agent_id`, `total_ms`, …); log progress to stderr.
+6. Exit with the real status code (0 = pass).
+
+The scaffolded skeleton implements all of this — replace its TODO block.
+
+## Verification membership
+
+Listing a stage id in `verificationStages` is what includes it in
+`har env verify <id> --full`. Ids that match a registered stage run via their
+script/command; ids without a registry entry (e.g. `typecheck`, `api-health`)
+are inline steps owned by `.har/verify.sh`. Lifecycle kinds
+(`setup`/`launch`/`reset`/`teardown`/`inspect`) and `verify` itself never run
+as part of verification, even if listed.
+
+## Commit gate
+
+The registry also holds the optional `commitGate` config (installed via
+`har hooks install`): `{ "commitGate": { "mode": "block" | "warn", "scope":
+"worktrees" | "all" } }` controls whether unverified change batches may be
+committed.
+
+## Shipped plugins
+
+`har env add-plugin --list` shows available plugins; `har env add-plugin
+playwright` (web), `har env add-plugin rocketsim` (iOS), or `har env
+add-plugin kerno` (backend), `har env add-plugin gitleaks` (secrets scanning, any
+stack), or `har env add-plugin trivy` (dependency + IaC security scan, any stack),
+or `har env add-plugin semgrep` (SAST, any stack)
+installs one. A
+plugin is just packaging: it copies files, merges `package.json` fragments,
+and registers stages through the exact same registry as `add-stage --custom`.

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

@@ -0,0 +1,407 @@
+#!/usr/bin/env bash
+# Provision the project toolchain and append resolved paths to .env.agent.<id>.
+# Called from launch.sh after the agent env file is created.
+#
+# Configure in harness.env:
+#   HARNESS_ECOSYSTEM   — auto (default) | node | python | go | rust | java | ruby | ios | none
+#   HARNESS_INSTALL_CMD — optional override (eval in HAR_WORK_DIR)
+# Ecosystem-specific optional overrides:
+#   HARNESS_PYTHON_VENV_DIR — Python venv path relative to HAR_WORK_DIR (default: .har/venv)
+#
+# Required env from caller: HAR_WORK_DIR, HAR_ENV_FILE
+# Optional: HAR_WORKTREE_DIR, HAR_REL_PREFIX, HAR_AGENT_ID (for logging)
+set -euo pipefail
+
+: "${HAR_WORK_DIR:?HAR_WORK_DIR is required}"
+: "${HAR_ENV_FILE:?HAR_ENV_FILE is required}"
+
+HAR_WORKTREE_DIR="${HAR_WORKTREE_DIR:-}"
+HAR_REL_PREFIX="${HAR_REL_PREFIX:-}"
+HAR_AGENT_ID="${HAR_AGENT_ID:-}"
+
+pt_log() {
+  if [ -n "$HAR_AGENT_ID" ]; then
+    echo "==> [agent-${HAR_AGENT_ID}] toolchain: $*" >&2
+  else
+    echo "==> [provision-toolchain] $*" >&2
+  fi
+}
+
+# ── Node package manager helpers ──────────────────────────────────────────────
+# Mirrored verbatim in harness.env and provision-toolchain.sh so a sourcing
+# script and the provisioning subprocess resolve the same tool.
+
+# Package managers HAR can drive, in fallback preference order.
+HAR_NODE_PACKAGE_MANAGERS="npm bun pnpm yarn"
+
+# Package manager the repo declares: an explicit HARNESS_NODE_PACKAGE_MANAGER
+# wins, then package.json "packageManager", then the lockfile. Empty when the
+# repo says nothing.
+har_node_declared_package_manager() {
+  local dir="${1:-.}"
+
+  if [ -n "${HARNESS_NODE_PACKAGE_MANAGER:-}" ]; then
+    echo "$HARNESS_NODE_PACKAGE_MANAGER"
+    return
+  fi
+  if [ -f "$dir/package.json" ]; then
+    local field
+    field="$(sed -n 's/.*"packageManager"[[:space:]]*:[[:space:]]*"\([a-z]*\)@.*/\1/p' "$dir/package.json" | head -1)"
+    if [ -n "$field" ]; then
+      echo "$field"
+      return
+    fi
+  fi
+  if [ -f "$dir/bun.lock" ] || [ -f "$dir/bun.lockb" ]; then echo bun; return; fi
+  if [ -f "$dir/pnpm-lock.yaml" ]; then echo pnpm; return; fi
+  if [ -f "$dir/yarn.lock" ]; then echo yarn; return; fi
+  if [ -f "$dir/package-lock.json" ]; then echo npm; return; fi
+  echo ""
+}
+
+# Package manager to actually run. A manager the repo declares but this machine
+# lacks falls back to one that is installed, so a repo pinned to npm still
+# provisions on a bun-only machine (and the reverse).
+har_node_package_manager() {
+  local dir="${1:-.}"
+  local declared
+  declared="$(har_node_declared_package_manager "$dir")"
+
+  if [ -n "$declared" ] && command -v "$declared" >/dev/null 2>&1; then
+    echo "$declared"
+    return
+  fi
+
+  local candidate
+  for candidate in $HAR_NODE_PACKAGE_MANAGERS; do
+    if command -v "$candidate" >/dev/null 2>&1; then
+      echo "$candidate"
+      return
+    fi
+  done
+
+  echo "${declared:-npm}"
+}
+
+# Lockfile a manager writes, so a substitute install can clean up after itself.
+har_node_lockfile() {
+  case "$1" in
+    bun) echo "bun.lock" ;;
+    npm) echo "package-lock.json" ;;
+    pnpm) echo "pnpm-lock.yaml" ;;
+    yarn) echo "yarn.lock" ;;
+    *) echo "" ;;
+  esac
+}
+
+# Install dependencies in a directory. When a substitute manager stands in for
+# the one the repo declares, any lockfile it creates is removed afterwards:
+# provisioning must not migrate the repo to a different package manager.
+# (bun writes bun.lock even under --no-save, so the flags alone are not enough.)
+har_node_install() {
+  local dir="$1"
+  local manager="$2"
+  local declared="${3:-}"
+  local substituting=false
+  local lockfile=""
+  local had_lockfile=false
+
+  if [ -n "$declared" ] && [ "$declared" != "$manager" ]; then
+    substituting=true
+    lockfile="$(har_node_lockfile "$manager")"
+    if [ -n "$lockfile" ] && [ -e "$dir/$lockfile" ]; then
+      had_lockfile=true
+    fi
+  fi
+
+  local code=0
+  (cd "$dir" && "$manager" install --silent) || code=$?
+
+  if [ "$substituting" = true ] && [ "$had_lockfile" = false ] && [ -n "$lockfile" ]; then
+    rm -f "$dir/$lockfile"
+    [ "$manager" = "bun" ] && rm -f "$dir/bun.lockb"
+  fi
+  return $code
+}
+
+# Package runner (npx equivalent) for one-off CLIs such as pm2, including the
+# flag that keeps it non-interactive. Takes a manager name, or none to resolve
+# from the environment and PATH.
+har_pkg_exec() {
+  case "${1:-${HARNESS_NODE_PACKAGE_MANAGER:-}}" in
+    bun) echo "bunx"; return ;;
+    pnpm) echo "pnpm dlx"; return ;;
+    yarn) echo "yarn dlx"; return ;;
+    npm) echo "npx --yes"; return ;;
+  esac
+  if command -v npx >/dev/null 2>&1; then echo "npx --yes"; return; fi
+  if command -v bunx >/dev/null 2>&1; then echo "bunx"; return; fi
+  if command -v pnpm >/dev/null 2>&1; then echo "pnpm dlx"; return; fi
+  echo "npx --yes"
+}
+
+append_env() {
+  local key="$1"
+  local value="$2"
+  # %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() {
+  local prefix="$1"
+  [ -n "$prefix" ] && [ -d "$prefix" ] || return 0
+  append_env "PATH" "${prefix}:${PATH:-$PATH}"
+}
+
+detect_ecosystem() {
+  local dir="$1"
+  local configured="${HARNESS_ECOSYSTEM:-auto}"
+  if [ -n "$configured" ] && [ "$configured" != "auto" ]; then
+    echo "$configured"
+    return
+  fi
+  if [ -f "$dir/package.json" ]; then echo node; return; fi
+  if [ -f "$dir/pyproject.toml" ] || [ -f "$dir/setup.py" ] || [ -f "$dir/setup.cfg" ] \
+    || [ -f "$dir/requirements.txt" ] || [ -f "$dir/Pipfile" ]; then
+    echo python
+    return
+  fi
+  if [ -f "$dir/go.mod" ]; then echo go; return; fi
+  if [ -f "$dir/Cargo.toml" ]; then echo rust; return; fi
+  if [ -f "$dir/pom.xml" ] || [ -f "$dir/build.gradle" ] || [ -f "$dir/build.gradle.kts" ]; then
+    echo java
+    return
+  fi
+  if [ -f "$dir/Gemfile" ]; then echo ruby; return; fi
+  if [ -n "${HARNESS_XCODE_SCHEME:-}" ] || [ -n "${HARNESS_XCODE_PROJECT:-}" ] \
+    || [ -n "${HARNESS_XCODE_WORKSPACE:-}" ]; then
+    echo ios
+    return
+  fi
+  echo none
+}
+
+run_install_cmd() {
+  local dir="$1"
+  if [ -n "${HARNESS_INSTALL_CMD:-}" ]; then
+    pt_log "Running HARNESS_INSTALL_CMD..."
+    (cd "$dir" && eval "$HARNESS_INSTALL_CMD")
+    return
+  fi
+  return 1
+}
+
+provision_node() {
+  local dir="$1"
+  local node_bin="node"
+  local pkg_manager declared_manager
+  declared_manager="$(har_node_declared_package_manager "$dir")"
+  pkg_manager="$(har_node_package_manager "$dir")"
+
+  if [ -n "$declared_manager" ] && [ "$declared_manager" != "$pkg_manager" ]; then
+    pt_log "Repo declares ${declared_manager}, which is not on PATH — installing with ${pkg_manager} and leaving the lockfile untouched."
+  fi
+
+  if ! run_install_cmd "$dir"; then
+    pt_log "Installing Node dependencies with ${pkg_manager}..."
+    har_node_install "$dir" "$pkg_manager" "$declared_manager"
+  fi
+
+  if command -v node >/dev/null 2>&1; then
+    node_bin="$(command -v node)"
+  elif [ "$pkg_manager" = "bun" ]; then
+    # bun-only machine: bun runs the `node -e` snippets verify.sh relies on.
+    node_bin="$(command -v bun)"
+  fi
+
+  local npm_bin="$pkg_manager"
+  if command -v "$pkg_manager" >/dev/null 2>&1; then
+    npm_bin="$(command -v "$pkg_manager")"
+  fi
+
+  append_env "HARNESS_ECOSYSTEM" "node"
+  append_env "NODE_BIN" "$node_bin"
+  append_env "NPM_BIN" "$npm_bin"
+  append_env "HARNESS_NODE_PACKAGE_MANAGER" "$pkg_manager"
+  append_env "HARNESS_PKG_EXEC" "$(har_pkg_exec "$pkg_manager")"
+  append_path_prefix "$dir/node_modules/.bin"
+}
+
+provision_python() {
+  local dir="$1"
+  local venv_rel="${HARNESS_PYTHON_VENV_DIR:-.har/venv}"
+  local venv_dir="$dir/$venv_rel"
+  local python_bin="python3"
+
+  if ! command -v python3 >/dev/null 2>&1; then
+    pt_log "python3 not found on PATH — skipping venv provisioning"
+    append_env "HARNESS_ECOSYSTEM" "python"
+    append_env "PYTHON_BIN" "${PYTHON_BIN:-python3}"
+    return
+  fi
+
+  if [ ! -d "$venv_dir" ]; then
+    pt_log "Creating Python venv at $venv_rel..."
+    if ! python3 -m venv "$venv_dir"; then
+      rm -rf "$venv_dir"
+      pt_log "python3 -m venv failed (on Debian/Ubuntu install python3-venv) — using system python3"
+      append_env "HARNESS_ECOSYSTEM" "python"
+      append_env "PYTHON_BIN" "$(command -v python3)"
+      return
+    fi
+  fi
+
+  if [ ! -x "$venv_dir/bin/python" ]; then
+    pt_log "Python venv at $venv_rel is missing or broken — using system python3"
+    append_env "HARNESS_ECOSYSTEM" "python"
+    append_env "PYTHON_BIN" "$(command -v python3)"
+    return
+  fi
+
+  python_bin="$venv_dir/bin/python"
+  # shellcheck disable=SC1091
+  source "$venv_dir/bin/activate"
+
+  if ! run_install_cmd "$dir"; then
+    pt_log "Installing Python dependencies..."
+    if [ -f "$dir/pyproject.toml" ]; then
+      (cd "$dir" && pip install -q -e ".[dev]" 2>/dev/null) || (cd "$dir" && pip install -q -e .)
+    elif [ -f "$dir/requirements.txt" ]; then
+      (cd "$dir" && pip install -q -r requirements.txt)
+    elif [ -f "$dir/setup.py" ] || [ -f "$dir/setup.cfg" ]; then
+      (cd "$dir" && pip install -q -e .)
+    elif [ -f "$dir/Pipfile" ] && command -v pipenv >/dev/null 2>&1; then
+      (cd "$dir" && pipenv install --dev)
+      python_bin="$(cd "$dir" && pipenv --py)"
+    fi
+  fi
+
+  append_env "HARNESS_ECOSYSTEM" "python"
+  append_env "PYTHON_BIN" "$python_bin"
+  append_env "VIRTUAL_ENV" "$venv_dir"
+  append_path_prefix "$venv_dir/bin"
+}
+
+provision_go() {
+  local dir="$1"
+  if ! run_install_cmd "$dir"; then
+    if command -v go >/dev/null 2>&1; then
+      pt_log "Downloading Go modules..."
+      (cd "$dir" && go mod download)
+    else
+      pt_log "go not found on PATH — record paths only"
+    fi
+  fi
+  append_env "HARNESS_ECOSYSTEM" "go"
+  append_env "GO_BIN" "$(command -v go 2>/dev/null || echo go)"
+  if [ -n "${GOPATH:-}" ]; then append_env "GOPATH" "$GOPATH"; fi
+  if [ -n "${GOROOT:-}" ]; then append_env "GOROOT" "$GOROOT"; fi
+}
+
+provision_rust() {
+  local dir="$1"
+  if ! run_install_cmd "$dir"; then
+    if command -v cargo >/dev/null 2>&1; then
+      pt_log "Fetching Rust dependencies..."
+      (cd "$dir" && cargo fetch)
+    else
+      pt_log "cargo not found on PATH — record paths only"
+    fi
+  fi
+  append_env "HARNESS_ECOSYSTEM" "rust"
+  append_env "CARGO_BIN" "$(command -v cargo 2>/dev/null || echo cargo)"
+  append_env "RUSTC_BIN" "$(command -v rustc 2>/dev/null || echo rustc)"
+}
+
+provision_java() {
+  local dir="$1"
+  run_install_cmd "$dir" || true
+  append_env "HARNESS_ECOSYSTEM" "java"
+  if [ -n "${JAVA_HOME:-}" ]; then
+    append_env "JAVA_HOME" "$JAVA_HOME"
+    append_path_prefix "$JAVA_HOME/bin"
+  fi
+  if command -v mvn >/dev/null 2>&1; then
+    append_env "MVN_BIN" "$(command -v mvn)"
+  elif [ -f "$dir/gradlew" ]; then
+    append_env "GRADLE_BIN" "$dir/gradlew"
+  elif command -v gradle >/dev/null 2>&1; then
+    append_env "GRADLE_BIN" "$(command -v gradle)"
+  fi
+}
+
+provision_ruby() {
+  local dir="$1"
+  if ! run_install_cmd "$dir"; then
+    if command -v bundle >/dev/null 2>&1; then
+      pt_log "Installing Ruby gems..."
+      (cd "$dir" && bundle install --quiet)
+    else
+      pt_log "bundle not found on PATH — record paths only"
+    fi
+  fi
+  append_env "HARNESS_ECOSYSTEM" "ruby"
+  append_env "RUBY_BIN" "$(command -v ruby 2>/dev/null || echo ruby)"
+  append_env "BUNDLE_BIN" "$(command -v bundle 2>/dev/null || echo bundle)"
+  append_path_prefix "$dir/vendor/bundle/bin"
+}
+
+provision_ios() {
+  local dir="$1"
+  run_install_cmd "$dir" || true
+  append_env "HARNESS_ECOSYSTEM" "ios"
+  append_env "XCODEBUILD_BIN" "$(command -v xcodebuild 2>/dev/null || echo xcodebuild)"
+  if [ -n "${HARNESS_XCODE_SCHEME:-}" ]; then
+    append_env "HARNESS_XCODE_SCHEME" "$HARNESS_XCODE_SCHEME"
+  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
+  if [ -n "${DEVELOPER_DIR:-}" ]; then
+    append_env "DEVELOPER_DIR" "$DEVELOPER_DIR"
+  fi
+}
+
+provision_monorepo_root() {
+  [ -n "$HAR_REL_PREFIX" ] || return 0
+  [ -n "$HAR_WORKTREE_DIR" ] || return 0
+  [ -f "$HAR_WORKTREE_DIR/package.json" ] || return 0
+  [ -d "$HAR_WORKTREE_DIR/node_modules" ] && return 0
+  local pkg_manager
+  pkg_manager="$(har_node_package_manager "$HAR_WORKTREE_DIR")"
+  pt_log "Installing monorepo root dependencies in $HAR_WORKTREE_DIR with ${pkg_manager}..."
+  har_node_install "$HAR_WORKTREE_DIR" "$pkg_manager" \
+    "$(har_node_declared_package_manager "$HAR_WORKTREE_DIR")"
+}
+
+provision_ecosystem() {
+  local dir="$1"
+  local ecosystem
+  ecosystem="$(detect_ecosystem "$dir")"
+  pt_log "Toolchain ecosystem: ${ecosystem} (work dir: ${dir})"
+
+  case "$ecosystem" in
+    node) provision_node "$dir" ;;
+    python) provision_python "$dir" ;;
+    go) provision_go "$dir" ;;
+    rust) provision_rust "$dir" ;;
+    java) provision_java "$dir" ;;
+    ruby) provision_ruby "$dir" ;;
+    ios) provision_ios "$dir" ;;
+    none)
+      if run_install_cmd "$dir"; then
+        append_env "HARNESS_ECOSYSTEM" "custom"
+      else
+        pt_log "No ecosystem manifest detected — set HARNESS_ECOSYSTEM or HARNESS_INSTALL_CMD in harness.env"
+        append_env "HARNESS_ECOSYSTEM" "none"
+      fi
+      ;;
+  esac
+}
+
+append_env "HARNESS_TOOLCHAIN_PROVISIONED" "true"
+provision_ecosystem "$HAR_WORK_DIR"
+provision_monorepo_root

package/dist/templates/runtime-bundles/shared-kernel/stages/README.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Per-stage scripts live here (e.g. ./.har/stages/browser-e2e.sh <agent-id>).
+#
+# Read .har/STAGES.md for the authoring guide: the stage script contract,
+# command vs script stages, and how verificationStages controls verify --full.
+#
+# Scaffold a new one with:
+#   har env add-stage <id> --custom --script
+
+echo "Add stage scripts under .har/stages/ and register them in stages.json — see .har/STAGES.md." >&2
+exit 1

package/dist/templates/runtime-bundles/xcode-sim/README.md

@@ -0,0 +1,4 @@
+# xcode-sim
+
+Runtime bundle for iOS profiles: Simulator helpers (`simulator.sh`).
+Presence of this file is the capability marker (`harnessUsesSimulator`).