fix: harden Ralph session state recovery

Author: LarsCowe

ralph/RALPH-REFERENCE.md

@@ -97,7 +97,7 @@ This applies to every driver that exposes resumable IDs today:
 
 | File | Purpose |
 |------|---------|
-| `.ralph/.ralph_session` | Current session ID and timestamps |
+| `.ralph/.ralph_session` | Current Ralph session state (active or reset/inactive) |
 | `.ralph/.ralph_session_history` | History of last 50 session transitions |
 | `.ralph/.claude_session_id` | Persisted driver session ID (shared filename for historical reasons; used by Claude Code, Codex, and Cursor) |
 
@@ -119,13 +119,23 @@ Sessions expire after 24 hours (configurable via `SESSION_EXPIRY_HOURS` in `.ral
 
 ### Session State Structure
 
+Active session payload:
+
 ```json
 {
   "session_id": "uuid-string",
   "created_at": "ISO-timestamp",
-  "last_used": "ISO-timestamp",
-  "reset_at": "ISO-timestamp (if reset)",
-  "reset_reason": "reason string (if reset)"
+  "last_used": "ISO-timestamp"
+}
+```
+
+Reset/inactive payload:
+
+```json
+{
+  "session_id": "",
+  "reset_at": "ISO-timestamp",
+  "reset_reason": "reason string"
 }
 ```
 

ralph/lib/date_utils.sh

@@ -49,35 +49,37 @@ get_epoch_seconds() {
 # Convert ISO 8601 timestamp to Unix epoch seconds
 # Input: ISO timestamp (e.g., "2025-01-15T10:30:00+00:00")
 # Returns: Unix epoch seconds on stdout
-# Falls back to current epoch on parse failure (safe default)
-parse_iso_to_epoch() {
+# Returns non-zero on parse failure.
+parse_iso_to_epoch_strict() {
     local iso_timestamp=$1
 
     if [[ -z "$iso_timestamp" || "$iso_timestamp" == "null" ]]; then
-        date +%s
-        return
+        return 1
     fi
 
+    local normalized_iso
+    normalized_iso=$(printf '%s' "$iso_timestamp" | sed -E 's/\.([0-9]+)(Z|[+-][0-9]{2}:[0-9]{2})$/\2/')
+
     # Try GNU date -d (Linux, macOS with Homebrew coreutils)
     local result
     if result=$(date -d "$iso_timestamp" +%s 2>/dev/null) && [[ "$result" =~ ^[0-9]+$ ]]; then
         echo "$result"
-        return
+        return 0
     fi
 
     # Try BSD date -j (native macOS)
     # Normalize timezone for BSD parsing (Z → +0000, ±HH:MM → ±HHMM)
     local tz_fixed
-    tz_fixed=$(echo "$iso_timestamp" | sed -E 's/Z$/+0000/; s/([+-][0-9]{2}):([0-9]{2})$/\1\2/')
+    tz_fixed=$(printf '%s' "$normalized_iso" | sed -E 's/Z$/+0000/; s/([+-][0-9]{2}):([0-9]{2})$/\1\2/')
     if result=$(date -j -f "%Y-%m-%dT%H:%M:%S%z" "$tz_fixed" +%s 2>/dev/null) && [[ "$result" =~ ^[0-9]+$ ]]; then
         echo "$result"
-        return
+        return 0
     fi
 
     # Fallback: manual epoch arithmetic from ISO components
     # Parse: YYYY-MM-DDTHH:MM:SS (ignore timezone, assume UTC)
     local year month day hour minute second
-    if [[ "$iso_timestamp" =~ ^([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2}) ]]; then
+    if [[ "$normalized_iso" =~ ^([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2}) ]]; then
         year="${BASH_REMATCH[1]}"
         month="${BASH_REMATCH[2]}"
         day="${BASH_REMATCH[3]}"
@@ -88,10 +90,26 @@ parse_iso_to_epoch() {
         # Use date with explicit components if available
         if result=$(date -u -d "${year}-${month}-${day} ${hour}:${minute}:${second}" +%s 2>/dev/null) && [[ "$result" =~ ^[0-9]+$ ]]; then
             echo "$result"
-            return
+            return 0
         fi
     fi
 
+    return 1
+}
+
+# Convert ISO 8601 timestamp to Unix epoch seconds
+# Input: ISO timestamp (e.g., "2025-01-15T10:30:00+00:00")
+# Returns: Unix epoch seconds on stdout
+# Falls back to current epoch on parse failure (safe default)
+parse_iso_to_epoch() {
+    local iso_timestamp=$1
+    local result
+
+    if result=$(parse_iso_to_epoch_strict "$iso_timestamp"); then
+        echo "$result"
+        return 0
+    fi
+
     # Ultimate fallback: return current epoch (safe default)
     date +%s
 }
@@ -101,4 +119,5 @@ export -f get_iso_timestamp
 export -f get_next_hour_time
 export -f get_basic_timestamp
 export -f get_epoch_seconds
+export -f parse_iso_to_epoch_strict
 export -f parse_iso_to_epoch

ralph/ralph_loop.sh

@@ -1034,6 +1034,7 @@ save_claude_session() {
         session_id=$(extract_session_id_from_output "$output_file" 2>/dev/null || echo "")
         if [[ -n "$session_id" && "$session_id" != "null" ]]; then
             echo "$session_id" > "$CLAUDE_SESSION_FILE"
+            sync_ralph_session_with_driver "$session_id"
             log_status "INFO" "Saved session: ${session_id:0:20}..."
         fi
     fi
@@ -1043,6 +1044,101 @@ save_claude_session() {
 # SESSION LIFECYCLE MANAGEMENT FUNCTIONS (Phase 1.2)
 # =============================================================================
 
+write_active_ralph_session() {
+    local session_id=$1
+    local created_at=$2
+    local last_used=${3:-$created_at}
+
+    jq -n \
+        --arg session_id "$session_id" \
+        --arg created_at "$created_at" \
+        --arg last_used "$last_used" \
+        '{
+            session_id: $session_id,
+            created_at: $created_at,
+            last_used: $last_used
+        }' > "$RALPH_SESSION_FILE"
+}
+
+write_inactive_ralph_session() {
+    local reset_at=$1
+    local reset_reason=$2
+
+    jq -n \
+        --arg session_id "" \
+        --arg reset_at "$reset_at" \
+        --arg reset_reason "$reset_reason" \
+        '{
+            session_id: $session_id,
+            reset_at: $reset_at,
+            reset_reason: $reset_reason
+        }' > "$RALPH_SESSION_FILE"
+}
+
+get_ralph_session_state() {
+    if [[ ! -f "$RALPH_SESSION_FILE" ]]; then
+        echo "missing"
+        return 0
+    fi
+
+    if ! jq empty "$RALPH_SESSION_FILE" 2>/dev/null; then
+        echo "invalid"
+        return 0
+    fi
+
+    local session_id_type
+    session_id_type=$(
+        jq -r 'if has("session_id") then (.session_id | type) else "missing" end' \
+            "$RALPH_SESSION_FILE" 2>/dev/null
+    ) || {
+        echo "invalid"
+        return 0
+    }
+
+    if [[ "$session_id_type" != "string" ]]; then
+        echo "invalid"
+        return 0
+    fi
+
+    local session_id
+    session_id=$(jq -r '.session_id' "$RALPH_SESSION_FILE" 2>/dev/null) || {
+        echo "invalid"
+        return 0
+    }
+
+    if [[ "$session_id" == "" ]]; then
+        echo "inactive"
+        return 0
+    fi
+
+    local created_at_type
+    created_at_type=$(
+        jq -r 'if has("created_at") then (.created_at | type) else "missing" end' \
+            "$RALPH_SESSION_FILE" 2>/dev/null
+    ) || {
+        echo "invalid"
+        return 0
+    }
+
+    if [[ "$created_at_type" != "string" ]]; then
+        echo "invalid"
+        return 0
+    fi
+
+    local created_at
+    created_at=$(jq -r '.created_at' "$RALPH_SESSION_FILE" 2>/dev/null) || {
+        echo "invalid"
+        return 0
+    }
+
+    if ! is_usable_ralph_session_created_at "$created_at"; then
+        echo "invalid"
+        return 0
+    fi
+
+    echo "active"
+}
+
 # Get current session ID from Ralph session file
 # Returns: session ID string or empty if not found
 get_session_id() {
@@ -1064,6 +1160,65 @@ get_session_id() {
     return 0
 }
 
+is_usable_ralph_session_created_at() {
+    local created_at=$1
+    if [[ -z "$created_at" || "$created_at" == "null" ]]; then
+        return 1
+    fi
+
+    local created_at_epoch
+    created_at_epoch=$(parse_iso_to_epoch_strict "$created_at") || return 1
+
+    local now_epoch
+    now_epoch=$(get_epoch_seconds)
+
+    [[ "$created_at_epoch" -le "$now_epoch" ]]
+}
+
+get_active_session_created_at() {
+    if [[ "$(get_ralph_session_state)" != "active" ]]; then
+        echo ""
+        return 0
+    fi
+
+    local created_at
+    created_at=$(jq -r '.created_at // ""' "$RALPH_SESSION_FILE" 2>/dev/null)
+    if [[ "$created_at" == "null" ]]; then
+        created_at=""
+    fi
+
+    if ! is_usable_ralph_session_created_at "$created_at"; then
+        echo ""
+        return 0
+    fi
+
+    echo "$created_at"
+}
+
+sync_ralph_session_with_driver() {
+    local driver_session_id=$1
+    if [[ -z "$driver_session_id" || "$driver_session_id" == "null" ]]; then
+        return 0
+    fi
+
+    local ts
+    ts=$(get_iso_timestamp)
+
+    if [[ "$(get_ralph_session_state)" == "active" ]]; then
+        local current_session_id
+        current_session_id=$(get_session_id)
+        local current_created_at
+        current_created_at=$(get_active_session_created_at)
+
+        if [[ "$current_session_id" == "$driver_session_id" && -n "$current_created_at" ]]; then
+            write_active_ralph_session "$driver_session_id" "$current_created_at" "$ts"
+            return 0
+        fi
+    fi
+
+    write_active_ralph_session "$driver_session_id" "$ts" "$ts"
+}
+
 # Reset session with reason logging
 # Usage: reset_session "reason_for_reset"
 reset_session() {
@@ -1073,20 +1228,7 @@ reset_session() {
     local reset_timestamp
     reset_timestamp=$(get_iso_timestamp)
 
-    # Always create/overwrite the session file using jq for safe JSON escaping
-    jq -n \
-        --arg session_id "" \
-        --arg created_at "" \
-        --arg last_used "" \
-        --arg reset_at "$reset_timestamp" \
-        --arg reset_reason "$reason" \
-        '{
-            session_id: $session_id,
-            created_at: $created_at,
-            last_used: $last_used,
-            reset_at: $reset_at,
-            reset_reason: $reset_reason
-        }' > "$RALPH_SESSION_FILE"
+    write_inactive_ralph_session "$reset_timestamp" "$reason"
 
     # Also clear the Claude session file for consistency
     rm -f "$CLAUDE_SESSION_FILE" 2>/dev/null
@@ -1175,67 +1317,39 @@ init_session_tracking() {
     local ts
     ts=$(get_iso_timestamp)
 
-    # Create session file if it doesn't exist
-    if [[ ! -f "$RALPH_SESSION_FILE" ]]; then
-        local new_session_id
-        new_session_id=$(generate_session_id)
-
-        jq -n \
-            --arg session_id "$new_session_id" \
-            --arg created_at "$ts" \
-            --arg last_used "$ts" \
-            --arg reset_at "" \
-            --arg reset_reason "" \
-            '{
-                session_id: $session_id,
-                created_at: $created_at,
-                last_used: $last_used,
-                reset_at: $reset_at,
-                reset_reason: $reset_reason
-            }' > "$RALPH_SESSION_FILE"
-
-        log_status "INFO" "Initialized session tracking (session: $new_session_id)"
+    local session_state
+    session_state=$(get_ralph_session_state)
+    if [[ "$session_state" == "active" ]]; then
         return 0
     fi
 
-    # Validate existing session file
-    if ! jq empty "$RALPH_SESSION_FILE" 2>/dev/null; then
+    if [[ "$session_state" == "invalid" ]]; then
         log_status "WARN" "Corrupted session file detected, recreating..."
-        local new_session_id
-        new_session_id=$(generate_session_id)
-
-        jq -n \
-            --arg session_id "$new_session_id" \
-            --arg created_at "$ts" \
-            --arg last_used "$ts" \
-            --arg reset_at "$ts" \
-            --arg reset_reason "corrupted_file_recovery" \
-            '{
-                session_id: $session_id,
-                created_at: $created_at,
-                last_used: $last_used,
-                reset_at: $reset_at,
-                reset_reason: $reset_reason
-            }' > "$RALPH_SESSION_FILE"
     fi
+
+    local new_session_id
+    new_session_id=$(generate_session_id)
+    write_active_ralph_session "$new_session_id" "$ts" "$ts"
+
+    log_status "INFO" "Initialized session tracking (session: $new_session_id)"
 }
 
 # Update last_used timestamp in session file (called on each loop iteration)
 update_session_last_used() {
-    if [[ ! -f "$RALPH_SESSION_FILE" ]]; then
+    if [[ "$(get_ralph_session_state)" != "active" ]]; then
         return 0
     fi
 
     local ts
     ts=$(get_iso_timestamp)
 
-    # Update last_used in existing session file
-    local updated
-    updated=$(jq --arg last_used "$ts" '.last_used = $last_used' "$RALPH_SESSION_FILE" 2>/dev/null)
-    local jq_status=$?
+    local session_id
+    session_id=$(get_session_id)
+    local created_at
+    created_at=$(get_active_session_created_at)
 
-    if [[ $jq_status -eq 0 && -n "$updated" ]]; then
-        echo "$updated" > "$RALPH_SESSION_FILE"
+    if [[ -n "$session_id" && -n "$created_at" ]]; then
+        write_active_ralph_session "$session_id" "$created_at" "$ts"
     fi
 }