supercode_harness/

store.rs

//! A directory-backed store for supercode's own sessions — naming, titles,
//! listing, archiving, and deletion. The analog of `claude --name` / the Codex
//! `resume`/`archive`/`delete` session lifecycle.
//!
//! Each session is a `<name>.jsonl` transcript (one [`crate::ChatMessage`] per
//! line) plus a `<name>.meta.json` sidecar carrying the title. Archiving moves
//! the pair under an `archived/` subdirectory.

use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::error::{Error, Result};
use crate::reduce::ReductionLog;

/// Lightweight metadata about a stored session.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct SessionInfo {
    /// The session name (the file stem; unique within the store).
    pub name: String,
    /// A human-readable title.
    #[serde(default)]
    pub title: String,
    /// Whether the session is archived.
    #[serde(default)]
    pub archived: bool,
    /// Whether reduced-mode projection (A5) has ever been applied to this
    /// session. `#[serde(default)]` so meta.json files written before A2
    /// still parse (they simply read as `false`).
    #[serde(default)]
    pub reduced: bool,
    /// The model tier (B1/D5) last used for this session, if tiers are
    /// configured; empty otherwise.
    #[serde(default)]
    pub tier: String,
    /// Serialized byte size of the full (unreduced) view, last measured (C9).
    #[serde(default)]
    pub full_bytes: u64,
    /// Serialized byte size of the current reduced working view, last
    /// measured (C9).
    #[serde(default)]
    pub view_bytes: u64,
    /// Number of `[sc-reduced ...]` stubs currently standing in the working
    /// view (C2/A4).
    #[serde(default)]
    pub stub_count: u32,
    /// Number of escalation events recorded for this session (B5/C8).
    #[serde(default)]
    pub escalations: u32,
    /// BP-8 (catalog:153 "Format versioning/migration"): the on-disk
    /// generation this session's family was last written at. `0` — the
    /// `#[serde(default)]`, and what every pre-BP-8 meta.json reads as —
    /// means "unmarked", which is what [`SessionStore::upgrade_in_place`]
    /// keys off.
    #[serde(default)]
    pub format_version: u32,
}

/// A filesystem session store rooted at a directory.
pub struct SessionStore {
    root: PathBuf,
}

impl SessionStore {
    /// Address a store at `root` without touching the filesystem. Read-only
    /// discovery paths use this so merely checking whether a named session
    /// exists cannot create an empty store directory. Mutating methods still
    /// create their required directories before writing.
    pub fn at(root: impl Into<PathBuf>) -> Self {
        SessionStore { root: root.into() }
    }

    /// Open (creating if needed) a store at `root`.
    pub fn open(root: impl Into<PathBuf>) -> Result<Self> {
        let root = root.into();
        std::fs::create_dir_all(&root)?;
        Ok(Self::at(root))
    }

    /// Reject session names that could escape the store root. Names are file
    /// stems, so anything with a path separator, a `..` component, or a leading
    /// dot/whitespace is invalid — without this, a name like `../../foo` would
    /// read/write/delete files outside the store.
    fn validate_name(name: &str) -> Result<()> {
        let bad = name.is_empty()
            || name.contains('/')
            || name.contains('\\')
            || name.contains('\0')
            || name.split(['/', '\\']).any(|c| c == ".." || c == ".")
            || std::path::Path::new(name).is_absolute()
            || name.trim() != name;
        if bad {
            return Err(Error::Other(format!("invalid session name: `{name}`")));
        }
        Ok(())
    }

