feat(session): add session lifecycle management with auto-reset triggers

- Add session management functions: get_session_id(), reset_session(),
  log_session_transition(), init_session_tracking()
- Session auto-reset on: circuit breaker open, manual interrupt,
  project completion, manual circuit reset
- Add --reset-session CLI flag for manual session reset
- Add session history tracking (.ralph_session_history, last 50 entries)
- New config: RALPH_SESSION_FILE, RALPH_SESSION_HISTORY_FILE
- Add 26 comprehensive tests for session continuity (TDD)
- All 265 tests pass (up from 239)
- Update CLAUDE.md with v0.9.7 release notes

Author: Test User

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 This is the Ralph for Claude Code repository - an autonomous AI development loop system that enables continuous development cycles with intelligent exit detection and rate limiting.
 
-**Version**: v0.9.6 | **Tests**: 239 passing (100% pass rate) | **CI/CD**: GitHub Actions
+**Version**: v0.9.7 | **Tests**: 265 passing (100% pass rate) | **CI/CD**: GitHub Actions
 
 ## Core Architecture
 
@@ -37,6 +37,9 @@ The system uses a modular architecture with reusable components in the `lib/` di
    - Extracts structured fields: status, exit_signal, work_type, files_modified
    - **Session management**: `store_session_id()`, `get_last_session_id()`, `should_resume_session()`
    - Automatic session persistence to `.claude_session_id` file with 24-hour expiration
+   - Session lifecycle: `get_session_id()`, `reset_session()`, `log_session_transition()`, `init_session_tracking()`
+   - Session history tracked in `.ralph_session_history` (last 50 transitions)
+   - Session auto-reset on: circuit breaker open, manual interrupt, project completion
    - Detects test-only loops and stuck error patterns
    - Two-stage error filtering to eliminate false positives
    - Multi-line error matching for accurate stuck loop detection
@@ -81,6 +84,9 @@ ralph --status
 # Circuit breaker management
 ralph --reset-circuit
 ralph --circuit-status
