Summary

Orphaned transcript .jsonl files accumulate indefinitely in ~/.openclaw/agents/main/sessions/ because the session lifecycle does not clean up stale files when sessions are reset, restarted, or when subagent runs complete.

Observed Behavior

Running openclaw doctor reports:> Found 800 orphan transcript file(s) in ~/.openclaw/agents/main/sessions. They are not referenced by sessions.json and can consume disk over time.

sessions.json contains only the single live session entry (agent:main:main), while hundreds of .jsonl files from prior sessions remain on disk with no reference.

Root Cause (Hypothesis)

Each session reset (/reset, /new), gateway restart, or subagent run (sessions_spawn) creates a new UUID-named .jsonl file and updates the sessions.json pointer — but the previous file is never deleted. Subagent/cron run files appear to be written but never registered in sessions.json at all, so they are orphaned immediately after the run completes.

On a moderately active instance (~23 days uptime, multiple resets/day, frequent cron subagents), this produced 800 orphaned files.

Environment

• OpenClaw version: 2026.2.21-2 (orphans accumulated before 2026.2.23 cleanup additions)
• OS: Linux (LXC container, Proxmox)- Frequent subagent usage via sessions_spawn and isolated cron jobs

Expected Behavior

Old .jsonl files should be deleted (or archived/rotated) when a session is reset or a subagent run completes. openclaw sessions cleanup (added in 2026.2.23) addresses future accumulation but must be run manually or scheduled — there's no automatic trigger.

Suggestions

1. Auto-delete the previous .jsonl on session reset/new
2. Auto-cleanup subagent transcript files after run completes (or after a configurable retention window)
3. Optionally run cleanup on gateway start when orphan count exceeds a threshold
4. Ship sensible defaults for session.maintenance.maxDiskBytes / highWaterBytes so installations self-limit

Related2026.2.23 added openclaw sessions cleanup and disk-budget controls — good first step, but orphans from before this release still need a remediation path.