@osfactory/har 0.6.0 → 0.8.0

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

@@ -3,7 +3,7 @@
 # Every launch starts a FRESH session: any previous session for the slot is torn
 # down (its branch is kept) and a new suffixed worktree is created from HEAD.
 #
-# Usage: ./.har/launch.sh <agent-id> [--no-worktree] [--claude] [--replace] [--force]
+# Usage: ./.har/launch.sh <agent-id> [--no-worktree] [--claude] [--replace] [--force] [--resume]
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -19,6 +19,7 @@ USE_WORKTREE="${HARNESS_USE_WORKTREE:-true}"
 USE_CLAUDE=false
 FORCE=false
 REPLACE=false
+RESUME=false
 PURPOSE="${HAR_SESSION_PURPOSE:-}"
 
 for arg in "$@"; do
@@ -28,12 +29,13 @@ for arg in "$@"; do
     --claude)   USE_CLAUDE=true ;;
     --replace)  REPLACE=true ;;
     --force)    FORCE=true ;;
+    --resume)   RESUME=true ;;
     --purpose=*) PURPOSE="${arg#--purpose=}" ;;
   esac
 done
 
 if [[ -z "$AGENT_ID" ]]; then
-  echo "Usage: $0 <agent-id> [--no-worktree] [--claude] [--replace] [--force] [--purpose=label]" >&2
+  echo "Usage: $0 <agent-id> [--no-worktree] [--claude] [--replace] [--force] [--resume] [--purpose=label]" >&2
   echo "  agent-id must be between ${HARNESS_AGENT_SLOT_MIN} and ${HARNESS_AGENT_SLOT_MAX}" >&2
   exit 1
 fi
@@ -42,24 +44,65 @@ validate_agent_id "$AGENT_ID"
 
 log() { echo "==> [agent-$AGENT_ID] $*" >&2; }
 
-FE_PORT=$(( HARNESS_FE_BASE_PORT + AGENT_ID * 10 ))
-API_PORT=$(( HARNESS_API_BASE_PORT + AGENT_ID * 10 ))
-DEBUG_PORT=$(( 9200 + AGENT_ID * 10 ))
-DB_PORT="${AGENT_DB_PORT:-15432}"
-MINIO_PORT="${AGENT_MINIO_PORT:-19000}"
-BROWSER_PORT="${AGENT_BROWSER_PORT:-13001}"
+WORK_DIR="$REPO_ROOT"
+WORKTREE_DIR=""
+BRANCH=""
+SUFFIX=""
+BASE_BRANCH=""
+BASE_COMMIT=""
+ENV_FILE=""
+REGISTRY_WRITTEN=false
+
+if [ "$RESUME" = true ]; then
+  har_launch_preflight "$AGENT_ID" "$FORCE" "$REPLACE" true || exit $?
+  eval "$(har_resume_session_assignments "$AGENT_ID")"
+  REGISTRY_WRITTEN=true
+  mark_slot_failed() {
+    local exit_code="$?"
+    if [ "$exit_code" != "0" ] && [ "$REGISTRY_WRITTEN" = true ]; then
+      log "Resume failed. Recording failed slot state..."
+      set +e
+      SLOT_AGENT_ID="$AGENT_ID" \
+      SLOT_MODE="$([ "$USE_WORKTREE" = true ] && echo worktree || echo root)" \
+      SLOT_WORK_DIR="$WORK_DIR" \
+      SLOT_SUFFIX="${SUFFIX:-}" \
+      SLOT_WORKTREE_PATH="${WORKTREE_DIR:-}" \
+      SLOT_BRANCH="${BRANCH:-}" \
+      SLOT_BASE_BRANCH="${BASE_BRANCH:-}" \
+      SLOT_BASE_COMMIT="${BASE_COMMIT:-}" \
+      SLOT_PURPOSE="${PURPOSE}" \
+      SLOT_PORTS_JSON="{\"frontend\":${FE_PORT},\"api\":${API_PORT},\"debug\":${DEBUG_PORT},\"db\":${DB_PORT}}" \
+      SLOT_PREVIEW_URLS_JSON="{\"frontend\":\"http://localhost:${FE_PORT}\",\"api\":\"http://localhost:${API_PORT}\"}" \
+      SLOT_STATUS="failed" \
+      SLOT_LAST_ERROR="launch.sh --resume exited with code ${exit_code}" \
+        write_slot_registry
+      log "  Work dir:  ${WORK_DIR}"
+      log "  Env file:  ${ENV_FILE}"
+      log "  Recovery:  ./.har/launch.sh ${AGENT_ID} --resume"
+    fi
+  }
+  trap mark_slot_failed EXIT
+else
+  # Preflight before worktree/install — ports, foreign PM2, Docker, occupied slot.
+  har_launch_preflight "$AGENT_ID" "$FORCE" "$REPLACE" || exit $?
 