+
+# Session management
+ralph --reset-session    # Reset session state manually
 ```
 
 ### Monitoring
@@ -275,13 +281,14 @@ Ralph uses advanced error detection with two-stage filtering to eliminate false
 
 ## Test Suite
 
-### Test Files (239 tests total)
+### Test Files (265 tests total)
 
 | File | Tests | Description |
 |------|-------|-------------|
 | `test_cli_parsing.bats` | 27 | CLI argument parsing for all 12 flags |
 | `test_cli_modern.bats` | 29 | Modern CLI commands (Phase 1.1) + build_claude_command fix |
 | `test_json_parsing.bats` | 36 | JSON output format parsing + Claude CLI format + session management |
+| `test_session_continuity.bats` | 26 | Session lifecycle management + circuit breaker integration |
 | `test_exit_detection.bats` | 20 | Exit signal detection |
 | `test_rate_limiting.bats` | 15 | Rate limiting behavior |
 | `test_loop_execution.bats` | 20 | Integration tests |
@@ -304,6 +311,23 @@ bats tests/unit/test_cli_parsing.bats
 
 ## Recent Improvements
 
+### Session Lifecycle Management (v0.9.7)
+- Added complete session lifecycle management with automatic reset triggers:
+  - `get_session_id()` - Retrieves current session from `.ralph_session`
+  - `reset_session(reason)` - Clears session with reason logging
+  - `log_session_transition()` - Records transitions to `.ralph_session_history`
+  - `init_session_tracking()` - Initializes session file with validation
+- Session auto-reset integration points:
+  - Circuit breaker open events (stagnation detection)
+  - Manual interrupt (Ctrl+C / SIGINT)
+  - Project completion (graceful exit)
+  - Manual circuit breaker reset (`--reset-circuit`)
+- Added `--reset-session` CLI flag for manual session reset
+- Session history tracking (last 50 transitions) for debugging
+- New configuration constants: `RALPH_SESSION_FILE`, `RALPH_SESSION_HISTORY_FILE`
+- Added 26 new tests for session continuity features
+- Test count: 265 (up from 239)
+
 ### JSON Output & Session Management (v0.9.6)
 - Extended `parse_json_response()` to support Claude Code CLI JSON format
   - Supports `result`, `sessionId`, and `metadata` fields alongside existing flat format

ralph_loop.sh

@@ -33,6 +33,11 @@ CLAUDE_USE_CONTINUE=true                 # Enable session continuity
 CLAUDE_SESSION_FILE=".claude_session_id" # Session ID persistence file
 CLAUDE_MIN_VERSION="2.0.76"              # Minimum required Claude CLI version
 
+# Session management configuration (Phase 1.2)
+RALPH_SESSION_FILE=".ralph_session"              # Ralph-specific session tracking
+RALPH_SESSION_HISTORY_FILE=".ralph_session_history"  # Session transition history
+SESSION_EXPIRATION_SECONDS=86400                 # 24 hours in seconds
+
 # Valid tool patterns for --allowed-tools validation
 # Tools can be exact matches or pattern matches with wildcards in parentheses
 VALID_TOOL_PATTERNS=(
@@ -477,6 +482,125 @@ save_claude_session() {
     fi
 }
 
+# =============================================================================
+# SESSION LIFECYCLE MANAGEMENT FUNCTIONS (Phase 1.2)
+# =============================================================================
+
+# Get current session ID from Ralph session file
+# Returns: session ID string or empty if not found
+get_session_id() {
+    if [[ ! -f "$RALPH_SESSION_FILE" ]]; then
+        echo ""
+        return 0
+    fi
+
+    # Extract session_id from JSON file
+    local session_id=$(jq -r '.session_id // ""' "$RALPH_SESSION_FILE" 2>/dev/null)
+    if [[ "$session_id" == "null" ]]; then
+        session_id=""
+    fi
+    echo "$session_id"
+    return 0
+}
+
+# Reset session with reason logging
+# Usage: reset_session "reason_for_reset"
+reset_session() {
+    local reason=${1:-"manual_reset"}
+
+    # Log the transition before clearing
+    local old_session_id=$(get_session_id)
+
+    # Clear the session file
+    if [[ -f "$RALPH_SESSION_FILE" ]]; then
+        cat > "$RALPH_SESSION_FILE" << EOF
+{
+    "session_id": "",
+    "created_at": "",
+    "last_used": "",
+    "reset_at": "$(get_iso_timestamp)",
+    "reset_reason": "$reason"
+}
+EOF
+    fi
+
+    # Also clear the Claude session file for consistency
+    if [[ -f "$CLAUDE_SESSION_FILE" ]]; then
+        rm -f "$CLAUDE_SESSION_FILE"
+    fi
+
+    # Log the session transition
+    log_session_transition "active" "reset" "$reason" "${loop_count:-0}"
+
+    log_status "INFO" "Session reset: $reason"
+}
+
+# Log session state transitions to history file
+# Usage: log_session_transition from_state to_state reason loop_number
+log_session_transition() {
+    local from_state=$1
+    local to_state=$2
+    local reason=$3
+    local loop_number=${4:-0}
+
+    # Initialize history file if needed
+    if [[ ! -f "$RALPH_SESSION_HISTORY_FILE" ]]; then
+        echo '[]' > "$RALPH_SESSION_HISTORY_FILE"
+    fi
+
+    # Create transition entry
+    local transition
+    transition=$(jq -n \
+        --arg timestamp "$(get_iso_timestamp)" \
+        --arg from_state "$from_state" \
+        --arg to_state "$to_state" \
+        --arg reason "$reason" \
+        --argjson loop_number "$loop_number" \
+        '{
+            timestamp: $timestamp,
+            from_state: $from_state,
+            to_state: $to_state,
+            reason: $reason,
+            loop_number: $loop_number
+        }')
+
+    # Append to history and keep only last 50 entries
+    local history=$(cat "$RALPH_SESSION_HISTORY_FILE" 2>/dev/null || echo '[]')
+    history=$(echo "$history" | jq ". += [$transition] | .[-50:]")
+    echo "$history" > "$RALPH_SESSION_HISTORY_FILE"
+}
+
+# Initialize session tracking (called at loop start)
+init_session_tracking() {
+    # Create session file if it doesn't exist
+    if [[ ! -f "$RALPH_SESSION_FILE" ]]; then
+        cat > "$RALPH_SESSION_FILE" << EOF
+{
+    "session_id": "",
+    "created_at": "$(get_iso_timestamp)",
+    "last_used": "",
+    "reset_at": "",
+    "reset_reason": ""
+}
+EOF
+        log_status "INFO" "Initialized session tracking"
+    fi
+
+    # Validate existing session file
+    if ! jq empty "$RALPH_SESSION_FILE" 2>/dev/null; then
+        log_status "WARN" "Corrupted session file detected, recreating..."
+        cat > "$RALPH_SESSION_FILE" << EOF
+{
+    "session_id": "",
+    "created_at": "$(get_iso_timestamp)",
+    "last_used": "",
+    "reset_at": "",
+    "reset_reason": "corrupted_file_recovery"
+}
+EOF
+    fi
+}
+
 # Global array for Claude command arguments (avoids shell injection)
 declare -a CLAUDE_CMD_ARGS=()
 
@@ -731,6 +855,7 @@ EOF
 # Cleanup function
 cleanup() {
     log_status "INFO" "Ralph loop interrupted. Cleaning up..."
+    reset_session "manual_interrupt"
     update_status "$loop_count" "$(cat "$CALL_COUNT_FILE" 2>/dev/null || echo "0")" "interrupted" "stopped"
     exit 0
 }
@@ -785,6 +910,7 @@ main() {
 
         # Check circuit breaker before attempting execution
         if should_halt_execution; then
+            reset_session "circuit_breaker_open"
             update_status "$loop_count" "$(cat "$CALL_COUNT_FILE")" "circuit_breaker_open" "halted" "stagnation_detected"
             log_status "ERROR" "🛑 Circuit breaker has opened - execution halted"
             break
@@ -800,13 +926,14 @@ main() {
         local exit_reason=$(should_exit_gracefully)
         if [[ "$exit_reason" != "" ]]; then
             log_status "SUCCESS" "🏁 Graceful exit triggered: $exit_reason"
+            reset_session "project_complete"
             update_status "$loop_count" "$(cat "$CALL_COUNT_FILE")" "graceful_exit" "completed" "$exit_reason"
-            
+
             log_status "SUCCESS" "🎉 Ralph has completed the project! Final stats:"
             log_status "INFO" "  - Total loops: $loop_count"
             log_status "INFO" "  - API calls used: $(cat "$CALL_COUNT_FILE")"
             log_status "INFO" "  - Exit reason: $exit_reason"
-            
+
             break
         fi
 
@@ -825,6 +952,7 @@ main() {
             sleep 5
         elif [ $exec_result -eq 3 ]; then
             # Circuit breaker opened
+            reset_session "circuit_breaker_trip"
             update_status "$loop_count" "$(cat "$CALL_COUNT_FILE")" "circuit_breaker_open" "halted" "stagnation_detected"
             log_status "ERROR" "🛑 Circuit breaker has opened - halting loop"
             log_status "INFO" "Run 'ralph --reset-circuit' to reset the circuit breaker after addressing issues"
@@ -896,6 +1024,7 @@ Options:
     -t, --timeout MIN       Set Claude Code execution timeout in minutes (default: $CLAUDE_TIMEOUT_MINUTES)
     --reset-circuit         Reset circuit breaker to CLOSED state
     --circuit-status        Show circuit breaker status and exit
+    --reset-session         Reset session state and exit (clears session continuity)
 
 Modern CLI Options (Phase 1.1):
     --output-format FORMAT  Set Claude output format: json or text (default: $CLAUDE_OUTPUT_FORMAT)
@@ -968,7 +1097,17 @@ while [[ $# -gt 0 ]]; do
             # Source the circuit breaker library
             SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
             source "$SCRIPT_DIR/lib/circuit_breaker.sh"
+            source "$SCRIPT_DIR/lib/date_utils.sh"
             reset_circuit_breaker "Manual reset via command line"
+            reset_session "manual_circuit_reset"
+            exit 0
+            ;;
+        --reset-session)
+            # Reset session state only
+            SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
+            source "$SCRIPT_DIR/lib/date_utils.sh"
+            reset_session "manual_reset_flag"
+            echo -e "${GREEN}✅ Session state reset successfully${NC}"
             exit 0
             ;;
         --circuit-status)