agentic-loop 3.18.2 → 3.21.0

package/ralph/loop.sh

@@ -29,7 +29,7 @@ preflight_checks() {
 
   # Check frontend connectivity if configured
   local test_url
-  test_url=$(get_config '.testUrlBase' "")
+  test_url=$(get_config '.urls.frontend' "")
   if [[ -n "$test_url" ]]; then
     printf "  Frontend connectivity ($test_url)... "
     if curl -sf --connect-timeout 5 "$test_url" >/dev/null 2>&1; then
@@ -48,8 +48,8 @@ preflight_checks() {
     # Check for alembic migrations
     if [[ -d "$backend_dir/alembic" ]] || [[ -d "$backend_dir/migrations" ]]; then
       printf "  Database migrations... "
-      # Detect Python runner
-      local py_runner="python"
+      # Detect Python runner (python3 for macOS compatibility)
+      local py_runner="python3"
       if [[ -f "$backend_dir/uv.lock" ]]; then
         py_runner="uv run"
       elif [[ -f "$backend_dir/poetry.lock" ]]; then
@@ -158,6 +158,22 @@ _write_preflight_cache() {
   echo "$(date +%s) $config_hash" > "$RALPH_DIR/.preflight_cache"
 }
 
+_prd_structure_hash() {
+  # Hash only the fields that PRD validation cares about (story structure, testSteps, etc.)
+  # Ignores runtime state (passes, retryCount, skipped) so loop progress doesn't
+  # invalidate the validation cache and trigger expensive re-fixes on every restart.
+  jq '[.stories[] | del(.passes, .retryCount, .skipped, .skipReason)] | sort_by(.id)' \
+    "$RALPH_DIR/prd.json" 2>/dev/null | _file_hash_stdin
+}
+
+_file_hash_stdin() {
+  if command -v md5sum &>/dev/null; then
+    md5sum | cut -d' ' -f1
+  else
+    md5 -q
+  fi
+}
+
 _is_prd_cached() {
   local cache_file="$RALPH_DIR/.prd_validated"
   [[ ! -f "$cache_file" ]] && return 1
@@ -170,7 +186,7 @@ _is_prd_cached() {
   [[ $(( now - cached_time )) -gt $PREFLIGHT_CACHE_TTL_SECONDS ]] && return 1
 
   local prd_hash
-  prd_hash=$(_file_hash "$RALPH_DIR/prd.json")
+  prd_hash=$(_prd_structure_hash)
   [[ "$cached_hash" != "$prd_hash" ]] && return 1
 
   return 0
@@ -178,7 +194,7 @@ _is_prd_cached() {
 
 _write_prd_cache() {
   local prd_hash
-  prd_hash=$(_file_hash "$RALPH_DIR/prd.json")
+  prd_hash=$(_prd_structure_hash)
   echo "$(date +%s) $prd_hash" > "$RALPH_DIR/.prd_validated"
 }
 
@@ -317,6 +333,9 @@ $existing_signs
 ## Rules
 - Extract a single, actionable pattern that prevents this class of failure
 - The pattern should be general enough to apply to future stories, not specific to this one
+- NEVER include credentials, passwords, API keys, tokens, emails, or secrets in the pattern
+  Instead of: "Login with admin@example.com / Password123"
+  Write: "Use Playwright to login with test credentials from environment variables"
 - If the failure is trivial, unclear, or you can't extract a useful pattern, respond with just: NONE
 - Category must be one of: backend, frontend, testing, general, database, security
 
@@ -373,6 +392,12 @@ PATTERN: <pattern>"
       ;;
   esac
 
+  # Reject signs that contain credentials or secrets
+  if echo "$pattern" | grep -qiE '([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}|password[[:space:]]*[:=]|[[:space:]][A-Za-z0-9_]*_?(pass|pwd|token|secret|key|api.?key)[[:space:]]*[:=]|sk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36})'; then
+    log_progress "$story" "SIGN_AUTO" "Skipped - pattern contains credentials"
+    return 0
+  fi
+
   # Check for duplicates before adding
   if _sign_is_duplicate "$pattern"; then
     log_progress "$story" "SIGN_AUTO" "Skipped - duplicate of existing sign"
@@ -390,14 +415,234 @@ PATTERN: <pattern>"
   return 0
 }
 
-run_loop() {
-  # Trap Ctrl+C so it stops the entire loop, not just the current child process.
-  # Without this, SIGINT only kills the pipeline (claude|tee) and the while loop continues.
-  trap 'echo ""; print_warning "Ctrl+C received — stopping loop..."; trap - INT; kill -INT $$' INT
+# Generate a starter docker-compose.yml based on detected project type
+_generate_docker_compose() {
+  local project_type
+  project_type=$(detect_project_type)
+
+  local compose_content=""
+
+  case "$project_type" in
+    fullstack|django|fastapi|python|node)
+      compose_content="services:
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: app
+      POSTGRES_DB: app_dev
+    ports:
+      - \"5432:5432\"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: [\"CMD-SHELL\", \"pg_isready -U app\"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    ports:
+      - \"6379:6379\"
+    healthcheck:
+      test: [\"CMD\", \"redis-cli\", \"ping\"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  pgdata:"
+      ;;
+    go|rust)
+      compose_content="services:
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: app
+      POSTGRES_DB: app_dev
+    ports:
+      - \"5432:5432\"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: [\"CMD-SHELL\", \"pg_isready -U app\"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  pgdata:"
+      ;;
+    elixir)
+      compose_content="services:
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: app_dev
+    ports:
+      - \"5432:5432\"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: [\"CMD-SHELL\", \"pg_isready -U postgres\"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  pgdata:"
+      ;;
+    fastmcp)
+      compose_content="services:
+  app:
+    build: .
+    ports:
+      - \"8000:8000\"
+    volumes:
+      - .:/app
+    environment:
+      - LOG_LEVEL=debug"
+      ;;
+    *)
+      # minimal or unknown — shouldn't reach here but handle gracefully
+      print_warning "No Docker template for project type: $project_type"
+      return 1
+      ;;
+  esac
+
+  echo "$compose_content" > docker-compose.yml
+  print_success "Generated docker-compose.yml for $project_type project"
+  echo ""
+  echo "  Services:"
+  grep -E '^[[:space:]]{2}[a-z]' docker-compose.yml | sed 's/:$//' | sed 's/^/    /'
+  echo ""
+  echo "  Next steps:"
+  echo "    docker compose up -d"
+  echo "    docker compose ps        # verify services are healthy"
+  echo ""
+  echo "  Update your .env to point at the Docker services:"
+  case "$project_type" in
+    elixir)
+      echo "    DATABASE_URL=ecto://postgres:postgres@localhost:5432/app_dev"
+      ;;
+    fastmcp)
+      ;;
+    *)
+      echo "    DATABASE_URL=postgresql://app:app@localhost:5432/app_dev"
+      echo "    REDIS_URL=redis://localhost:6379"
+      ;;
+  esac
+  echo ""
+}
 
