@osfactory/har 0.36.2 → 0.38.0

package/dist/templates/adaptation-prompt-init.md

@@ -153,7 +153,7 @@ Document and configure ports in `.har/harness.env` and `.har/README.md`. Use the
 | Mailpit | `HARNESS_MAILPIT_*_PORT_DEFAULT` | Scan configured ranges |
 | Headless browser | `HARNESS_BROWSER_PORT_DEFAULT` | Scan configured ranges |
 
-Set slot limits in `.har/stages.json` (`agentSlots`) based on machine capacity. `har env maintain --finalize` syncs legacy `HARNESS_AGENT_SLOT_*` exports in `harness.env`.
+Onboarding may set an initial `agentSlots.max` in `.har/stages.json`. After you know the real stack cost, **re-tune** that limit for machine capacity (lighter stack → you can raise; heavy Docker/DB → lower). `har env maintain --finalize` syncs legacy `HARNESS_AGENT_SLOT_*` exports in `harness.env`.
 
 **Port / infra checklist:**
 

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

@@ -11,7 +11,7 @@ har env status        # or ./.har/agent-cli.sh 1 status
 ```
 
 - One slot ≈ one task. If slot 1 is occupied by unrelated work, use slot 2+ (limit: `agentSlots` in `.har/stages.json`).
-- Never replace an occupied slot (`--replace`/`--force`) without the user explicitly approving it.
+- Occupied slots always block a new launch: run `har env teardown <id>` (or `complete <id>`) first, then launch again.
 
 ## 2. Launch — BEFORE editing any file
 
@@ -19,7 +19,7 @@ har env status        # or ./.har/agent-cli.sh 1 status
 har env launch <id>   # or ./.har/launch.sh <id>
 ```
 
-Launch creates a fresh session worktree from HEAD and prints its **work dir** (also recorded in `.har/slots/agent-<id>.json`, path like `~/worktrees/<base>-<sha4>-har-agent-<id>-<rand4>`). If a previous launch failed partway, retry with `--resume` instead of replacing.
+Launch creates a fresh session worktree from HEAD and prints its **work dir** (also recorded in `.har/slots/agent-<id>.json`, path like `~/worktrees/<base>-<sha4>-har-agent-<id>-<rand4>`). If a previous launch failed partway, retry with `--resume` instead of starting fresh.
 
 If the task already has a stable issue or ticket ID, bind it without changing the
 methodology that produced it:

package/dist/templates/cursor-rule.mdc.template

@@ -15,20 +15,19 @@ work around it with ad-hoc commands.
 
 ## Before making changes
 
