Summary

This PR completes and hardens session/cron maintenance with safer cleanup semantics, clearer operator UX, and stronger observability.

• Adds first-class session maintenance controls:
  • session.maintenance.resetArchiveRetention
  • session.maintenance.maxDiskBytes
  • session.maintenance.highWaterBytes
• Adds openclaw sessions cleanup with --dry-run, --enforce, --json, and active-session protection.
• Adds multi-agent targeting for session inspection/cleanup via --agent <id> and --all-agents.
• Expands dry-run UX to show per-session planned actions in a table (Action, Key, Age, Model, Flags).
• Hardens transcript/archive cleanup to stay scoped to the owning store directory.
• Adds cron maintenance controls:
  • cron.sessionRetention transcript archival/cleanup
  • cron.runLog.maxBytes / cron.runLog.keepLines pruning
• Updates doctor state-integrity messaging with actionable OpenClaw verification commands.
• Fixes enforce-mode reporting so cleanup JSON/text summaries use actual applied maintenance stats (not preview-derived values).
• Adds regression coverage for enforce-mode summary correctness and doctor hint messaging.

Defaults and compatibility

• No default behavior changes.
• Existing defaults remain unchanged (warn, 30d, 500, 10mb; cron 24h; run-log 2_000_000 bytes / 2000 lines).
• New knobs are additive and default-safe.
• No breaking changes for existing configs.

Tests

• pnpm vitest src/config/sessions/artifacts.test.ts src/config/sessions/store.pruning.integration.test.ts src/commands/sessions-cleanup.test.ts src/cron/session-reaper.test.ts
• pnpm vitest src/gateway/session-utils.fs.test.ts src/commands/doctor-state-integrity.test.ts src/commands/doctor-state-integrity.test.ts
• pnpm check

Greptile Summary

This PR implements comprehensive session and cron maintenance hardening with safer cleanup semantics and improved operator UX. The changes add first-class session maintenance controls (session.maintenance.resetArchiveRetention, maxDiskBytes, highWaterBytes), a new openclaw sessions cleanup command with dry-run and enforce modes, multi-agent targeting via --agent and --all-agents, and cron maintenance controls for session retention and run-log pruning.

Key improvements:

• Path traversal protection via restrictToStoreDir ensures cleanup operations stay scoped to the owning store directory
• Disk budget enforcement removes oldest archives and transcripts when thresholds are exceeded
• Active session protection prevents cleanup from evicting in-use sessions
• Enhanced dry-run UX shows per-session planned actions in a table with Action, Key, Age, Model, and Flags columns
• Enforce-mode reporting fixed to use actual applied stats instead of preview-derived values
• Doctor state-integrity messaging updated with actionable verification commands
• Comprehensive test coverage for enforce-mode summary correctness and edge cases

Architecture:

• Session disk budget logic lives in src/config/sessions/disk-budget.ts with proper file/entry size accounting
• Cleanup command implementation in src/commands/sessions-cleanup.ts handles both dry-run preview and enforce modes
• Transcript archiving now respects store directory boundaries via path validation
• Cron session reaper in src/cron/session-reaper.ts handles ephemeral run session cleanup with throttling

Confidence Score: 4/5

• This PR is safe to merge with minor risk - the implementation is well-tested and includes proper safety mechanisms
• The PR demonstrates solid engineering with comprehensive test coverage, proper path traversal protection, active session guards, and backward-compatible defaults. The disk budget enforcement logic correctly handles concurrent operations, and the restrictToStoreDir flag prevents cleanup from affecting paths outside the sessions directory. One minor area that warrants attention is ensuring the doctor hints reference the correct command syntax across all edge cases.
• Pay close attention to src/config/sessions/disk-budget.ts for the core cleanup logic and path safety validation

_{Last reviewed commit: a202c52}