Data retention

Retention controls when sessions and related artifacts expire and are physically deleted. It is off by default so unconfigured environments do not delete by accident; when enabled it cleans by TTL, grace, and orphan-sandbox rules, and writes audit.

Enablement and defaults

Config key retention must set enabled: true explicitly. Typical defaults: session TTL 90 days, grace 7 days, orphan sandbox 30 days, scheduled job daily at 03:00. Within grace, renewed session activity can auto-extend.

flowchart LR
  A[Active session] -->|past TTL| W[Grace period]
  W -->|active again| A
  W -->|expires| D[Physical delete]
  O[Orphan sandbox] -->|past orphan_days| D

Delete scope

Expiry cleanup targets the full session tree (messages, parts, todos, the session itself), plus sandbox session directories and related observation and HITL tickets. Audit events carry source=retention (alerts, expiry, sandbox reclaim, and so on) so they can be distinguished from manual deletes.

Manual scan and similar ops actions are RBAC-gated (typically admin only). See RBAC.

Boundaries

• When disabled, nothing is deleted by TTL automatically; do not assume “install implies retention.”
• Deletes are not reversible; production should confirm TTL and backup policy first.
• Under multi-tenancy, cleanup runs in tenant context to avoid cross-tenant damage.

---

Related reading:

• File sandbox
• Observability
• Hash-chain audit