Session Lifecycle Management#

Sessions in Decant have three visibility states — visible (default), archived, and deleted — stored as local metadata that never touches the underlying JSONL source files 1.

State is persisted in the session_user_state table, keyed by (tool, source_session_id). This composite key outlives the physical session row, which is what makes tombstone-based deletion durable.

Archiving#

Archiving is a soft-hide: the session row stays in the database but is excluded from default list, search, and statistics results 1.

• Opt-in: Pass include_archived=true to GET /api/sessions or statistics endpoints to re-include archived sessions 1.
• Search is always filtered: GET /api/sessions/search-index (the command-palette haystack) never surfaces archived sessions, regardless of any parameter 2. Full-text search is similarly limited to visible sessions.
• Ancestor propagation: Archive state is inherited from ancestors via a recursive CTE — if a parent session is archived, child/sub-agent sessions are also hidden. See sessionUserStatePredicate().

The state mutation endpoint is POST /api/sessions/{id}/state with body { "state": "archived" | "visible" | "deleted" }.

Deletion (Tombstones)#

Deletion is a hard delete with tombstone protection: the session subtree is physically removed from the database, and tombstone rows are written to session_user_state with state = 'deleted' so that a subsequent sync does not restore the session 1.

The setSessionUserState() function handles two categories of tombstones on deletion:

1. Direct tombstone — a (tool, source_session_id) row for the deleted session itself.
2. Spawn tombstones (Claude Code only) — child transcripts spawned via tool calls are tracked under the reserved namespace __decant_internal_claude_spawn__, keyed as JSON.stringify([rootSourceSessionId, spawnToolUseId]) 3. When a child transcript is later encountered during sync, inheritDeletedSessionTombstone() propagates the deletion.

Ingest source entries that no longer have any live sessions pointing to them are marked status = 'skipped_deleted' 4. The source JSONL file is never modified.

Effect on List and Statistics Operations#

The shared predicate sessionUserStatePredicateForDatabase() is applied consistently across listSessions() in src/query.ts and statsScope() in src/stats.ts. When no hidden state exists in the database, the predicate optimizes to a no-op.

Deleted sessions are always excluded — there is no flag to surface them after deletion.

Key Source Locations#