    fn transcript_path(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived).join(format!("{name}.jsonl"))
    }
    fn meta_path(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived).join(format!("{name}.meta.json"))
    }
    /// `<root>/<name>.sidecar.jsonl` (or under `archived/`) — the A1
    /// native-v2 file, source of truth (D1).
    fn sidecar_path_in(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived).join(format!("{name}.sidecar.jsonl"))
    }
    /// `<root>/<name>.reduction.json` (or under `archived/`) — the persisted
    /// `ReductionLog`, the stub index (D1).
    fn reduction_path(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived).join(format!("{name}.reduction.json"))
    }
    /// `<root>/<name>.events.jsonl` (or under `archived/`) — the session's
    /// per-round-trip marker log (C8/D1). BP-7 filled this slot in:
    /// [`Self::save_turn_records`]/[`Self::load_turn_records`] write and
    /// read [`crate::turn_record::TurnRecord`]s here, and the lifecycle
    /// sweep (`archive`/`delete`) carries the file with the family.
    fn events_path(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived).join(format!("{name}.events.jsonl"))
    }
    /// `<root>/<name>.usage.jsonl` (or under `archived/`) — P4b (design
    /// §5.2 "P4", §1.6, catalog §4a "persisted per-turn usage records"): one
    /// [`crate::usage_log::UsageRecord`] per line.
    fn usage_path(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived).join(format!("{name}.usage.jsonl"))
    }
    /// `<root>/<name>.model_change.jsonl` (or under `archived/`) — P4c
    /// (design §5.2 "P4" core NEW-significant, §1.10/§3.1
    /// `core.model_switch.allow_switch`): one
    /// [`crate::model_change::ModelChangeRecord`] per line.
    fn model_change_path(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived)
            .join(format!("{name}.model_change.jsonl"))
    }
    /// `<root>/<name>.git.json` (or under `archived/`) — P4e (design §5.2
    /// "P4e", §1.6/§3.1 `core.session.git_metadata`): the single
    /// [`crate::git_metadata::GitMetadataRecord`] captured for this
    /// session, if any (a single record, not a JSONL log — see that
    /// module's doc comment).
    fn git_metadata_path(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived).join(format!("{name}.git.json"))
    }
    /// `<root>/<name>.goal.json` (or under `archived/`) — BP-7 (catalog
    /// §4a "Goals"): the session's single [`crate::goals::GoalRecord`], if
    /// one was ever set. A single record, not a log, exactly like
    /// `<name>.git.json`.
    fn goal_path(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived).join(format!("{name}.goal.json"))
    }
    /// `<root>/<name>.fork.json` (or under `archived/`) — P4e (§1.6
    /// obligation-6 "fork-to-new-file WITH provenance", CX shape): the
    /// [`ForkProvenance`] record for a session created via [`Self::fork`].
    /// Absent for a session that was never forked (the overwhelmingly
    /// common case).
    fn fork_path(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived).join(format!("{name}.fork.json"))
    }
    /// `<root>/<name>.tree.json` (or under `archived/`) — P5-5 (design §2
    /// module 21 `session.tree`, §2.1 D-6): the persisted
    /// [`supercode_interchange::session_tree::SessionTree`] — the full in-place tree (every
    /// node of every branch), typed and lossless. Absent for a session that
    /// never invoked a tree operation (rewind/branch/label) — the
    /// overwhelmingly common, degenerate-single-path case; the plain
    /// `<name>.jsonl` transcript alone already IS that session's complete
    /// record, so no sidecar is ever created for it, keeping default-off
    /// behavior byte-identical to pre-P5-5.
    fn tree_path(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived).join(format!("{name}.tree.json"))
    }
    /// `<root>/<name>.journal.jsonl` (or under `archived/`) — BP-8
    /// (catalog:150 "Append-only durable transcript", catalog:154
    /// "Queued-prompt persistence", catalog:156 "Todos/plan persisted per
    /// session"): the append-only, flush-per-record operation log
    /// (`crate::session_journal`). Absent for a session whose config never
    /// armed it (`[core.session] append_only`), which is every pre-BP-8
    /// caller — the plain `<name>.jsonl` transcript alone stays that
    /// session's complete record.
    fn journal_path_in(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived).join(format!("{name}.journal.jsonl"))
    }
    /// `<root>/<name>.plan.json` (or under `archived/`) — BP-8
    /// (catalog:156): the session's current `update_plan` checklist, the
    /// folded head of the journal's `plan` records, written so a reader
    /// that only wants the plan does not have to replay the whole log.
    fn plan_path_in(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived).join(format!("{name}.plan.json"))
    }
    /// Claude runtime-state manifest reconstructed at import time. Kept as a
    /// separate family member so scheduling/control-plane state is never
    /// flattened into the provider-visible message transcript.
    fn claude_runtime_path(&self, name: &str, archived: bool) -> PathBuf {
        self.dir(archived)
            .join(format!("{name}.claude-runtime.json"))
    }
    /// `<root>/<name>.subagents/` (or under `archived/`) — P5-3 (design §2
    /// module 9 D5 "subagent transcripts"): the directory holding one
    /// `<child_id>.sidecar.jsonl` (the D5 transcript) + one
    /// `<child_id>.lineage.json` (the typed [`crate::subagents::SubagentLineage`]
    /// record) pair per child natively spawned under this parent session —
    /// the D5 analog of Claude Code's own `<stem>/subagents/agent-*.jsonl`
    /// on-disk convention (`supercode_interchange::session::subagents_dir_for`), but for
    /// sessions THIS store owns rather than an imported CC transcript.
    fn subagents_dir(&self, parent_name: &str, archived: bool) -> PathBuf {
        self.dir(archived).join(format!("{parent_name}.subagents"))
    }
    fn subagent_transcript_path(
        &self,
        parent_name: &str,
        child_id: &str,
        archived: bool,
    ) -> PathBuf {
        self.subagents_dir(parent_name, archived)
            .join(format!("{child_id}.sidecar.jsonl"))
    }
    fn subagent_lineage_path(&self, parent_name: &str, child_id: &str, archived: bool) -> PathBuf {
        self.subagents_dir(parent_name, archived)
            .join(format!("{child_id}.lineage.json"))
    }
    fn dir(&self, archived: bool) -> PathBuf {
        if archived {
            self.root.join("archived")
        } else {
            self.root.clone()
        }
    }

    /// The path a sidecar for `name` lives (or would live) at:
    /// `<root>/<name>.sidecar.jsonl`. Does not validate `name` or touch the
    /// filesystem — like the private `transcript_path`/`meta_path` helpers,
    /// it's the read/write methods (`save_sidecar`, `load_sidecar`, and
    /// `Agent::resume_recorded`'s caller) that enforce `validate_name` before
    /// any I/O happens.
    pub fn sidecar_path(&self, name: &str) -> PathBuf {
        self.sidecar_path_in(name, false)
    }

    /// The active reduction-log path for `name`. Like [`Self::sidecar_path`],
    /// this is a path projection only; callers that read or write must still
    /// go through the validated store methods.
    pub fn reduction_log_path(&self, name: &str) -> Result<PathBuf> {
        Self::validate_name(name)?;
        Ok(self.reduction_path(name, false))
    }

    /// Canonical active transcript location for a validated session name.
    /// The file need not exist yet; runtime registration uses this to report
    /// where the SDK owner will persist successful turns.
    pub fn session_path(&self, name: &str) -> Result<PathBuf> {
        Self::validate_name(name)?;
        Ok(self.transcript_path(name, false))
    }

    /// Exact active/archive transcript path. Unlike [`Self::session_path`],
    /// this preserves an explicit archived-family selection.
    pub fn session_path_for(&self, name: &str, archived: bool) -> Result<PathBuf> {
        Self::validate_name(name)?;
        Ok(self.transcript_path(name, archived))
    }

    /// Exact active/archive native-v2 sidecar path.
    pub fn sidecar_path_for(&self, name: &str, archived: bool) -> Result<PathBuf> {
        Self::validate_name(name)?;
        Ok(self.sidecar_path_in(name, archived))
    }

    /// Exact active/archive stored-child sidecar path.
    pub fn subagent_transcript_path_for(
        &self,
        parent_name: &str,
        child_id: &str,
        archived: bool,
    ) -> Result<PathBuf> {
        Self::validate_name(parent_name)?;
        Self::validate_name(child_id)?;
        Ok(self.subagent_transcript_path(parent_name, child_id, archived))
    }

    /// Overwrite (or create) `<name>`'s sidecar file with `sidecar_jsonl`
    /// verbatim.
    pub fn save_sidecar(&self, name: &str, sidecar_jsonl: &str) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(false))?;
        std::fs::write(self.sidecar_path_in(name, false), sidecar_jsonl)?;
        Ok(())
    }

    /// Read `<name>`'s sidecar file (active or archived), if it exists.
    /// `None` when no sidecar has ever been recorded for this session (e.g.
    /// a plain, non-reduced resume).
    pub fn load_sidecar(&self, name: &str) -> Result<Option<String>> {
        Self::validate_name(name)?;
        let active = self.sidecar_path_in(name, false);
        let path = if active.exists() {
            active
        } else {
            self.sidecar_path_in(name, true)
        };
        if !path.exists() {
            return Ok(None);
        }
        Ok(Some(std::fs::read_to_string(path)?))
    }

    /// Read a sidecar from exactly the selected active/archive family.
    pub fn load_sidecar_from(&self, name: &str, archived: bool) -> Result<Option<String>> {
        Self::validate_name(name)?;
        let path = self.sidecar_path_in(name, archived);
        if !path.exists() {
            return Ok(None);
        }
        Ok(Some(std::fs::read_to_string(path)?))
    }

    /// Persist `<name>`'s [`ReductionLog`] (the stub index) as
    /// `<name>.reduction.json`.
    pub fn save_reduction_log(&self, name: &str, log: &ReductionLog) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(false))?;
        let json = serde_json::to_string(log).map_err(Error::Decode)?;
        std::fs::write(self.reduction_path(name, false), json)?;
        Ok(())
    }

    /// Read `<name>`'s [`ReductionLog`] (active or archived), if one has
    /// ever been saved.
    pub fn load_reduction_log(&self, name: &str) -> Result<Option<ReductionLog>> {
        Self::validate_name(name)?;
        let active = self.reduction_path(name, false);
        let path = if active.exists() {
            active
        } else {
            self.reduction_path(name, true)
        };
        if !path.exists() {
            return Ok(None);
        }
        let text = std::fs::read_to_string(path)?;
        Ok(Some(serde_json::from_str(&text).map_err(Error::Decode)?))
    }

    /// Read a reduction log from exactly the selected active/archive family.
    pub fn load_reduction_log_from(
        &self,
        name: &str,
        archived: bool,
    ) -> Result<Option<ReductionLog>> {
        Self::validate_name(name)?;
        let path = self.reduction_path(name, archived);
        if !path.exists() {
            return Ok(None);
        }
        let text = std::fs::read_to_string(path)?;
        Ok(Some(serde_json::from_str(&text).map_err(Error::Decode)?))
    }

    /// P4b: overwrite (or create) `<name>`'s usage log with `records`
    /// (bulk-write, like [`Self::save_reduction_log`] — not an incremental
    /// append — so a caller with the full in-memory
    /// [`crate::usage_log::UsageRecord`] list, e.g. [`crate::Agent::usage_records`],
    /// can persist it in one call).
    pub fn save_usage_log(
        &self,
        name: &str,
        records: &[crate::usage_log::UsageRecord],
    ) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(false))?;
        let jsonl = crate::usage_log::to_jsonl(records)?;
        std::fs::write(self.usage_path(name, false), jsonl)?;
        Ok(())
    }

    /// P4b: read `<name>`'s usage log (active or archived). Empty (not an
    /// error) when no usage log has ever been saved for this session.
    pub fn load_usage_log(&self, name: &str) -> Result<Vec<crate::usage_log::UsageRecord>> {
        Self::validate_name(name)?;
        let active = self.usage_path(name, false);
        let path = if active.exists() {
            active
        } else {
            self.usage_path(name, true)
        };
        if !path.exists() {
            return Ok(Vec::new());
        }
        crate::usage_log::from_jsonl(&std::fs::read_to_string(path)?)
    }

    /// BP-7 (catalog §4a "Goals"): write `<name>`'s standing objective.
    pub fn save_goal(&self, name: &str, goal: &crate::goals::GoalRecord) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(false))?;
        let json = serde_json::to_string_pretty(goal).map_err(crate::Error::Decode)?;
        std::fs::write(self.goal_path(name, false), json)?;
        Ok(())
    }

    /// BP-7: read `<name>`'s standing objective (active or archived).
    /// `None` when the session never set one.
    pub fn load_goal(&self, name: &str) -> Result<Option<crate::goals::GoalRecord>> {
        Self::validate_name(name)?;
        let active = self.goal_path(name, false);
        let path = if active.exists() {
            active
        } else {
            self.goal_path(name, true)
        };
        if !path.exists() {
            return Ok(None);
        }
        let text = std::fs::read_to_string(path)?;
        if text.trim().is_empty() {
            return Ok(None);
        }
        Ok(Some(
            serde_json::from_str(&text).map_err(crate::Error::Decode)?,
        ))
    }

    /// BP-7: drop `<name>`'s standing objective (both locations). A no-op
    /// when none was ever written.
    pub fn clear_goal(&self, name: &str) -> Result<()> {
        Self::validate_name(name)?;
        for archived in [false, true] {
            let p = self.goal_path(name, archived);
            if p.exists() {
                std::fs::remove_file(p)?;
            }
        }
        Ok(())
    }

    /// BP-7 (catalog §4a "Turn/step bracketing records"): overwrite (or
    /// create) `<name>`'s per-round-trip marker log — the
    /// `<name>.events.jsonl` family member this store has always reserved
    /// and swept but never had a writer for. Same bulk-write shape as
    /// [`Self::save_usage_log`], for a caller holding the full in-memory
    /// [`crate::turn_record::TurnRecord`] list (e.g.
    /// [`crate::Agent::turn_records`]).
    pub fn save_turn_records(
        &self,
        name: &str,
        records: &[crate::turn_record::TurnRecord],
    ) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(false))?;
        let jsonl = crate::turn_record::to_jsonl(records)?;
        std::fs::write(self.events_path(name, false), jsonl)?;
        Ok(())
    }

    /// BP-7: read `<name>`'s marker log (active or archived). Empty (not an
    /// error) when none has ever been written for this session.
    pub fn load_turn_records(&self, name: &str) -> Result<Vec<crate::turn_record::TurnRecord>> {
        Self::validate_name(name)?;
        let active = self.events_path(name, false);
        let path = if active.exists() {
            active
        } else {
            self.events_path(name, true)
        };
        if !path.exists() {
            return Ok(Vec::new());
        }
        crate::turn_record::from_jsonl(&std::fs::read_to_string(path)?)
    }

    /// P4c: overwrite (or create) `<name>`'s model-change log with
    /// `records` — same bulk-write shape as [`Self::save_usage_log`], for a
    /// caller with the full in-memory [`crate::model_change::ModelChangeRecord`]
    /// list (e.g. [`crate::Agent::model_change_records`]).
    pub fn save_model_change_log(
        &self,
        name: &str,
        records: &[crate::model_change::ModelChangeRecord],
    ) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(false))?;
        let jsonl = crate::model_change::to_jsonl(records)?;
        std::fs::write(self.model_change_path(name, false), jsonl)?;
        Ok(())
    }

    /// P4c: read `<name>`'s model-change log (active or archived). Empty
    /// (not an error) when no model-change log has ever been saved for this
    /// session — the overwhelmingly common case (`allow_switch = false`,
    /// the default, or a session that never switched models).
    pub fn load_model_change_log(
        &self,
        name: &str,
    ) -> Result<Vec<crate::model_change::ModelChangeRecord>> {
        Self::validate_name(name)?;
        let active = self.model_change_path(name, false);
        let path = if active.exists() {
            active
        } else {
            self.model_change_path(name, true)
        };
        if !path.exists() {
            return Ok(Vec::new());
        }
        crate::model_change::from_jsonl(&std::fs::read_to_string(path)?)
    }

    /// P4e (§1.6/§3.1 `core.session.git_metadata`): persist `<name>`'s
    /// captured git metadata as `<name>.git.json` — a single-record
    /// overwrite, like [`Self::save_reduction_log`], not an append.
    pub fn save_git_metadata(
        &self,
        name: &str,
        record: &crate::git_metadata::GitMetadataRecord,
    ) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(false))?;
        let json = crate::git_metadata::to_json(record)?;
        std::fs::write(self.git_metadata_path(name, false), json)?;
        Ok(())
    }

    /// P4e: read `<name>`'s captured git metadata (active or archived).
    /// `None` (not an error) when no git metadata was ever saved for this
    /// session — the default (`session_git_metadata = false`).
    pub fn load_git_metadata(
        &self,
        name: &str,
    ) -> Result<Option<crate::git_metadata::GitMetadataRecord>> {
        Self::validate_name(name)?;
        let active = self.git_metadata_path(name, false);
        let path = if active.exists() {
            active
        } else {
            self.git_metadata_path(name, true)
        };
        if !path.exists() {
            return Ok(None);
        }
        Ok(Some(crate::git_metadata::from_json(
            &std::fs::read_to_string(path)?,
        )?))
    }

    /// Save (or overwrite) a session's transcript JSONL and title.
    pub fn save(&self, name: &str, title: &str, transcript_jsonl: &str) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(false))?;
        std::fs::write(self.transcript_path(name, false), transcript_jsonl)?;
        let info = SessionInfo {
            name: name.to_string(),
            title: title.to_string(),
            archived: false,
            ..Default::default()
        };
        std::fs::write(
            self.meta_path(name, false),
            serde_json::to_string(&info).map_err(Error::Decode)?,
        )?;
        Ok(())
    }

    /// Read a session's transcript JSONL (active or archived).
    pub fn load(&self, name: &str) -> Result<String> {
        Self::validate_name(name)?;
        let active = self.transcript_path(name, false);
        let path = if active.exists() {
            active
        } else {
            self.transcript_path(name, true)
        };
        Ok(std::fs::read_to_string(path)?)
    }

    /// Read a transcript from exactly the selected active/archive family.
    pub fn load_from(&self, name: &str, archived: bool) -> Result<String> {
        Self::validate_name(name)?;
        Ok(std::fs::read_to_string(
            self.transcript_path(name, archived),
        )?)
    }

    /// Read a transcript from exactly the selected family when its directory
    /// entry exists, preserving [`Self::load_if_present`]'s error semantics.
    pub fn load_if_present_from(&self, name: &str, archived: bool) -> Result<Option<String>> {
        Self::validate_name(name)?;
        let path = self.transcript_path(name, archived);
        match std::fs::symlink_metadata(&path) {
            Ok(_) => Ok(Some(std::fs::read_to_string(path)?)),
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
            Err(error) => Err(error.into()),
        }
    }

    /// Read a session's transcript JSONL when a transcript directory entry
    /// exists (active or archived).
    ///
    /// Unlike [`Self::transcript_mtime`], this distinguishes genuine absence
    /// from metadata/read failures. A dangling symlink, directory in place of
    /// the transcript, permission failure, or any other present-but-unreadable
    /// entry is an error rather than `None`.
    pub fn load_if_present(&self, name: &str) -> Result<Option<String>> {
        Self::validate_name(name)?;
        for archived in [false, true] {
            let path = self.transcript_path(name, archived);
            match std::fs::symlink_metadata(&path) {
                Ok(_) => return Ok(Some(std::fs::read_to_string(path)?)),
                Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
                Err(e) => return Err(e.into()),
            }
        }
        Ok(None)
    }

    /// List all sessions (active and archived).
    pub fn list(&self) -> Vec<SessionInfo> {
        let mut out = Vec::new();
        for archived in [false, true] {
            let dir = self.dir(archived);
            let Ok(rd) = std::fs::read_dir(&dir) else {
                continue;
            };
            for entry in rd.flatten() {
                let p = entry.path();
                if p.extension().and_then(|e| e.to_str()) != Some("json") {
                    continue;
                }
                // `*.meta.json`
                if !p.to_string_lossy().ends_with(".meta.json") {
                    continue;
                }
                if let Ok(text) = std::fs::read_to_string(&p) {
                    if let Ok(mut info) = serde_json::from_str::<SessionInfo>(&text) {
                        info.archived = archived;
                        out.push(info);
                    }
                }
            }
        }
        out.sort_by(|a, b| a.name.cmp(&b.name));
        out
    }

    /// Move a session into the archive: the whole `<name>.*` family (D1) —
    /// transcript, meta, sidecar, reduction log, and event log — tolerating
    /// any member that doesn't exist (e.g. a session never recorded in
    /// reduced mode has no sidecar/reduction/events file).
    pub fn archive(&self, name: &str) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(true))?;
        for (from, to) in [
            (
                self.transcript_path(name, false),
                self.transcript_path(name, true),
            ),
            (self.meta_path(name, false), self.meta_path(name, true)),
            (
                self.sidecar_path_in(name, false),
                self.sidecar_path_in(name, true),
            ),
            (
                self.reduction_path(name, false),
                self.reduction_path(name, true),
            ),
            (self.events_path(name, false), self.events_path(name, true)),
            (self.usage_path(name, false), self.usage_path(name, true)),
            (
                self.model_change_path(name, false),
                self.model_change_path(name, true),
            ),
            (
                self.git_metadata_path(name, false),
                self.git_metadata_path(name, true),
            ),
            (self.goal_path(name, false), self.goal_path(name, true)),
            (self.fork_path(name, false), self.fork_path(name, true)),
            (self.tree_path(name, false), self.tree_path(name, true)),
            (
                self.journal_path_in(name, false),
                self.journal_path_in(name, true),
            ),
            (
                self.plan_path_in(name, false),
                self.plan_path_in(name, true),
            ),
            (
                self.claude_runtime_path(name, false),
                self.claude_runtime_path(name, true),
            ),
        ] {
            if from.exists() {
                std::fs::rename(&from, &to)?;
            }
        }
        // P5-3 (D5 "folded into archive… like other session sidecars"): the
        // `<name>.subagents/` directory is a WHOLE-DIRECTORY member of the
        // family — moved as a unit (not file-by-file) since its member
        // count varies per session.
        let subagents_from = self.subagents_dir(name, false);
        if subagents_from.exists() {
            std::fs::rename(&subagents_from, self.subagents_dir(name, true))?;
        }
        Ok(())
    }

    /// Permanently delete a session (active or archived): the whole
    /// `<name>.*` family (D1) — a delete that left a full-fidelity sidecar
    /// behind would be a data-retention surprise. Tolerates any member that
    /// doesn't exist.
    pub fn delete(&self, name: &str) -> Result<()> {
        Self::validate_name(name)?;
        for archived in [false, true] {
            for p in [
                self.transcript_path(name, archived),
                self.meta_path(name, archived),
                self.sidecar_path_in(name, archived),
                self.reduction_path(name, archived),
                self.events_path(name, archived),
                self.usage_path(name, archived),
                self.model_change_path(name, archived),
                self.git_metadata_path(name, archived),
                self.goal_path(name, archived),
                self.fork_path(name, archived),
                self.tree_path(name, archived),
                self.journal_path_in(name, archived),
                self.plan_path_in(name, archived),
                self.claude_runtime_path(name, archived),
            ] {
                if p.exists() {
                    std::fs::remove_file(p)?;
                }
            }
            // P5-3 (D5 "…delete… like other session sidecars"): the whole
            // `<name>.subagents/` directory, active and archived.
            let subagents_dir = self.subagents_dir(name, archived);
            if subagents_dir.exists() {
                std::fs::remove_dir_all(&subagents_dir)?;
            }
        }
        Ok(())
    }

    /// Rename the human-readable title of a session, preserving its other
    /// recorded stats (`reduced`, `tier`, byte/stub counts, ...) rather than
    /// resetting them to defaults.
    pub fn set_title(&self, name: &str, title: &str) -> Result<()> {
        Self::validate_name(name)?;
        for archived in [false, true] {
            let mp = self.meta_path(name, archived);
            if mp.exists() {
                let mut info: SessionInfo = std::fs::read_to_string(&mp)
                    .ok()
                    .and_then(|t| serde_json::from_str(&t).ok())
                    .unwrap_or_else(|| SessionInfo {
                        name: name.to_string(),
                        ..Default::default()
                    });
                info.title = title.to_string();
                info.archived = archived;
                std::fs::write(&mp, serde_json::to_string(&info).map_err(Error::Decode)?)?;
                return Ok(());
            }
        }
        Err(Error::Other(format!("no session named `{name}`")))
    }

    /// The store's root directory.
    pub fn root(&self) -> &Path {
        &self.root
    }

    /// The transcript file's mtime (active or archived), if it exists.
    ///
    /// Legacy session names embed a creation timestamp (`<tag>-<micros>`),
    /// so callers could derive age/order from the name alone. UX-25's
    /// memorable names (`<tag>-<adjective>-<noun>`) carry no timestamp, so
    /// callers that need one — ordering `sessions list`, resolving
    /// `--continue`/`--last` — fall back to this instead.
    pub fn transcript_mtime(&self, name: &str) -> Option<std::time::SystemTime> {
        Self::validate_name(name).ok()?;
        let active = self.transcript_path(name, false);
        let path = if active.exists() {
            active
        } else {
            self.transcript_path(name, true)
        };
        std::fs::metadata(path).ok()?.modified().ok()
    }

    /// Record (or update) a session's reduced-mode stats (C1/C9):
    /// `reduced = true` plus the full/view byte counts and stub count.
    /// Creates `<name>.meta.json` with `title` if it doesn't exist yet (so a
    /// reduced-mode `resume` is visible to `sessions list` even before any
    /// plain transcript has been saved for it under this name); otherwise
    /// preserves the existing title/archived flag, like [`Self::set_title`].
    pub fn set_reduction_stats(
        &self,
        name: &str,
        title: &str,
        full_bytes: u64,
        view_bytes: u64,
        stub_count: u32,
    ) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(false))?;
        let mp = self.meta_path(name, false);
        let mut info: SessionInfo = std::fs::read_to_string(&mp)
            .ok()
            .and_then(|t| serde_json::from_str(&t).ok())
            .unwrap_or_else(|| SessionInfo {
                name: name.to_string(),
                title: title.to_string(),
                ..Default::default()
            });
        info.reduced = true;
        info.full_bytes = full_bytes;
        info.view_bytes = view_bytes;
        info.stub_count = stub_count;
        std::fs::write(&mp, serde_json::to_string(&info).map_err(Error::Decode)?)?;
        Ok(())
    }

    /// P4e (§1.6 obligation-6 "fork-to-new-file WITH provenance", CX shape:
    /// "linear store, fork copies + truncation"): copy session `from`'s
    /// transcript into a NEW session `to`, optionally truncated to the
    /// first `truncate_at_message` lines (each line is one message; `None`
    /// is a full, byte-identical copy — the pre-P4e `sessions fork`
    /// behavior), and persist a [`ForkProvenance`] record for `to` (typed,
    /// lossless per §1.13: an auditor/translator can always recover exactly
    /// which session and message offset a fork came from). Does NOT touch
    /// `from` at all -- the source session's own full fidelity is
    /// unaffected regardless of whether `to` is truncated.
    pub fn fork(
        &self,
        from: &str,
        to: &str,
        title: &str,
        truncate_at_message: Option<usize>,
        timestamp_ms: i64,
    ) -> Result<ForkProvenance> {
        Self::validate_name(from)?;
        Self::validate_name(to)?;
        let jsonl = self.load(from)?;
        if let Some(n) = truncate_at_message {
            Self::validate_safe_truncation(&jsonl, n)?;
        }
        let content = match truncate_at_message {
            Some(n) => {
                let lines: Vec<&str> = jsonl.lines().take(n).collect();
                if lines.is_empty() {
                    String::new()
                } else {
                    let mut s = lines.join("\n");
                    s.push('\n');
                    s
                }
            }
            None => jsonl,
        };
        self.save(to, title, &content)?;

        // DEFECT-4 fix (independent Fable-5 review of P4e): copy the whole
        // `<name>.*` sidecar family so a fork of a REDUCED session stays
        // expandable (§1.13 lossless: the fork doc claims lossless, but a
        // fork that dropped the sidecar left dangling `.sidecar.jsonl`/
        // `.reduction.json` references). Always copied WHOLE — even when
        // `truncate_at_message` shortens the transcript — because the
        // sidecar/logs are the full-fidelity source of truth the (possibly
        // truncated) transcript is only ever a PROJECTION of; truncating
        // them to match the transcript would throw away exactly the data
        // `/expand`/handoff need to reconstruct anything beyond the cut
        // line. `validate_safe_truncation` above is what keeps a truncated
        // fork coherent instead: it refuses a cut that would leave the
        // transcript ending on a dangling tool_call, so the transcript
        // itself is always a valid, replayable prefix regardless of how
        // much of the sidecar's fuller history now sits "ahead" of it.
        self.copy_family_member(from, to, Self::sidecar_path_in)?;
        self.copy_family_member(from, to, Self::reduction_path)?;
        self.copy_family_member(from, to, Self::usage_path)?;
        self.copy_family_member(from, to, Self::model_change_path)?;
        self.copy_family_member(from, to, Self::git_metadata_path)?;
        // P5-5: the `.tree.json` sidecar (if this session ever branched) is
        // a full-fidelity family member too — copied whole, same rationale
        // as the sidecar/reduction-log copies just above (the possibly
        // truncated transcript is only ever a projection of it).
        self.copy_family_member(from, to, Self::tree_path)?;
        self.copy_family_member(from, to, Self::claude_runtime_path)?;

        let provenance = ForkProvenance {
            forked_from: from.to_string(),
            forked_at_message: truncate_at_message,
            timestamp_ms,
        };
        self.save_fork_provenance(to, &provenance)?;
        Ok(provenance)
    }

    /// DEFECT-4 fix: copy one member of the `<name>.*` sidecar family from
    /// `from` to `to`'s ACTIVE location (a fresh fork always lands active,
    /// never pre-archived), reading `from`'s active copy if present, else
    /// its archived one — mirrors every other member accessor's
    /// active-or-archived fallback (`load_sidecar`, `load_reduction_log`,
    /// ...). A no-op (not an error) when `from` never recorded this member
    /// at all, matching [`Self::archive`]/[`Self::delete`]'s tolerance.
    fn copy_family_member(
        &self,
        from: &str,
        to: &str,
        path_of: impl Fn(&Self, &str, bool) -> PathBuf,
    ) -> Result<()> {
        let active = path_of(self, from, false);
        let src = if active.exists() {
            active
        } else {
            let archived = path_of(self, from, true);
            if !archived.exists() {
                return Ok(());
            }
            archived
        };
        std::fs::create_dir_all(self.dir(false))?;
        std::fs::copy(&src, path_of(self, to, false))?;
        Ok(())
    }

    /// DEFECT-4 fix: refuse a `--at n` fork whose cut point would leave the
    /// truncated transcript ending on an assistant `tool_calls` message
    /// whose tool-result reply (or replies, for a parallel batch) falls at
    /// or past `n` — i.e. a dangling tool_call with no matching tool
    /// message in the kept prefix. Such a transcript is neither a valid
    /// provider request (an assistant tool_calls turn MUST be followed by
    /// matching tool results before the next real turn) nor safely
    /// `/expand`-able. `n == 0` (an empty fork) and any `n` that lands on a
    /// clean turn boundary both pass trivially.
    fn validate_safe_truncation(jsonl: &str, n: usize) -> Result<()> {
        let kept: Vec<supercode_interchange::ChatMessage> = jsonl
            .lines()
            .take(n)
            .filter(|l| !l.trim().is_empty())
            .map(|l| serde_json::from_str(l).map_err(Error::Decode))
            .collect::<Result<_>>()?;
        let mut pending: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();
        for m in &kept {
            if let Some(calls) = &m.tool_calls {
                for c in calls {
                    pending.insert(c.id.clone());
                }
            }
            if let Some(id) = &m.tool_call_id {
                pending.remove(id);
            }
        }
        if !pending.is_empty() {
            return Err(Error::Other(format!(
                "fork --at {n} would cut off {} unresolved tool_call result(s) ({}) — \
                 choose a boundary at or after the assistant's tool_calls message AND \
                 all of its tool results",
                pending.len(),
                pending.into_iter().collect::<Vec<_>>().join(", "),
            )));
        }
        Ok(())
    }

    /// Persist `<name>`'s [`ForkProvenance`] as `<name>.fork.json` —
    /// overwrite semantics, like [`Self::save_reduction_log`].
    pub fn save_fork_provenance(&self, name: &str, provenance: &ForkProvenance) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(false))?;
        let json = serde_json::to_string(provenance).map_err(Error::Decode)?;
        std::fs::write(self.fork_path(name, false), json)?;
        Ok(())
    }

    /// Read `<name>`'s [`ForkProvenance`] (active or archived). `None`
    /// (not an error) when `<name>` was never created via [`Self::fork`].
    pub fn load_fork_provenance(&self, name: &str) -> Result<Option<ForkProvenance>> {
        Self::validate_name(name)?;
        let active = self.fork_path(name, false);
        let path = if active.exists() {
            active
        } else {
            self.fork_path(name, true)
        };
        if !path.exists() {
            return Ok(None);
        }
        Ok(Some(
            serde_json::from_str(&std::fs::read_to_string(path)?).map_err(Error::Decode)?,
        ))
    }

    /// P5-5 (design §2 module 21 `session.tree`, §1.6 "typed session data …
    /// folded into archive/delete/list"): persist `<name>`'s
    /// [`supercode_interchange::session_tree::SessionTree`] as `<name>.tree.json` —
    /// overwrite semantics, like [`Self::save_reduction_log`].
    pub fn save_tree(
        &self,
        name: &str,
        tree: &supercode_interchange::session_tree::SessionTree,
    ) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(false))?;
        let json = serde_json::to_string(tree).map_err(Error::Decode)?;
        std::fs::write(self.tree_path(name, false), json)?;
        Ok(())
    }

    /// Persist the non-executing Claude runtime manifest as a member of this
    /// session's sidecar family.
    pub fn save_claude_runtime_manifest(
        &self,
        name: &str,
        manifest: &crate::claude_runtime_state::ClaudeRuntimeManifest,
    ) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(false))?;
        let json = serde_json::to_string(manifest).map_err(Error::Decode)?;
        std::fs::write(self.claude_runtime_path(name, false), json)?;
        Ok(())
    }

    /// Load a Claude runtime manifest from the active or archived family.
    pub fn load_claude_runtime_manifest(
        &self,
        name: &str,
    ) -> Result<Option<crate::claude_runtime_state::ClaudeRuntimeManifest>> {
        Self::validate_name(name)?;
        let active = self.claude_runtime_path(name, false);
        let path = if active.exists() {
            active
        } else {
            self.claude_runtime_path(name, true)
        };
        if !path.exists() {
            return Ok(None);
        }
        Ok(Some(
            serde_json::from_str(&std::fs::read_to_string(path)?).map_err(Error::Decode)?,
        ))
    }

    /// Load a Claude runtime manifest from exactly the selected family.
    pub fn load_claude_runtime_manifest_from(
        &self,
        name: &str,
        archived: bool,
    ) -> Result<Option<crate::claude_runtime_state::ClaudeRuntimeManifest>> {
        Self::validate_name(name)?;
        let path = self.claude_runtime_path(name, archived);
        if !path.exists() {
            return Ok(None);
        }
        Ok(Some(
            serde_json::from_str(&std::fs::read_to_string(path)?).map_err(Error::Decode)?,
        ))
    }

    /// Read `<name>`'s [`supercode_interchange::session_tree::SessionTree`] (active or
    /// archived). `None` (not an error) when no tree operation was ever
    /// persisted for this session — the default, degenerate-single-path
    /// case (see `Self::tree_path`'s doc comment).
    pub fn load_tree(
        &self,
        name: &str,
    ) -> Result<Option<supercode_interchange::session_tree::SessionTree>> {
        Self::validate_name(name)?;
        let active = self.tree_path(name, false);
        let path = if active.exists() {
            active
        } else {
            self.tree_path(name, true)
        };
        if !path.exists() {
            return Ok(None);
        }
        Ok(Some(
            serde_json::from_str(&std::fs::read_to_string(path)?).map_err(Error::Decode)?,
        ))
    }

    /// P5-3 (design §2 module 9 D5 "subagent transcripts"): persist a
    /// natively-spawned child's full sidecar (native-v2 JSONL, typically
    /// [`supercode_interchange::session::Session::to_native_jsonl_v2`]'s output, carrying
    /// the child's own lineage header — see that method's doc comment) at
    /// `<parent_name>.subagents/<child_id>.sidecar.jsonl`. `child_id` is
    /// validated exactly like a top-level session name (it becomes a file
    /// stem too) — same path-traversal floor as `Self::validate_name`.
    pub fn save_subagent_transcript(
        &self,
        parent_name: &str,
        child_id: &str,
        sidecar_jsonl: &str,
    ) -> Result<()> {
        Self::validate_name(parent_name)?;
        Self::validate_name(child_id)?;
        std::fs::create_dir_all(self.subagents_dir(parent_name, false))?;
        std::fs::write(
            self.subagent_transcript_path(parent_name, child_id, false),
            sidecar_jsonl,
        )?;
        Ok(())
    }

    /// Persist every subagent attached to an imported [`supercode_interchange::session::Session`]
    /// into this store's existing `<parent_name>.subagents/` family.
    ///
    /// Each child is wrapped in native-v2 before it is written, so its
    /// foreign-harness `raw` body survives a later process/disk reload
    /// byte-for-byte. All ids are validated (and duplicates rejected) before
    /// the first write: an import with incomplete lineage must fail loudly
    /// instead of silently dropping or overwriting a child transcript.
    pub fn save_imported_subagents(
        &self,
        parent_name: &str,
        subagents: &[supercode_interchange::session::Session],
    ) -> Result<usize> {
        Self::validate_name(parent_name)?;

        let mut seen = std::collections::BTreeSet::new();
        for child in subagents {
            let child_id = child.meta.agent_id.as_deref().ok_or_else(|| {
                Error::Other(format!(
                    "cannot persist an imported subagent for `{parent_name}` without an agent id"
                ))
            })?;
            Self::validate_name(child_id)?;
            if !seen.insert(child_id.to_string()) {
                return Err(Error::Other(format!(
                    "duplicate imported subagent id `{child_id}` for `{parent_name}`"
                )));
            }
        }

        // Serialize/write one at a time: real Claude sessions can have
        // hundreds of MiB of child logs, so retaining a second in-memory
        // copy of every child at once would defeat the resume path this
        // helper exists to support.
        for child in subagents {
            let child_id = child.meta.agent_id.as_deref().expect("validated above");
            self.save_subagent_transcript(parent_name, child_id, &child.to_native_jsonl_v2(&[]))?;
        }
        Ok(subagents.len())
    }

    /// Read a child's sidecar (active or archived). `None` when this
    /// `(parent_name, child_id)` pair was never saved.
    pub fn load_subagent_transcript(
        &self,
        parent_name: &str,
        child_id: &str,
    ) -> Result<Option<String>> {
        Self::validate_name(parent_name)?;
        Self::validate_name(child_id)?;
        let active = self.subagent_transcript_path(parent_name, child_id, false);
        let path = if active.exists() {
            active
        } else {
            self.subagent_transcript_path(parent_name, child_id, true)
        };
        if !path.exists() {
            return Ok(None);
        }
        Ok(Some(std::fs::read_to_string(path)?))
    }

    /// Read a child sidecar from exactly the selected parent family.
    pub fn load_subagent_transcript_from(
        &self,
        parent_name: &str,
        child_id: &str,
        archived: bool,
    ) -> Result<Option<String>> {
        Self::validate_name(parent_name)?;
        Self::validate_name(child_id)?;
        let path = self.subagent_transcript_path(parent_name, child_id, archived);
        if !path.exists() {
            return Ok(None);
        }
        Ok(Some(std::fs::read_to_string(path)?))
    }

    /// P5-3: persist a child's typed [`crate::subagents::SubagentLineage`]
    /// record at `<parent_name>.subagents/<child_id>.lineage.json` —
    /// overwrite semantics, like [`Self::save_reduction_log`].
    pub fn save_subagent_lineage(
        &self,
        parent_name: &str,
        child_id: &str,
        record: &crate::subagents::SubagentLineage,
    ) -> Result<()> {
        Self::validate_name(parent_name)?;
        Self::validate_name(child_id)?;
        std::fs::create_dir_all(self.subagents_dir(parent_name, false))?;
        let json = serde_json::to_string(record).map_err(Error::Decode)?;
        std::fs::write(
            self.subagent_lineage_path(parent_name, child_id, false),
            json,
        )?;
        Ok(())
    }

    /// Read a child's lineage record (active or archived). `None` when this
    /// `(parent_name, child_id)` pair was never saved.
    pub fn load_subagent_lineage(
        &self,
        parent_name: &str,
        child_id: &str,
    ) -> Result<Option<crate::subagents::SubagentLineage>> {
        Self::validate_name(parent_name)?;
        Self::validate_name(child_id)?;
        let active = self.subagent_lineage_path(parent_name, child_id, false);
        let path = if active.exists() {
            active
        } else {
            self.subagent_lineage_path(parent_name, child_id, true)
        };
        if !path.exists() {
            return Ok(None);
        }
        Ok(Some(
            serde_json::from_str(&std::fs::read_to_string(path)?).map_err(Error::Decode)?,
        ))
    }

    /// P5-3: every child id natively spawned under `parent_name` (active AND
    /// archived, deduped and sorted) — discovered from the `.sidecar.jsonl`
    /// members of `Self::subagents_dir`, the same "list what's on disk"
    /// posture [`Self::list`] uses for top-level sessions.
    pub fn list_subagent_ids(&self, parent_name: &str) -> Result<Vec<String>> {
        Self::validate_name(parent_name)?;
        let mut ids = std::collections::BTreeSet::new();
        for archived in [false, true] {
            let dir = self.subagents_dir(parent_name, archived);
            let Ok(rd) = std::fs::read_dir(&dir) else {
                continue;
            };
            for entry in rd.flatten() {
                let p = entry.path();
                if let Some(name) = p.file_name().and_then(|n| n.to_str()) {
                    if let Some(id) = name.strip_suffix(".sidecar.jsonl") {
                        ids.insert(id.to_string());
                    }
                }
            }
        }
        Ok(ids.into_iter().collect())
    }

    /// List child ids from exactly the selected active/archive family.
    pub fn list_subagent_ids_from(&self, parent_name: &str, archived: bool) -> Result<Vec<String>> {
        Self::validate_name(parent_name)?;
        let mut ids = std::collections::BTreeSet::new();
        let dir = self.subagents_dir(parent_name, archived);
        let Ok(rd) = std::fs::read_dir(&dir) else {
            return Ok(Vec::new());
        };
        for entry in rd.flatten() {
            let p = entry.path();
            if let Some(name) = p.file_name().and_then(|n| n.to_str()) {
                if let Some(id) = name.strip_suffix(".sidecar.jsonl") {
                    ids.insert(id.to_string());
                }
            }
        }
        Ok(ids.into_iter().collect())
    }

    // ---- BP-8: the append-only journal (catalog:150/154/156) ------------

    /// The journal path for `name` — `<root>/<name>.journal.jsonl`.
    pub fn journal_path(&self, name: &str) -> Result<PathBuf> {
        Self::validate_name(name)?;
        Ok(self.journal_path_in(name, false))
    }

    /// Open (creating if absent) `name`'s append-only journal for writing.
    pub fn open_journal(&self, name: &str) -> Result<crate::session_journal::SessionJournal> {
        Self::validate_name(name)?;
        crate::session_journal::SessionJournal::open_append(&self.journal_path_in(name, false))
    }

    /// Replay `name`'s journal (active or archived). `None` when the
    /// session never had one — every pre-BP-8 session, and every session
    /// whose config left `[core.session] append_only` off.
    pub fn load_journal(&self, name: &str) -> Result<Option<crate::session_journal::JournalState>> {
        Self::validate_name(name)?;
        for archived in [false, true] {
            let path = self.journal_path_in(name, archived);
            if path.exists() {
                return crate::session_journal::replay(&path);
            }
        }
        Ok(None)
    }

    /// Write `name`'s current plan (the folded head of the journal's `plan`
    /// records) as `<name>.plan.json`.
    pub fn save_plan(&self, name: &str, plan: &[crate::session_journal::PlanEntry]) -> Result<()> {
        Self::validate_name(name)?;
        std::fs::create_dir_all(self.dir(false))?;
        std::fs::write(
            self.plan_path_in(name, false),
            serde_json::to_string(plan).map_err(Error::Decode)?,
        )?;
        Ok(())
    }

    /// Read `name`'s persisted plan (active or archived), if any.
    pub fn load_plan(&self, name: &str) -> Result<Option<Vec<crate::session_journal::PlanEntry>>> {
        Self::validate_name(name)?;
        for archived in [false, true] {
            let path = self.plan_path_in(name, archived);
            if path.exists() {
                let text = std::fs::read_to_string(path)?;
                return Ok(Some(serde_json::from_str(&text).map_err(Error::Decode)?));
            }
        }
        Ok(None)
    }

    // ---- BP-8: rename (catalog:152 "Session naming/rename") -------------

    /// Change a session's RESUME HANDLE — the name every resume door takes
    /// — by moving its whole `<name>.*` family (D1) to the new stem, in
    /// whichever of the active/archived directories it lives in.
    ///
    /// This is the half [`Self::set_title`] is not: `set_title` changes the
    /// display string only, and a session found by its old handle after a
    /// title change is the same session. A rename moves the handle itself,
    /// so it must move every family member atomically enough that a
    /// half-renamed session is never left behind — hence the up-front
    /// collision check (any `<to>.*` member existing at all refuses) rather
    /// than discovering the clash halfway through the moves.
    pub fn rename(&self, from: &str, to: &str) -> Result<()> {
        Self::validate_name(from)?;
        Self::validate_name(to)?;
        if from == to {
            return Ok(());
        }
        let mut moves: Vec<(PathBuf, PathBuf)> = Vec::new();
        let mut found = false;
        for archived in [false, true] {
            let dir = self.dir(archived);
            let Ok(rd) = std::fs::read_dir(&dir) else {
                continue;
            };
            for entry in rd.flatten() {
                let file = entry.file_name();
                let Some(file) = file.to_str() else { continue };
                // `<stem>.` prefix: session stems never contain a `.`, so
                // this can only match this session's own family members
                // (`<name>.jsonl`, `<name>.meta.json`, `<name>.subagents/`, …).
                let Some(suffix) = file.strip_prefix(&format!("{from}.")) else {
                    continue;
                };
                found = true;
                let target = dir.join(format!("{to}.{suffix}"));
                if target.exists() {
                    return Err(Error::Other(format!(
                        "cannot rename `{from}` to `{to}`: `{}` already exists",
                        target.display()
                    )));
                }
                moves.push((entry.path(), target));
            }
        }
        if !found {
            return Err(Error::Other(format!("no session named `{from}`")));
        }
        for (src, dst) in &moves {
            std::fs::rename(src, dst)?;
        }
        // The meta carries the name as data too; a renamed session that
        // still reported its old name to `list` would be a split brain.
        for archived in [false, true] {
            let mp = self.meta_path(to, archived);
            if mp.exists() {
                if let Some(mut info) = std::fs::read_to_string(&mp)
                    .ok()
                    .and_then(|t| serde_json::from_str::<SessionInfo>(&t).ok())
                {
                    info.name = to.to_string();
                    info.archived = archived;
                    std::fs::write(&mp, serde_json::to_string(&info).map_err(Error::Decode)?)?;
                }
            }
        }
        // The rename is itself a session event: record it in the (moved)
        // journal so the handle's history is recoverable from the log.
        if self.journal_path_in(to, false).exists() {
            let mut journal = self.open_journal(to)?;
            journal.append(crate::session_journal::JournalOp::Rename {
                from: from.to_string(),
                to: to.to_string(),
            })?;
        }
        self.invalidate_index();
        Ok(())
    }

    // ---- BP-8: format versioning + in-place upgrade (catalog:153) --------

    /// The generation THIS build writes. A session whose meta carries this
    /// value is already in the current on-disk shape and
    /// [`Self::upgrade_in_place`] does nothing for it.
    pub const FORMAT_VERSION: u32 = 2;

    /// The generation `name`'s stored family is at. `0` means the meta
    /// carries no marker at all — every session written before BP-8.
    pub fn format_version(&self, name: &str) -> u32 {
        self.list()
            .into_iter()
            .find(|s| s.name == name)
            .map(|s| s.format_version)
            .unwrap_or(0)
    }

    /// Upgrade `name`'s stored transcript IN PLACE to
    /// [`Self::FORMAT_VERSION`], and stamp the marker so no later read
    /// repeats the work.
    ///
    /// **Reversible.** The original bytes are copied verbatim to
    /// `<name>.v<old>.jsonl` BEFORE anything is rewritten, so the
    /// pre-upgrade file is always recoverable; the rewrite itself is a
    /// per-line [`crate::ChatMessage`] round-trip, which drops keys this
    /// build does not model and normalizes the ones it does — never
    /// collapsing multimodal parts into text or otherwise changing what the
    /// line MEANS.
    ///
    /// Returns `None` when the session is already current (or has no
    /// transcript) — that `None` is the whole point of the marker: the
    /// tolerant path is paid once, not on every read.
    pub fn upgrade_in_place(&self, name: &str) -> Result<Option<FormatUpgrade>> {
        Self::validate_name(name)?;
        let current = self.format_version(name);
        if current >= Self::FORMAT_VERSION {
            return Ok(None);
        }
        let (path, archived) = {
            let active = self.transcript_path(name, false);
            if active.exists() {
                (active, false)
            } else {
                let arch = self.transcript_path(name, true);
                if !arch.exists() {
                    return Ok(None);
                }
                (arch, true)
            }
        };
        let original = std::fs::read_to_string(&path)?;
        let mut upgraded = String::with_capacity(original.len());
        let mut lines = 0usize;
        for line in original.lines() {
            if line.trim().is_empty() {
                continue;
            }
            let msg: crate::ChatMessage =
                serde_json::from_str(line.trim()).map_err(Error::Decode)?;
            if lines > 0 {
                upgraded.push('\n');
            }
            upgraded.push_str(&serde_json::to_string(&msg).map_err(Error::Decode)?);
            lines += 1;
        }
        let backup_name = format!("{name}.v{current}.jsonl");
        let backup = self.dir(archived).join(&backup_name);
        // Preserve first, rewrite second: an interruption between the two
        // leaves the original intact under both names, never neither.
        std::fs::write(&backup, original.as_bytes())?;
        let rewritten = upgraded != original;
        if rewritten {
            std::fs::write(&path, upgraded.as_bytes())?;
        }
        self.set_format_version(name, Self::FORMAT_VERSION)?;
        if self.journal_path_in(name, false).exists() {
            let mut journal = self.open_journal(name)?;
            journal.append(crate::session_journal::JournalOp::Upgrade {
                from_version: current,
                to_version: Self::FORMAT_VERSION,
                original: backup_name.clone(),
            })?;
        }
        self.invalidate_index();
        Ok(Some(FormatUpgrade {
            from_version: current,
            to_version: Self::FORMAT_VERSION,
            original: backup_name,
            messages: lines,
            rewritten,
        }))
    }

    /// Stamp the format marker on `name`'s meta, preserving every other
    /// recorded field (same posture as [`Self::set_title`]).
    pub fn set_format_version(&self, name: &str, version: u32) -> Result<()> {
        Self::validate_name(name)?;
        for archived in [false, true] {
            let mp = self.meta_path(name, archived);
            if mp.exists() {
                let mut info: SessionInfo = std::fs::read_to_string(&mp)
                    .ok()
                    .and_then(|t| serde_json::from_str(&t).ok())
                    .unwrap_or_else(|| SessionInfo {
                        name: name.to_string(),
                        ..Default::default()
                    });
                info.format_version = version;
                info.archived = archived;
                std::fs::write(&mp, serde_json::to_string(&info).map_err(Error::Decode)?)?;
                return Ok(());
            }
        }
        Err(Error::Other(format!("no session named `{name}`")))
    }

    // ---- BP-8: the derived index cache (catalog:151) ---------------------

    /// `<root>/.session-index.json` — the derived listing cache. Never a
    /// session name (it starts with a dot, which [`Self::validate_name`]
    /// rejects) and never a `*.meta.json`, so [`Self::list`] cannot see it.
    pub fn index_path(&self) -> PathBuf {
        self.root.join(".session-index.json")
    }

    /// Delete the derived index. Purely a cache drop: the next
    /// [`Self::index`] rebuilds an identical answer from the transcripts,
    /// which remain the only record.
    pub fn invalidate_index(&self) {
        let _ = std::fs::remove_file(self.index_path());
    }

    /// The fast listing: title, age-ordering time, message count and a
    /// first-user-line preview for every session, WITHOUT reading each
    /// transcript on every call.
    ///
    /// The transcripts stay authoritative. Each cached row carries the
    /// `(mtime, size)` of the transcript it was derived from; a row whose
    /// validator still matches is reused, and any row that does not (or is
    /// missing) is re-derived by reading that one file. The cache is then
    /// written back. Deleting [`Self::index_path`] therefore changes
    /// nothing except how much work the next call does — which is exactly
    /// what makes it a cache and not a second source of truth.
    pub fn index(&self) -> SessionIndex {
        let cached: std::collections::HashMap<String, SessionIndexEntry> =
            std::fs::read_to_string(self.index_path())
                .ok()
                .and_then(|t| serde_json::from_str::<SessionIndexFile>(&t).ok())
                .filter(|f| f.version == SESSION_INDEX_VERSION)
                .map(|f| f.entries.into_iter().map(|e| (e.name.clone(), e)).collect())
                .unwrap_or_default();
        let mut out = SessionIndex::default();
        for info in self.list() {
            let path = self.transcript_path(&info.name, info.archived);
            let (mtime_nanos, size) = match std::fs::metadata(&path) {
                Ok(m) => (
                    m.modified()
                        .ok()
                        .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
                        .map(|d| d.as_nanos() as u64)
                        .unwrap_or(0),
                    m.len(),
                ),
                Err(_) => (0, 0),
            };
            match cached.get(&info.name) {
                Some(hit)
                    if hit.mtime_nanos == mtime_nanos
                        && hit.size == size
                        && hit.archived == info.archived
                        && hit.title == info.title =>
                {
                    out.reused += 1;
                    out.entries.push(hit.clone());
                }
                _ => {
                    out.rederived += 1;
                    out.entries
                        .push(self.derive_index_entry(&info, mtime_nanos, size));
                }
            }
        }
        out.entries
            .sort_by(|a, b| b.time_secs.cmp(&a.time_secs).then(a.name.cmp(&b.name)));
        let file = SessionIndexFile {
            version: SESSION_INDEX_VERSION,
            entries: out.entries.clone(),
        };
        // Never CREATES the root: addressing a store must not bring one
        // into existence (see `SessionStore::at`), and a listing is a read.
        if self.root.is_dir() {
            if let Ok(text) = serde_json::to_string(&file) {
                let _ = std::fs::write(self.index_path(), text);
            }
        }
        out
    }

    fn derive_index_entry(
        &self,
        info: &SessionInfo,
        mtime_nanos: u64,
        size: u64,
    ) -> SessionIndexEntry {
        let text = self
            .load_if_present_from(&info.name, info.archived)
            .ok()
            .flatten()
            .unwrap_or_default();
        let mut messages = 0usize;
        let mut preview = String::new();
        for line in text.lines() {
            if line.trim().is_empty() {
                continue;
            }
            messages += 1;
            if preview.is_empty() {
                if let Ok(msg) = serde_json::from_str::<crate::ChatMessage>(line.trim()) {
                    if msg.role == crate::Role::User {
                        if let Some(c) = msg.content.as_deref() {
                            preview = preview_line(c);
                        }
                    }
                }
            }
        }
        SessionIndexEntry {
            name: info.name.clone(),
            title: info.title.clone(),
            archived: info.archived,
            time_secs: derive_session_time(&info.name, mtime_nanos / 1_000_000),
            preview,
            messages,
            mtime_nanos,
            size,
        }
    }

    /// P4e (§1.6/§3.1 `core.session.retention_days`): permanently delete
    /// every ARCHIVED session (never an active one — retention is a
    /// post-archive concern, matching every peer harness) whose transcript
    /// is older than `retention_days` days as of `now`. Returns the names
    /// deleted (empty if nothing was old enough, or `retention_days == 0`
    /// which this treats as "prune nothing" rather than "prune
    /// everything" -- an explicit, non-surprising floor).
    pub fn prune_expired(
        &self,
        retention_days: u32,
        now: std::time::SystemTime,
    ) -> Result<Vec<String>> {
        if retention_days == 0 {
            return Ok(Vec::new());
        }
        let Some(cutoff) = now.checked_sub(std::time::Duration::from_secs(
            retention_days as u64 * 86_400,
        )) else {
            return Ok(Vec::new());
        };
        let mut pruned = Vec::new();
        for info in self.list() {
            if !info.archived {
                continue;
            }
            let Some(mtime) = self.transcript_mtime(&info.name) else {
                continue;
            };
            if mtime < cutoff {
                self.delete(&info.name)?;
                pruned.push(info.name);
            }
        }
        Ok(pruned)
    }
}

