Session Persistence — Three Channels

## Full reference: session persistence as a deliberate design

Derived from architecture.md §Session Persistence and build-your-own-agent.md Decision 6 of the VILA-Lab/Dive-into-Claude-Code paper (arXiv 2604.14228). All section references below are to architecture.md unless noted.

### 1. Why this pack exists

Most harness engineers see "permissions prompt me again after resume" and file it as a UX bug. It is not. It is a named safety invariant in the paper (§Session Persistence):

> Permissions Never Restored on Resume — Trust is always re-established in the current session. This accepts user friction as the cost of maintaining the safety invariant.

The first-week fix for every new harness team is "remember the user's last-session allow rules." That change looks like a 10-line improvement. In practice it is a silent privilege escalation: a malicious prompt from the last session (or an injected CLAUDE.md delta, or a compromised tool output that steered the user into an unwise allow) continues to hold privilege after the user thought they had closed the door. The paper accepts the friction to keep that door closed.

This pack is the artifact to hand to a colleague who is about to file that "bug."

### 2. Three persistence channels

From architecture.md §Three Persistence Channels:

| Channel | Format | Purpose |
|:--|:--|:--|
| Session transcripts | Append-only JSONL | Full conversation, chain-patched compaction boundaries |
| Global prompt history | `history.jsonl` | Cross-session prompt recall (reverse-read for Up-arrow) |
| Subagent sidechains | Separate JSONL per subagent | Isolated subagent histories |

Each channel has a distinct failure isolation boundary. Corruption of the global history does not affect a live session. Corruption of a sidechain does not affect the parent. A crashed session leaves a recoverable tail in its own transcript without blocking new sessions from starting.

### 3. Append-only + chain patching

The paper's §Chain Patching section (paraphrased) describes the compaction model: compact boundaries record headUuid / anchorUuid / tailUuid. The session loader patches the message chain at read time. Nothing is destructively edited on disk.

This is the critical invariant. A naive compactor rewrites the transcript to replace a span of old messages with a summary. That destroys replay: you can no longer reconstruct what the agent saw before compaction. The Claude Code design instead appends a compaction marker — on read, the loader follows the chain patches to project the effective message sequence. The on-disk log remains the ground truth.

Practical consequences:

- Debugging a past run: you can always read the original events, even through multiple compaction passes.
- Forking: copy the transcript to a new path; no in-place mutation means no race.
- Version control: the transcript is safe to check into git for post-mortems (after redaction).

### 4. Checkpoints

Checkpoints live at `~/.claude/file-history/<sessionId>/` (README §Session Persistence). They support `--rewind-files`: the harness can revert filesystem state to a prior checkpoint without rewinding the conversation. Two implications:

- Checkpoint storage is per-session, per-machine; it does not travel across machines.
- The checkpoint hash is part of the session's required outputs in this pack's contract.

### 5. Why JSONL

From build-your-own-agent.md Decision 6 and architecture.md §Design Trade-off:

> Append-only JSONL favors auditability and simplicity over query power. Every event is human-readable, version-controllable, and reconstructable without specialized tooling.

Trade-off inventory:

- Gains: transparency, trivial crash recovery, no schema migration, no DB operational burden, portable across machines.
- Losses: no SQL queries, no indexes, no server-side aggregation, O(n) scans for anything non-trivial.

The paper frames this as a deliberate choice: the production harness optimises for the case where a human or an agent needs to reconstruct what happened. For analytics, emit a secondary stream to a queryable store — do NOT promote the transcript into the primary database.

### 6. The deliberate non-feature: permissions do not restore

The failure mode to avoid here is "resume restores permissions automatically (UX fix that breaks safety)." Why this is a staff-level trap:

- The "fix" looks trivial — add a permission ledger to the transcript, read it on resume.
- It defeats the per-session trust re-establishment the paper names as an invariant.
- It creates a compounding-privilege attack: each session inherits the previous session's allows, so an allow granted under duress (hostile CLAUDE.md, compromised tool output, social-engineered user) persists indefinitely.
- The 7-safety-layers design (architecture.md §Seven Independent Safety Layers) lists "non-restoration on resume" as layer 6 of 7. Removing it removes a layer.

If you must reduce the re-prompt burden, do it by:

1. Scoping user-initiated allow rules to a settings file the user explicitly reviews (not an implicit ledger).
2. Using auto-mode classifier (see `injection-surface-audit` pack) to raise the automation floor without persisting allows.
3. Keeping the per-session re-prompt for any action with irreversible consequences.

Do NOT quietly roll permissions forward from session to session.

### 7. Global prompt history

`history.jsonl` is the Up-arrow buffer. A single file, append-only, one entry per user prompt. Retention is the user's responsibility. The file grows unboundedly unless a rotation policy is in place — a documented failure mode for long-lived installations.

Suggested retention (not enforced by the harness): rotate at 10 MiB or 10k entries, keep the last file in a `history.jsonl.1` rollover, delete older on a monthly sweep.

### 8. Subagent sidechains

Documented in detail in the `subagent-delegation-three-isolation-modes` pack. The relevant persistence notes here:

- Sidechains live at `.sidechains/<task-id>.jsonl`, distinct directory from session transcripts.
- Parent never reads a child's sidechain; only the summary returns to the parent transcript.
- Sidechain byte caps are a cross-child aggregate — a runaway can fill the disk. Monitor.
- On a crashed subagent, flush discipline becomes critical: a sidechain never flushed is lost context. Use `fsync` on subagent exit.

### 9. Crash recovery

The crash-recovery model is intentionally simple:

1. Session transcript ends without a terminator event → loader treats the last valid line as the final event and opens a new session.
2. Mid-turn tool call interrupted → the incomplete tool-call event is present but no tool-result event; resume sees the gap and retries the call.
3. Compaction interrupted → a partial chain-patch marker is present; the loader falls back to pre-compaction chain walk.
4. Sidechain never flushed → parent's summary is lost; the specific subagent's output is gone (documented failure mode).

None of these require a journal, WAL, or database transaction. The append-only model degrades to a lossy-at-the-tail state that is the same as the normal crash semantics of any O_APPEND log.

### 10. What NOT to do

Catalogued from community reimplementations and documented anti-patterns:

1. **Mutating compaction boundaries in-place** — destroys replay.
2. **Persisting permissions across resume** — erases safety invariant.
3. **No retention on history.jsonl** — grows unboundedly over years.
4. **Forgetting to fsync a crashed subagent's sidechain** — silent context loss.
5. **Re-reading the transcript on every turn** — O(n) scan on every model call, catastrophic tail latency.
6. **Using the transcript as the primary analytics store** — it is optimised for audit, not aggregation.

### 11. Relationship to other packs

- `subagent-delegation-three-isolation-modes` — covers sidechains in depth; this pack covers sessions + history.
- `claude-code-guide` — onboarding reference that cites session memory as one section; this pack is the dedicated persistence specification.
- `injection-surface-audit` — the permissions-non-restoration invariant is one of the audit's checks.