-1. **On the main checkout, switch to the intended base** (usually `main`) — every launch creates a worktree from that HEAD. `--replace` does not select the base.
+1. **On the main checkout, switch to the intended base** (usually `main`) — every launch creates a worktree from that HEAD.
 2. **Launch your slot FIRST — before editing any file.** Use `har_launch_environment` with `agentId: 1` (MCP) or `har env launch 1`. Launch always creates a **fresh session worktree** and returns its **work dir**. If the task binds to a durable external work item (a GitHub issue, a Linear ticket, a task from the user's tracker), pass `workUnitId` + `title` on launch (`har_launch_environment` `workUnitId`/`title`, or CLI `--work-id`/`--work-title`) so Mission Control attributes usage and events to that work item instead of leaving them session-only.
 3. **Make ALL file edits under the returned work dir — never in the main checkout.** The work dir looks like `~/worktrees/<base-branch>-<sha4>-har-agent-<id>-<rand4>` (recorded in `.har/slots/agent-<id>.json`). Edits there hot-reload in the running slot; use `har env restart <id>` or `./.har/agent-cli.sh <id> restart` if a change doesn't take.
 4. Read [AGENT.md](./AGENT.md) at the repo root
 5. Read [.har/README.md](./.har/README.md) and [.har/stages.json](./.har/stages.json)
 6. After launch, read [.har/CLAUDE.agent.md](./.har/CLAUDE.agent.md) for slot URLs and definition of done
 
-When a slot is occupied: prefer `complete` / `teardown` if the previous task is finished, then launch. Use `--replace` / `confirmReplace=true` only to reuse the same slot id immediately (destroys the old worktree; the old branch is kept if committed). If the previous session has uncommitted changes, you must also pass `force`/`--force` after **explicit user approval** — never autonomously. Failed launches: `--resume` / `recover`, not `--replace`.
+When a slot is occupied: it always blocks a new launch. Run `complete` / `teardown` on that slot id first, then `launch` again. Occupied slots do not choose the base branch either way — switch the main checkout to your intended base before launching. Failed/starting launches can be resumed instead: `--resume` / `recover`.
 
 ### Slot safety (read before launch)
 
 - **One slot ≈ one task** — do not share slot 1 across unrelated chats; use slot 2+ for parallel work.
 - **Call `har_get_status` / `har env status`** before launch when a slot may be occupied.
-- **Never** set `force`/`confirmReplace` without the user explicitly approving replacement.
 - **Commit early and often** in the session worktree — teardown keeps the branch, not uncommitted work.
 - **Gitignored paths are ephemeral** (`state/`, `runs/`, local clones) — they are lost when the worktree is removed.
 - With telemetry on (default, including prompts), Mission Control derives session purpose from the first captured user prompt.

package/dist/templates/har-boilerplate/CLAUDE.agent.md

@@ -12,7 +12,7 @@
 | **Database** | `agent_${AGENT_ID}` on `localhost:${DB_PORT}` (when `db` is in `HARNESS_INFRA_SERVICES`) |
 | **Work dir** | Fresh session worktree per launch — see the launch output or `.har/slots/agent-${AGENT_ID}.json` |
 
-**Never edit the main checkout** — launch FIRST, then make ALL file edits under the work dir from the launch output. Edits there hot-reload in the running slot; use `./.har/agent-cli.sh ${AGENT_ID} restart` if a change doesn't take. Relaunching replaces the session (branch kept) and requires explicit confirmation; dirty worktrees also need `--force` after user approval.
+**Never edit the main checkout** — launch FIRST, then make ALL file edits under the work dir from the launch output. Edits there hot-reload in the running slot; use `./.har/agent-cli.sh ${AGENT_ID} restart` if a change doesn't take. An occupied slot always blocks a new launch — run `./.har/teardown.sh ${AGENT_ID}` (or `complete`) first, then launch again.
 
 This slot runs **only the primary application** (`HARNESS_PRIMARY_APP`). External dependencies and any supporting services run once, shared by all slots — `setup-infra.sh` manages them; never start them yourself.
 

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

@@ -187,13 +187,13 @@ Switch that checkout to your intended base before launch. The session is recorde
 the work dir through it. Make ALL file edits under the work dir printed by launch,
 never in the main checkout.
 
-- Prefer `complete` / `teardown` when a task is finished, then launch.
-- `--replace` destroys the previous worktree (requires confirmation); it does **not**
-  choose `main`. Uncommitted changes also need `--force` after explicit user approval.
+- Occupied slots always block a new launch: `har env complete <id>` (or `teardown <id>`),
+  then `har env launch <id>`. A new launch never chooses `main` for you — switch the
+  main checkout to your intended base first.
 - `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, the registry records `status: failed`.
-  Resume without `--replace`: `har env launch <id> --resume` or `har env recover <id>`.
+  Resume it instead of starting fresh: `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).

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

