Session/Cron: harden maintenance and expand docs

docs/cli/cron.md

@@ -23,6 +23,11 @@ Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-
 
 Note: recurring jobs now use exponential retry backoff after consecutive errors (30s → 1m → 5m → 15m → 60m), then return to normal schedule after the next successful run.
 
+Note: retention/pruning is controlled in config:
+
+- `cron.sessionRetention` (default `24h`) prunes completed isolated run sessions.
+- `cron.runLog.maxBytes` + `cron.runLog.keepLines` prune `~/.openclaw/cron/runs/<jobId>.jsonl`.
+
 ## Common edits
 
 Update delivery settings without changing the message:

docs/cli/doctor.md

@@ -27,6 +27,7 @@ Notes:
 
 - Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and `--non-interactive` is **not** set. Headless runs (cron, Telegram, no terminal) will skip prompts.
 - `--fix` (alias for `--repair`) writes a backup to `~/.openclaw/openclaw.json.bak` and drops unknown config keys, listing each removal.
+- State integrity checks now detect orphan transcript files in the sessions directory and can archive them as `.deleted.<timestamp>` to reclaim space safely.
 
 ## macOS: `launchctl` env overrides
 

docs/cli/sessions.md

@@ -14,3 +14,26 @@ openclaw sessions
 openclaw sessions --active 120
 openclaw sessions --json
 ```
+
+## Cleanup maintenance
+
+Run maintenance now (instead of waiting for the next write cycle):
+
+```bash
+openclaw sessions cleanup --dry-run
+openclaw sessions cleanup --enforce
+openclaw sessions cleanup --enforce --active-key "agent:main:telegram:dm:123"
+openclaw sessions cleanup --json
+```
+
+`openclaw sessions cleanup` uses `session.maintenance` settings from config:
+
+- `--dry-run`: preview how many entries would be pruned/capped without writing.
+- `--enforce`: apply maintenance even when `session.maintenance.mode` is `warn`.
+- `--active-key <key>`: protect a specific active key from disk-budget eviction.
+- `--store <path>`: run against a specific `sessions.json` file.
+- `--json`: print one JSON summary object. Dry-run output includes projected `diskBudget` impact (`totalBytesBefore/After`, `removedFiles`, `removedEntries`) when disk budgeting is enabled.
+
+Related:
+
+- Session config: [Configuration reference](/gateway/configuration-reference#session)