-log "Ports: frontend=$FE_PORT api=$API_PORT debug=$DEBUG_PORT"
+  # Replace any previous session for this slot — requires explicit confirmation.
+  if slot_is_occupied "$AGENT_ID"; then
+    require_slot_replace_confirm "$AGENT_ID" "$FORCE" "$REPLACE"
+    log "Replacing previous session for slot ${AGENT_ID}..."
+    "$SCRIPT_DIR/teardown.sh" "$AGENT_ID" >&2
+  fi
+fi
 
-# Replace any previous session for this slot — requires explicit confirmation.
-if slot_is_occupied "$AGENT_ID"; then
-  require_slot_replace_confirm "$AGENT_ID" "$FORCE" "$REPLACE"
-  log "Replacing previous session for slot ${AGENT_ID}..."
-  "$SCRIPT_DIR/teardown.sh" "$AGENT_ID" >&2
+if har_harness_uses_pm2; then
+  log "Ports: frontend=$FE_PORT api=$API_PORT debug=$DEBUG_PORT"
 fi
 
-# Ensure shared infra is running
+# Ensure shared infra is running (persists host ports in .har/state/infra.env).
 "$SCRIPT_DIR/setup-infra.sh"
+DB_PORT="${AGENT_DB_PORT:-${HARNESS_DB_PORT_DEFAULT:-15432}}"
+MINIO_PORT="${AGENT_MINIO_PORT:-${HARNESS_MINIO_PORT_DEFAULT:-19000}}"
+BROWSER_PORT="${AGENT_BROWSER_PORT:-${HARNESS_BROWSER_PORT_DEFAULT:-13001}}"
 
 # Clone agent database from template
 if har_infra_enabled db && [ -n "${HARNESS_TEMPLATE_DB:-}" ]; then
@@ -85,105 +128,113 @@ if har_infra_enabled minio; then
 fi
 
 # Session worktree (default — use --no-worktree to work in repo root).
-# Name encodes what the session is based on: <base-branch>-<sha4>-har-agent-<id>-<rand4>.
-WORK_DIR="$REPO_ROOT"
-WORKTREE_DIR=""
-BRANCH=""
-SUFFIX=""
-BASE_BRANCH="$(git -C "$REPO_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "detached")"
-BASE_COMMIT="$(git -C "$REPO_ROOT" rev-parse HEAD 2>/dev/null || true)"
-if [ "$USE_WORKTREE" = true ]; then
-  SHORT_SHA="$(git -C "$REPO_ROOT" rev-parse --short=4 HEAD)"
-  SUFFIX="$(LC_ALL=C tr -dc 'a-z0-9' </dev/urandom 2>/dev/null | head -c 4 || true)"
-  [ -n "$SUFFIX" ] || SUFFIX="$(printf '%04d' $(( RANDOM % 10000 )))"
-  SESSION_NAME="${BASE_BRANCH//\//-}-${SHORT_SHA}-har-agent-${AGENT_ID}-${SUFFIX}"
-  BRANCH="$SESSION_NAME"
-  WORKTREE_DIR="$HOME/worktrees/${SESSION_NAME}"
-  log "Creating session worktree at $WORKTREE_DIR (branch $BRANCH)..."
-  git -C "$REPO_ROOT" worktree add "$WORKTREE_DIR" -b "$BRANCH"
-  # Worktrees are always rooted at the git repo — if this project lives in a
-  # subdirectory (monorepo), point WORK_DIR at the project inside the worktree.
-  REL_PREFIX="$(git -C "$REPO_ROOT" rev-parse --show-prefix 2>/dev/null || true)"
-  WORK_DIR="${WORKTREE_DIR%/}/${REL_PREFIX}"
-  WORK_DIR="${WORK_DIR%/}"
-else
-  log "Using repo root (worktree disabled)"
-fi
+if [ "$RESUME" != true ]; then
+  # Name encodes what the session is based on: <base-branch>-<sha4>-har-agent-<id>-<rand4>.
+  WORK_DIR="$REPO_ROOT"
+  WORKTREE_DIR=""
+  BRANCH=""
+  SUFFIX=""
+  BASE_BRANCH="$(git -C "$REPO_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "detached")"
+  BASE_COMMIT="$(git -C "$REPO_ROOT" rev-parse HEAD 2>/dev/null || true)"
+  if [ "$USE_WORKTREE" = true ]; then
+    SHORT_SHA="$(git -C "$REPO_ROOT" rev-parse --short=4 HEAD)"
+    SUFFIX="$(LC_ALL=C tr -dc 'a-z0-9' </dev/urandom 2>/dev/null | head -c 4 || true)"
+    [ -n "$SUFFIX" ] || SUFFIX="$(printf '%04d' $(( RANDOM % 10000 )))"
+    SESSION_NAME="${BASE_BRANCH//\//-}-${SHORT_SHA}-har-agent-${AGENT_ID}-${SUFFIX}"
+    BRANCH="$SESSION_NAME"
+    WORKTREE_DIR="$HOME/worktrees/${SESSION_NAME}"
+    log "Creating session worktree at $WORKTREE_DIR (branch $BRANCH)..."
+    git -C "$REPO_ROOT" worktree add "$WORKTREE_DIR" -b "$BRANCH"
+    REL_PREFIX="$(git -C "$REPO_ROOT" rev-parse --show-prefix 2>/dev/null || true)"
+    WORK_DIR="${WORKTREE_DIR%/}/${REL_PREFIX}"
+    WORK_DIR="${WORK_DIR%/}"
+  else
+    log "Using repo root (worktree disabled)"
+    REL_PREFIX="$(git -C "$REPO_ROOT" rev-parse --show-prefix 2>/dev/null || true)"
+  fi
 
