#11893: feat(doctor): add session JSON validation to detect corruption
commands
stale
Cluster:
Session File Path Management
## Problem
A corrupt `sessions.json` file can cause cascading failures:
1. Gateway tries to load invalid JSON
2. API calls fail with errors
3. Provider cooldowns trigger
4. Agent goes down for hours until manual intervention
This happened to me (running OpenClaw via Alex agent) and took hours to diagnose.
## Solution
Add JSON validation to `openclaw doctor`:
1. **`validateSessionsJson()`** - Checks `sessions.json` is valid JSON before loading
2. **`countCorruptJsonlLines()`** - Detects malformed lines in session JSONL files
3. **Repair option** - If sessions.json is corrupt, offer to reset it to `{}`
4. **Warning** - Alert if main session transcript has corrupt JSON lines
## Testing
Tested by intentionally corrupting `sessions.json` and running `openclaw doctor`.
## Related
This check could also be added to the default `AGENTS.md` heartbeat recommendations so agents self-monitor, but that's a separate PR.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR extends `openclaw doctor` state-integrity checks by:
- Validating `sessions.json` parses as JSON and offering an interactive repair (reset to `{}`) when it’s corrupt.
- Scanning the main session transcript JSONL file and warning when some lines aren’t valid JSON.
These checks run as part of `noteStateIntegrity()` and aim to detect/mitigate corrupted session state before it causes broader gateway/API failures.
<h3>Confidence Score: 3/5</h3>
- This PR is close to safe, but needs a guard to avoid doctor crashing on still-corrupt sessions.json.
- The added validation/repair logic is straightforward, but `loadSessionStore()` is still called even when validation fails and the user declines or repair fails, which can reintroduce the original failure mode and prevent the doctor command from completing.
- src/commands/doctor-state-integrity.ts
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#17026: fix(doctor): handle invalid session file paths gracefully
by Limitless2023 · 2026-02-15
79.8%
#18179: CLI: add sessions --json-debug diagnostics
by p6l-richard · 2026-02-16
77.2%
#16135: fix: handle session file paths from other agents in doctor command
by MisterGuy420 · 2026-02-14
75.6%
#9011: fix(session): auto-recovery for corrupted tool responses [AI-assisted]
by cheenu1092-oss · 2026-02-04
75.2%
#21493: fix: auto-initialize agent sessions.json on agent creation
by programadormartinez · 2026-02-20
74.7%
#15744: fix: allow cross-agent session path validation
by scottgl9 · 2026-02-13
73.7%
#16779: feat: add `openclaw sessions scrub` command and doctor check for se...
by akoscz · 2026-02-15
73.7%
#16061: fix(sessions): tolerate invalid sessionFile metadata
by haoyifan · 2026-02-14
73.7%
#10578: feat(doctor): exit with code 1 when critical errors are detected
by 13rac1 · 2026-02-06
73.0%
#18593: fix: resolve symlinks in session path validation (#18553)
by EpaL · 2026-02-16
72.4%