Bug Description

sessions.json can become corrupted (0 bytes), causing silent session aggregation failures. When this happens, OpenClaw cannot list or manage sessions properly, and there's no automatic recovery mechanism.

Environment

• OpenClaw version: 2026.5.3-1
• OS: Linux 6.8.0-110-generic (x64)
• Node: v22.22.2
• Gateway: systemd user service
• Session store: ~/.openclaw/agents/main/sessions/sessions.json

Observed State

$ ls -la ~/.openclaw/state/sessions.json
-rw-rw-r-- 1 moltbot moltbot 0 May 5 16:58 sessions.json

$ wc -c ~/.openclaw/state/sessions.json
0 /home/moltbot/.openclaw/state/sessions.json

Session directory: 7,806 jsonl files (404MB total)

Symptoms

1. Session operations fail silently

   • sessions.list may timeout or return empty
   • Session aggregation cannot complete
   • No user-facing error message

2. SessionWriteLockTimeoutError cascades

   • Lock held for 60s (timeout)
   • Event loop starvation (ELD P99=7,772ms)
   • Discord slash commands fail ("Application did not respond")

3. No automatic recovery

   • File remains 0 bytes indefinitely
   • Manual intervention required: echo "[]" > sessions.json

Root Cause Hypothesis

Likely caused by:

• Concurrent write during session compaction
• Gateway restart mid-write
• Session file lock contention during heavy load

Impact

• Complete session management failure - Cannot list, archive, or prune sessions
• Cascading failures - Event loop starvation affects all channels
• Data loss risk - If sessions.json is the source of truth for active sessions

Expected Behavior

1. Atomic writes - Use temp file + rename pattern for sessions.json updates
2. Corruption detection - Validate JSON on read, trigger rebuild if invalid
3. Automatic recovery - If sessions.json is empty/invalid, rebuild from session directory scan
4. Health check - openclaw doctor should flag empty/corrupted sessions.json

Reproduction Steps

1. Have high session file count (~7,000+ files)
2. Trigger session compaction or heavy concurrent operations
3. Force gateway restart during active session write (SIGTERM)
4. Check ~/.openclaw/state/sessions.json - may be 0 bytes

Workaround

# Manual recovery
echo "[]" > ~/.openclaw/state/sessions.json

# Then restart gateway
systemctl --user restart openclaw-gateway

Related Issues

• sessions.list latency around 10s and fixed 10s pi-trajectory-flush timeout under moderate session load #75839 - pi-trajectory-flush timeout with high session count
• Make session write lock configurable + narrow lock scope (avoid timeout=All models failed) #13744 - Make session write lock configurable
• [Bug] Discord interaction handler AbortError floods log when event loop is saturated — no user-facing recovery #77716 - Discord AbortError during event loop saturation
• [Bug] sessions.list/send gateway timeout after event loop stall (v2026.5.2) #76421 - sessions.list timeout after event loop stall

Suggested Fix

1. Write atomicity:

// Pseudo-code for atomic session.json update
const tmpFile = `${sessionFile}.tmp.${Date.now()}`;
fs.writeFileSync(tmpFile, JSON.stringify(sessions));
fs.renameSync(tmpFile, sessionFile); // Atomic on POSIX

2. Validation on read:

const data = fs.readFileSync(sessionFile, 'utf8');
if (!data || data.length === 0) {
  logger.warn('sessions.json is empty, rebuilding...');
  return rebuildFromSessionDir();
}

3. Rebuild function:

function rebuildFromSessionDir() {
  const sessionFiles = fs.readdirSync(sessionsDir)
    .filter(f => f.endsWith('.jsonl'))
    .map(f => parseSessionFile(f));
  return sessionFiles;
}

4. Health check:
   Add to openclaw doctor:

[FAIL] sessions.json is 0 bytes (corrupted)
  Fix: Run `openclaw sessions rebuild-index`

Evidence from 2026-05-05 Incident

• sessions.json: 0 bytes (corrupted)
• Session files: 7,806 jsonl files
• SessionWriteLockTimeoutError at 17:35:58 and 18:23:26
• Event loop utilization: 95.8%
• Discord slash commands: "Application did not respond"
• Fixed by: echo "[]" > sessions.json + gateway restart