-# Generate .env.agent.N
-# Keep harness-generated files out of accidental `git add -A` commits in repos
-# 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
-    grep -qxF "$pattern" "$GIT_EXCLUDE" 2>/dev/null || echo "$pattern" >> "$GIT_EXCLUDE"
-  done
-fi
+  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
+      grep -qxF "$pattern" "$GIT_EXCLUDE" 2>/dev/null || echo "$pattern" >> "$GIT_EXCLUDE"
+    done
+  fi
 
-ENV_FILE="$WORK_DIR/.env.agent.${AGENT_ID}"
-log "Generating $ENV_FILE..."
-AGENT_ID="$AGENT_ID" \
-API_PORT="$API_PORT" \
-FE_PORT="$FE_PORT" \
-DEBUG_PORT="$DEBUG_PORT" \
-DB_PORT="$DB_PORT" \
-MINIO_PORT="$MINIO_PORT" \
-BROWSER_PORT="$BROWSER_PORT" \
-REPO_ROOT="$WORK_DIR" \
-  envsubst '${AGENT_ID} ${API_PORT} ${FE_PORT} ${DEBUG_PORT} ${DB_PORT} ${MINIO_PORT} ${BROWSER_PORT} ${REPO_ROOT}' \
-  < "$SCRIPT_DIR/env.template" > "$ENV_FILE"
+  ENV_FILE="$WORK_DIR/.env.agent.${AGENT_ID}"
+  log "Generating $ENV_FILE..."
+  har_regenerate_agent_env_file "$AGENT_ID" "$WORK_DIR" "$ENV_FILE"
 