/// BP-8: what [`SessionStore::upgrade_in_place`] did.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FormatUpgrade {
    /// The generation the file was at (`0` = unmarked).
    pub from_version: u32,
    /// The generation it is at now.
    pub to_version: u32,
    /// Store-relative file holding the ORIGINAL bytes verbatim.
    pub original: String,
    /// Messages in the upgraded transcript.
    pub messages: usize,
    /// Whether the transcript bytes actually changed (a file already in
    /// today's shape is only STAMPED, never rewritten).
    pub rewritten: bool,
}

/// BP-8: the derived-index cache format version.
pub const SESSION_INDEX_VERSION: u32 = 1;

/// One cached listing row — see [`SessionStore::index`].
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct SessionIndexEntry {
    /// Session name (the resume handle).
    pub name: String,
    /// Display title.
    pub title: String,
    /// Whether the session is archived.
    pub archived: bool,
    /// Seconds since the epoch used to order "newest first".
    pub time_secs: u64,
    /// First user line, truncated — the picker's preview.
    pub preview: String,
    /// Messages in the transcript.
    pub messages: usize,
    /// Validator: transcript mtime in unix-NANOSECONDS at derivation time.
    /// Nanoseconds, not milliseconds: two writes inside one millisecond
    /// that happen to produce the same byte count would otherwise validate
    /// a stale row.
    pub mtime_nanos: u64,
    /// Validator: transcript size in bytes at derivation time.
    pub size: u64,
}

