@osfactory/har 0.6.0 → 0.7.0

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

@@ -26,6 +26,337 @@ validate_agent_id() {
   fi
 }
 
+# ── Port allocation ─────────────────────────────────────────────────────────────
+# Try the configured default first; scan the slot lane or infra range when busy.
+
+port_in_use() {
+  local port="$1"
+  (exec 3<>"/dev/tcp/127.0.0.1/$port") 2>/dev/null && { exec 3>&- || true; return 0; }
+  return 1
+}
+
+har_port_step() {
+  echo "${HARNESS_PORT_STEP:-10}"
+}
+
+har_default_app_port() {
+  local base="$1"
+  local agent_id="$2"
+  echo $(( base + agent_id * $(har_port_step) ))
+}
+
+har_slot_port_lane_end() {
+  local default_port="$1"
+  echo $(( default_port + $(har_port_step) - 1 ))
+}
+
+# har_pick_free_port <start> <end> — echoes the first free port in [start, end].
+har_pick_free_port() {
+  local start="$1"
+  local end="$2"
+  local port
+  for ((port=start; port<=end; port++)); do
+    if ! port_in_use "$port"; then
+      echo "$port"
+      return 0
+    fi
+  done
+  echo "Error: no free port in range ${start}-${end}" >&2
+  return 1
+}
+
+# har_allocate_port <default> <scan_start> <scan_end>
+har_allocate_port() {
+  local default_port="$1"
+  local scan_start="$2"
+  local scan_end="$3"
+  if ! port_in_use "$default_port"; then
+    echo "$default_port"
+    return 0
+  fi
+  har_pick_free_port "$scan_start" "$scan_end"
+}
+
+# Allocate FE/API/DEBUG ports for a slot. Sets FE_PORT, API_PORT, DEBUG_PORT.
+har_allocate_slot_app_ports() {
+  local agent_id="$1"
+  local step fe_default api_default debug_default
+  step="$(har_port_step)"
+  fe_default="$(har_default_app_port "${HARNESS_FE_BASE_PORT}" "$agent_id")"
+  api_default="$(har_default_app_port "${HARNESS_API_BASE_PORT}" "$agent_id")"
+  debug_default=$(( 9200 + agent_id * step ))
+
+  FE_PORT="$(har_allocate_port "$fe_default" "$fe_default" "$(har_slot_port_lane_end "$fe_default")")"
+  API_PORT="$(har_allocate_port "$api_default" "$api_default" "$(har_slot_port_lane_end "$api_default")")"
+  DEBUG_PORT="$(har_allocate_port "$debug_default" "$debug_default" $(( debug_default + step - 1 )) )"
+  export FE_PORT API_PORT DEBUG_PORT
+}
+
+# ── Launch preflight (#36) ─────────────────────────────────────────────────────
+
+har_harness_uses_pm2() {
+  [ -f "${SCRIPT_DIR}/ecosystem.agent.template.cjs" ]
+}
+
+har_port_docker_occupant() {
+  local port="$1"
+  docker ps --format '{{.Names}}\t{{.Ports}}' 2>/dev/null \
+    | grep -E ":${port}->|:${port}/" | head -1 | cut -f1 || true
+}
+
+har_check_control_port_conflict() {
+  local port="$1"
+  local name
+  name="$(docker ps --format '{{.Names}}\t{{.Ports}}' 2>/dev/null \
+    | grep -i control | grep -E ":${port}->|:${port}/" | head -1 | cut -f1 || true)"
+  if [ -n "$name" ]; then
+    echo "ERROR: Mission Control container \"${name}\" occupies port ${port}." >&2
+    echo "  Run: har control down — or use a different agent slot." >&2
+    return 1
+  fi
+  return 0
+}
+
+har_check_foreign_pm2() {
+  local agent_id="$1"
+  local pm2_raw
+  har_harness_uses_pm2 || return 0
+  pm2_raw="$(npx --yes pm2 jlist 2>/dev/null || true)"
+  [ -n "$pm2_raw" ] || return 0
+  set +e
+  echo "$pm2_raw" | node -e "
+const agentId = process.argv[1];
+const project = process.argv[2];
+const slotPrefix = 'har-' + project + '-agent-' + agentId + '-';
+const legacyPrefix = 'agent-' + agentId + '-';
+let raw = '';
+process.stdin.on('data', c => raw += c);
+process.stdin.on('end', () => {
+  try {
+    const arr = JSON.parse(raw);
+    if (!Array.isArray(arr)) process.exit(0);
+    const foreign = arr.filter(x =>
+      x.name && (
+        (x.name.startsWith('har-') && x.name.includes('-agent-' + agentId + '-') && !x.name.startsWith(slotPrefix)) ||
+        (x.name.startsWith(legacyPrefix) && !x.name.startsWith('har-'))
+      ));
+    if (foreign.length === 0) process.exit(0);
+    console.error('ERROR: foreign PM2 processes match agent ' + agentId + ':');
+    foreign.forEach(p => {
+      const cwd = p.pm2_env?.pm_cwd || p.pm2_env?.cwd || 'unknown';
+      console.error('  ' + p.name + '  cwd=' + cwd);
+    });
+    console.error('  Stop the other harness session or use a different slot.');
+    process.exit(1);
+  } catch {
+    process.exit(0);
+  }
+});
+" "$agent_id" "$HARNESS_PROJECT_NAME"
+  local rc=$?
+  set -e
+  return "$rc"
+}
+
+# ── Resume failed launch (#38) ───────────────────────────────────────────────
+
+slot_session_status() {
+  local agent_id="$1"
+  read_slot_field "$(slot_registry_file "$agent_id")" status || true
+}
+
+slot_is_resumable() {
+  local agent_id="$1"
+  local status
+  status="$(slot_session_status "$agent_id")"
+  [ "$status" = "failed" ] || [ "$status" = "starting" ]
+}
+
+har_resume_session_assignments() {
+  local agent_id="$1"
+  local reg work_dir worktree branch suffix base_branch base_commit purpose mode env_file
+
+  if ! slot_is_resumable "$agent_id"; then
+    local status
+    status="$(slot_session_status "$agent_id")"
+    echo "echo \"ERROR: slot ${agent_id} is not resumable (status=${status:-none}; need failed or starting).\" >&2" >&2
+    echo "echo \"  Use a normal launch, or --replace to start a fresh session.\" >&2"
+    echo 'exit 2'
+    return 1
+  fi
+
+  reg="$(slot_registry_file "$agent_id")"
+  work_dir="$(read_slot_field "$reg" workDir || true)"
+  worktree="$(read_slot_field "$reg" worktreePath || true)"
+  branch="$(read_slot_field "$reg" branch || true)"
+  suffix="$(read_slot_field "$reg" suffix || true)"
+  base_branch="$(read_slot_field "$reg" baseBranch || true)"
+  base_commit="$(read_slot_field "$reg" baseCommit || true)"
+  purpose="$(read_slot_field "$reg" purpose || true)"
+  mode="$(read_slot_field "$reg" mode || true)"
+
+  if [ -z "$work_dir" ] || [ ! -d "$work_dir" ]; then
+    echo "echo \"ERROR: resume requires work dir from registry (missing or not found).\" >&2"
+    echo 'exit 1'
+    return 1
+  fi
+
+  env_file="$work_dir/.env.agent.${agent_id}"
+  if [ ! -f "$env_file" ]; then
+    echo "echo \"ERROR: resume requires env file: ${env_file}\" >&2"
+    echo 'exit 1'
+    return 1
+  fi
+
+  printf '%s\n' \
+    "WORK_DIR='${work_dir}'" \
+    "WORKTREE_DIR='${worktree}'" \
+    "BRANCH='${branch}'" \
+    "SUFFIX='${suffix}'" \
+    "BASE_BRANCH='${base_branch}'" \
+    "BASE_COMMIT='${base_commit}'" \
+    "PURPOSE='${purpose}'" \
+    "USE_WORKTREE=$([ "$mode" = worktree ] && echo true || echo false)" \
+    "ENV_FILE='${env_file}'"
+}
+
+har_toolchain_ready() {
+  local work_dir="$1"
+  if [ -f "$work_dir/package.json" ] && [ -d "$work_dir/node_modules" ]; then
+    return 0
+  fi
+  if [ -d "$work_dir/.har/venv" ]; then
+    return 0
+  fi
+  return 1
+}
+
+har_regenerate_agent_env_file() {
+  local agent_id="$1"
+  local work_dir="$2"
+  local env_file="$3"
+  local worktree_dir="${4:-}"
+  local template="${SCRIPT_DIR}/env.template"
+  if [ -f "$template" ]; then
+    AGENT_ID="$agent_id" \
+    API_PORT="${API_PORT:-}" \
+    FE_PORT="${FE_PORT:-}" \
+    DEBUG_PORT="${DEBUG_PORT:-}" \
+    DB_PORT="${DB_PORT:-${AGENT_DB_PORT:-${HARNESS_DB_PORT_DEFAULT:-15432}}}" \
+    MINIO_PORT="${MINIO_PORT:-${AGENT_MINIO_PORT:-${HARNESS_MINIO_PORT_DEFAULT:-19000}}}" \
+    BROWSER_PORT="${BROWSER_PORT:-${AGENT_BROWSER_PORT:-${HARNESS_BROWSER_PORT_DEFAULT:-13001}}}" \
+    REPO_ROOT="$work_dir" \
+      envsubst '${AGENT_ID} ${API_PORT} ${FE_PORT} ${DEBUG_PORT} ${DB_PORT} ${MINIO_PORT} ${BROWSER_PORT} ${REPO_ROOT}' \
+      < "$template" > "$env_file"
+    return 0
+  fi
+  cat > "$env_file" <<EOF
+# Agent environment — generated by launch.sh
+AGENT_ID=${agent_id}
+REPO_ROOT=${work_dir}
+WORKTREE_DIR=${worktree_dir}
+NODE_ENV=test
+EOF
+}
+
+har_launch_preflight() {
+  local agent_id="$1"
+  local force="${2:-false}"
+  local replace="${3:-false}"
+  local resume="${4:-false}"
+
+  if [ "$resume" = true ]; then
+    if ! slot_is_resumable "$agent_id"; then
+      local status
+      status="$(slot_session_status "$agent_id")"
+      echo "ERROR: slot ${agent_id} is not resumable (status=${status:-none}; need failed or starting)." >&2
+      echo "  Use a normal launch, or --replace to start a fresh session." >&2
+      return 2
+    fi
+    echo "==> [agent-${agent_id}] Resuming partial launch (worktree and deps preserved)..." >&2
+  elif slot_is_occupied "$agent_id"; then
+    if [ "$replace" != true ] && [ "${HAR_CONFIRM_REPLACE:-}" != "1" ]; then
+      print_slot_replace_warning "$agent_id"
+      echo "ERROR: slot ${agent_id} is occupied — pass --replace to proceed." >&2
+      return 2
+    fi
+    local wt
+    wt="$(existing_slot_worktree "$agent_id")"
+    if [ -n "$wt" ] && slot_worktree_dirty "$wt" && [ "$force" != true ]; then
+      echo "ERROR: dirty worktree requires --force after explicit user approval." >&2
+      return 2
+    fi
+  fi
+
+  if har_harness_uses_pm2; then
+    har_check_foreign_pm2 "$agent_id" || return 1
+    har_allocate_slot_app_ports "$agent_id" || return 1
+    local port occupant
+    for port in $(printf '%s\n' "$FE_PORT" "$API_PORT" | sort -u); do
+      har_check_control_port_conflict "$port" || return 1
+      occupant="$(har_port_docker_occupant "$port")"
+      if [ -n "$occupant" ] && [[ "$occupant" != har-${HARNESS_PROJECT_NAME}-* ]]; then
+        echo "ERROR: Docker container \"${occupant}\" binds port ${port}." >&2
+        echo "  Stop it with: docker stop ${occupant}" >&2
+        return 1
+      fi
+    done
+  fi
+  return 0
+}
+
+# Load persisted app/infra ports from .env.agent.<id> or the slot registry.
+load_agent_ports() {
+  local agent_id="$1"
+  local repo_root="$2"
+  local env_file reg ports_json
+  env_file="$(resolve_agent_env_file "$agent_id" "$repo_root" 2>/dev/null || true)"
+  if [ -n "$env_file" ] && [ -f "$env_file" ]; then
+    # shellcheck source=/dev/null
+    source "$env_file"
+    FE_PORT="${FE_PORT:-}"
+    API_PORT="${API_PORT:-${PORT:-}}"
+    DEBUG_PORT="${DEBUG_PORT:-}"
+    DB_PORT="${PGPORT:-${DB_PORT:-}}"
+    return 0
+  fi
+  reg="$(slot_registry_file "$agent_id")"
+  if [ -f "$reg" ]; then
+    ports_json="$(node -e '
+try {
+  const p = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).ports;
+  if (p) process.stdout.write(JSON.stringify(p));
+} catch {}
+' "$reg" 2>/dev/null || true)"
+    if [ -n "$ports_json" ]; then
+      FE_PORT="$(node -e "const p=JSON.parse(process.argv[1]);process.stdout.write(String(p.frontend??''))" "$ports_json")"
+      API_PORT="$(node -e "const p=JSON.parse(process.argv[1]);process.stdout.write(String(p.api??''))" "$ports_json")"
+      DEBUG_PORT="$(node -e "const p=JSON.parse(process.argv[1]);process.stdout.write(String(p.debug??''))" "$ports_json")"
+      DB_PORT="$(node -e "const p=JSON.parse(process.argv[1]);process.stdout.write(String(p.db??''))" "$ports_json")"
+      export FE_PORT API_PORT DEBUG_PORT DB_PORT
+      return 0
+    fi
+  fi
+  har_allocate_slot_app_ports "$agent_id"
+  DB_PORT="${AGENT_DB_PORT:-${HARNESS_DB_PORT_DEFAULT:-15432}}"
+  export FE_PORT API_PORT DEBUG_PORT DB_PORT
+}
+
+# ── Project-scoped PM2 names ────────────────────────────────────────────────────
+# Pattern: har-<project>-agent-<id>-<service> (machine-global PM2 namespace).
+
+har_pm2_slot_prefix() {
+  echo "har-${HARNESS_PROJECT_NAME}-agent-${1}"
+}
+
+har_pm2_delete_regex() {
+  echo "/^har-${HARNESS_PROJECT_NAME}-agent-${1}-/"
+}
+
+har_tmux_session() {
+  echo "har-${HARNESS_PROJECT_NAME}-agent-${1}"
+}
+
 # ── Slot registry ─────────────────────────────────────────────────────────────
 # .har/slots/agent-<id>.json is the source of truth for where a session lives
 # (worktree path, work dir, branch, base commit). Written by launch.sh, removed

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