-REGISTRY_WRITTEN=false
-mark_slot_failed() {
-  local exit_code="$?"
-  if [ "$exit_code" != "0" ] && [ "$REGISTRY_WRITTEN" = true ]; then
-    log "Launch failed after creating the session. Recording failed slot state..."
-    set +e
-    SLOT_AGENT_ID="$AGENT_ID" \
-    SLOT_MODE="$([ "$USE_WORKTREE" = true ] && echo worktree || echo root)" \
-    SLOT_WORK_DIR="$WORK_DIR" \
-    SLOT_SUFFIX="${SUFFIX:-}" \
-    SLOT_WORKTREE_PATH="${WORKTREE_DIR:-}" \
-    SLOT_BRANCH="${BRANCH:-}" \
-    SLOT_BASE_BRANCH="${BASE_BRANCH:-}" \
-    SLOT_BASE_COMMIT="${BASE_COMMIT:-}" \
-    SLOT_PURPOSE="${PURPOSE}" \
-    SLOT_PORTS_JSON="{\"frontend\":${FE_PORT},\"api\":${API_PORT},\"debug\":${DEBUG_PORT}}" \
-    SLOT_PREVIEW_URLS_JSON="{\"frontend\":\"http://localhost:${FE_PORT}\",\"api\":\"http://localhost:${API_PORT}\"}" \
-    SLOT_STATUS="failed" \
-    SLOT_LAST_ERROR="launch.sh exited with code ${exit_code}" \
-      write_slot_registry
-    log "  Work dir:  ${WORK_DIR}"
-    log "  Env file:  ${ENV_FILE}"
-    log "  Recovery:  fix the failure, then relaunch with --replace when ready."
-  fi
-}
-trap mark_slot_failed EXIT
+  REGISTRY_WRITTEN=false
+  mark_slot_failed() {
+    local exit_code="$?"
+    if [ "$exit_code" != "0" ] && [ "$REGISTRY_WRITTEN" = true ]; then
+      log "Launch failed after creating the session. Recording failed slot state..."
+      set +e
+      SLOT_AGENT_ID="$AGENT_ID" \
+      SLOT_MODE="$([ "$USE_WORKTREE" = true ] && echo worktree || echo root)" \
+      SLOT_WORK_DIR="$WORK_DIR" \
+      SLOT_SUFFIX="${SUFFIX:-}" \
+      SLOT_WORKTREE_PATH="${WORKTREE_DIR:-}" \
+      SLOT_BRANCH="${BRANCH:-}" \
+      SLOT_BASE_BRANCH="${BASE_BRANCH:-}" \
+      SLOT_BASE_COMMIT="${BASE_COMMIT:-}" \
+      SLOT_PURPOSE="${PURPOSE}" \
+      SLOT_PORTS_JSON="{\"frontend\":${FE_PORT},\"api\":${API_PORT},\"debug\":${DEBUG_PORT},\"db\":${DB_PORT}}" \
+      SLOT_PREVIEW_URLS_JSON="{\"frontend\":\"http://localhost:${FE_PORT}\",\"api\":\"http://localhost:${API_PORT}\"}" \
+      SLOT_STATUS="failed" \
+      SLOT_LAST_ERROR="launch.sh exited with code ${exit_code}" \
+        write_slot_registry
+      log "  Work dir:  ${WORK_DIR}"
+      log "  Env file:  ${ENV_FILE}"
+      log "  Recovery:  ./.har/launch.sh ${AGENT_ID} --resume"
+    fi
+  }
+  trap mark_slot_failed EXIT
 
-# Record the session before slow or fragile setup so verify/status/teardown can
-# recover partial launches that already created a worktree and env file.
-SLOT_AGENT_ID="$AGENT_ID" \
-SLOT_MODE="$([ "$USE_WORKTREE" = true ] && echo worktree || echo root)" \
-SLOT_WORK_DIR="$WORK_DIR" \
-SLOT_SUFFIX="${SUFFIX:-}" \
-SLOT_WORKTREE_PATH="${WORKTREE_DIR:-}" \
-SLOT_BRANCH="${BRANCH:-}" \
-SLOT_BASE_BRANCH="${BASE_BRANCH:-}" \
-SLOT_BASE_COMMIT="${BASE_COMMIT:-}" \
-SLOT_PURPOSE="${PURPOSE}" \
-SLOT_PORTS_JSON="{\"frontend\":${FE_PORT},\"api\":${API_PORT},\"debug\":${DEBUG_PORT}}" \
-SLOT_PREVIEW_URLS_JSON="{\"frontend\":\"http://localhost:${FE_PORT}\",\"api\":\"http://localhost:${API_PORT}\"}" \
-SLOT_STATUS="starting" \
-  write_slot_registry
-REGISTRY_WRITTEN=true
+  SLOT_AGENT_ID="$AGENT_ID" \
+  SLOT_MODE="$([ "$USE_WORKTREE" = true ] && echo worktree || echo root)" \
+  SLOT_WORK_DIR="$WORK_DIR" \
+  SLOT_SUFFIX="${SUFFIX:-}" \
+  SLOT_WORKTREE_PATH="${WORKTREE_DIR:-}" \
+  SLOT_BRANCH="${BRANCH:-}" \
+  SLOT_BASE_BRANCH="${BASE_BRANCH:-}" \
+  SLOT_BASE_COMMIT="${BASE_COMMIT:-}" \
+  SLOT_PURPOSE="${PURPOSE}" \
+  SLOT_PORTS_JSON="{\"frontend\":${FE_PORT},\"api\":${API_PORT},\"debug\":${DEBUG_PORT},\"db\":${DB_PORT}}" \
+  SLOT_PREVIEW_URLS_JSON="{\"frontend\":\"http://localhost:${FE_PORT}\",\"api\":\"http://localhost:${API_PORT}\"}" \
+  SLOT_STATUS="starting" \
+    write_slot_registry
+  REGISTRY_WRITTEN=true
+else
+  REL_PREFIX="$(git -C "$REPO_ROOT" rev-parse --show-prefix 2>/dev/null || true)"
+  log "Resuming session at ${WORK_DIR}"
+  har_regenerate_agent_env_file "$AGENT_ID" "$WORK_DIR" "$ENV_FILE"
+  SLOT_AGENT_ID="$AGENT_ID" \
+  SLOT_MODE="$([ "$USE_WORKTREE" = true ] && echo worktree || echo root)" \
+  SLOT_WORK_DIR="$WORK_DIR" \
+  SLOT_SUFFIX="${SUFFIX:-}" \
+  SLOT_WORKTREE_PATH="${WORKTREE_DIR:-}" \
+  SLOT_BRANCH="${BRANCH:-}" \
+  SLOT_BASE_BRANCH="${BASE_BRANCH:-}" \
+  SLOT_BASE_COMMIT="${BASE_COMMIT:-}" \
+  SLOT_PURPOSE="${PURPOSE}" \
+  SLOT_PORTS_JSON="{\"frontend\":${FE_PORT},\"api\":${API_PORT},\"debug\":${DEBUG_PORT},\"db\":${DB_PORT}}" \
+  SLOT_PREVIEW_URLS_JSON="{\"frontend\":\"http://localhost:${FE_PORT}\",\"api\":\"http://localhost:${API_PORT}\"}" \
+  SLOT_STATUS="starting" \
+    write_slot_registry
+fi
 
