sessions

type ScanOptions struct {
	// IncludeArchived also scans the archived_sessions/ directory. By default
	// (false) only active sessions are scanned.
	IncludeArchived bool
	// DecompressCompressed, when true, attempts to recover metadata (cwd, thread
	// id, preview, ...) from .jsonl.zst rollout files by decompressing their head
	// with the external `zstd` tool. It is opt-in and degrades gracefully: when
	// `zstd` is not installed or a file cannot be decompressed, the compressed
	// file is reported as metadata-unknown exactly as when this is false. The
	// compressed files themselves are only read, never modified.
	DecompressCompressed bool
}

type ScanResult struct {
	Sessions []Session
	// Files is the total number of rollout files detected (valid or not).
	Files int
	// Valid is the number of sessions whose SessionMeta parsed successfully.
	Valid int
	// Invalid is the number of files that produced no usable SessionMeta.
	Invalid int
	// Compressed is the number of .jsonl.zst files detected (regardless of whether
	// their metadata was recovered via zstd).
	Compressed int
	// Warnings are scan-level warnings (e.g. unreadable directories).
	Warnings []string
}

type Session struct {
	// File location.
	Path     string // absolute path on this device
	RelPath  string // path relative to the sessions root (e.g. 2026/06/13/rollout-...jsonl)
	FileName string

	// File-level facts (always populated).
	Compressed bool // true for .jsonl.zst
	Archived   bool // true if found under archived_sessions/
	SizeBytes  int64
	ModTime    time.Time // file modification time; used as updated_at

	// Best-effort metadata parsed from the rollout contents.
	ThreadID         string
	CWD              string
	Originator       string
	CLIVersion       string
	Source           string // e.g. "cli", "appServer"
	ModelProvider    string
	GitBranch        string
	GitSHA           string
	GitOriginURL     string
	CreatedAt        string // SessionMeta timestamp, or derived from filename
	FirstUserMessage string
	Preview          string

	// Parsing status.
	Parsed   bool     // true if a SessionMeta line was found and parsed
	Warnings []string // non-fatal parsing warnings
}