bmalph 1.0.0

package/ralph/lib/response_analyzer.sh

@@ -0,0 +1,768 @@
+#!/bin/bash
+# Response Analyzer Component for Ralph
+# Analyzes Claude Code output to detect completion signals, test-only loops, and progress
+
+# Source date utilities for cross-platform compatibility
+source "$(dirname "${BASH_SOURCE[0]}")/date_utils.sh"
+
+# Response Analysis Functions
+# Based on expert recommendations from Martin Fowler, Michael Nygard, Sam Newman
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Use RALPH_DIR if set by main script, otherwise default to .ralph
+RALPH_DIR="${RALPH_DIR:-.ralph}"
+
+# Analysis configuration
+COMPLETION_KEYWORDS=("done" "complete" "finished" "all tasks complete" "project complete" "ready for review")
+TEST_ONLY_PATTERNS=("npm test" "bats" "pytest" "jest" "cargo test" "go test" "running tests")
+NO_WORK_PATTERNS=("nothing to do" "no changes" "already implemented" "up to date")
+
+# =============================================================================
+# JSON OUTPUT FORMAT DETECTION AND PARSING
+# =============================================================================
+
+# Detect output format (json or text)
+# Returns: "json" if valid JSON, "text" otherwise
+detect_output_format() {
+    local output_file=$1
+
+    if [[ ! -f "$output_file" ]] || [[ ! -s "$output_file" ]]; then
+        echo "text"
+        return
+    fi
+
+    # Check if file starts with { or [ (JSON indicators)
+    local first_char=$(head -c 1 "$output_file" 2>/dev/null | tr -d '[:space:]')
+
+    if [[ "$first_char" != "{" && "$first_char" != "[" ]]; then
+        echo "text"
+        return
+    fi
+
+    # Validate as JSON using jq
+    if jq empty "$output_file" 2>/dev/null; then
+        echo "json"
+    else
+        echo "text"
+    fi
+}
+
+# Parse JSON response and extract structured fields
+# Creates .ralph/.json_parse_result with normalized analysis data
+# Supports THREE JSON formats:
+# 1. Flat format: { status, exit_signal, work_type, files_modified, ... }
+# 2. Claude CLI object format: { result, sessionId, metadata: { files_changed, has_errors, completion_status, ... } }
+# 3. Claude CLI array format: [ {type: "system", ...}, {type: "assistant", ...}, {type: "result", ...} ]
+parse_json_response() {
+    local output_file=$1
+    local result_file="${2:-$RALPH_DIR/.json_parse_result}"
+    local normalized_file=""
+
+    if [[ ! -f "$output_file" ]]; then
+        echo "ERROR: Output file not found: $output_file" >&2
+        return 1
+    fi
+
+    # Validate JSON first
+    if ! jq empty "$output_file" 2>/dev/null; then
+        echo "ERROR: Invalid JSON in output file" >&2
+        return 1
+    fi
+
+    # Check if JSON is an array (Claude CLI array format)
+    # Claude CLI outputs: [{type: "system", ...}, {type: "assistant", ...}, {type: "result", ...}]
+    if jq -e 'type == "array"' "$output_file" >/dev/null 2>&1; then
+        normalized_file=$(mktemp)
+
+        # Extract the "result" type message from the array (usually the last entry)
+        # This contains: result, session_id, is_error, duration_ms, etc.
+        local result_obj=$(jq '[.[] | select(.type == "result")] | .[-1] // {}' "$output_file" 2>/dev/null)
+
+        # Guard against empty result_obj if jq fails (review fix: Macroscope)
+        [[ -z "$result_obj" ]] && result_obj="{}"
+
+        # Extract session_id from init message as fallback
+        local init_session_id=$(jq -r '.[] | select(.type == "system" and .subtype == "init") | .session_id // empty' "$output_file" 2>/dev/null | head -1)
+
+        # Prioritize result object's own session_id, then fall back to init message (review fix: CodeRabbit)
+        # This prevents session ID loss when arrays lack an init message with session_id
+        local effective_session_id
+        effective_session_id=$(echo "$result_obj" | jq -r '.sessionId // .session_id // empty' 2>/dev/null)
+        if [[ -z "$effective_session_id" || "$effective_session_id" == "null" ]]; then
+            effective_session_id="$init_session_id"
+        fi
+
+        # Build normalized object merging result with effective session_id
+        if [[ -n "$effective_session_id" && "$effective_session_id" != "null" ]]; then
+            echo "$result_obj" | jq --arg sid "$effective_session_id" '. + {sessionId: $sid} | del(.session_id)' > "$normalized_file"
+        else
+            echo "$result_obj" | jq 'del(.session_id)' > "$normalized_file"
+        fi
+
+        # Use normalized file for subsequent parsing
+        output_file="$normalized_file"
+    fi
+
+    # Detect JSON format by checking for Claude CLI fields
+    local has_result_field=$(jq -r 'has("result")' "$output_file" 2>/dev/null)
+
+    # Extract fields - support both flat format and Claude CLI format
+    # Priority: Claude CLI fields first, then flat format fields
+
+    # Status: from flat format OR derived from metadata.completion_status
+    local status=$(jq -r '.status // "UNKNOWN"' "$output_file" 2>/dev/null)
+    local completion_status=$(jq -r '.metadata.completion_status // ""' "$output_file" 2>/dev/null)
+    if [[ "$completion_status" == "complete" || "$completion_status" == "COMPLETE" ]]; then
+        status="COMPLETE"
+    fi
+
+    # Exit signal: from flat format OR derived from completion_status
+    local exit_signal=$(jq -r '.exit_signal // false' "$output_file" 2>/dev/null)
+
+    # Bug #1 Fix: If exit_signal is still false, check for RALPH_STATUS block in .result field
+    # Claude CLI JSON format embeds the RALPH_STATUS block within the .result text field
+    if [[ "$exit_signal" == "false" && "$has_result_field" == "true" ]]; then
+        local result_text=$(jq -r '.result // ""' "$output_file" 2>/dev/null)
+        if [[ -n "$result_text" ]] && echo "$result_text" | grep -q -- "---RALPH_STATUS---"; then
+            # Extract EXIT_SIGNAL value from RALPH_STATUS block within result text
+            local embedded_exit_sig=$(echo "$result_text" | grep "EXIT_SIGNAL:" | cut -d: -f2 | xargs)
+            if [[ "$embedded_exit_sig" == "true" ]]; then
+                exit_signal="true"
+                [[ "${VERBOSE_PROGRESS:-}" == "true" ]] && echo "DEBUG: Extracted EXIT_SIGNAL=true from .result RALPH_STATUS block" >&2
+            fi
+            # Also check STATUS field as fallback
+            local embedded_status=$(echo "$result_text" | grep "STATUS:" | cut -d: -f2 | xargs)
+            if [[ "$embedded_status" == "COMPLETE" && "$exit_signal" != "true" ]]; then
+                # STATUS: COMPLETE without explicit EXIT_SIGNAL implies completion
+                exit_signal="true"
+                [[ "${VERBOSE_PROGRESS:-}" == "true" ]] && echo "DEBUG: Inferred EXIT_SIGNAL=true from .result STATUS=COMPLETE" >&2
+            fi
+        fi
+    fi
+
+    # Work type: from flat format
+    local work_type=$(jq -r '.work_type // "UNKNOWN"' "$output_file" 2>/dev/null)
+
+    # Files modified: from flat format OR from metadata.files_changed
+    local files_modified=$(jq -r '.metadata.files_changed // .files_modified // 0' "$output_file" 2>/dev/null)
+
+    # Error count: from flat format OR derived from metadata.has_errors
+    # Note: When only has_errors=true is present (without explicit error_count),
+    # we set error_count=1 as a minimum. This is defensive programming since
+    # the stuck detection threshold is >5 errors, so 1 error won't trigger it.
+    # Actual error count may be higher, but precise count isn't critical for our logic.
+    local error_count=$(jq -r '.error_count // 0' "$output_file" 2>/dev/null)
+    local has_errors=$(jq -r '.metadata.has_errors // false' "$output_file" 2>/dev/null)
+    if [[ "$has_errors" == "true" && "$error_count" == "0" ]]; then
+        error_count=1  # At least one error if has_errors is true
+    fi
+
+    # Summary: from flat format OR from result field (Claude CLI format)
+    local summary=$(jq -r '.result // .summary // ""' "$output_file" 2>/dev/null)
+
+    # Session ID: from Claude CLI format (sessionId) OR from metadata.session_id
+    local session_id=$(jq -r '.sessionId // .metadata.session_id // ""' "$output_file" 2>/dev/null)
+
+    # Loop number: from metadata
+    local loop_number=$(jq -r '.metadata.loop_number // .loop_number // 0' "$output_file" 2>/dev/null)
+
+    # Confidence: from flat format
+    local confidence=$(jq -r '.confidence // 0' "$output_file" 2>/dev/null)
+
+    # Progress indicators: from Claude CLI metadata (optional)
+    local progress_count=$(jq -r '.metadata.progress_indicators | if . then length else 0 end' "$output_file" 2>/dev/null)
+
+    # Normalize values
+    # Convert exit_signal to boolean string
+    if [[ "$exit_signal" == "true" || "$status" == "COMPLETE" || "$completion_status" == "complete" || "$completion_status" == "COMPLETE" ]]; then
+        exit_signal="true"
+    else
+        exit_signal="false"
+    fi
+
+    # Determine is_test_only from work_type
+    local is_test_only="false"
+    if [[ "$work_type" == "TEST_ONLY" ]]; then
+        is_test_only="true"
+    fi
+
+    # Determine is_stuck from error_count (threshold >5)
+    local is_stuck="false"
+    error_count=$((error_count + 0))  # Ensure integer
+    if [[ $error_count -gt 5 ]]; then
+        is_stuck="true"
+    fi
+
+    # Ensure files_modified is integer
+    files_modified=$((files_modified + 0))
+
+    # Ensure progress_count is integer
+    progress_count=$((progress_count + 0))
+
+    # Calculate has_completion_signal
+    local has_completion_signal="false"
+    if [[ "$status" == "COMPLETE" || "$exit_signal" == "true" ]]; then
+        has_completion_signal="true"
+    fi
+
+    # Boost confidence based on structured data availability
+    if [[ "$has_result_field" == "true" ]]; then
+        confidence=$((confidence + 20))  # Structured response boost
+    fi
+    if [[ $progress_count -gt 0 ]]; then
+        confidence=$((confidence + progress_count * 5))  # Progress indicators boost
+    fi
+
+    # Write normalized result using jq for safe JSON construction
+    # String fields use --arg (auto-escapes), numeric/boolean use --argjson
+    jq -n \
+        --arg status "$status" \
+        --argjson exit_signal "$exit_signal" \
+        --argjson is_test_only "$is_test_only" \
+        --argjson is_stuck "$is_stuck" \
+        --argjson has_completion_signal "$has_completion_signal" \
+        --argjson files_modified "$files_modified" \
+        --argjson error_count "$error_count" \
+        --arg summary "$summary" \
+        --argjson loop_number "$loop_number" \
+        --arg session_id "$session_id" \
+        --argjson confidence "$confidence" \
+        '{
+            status: $status,
+            exit_signal: $exit_signal,
+            is_test_only: $is_test_only,
+            is_stuck: $is_stuck,
+            has_completion_signal: $has_completion_signal,
+            files_modified: $files_modified,
+            error_count: $error_count,
+            summary: $summary,
+            loop_number: $loop_number,
+            session_id: $session_id,
+            confidence: $confidence,
+            metadata: {
+                loop_number: $loop_number,
+                session_id: $session_id
+            }
+        }' > "$result_file"
+
+    # Cleanup temporary normalized file if created (for array format handling)
+    if [[ -n "$normalized_file" && -f "$normalized_file" ]]; then
+        rm -f "$normalized_file"
+    fi
+
+    return 0
+}
+
+# Analyze Claude Code response and extract signals
+analyze_response() {
+    local output_file=$1
+    local loop_number=$2
+    local analysis_result_file=${3:-"$RALPH_DIR/.response_analysis"}
+
+    # Initialize analysis result
+    local has_completion_signal=false
+    local is_test_only=false
+    local is_stuck=false
+    local has_progress=false
+    local confidence_score=0
+    local exit_signal=false
+    local work_summary=""
+    local files_modified=0
+
+    # Read output file
+    if [[ ! -f "$output_file" ]]; then
+        echo "ERROR: Output file not found: $output_file"
+        return 1
+    fi
+
+    local output_content=$(cat "$output_file")
+    local output_length=${#output_content}
+
+    # Detect output format and try JSON parsing first
+    local output_format=$(detect_output_format "$output_file")
+
+    if [[ "$output_format" == "json" ]]; then
+        # Try JSON parsing
+        if parse_json_response "$output_file" "$RALPH_DIR/.json_parse_result" 2>/dev/null; then
+            # Extract values from JSON parse result
+            has_completion_signal=$(jq -r '.has_completion_signal' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "false")
+            exit_signal=$(jq -r '.exit_signal' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "false")
+            is_test_only=$(jq -r '.is_test_only' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "false")
+            is_stuck=$(jq -r '.is_stuck' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "false")
+            work_summary=$(jq -r '.summary' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "")
+            files_modified=$(jq -r '.files_modified' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "0")
+            local json_confidence=$(jq -r '.confidence' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "0")
+            local session_id=$(jq -r '.session_id' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "")
+
+            # Persist session ID if present (for session continuity across loop iterations)
+            if [[ -n "$session_id" && "$session_id" != "null" ]]; then
+                store_session_id "$session_id"
+                [[ "${VERBOSE_PROGRESS:-}" == "true" ]] && echo "DEBUG: Persisted session ID: $session_id" >&2
+            fi
+
+            # JSON parsing provides high confidence
+            if [[ "$exit_signal" == "true" ]]; then
+                confidence_score=100
+            else
+                confidence_score=$((json_confidence + 50))
+            fi
+
+            # Check for file changes via git (supplements JSON data)
+            if command -v git &>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
+                local git_files=$(git diff --name-only 2>/dev/null | wc -l)
+                if [[ $git_files -gt 0 ]]; then
+                    has_progress=true
+                    files_modified=$git_files
+                fi
+            fi
+
+            # Write analysis results for JSON path using jq for safe construction
+            jq -n \
+                --argjson loop_number "$loop_number" \
+                --arg timestamp "$(get_iso_timestamp)" \
+                --arg output_file "$output_file" \
+                --arg output_format "json" \
+                --argjson has_completion_signal "$has_completion_signal" \
+                --argjson is_test_only "$is_test_only" \
+                --argjson is_stuck "$is_stuck" \
+                --argjson has_progress "$has_progress" \
+                --argjson files_modified "$files_modified" \
+                --argjson confidence_score "$confidence_score" \
+                --argjson exit_signal "$exit_signal" \
+                --arg work_summary "$work_summary" \
+                --argjson output_length "$output_length" \
+                '{
+                    loop_number: $loop_number,
+                    timestamp: $timestamp,
+                    output_file: $output_file,
+                    output_format: $output_format,
+                    analysis: {
+                        has_completion_signal: $has_completion_signal,
+                        is_test_only: $is_test_only,
+                        is_stuck: $is_stuck,
+                        has_progress: $has_progress,
+                        files_modified: $files_modified,
+                        confidence_score: $confidence_score,
+                        exit_signal: $exit_signal,
+                        work_summary: $work_summary,
+                        output_length: $output_length
+                    }
+                }' > "$analysis_result_file"
+            rm -f "$RALPH_DIR/.json_parse_result"
+            return 0
+        fi
+        # If JSON parsing failed, fall through to text parsing
+    fi
+
+    # Text parsing fallback (original logic)
+
+    # Track whether an explicit EXIT_SIGNAL was found in RALPH_STATUS block
+    # If explicit signal found, heuristics should NOT override Claude's intent
+    local explicit_exit_signal_found=false
+
+    # 1. Check for explicit structured output (if Claude follows schema)
+    if grep -q -- "---RALPH_STATUS---" "$output_file"; then
+        # Parse structured output
+        local status=$(grep "STATUS:" "$output_file" | cut -d: -f2 | xargs)
+        local exit_sig=$(grep "EXIT_SIGNAL:" "$output_file" | cut -d: -f2 | xargs)
+
+        # If EXIT_SIGNAL is explicitly provided, respect it
+        if [[ -n "$exit_sig" ]]; then
+            explicit_exit_signal_found=true
+            if [[ "$exit_sig" == "true" ]]; then
+                has_completion_signal=true
+                exit_signal=true
+                confidence_score=100
+            else
+                # Explicit EXIT_SIGNAL: false - Claude says to continue
+                exit_signal=false
+            fi
+        elif [[ "$status" == "COMPLETE" ]]; then
+            # No explicit EXIT_SIGNAL but STATUS is COMPLETE
+            has_completion_signal=true
+            exit_signal=true
+            confidence_score=100
+        fi
+    fi
+
+    # 2. Detect completion keywords in natural language output
+    for keyword in "${COMPLETION_KEYWORDS[@]}"; do
+        if grep -qi "$keyword" "$output_file"; then
+            has_completion_signal=true
+            ((confidence_score+=10))
+            break
+        fi
+    done
+
+    # 3. Detect test-only loops
+    local test_command_count=0
+    local implementation_count=0
+    local error_count=0
+
+    test_command_count=$(grep -c -i "running tests\|npm test\|bats\|pytest\|jest" "$output_file" 2>/dev/null | head -1 || echo "0")
+    implementation_count=$(grep -c -i "implementing\|creating\|writing\|adding\|function\|class" "$output_file" 2>/dev/null | head -1 || echo "0")
+
+    # Strip whitespace and ensure it's a number
+    test_command_count=$(echo "$test_command_count" | tr -d '[:space:]')
+    implementation_count=$(echo "$implementation_count" | tr -d '[:space:]')
+
+    # Convert to integers with default fallback
+    test_command_count=${test_command_count:-0}
+    implementation_count=${implementation_count:-0}
+    test_command_count=$((test_command_count + 0))
+    implementation_count=$((implementation_count + 0))
+
+    if [[ $test_command_count -gt 0 ]] && [[ $implementation_count -eq 0 ]]; then
+        is_test_only=true
+        work_summary="Test execution only, no implementation"
+    fi
+
+    # 4. Detect stuck/error loops
+    # Use two-stage filtering to avoid counting JSON field names as errors
+    # Stage 1: Filter out JSON field patterns like "is_error": false
+    # Stage 2: Count actual error messages in specific contexts
+    # Pattern aligned with ralph_loop.sh to ensure consistent behavior
+    error_count=$(grep -v '"[^"]*error[^"]*":' "$output_file" 2>/dev/null | \
+                  grep -cE '(^Error:|^ERROR:|^error:|\]: error|Link: error|Error occurred|failed with error|[Ee]xception|Fatal|FATAL)' \
+                  2>/dev/null || echo "0")
+    error_count=$(echo "$error_count" | tr -d '[:space:]')
+    error_count=${error_count:-0}
+    error_count=$((error_count + 0))
+
+    if [[ $error_count -gt 5 ]]; then
+        is_stuck=true
+    fi
+
+    # 5. Detect "nothing to do" patterns
+    for pattern in "${NO_WORK_PATTERNS[@]}"; do
+        if grep -qi "$pattern" "$output_file"; then
+            has_completion_signal=true
+            ((confidence_score+=15))
+            work_summary="No work remaining"
+            break
+        fi
+    done
+
+    # 6. Check for file changes (git integration)
+    if command -v git &>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
+        files_modified=$(git diff --name-only 2>/dev/null | wc -l)
+        if [[ $files_modified -gt 0 ]]; then
+            has_progress=true
+            ((confidence_score+=20))
+        fi
+    fi
+
+    # 7. Analyze output length trends (detect declining engagement)
+    if [[ -f "$RALPH_DIR/.last_output_length" ]]; then
+        local last_length=$(cat "$RALPH_DIR/.last_output_length")
+        local length_ratio=$((output_length * 100 / last_length))
+
+        if [[ $length_ratio -lt 50 ]]; then
+            # Output is less than 50% of previous - possible completion
+            ((confidence_score+=10))
+        fi
+    fi
+    echo "$output_length" > "$RALPH_DIR/.last_output_length"
+
+    # 8. Extract work summary from output
+    if [[ -z "$work_summary" ]]; then
+        # Try to find summary in output
+        work_summary=$(grep -i "summary\|completed\|implemented" "$output_file" | head -1 | cut -c 1-100)
+        if [[ -z "$work_summary" ]]; then
+            work_summary="Output analyzed, no explicit summary found"
+        fi
+    fi
+
+    # 9. Determine exit signal based on confidence (heuristic)
+    # IMPORTANT: Only apply heuristics if no explicit EXIT_SIGNAL was found in RALPH_STATUS
+    # Claude's explicit intent takes precedence over natural language pattern matching
+    if [[ "$explicit_exit_signal_found" != "true" ]]; then
+        if [[ $confidence_score -ge 40 || "$has_completion_signal" == "true" ]]; then
+            exit_signal=true
+        fi
+    fi
+
+    # Write analysis results to file (text parsing path) using jq for safe construction
+    jq -n \
+        --argjson loop_number "$loop_number" \
+        --arg timestamp "$(get_iso_timestamp)" \
+        --arg output_file "$output_file" \
+        --arg output_format "text" \
+        --argjson has_completion_signal "$has_completion_signal" \
+        --argjson is_test_only "$is_test_only" \
+        --argjson is_stuck "$is_stuck" \
+        --argjson has_progress "$has_progress" \
+        --argjson files_modified "$files_modified" \
+        --argjson confidence_score "$confidence_score" \
+        --argjson exit_signal "$exit_signal" \
+        --arg work_summary "$work_summary" \
+        --argjson output_length "$output_length" \
+        '{
+            loop_number: $loop_number,
+            timestamp: $timestamp,
+            output_file: $output_file,
+            output_format: $output_format,
+            analysis: {
+                has_completion_signal: $has_completion_signal,
+                is_test_only: $is_test_only,
+                is_stuck: $is_stuck,
+                has_progress: $has_progress,
+                files_modified: $files_modified,
+                confidence_score: $confidence_score,
+                exit_signal: $exit_signal,
+                work_summary: $work_summary,
+                output_length: $output_length
+            }
+        }' > "$analysis_result_file"
+
+    # Always return 0 (success) - callers should check the JSON result file
+    # Returning non-zero would cause issues with set -e and test frameworks
+    return 0
+}
+
+# Update exit signals file based on analysis
+update_exit_signals() {
+    local analysis_file=${1:-"$RALPH_DIR/.response_analysis"}
+    local exit_signals_file=${2:-"$RALPH_DIR/.exit_signals"}
+
+    if [[ ! -f "$analysis_file" ]]; then
+        echo "ERROR: Analysis file not found: $analysis_file"
+        return 1
+    fi
+
+    # Read analysis results
+    local is_test_only=$(jq -r '.analysis.is_test_only' "$analysis_file")
+    local has_completion_signal=$(jq -r '.analysis.has_completion_signal' "$analysis_file")
+    local loop_number=$(jq -r '.loop_number' "$analysis_file")
+    local has_progress=$(jq -r '.analysis.has_progress' "$analysis_file")
+
+    # Read current exit signals
+    local signals=$(cat "$exit_signals_file" 2>/dev/null || echo '{"test_only_loops": [], "done_signals": [], "completion_indicators": []}')
+
+    # Update test_only_loops array
+    if [[ "$is_test_only" == "true" ]]; then
+        signals=$(echo "$signals" | jq ".test_only_loops += [$loop_number]")
+    else
+        # Clear test_only_loops if we had implementation
+        if [[ "$has_progress" == "true" ]]; then
+            signals=$(echo "$signals" | jq '.test_only_loops = []')
+        fi
+    fi
+
+    # Update done_signals array
+    if [[ "$has_completion_signal" == "true" ]]; then
+        signals=$(echo "$signals" | jq ".done_signals += [$loop_number]")
+    fi
+
+    # Update completion_indicators array (strong signals)
+    local confidence=$(jq -r '.analysis.confidence_score' "$analysis_file")
+    if [[ $confidence -ge 60 ]]; then
+        signals=$(echo "$signals" | jq ".completion_indicators += [$loop_number]")
+    fi
+
+    # Keep only last 5 signals (rolling window)
+    signals=$(echo "$signals" | jq '.test_only_loops = .test_only_loops[-5:]')
+    signals=$(echo "$signals" | jq '.done_signals = .done_signals[-5:]')
+    signals=$(echo "$signals" | jq '.completion_indicators = .completion_indicators[-5:]')
+
+    # Write updated signals
+    echo "$signals" > "$exit_signals_file"
+
+    return 0
+}
+
+# Log analysis results in human-readable format
+log_analysis_summary() {
+    local analysis_file=${1:-"$RALPH_DIR/.response_analysis"}
+
+    if [[ ! -f "$analysis_file" ]]; then
+        return 1
+    fi
+
+    local loop=$(jq -r '.loop_number' "$analysis_file")
+    local exit_sig=$(jq -r '.analysis.exit_signal' "$analysis_file")
+    local confidence=$(jq -r '.analysis.confidence_score' "$analysis_file")
+    local test_only=$(jq -r '.analysis.is_test_only' "$analysis_file")
+    local files_changed=$(jq -r '.analysis.files_modified' "$analysis_file")
+    local summary=$(jq -r '.analysis.work_summary' "$analysis_file")
+
+    echo -e "${BLUE}╔════════════════════════════════════════════════════════════╗${NC}"
+    echo -e "${BLUE}║           Response Analysis - Loop #$loop                 ║${NC}"
+    echo -e "${BLUE}╚════════════════════════════════════════════════════════════╝${NC}"
+    echo -e "${YELLOW}Exit Signal:${NC}      $exit_sig"
+    echo -e "${YELLOW}Confidence:${NC}       $confidence%"
+    echo -e "${YELLOW}Test Only:${NC}        $test_only"
+    echo -e "${YELLOW}Files Changed:${NC}    $files_changed"
+    echo -e "${YELLOW}Summary:${NC}          $summary"
+    echo ""
+}
+
+# Detect if Claude is stuck (repeating same errors)
+detect_stuck_loop() {
+    local current_output=$1
+    local history_dir=${2:-"$RALPH_DIR/logs"}
+
+    # Get last 3 output files
+    local recent_outputs=$(ls -t "$history_dir"/claude_output_*.log 2>/dev/null | head -3)
+
+    if [[ -z "$recent_outputs" ]]; then
+        return 1  # Not enough history
+    fi
+
+    # Extract key errors from current output using two-stage filtering
+    # Stage 1: Filter out JSON field patterns to avoid false positives
+    # Stage 2: Extract actual error messages
+    local current_errors=$(grep -v '"[^"]*error[^"]*":' "$current_output" 2>/dev/null | \
+                          grep -E '(^Error:|^ERROR:|^error:|\]: error|Link: error|Error occurred|failed with error|[Ee]xception|Fatal|FATAL)' 2>/dev/null | \
+                          sort | uniq)
+
+    if [[ -z "$current_errors" ]]; then
+        return 1  # No errors
+    fi
+
+    # Check if same errors appear in all recent outputs
+    # For multi-line errors, verify ALL error lines appear in ALL history files
+    local all_files_match=true
+    while IFS= read -r output_file; do
+        local file_matches_all=true
+        while IFS= read -r error_line; do
+            # Use -F for literal fixed-string matching (not regex)
+            if ! grep -qF "$error_line" "$output_file" 2>/dev/null; then
+                file_matches_all=false
+                break
+            fi
+        done <<< "$current_errors"
+
+        if [[ "$file_matches_all" != "true" ]]; then
+            all_files_match=false
+            break
+        fi
+    done <<< "$recent_outputs"
+
+    if [[ "$all_files_match" == "true" ]]; then
+        return 0  # Stuck on same error(s)
+    else
+        return 1  # Making progress or different errors
+    fi
+}
+
+# =============================================================================
+# SESSION MANAGEMENT FUNCTIONS
+# =============================================================================
+
+# Session file location - standardized across ralph_loop.sh and response_analyzer.sh
+SESSION_FILE="$RALPH_DIR/.claude_session_id"
+# Session expiration time in seconds (24 hours)
+SESSION_EXPIRATION_SECONDS=86400
+
+# Store session ID to file with timestamp
+# Usage: store_session_id "session-uuid-123"
+store_session_id() {
+    local session_id=$1
+
+    if [[ -z "$session_id" ]]; then
+        return 1
+    fi
+
+    # Write session with timestamp using jq for safe JSON construction
+    jq -n \
+        --arg session_id "$session_id" \
+        --arg timestamp "$(get_iso_timestamp)" \
+        '{
+            session_id: $session_id,
+            timestamp: $timestamp
+        }' > "$SESSION_FILE"
+
+    return 0
+}
+
+# Get the last stored session ID
+# Returns: session ID string or empty if not found
+get_last_session_id() {
+    if [[ ! -f "$SESSION_FILE" ]]; then
+        echo ""
+        return 0
+    fi
+
+    # Extract session_id from JSON file
+    local session_id=$(jq -r '.session_id // ""' "$SESSION_FILE" 2>/dev/null)
+    echo "$session_id"
+    return 0
+}
+
+# Check if the stored session should be resumed
+# Returns: 0 (true) if session is valid and recent, 1 (false) otherwise
+should_resume_session() {
+    if [[ ! -f "$SESSION_FILE" ]]; then
+        echo "false"
+        return 1
+    fi
+
+    # Get session timestamp
+    local timestamp=$(jq -r '.timestamp // ""' "$SESSION_FILE" 2>/dev/null)
+
+    if [[ -z "$timestamp" ]]; then
+        echo "false"
+        return 1
+    fi
+
+    # Calculate session age using date utilities
+    local now=$(get_epoch_seconds)
+    local session_time
+
+    # Parse ISO timestamp to epoch - try multiple formats for cross-platform compatibility
+    # Strip milliseconds if present (e.g., 2026-01-09T10:30:00.123+00:00 → 2026-01-09T10:30:00+00:00)
+    local clean_timestamp="${timestamp}"
+    if [[ "$timestamp" =~ \.[0-9]+[+-Z] ]]; then
+        clean_timestamp=$(echo "$timestamp" | sed 's/\.[0-9]*\([+-Z]\)/\1/')
+    fi
+
+    if command -v gdate &>/dev/null; then
+        # macOS with coreutils
+        session_time=$(gdate -d "$clean_timestamp" +%s 2>/dev/null)
+    elif date --version 2>&1 | grep -q GNU; then
+        # GNU date (Linux)
+        session_time=$(date -d "$clean_timestamp" +%s 2>/dev/null)
+    else
+        # BSD date (macOS without coreutils) - try parsing ISO format
+        # Format: 2026-01-09T10:30:00+00:00 or 2026-01-09T10:30:00Z
+        # Strip timezone suffix for BSD date parsing
+        local date_only="${clean_timestamp%[+-Z]*}"
+        session_time=$(date -j -f "%Y-%m-%dT%H:%M:%S" "$date_only" +%s 2>/dev/null)
+    fi
+
+    # If we couldn't parse the timestamp, consider session expired
+    if [[ -z "$session_time" || ! "$session_time" =~ ^[0-9]+$ ]]; then
+        echo "false"
+        return 1
+    fi
+
+    # Calculate age in seconds
+    local age=$((now - session_time))
+
+    # Check if session is still valid (less than expiration time)
+    if [[ $age -lt $SESSION_EXPIRATION_SECONDS ]]; then
+        echo "true"
+        return 0
+    else
+        echo "false"
+        return 1
+    fi
+}
+
+# Export functions for use in ralph_loop.sh
+export -f detect_output_format
+export -f parse_json_response
+export -f analyze_response
+export -f update_exit_signals
+export -f log_analysis_summary
+export -f detect_stuck_loop
+export -f store_session_id
+export -f get_last_session_id
+export -f should_resume_session