@@ -103,7 +103,7 @@ process.stdin.on('end', () => {
         exit 1
       fi
       if [ -z "$ENV_FILE" ]; then
-        echo "ERROR: .env.agent.${AGENT_ID} could not be resolved — relaunch with --replace when ready." >&2
+        echo "ERROR: .env.agent.${AGENT_ID} could not be resolved — teardown this slot, then relaunch." >&2
         exit 1
       fi
     elif [ -n "$ENV_FILE" ] && [ -f "$ENV_FILE" ]; then

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

@@ -53,12 +53,18 @@ validate_agent_id() {
   fi
 
   if [[ -z "$id" ]] || ! [[ "$id" =~ ^[0-9]+$ ]]; then
-    echo "Error: agent-id must be a positive integer between ${min} and ${max}" >&2
+    echo "Error: invalid agent slot id: ${id:-"(missing)"}" >&2
+    echo "  Must be an integer between ${min} and ${max} (see .har/stages.json → agentSlots)" >&2
     exit 1
   fi
 
   if (( id < min || id > max )); then
-    echo "Error: agent-id must be between ${min} and ${max}" >&2
+    echo "Error: invalid agent slot id: ${id}" >&2
+    echo "  Valid slots: ${min}–${max} (configured in .har/stages.json → agentSlots)" >&2
+    echo "  Run: har env status   # see which slots are in use" >&2
+    if (( id > max )); then
+      echo "  To allow slot ${id}, raise agentSlots.max in .har/stages.json." >&2
+    fi
     exit 1
   fi
 }
@@ -239,7 +245,7 @@ har_resume_session_assignments() {
     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 "echo \"  Free the slot first: har env teardown ${agent_id} (or complete ${agent_id}), then har env launch ${agent_id}.\" >&2"
     echo 'exit 2'
     return 1
   fi
@@ -320,36 +326,27 @@ har_regenerate_agent_env_file() {
   fi
 }
 
-# har_launch_preflight <agent_id> <force> <replace> [resume]
-# Exit 0 when ready; 2 when occupied/replace required; 1 on machine blockers.
+# har_launch_preflight <agent_id> [resume]
+# Exit 0 when ready; 2 when occupied (free the slot first) or not resumable; 1 on machine blockers.
 # Sets FE_PORT/API_PORT/DEBUG_PORT when this harness uses PM2.
 har_launch_preflight() {
   local agent_id="$1"
-  local force="${2:-false}"
-  local replace="${3:-false}"
-  local resume="${4:-false}"
+  local resume="${2:-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
+      echo "  Free the slot first: har env teardown ${agent_id} (or complete ${agent_id}), then har env launch ${agent_id}." >&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
+    print_slot_occupied_warning "$agent_id"
+    echo "ERROR: slot ${agent_id} is occupied." >&2
+    echo "  Free it first: har env teardown ${agent_id} (or complete ${agent_id}), then har env launch ${agent_id}." >&2
+    return 2
   fi
 
   if har_harness_uses_pm2; then
@@ -511,8 +508,8 @@ slot_dirty_summary() {
   echo "dirty (${count} changed)"
 }
 
-# Print a warning before replacing an occupied slot (stdout — visible to agents).
-print_slot_replace_warning() {
+# Print details about an occupied slot (stdout — visible to agents).
+print_slot_occupied_warning() {
   local agent_id="$1"
   local reg wt branch work_dir created status last_error dirty_summary head
   reg="$(slot_registry_file "$agent_id")"
@@ -528,7 +525,7 @@ print_slot_replace_warning() {
   fi
 
   echo "" >&2
-  echo "⚠ Slot ${agent_id} is already in use — replacing will REMOVE the worktree." >&2
+  echo "⚠ Slot ${agent_id} is already in use." >&2
   [ -n "$wt" ] && echo "  Worktree:  ${wt}" >&2
   [ -n "$work_dir" ] && echo "  Work dir:  ${work_dir}" >&2
   [ -n "$branch" ] && echo "  Branch:    ${branch}${head:+ @ ${head}}" >&2
@@ -544,54 +541,21 @@ print_slot_replace_warning() {
     base_sha="$(git -C "$base_root" rev-parse --short HEAD 2>/dev/null || true)"
     echo "  New session will be based on: ${base_branch}${base_sha:+ @ ${base_sha}}" >&2
     echo "  (HEAD of ${base_root})" >&2
-    echo "  --replace does not choose this base — switch that checkout first for a new unrelated task." >&2
+    echo "  Switch that checkout to your intended base before launching a new session." >&2
     echo "" >&2
   fi
-  echo "  Prefer complete/teardown when the previous task is finished, then launch." >&2
-  echo "  The session branch is kept only if you committed. Gitignored paths" >&2
-  echo "  (state/, runs/, local clones, .env.local) are NOT preserved." >&2
-  echo "" >&2
-}
-
-# Require explicit confirmation before replacing an occupied slot.
-#   $1 agent_id  $2 force(true/false)  $3 replace(true/false)
-# Exits 1 when replacement must not proceed.
-require_slot_replace_confirm() {
-  local agent_id="$1"
-  local force="$2"
-  local replace="$3"
-  local wt
-
-  slot_is_occupied "$agent_id" || return 0
-
-  print_slot_replace_warning "$agent_id"
-  wt="$(existing_slot_worktree "$agent_id")"
-
-  if [ -n "$wt" ] && slot_worktree_dirty "$wt" && [ "$force" != true ]; then
-    echo "ERROR: previous session for slot ${agent_id} has uncommitted changes." >&2
-    echo "  Commit them in the worktree (branch is kept on teardown), or pass --force to discard." >&2
-    echo "  --force destroys uncommitted work — only use after explicit user approval." >&2
-    exit 1
-  fi
-
-  if [ "$replace" = true ] || [ "${HAR_CONFIRM_REPLACE:-}" = "1" ]; then
-    return 0
-  fi
-
-  if [ -t 0 ] && [ -t 1 ]; then
-    local answer
-    read -r -p "Replace slot ${agent_id}? Uncommitted work is lost unless committed. [y/N] " answer
-    if [[ "$answer" =~ ^[Yy]$ ]]; then
-      return 0
-    fi
-    echo "Aborted — slot ${agent_id} left unchanged." >&2
-    exit 2
+  if [ "$dirty_summary" != "clean" ] && [ "$dirty_summary" != "unknown" ]; then
+    echo "  Commit or discard changes in the worktree, then teardown/complete the slot:" >&2
+  else
+    echo "  Free the slot, then launch again:" >&2
   fi
-
-  echo "ERROR: slot ${agent_id} is occupied." >&2
-  echo "  Pass --replace (or set HAR_CONFIRM_REPLACE=1) after reviewing the warning above." >&2
-  echo "  If the worktree is dirty, also pass --force (only after explicit user approval)." >&2
-  exit 2
+  echo "    har env complete ${agent_id}   # or: har env teardown ${agent_id}" >&2
+  echo "    har env launch ${agent_id}" >&2
+  echo "" >&2
+  echo "  complete/teardown remove the worktree. The session branch is kept only if" >&2
+  echo "  you committed. Gitignored paths (state/, runs/, local clones, .env.local)" >&2
+  echo "  are NOT preserved." >&2
+  echo "" >&2
 }
 
 git_common_dir() {

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

@@ -2,8 +2,9 @@
 # Launches a single agent instance with isolated ports, database, and PM2 processes.
 # 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.
+# Occupied slots always block: run ./.har/teardown.sh (or complete it) first, then relaunch.
 #
-# Usage: ./.har/launch.sh <agent-id> [--no-worktree] [--claude] [--replace] [--force] [--resume]
+# Usage: ./.har/launch.sh <agent-id> [--no-worktree] [--claude] [--resume]
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -17,8 +18,6 @@ source "$SCRIPT_DIR/agent-slot.sh"
 AGENT_ID="${1:-}"
 USE_WORKTREE="${HARNESS_USE_WORKTREE:-true}"
 USE_CLAUDE=false
-FORCE=false
-REPLACE=false
 RESUME=false
 WORK_UNIT_ID="${HAR_WORK_UNIT_ID:-}"
 ATTEMPT_ID="${HAR_ATTEMPT_ID:-}"
@@ -28,8 +27,6 @@ for arg in "$@"; do
     --no-worktree) USE_WORKTREE=false ;;
     --worktree) USE_WORKTREE=true ;;
     --claude)   USE_CLAUDE=true ;;
-    --replace)  REPLACE=true ;;
-    --force)    FORCE=true ;;
     --resume)   RESUME=true ;;
     --work-id=*) WORK_UNIT_ID="${arg#*=}" ;;
     --attempt-id=*) ATTEMPT_ID="${arg#*=}" ;;
