Session Healer

Automatically detects and heals locked OpenClaw session files.

Quick Start

# Check for locked sessions
neckr0ik-session-healer check

# Clear all stale locks
neckr0ik-session-healer heal

# Clear specific session lock
neckr0ik-session-healer unlock <session-id>

What This Fixes

The "session file locked" error occurs when:

• OpenClaw crashes while writing to a session
• Multiple processes try to access the same session
• Network timeout during session write
• System crash leaves stale lock files

Symptoms:

• "session file locked (timeout 10000ms)" errors
• All models fail with lock timeout
• Session becomes unresponsive

How It Works

1. Scans ~/.openclaw/agents/*/sessions/*.jsonl.lock files
2. Checks if the owning process is still alive
3. If process is dead, removes the stale lock
4. Optionally recovers session data if corrupted

Commands

check

neckr0ik-session-healer check [--verbose]

Scans for locked sessions and reports:
- Lock file path
- Owning PID
- Process status (alive/dead)
- Lock age
- Session ID

heal

neckr0ik-session-healer heal [--force]

Clears all stale locks (where owning process is dead).

Options:
  --force    Clear all locks, even for alive processes (dangerous)
  --dry-run  Show what would be cleared without doing it

unlock

neckr0ik-session-healer unlock <session-id>

Clears a specific session lock by session ID.

recover

neckr0ik-session-healer recover <session-id>

Attempts to recover a corrupted session file:
- Validates JSON lines
- Removes corrupted lines
- Creates backup before recovery

Safety Features

• Never clears locks for processes that are still alive (unless --force)
• Creates backups before modifying session files
• Logs all actions for audit trail
• Validates session file integrity after healing

Example Output

$ neckr0ik-session-healer check

Checking for locked sessions...
Found 3 lock files:

  ✗ session: c4fa26e6-20be-4843-9678-a2f328dd1844
    Lock: /Users/user/.openclaw/agents/main/sessions/.../c4fa...jsonl.lock
    PID: 52251 (DEAD - process not running)
    Age: 2 hours 34 minutes
    Status: STALE - safe to clear

  ✓ session: a1b2c3d4-5678-90ab-cdef-1234567890ab
    Lock: /Users/user/.openclaw/agents/main/sessions/.../a1b2...jsonl.lock
    PID: 12345 (ALIVE)
    Age: 5 minutes
    Status: ACTIVE - do not clear

$ neckr0ik-session-healer heal

Healing stale locks...
[CLEARED] c4fa26e6-20be-4843-9678-a2f328dd1844 (PID 52251 was dead)
[SKIPPED] a1b2c3d4-5678-90ab-cdef-1234567890ab (PID 12345 still alive)

Healed 1 session. 0 errors.

See Also

• scripts/healer.py - Main healer script
• references/lock-recovery.md - Detailed recovery guide