-log "Provisioning toolchain (see harness.env: HARNESS_ECOSYSTEM, HARNESS_INSTALL_CMD)..."
-HAR_WORK_DIR="$WORK_DIR" \
-HAR_ENV_FILE="$ENV_FILE" \
-HAR_WORKTREE_DIR="${WORKTREE_DIR:-}" \
-HAR_REL_PREFIX="${REL_PREFIX:-}" \
-HAR_AGENT_ID="$AGENT_ID" \
-  "$SCRIPT_DIR/provision-toolchain.sh"
+if [ "$RESUME" = true ] && har_toolchain_ready "$WORK_DIR"; then
+  log "Toolchain already provisioned — skipping install."
+else
+  log "Provisioning toolchain (see harness.env: HARNESS_ECOSYSTEM, HARNESS_INSTALL_CMD)..."
+  HAR_WORK_DIR="$WORK_DIR" \
+  HAR_ENV_FILE="$ENV_FILE" \
+  HAR_WORKTREE_DIR="${WORKTREE_DIR:-}" \
+  HAR_REL_PREFIX="${REL_PREFIX:-}" \
+  HAR_AGENT_ID="$AGENT_ID" \
+    "$SCRIPT_DIR/provision-toolchain.sh"
+fi
 
 if [ -n "${HARNESS_DB_MINIMAL_BOOTSTRAP_CMD:-}" ]; then
   log "Running minimal data bootstrap..."
@@ -194,13 +245,15 @@ fi
 ECOSYSTEM_FILE="$WORK_DIR/ecosystem.agent.${AGENT_ID}.config.cjs"
 log "Generating $ECOSYSTEM_FILE..."
 AGENT_ID="$AGENT_ID" \
+HARNESS_PROJECT_NAME="$HARNESS_PROJECT_NAME" \
 FE_PORT="$FE_PORT" \
 DEBUG_PORT="$DEBUG_PORT" \
-  envsubst '${AGENT_ID} ${FE_PORT} ${DEBUG_PORT}' \
+  envsubst '${AGENT_ID} ${HARNESS_PROJECT_NAME} ${FE_PORT} ${DEBUG_PORT}' \
   < "$SCRIPT_DIR/ecosystem.agent.template.cjs" > "$ECOSYSTEM_FILE"
 
-# Stop existing processes for this agent
-npx --yes pm2 delete "/^agent-${AGENT_ID}-/" 2>/dev/null || true
+PM2_REGEX="$(har_pm2_delete_regex "$AGENT_ID")"
+# Stop existing processes for this agent (project-scoped — never touch other harnesses).
+npx --yes pm2 delete "$PM2_REGEX" 2>/dev/null || true
 
 # Start PM2 processes
 log "Starting PM2 processes..."
@@ -240,14 +293,14 @@ SLOT_BRANCH="${BRANCH:-}" \
 SLOT_BASE_BRANCH="${BASE_BRANCH:-}" \
 SLOT_BASE_COMMIT="${BASE_COMMIT:-}" \
 SLOT_PURPOSE="${PURPOSE}" \