@@ -44,7 +41,7 @@ export SLOT_ATTEMPT_ID="$ATTEMPT_ID"
 
 if [[ -z "$AGENT_ID" ]]; then
   har_load_agent_slot_limits
-  echo "Usage: $0 <agent-id> [--no-worktree] [--claude] [--replace] [--force] [--resume] " >&2
+  echo "Usage: $0 <agent-id> [--no-worktree] [--claude] [--resume]" >&2
   echo "  agent-id must be between ${HARNESS_AGENT_SLOT_MIN} and ${HARNESS_AGENT_SLOT_MAX}" >&2
   exit 1
 fi
@@ -63,7 +60,7 @@ ENV_FILE=""
 REGISTRY_WRITTEN=false
 
 if [ "$RESUME" = true ]; then
-  har_launch_preflight "$AGENT_ID" "$FORCE" "$REPLACE" true || exit $?
+  har_launch_preflight "$AGENT_ID" true || exit $?
   eval "$(har_resume_session_assignments "$AGENT_ID")"
   REGISTRY_WRITTEN=true
   mark_slot_failed() {
@@ -92,14 +89,8 @@ if [ "$RESUME" = true ]; then
   trap mark_slot_failed EXIT
 else
   # Preflight before worktree/install — ports, foreign PM2, Docker, occupied slot.
-  har_launch_preflight "$AGENT_ID" "$FORCE" "$REPLACE" || exit $?
-
-  # 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
+  # Occupied slots always block here: teardown/complete first, then relaunch.
+  har_launch_preflight "$AGENT_ID" || exit $?
 fi
 
 if har_harness_uses_pm2; then

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Launch readiness gate — run before launch.sh or standalone.
-# Usage: ./.har/preflight.sh <agent-id> [--replace] [--force]
+# Usage: ./.har/preflight.sh <agent-id>
 # JSON:  har env preflight <id> --json
 set -euo pipefail
 
@@ -13,24 +13,15 @@ source "$SCRIPT_DIR/harness.env"
 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
+  echo "Usage: $0 <agent-id>" >&2
   exit 1
 fi
 
 validate_agent_id "$AGENT_ID"
 
-if har_launch_preflight "$AGENT_ID" "$FORCE" "$REPLACE"; then
+if har_launch_preflight "$AGENT_ID"; 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}"

