supercode/

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,
}

/// 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 CLI-owned
    /// event log (C8). No reader/writer lives here yet; only the lifecycle
    /// sweep (`archive`/`delete`) needs to know its name (D1).
    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>.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
    /// [`crate::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"))
    }
    /// 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 (`crate::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)
    }

    /// 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)?)
    }

    /// 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.fork_path(name, false), self.fork_path(name, true)),
            (self.tree_path(name, false), self.tree_path(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.fork_path(name, archived),
                self.tree_path(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<crate::message::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
    /// [`crate::session_tree::SessionTree`] as `<name>.tree.json` —
    /// overwrite semantics, like [`Self::save_reduction_log`].
    pub fn save_tree(&self, name: &str, tree: &crate::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 [`crate::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<crate::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
    /// [`crate::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 [`crate::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: &[crate::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())
    }

    /// 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)
    }
}

/// 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,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn addressing_a_store_does_not_create_its_root() {
        let tmp = std::env::temp_dir().join(format!(
            "sc-store-address-only-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        let store = SessionStore::at(&tmp);
        assert_eq!(store.root(), tmp);
        assert!(!tmp.exists());
        assert!(store.list().is_empty());
        assert!(!tmp.exists());
    }

    #[test]
    fn rejects_path_traversal_names() {
        let tmp = std::env::temp_dir().join(format!("sc-store-test-{}", std::process::id()));
        let store = SessionStore::open(&tmp).unwrap();
        for bad in ["../escape", "..", "a/b", "/abs", "", "  ", ".", "x\0y"] {
            assert!(store.save(bad, "t", "{}").is_err(), "should reject `{bad}`");
            assert!(store.load(bad).is_err(), "should reject load `{bad}`");
            assert!(store.delete(bad).is_err(), "should reject delete `{bad}`");
        }
        // A normal name still works and stays inside the root.
        store.save("ok-name", "t", "{}").unwrap();
        assert!(tmp.join("ok-name.jsonl").exists());
        // Nothing escaped the root.
        assert!(!tmp.parent().unwrap().join("escape.jsonl").exists());
        let _ = std::fs::remove_dir_all(&tmp);
    }

    fn temp_store() -> (SessionStore, std::path::PathBuf) {
        use std::sync::atomic::{AtomicU64, Ordering};
        static N: AtomicU64 = AtomicU64::new(0);
        let tmp = std::env::temp_dir().join(format!(
            "sc-store-model-change-{}-{}",
            std::process::id(),
            N.fetch_add(1, Ordering::SeqCst)
        ));
        (SessionStore::open(&tmp).unwrap(), tmp)
    }

    /// P4c (S1.10, "round-trip losslessly through the store" — the explicit
    /// item-9 proof requirement): a saved `model_change` log survives a
    /// save/load round trip byte-for-byte in every field.
    #[test]
    fn model_change_log_round_trips_losslessly_through_the_store() {
        let (store, tmp) = temp_store();
        store.save("sess", "t", "[]").unwrap();
        let records = vec![
            crate::model_change::ModelChangeRecord::new(
                0,
                "vendor/model-a",
                "vendor/model-b",
                true,
                4,
                1_700_000_000_000,
            ),
            crate::model_change::ModelChangeRecord::new(
                5,
                "vendor/model-b",
                "vendor/model-c",
                true,
                0,
                1_700_000_050_000,
            ),
        ];
        store.save_model_change_log("sess", &records).unwrap();
        let loaded = store.load_model_change_log("sess").unwrap();
        assert_eq!(loaded, records);
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// A session that never switched models has an empty (not missing/error)
    /// model-change log — the overwhelmingly common case.
    #[test]
    fn model_change_log_is_empty_when_never_saved() {
        let (store, tmp) = temp_store();
        store.save("sess", "t", "[]").unwrap();
        assert_eq!(store.load_model_change_log("sess").unwrap(), Vec::new());
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// The `<name>.model_change.jsonl` sidecar is part of the `<name>.*`
    /// family: `archive`/`delete` move/remove it exactly like every other
    /// member (usage log, reduction log, sidecar, events).
    #[test]
    fn model_change_log_travels_with_archive_and_is_removed_by_delete() {
        let (store, tmp) = temp_store();
        store.save("sess", "t", "[]").unwrap();
        let records = vec![crate::model_change::ModelChangeRecord::new(
            0, "a", "b", true, 1, 1,
        )];
        store.save_model_change_log("sess", &records).unwrap();
        assert!(tmp.join("sess.model_change.jsonl").exists());

        store.archive("sess").unwrap();
        assert!(!tmp.join("sess.model_change.jsonl").exists());
        assert!(tmp.join("archived/sess.model_change.jsonl").exists());
        // Still readable after archiving.
        assert_eq!(store.load_model_change_log("sess").unwrap(), records);

        store.delete("sess").unwrap();
        assert!(!tmp.join("archived/sess.model_change.jsonl").exists());
        assert_eq!(store.load_model_change_log("sess").unwrap(), Vec::new());
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// P4e (§1.13 "round-trip losslessly through the store"): a saved
    /// `GitMetadataRecord` survives a save/load round trip byte-for-byte.
    #[test]
    fn git_metadata_round_trips_losslessly_through_the_store() {
        let (store, tmp) = temp_store();
        store.save("sess", "t", "[]").unwrap();
        let record = crate::git_metadata::GitMetadataRecord {
            branch: Some("main".to_string()),
            sha: Some("deadbeef".to_string()),
            dirty: true,
            captured_at_ms: 1_700_000_000_000,
        };
        store.save_git_metadata("sess", &record).unwrap();
        assert_eq!(store.load_git_metadata("sess").unwrap(), Some(record));
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// A session with `session_git_metadata` off (the default) never gets a
    /// `.git.json` file, and loading it back is `None`, not an error.
    #[test]
    fn git_metadata_is_none_when_never_saved() {
        let (store, tmp) = temp_store();
        store.save("sess", "t", "[]").unwrap();
        assert_eq!(store.load_git_metadata("sess").unwrap(), None);
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// The `<name>.git.json` sidecar travels with `archive`/is removed by
    /// `delete`, exactly like every other `<name>.*` family member.
    #[test]
    fn git_metadata_travels_with_archive_and_is_removed_by_delete() {
        let (store, tmp) = temp_store();
        store.save("sess", "t", "[]").unwrap();
        let record = crate::git_metadata::GitMetadataRecord {
            branch: Some("main".to_string()),
            sha: None,
            dirty: false,
            captured_at_ms: 1,
        };
        store.save_git_metadata("sess", &record).unwrap();
        assert!(tmp.join("sess.git.json").exists());

        store.archive("sess").unwrap();
        assert!(!tmp.join("sess.git.json").exists());
        assert!(tmp.join("archived/sess.git.json").exists());
        assert_eq!(store.load_git_metadata("sess").unwrap(), Some(record));

        store.delete("sess").unwrap();
        assert!(!tmp.join("archived/sess.git.json").exists());
        assert_eq!(store.load_git_metadata("sess").unwrap(), None);
        let _ = std::fs::remove_dir_all(&tmp);
    }

    // -------------------------------------------------------------------
    // P5-3 (design §2 module 9 D5 "subagent transcripts"): the
    // `<name>.subagents/` family member.
    // -------------------------------------------------------------------

    fn sample_lineage(child_id: &str) -> crate::subagents::SubagentLineage {
        crate::subagents::SubagentLineage {
            child_agent_id: child_id.to_string(),
            parent_session_id: Some("parent-sess".to_string()),
            parent_tool_use_id: "call_1".to_string(),
            depth: 1,
            agent_type: Some("researcher".to_string()),
            task: "investigate the flaky test".to_string(),
            background: false,
            spawned_at_ms: 1_700_000_000_000,
            model: "vendor/model-a".to_string(),
        }
    }

    /// §1.13 lossless round trip: a saved [`crate::subagents::SubagentLineage`]
    /// survives a save/load cycle byte-for-byte in every field.
    #[test]
    fn subagent_lineage_round_trips_losslessly_through_the_store() {
        let (store, tmp) = temp_store();
        store.save("parent-sess", "t", "[]").unwrap();
        let record = sample_lineage("agent-1");
        store
            .save_subagent_lineage("parent-sess", "agent-1", &record)
            .unwrap();
        assert_eq!(
            store
                .load_subagent_lineage("parent-sess", "agent-1")
                .unwrap(),
            Some(record)
        );
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// A child transcript saved via `save_subagent_transcript` round-trips
    /// byte-for-byte AND parses back through `Session::from_native_str`
    /// (proving the whole native-write pipeline — lineage header included —
    /// not just the store's own byte plumbing).
    #[test]
    fn subagent_transcript_round_trips_and_parses_back_with_lineage() {
        let (store, tmp) = temp_store();
        store.save("parent-sess", "t", "[]").unwrap();

        let mut session = crate::session::Session::from_claude_code_str("").unwrap();
        session.meta.agent_id = Some("agent-1".to_string());
        session.meta.parent_tool_use_id = Some("call_1".to_string());
        session
            .meta
            .lineage
            .insert("parent_thread_id".to_string(), "parent-sess".to_string());
        session
            .meta
            .lineage
            .insert("depth".to_string(), "1".to_string());
        let appended = vec![crate::message::ChatMessage::user("hello from the child")];
        let sidecar_jsonl = session.to_native_jsonl_v2(&appended);

        store
            .save_subagent_transcript("parent-sess", "agent-1", &sidecar_jsonl)
            .unwrap();
        let loaded = store
            .load_subagent_transcript("parent-sess", "agent-1")
            .unwrap()
            .expect("just saved");
        assert_eq!(loaded, sidecar_jsonl);

        let parsed = crate::session::Session::from_native_str(&loaded).unwrap();
        assert_eq!(parsed.meta.agent_id.as_deref(), Some("agent-1"));
        assert_eq!(parsed.meta.parent_tool_use_id.as_deref(), Some("call_1"));
        assert_eq!(
            parsed.meta.lineage.get("parent_thread_id"),
            Some(&"parent-sess".to_string())
        );
        assert_eq!(
            parsed.messages.last().and_then(|m| m.content.as_deref()),
            Some("hello from the child")
        );

        assert_eq!(
            store.list_subagent_ids("parent-sess").unwrap(),
            vec!["agent-1".to_string()]
        );
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// Imported Claude child logs use the same store family as native
    /// children, but retain their foreign raw body inside native-v2. Prove
    /// the real process boundary: close/reopen the store, parse the wrapper,
    /// and recover CRLF/trailing-whitespace source bytes exactly.
    #[test]
    fn imported_subagents_survive_disk_reload_with_verbatim_source_bytes() {
        let (store, tmp) = temp_store();
        let original = concat!(
            "{\"type\":\"user\",\"sessionId\":\"parent\",\"agentId\":\"child-7\",\"uuid\":\"u1\",\"parentUuid\":null,\"message\":{\"role\":\"user\",\"content\":\"inspect it\"}}  \r\n",
            "{\"type\":\"queue-operation\",\"operation\":\"dequeue\"}"
        );
        let mut child = crate::session::Session::from_claude_code_str(original).unwrap();
        child.meta.agent_id = Some("child-7".to_string());
        child.meta.parent_tool_use_id = Some("toolu_task_7".to_string());

        assert_eq!(
            store
                .save_imported_subagents("parent-sess", &[child])
                .unwrap(),
            1
        );
        drop(store);

        let reopened = SessionStore::open(&tmp).unwrap();
        let native = reopened
            .load_subagent_transcript("parent-sess", "child-7")
            .unwrap()
            .expect("imported child persisted");
        let loaded = crate::session::Session::from_sidecar_str(&native).unwrap();
        assert_eq!(
            loaded.meta.source,
            crate::session::SessionSource::ClaudeCode
        );
        assert_eq!(loaded.meta.agent_id.as_deref(), Some("child-7"));
        assert_eq!(
            loaded.meta.parent_tool_use_id.as_deref(),
            Some("toolu_task_7")
        );
        assert_eq!(loaded.raw_verbatim(), original);
        assert!(loaded.raw_is_verbatim);

        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// Validate the complete imported child id set before writing anything,
    /// so a duplicate cannot silently overwrite the first transcript.
    #[test]
    fn imported_subagent_duplicate_ids_fail_before_any_write() {
        let (store, tmp) = temp_store();
        let mut first = crate::session::Session::from_claude_code_str("{}").unwrap();
        first.meta.agent_id = Some("same".to_string());
        let second = first.clone();

        assert!(store
            .save_imported_subagents("parent-sess", &[first, second])
            .unwrap_err()
            .to_string()
            .contains("duplicate imported subagent id"));
        assert!(!tmp.join("parent-sess.subagents").exists());

        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// The whole `<name>.subagents/` directory travels with `archive` and is
    /// removed by `delete`, exactly like every other `<name>.*` family
    /// member (D5 "folded into archive/delete/list").
    #[test]
    fn subagent_family_travels_with_archive_and_is_removed_by_delete() {
        let (store, tmp) = temp_store();
        store.save("parent-sess", "t", "[]").unwrap();
        store
            .save_subagent_lineage("parent-sess", "agent-1", &sample_lineage("agent-1"))
            .unwrap();
        store
            .save_subagent_transcript("parent-sess", "agent-1", "{}\n")
            .unwrap();
        assert!(tmp
            .join("parent-sess.subagents/agent-1.lineage.json")
            .exists());
        assert!(tmp
            .join("parent-sess.subagents/agent-1.sidecar.jsonl")
            .exists());

        store.archive("parent-sess").unwrap();
        assert!(!tmp.join("parent-sess.subagents").exists());
        assert!(tmp
            .join("archived/parent-sess.subagents/agent-1.lineage.json")
            .exists());
        // Still readable (active-or-archived fallback) after archiving.
        assert_eq!(
            store.list_subagent_ids("parent-sess").unwrap(),
            vec!["agent-1".to_string()]
        );
        assert!(store
            .load_subagent_lineage("parent-sess", "agent-1")
            .unwrap()
            .is_some());

        store.delete("parent-sess").unwrap();
        assert!(!tmp.join("archived/parent-sess.subagents").exists());
        assert_eq!(
            store
                .load_subagent_lineage("parent-sess", "agent-1")
                .unwrap(),
            None
        );
        assert!(store.list_subagent_ids("parent-sess").unwrap().is_empty());
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// A session that never spawned any subagents has no `.subagents/`
    /// directory at all, and every accessor reports the empty/`None` case
    /// rather than erroring — the default-off, zero-cost posture.
    #[test]
    fn subagent_family_is_absent_by_default() {
        let (store, tmp) = temp_store();
        store.save("sess", "t", "[]").unwrap();
        assert_eq!(
            store.load_subagent_lineage("sess", "agent-1").unwrap(),
            None
        );
        assert_eq!(
            store.load_subagent_transcript("sess", "agent-1").unwrap(),
            None
        );
        assert!(store.list_subagent_ids("sess").unwrap().is_empty());
        assert!(!tmp.join("sess.subagents").exists());
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// Happy path: a full (untruncated) fork is a byte-identical copy of
    /// the source transcript, with a provenance record naming the source
    /// and `forked_at_message = None`.
    #[test]
    fn fork_full_copy_is_byte_identical_with_provenance() {
        let (store, tmp) = temp_store();
        let transcript = "{\"role\":\"user\"}\n{\"role\":\"assistant\"}\n";
        store.save("orig", "t", transcript).unwrap();
        let provenance = store
            .fork("orig", "copy", "fork of t", None, 1_700_000_000_000)
            .unwrap();
        assert_eq!(store.load("copy").unwrap(), transcript);
        assert_eq!(provenance.forked_from, "orig");
        assert_eq!(provenance.forked_at_message, None);
        assert_eq!(
            store.load_fork_provenance("copy").unwrap(),
            Some(provenance)
        );
        // The source is untouched.
        assert_eq!(store.load("orig").unwrap(), transcript);
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// Boundary: a truncated fork (CX shape: copy + truncation) keeps only
    /// the first N messages, and the provenance record honestly reports the
    /// truncation point so a reader can tell it's a partial fork.
    #[test]
    fn fork_with_truncation_keeps_only_leading_messages() {
        let (store, tmp) = temp_store();
        let transcript = "{\"role\":\"system\"}\n{\"role\":\"user\"}\n{\"role\":\"assistant\"}\n{\"role\":\"tool\"}\n";
        store.save("orig", "t", transcript).unwrap();
        let provenance = store
            .fork("orig", "partial", "partial fork", Some(2), 42)
            .unwrap();
        assert_eq!(
            store.load("partial").unwrap(),
            "{\"role\":\"system\"}\n{\"role\":\"user\"}\n"
        );
        assert_eq!(provenance.forked_at_message, Some(2));
        // The source retains every message — truncation only affects the
        // NEW fork, never the original.
        assert_eq!(store.load("orig").unwrap(), transcript);
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// A session never created via `fork` has no provenance record.
    #[test]
    fn fork_provenance_is_none_for_a_plain_session() {
        let (store, tmp) = temp_store();
        store.save("sess", "t", "[]").unwrap();
        assert_eq!(store.load_fork_provenance("sess").unwrap(), None);
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// `prune_expired` deletes only ARCHIVED sessions older than the
    /// retention window, leaving active sessions and fresh archives alone.
    #[test]
    fn prune_expired_deletes_only_old_archived_sessions() {
        let (store, tmp) = temp_store();
        store.save("old-archived", "t", "[]").unwrap();
        store.archive("old-archived").unwrap();
        store.save("fresh-archived", "t", "[]").unwrap();
        store.archive("fresh-archived").unwrap();
        store.save("active", "t", "[]").unwrap();

        // Back-date the old archived session's mtime well past any
        // reasonable retention window.
        let old_path = tmp.join("archived/old-archived.jsonl");
        let ancient = std::time::SystemTime::now() - std::time::Duration::from_secs(400 * 86_400);
        std::fs::OpenOptions::new()
            .write(true)
            .open(&old_path)
            .unwrap()
            .set_modified(ancient)
            .unwrap();

        let pruned = store
            .prune_expired(30, std::time::SystemTime::now())
            .unwrap();
        assert_eq!(pruned, vec!["old-archived".to_string()]);
        assert!(!old_path.exists());
        assert!(tmp.join("archived/fresh-archived.jsonl").exists());
        assert!(tmp.join("active.jsonl").exists());
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// `retention_days == 0` is an explicit "prune nothing" floor, not
    /// "prune everything" — a config typo must never nuke every archive.
    #[test]
    fn prune_expired_zero_days_prunes_nothing() {
        let (store, tmp) = temp_store();
        store.save("sess", "t", "[]").unwrap();
        store.archive("sess").unwrap();
        let pruned = store
            .prune_expired(0, std::time::SystemTime::now())
            .unwrap();
        assert!(pruned.is_empty());
        assert!(tmp.join("archived/sess.jsonl").exists());
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// Default-unchanged: an active (never-archived) session is never
    /// pruned, regardless of age.
    #[test]
    fn prune_expired_never_touches_active_sessions() {
        let (store, tmp) = temp_store();
        store.save("active", "t", "[]").unwrap();
        let ancient = std::time::SystemTime::now() - std::time::Duration::from_secs(400 * 86_400);
        std::fs::OpenOptions::new()
            .write(true)
            .open(tmp.join("active.jsonl"))
            .unwrap()
            .set_modified(ancient)
            .unwrap();
        let pruned = store
            .prune_expired(30, std::time::SystemTime::now())
            .unwrap();
        assert!(pruned.is_empty());
        assert!(tmp.join("active.jsonl").exists());
        let _ = std::fs::remove_dir_all(&tmp);
    }

    // -------------------------------------------------------------------
    // P5-5 (design §2 module 21 `session.tree`): the `<name>.tree.json`
    // family member.
    // -------------------------------------------------------------------

    fn sample_tree() -> crate::session_tree::SessionTree {
        let mut tree = crate::session_tree::SessionTree::from_linear(
            &[
                crate::message::ChatMessage::user("hello"),
                crate::message::ChatMessage::assistant("hi"),
            ],
            1_700_000_000_000,
        );
        tree.branch("n0", Some("side".to_string()), 1_700_000_001_000)
            .unwrap();
        tree.append_message(
            crate::message::ChatMessage::user("side turn"),
            1_700_000_002_000,
        );
        tree
    }

    /// §1.13 lossless round trip: a saved [`crate::session_tree::SessionTree`]
    /// — nodes, branches, and the active-branch pointer — survives a
    /// save/load cycle with every branch's linear projection intact.
    #[test]
    fn session_tree_round_trips_losslessly_through_the_store() {
        let (store, tmp) = temp_store();
        store.save("sess", "t", "[]").unwrap();
        let tree = sample_tree();
        store.save_tree("sess", &tree).unwrap();
        let loaded = store.load_tree("sess").unwrap().expect("just saved");

        assert_eq!(loaded.root, tree.root);
        assert_eq!(loaded.active_branch, tree.active_branch);
        assert_eq!(loaded.nodes.len(), tree.nodes.len());
        assert_eq!(
            loaded.linear_projection_of("main").unwrap().len(),
            tree.linear_projection_of("main").unwrap().len()
        );
        assert_eq!(
            loaded.linear_projection().unwrap().len(),
            tree.linear_projection().unwrap().len()
        );
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// F1 (HIGH, ported from the Fable-5 adversarial review's
    /// `attack_tree_sidecar_drops_message_metadata`): a rewound-past branch
    /// — whose messages have NO backing beyond the `.tree.json` sidecar — must
    /// keep `ChatMessage::metadata` through a save/load cycle. Before the
    /// fix, `TreeNode` persisted via `ChatMessage`'s custom wire `Serialize`
    /// (`message.rs:49-79`), which deliberately OMITS `metadata` — so this
    /// assertion FAILING (metadata empty) would mean the sidecar reverted to
    /// that lossy behavior.
    #[test]
    fn attack_tree_sidecar_preserves_message_metadata() {
        let (store, tmp) = temp_store();
        let mut m = crate::message::ChatMessage::user("turn with provenance");
        m.metadata
            .insert("phase".to_string(), "commentary".to_string());
        m.metadata
            .insert("turn_id".to_string(), "cx-turn-42".to_string());
        m.metadata
            .insert("pi_entry_id".to_string(), "entry-7".to_string());
        let mut tree = crate::session_tree::SessionTree::from_linear(
            &[m.clone(), crate::message::ChatMessage::assistant("ok")],
            1,
        );
        // Rewind so n0..n1 becomes an off-path preserved branch whose ONLY
        // persistent record is the .tree.json sidecar.
        let preserved = tree.rewind("n0", 2).unwrap().unwrap();
        store.save("s", "t", "").unwrap();
        store.save_tree("s", &tree).unwrap();
        let loaded = store.load_tree("s").unwrap().unwrap();
        let recovered = loaded.linear_projection_of(&preserved).unwrap();
        assert_eq!(recovered.len(), 2);
        // The metadata must have survived the sidecar round trip in full.
        assert_eq!(
            recovered[0].metadata.get("phase"),
            Some(&"commentary".to_string())
        );
        assert_eq!(
            recovered[0].metadata.get("turn_id"),
            Some(&"cx-turn-42".to_string())
        );
        assert_eq!(
            recovered[0].metadata.get("pi_entry_id"),
            Some(&"entry-7".to_string())
        );
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// F1 (HIGH, ported from the Fable-5 review's
    /// `attack_message_with_both_content_and_parts_loses_content_through_sidecar`):
    /// `ChatMessage`'s wire `Serialize` collapses `content` whenever
    /// `content_parts` is also set (parts win, plain string dropped) — the
    /// correct behavior for an OUTBOUND provider request, but wrong for this
    /// sidecar, which must keep both independently since it's the only
    /// durable record of an off-path branch. Before the fix this assertion
    /// (`content` surviving) would fail.
    #[test]
    fn attack_tree_sidecar_preserves_content_alongside_content_parts() {
        let (store, tmp) = temp_store();
        let mut m = crate::message::ChatMessage::user("plain content");
        m.content_parts = Some(vec![serde_json::json!({"type":"text","text":"part"})]);
        let tree = crate::session_tree::SessionTree::from_linear(&[m], 1);
        store.save("s", "t", "").unwrap();
        store.save_tree("s", &tree).unwrap();
        let loaded = store.load_tree("s").unwrap().unwrap();
        let got = &loaded.node("n0").unwrap().message;
        assert_eq!(got.content.as_deref(), Some("plain content"));
        assert_eq!(
            got.content_parts.as_ref().unwrap()[0]["text"],
            serde_json::json!("part")
        );
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// F1: a FULL-FIDELITY round trip, not just length/content/role (the gap
    /// that hid the original defect — `session_tree_round_trips_losslessly_through_the_store`
    /// above only ever compared `.len()`). Asserts `metadata` and
    /// `content_parts` field-for-field equality on every node after a
    /// save/load cycle.
    #[test]
    fn session_tree_round_trip_preserves_full_message_fidelity_not_just_length() {
        let (store, tmp) = temp_store();
        let mut m0 = crate::message::ChatMessage::user("hello");
        m0.metadata
            .insert("promptSource".to_string(), "cli".to_string());
        m0.metadata.insert("isMeta".to_string(), "true".to_string());
        let mut m1 = crate::message::ChatMessage::assistant("hi");
        m1.content_parts = Some(vec![
            serde_json::json!({"type": "text", "text": "hi"}),
            serde_json::json!({"type": "image_url", "image_url": {"url": "data:image/png;base64,AA"}}),
        ]);
        m1.metadata
            .insert("review_findings".to_string(), "none".to_string());
        let tree = crate::session_tree::SessionTree::from_linear(
            &[m0.clone(), m1.clone()],
            1_700_000_000_000,
        );
        store.save("s", "t", "").unwrap();
        store.save_tree("s", &tree).unwrap();
        let loaded = store.load_tree("s").unwrap().unwrap();

        let got0 = &loaded.node("n0").unwrap().message;
        assert_eq!(got0.content, m0.content);
        assert_eq!(got0.metadata, m0.metadata);
        assert_eq!(got0.content_parts, m0.content_parts);

        let got1 = &loaded.node("n1").unwrap().message;
        assert_eq!(got1.content, m1.content);
        assert_eq!(got1.metadata, m1.metadata);
        assert_eq!(got1.content_parts, m1.content_parts);

        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// Re-verification (Fable-5 review's `attack_tree_sidecar_save_load_save_is_byte_identical`):
    /// F1's serialization change (routing `TreeNode.message` through
    /// [`crate::sidecar::NativeTurn`] instead of `ChatMessage`'s own wire
    /// serde) must not break the sidecar's save→load→save byte-identity —
    /// in particular, `TreeNodeWire`'s `ts` field must be derived
    /// deterministically from the node's `created_at_ms`, NOT from
    /// wall-clock `now()` (which `NativeTurn::from(&ChatMessage)` normally
    /// stamps), or every reload-then-resave would produce different bytes.
    #[test]
    fn tree_sidecar_save_load_save_is_byte_identical_after_f1() {
        let (store, tmp) = temp_store();
        let mut tree = crate::session_tree::SessionTree::from_linear(
            &[
                crate::message::ChatMessage::user("a"),
                crate::message::ChatMessage::assistant("b"),
            ],
            1_700_000_000_000,
        );
        tree.branch("n0", Some("side".to_string()), 2).unwrap();
        tree.append_message(crate::message::ChatMessage::user("c"), 3);
        tree.label("n1", "checkpoint").unwrap();
        store.save("s", "t", "").unwrap();
        store.save_tree("s", &tree).unwrap();
        let bytes1 = std::fs::read(tmp.join("s.tree.json")).unwrap();
        let loaded = store.load_tree("s").unwrap().unwrap();
        store.save_tree("s", &loaded).unwrap();
        let bytes2 = std::fs::read(tmp.join("s.tree.json")).unwrap();
        assert_eq!(bytes1, bytes2);
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// Re-verification (Fable-5 review's `attack_corrupt_tree_json_errors_on_load`):
    /// unchanged by F1 — a corrupt or empty `.tree.json` must still ERROR
    /// on load, never panic or silently return `None`.
    #[test]
    fn corrupt_tree_json_still_errors_on_load_after_the_fixes() {
        let (store, tmp) = temp_store();
        store.save("s", "t", "").unwrap();
        std::fs::write(tmp.join("s.tree.json"), "{not json").unwrap();
        assert!(store.load_tree("s").is_err());
        std::fs::write(tmp.join("s.tree.json"), "").unwrap();
        assert!(store.load_tree("s").is_err());
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// A session that never invoked a tree operation has no `.tree.json`
    /// sidecar, and loading it back is `None`, not an error — the
    /// degenerate-single-path default.
    #[test]
    fn session_tree_is_absent_by_default() {
        let (store, tmp) = temp_store();
        store.save("sess", "t", "[]").unwrap();
        assert!(store.load_tree("sess").unwrap().is_none());
        assert!(!tmp.join("sess.tree.json").exists());
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// The `<name>.tree.json` sidecar travels with `archive`/is removed by
    /// `delete`, exactly like every other `<name>.*` family member (D5
    /// "folded into archive/delete/list").
    #[test]
    fn session_tree_travels_with_archive_and_is_removed_by_delete() {
        let (store, tmp) = temp_store();
        store.save("sess", "t", "[]").unwrap();
        store.save_tree("sess", &sample_tree()).unwrap();
        assert!(tmp.join("sess.tree.json").exists());

        store.archive("sess").unwrap();
        assert!(!tmp.join("sess.tree.json").exists());
        assert!(tmp.join("archived/sess.tree.json").exists());
        // Still readable after archiving.
        assert!(store.load_tree("sess").unwrap().is_some());

        store.delete("sess").unwrap();
        assert!(!tmp.join("archived/sess.tree.json").exists());
        assert!(store.load_tree("sess").unwrap().is_none());
        let _ = std::fs::remove_dir_all(&tmp);
    }

    /// A fork copies the source session's `.tree.json` sidecar whole (like
    /// the sidecar/reduction-log/usage/model-change/git-metadata members) —
    /// a fork of a branched session stays fully tree-addressable, not
    /// silently downgraded to linear-only.
    #[test]
    fn fork_copies_the_session_tree_sidecar() {
        let (store, tmp) = temp_store();
        let transcript = "{\"role\":\"user\"}\n";
        store.save("orig", "t", transcript).unwrap();
        store.save_tree("orig", &sample_tree()).unwrap();

        store
            .fork("orig", "copy", "fork of t", None, 1_700_000_000_000)
            .unwrap();
        let copied = store.load_tree("copy").unwrap().expect("copied");
        let orig = store.load_tree("orig").unwrap().unwrap();
        assert_eq!(copied.nodes.len(), orig.nodes.len());
        assert_eq!(copied.branches.len(), orig.branches.len());
        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn claude_runtime_manifest_roundtrips_and_travels_with_family_lifecycle() {
        let (store, tmp) = temp_store();
        store.save("sess", "t", "[]").unwrap();
        let source = concat!(
            "{\"type\":\"permission-mode\",\"permissionMode\":\"bypassPermissions\",",
            "\"timestamp\":\"2026-07-14T00:00:00Z\"}\n"
        );
        let session = crate::Session::from_claude_code_str(source).unwrap();
        let manifest =
            crate::claude_runtime_state::ClaudeRuntimeManifest::from_session(&session).unwrap();
        store
            .save_claude_runtime_manifest("sess", &manifest)
            .unwrap();
        assert_eq!(
            store.load_claude_runtime_manifest("sess").unwrap(),
            Some(manifest.clone())
        );

        store
            .fork("sess", "copy", "copy", None, 1_700_000_000_000)
            .unwrap();
        assert_eq!(
            store.load_claude_runtime_manifest("copy").unwrap(),
            Some(manifest.clone())
        );
        store.archive("sess").unwrap();
        assert!(!tmp.join("sess.claude-runtime.json").exists());
        assert!(tmp.join("archived/sess.claude-runtime.json").exists());
        assert_eq!(
            store.load_claude_runtime_manifest("sess").unwrap(),
            Some(manifest)
        );
        store.delete("sess").unwrap();
        assert!(store
            .load_claude_runtime_manifest("sess")
            .unwrap()
            .is_none());
        let _ = std::fs::remove_dir_all(&tmp);
    }
}