-  local max_iterations="$DEFAULT_MAX_ITERATIONS"
+# Check for Docker compose files and warn if missing
+# Called from run_loop() before preflight checks
+_docker_safety_warning() {
+  # Skip if env var is set
+  [[ "${RALPH_SKIP_DOCKER_WARNING:-}" == "1" ]] && return 0
+
+  # Skip if docker.enabled is true in config
+  local docker_enabled
+  docker_enabled=$(get_config '.docker.enabled' "false")
+  if [[ "$docker_enabled" == "true" ]]; then
+    return 0
+  fi
+
+  # Skip if project type doesn't need services
+  local project_type
+  project_type=$(detect_project_type)
+  if [[ "$project_type" == "minimal" || "$project_type" == "hugo" ]]; then
+    return 0
+  fi
+
+  # Check for any compose file
+  for compose_file in "docker-compose.yml" "docker-compose.yaml" "compose.yml" "compose.yaml"; do
+    if [[ -f "$compose_file" ]]; then
+      return 0
+    fi
+  done
+
+  # No compose file found — show warning
+  echo ""
+  echo "  ╔══════════════════════════════════════════════════════════════════╗"
+  echo "  ║                                                                  ║"
+  echo "  ║   ⚠️  YOUR PROJECT IS NOT USING DOCKER                          ║"
+  echo "  ║                                                                  ║"
+  echo "  ║   Ralph runs autonomously — it writes code, runs commands,       ║"
+  echo "  ║   and executes migrations without asking.                        ║"
+  echo "  ║                                                                  ║"
+  echo "  ║   Without Docker, Ralph operates directly on your local          ║"
+  echo "  ║   machine. A bad migration can corrupt real databases.           ║"
+  echo "  ║   A runaway command can affect services outside this repo.       ║"
+  echo "  ║                                                                  ║"
+  echo "  ║   With Docker, your project's services are isolated:             ║"
+  echo "  ║     - Databases and caches run in containers, not locally        ║"
+  echo "  ║     - Nothing outside the project is touched                     ║"
+  echo "  ║     - Reset anytime: docker compose down -v && up -d             ║"
+  echo "  ║                                                                  ║"
+  echo "  ║   Suppress: RALPH_SKIP_DOCKER_WARNING=1 npx agentic-loop run    ║"
+  echo "  ║                                                                  ║"
+  echo "  ╚══════════════════════════════════════════════════════════════════╝"
+  echo ""
+
+  local response
+  read -r -p "  [S]et up Docker now  |  [C]ontinue without Docker  |  [Q]uit: " response
+
+  case "$response" in
+    [Ss])
+      echo ""
+      if ! _generate_docker_compose; then
+        print_info "You can create a docker-compose.yml manually, or continue without Docker."
+      fi
+      ;;
+    [Qq])
+      echo ""
+      echo "  Exiting. Set up Docker and try again, or suppress with:"
+      echo "    RALPH_SKIP_DOCKER_WARNING=1 npx agentic-loop run"
+      echo ""
+      exit 0
+      ;;
+    *)
+      # Default: continue
+      echo ""
+      print_info "Continuing without Docker. Suppress future warnings with:"
+      echo "    RALPH_SKIP_DOCKER_WARNING=1 npx agentic-loop run"
+      echo ""
+      ;;
+  esac
+}
+
+run_loop() {
+  # PID of the currently running Claude pipeline (used by trap to kill it)
+  _CLAUDE_PIPELINE_PID=""
+
+  # Trap Ctrl+C to kill Claude and stop the loop.
+  # When Claude runs as a foreground pipeline, bash defers trap handling until the
+  # pipeline exits — so Ctrl+C just gets swallowed. We solve this by running the
+  # pipeline in a background subshell and `wait`ing for it, which lets the trap
+  # fire immediately. The trap kills the subshell, touches .stop, then exits.
+  trap '
+    echo ""
+    print_warning "Ctrl+C received — stopping loop..."
+    [[ -n "$_CLAUDE_PIPELINE_PID" ]] && kill -TERM "$_CLAUDE_PIPELINE_PID" 2>/dev/null
+    touch "$RALPH_DIR/.stop"
+    kill 0 2>/dev/null
+    exit 130
+  ' INT
+
+  local max_iterations=""  # No cap by default — per-story circuit breaker is the safety net
   local specific_story=""
   local fast_mode=false
+  local quiet_mode
+  quiet_mode=$(get_config '.quiet' "false")
 
   # Parse arguments
   while [[ $# -gt 0 ]]; do
@@ -414,6 +659,10 @@ run_loop() {
         fast_mode=true
         shift
         ;;
+      --quiet)
+        quiet_mode=true
+        shift
+        ;;
       *)
         shift
         ;;
@@ -426,6 +675,9 @@ run_loop() {
   # Validate prerequisites
   check_dependencies
 
+  # Warn if no Docker compose file (safety net for autonomous execution)
+  _docker_safety_warning
+
   # Pre-loop checks to catch issues before wasting iterations
   if [[ "$fast_mode" == "true" ]]; then
     print_info "Fast mode: skipping connectivity checks"
@@ -460,9 +712,21 @@ run_loop() {
     else
       print_error "No PRD found."
       echo ""
-      echo "Create one with:"
-      echo "  /idea 'your feature description'   # thorough (recommended)"
-      echo "  ralph prd 'your feature'           # quick"
+      echo "  You need to create a plan before Ralph can run."
+      echo ""
+      echo "  1. Open Claude in your terminal:"
+      echo ""
+      echo "       claude --dangerously-skip-permissions"
+      echo ""
+      echo "  2. Inside Claude, type:"
+      echo ""
+      echo "       /idea \"your feature description\""
+      echo ""
+      echo "  Note: /idea is a Claude skill — it only works inside an active"
+      echo "  Claude session, not from your regular terminal."
+      echo ""
+      echo "  See Step 4 of the Getting Started guide:"
+      echo "    docs/GETTING-STARTED.md"
       echo ""
       exit 1
     fi
@@ -499,13 +763,16 @@ run_loop() {
   # Default to 5 retries - enough for transient issues, stops before wasting cycles
   # Override with config.json: "maxStoryRetries": 8
   max_story_retries=$(get_config '.maxStoryRetries' "5")
+  # Read timeout once at loop start — not per iteration, so Claude can't extend it mid-run
+  local timeout_seconds
+  timeout_seconds=$(get_config '.maxSessionSeconds' "$DEFAULT_TIMEOUT_SECONDS")
   local total_attempts=0
   local skipped_stories=()
   local start_time
   local session_started=false  # Track if we've started a Claude session
   start_time=$(date +%s)
 
-  while [[ $iteration -lt $max_iterations ]]; do
+  while [[ -z "$max_iterations" || $iteration -lt $max_iterations ]]; do
     # Check for stop signal
     if [[ -f "$RALPH_DIR/.stop" ]]; then
       rm -f "$RALPH_DIR/.stop"
@@ -519,7 +786,11 @@ run_loop() {
 
     ((iteration++))
     echo ""
-    print_info "=== Iteration $iteration/$max_iterations ==="
+    if [[ -n "$max_iterations" ]]; then
+      print_info "=== Iteration $iteration/$max_iterations ==="
+    else
+      print_info "=== Iteration $iteration ==="
+    fi
     echo ""
 
     # 1. Get next incomplete story
@@ -683,11 +954,12 @@ run_loop() {
     echo "└─────────────────────────────────────────────────────────┘"
     echo ""
 
-    local timeout_seconds
-    timeout_seconds=$(get_config '.maxSessionSeconds' "$DEFAULT_TIMEOUT_SECONDS")
+    # Snapshot PRD passes state before Claude runs (detect tampering after)
+    local passes_before
+    passes_before=$(jq '[.stories[] | {id, passes}]' "$RALPH_DIR/prd.json" 2>/dev/null)
 
     # Run Claude - first story gets fresh session, subsequent continue the session
-    local -a claude_args=(-p --dangerously-skip-permissions --verbose)
+    local -a claude_args=(-p --dangerously-skip-permissions --verbose --output-format stream-json)
     if [[ "$session_started" == "true" ]]; then
       claude_args=(--continue "${claude_args[@]}")
     fi
@@ -696,27 +968,146 @@ run_loop() {
     local claude_output_log claude_exit_code max_crash_retries=5 crash_attempt=0
     claude_output_log=$(create_temp_file ".log") || { rm -f "$prompt_file"; return 1; }
 
-    # Filter to hide ugly CLI crash messages from terminal (still captured in log)
-    # Strips: "This error originated...", "Error: No messages", stack traces
-    _filter_cli_noise() {
-      grep -v -E \
-        -e "This error originated either by throwing" \
-        -e "a catch block, or by rejecting a promise" \
-        -e "The promise rejected with the reason:" \
-        -e "Error: No messages returned" \
-        -e "at [A-Za-z0-9_]+ \(/\\\$bunfs/" \
-        -e "at processTicksAndRejections" \
-        -e "unhandled.*promise.*rejection" \
-        || true  # Don't fail if no lines pass filter
+    # Parse stream-json output from Claude CLI and display a live activity feed.
+    # Shows tool usage (Read, Edit, Bash, etc.) as clean one-line summaries.
+    # Non-JSON lines (crash messages) are passed through for crash detection.
+    # Usage: _parse_stream_activity "true"|"false"
+    _parse_stream_activity() {
+      local quiet="${1:-false}"
+      local dim=$'\033[2m' green=$'\033[0;32m' nc=$'\033[0m'
+      local line
+      while IFS= read -r line; do
+        # Non-JSON lines (crash messages, errors) — always pass through
+        if [[ "$line" != "{"* ]]; then
+          echo "$line"
+          continue
+        fi
+
+        # In quiet mode, skip all JSON parsing (activity suppressed)
+        if [[ "$quiet" == "true" ]]; then
+          continue
+        fi
+
+        # Fast pre-filter: only parse assistant (tool activity) and result (summary)
+        # events. Skip system/user/etc. to avoid unnecessary jq calls.
+        if [[ "$line" != *'"assistant"'* && "$line" != *'"result"'* ]]; then
+          continue
+        fi
+
+        local msg_type
+        msg_type=$(jq -r '.type // empty' <<< "$line" 2>/dev/null) || continue
+
+        if [[ "$msg_type" == "assistant" ]]; then
+          # Show Claude's explanation if present (the "what/why" before tool calls)
+          local explanation
+          explanation=$(jq -r '
+            [.message.content[]? | select(.type == "text") | .text] | join(" ")
+          ' <<< "$line" 2>/dev/null)
+          if [[ -n "$explanation" ]]; then
+            # Take first sentence and truncate at word boundary
+            explanation="${explanation%%.*}"
+            if [[ ${#explanation} -gt 72 ]]; then
+              explanation="${explanation:0:72}"
+              explanation="${explanation% *}..."
+            fi
+            printf "  ${dim}— %s${nc}\n" "$explanation"
+          fi
+
+          # Extract tool_use content blocks
+          local tool_entries
+          tool_entries=$(jq -r '
+            .message.content[]?
+            | select(.type == "tool_use")
+            | .name + "\t" + (.input | tostring)
+          ' <<< "$line" 2>/dev/null) || continue
+
+          while IFS=$'\t' read -r tool_name tool_input; do
+            [[ -z "$tool_name" ]] && continue
+            local label="" detail=""
+            case "$tool_name" in
+              Read)
+                label="Reading"
+                detail=$(jq -r '.file_path // empty' <<< "$tool_input" 2>/dev/null)
+                detail="${detail#"$PWD/"}"
+                ;;
+              Edit)
+                label="Editing"
+                detail=$(jq -r '.file_path // empty' <<< "$tool_input" 2>/dev/null)
+                detail="${detail#"$PWD/"}"
+                ;;
+              Write)
+                label="Creating"
+                detail=$(jq -r '.file_path // empty' <<< "$tool_input" 2>/dev/null)
+                detail="${detail#"$PWD/"}"
+                ;;
+              Bash)
+                label="Running"
+                # Prefer human-readable description over raw command
+                detail=$(jq -r '.description // empty' <<< "$tool_input" 2>/dev/null)
+                if [[ -z "$detail" ]]; then
+                  detail=$(jq -r '.command // empty' <<< "$tool_input" 2>/dev/null)
+                  detail="${detail:0:60}"
+                fi
+                ;;
+              Grep)
+                label="Searching"
+                detail=$(jq -r '.pattern // empty' <<< "$tool_input" 2>/dev/null)
+                detail="for \"$detail\""
+                ;;
+              Glob)
+                label="Finding"
+                detail=$(jq -r '.pattern // empty' <<< "$tool_input" 2>/dev/null)
+                detail="files matching $detail"
+                ;;
+              Task)
+                label="Spawning"
+                detail=$(jq -r '.description // empty' <<< "$tool_input" 2>/dev/null)
+                ;;
+              *)
+                label="$tool_name"
+                ;;
+            esac
+            printf "  ${dim}⟳${nc} %-10s %s\n" "$label" "$detail"
+          done <<< "$tool_entries"
+
+        elif [[ "$msg_type" == "result" ]]; then
+          local cost duration_ms
+          cost=$(jq -r '.total_cost_usd // empty' <<< "$line" 2>/dev/null)
+          duration_ms=$(jq -r '.duration_ms // empty' <<< "$line" 2>/dev/null)
+          local cost_str="" dur_str=""
+          [[ -n "$cost" ]] && cost_str=$(printf '$%.2f' "$cost")
+          if [[ -n "$duration_ms" ]]; then
+            local total_secs=$(( duration_ms / 1000 ))
+            if [[ $total_secs -ge 60 ]]; then
+              dur_str="$((total_secs / 60))m $((total_secs % 60))s"
+            else
+              dur_str="${total_secs}s"
+            fi
+          fi
+          echo ""
+          if [[ -n "$cost_str" && -n "$dur_str" ]]; then
+            echo -e "  ${green}✓ Done${nc} ${dim}(${cost_str}, ${dur_str})${nc}"
+          elif [[ -n "$cost_str" ]]; then
+            echo -e "  ${green}✓ Done${nc} ${dim}(${cost_str})${nc}"
+          elif [[ -n "$dur_str" ]]; then
+            echo -e "  ${green}✓ Done${nc} ${dim}(${dur_str})${nc}"
+          fi
+        fi
+      done
     }
 
     while [[ $crash_attempt -lt $max_crash_retries ]]; do
       claude_exit_code=0
-      # Use pipefail to capture Claude's exit code, not tee's
-      set -o pipefail
-      # Capture full output to log, show filtered output to terminal
-      cat "$prompt_file" | run_with_timeout "$timeout_seconds" claude "${claude_args[@]}" 2>&1 | tee "$claude_output_log" | _filter_cli_noise || claude_exit_code=$?
-      set +o pipefail
+      # Run Claude in a background subshell so the INT trap can fire immediately.
+      # Without this, bash defers SIGINT handling until the foreground pipeline exits,
+      # making Ctrl+C unresponsive while Claude is running.
+      (
+        set -o pipefail
+        cat "$prompt_file" | run_with_timeout "$timeout_seconds" claude "${claude_args[@]}" 2>&1 | tee "$claude_output_log" | _parse_stream_activity "$quiet_mode"
+      ) &
+      _CLAUDE_PIPELINE_PID=$!
+      wait "$_CLAUDE_PIPELINE_PID" || claude_exit_code=$?
+      _CLAUDE_PIPELINE_PID=""
 
       # Check for recoverable CLI crashes (transient API failures)
       if grep -qE "(No messages returned|unhandled.*promise.*rejection)" "$claude_output_log" 2>/dev/null; then
@@ -752,6 +1143,55 @@ run_loop() {
 
     rm -f "$claude_output_log"
 
+    # Check for skip signal (user ran `ralph skip` while Claude was running)
+    if [[ -f "$RALPH_DIR/.skip" ]]; then
+      rm -f "$RALPH_DIR/.skip"
+      print_warning "Skip signal received — skipping $story"
+      log_progress "$story" "SKIPPED" "User requested skip"
+      skipped_stories+=("$story")
+      jq --arg id "$story" '(.stories[] | select(.id==$id)) |= . + {skipped: true, skipReason: "user skipped"}' \
+        "$RALPH_DIR/prd.json" > "$RALPH_DIR/prd.json.tmp" && mv "$RALPH_DIR/prd.json.tmp" "$RALPH_DIR/prd.json"
+      last_story=""
+      consecutive_failures=0
+      consecutive_timeouts=0
+      session_started=false
+      rm -f "$prompt_file"
+      continue
+    fi
+
+    # Check for blocked signal (Claude created .blocked to indicate it's stuck)
+    if [[ -f "$RALPH_DIR/.blocked" ]]; then
+      local block_reason
+      block_reason=$(cat "$RALPH_DIR/.blocked" 2>/dev/null | head -1)
+      rm -f "$RALPH_DIR/.blocked"
+      print_error "Story $story blocked — ${block_reason:-no reason given}"
+      log_progress "$story" "BLOCKED" "${block_reason:-Claude signaled blocked}"
+      echo ""
+      echo "  Claude signaled it cannot complete this story."
+      echo "  Check .ralph/progress.txt for details on what was attempted."
+      echo ""
+      mkdir -p "$RALPH_DIR/failures"
+      echo "${block_reason:-Claude signaled blocked}" > "$RALPH_DIR/failures/$story.txt"
+      local passed failed
+      passed=$(jq '[.stories[] | select(.passes==true)] | length' "$RALPH_DIR/prd.json" 2>/dev/null || echo "0")
+      failed=$(jq '[.stories[] | select(.passes==false)] | length' "$RALPH_DIR/prd.json" 2>/dev/null || echo "0")
+      send_notification "🛑 Ralph stopped: $story blocked. $passed passed, $failed remaining"
+      print_progress_summary "$start_time" "$total_attempts" "0"
+      rm -f "$prompt_file"
+      return 1
+    fi
+
+    # Check for stop signal (user ran `ralph stop` or Ctrl+C while Claude was running)
+    if [[ -f "$RALPH_DIR/.stop" ]]; then
+      rm -f "$RALPH_DIR/.stop" "$prompt_file"
+      print_warning "Stop signal received. Exiting gracefully."
+      local passed failed
+      passed=$(jq '[.stories[] | select(.passes==true)] | length' "$RALPH_DIR/prd.json" 2>/dev/null || echo "0")
+      failed=$(jq '[.stories[] | select(.passes==false)] | length' "$RALPH_DIR/prd.json" 2>/dev/null || echo "0")
+      send_notification "🛑 Ralph stopped: $passed passed, $failed remaining"
+      return 0
+    fi
+
     if [[ $claude_exit_code -ne 0 ]]; then
       ((consecutive_timeouts++))
       print_warning "Claude session ended (timeout or error) - timeout $consecutive_timeouts/$max_timeouts"
@@ -761,24 +1201,27 @@ run_loop() {
       # Session may be broken - reset for next attempt
       session_started=false
 
-      # Skip on repeated timeouts (story is too large/complex for single session)
+      # Stop loop on repeated timeouts — story needs manual intervention
       if [[ $consecutive_timeouts -ge $max_timeouts ]]; then
-        print_error "Story $story timed out $max_timeouts times - needs to be broken up"
+        print_error "Story $story timed out $max_timeouts consecutive times — stopping loop"
         echo ""
-        echo "  Consecutive timeouts indicate the story is too large for a single"
-        echo "  Claude session (${timeout_seconds}s). Consider:"
-        echo "    - Breaking it into smaller, focused stories"
-        echo "    - Increasing maxSessionSeconds in config.json"
+        echo "  The story timed out ${max_timeouts}x (${timeout_seconds}s each). This usually means:"
+        echo "    - The story is too large for a single Claude session"
+        echo "    - Claude is stuck in a retry loop within the session"
+        echo ""
+        echo "  To fix:"
+        echo "    - Break the story into smaller stories"
+        echo "    - Increase maxSessionSeconds in .ralph/config.json"
+        echo "    - Check .ralph/progress.txt for what Claude was attempting"
         echo ""
         mkdir -p "$RALPH_DIR/failures"
         echo "Story $story timed out $max_timeouts consecutive times (${timeout_seconds}s each)" > "$RALPH_DIR/failures/$story.txt"
-        echo "Consider breaking this story into smaller pieces." >> "$RALPH_DIR/failures/$story.txt"
-        skipped_stories+=("$story")
-        jq --arg id "$story" '(.stories[] | select(.id==$id)) |= . + {skipped: true, skipReason: "repeated timeouts"}' "$RALPH_DIR/prd.json" > "$RALPH_DIR/prd.json.tmp" && mv "$RALPH_DIR/prd.json.tmp" "$RALPH_DIR/prd.json"
-        last_story=""
-        consecutive_failures=0
-        consecutive_timeouts=0
-        continue
+        local passed failed
+        passed=$(jq '[.stories[] | select(.passes==true)] | length' "$RALPH_DIR/prd.json" 2>/dev/null || echo "0")
+        failed=$(jq '[.stories[] | select(.passes==false)] | length' "$RALPH_DIR/prd.json" 2>/dev/null || echo "0")
+        send_notification "🛑 Ralph stopped: $story timed out ${max_timeouts}x. $passed passed, $failed remaining"
+        print_progress_summary "$start_time" "$total_attempts" "0"
+        return 1
       fi
 
       # If running specific story, exit on failure
@@ -792,6 +1235,19 @@ run_loop() {
     rm -f "$prompt_file"
     session_started=true  # Mark session as active for subsequent stories
 
+    # Reset any story state changes Claude made — Ralph owns passes/retryCount/skipped
+    local passes_after
+    passes_after=$(jq '[.stories[] | {id, passes}]' "$RALPH_DIR/prd.json" 2>/dev/null)
+    if [[ "$passes_before" != "$passes_after" ]]; then
+      print_info "Resetting story state — verification will determine pass/fail"
+      log_progress "$story" "RESET" "Story state modified during session, restored before verification"
+      local restored
+      restored=$(jq --argjson before "$passes_before" '
+        .stories |= [.[] | . as $s | ($before[] | select(.id == $s.id)) as $orig |
+          if $orig then $s + {passes: $orig.passes} else $s end]
+      ' "$RALPH_DIR/prd.json") && echo "$restored" > "$RALPH_DIR/prd.json"
+    fi
+
     # 5. Run migrations BEFORE verification (tests need DB schema)
     if ! run_migrations_if_needed "$pre_story_sha"; then
       log_progress "$story" "FAILED" "Migration failed"
@@ -804,8 +1260,9 @@ run_loop() {
     echo ""
     # Capture verification output for failure context
     local verify_log="$RALPH_DIR/last_verification.log"
-    set -o pipefail
-    if run_verification "$story" 2>&1 | tee "$verify_log"; then
+    local verify_exit=0
+    run_verification "$story" 2>&1 | tee "$verify_log" || verify_exit=$?
+    if [[ $verify_exit -eq 0 ]]; then
       # Mark story as complete and reset retry count
       update_json "$RALPH_DIR/prd.json" \
         --arg id "$story" '(.stories[] | select(.id==$id)) |= . + {passes: true, retryCount: 0}'
@@ -895,8 +1352,19 @@ run_loop() {
       # If running specific story, we're done
       [[ -n "$specific_story" ]] && return 0
     else
-      log_progress "$story" "FAILED" "Verification failed, will retry"
-      print_warning "Verification failed for $story, iterating..."
+      # Show which step failed so users can diagnose stuck loops
+      local failed_at=""
+      if [[ -f "$verify_log" ]]; then
+        # Strip ANSI codes before searching (print_error adds color)
+        failed_at=$(sed 's/\x1b\[[0-9;]*m//g' "$verify_log" | grep -o "Verification failed at: .*" | sed 's/ =*$//' | tail -1)
+      fi
+      if [[ -n "$failed_at" ]]; then
+        log_progress "$story" "FAILED" "$failed_at"
+        print_warning "$failed_at — will retry $story..."
+      else
+        log_progress "$story" "FAILED" "Verification failed, will retry"
+        print_warning "Verification failed for $story, iterating..."
+      fi
 
       # If running specific story, exit on failure
       [[ -n "$specific_story" ]] && return 1
@@ -1103,6 +1571,18 @@ build_prompt() {
     echo '```'
   fi
 
+  # Session boundaries — Ralph controls story state, not Claude
+  echo ""
+  echo "## Session Rules"
+  echo ""
+  echo "- **When done implementing, stop.** Ralph runs verification (lint, tests, build) after your session and marks the story."
+  echo "- **Don't edit prd.json** — Ralph manages story state. Any changes to passes/retryCount/skipped are reset before verification."
+  echo "- **If blocked**, write the reason and stop:"
+  echo '  ```'
+  echo '  echo "BLOCKED: [describe the issue]" > .ralph/.blocked'
+  echo '  ```'
+  echo "  Ralph will stop the loop so the issue can be resolved."
+
   # Signs are critical - always inject to prevent repeated mistakes
   _inject_signs
 }
@@ -1220,6 +1700,6 @@ archive_feature() {
   echo "All stories passed! PRD kept at: $RALPH_DIR/prd.json"
   echo ""
   echo "Next:"
-  echo "  /idea 'new feature'     # Add more stories (will append)"
+  echo "  Start a Claude Code session and run /idea to brainstorm your next feature."
   echo "  ralph status            # See completed stories"
 }