Deleted Session Tombstone Semantics#

When a session is deleted, Decant performs a hard delete with tombstone protection: live session rows are physically removed, but a tombstone record in ingest_source is left behind to prevent a future sync from re-ingesting the same transcript.

What happens during deletion#

setSessionUserState(db, id, "deleted") 1 calls deleteSessionIdentities(), which:

1. Deletes the session rows (and orphans children by clearing parent_session_id). 2
2. Updates ingest_source for any paths that no longer have surviving session rows: 3
   ⧉

   SET session_id = NULL,
       status = 'skipped_deleted'
   

Both steps happen atomically inside the same database write transaction. The source JSONL file is never modified. 4

Why the tombstone is unreachable by session ID#

After the update, ingest_source.session_id is NULL. Any query of the form:

SELECT * FROM ingest_source WHERE session_id = ?

returns no rows — the tombstone row exists, but the foreign key is gone. This is by design: the row's purpose is to block re-ingestion, not to be found by session lookup.

The only reliable way to reach the tombstone is to query by path:

SELECT * FROM ingest_source WHERE path = ? AND status = 'skipped_deleted'

This matters when writing tests or diagnostics that assert on tombstone presence: always key on path, never on a session ID. 3

The ingest_source schema 5 confirms that path is the PRIMARY KEY and session_id is a nullable REFERENCES session(id) ON DELETE SET NULL.

Transcript bytes persist until vacuum#

Deleting rows in SQLite frees pages but does not zero their content. Deleted transcript text remains physically present in decant.db — and greppable — until the file is rewritten. 6

Run the following to reclaim that space:

decant db vacuum

This executes VACUUM; on the archive, rewriting the database file and eliminating freed pages. 7 The CLI also surfaces a reminder after every session deletion. 8

Implication: documentation or comments that describe deletion as "removing the transcript" are only accurate if they also name vacuum. Until decant db vacuum runs, the transcript text is still present on disk.

Related: Claude spawn tombstones#

For Claude Code sessions, child transcripts spawned via tool calls get their own session_user_state tombstones under the __decant_internal_claude_spawn__ namespace. When a spawned child transcript is encountered during a later sync, inheritDeletedSessionTombstone() propagates the deletion without re-ingesting the transcript. 9

Key source locations#