PR #75672: feat(sessions): clean up archived transcript files on cleanup (#75658)

• Repository: openclaw/openclaw
• Author: ottodeng
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/75672

Description (problem / solution / changelog)

Fixes #75658.

Problem

openclaw sessions cleanup only manages entries in sessions.json (the index). The on-disk archive artefacts that the gateway leaves behind during normal use accumulate indefinitely:

• <sessionId>.jsonl.deleted.<ts> (explicitly-deleted sessions)
• <sessionId>.jsonl.reset.<ts> (post-/reset snapshots)
• <sessionId>.checkpoint.<uuid>.jsonl for sessions that are no longer in the index (orphan compaction checkpoints)

The reporter saw 63 MB of archived files vs 36 MB of live state on a busy Pi install. openclaw sessions cleanup --all-agents --dry-run reported Would prune missing transcripts: 0 despite 86 archive files.

This compounds the synchronous-fs.readFileSync event-loop blocking discussed in #75656 — the bigger the directory, the worse the wedges.

Why the gateway already had the helper

cleanupArchivedSessionTranscripts() (in src/gateway/session-archive.runtime.ts) already implements the timestamp-based pruning logic. The gateway calls it inline during normal maintenance (src/config/sessions/store.ts lines 347–363). The CLI just never wired it up.

Fix

Add planArchivedSessionFileCleanup() to the sessions cleanup command:

1. Scan the directory containing the session store.
2. .deleted.<ts> older than maintenance.pruneAfterMs → remove.
3. .reset.<ts> older than maintenance.resetArchiveRetentionMs → remove (skipped when retention is null, matching existing runtime behaviour — operators opt in via sessionMaintenance.resetArchiveRetention).
4. <sessionId>.checkpoint.<uuid>.jsonl whose sessionId is no longer in the live index → remove.
5. Honours --dry-run (preview) and --enforce (apply).

The plan is surfaced in:

• The dry-run summary log: Would remove archived transcripts: N (deleted=, reset=, orphan-checkpoint=, B bytes) (or Archived transcripts scanned: N (none past retention) when nothing qualifies).
• A new archivedFiles field on SessionCleanupSummary (and therefore the JSON output).

Tests

New sessions-cleanup.archived-files.test.ts covers four cases:

• dry-run reports candidates without deleting any files
• apply removes .deleted, .reset, and orphan checkpoints, while preserving in-window archives, live checkpoints, the unrelated sessions.json, and non-session files
• resetArchiveRetentionMs: null preserves all .reset files but .deleted files are still removed via pruneAfterMs
• a missing store directory returns an empty plan instead of throwing

The logic was first validated with a standalone fs-based simulator before being mirrored into the test file. All cases pass.

The pre-existing sessions-cleanup.test.ts continues to work — it already supplies resetArchiveRetentionMs in the mocked maintenance config and the new helper handles missing on-disk directories silently.

Risk

Medium-low. The helper:

• Uses the existing archive-timestamp parser (parseSessionArchiveTimestamp) so it cannot mis-identify non-archive files.
• Only acts inside the directory of the configured store.
• Honours both retention thresholds that the gateway already enforces via cleanupArchivedSessionTranscripts.
• Treats the store directory not existing as a no-op.
• Treats unlink failures as best-effort (matches cleanupArchivedSessionTranscripts).

The directory walk is fs.readdirSync + fs.statSync per file. Pi/ARM users with hundreds of MB of archive files will see a one-time pause during cleanup; this matches the gateway-side maintenance path that is already on the same code shape.

Changed files

• CHANGELOG.md (modified, +2/-0)
• docs/cli/sessions.md (modified, +25/-0)
• src/commands/sessions-cleanup.archived-files.test.ts (added, +180/-0)
• src/commands/sessions-cleanup.ts (modified, +224/-2)