# src/sessions KNOWLEDGE BASE
## OVERVIEW
JSONL session boundary: ids, append durability, tolerant/strict replay reads, metadata sidecars, pruning, compaction checkpoints, AI title events, and session scope normalization across git worktrees.
## STRUCTURE
```text
src/sessions/
├── mod.rs # facade exports and crate-private re-exports
├── event.rs # SessionEvent, SessionEventKind, local-only event classification
├── manager.rs # SessionManager, Session, id/path lifecycle
├── read.rs # strict/tolerant/bounded JSONL reads and id validation
├── write.rs # redacted durable append path, title/compaction record helpers
├── metadata.rs # metadata sidecar rebuild/update/listing/title/compaction lookup
├── prune.rs # /prune-sessions parsing and deletion report
├── scope.rs # session_path scope normalization to primary git worktree
└── titles.rs # background session title generation
```
## WHERE TO LOOK
| Session lifecycle | `manager.rs` | `SessionManager`, `Session` | Create/open/list/most_recent; ids become `{id}.jsonl`. |
| Event model | `event.rs` | `SessionEvent`, `SessionEventKind` | Stable `event_type` strings; unknown legacy kinds tolerated. |
| Append path | `write.rs` | `Session::append_owned` | Validate ids, redact payload, lock, append, sync, update metadata. |
| Durable write helper | `write.rs` | `append_event_line_durably` | Serialize one JSON object plus newline; flush, sync, rollback partial append. |
| Strict/tolerant reads | `read.rs` | `read_events*`, `visit_events_tolerant_bounded` | Strict fails; tolerant keeps valid events plus capped diagnostics. |
| Metadata cache | `metadata.rs` | `SessionMetadataRecord` | Sidecar invalidates on schema/id/JSONL marker mismatch. |
| Compaction | `metadata.rs`, `write.rs` | `CompactionCheckpoint`, `record_session_compaction` | Redacted summaries; latest valid checkpoint wins. |
| Pruning | `prune.rs` | `parse_prune_sessions_days`, `prune_sessions` | Retention parser, active-session skip, checkpoint pruning. |
| Scope path | `scope.rs` | `resolve_session_scope_path` | Worktree sessions scope to primary worktree path. |
| Titles | `titles.rs` | `SessionTitleJob`, `SessionTitleUpdate` | PRD-0033 background title generation and notification. |
## CONVENTIONS
- Session ids stay path-safe: no empty, `..`, separator, absolute path, dot-extension, or non `[A-Za-z0-9_-]` chars.
- New sessions do not create JSONL file until first append; avoids orphan shells.
- `Session::append_owned` is session durability boundary. Keep id validation, redaction, locks, newline append, flush, sync, rollback, and metadata update together.
- Payload redaction happens inside append path before disk write; credential-like keys become `<redacted>` where applicable.
- Metadata is cache, not source of truth. Rebuild from JSONL when marker/schema/id validation fails.
- JSONL marker = file length plus modified ns. Update after successful append only.
- Replay size accounting uses original JSONL line bytes. Do not reserialize events for byte budgets.
- Tolerant reads report line number and parse/read error only. Never include malformed line content.
- Diagnostic caps stay bounded; overflow message uses line `0` summary.
- Local-only event kinds stay out of provider replay unless caller explicitly filters otherwise.
- Session scope path records primary git worktree when cwd is any linked worktree.
- Title generation uses first prompt context, max 2000 chars input, max 50 chars output.
- Best-effort event recording may warn but must not abort provider/tool execution.
- User-visible session writes should return append errors to caller.
## ANTI-PATTERNS
- Do not bypass `Session::append_owned` for JSONL writes.
- Do not write session JSONL with `fs::write`, partial rewrites, or unflushed buffered output.
- Do not remove either lock layer; concurrent appends must remain parseable.
- Do not trust sidecar metadata when JSONL marker changed.
- Do not expose corrupted/malformed JSONL line text in diagnostics, logs, UI, or provider payloads.
- Do not let session title failures break active runs.
- Do not accept user-supplied path fragments as session ids; validate through session-id rules before file access.
- Do not make unknown event types fatal during replay.
- Do not change persisted `event_type` strings without migration and replay tests.