package/dist/templates/har-boilerplate-cli/CLAUDE.agent.md

@@ -9,7 +9,7 @@
 | **Agent ID** | ${AGENT_ID} |
 | **Work dir** | Fresh session worktree per launch — see the launch output or `.har/slots/agent-${AGENT_ID}.json` |
 
-**Never edit the main checkout** — launch FIRST, then make ALL file edits under the work dir from the launch output. Relaunching replaces the session (branch kept) and requires explicit confirmation (`--replace` / `confirmReplace`); dirty worktrees also need `--force` after user approval — never autonomously.
+**Never edit the main checkout** — launch FIRST, then make ALL file edits under the work dir from the launch output. An occupied slot always blocks a new launch — run `har env teardown <id>` (or `complete <id>`) first, then launch again.
 
 ```bash
 ./.har/agent-cli.sh ${AGENT_ID} status

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

@@ -145,9 +145,9 @@ Switch that checkout to your intended base before launch. The session is recorde
 the work dir through it. Make ALL file edits under the work dir printed by launch,
 never in the main checkout.
 
-- Prefer `complete` / `teardown` when a task is finished, then launch.
-- `--replace` destroys the previous worktree (requires confirmation); it does **not**
-  choose `main`. Uncommitted changes also need `--force` after explicit user approval.
+- Occupied slots always block a new launch: `har env complete <id>` (or `teardown <id>`),
+  then `har env launch <id>`. A new launch never chooses `main` for you — switch the
+  main checkout to your intended base first.
 - `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

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

@@ -53,12 +53,18 @@ validate_agent_id() {
   fi
 
   if [[ -z "$id" ]] || ! [[ "$id" =~ ^[0-9]+$ ]]; then
-    echo "Error: agent-id must be a positive integer between ${min} and ${max}" >&2
+    echo "Error: invalid agent slot id: ${id:-"(missing)"}" >&2
+    echo "  Must be an integer between ${min} and ${max} (see .har/stages.json → agentSlots)" >&2
     exit 1
   fi
 
   if (( id < min || id > max )); then
-    echo "Error: agent-id must be between ${min} and ${max}" >&2
+    echo "Error: invalid agent slot id: ${id}" >&2
+    echo "  Valid slots: ${min}–${max} (configured in .har/stages.json → agentSlots)" >&2
+    echo "  Run: har env status   # see which slots are in use" >&2
+    if (( id > max )); then
+      echo "  To allow slot ${id}, raise agentSlots.max in .har/stages.json." >&2
+    fi
     exit 1
   fi
 }
@@ -217,7 +223,7 @@ har_resume_session_assignments() {
     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 "echo \"  Free the slot first: har env teardown ${agent_id} (or complete ${agent_id}), then har env launch ${agent_id}.\" >&2"
     echo 'exit 2'
     return 1
   fi
@@ -304,33 +310,26 @@ EOF
   fi
 }
 