-SLOT_PORTS_JSON="{\"frontend\":${FE_PORT},\"api\":${API_PORT},\"debug\":${DEBUG_PORT}}" \
+SLOT_PORTS_JSON="{\"frontend\":${FE_PORT},\"api\":${API_PORT},\"debug\":${DEBUG_PORT},\"db\":${DB_PORT}}" \
 SLOT_PREVIEW_URLS_JSON="{\"frontend\":\"http://localhost:${FE_PORT}\",\"api\":\"http://localhost:${API_PORT}\"}" \
 SLOT_STATUS="active" \
   write_slot_registry
 
 # Launch Claude Code in tmux (optional)
 if [ "$USE_CLAUDE" = true ]; then
-  TMUX_SESSION="agent-${AGENT_ID}"
+  TMUX_SESSION="$(har_tmux_session "$AGENT_ID")"
   if tmux has-session -t "$TMUX_SESSION" 2>/dev/null; then
     tmux kill-session -t "$TMUX_SESSION"
   fi

package/dist/templates/har-boilerplate/preflight.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Launch readiness gate — run before launch.sh or standalone.
+# Usage: ./.har/preflight.sh <agent-id> [--replace] [--force]
+# JSON:  har env preflight <id> --json
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/agent-slot.sh"
+
+AGENT_ID="${1:-}"
+FORCE=false
+REPLACE=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --replace) REPLACE=true ;;
+    --force)   FORCE=true ;;
+  esac
+done
+
+if [[ -z "$AGENT_ID" ]]; then
+  echo "Usage: $0 <agent-id> [--replace] [--force]" >&2
+  exit 1
+fi
+
+validate_agent_id "$AGENT_ID"
+
+if har_launch_preflight "$AGENT_ID" "$FORCE" "$REPLACE"; then
+  echo "Slot ${AGENT_ID}: ready to launch."
+  if har_harness_uses_pm2; then
+    echo "  Ports: frontend=${FE_PORT} api=${API_PORT} debug=${DEBUG_PORT}"
+  fi
+  exit 0
+fi
+
+exit $?

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

@@ -11,26 +11,101 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 COMPOSE_FILE="$SCRIPT_DIR/docker-compose.agent.yml"
+INFRA_STATE="$SCRIPT_DIR/state/infra.env"
 
 # shellcheck source=/dev/null
 source "$SCRIPT_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/agent-slot.sh"
 
 COMPOSE_PROJECT="har-${HARNESS_PROJECT_NAME}"
-DB_PORT="${AGENT_DB_PORT:-15432}"
 PSQL="har_pg psql -d postgres"
 
 log() { echo "==> $*" >&2; }
 