/// The listing plus how it was obtained (how many rows came from the cache
/// and how many had to be re-derived) — the counters make "this really is
/// read-repaired, not re-read from scratch" a checkable claim.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct SessionIndex {
    /// Rows, newest first.
    pub entries: Vec<SessionIndexEntry>,
    /// Rows served from the cache without opening the transcript.
    pub reused: usize,
    /// Rows re-derived from the transcript this call.
    pub rederived: usize,
}

#[derive(Serialize, Deserialize)]
struct SessionIndexFile {
    version: u32,
    entries: Vec<SessionIndexEntry>,
}

/// The "when was this session last active" rule, in one place so the store
/// and its callers cannot drift: a legacy `<tag>-<micros>` name carries its
/// own creation time, and everything else falls back to the transcript's
/// mtime.
pub fn derive_session_time(name: &str, mtime_ms: u64) -> u64 {
    if let Some(micros) = name.rsplit('-').next().and_then(|s| s.parse::<u128>().ok()) {
        return (micros / 1_000_000) as u64;
    }
    mtime_ms / 1000
}

/// One-line, length-capped preview of a message body.
fn preview_line(content: &str) -> String {
    let line = content.lines().find(|l| !l.trim().is_empty()).unwrap_or("");
    let line = line.trim();
    if line.chars().count() <= 80 {
        return line.to_string();
    }
    let truncated: String = line.chars().take(79).collect();
    format!("{truncated}…")
}

/// P4e (§1.6 obligation-6 "fork-to-new-file WITH provenance") — see
/// [`SessionStore::fork`].
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ForkProvenance {
    /// The session name this fork was copied from.
    pub forked_from: String,
    /// If the fork was truncated, how many leading messages it kept.
    /// `None` means a full, untruncated copy.
    #[serde(default)]
    pub forked_at_message: Option<usize>,
    /// Unix-ms wall-clock time the fork was created.
    #[serde(default)]
    pub timestamp_ms: i64,
}