+# har_launch_preflight <agent_id> [resume]
+# Exit 0 when ready; 2 when occupied (free the slot first) or not resumable; 1 on machine blockers.
 har_launch_preflight() {
   local agent_id="$1"
-  local force="${2:-false}"
-  local replace="${3:-false}"
-  local resume="${4:-false}"
+  local resume="${2:-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
+      echo "  Free the slot first: har env teardown ${agent_id} (or complete ${agent_id}), then har env launch ${agent_id}." >&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
+    print_slot_occupied_warning "$agent_id"
+    echo "ERROR: slot ${agent_id} is occupied." >&2
+    echo "  Free it first: har env teardown ${agent_id} (or complete ${agent_id}), then har env launch ${agent_id}." >&2
+    return 2
   fi
 
   if har_harness_uses_pm2; then
@@ -491,8 +490,8 @@ slot_dirty_summary() {
   echo "dirty (${count} changed)"
 }
 
-# Print a warning before replacing an occupied slot (stdout — visible to agents).
-print_slot_replace_warning() {
+# Print details about an occupied slot (stdout — visible to agents).
+print_slot_occupied_warning() {
   local agent_id="$1"
   local reg wt branch work_dir created status last_error dirty_summary head
   reg="$(slot_registry_file "$agent_id")"
@@ -508,7 +507,7 @@ print_slot_replace_warning() {
   fi
 
   echo "" >&2
-  echo "⚠ Slot ${agent_id} is already in use — replacing will REMOVE the worktree." >&2
+  echo "⚠ Slot ${agent_id} is already in use." >&2
   [ -n "$wt" ] && echo "  Worktree:  ${wt}" >&2
   [ -n "$work_dir" ] && echo "  Work dir:  ${work_dir}" >&2
   [ -n "$branch" ] && echo "  Branch:    ${branch}${head:+ @ ${head}}" >&2
@@ -524,54 +523,21 @@ print_slot_replace_warning() {
     base_sha="$(git -C "$base_root" rev-parse --short HEAD 2>/dev/null || true)"
     echo "  New session will be based on: ${base_branch}${base_sha:+ @ ${base_sha}}" >&2
     echo "  (HEAD of ${base_root})" >&2
-    echo "  --replace does not choose this base — switch that checkout first for a new unrelated task." >&2
+    echo "  Switch that checkout to your intended base before launching a new session." >&2
     echo "" >&2
   fi
-  echo "  Prefer complete/teardown when the previous task is finished, then launch." >&2
-  echo "  The session branch is kept only if you committed. Gitignored paths" >&2
-  echo "  (state/, runs/, local clones, .env.local) are NOT preserved." >&2
-  echo "" >&2
-}
-
-# Require explicit confirmation before replacing an occupied slot.
-#   $1 agent_id  $2 force(true/false)  $3 replace(true/false)
-# Exits 1 when replacement must not proceed.
-require_slot_replace_confirm() {
-  local agent_id="$1"
-  local force="$2"
-  local replace="$3"
-  local wt
-
-  slot_is_occupied "$agent_id" || return 0
-
-  print_slot_replace_warning "$agent_id"
-  wt="$(existing_slot_worktree "$agent_id")"
-
-  if [ -n "$wt" ] && slot_worktree_dirty "$wt" && [ "$force" != true ]; then
-    echo "ERROR: previous session for slot ${agent_id} has uncommitted changes." >&2
-    echo "  Commit them in the worktree (branch is kept on teardown), or pass --force to discard." >&2
-    echo "  --force destroys uncommitted work — only use after explicit user approval." >&2
-    exit 1
-  fi
-
-  if [ "$replace" = true ] || [ "${HAR_CONFIRM_REPLACE:-}" = "1" ]; then
-    return 0
-  fi
-
-  if [ -t 0 ] && [ -t 1 ]; then
-    local answer
-    read -r -p "Replace slot ${agent_id}? Uncommitted work is lost unless committed. [y/N] " answer
-    if [[ "$answer" =~ ^[Yy]$ ]]; then
-      return 0
-    fi
-    echo "Aborted — slot ${agent_id} left unchanged." >&2
-    exit 2
+  if [ "$dirty_summary" != "clean" ] && [ "$dirty_summary" != "unknown" ]; then
+    echo "  Commit or discard changes in the worktree, then teardown/complete the slot:" >&2
+  else
+    echo "  Free the slot, then launch again:" >&2
   fi
-
-  echo "ERROR: slot ${agent_id} is occupied." >&2
-  echo "  Pass --replace (or set HAR_CONFIRM_REPLACE=1) after reviewing the warning above." >&2
-  echo "  If the worktree is dirty, also pass --force (only after explicit user approval)." >&2
-  exit 2
+  echo "    har env complete ${agent_id}   # or: har env teardown ${agent_id}" >&2
+  echo "    har env launch ${agent_id}" >&2
+  echo "" >&2
+  echo "  complete/teardown remove the worktree. The session branch is kept only if" >&2
+  echo "  you committed. Gitignored paths (state/, runs/, local clones, .env.local)" >&2
+  echo "  are NOT preserved." >&2
+  echo "" >&2
 }
 
 git_common_dir() {

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

@@ -2,8 +2,9 @@
 # Launch an agent slot for CLI/library repos (git worktree by default, optional Docker infra).
 # 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.
+# Occupied slots always block: run ./.har/teardown.sh (or complete it) first, then relaunch.
 #
-# Usage: ./.har/launch.sh <agent-id> [--no-worktree] [--replace] [--force] [--resume]
+# Usage: ./.har/launch.sh <agent-id> [--no-worktree] [--resume]
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -16,8 +17,6 @@ source "$SCRIPT_DIR/agent-slot.sh"
 
 AGENT_ID="${1:-}"
 USE_WORKTREE="${HARNESS_USE_WORKTREE:-true}"
-FORCE=false
-REPLACE=false
 RESUME=false
 WORK_UNIT_ID="${HAR_WORK_UNIT_ID:-}"
 ATTEMPT_ID="${HAR_ATTEMPT_ID:-}"
@@ -26,8 +25,6 @@ for arg in "$@"; do
   case "$arg" in
     --no-worktree) USE_WORKTREE=false ;;
     --worktree) USE_WORKTREE=true ;;
-    --replace)  REPLACE=true ;;
-    --force)    FORCE=true ;;
     --resume)   RESUME=true ;;
     --work-id=*) WORK_UNIT_ID="${arg#*=}" ;;
     --attempt-id=*) ATTEMPT_ID="${arg#*=}" ;;