@@ -4,10 +4,17 @@
 export HARNESS_PROJECT_NAME=__PROJECT_NAME__
 export HARNESS_USE_WORKTREE=true
 
+# Optional per-slot HTTP ports for integration tests (unused when no local server).
 export HARNESS_FE_BASE_PORT=3000
 export HARNESS_API_BASE_PORT=8000
+export HARNESS_PORT_STEP=10
 export HARNESS_HEALTH_CHECK_PATH=
 
+# Shared infra host ports — setup-infra.sh tries DEFAULT first, scans when busy.
+export HARNESS_DB_PORT_DEFAULT=15432
+export HARNESS_DB_PORT_SCAN_START=15432
+export HARNESS_DB_PORT_SCAN_END=15499
+
 export HARNESS_AGENT_SLOT_MIN=1
 export HARNESS_AGENT_SLOT_MAX=3
 

package/dist/templates/har-boilerplate-cli/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] [--replace] [--force]
+# Usage: ./.har/launch.sh <agent-id> [--no-worktree] [--replace] [--force] [--resume]
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -18,6 +18,7 @@ AGENT_ID="${1:-}"
 USE_WORKTREE="${HARNESS_USE_WORKTREE:-true}"
 FORCE=false
 REPLACE=false
+RESUME=false
 PURPOSE="${HAR_SESSION_PURPOSE:-}"
 
 for arg in "$@"; do
