Summary

Problem

When a session undergoes compaction (either automatic due to context limits or manual reset), the transcript file is permanently deleted with no recovery mechanism. This causes:

1. Irreversible data loss: Hours/days of conversation history vanish instantly
2. No grace period: Deleted transcripts cannot be recovered even if compaction was triggered unintentionally
3. No visibility: Users have no warning that compaction will delete their transcript until it's already gone

Real-world impact

A user reported losing 4+ hours of conversation content (4/6 15:45-23:47 Beijing time) when a session reset occurred during a system upgrade. The reset happened at the filesystem level — the transcript file was deleted and replaced with a new one, leaving no trace of the original content.

Problem to solve

Current behavior

Session reset/compaction
    ↓
Old transcript.jsonl deleted
    ↓
New transcript.jsonl created
    ↓
[DATA PERMANENTLY LOST]

Expected behavior

Session reset/compaction
    ↓
Old transcript.jsonl → renamed to transcript.jsonl.archived.{timestamp}
    ↓
New transcript.jsonl created
    ↓
Archived files retained for N days (configurable)
    ↓
Background cleanup removes archived files older than N days

### Proposed solution

## Proposed Solution

Add a configuration option for transcript archival on compaction:

```json
{
  "session": {
    "compaction": {
      "archiveOnCompaction": true,
      "archivedRetentionDays": 7,
      "archiveDirectory": null
    }
  }
}

Behavior

• archiveOnCompaction: true (default: false)

  • Before deleting/replacing a transcript file, rename it to .{sessionId}.archived.{timestamp}.jsonl
  • If archiveDirectory is set, move the archived file there instead of keeping it in the sessions directory

• archivedRetentionDays: 7 (default: 7)

  • Background job removes archived transcripts older than N days
  • If 0, archived files are kept forever (manual cleanup required)

• Background cleanup runs on Gateway startup and every 24 hours

Alternative: Soft delete

Instead of renaming, add a deletedAt field to the sessions.json entry and move the transcript to an archive location. This preserves the sessions.json reference for potential recovery.

Why this matters

1. Compaction is invisible until it's too late: Users don't know compaction will delete their transcript until it's already gone
2. Upgrades trigger compaction: System upgrades often trigger compaction, and users may not realize their conversations are at risk
3. Multi-session environments: In shared or long-running setups, losing conversation history disrupts continuity

Implementation hints

The relevant code is in src/lib/session/compaction.ts or similar. The key change is in the compactSession flow:

1. Before deleting the old transcript, call fs.rename() to a backup path
2. Add archived file records to a simple manifest (or just rely on filesystem timestamps)
3. Add a cleanupArchivedTranscripts() function that runs on startup and via a timer

For the sessions.json, consider adding an archivedSessions array that tracks deleted/replaced sessions:

interface ArchivedSession {
  sessionId: string;
  archivedAt: number;  // Unix timestamp
  archivedPath: string;
  originalStartedAt?: number;
}

See also

• docs/reference/session-management-compaction.md - Current compaction documentation
• Related issue: Session transcript hygiene has no recovery path

Alternatives considered

No response

Impact

NOTHING

Evidence/examples

No response

Additional information

No response