+har_compose_service_running() {
+  local service="$1"
+  docker ps --filter "name=${COMPOSE_PROJECT}-${service}-1" --format '{{.Names}}' 2>/dev/null \
+    | grep -q "^${COMPOSE_PROJECT}-${service}-1\$"
+}
+
+har_resolve_infra_port() {
+  local var_name="$1"
+  local default_port="$2"
+  local scan_start="$3"
+  local scan_end="$4"
+  local service="${5:-}"
+  local current="${!var_name:-}"
+
+  if [ -n "$current" ] && { ! port_in_use "$current" || { [ -n "$service" ] && har_compose_service_running "$service"; }; }; then
+    echo "$current"
+    return 0
+  fi
+  har_allocate_port "$default_port" "$scan_start" "$scan_end"
+}
+
+mkdir -p "$(dirname "$INFRA_STATE")"
+if [ -f "$INFRA_STATE" ]; then
+  # shellcheck source=/dev/null
+  source "$INFRA_STATE"
+fi
+
+DB_PORT="$(har_resolve_infra_port AGENT_DB_PORT \
+  "${HARNESS_DB_PORT_DEFAULT:-15432}" \
+  "${HARNESS_DB_PORT_SCAN_START:-15432}" \
+  "${HARNESS_DB_PORT_SCAN_END:-15499}" \
+  db)"
+MINIO_PORT="$(har_resolve_infra_port AGENT_MINIO_PORT \
+  "${HARNESS_MINIO_PORT_DEFAULT:-19000}" \
+  "${HARNESS_MINIO_PORT_SCAN_START:-19000}" \
+  "${HARNESS_MINIO_PORT_SCAN_END:-19099}" \
+  minio)"
+MINIO_CONSOLE_PORT="$(har_resolve_infra_port AGENT_MINIO_CONSOLE_PORT \
+  "${HARNESS_MINIO_CONSOLE_PORT_DEFAULT:-19001}" \
+  "${HARNESS_MINIO_CONSOLE_PORT_SCAN_START:-19001}" \
+  "${HARNESS_MINIO_CONSOLE_PORT_SCAN_END:-19099}")"
+BROWSER_PORT="$(har_resolve_infra_port AGENT_BROWSER_PORT \
+  "${HARNESS_BROWSER_PORT_DEFAULT:-13001}" \
+  "${HARNESS_BROWSER_PORT_SCAN_START:-13001}" \
+  "${HARNESS_BROWSER_PORT_SCAN_END:-13099}" \
+  headless-browser)"
+MAILPIT_WEB_PORT="$(har_resolve_infra_port AGENT_MAILPIT_WEB_PORT \
+  "${HARNESS_MAILPIT_WEB_PORT_DEFAULT:-18025}" \
+  "${HARNESS_MAILPIT_WEB_PORT_SCAN_START:-18025}" \
+  "${HARNESS_MAILPIT_WEB_PORT_SCAN_END:-18099}" \
+  mailpit)"
+MAILPIT_SMTP_PORT="$(har_resolve_infra_port AGENT_MAILPIT_SMTP_PORT \
+  "${HARNESS_MAILPIT_SMTP_PORT_DEFAULT:-11025}" \
+  "${HARNESS_MAILPIT_SMTP_PORT_SCAN_START:-11025}" \
+  "${HARNESS_MAILPIT_SMTP_PORT_SCAN_END:-11099}")"
+
+export AGENT_DB_PORT="$DB_PORT"
+export AGENT_MINIO_PORT="$MINIO_PORT"
+export AGENT_MINIO_CONSOLE_PORT="$MINIO_CONSOLE_PORT"
+export AGENT_BROWSER_PORT="$BROWSER_PORT"
+export AGENT_MAILPIT_WEB_PORT="$MAILPIT_WEB_PORT"
+export AGENT_MAILPIT_SMTP_PORT="$MAILPIT_SMTP_PORT"
+
+cat > "$INFRA_STATE" <<EOF
+# Persisted by setup-infra.sh — host ports for shared docker compose services.
+export AGENT_DB_PORT=${DB_PORT}
+export AGENT_MINIO_PORT=${MINIO_PORT}
+export AGENT_MINIO_CONSOLE_PORT=${MINIO_CONSOLE_PORT}
+export AGENT_BROWSER_PORT=${BROWSER_PORT}
+export AGENT_MAILPIT_WEB_PORT=${MAILPIT_WEB_PORT}
+export AGENT_MAILPIT_SMTP_PORT=${MAILPIT_SMTP_PORT}
+EOF
+
 SERVICES="${HARNESS_INFRA_SERVICES:-}"
 
 if [ -n "$SERVICES" ]; then
   log "Starting shared infrastructure (project: $COMPOSE_PROJECT): $SERVICES"
   AGENT_DB_PORT="$DB_PORT" \
-  AGENT_MINIO_PORT="${AGENT_MINIO_PORT:-19000}" \
-  AGENT_MINIO_CONSOLE_PORT="${AGENT_MINIO_CONSOLE_PORT:-19001}" \
-  AGENT_BROWSER_PORT="${AGENT_BROWSER_PORT:-13001}" \
-  AGENT_MAILPIT_WEB_PORT="${AGENT_MAILPIT_WEB_PORT:-18025}" \
-  AGENT_MAILPIT_SMTP_PORT="${AGENT_MAILPIT_SMTP_PORT:-11025}" \
+  AGENT_MINIO_PORT="$MINIO_PORT" \
+  AGENT_MINIO_CONSOLE_PORT="$MINIO_CONSOLE_PORT" \
+  AGENT_BROWSER_PORT="$BROWSER_PORT" \
+  AGENT_MAILPIT_WEB_PORT="$MAILPIT_WEB_PORT" \
+  AGENT_MAILPIT_SMTP_PORT="$MAILPIT_SMTP_PORT" \
     docker compose -p "$COMPOSE_PROJECT" -f "$COMPOSE_FILE" up -d $SERVICES
 else
   log "No shared infra services enabled in harness.env (HARNESS_INFRA_SERVICES)"
@@ -85,18 +160,19 @@ fi
 # Shared app services — supporting services of a monolith/monorepo that agents
 # depend on but do not modify. Started ONCE on fixed ports, shared by all slots.
 # Create .har/ecosystem.shared.config.cjs (PM2 format, processes named
-# "har-shared-<name>") only when the primary app needs sibling services running.
+# "har-${HARNESS_PROJECT_NAME}-shared-<name>") only when the primary app needs
+# sibling services running.
 SHARED_ECOSYSTEM="$SCRIPT_DIR/ecosystem.shared.config.cjs"
 if [ -f "$SHARED_ECOSYSTEM" ]; then
   log "Starting shared app services from ecosystem.shared.config.cjs..."
   (cd "$REPO_ROOT" && npx --yes pm2 startOrReload "$SHARED_ECOSYSTEM" >/dev/null)