@@ -42,7 +39,7 @@ export SLOT_ATTEMPT_ID="$ATTEMPT_ID"
 
 if [[ -z "$AGENT_ID" ]]; then
   har_load_agent_slot_limits
-  echo "Usage: $0 <agent-id> [--no-worktree] [--replace] [--force] [--resume] " >&2
+  echo "Usage: $0 <agent-id> [--no-worktree] [--resume]" >&2
   echo "  agent-id must be between ${HARNESS_AGENT_SLOT_MIN} and ${HARNESS_AGENT_SLOT_MAX}" >&2
   exit 1
 fi
@@ -61,7 +58,7 @@ ENV_FILE=""
 REGISTRY_WRITTEN=false
 
 if [ "$RESUME" = true ]; then
-  har_launch_preflight "$AGENT_ID" "$FORCE" "$REPLACE" true || exit $?
+  har_launch_preflight "$AGENT_ID" true || exit $?
   eval "$(har_resume_session_assignments "$AGENT_ID")"
   REGISTRY_WRITTEN=true
   mark_slot_failed() {
@@ -87,13 +84,8 @@ if [ "$RESUME" = true ]; then
   }
   trap mark_slot_failed EXIT
 else
-  har_launch_preflight "$AGENT_ID" "$FORCE" "$REPLACE" || exit $?
-
-  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
+  # Occupied slots always block here: teardown/complete first, then relaunch.
+  har_launch_preflight "$AGENT_ID" || exit $?
 fi
 
 "$SCRIPT_DIR/setup-infra.sh"

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Launch readiness gate for CLI/library harnesses (occupied slot only).
-# Usage: ./.har/preflight.sh <agent-id> [--replace] [--force]
+# Usage: ./.har/preflight.sh <agent-id>
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -12,24 +12,15 @@ source "$SCRIPT_DIR/harness.env"
 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
+  echo "Usage: $0 <agent-id>" >&2
   exit 1
 fi
 
 validate_agent_id "$AGENT_ID"
 
-if har_launch_preflight "$AGENT_ID" "$FORCE" "$REPLACE"; then
+if har_launch_preflight "$AGENT_ID"; then
   echo "Slot ${AGENT_ID}: ready to launch."
   exit 0
 fi