@@ -26,12 +27,13 @@ for arg in "$@"; do
     --worktree) USE_WORKTREE=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] [--replace] [--force] [--purpose=label]" >&2
+  echo "Usage: $0 <agent-id> [--no-worktree] [--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
@@ -40,110 +42,158 @@ validate_agent_id "$AGENT_ID"
 
 log() { echo "==> [agent-$AGENT_ID] $*" >&2; }
 
-# 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
-
-"$SCRIPT_DIR/setup-infra.sh"
-
-# 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%/}"
+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_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
-  log "Using repo root (worktree disabled)"
-fi
+  har_launch_preflight "$AGENT_ID" "$FORCE" "$REPLACE" || exit $?
 
-# 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
+  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
 
-ENV_FILE="$WORK_DIR/.env.agent.${AGENT_ID}"
-log "Generating $ENV_FILE..."
-cat > "$ENV_FILE" <<EOF
-# Agent environment — generated by launch.sh
-AGENT_ID=${AGENT_ID}
-REPO_ROOT=${WORK_DIR}
-WORKTREE_DIR=${WORKTREE_DIR}
-NODE_ENV=test
-EOF
+"$SCRIPT_DIR/setup-infra.sh"
 
-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_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."
+if [ "$RESUME" != true ]; then
+  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
-}
-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_STATUS="starting" \
-  write_slot_registry
-REGISTRY_WRITTEN=true
-
-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"
-
-# Record the session in the slot registry — the source of truth for where
-# this slot's code lives (status/verify/teardown resolve through it).
+  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..."
+  har_regenerate_agent_env_file "$AGENT_ID" "$WORK_DIR" "$ENV_FILE" "${WORKTREE_DIR:-}"
+
+  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_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
+
+  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_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" "${WORKTREE_DIR:-}"
+  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_STATUS="starting" \
+    write_slot_registry
+fi
+
+if [ "$RESUME" = true ] && har_toolchain_ready "$WORK_DIR"; then
+  log "Toolchain already provisioned — skipping install."
+elif [ -f "$SCRIPT_DIR/provision-toolchain.sh" ]; then
+  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"
+elif [ -f "$WORK_DIR/package.json" ] && [ ! -d "$WORK_DIR/node_modules" ]; then
+  log "Installing dependencies in $WORK_DIR..."
+  (cd "$WORK_DIR" && npm install --silent)
+fi
+
 SLOT_AGENT_ID="$AGENT_ID" \
 SLOT_MODE="$([ "$USE_WORKTREE" = true ] && echo worktree || echo root)" \
 SLOT_WORK_DIR="$WORK_DIR" \