<!-- Generated by generate-agent-docs; preserve verified project-specific guidance when regenerating. -->
# Session storage guide
Parent: [source guide](../AGENTS.md).
Durable JSONL events, bounded reads, metadata, scope, retention and export.
## Where to look
| Change | Owner |
| --- | --- |
| Event kinds and local-only classification | `event.rs` |
| Create/open/list and writer admission | `manager.rs`, `writer.rs` |
| Read-only bounded local-agent inventory | `discovery.rs` |
| IDs, tolerant reads, append outcomes | `read.rs`, `write.rs` |
| Usage and preferences | `usage.rs`, `usage_recorder.rs`, `preferences.rs` |
| Neutral presentation/history hydration helpers | `chat.rs`; wire pages: `../local_agent/sessions.rs` |
| Prospective display-only applied previews | `tool_display.rs`; persistence: `../agent/session_persistence.rs` |
| Sidecars, retention and worktree scope | `metadata.rs`, `prune.rs`, `scope.rs` |
| PSM full-record reads, response links and durable batches | `progressive_summaries.rs`; status snapshots: `progressive_summaries/status.rs`; scheduling/provider work: `../progressive_session_maintenance.rs` |
| Preparation/export | `store.rs`, `export.rs`, `export/{discovery,archive}.rs` |
| Rewind forks and retained-prefix checkpoints | `rewind.rs`, `effects.rs`, `task_scope.rs` |
## Local contracts
- Startup prepares protected session root after config directory setup. Shared tool/subagent result data comes from `../output/`, never execution owners; chat may use `ToolCapability` only for saved dispatch-name equivalence.
- Validate IDs before constructing paths; new sessions may lack JSONL until first append. Use `Session::append_with_outcome`; `append_owned_batch` owns validation, redaction, locking, writes, rollback and metadata. Distinguish rolled-back from uncertain outcomes.
- Every newly appended event gets a hexadecimal `event_id` from the durable root `event-id-sequence`, shared by primary and child sessions. Reserve IDs before JSONL writes; never reset or prune the sequence. Rewind copies get fresh IDs; compaction archives and retained suffixes keep theirs. Readers accept legacy records without IDs. IDs stay out of UI/provider projections.
- Metadata validates session ID/schema/file length/modification time; stale sidecars rebuild from JSONL. Read limits count original line bytes, tolerant errors expose line numbers/safe errors rather than malformed content, unknown kinds remain readable. Provider replay belongs to context.
- Local-agent inventory stays read-only and bounded; no sidecar rebuild, retention or lease acquisition. Held-file opens use `O_NONBLOCK` before regular-file validation so FIFOs cannot stall admission.
- Chat projection reconciles final/chunk output before redaction/chunking, excludes internal prompts/private provider records and summarizes tools without raw bodies. Snapshot IDs are revision-scoped; mutation invalidates wire pages. This is separate from TUI state and provider replay.
- Writer leases differ from retention protection and stay in `Session` clones through cleanup. Lock order: writer → activation → append; nested work reuses admission. Delete sidecars only after successful session deletion.
- Worktree normalization belongs in `scope.rs`, deletion in `prune.rs`. Title records belong here, provider/background work in `../session_titles.rs`; best-effort title/cache failures cannot replace required append outcomes.
- PSM is opt-in and separate from replay/compaction. Observe committed records only; use `<id>.psm.ndjson`, never a session-discovery suffix. Failed batches cannot acknowledge inputs or append session diagnostics. Retain full records and event IDs through archive reads; tool results supply evidence but never standalone summaries.
- PSM diagnostics use atomic owner-private `<id>.psm.status.json` snapshots from the background worker only. Retain bounded redacted errors across passes; status write failure cannot fail summary generation. Never append diagnostic events to conversation history.
- Export owns cancellation and destination validation; no direct archive-write bypass.
- Usage checkpoints cover only removed prefixes. Retain active-run records so suffix snapshots replace partial usage without double counting; missing/unfinished request usage remains incomplete.
- `effects.rs` folds removed-prefix structured mutation evidence into bounded `execution_effects`. Restores/clean diffs/model summaries cannot erase observations; legacy missing evidence is incomplete and shell calls do not prove writes.
- `task_scope.rs` retains original delegated input and acknowledged steering outside summaries. Fold only removed prefixes into versioned checkpoints; missing/invalid required policy blocks execution. Scope caches are derived; validate steering before required append and update only after success.
- Rewind copies ordered prefix before retained prompt into a new fork, remaps top-level session IDs and uses durable batches; never truncates source JSONL. Preserve event-count cutoffs and aggregate prompt numbering. Unsent rewind prompts remain local diagnostic metadata.
- `tool_applied_preview` stores sanitized bounded display data after its execution result. Unique result display IDs plus session/parent/sequence join records, never adjacency. Duplicate/malformed previews stay unavailable. Redact multiline secrets before selection; live and reopened adapters share selected source. Hydration is display-only; preserve provider exclusion, owned budgets, degraded persistence and required execution evidence. Saved chat attachments scope real call IDs by turn and Code Mode parent; duplicates stay null and mismatched tool names fail exact open before attachment replacement.