-  log "Shared app services running (pm2 ls | grep har-shared-)."
+  log "Shared app services running (pm2 ls | grep har-${HARNESS_PROJECT_NAME}-shared-)."
 fi
 
 echo ""
 log "Infrastructure is ready."
 har_infra_enabled db               && log "  PostgreSQL: localhost:$DB_PORT"
-har_infra_enabled minio            && log "  MinIO:      http://localhost:${AGENT_MINIO_CONSOLE_PORT:-19001}"
-har_infra_enabled headless-browser && log "  Browser:    http://localhost:${AGENT_BROWSER_PORT:-13001}"
-har_infra_enabled mailpit          && log "  Mailpit:    http://localhost:${AGENT_MAILPIT_WEB_PORT:-18025}"
+har_infra_enabled minio            && log "  MinIO:      http://localhost:${MINIO_CONSOLE_PORT}"
+har_infra_enabled headless-browser && log "  Browser:    http://localhost:${BROWSER_PORT}"
+har_infra_enabled mailpit          && log "  Mailpit:    http://localhost:${MAILPIT_WEB_PORT}"
 exit 0

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

@@ -40,7 +40,8 @@ if [ -f "$REGISTRY_FILE" ]; then
 fi
 [ -n "$WORKTREE_PATH" ] || WORKTREE_PATH="$HOME/worktrees/${HARNESS_PROJECT_NAME}-agent-${AGENT_ID}"
 
-npx --yes pm2 delete "/^agent-${AGENT_ID}-/" 2>/dev/null || true
+PM2_REGEX="$(har_pm2_delete_regex "$AGENT_ID")"
+npx --yes pm2 delete "$PM2_REGEX" 2>/dev/null || true
 echo "✓ Stopped PM2 processes"
 
 if har_infra_enabled db; then

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

@@ -97,6 +97,32 @@ Work in the isolated git worktree created by launch. Use `./.har/agent-cli.sh <i
 
 When the project needs Postgres, Redis, or similar, add the service to `docker-compose.agent.yml` (or keep one from the menu), list it in `HARNESS_INFRA_SERVICES` in `harness.env`, and use `setup-infra.sh` — never run raw `docker compose` for shared infra. Shared services run once on fixed ports and serve every agent slot.
 
+## Port & shared services (CLI profile)
+
+This profile has **no PM2 app ports** — agents run project commands directly in their worktree. Port variables in `harness.env` exist for optional test servers and for shared Docker infra.
+
+### Port allocation
+
+| Layer | Scope | Rule | On conflict |
+|-------|-------|------|-------------|
+| Shared Postgres | Per machine | `HARNESS_DB_PORT_DEFAULT` | Scan `HARNESS_DB_PORT_SCAN_START..END` |
+| Other compose services | Per machine | `HARNESS_*_PORT_DEFAULT` for that service | Scan configured ranges in `harness.env` |
+
+When a repo adds a local HTTP server for integration tests, prefer reading ports from `.env.agent.<id>` or `./.har/agent-cli.sh <id>` rather than hardcoding values.
+
+### Shared vs per-slot
+
+| Resource | Model | Configuration |
+|----------|-------|---------------|
+| Postgres / Redis / mail / … | One shared container on a scanned host port | `HARNESS_INFRA_SERVICES` + matching vars in `harness.env` |
+| Per-slot databases | Cloned from template DB when `db` is enabled | `launch.sh` |
+| Application code | Isolated git worktree per slot | `HARNESS_USE_WORKTREE=true` |
+
+### Do not
+
+- Hardcode `15432` or other default infra ports in tests — read `AGENT_DB_PORT` from `.env.agent.<id>` or `har_pg`
+- Run raw `docker compose` for harness infrastructure — use `setup-infra.sh`
+
 ## Maintaining this harness
 
 When the project stack changes (new test commands, database needs, env vars):
@@ -122,6 +148,8 @@ work dir printed by launch, never in the main checkout.
   after explicit user approval.
 - `teardown` removes the worktree but **keeps the session branch** so you can push it
   or open a PR (`--delete-branch` to drop it).
+- If launch fails after creating a worktree/env file, resume with
+  `har env launch <id> --resume` or `har env recover <id>`.
 - `har env complete <id>` finishes a session: full verify (recorded as a validation),
   then teardown — branch kept.
 - `--no-worktree` runs the slot from the repo root instead (single-agent mode).