feat(retention): add session data retention management (#106)

Adds agent-strace retention status/clean commands to enforce configurable
data retention policies. Supports max_age_days, max_sessions, and
max_size_mb limits, configurable via .agent-strace.yaml or CLI flags.
Deletions are logged to .agent-traces/retention.log for audit trails.

Closes #89

Co-authored-by: Ona <no-reply@ona.com>

Author: Siddhant-K-code

README.md

@@ -216,6 +216,8 @@ agent-strace dashboard [--last N] [--html file] Aggregate stats and trends acros
 agent-strace annotate <session-id> <offset>     Add notes, labels, or bookmarks to events
 agent-strace token-budget <session-id>          Check token usage against model context limit
 agent-strace replay [session-id] [--limit N]    Replay a session (--limit caps events shown)
+agent-strace retention status                   Show session count, size, and what policy would delete
+agent-strace retention clean [--dry-run]        Delete sessions that exceed retention limits
 agent-strace watch [--timeout DURATION] [--budget $] [--on-death CMD] [--rules file]
                                                 Watch a live session; kill/pause on rule breach
 agent-strace share <session-id> [-o file]       Export a self-contained HTML report
@@ -297,6 +299,39 @@ Supported models: `sonnet` (default), `opus`, `haiku`, `gpt4`, `gpt4o`. Token co
 
 See [examples/session_analysis.md](examples/session_analysis.md) for a full walkthrough combining `import`, `explain`, and `cost`.
 
+### Data retention
+
+Enforce configurable retention policies to automatically delete old session data — required for GDPR, SOC 2, and internal data policies.
+
+```bash
+# Check current status and what policy would delete
+agent-strace retention status
+
+# Preview what would be deleted (no changes made)
+agent-strace retention clean --dry-run
+
+# Delete sessions older than 30 days
+agent-strace retention clean --max-age-days 30
+
+# Keep only the 1000 most recent sessions
+agent-strace retention clean --max-sessions 1000
+
+# Delete oldest sessions when storage exceeds 500 MB
+agent-strace retention clean --max-size-mb 500
+```
+
+Configure via `.agent-strace.yaml`:
+
+```yaml
+retention:
+  max_age_days: 30
+  max_sessions: 1000
+  max_size_mb: 500
+  on_delete: log    # log deletions to .agent-traces/retention.log
+```
+
+Policies are applied in order: age → count → size. Deletions are logged with session ID and timestamp (not content).
+
 ### Secret redaction
 
 Strip API keys, tokens, and credentials from traces before they hit disk.

src/agent_trace/__init__.py

@@ -1,3 +1,3 @@
 """agent-trace: strace for AI agents."""
 
-__version__ = "0.39.1"
+__version__ = "0.40.0"

src/agent_trace/cli.py

@@ -45,6 +45,7 @@
 from .postmortem import cmd_postmortem
 from .share import cmd_share
 from .token_budget import cmd_token_budget
+from .retention import cmd_retention
 from .watch import cmd_watch
 from .why import cmd_why
 from .models import EventType, SessionMeta, TraceEvent
@@ -772,6 +773,24 @@ def build_parser() -> argparse.ArgumentParser:
         help="transport protocol (default: stdio)",
     )
 
+    # retention
+    p_ret = sub.add_parser("retention", help="manage session data retention")
+    ret_sub = p_ret.add_subparsers(dest="retention_command")
+
+    ret_sub.add_parser("status", help="show retention status and what would be deleted")
+
+    p_ret_clean = ret_sub.add_parser("clean", help="delete sessions that exceed retention limits")
+    p_ret_clean.add_argument("--dry-run", action="store_true",
+                             help="show what would be deleted without deleting")
+    p_ret_clean.add_argument("--max-age-days", type=int, dest="max_age_days", metavar="N",
+                             help="delete sessions older than N days")
+    p_ret_clean.add_argument("--max-sessions", type=int, dest="max_sessions", metavar="N",
+                             help="keep only the most recent N sessions")
+    p_ret_clean.add_argument("--max-size-mb", type=float, dest="max_size_mb", metavar="MB",
+                             help="delete oldest sessions when storage exceeds MB")
+    p_ret_clean.add_argument("--config", metavar="FILE",
+                             help="path to .agent-strace.yaml config file")
+
     # diff --semantic and --eval-config flags (extend existing diff parser)
     p_diff.add_argument("--semantic", action="store_true",
                         help="semantic outcome-level diff (files, cost, errors)")
@@ -832,6 +851,7 @@ def main() -> None:
         "freshness": cmd_freshness,
         "standup": cmd_standup,
         "mcp": cmd_mcp,
+        "retention": cmd_retention,
     }
 
     handler = handlers.get(args.command)