Problem

sessions.json grows unbounded over time. Every heartbeat tick (default: 30m) triggers multiple full rewrites, and session keys from groups, threads, and DMs accumulate indefinitely with large embedded objects (skillsSnapshot, systemPromptReport). At >50MB the synchronous JSON parse blocks the event loop, causing Telegram webhook timeouts and effectively taking the bot down.

Fix

Three mitigations, all running inside saveSessionStoreUnlocked() on every write:

1. Prune stale entries

Remove entries with updatedAt older than 30 days. Entries without updatedAt are preserved (cannot determine staleness).

2. Cap entry count

Keep only the 500 most recently updated entries. Entries without updatedAt are evicted first (lowest priority).

3. File rotation

If the existing sessions.json exceeds 10MB before a write, rename it to sessions.json.bak.{timestamp}. Only the 3 most recent backups are kept.

Configuration

All three thresholds are configurable via openclaw.json under session.maintenance:

{
  "session": {
    "maintenance": {
      "pruneDays": 30,
      "maxEntries": 500,
      "rotateBytes": 10485760
    }
  }
}

All fields are optional — built-in defaults apply when unset. No env vars are used; configuration is purely through openclaw.json.

The SessionMaintenanceConfig type is added to types.base.ts and the Zod schema is added to zod-schema.session.ts.

The three exported functions also accept an optional override parameter for direct use in tests or programmatic callers:

• pruneStaleEntries(store, overrideDays?)
• capEntryCount(store, overrideMax?)
• rotateSessionFile(storePath, overrideBytes?)

Changes

Test results

72 tests pass (7 test files).

Notes

• Pruning and capping mutate the store object in-place before serialization. File rotation renames the on-disk file before the new write.
• No changes to function signatures of existing exported functions.
• Logged via createSubsystemLogger("sessions/store") at info level when entries are pruned, capped, or the file is rotated.

Greptile Overview

Greptile Summary

This PR adds automatic sessions.json maintenance during session store writes: pruning entries older than a configurable age, capping total entries to a configurable maximum, and rotating the on-disk file when it exceeds a size threshold (keeping a small set of .bak.{timestamp} backups). Configuration is wired through openclaw.json under session.maintenance with a new SessionMaintenanceConfig type and Zod validation. Migrations are updated to be able to bypass maintenance during one-time legacy merges.

One issue to fix before merge: the new pruning/capping/rotation test suite references crypto.randomUUID() without importing crypto, which will break in environments where crypto is not a global in tests.

Confidence Score: 4/5

• This PR is close to safe to merge, with one clear test/runtime issue to fix.
• Core maintenance logic (pruning/capping/rotation) is internally consistent and call sites remain compatible via an optional options param, but the new test file relies on an undeclared crypto identifier which can cause CI failures depending on the test runtime globals.
• src/config/sessions/store.pruning.test.ts

_{(2/5) Greptile learns from your feedback when you react with thumbs up/down!}