supercode_harness/

checkpoint.rs

//! §2 module 20 `checkpoint` (COMPOSABLE-HARNESS-DESIGN.md line 470): file
//! checkpointing / shadow-git; D4-adjacent revert; D3 turn-diff tracking.
//! Line 1504: "restores FILES, not context — pairs with, never replaces,
//! the reduction sidecar."
//!
//! **Not to be confused with** [`crate::Agent::checkpoint`]/[`crate::Agent::rewind_to`]
//! (an in-memory CONVERSATION-position marker, an unrelated pre-existing
//! facility) or [`supercode_interchange::session_tree`] (module 21, tree-addressable
//! sessions). This module only ever touches files on disk.
//!
//! # The write-path interception seam (D-5, shared with `formatters`/P5-11)
//! [`crate::tools::WriteObserver`] (defined in `crate::tools`, the seam's
//! natural owner since [`crate::tools::ToolContext`] carries it) is called
//! by `write_file`/`edit_file`/`apply_patch` around their mutation.
//! [`CheckpointObserver`] is this module's implementation: `before_write`
//! captures a pre-image; `after_write` is a no-op (reserved for
//! `formatters`).
//!
//! # Storage — never the user's real git
//! [`CheckpointStore`] is a content-addressed, per-project shadow store at
//! a caller-supplied `root` (the same dependency-injection shape as
//! [`crate::store::SessionStore::open`]) — blobs keyed by
//! [`crate::reduce::content_hash`] under `<root>/objects/`, one JSON
//! manifest per checkpoint under `<root>/checkpoints/<id>.json`. This
//! module never shells out to `git` and never touches the project's own
//! `.git` — there is no `GIT_DIR` to get wrong because none is ever used.
//!
//! # C8 (design line 1819) compliance
//! A [`CheckpointId`] is an opaque `String` — the ONLY thing a caller
//! (session record, CLI) ever threads around. It is never the file
//! contents, and it never reaches the model's context window: restoring
//! files is a disk operation, never a conversation-history mutation.

use std::collections::HashSet;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Mutex;

use serde::{Deserialize, Serialize};

use crate::error::{Error, Result};
use crate::tools::WriteObserver;

/// Default number of checkpoints retained per project before the oldest are
/// pruned (bounded-disk requirement) — overridable via
/// `[capabilities.checkpoint].retain`.
pub const DEFAULT_RETAIN: usize = 50;

/// An opaque, lexically-sortable (ascending = chronological, since it's
/// zero-padded-millis-prefixed) checkpoint identifier. This is ALL a
/// session record ever carries for C8 — never file contents.
pub type CheckpointId = String;

fn now_ms() -> u128 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_millis())
        .unwrap_or(0)
}

/// Mint a fresh id: zero-padded millis + an 8-hex-digit salt derived from
/// (pid, millis, a monotonic instant) — collision-free in practice without
/// pulling in a UUID/random dependency (matches this crate's existing
/// `shell_sentinel` precedent in `tools/builtins.rs`).
fn mint_id() -> CheckpointId {
    use std::hash::BuildHasher;
    let millis = now_ms();
    let salt = std::collections::hash_map::RandomState::new().hash_one((
        std::process::id(),
        millis,
        std::time::Instant::now(),
    ));
    format!("{millis:020}-{:08x}", salt as u32)
}

/// One file's entry in a [`CheckpointManifest`] — the turn-diff (D3) is
/// simply this manifest's `files` list.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CheckpointFileEntry {
    /// Path relative to the project root, `/`-separated, never absolute and
    /// never containing a `..` component in what [`CheckpointObserver`]
    /// itself writes (restore independently re-validates this — see
    /// [`CheckpointStore::restore`] — rather than trusting it).
    pub path: String,
    /// blake3 hex digest ([`crate::reduce::content_hash`]) of the pre-image
    /// content, or `None` if the file did not exist before this
    /// checkpoint's turn began (i.e. the write that follows is a create —
    /// restoring deletes it again).
    pub blob: Option<String>,
}

/// A checkpoint's full manifest — one JSON file per checkpoint.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CheckpointManifest {
    /// This checkpoint's id.
    pub id: CheckpointId,
    /// Unix-epoch milliseconds when this checkpoint was minted.
    pub created_at_ms: u128,
    /// A short, human-readable label (e.g. the turn's prompt excerpt) —
    /// display only, never re-parsed.
    pub label: String,
    /// Every file this turn captured a pre-image for — the D3 turn-diff.
    pub files: Vec<CheckpointFileEntry>,
}

/// Lightweight listing entry ([`CheckpointStore::list`]) — the manifest
/// without the (potentially long) file list.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CheckpointMeta {
    /// This checkpoint's id.
    pub id: CheckpointId,
    /// Unix-epoch milliseconds when this checkpoint was minted.
    pub created_at_ms: u128,
    /// A short, human-readable label — display only.
    pub label: String,
    /// How many files this checkpoint's manifest lists.
    pub file_count: usize,
}

/// The outcome of a [`CheckpointStore::restore`] call.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct RestoreReport {
    /// Files successfully restored (project-relative paths).
    pub restored: Vec<String>,
    /// Files refused, with the reason — e.g. an out-of-root or
    /// protected-path target. Non-empty means the restore was PARTIAL; a
    /// caller must surface this, never silently swallow it.
    pub refused: Vec<(String, String)>,
}

/// A directory-backed, content-addressed shadow store rooted at `root` —
/// see the module doc comment. Never touches anything outside `root` except
/// (during [`Self::restore`]) the project files a manifest names, which are
/// re-validated against `project_root` independently of how the manifest
/// was produced.
#[derive(Debug)]
pub struct CheckpointStore {
    root: PathBuf,
}

impl CheckpointStore {
    /// Open (creating if needed) a store at `root`. `Err` if `root` can't
    /// be created (e.g. an unwritable state dir) — callers (see
    /// [`observer_for_config`]) treat that as "disable checkpoint, warn
    /// once", never a crash.
    pub fn open(root: impl Into<PathBuf>) -> Result<Self> {
        let root = root.into();
        std::fs::create_dir_all(root.join("objects"))?;
        std::fs::create_dir_all(root.join("checkpoints"))?;
        Ok(CheckpointStore { root })
    }

    fn objects_dir(&self) -> PathBuf {
        self.root.join("objects")
    }
    fn checkpoints_dir(&self) -> PathBuf {
        self.root.join("checkpoints")
    }
    fn manifest_path(&self, id: &str) -> PathBuf {
        self.checkpoints_dir().join(format!("{id}.json"))
    }
    fn blob_path(&self, hash: &str) -> PathBuf {
        let prefix = &hash[..hash.len().min(2)];
        self.objects_dir().join(prefix).join(hash)
    }

    /// Reject an `id` that could escape the store root when joined into a
    /// path — the exact same defensive shape as
    /// `crate::store::SessionStore::validate_name`, since a `checkpoint
    /// restore <id>`/`checkpoint diff <id>` CLI argument is untrusted user
    /// input by the time it reaches here.
    fn validate_id(id: &str) -> Result<()> {
        let bad = id.is_empty()
            || id.contains('/')
            || id.contains('\\')
            || id.contains('\0')
            || id.split(['/', '\\']).any(|c| c == ".." || c == ".")
            || Path::new(id).is_absolute()
            || id.trim() != id;
        if bad {
            return Err(Error::Other(format!("invalid checkpoint id: `{id}`")));
        }
        Ok(())
    }

    /// Content-address `content`, writing it only if not already present
    /// (dedup — the same content written by two different checkpoints costs
    /// one blob). Atomic (write-to-tmp, rename) so a concurrent reader
    /// never observes a partial blob; a lost race against another writer
    /// racing the SAME hash is harmless (identical content either way).
    fn write_blob(&self, content: &[u8]) -> Result<String> {
        let hash = crate::reduce::content_hash(content);
        let dest = self.blob_path(&hash);
        if dest.exists() {
            return Ok(hash);
        }
        let Some(parent) = dest.parent() else {
            return Err(Error::Other("blob path has no parent".to_string()));
        };
        std::fs::create_dir_all(parent)?;
        let tmp = parent.join(format!(".tmp-{}-{}", std::process::id(), mint_id()));
        std::fs::write(&tmp, content)?;
        match std::fs::rename(&tmp, &dest) {
            Ok(()) => {}
            Err(e) if dest.exists() => {
                // Another writer won the race with identical content.
                let _ = std::fs::remove_file(&tmp);
                let _ = e;
            }
            Err(e) => return Err(e.into()),
        }
        Ok(hash)
    }

    fn read_blob(&self, hash: &str) -> Result<Vec<u8>> {
        std::fs::read(self.blob_path(hash)).map_err(Into::into)
    }

    fn write_manifest(&self, m: &CheckpointManifest) -> Result<()> {
        Self::validate_id(&m.id)?;
        let dest = self.manifest_path(&m.id);
        let json = serde_json::to_vec_pretty(m).map_err(|e| Error::Other(e.to_string()))?;
        let dir = self.checkpoints_dir();
        std::fs::create_dir_all(&dir)?;
        let tmp = dir.join(format!(".tmp-{}-{}", std::process::id(), mint_id()));
        std::fs::write(&tmp, &json)?;
        std::fs::rename(&tmp, &dest)?;
        Ok(())
    }

    /// Mint a fresh checkpoint (a new turn) with an empty file list. `label`
    /// is display-only.
    pub fn create_checkpoint(&self, label: &str) -> Result<CheckpointId> {
        let id = mint_id();
        let manifest = CheckpointManifest {
            id: id.clone(),
            created_at_ms: now_ms(),
            label: label.to_string(),
            files: Vec::new(),
        };
        self.write_manifest(&manifest)?;
        Ok(id)
    }

    /// Idempotently record `rel`'s pre-image under checkpoint `id` — a
    /// SECOND call for the same `(id, rel)` pair is a no-op (the manifest
    /// always keeps the EARLIEST pre-image seen this turn, which is the one
    /// a revert needs). `content: None` means the file did not exist yet.
    pub fn record_pre_image(&self, id: &str, rel: &str, content: Option<Vec<u8>>) -> Result<()> {
        let mut manifest = self.manifest(id)?;
        if manifest.files.iter().any(|f| f.path == rel) {
            return Ok(());
        }
        let blob = match content {
            Some(bytes) => Some(self.write_blob(&bytes)?),
            None => None,
        };
        manifest.files.push(CheckpointFileEntry {
            path: rel.to_string(),
            blob,
        });
        self.write_manifest(&manifest)
    }

    /// Read one checkpoint's full manifest.
    pub fn manifest(&self, id: &str) -> Result<CheckpointManifest> {
        Self::validate_id(id)?;
        let text = std::fs::read_to_string(self.manifest_path(id))
            .map_err(|e| Error::Other(format!("checkpoint `{id}` not found: {e}")))?;
        serde_json::from_str(&text)
            .map_err(|e| Error::Other(format!("checkpoint `{id}` manifest is corrupt: {e}")))
    }

    /// Every checkpoint in the store, newest first (ids are millis-prefixed
    /// so lexical descending order IS chronological descending order). A
    /// corrupt individual manifest is skipped (resilience — one bad file
    /// never hides every other checkpoint), not a hard error.
    pub fn list(&self) -> Result<Vec<CheckpointMeta>> {
        let dir = self.checkpoints_dir();
        let mut metas = Vec::new();
        if !dir.exists() {
            return Ok(metas);
        }
        for entry in std::fs::read_dir(&dir)? {
            let entry = entry?;
            let path = entry.path();
            if path.extension().and_then(|e| e.to_str()) != Some("json") {
                continue;
            }
            let Ok(text) = std::fs::read_to_string(&path) else {
                continue;
            };
            if let Ok(m) = serde_json::from_str::<CheckpointManifest>(&text) {
                metas.push(CheckpointMeta {
                    id: m.id,
                    created_at_ms: m.created_at_ms,
                    label: m.label,
                    file_count: m.files.len(),
                });
            }
        }
        metas.sort_by(|a, b| b.id.cmp(&a.id));
        Ok(metas)
    }

    /// D3 turn-diff: the set of project-relative paths this checkpoint's
    /// turn touched — exactly the manifest's file list (every entry exists
    /// BECAUSE a write-tool call captured a pre-image for it this turn).
    pub fn turn_diff(&self, id: &str) -> Result<Vec<String>> {
        Ok(self
            .manifest(id)?
            .files
            .into_iter()
            .map(|f| f.path)
            .collect())
    }

    /// BP-7 (catalog §4a "Turn diff tracking": "cumulative file-diff of
    /// the turn"): the turn's cumulative UNIFIED DIFF, not just the file
    /// list [`Self::turn_diff`] returns.
    ///
    /// Each manifest entry is a pre-image (`None` = the file did not exist
    /// before the turn); the post-image is whatever is on disk under
    /// `project_root` NOW (missing = the turn deleted it). So this is the
    /// net effect of the whole turn — a file written three times in one
    /// turn shows one diff from where it started to where it ended, which
    /// is exactly what "cumulative" means and what cc's `/diff` and cx's
    /// `turn_diff_tracker` show.
    ///
    /// Non-UTF-8 content on either side is reported as
    /// `Binary files a/<path> and b/<path> differ` rather than being
    /// diffed byte-wise into garbage; a file whose content is unchanged
    /// contributes nothing. Entries are emitted in sorted path order so
    /// the output is stable across runs.
    pub fn turn_patch(&self, id: &str, project_root: &Path) -> Result<String> {
        let mut entries = self.manifest(id)?.files;
        entries.sort_by(|a, b| a.path.cmp(&b.path));
        let mut out = String::new();
        for entry in entries {
            let before: Option<Vec<u8>> = match &entry.blob {
                Some(blob) => Some(self.read_blob(blob)?),
                None => None,
            };
            let after = std::fs::read(project_root.join(&entry.path)).ok();
            if before == after {
                continue;
            }
            let (Some(before_text), Some(after_text)) = (
                decode_side(before.as_deref()),
                decode_side(after.as_deref()),
            ) else {
                out.push_str(&format!(
                    "Binary files a/{0} and b/{0} differ
",
                    entry.path
                ));
                continue;
            };
            let patch = diffy::create_patch(&before_text, &after_text);
            out.push_str(&format!(
                "--- a/{0}
+++ b/{0}
",
                entry.path
            ));
            // `diffy` emits its own `---`/`+++` header lines with no file
            // names; the project-relative pair above replaces them, so the
            // output reads like an ordinary `git diff`.
            for line in patch.to_string().lines().skip(2) {
                out.push_str(line);
                out.push('\n');
            }
        }
        Ok(out)
    }

    /// D4-adjacent revert: restore `project_root`'s working files to
    /// checkpoint `id`. For each manifest entry: `Some(blob)` rewrites the
    /// file to that pre-image; `None` (didn't exist before the turn)
    /// deletes it if present now (undoing a create). SECURITY: every
    /// target is independently re-validated (never trusts the manifest was
    /// produced honestly) against `project_root` containment (no symlink
    /// escape, no `..` traversal) AND `protected_globs` (plus an
    /// unconditional `.git/**` floor) checked against BOTH the LEXICAL
    /// normalized path and the symlink-RESOLVED path — a lexical-only
    /// check would miss a manifest entry like `foo/config` where `foo` is
    /// a pre-existing symlink into `.git`: lexically it's clean, but it
    /// resolves inside `root` (so containment alone accepts it too) and
    /// lands on the real `.git/config`. A refused entry is recorded in
    /// [`RestoreReport::refused`], never silently applied AND never aborts
    /// the rest of the restore (partial-success, fully reported).
    pub fn restore(
        &self,
        id: &str,
        project_root: &Path,
        protected_globs: &[String],
    ) -> Result<RestoreReport> {
        let manifest = self.manifest(id)?;
        let mut report = RestoreReport::default();
        for entry in &manifest.files {
            // (1) Up-front rejection: a legitimately-captured entry (see
            // `CheckpointFileEntry::path`'s doc comment) is always a clean
            // relative path — `record_pre_image` never produces an absolute
            // path or a `..` component. An entry that has one is by
            // definition hostile or corrupt (traversal-injected, or a
            // corrupted/copied/shared manifest — exactly this module's
            // stated threat model) and must never reach a raw-string
            // pattern match at all.
            if let Some(reason) = reject_unsafe_manifest_path(&entry.path) {
                report.refused.push((entry.path.clone(), reason));
                continue;
            }
            let target = project_root.join(&entry.path);
            // (2) Normalize-then-protect: compute the SAME lexically-
            // normalized project-relative path `contained()` uses
            // internally, ONCE, and check `is_protected` against THAT
            // (not the raw manifest string) — so a `.git/**`-floor or
            // `protected_globs` bypass via `x/../.git/config` can no
            // longer disagree between the two checks (the root cause of
            // the bug this replaces: `is_protected` matched the raw
            // string while `contained` matched the normalized path).
            let Some(normalized_rel) = normalized_project_rel(project_root, &target) else {
                report.refused.push((
                    entry.path.clone(),
                    "refused: escapes the project root".to_string(),
                ));
                continue;
            };
            if is_protected(&normalized_rel, protected_globs) {
                report
                    .refused
                    .push((entry.path.clone(), "refused: protected path".to_string()));
                continue;
            }
            // Belt-and-suspenders: the existing symlink-safe containment
            // check (canonicalizes the longest existing ancestor, refusing
            // any symlink escape) still runs unconditionally.
            if !contained(project_root, &target) {
                report.refused.push((
                    entry.path.clone(),
                    "refused: escapes the project root".to_string(),
                ));
                continue;
            }
            // (3) Resolved-then-protect: `normalized_rel` above is a purely
            // LEXICAL collapse — it never resolves symlinks — while
            // `contained` (just above) DOES resolve symlinks when it
            // canonicalizes the longest existing ancestor. Those two views
            // of the path can disagree exactly when a component of `target`
            // is a symlink: e.g. a pre-existing `foo -> .git` inside
            // `project_root` plus a manifest entry `foo/config` lexically
            // normalizes to `foo/config` (not protected — no literal
            // `.git/` prefix) yet resolves to `<root>/.git/config` (still
            // "contained" under `project_root`, so the escape check above
            // doesn't catch it either — it never leaves the root, it just
            // lands somewhere the lexical path didn't say). Re-run
            // `is_protected` against the RESOLVED, symlink-followed
            // project-relative path too, so this can't slip through: the
            // `.git`/`protected_globs` floor now sees BOTH the lexical and
            // the resolved view, and refuses if EITHER is protected.
            if let Some(resolved_rel) = resolved_project_rel(project_root, &target) {
                if is_protected(&resolved_rel, protected_globs) {
                    report
                        .refused
                        .push((entry.path.clone(), "refused: protected path".to_string()));
                    continue;
                }
            }
            match &entry.blob {
                Some(hash) => {
                    let bytes = match self.read_blob(hash) {
                        Ok(b) => b,
                        Err(e) => {
                            report
                                .refused
                                .push((entry.path.clone(), format!("blob unreadable: {e}")));
                            continue;
                        }
                    };
                    if let Some(parent) = target.parent() {
                        let _ = std::fs::create_dir_all(parent);
                    }
                    if let Err(e) = std::fs::write(&target, &bytes) {
                        report
                            .refused
                            .push((entry.path.clone(), format!("write failed: {e}")));
                        continue;
                    }
                }
                None if target.exists() => {
                    if let Err(e) = std::fs::remove_file(&target) {
                        report
                            .refused
                            .push((entry.path.clone(), format!("delete failed: {e}")));
                        continue;
                    }
                }
                None => {}
            }
            report.restored.push(entry.path.clone());
        }
        Ok(report)
    }

    /// Bounded-disk requirement: keep only the `keep` newest checkpoints,
    /// deleting the rest, then GC any blob no longer referenced by a
    /// surviving manifest. Returns the number of checkpoints removed.
    pub fn prune(&self, keep: usize) -> Result<usize> {
        let mut metas = self.list()?; // newest first
        if metas.len() <= keep {
            return Ok(0);
        }
        let stale = metas.split_off(keep);
        let removed = stale.len();
        for m in stale {
            let _ = std::fs::remove_file(self.manifest_path(&m.id));
        }
        self.gc_unreferenced_blobs()?;
        Ok(removed)
    }

    /// Delete every blob under `objects/` not referenced by ANY surviving
    /// manifest — a full scan, not a refcount (simplest correct form; the
    /// retention bound keeps this cheap in practice — see [`Self::prune`]'s
    /// doc comment).
    fn gc_unreferenced_blobs(&self) -> Result<()> {
        let mut referenced: HashSet<String> = HashSet::new();
        for meta in self.list()? {
            if let Ok(m) = self.manifest(&meta.id) {
                for f in m.files {
                    if let Some(b) = f.blob {
                        referenced.insert(b);
                    }
                }
            }
        }
        let objects = self.objects_dir();
        if !objects.exists() {
            return Ok(());
        }
        for entry in std::fs::read_dir(&objects)? {
            let entry = entry?;
            if !entry.file_type()?.is_dir() {
                continue;
            }
            for inner in std::fs::read_dir(entry.path())? {
                let inner = inner?;
                let name = inner.file_name();
                let Some(name) = name.to_str() else {
                    continue;
                };
                if name.starts_with(".tmp-") {
                    continue; // an in-flight write, not ours to reap
                }
                if !referenced.contains(name) {
                    let _ = std::fs::remove_file(inner.path());
                }
            }
        }
        Ok(())
    }
}

// SECURITY (safe-path consolidation, CRITICAL fix): every primitive below
// used to be defined HERE, locally — this module's own P5-9 fix for the
// `.git`-clobber bug class. It is now `crate::safe_path`'s canonical
// implementation instead, with checkpoint DELEGATING to it (thin wrappers,
// same names, same signatures, same behavior) so `crate::permissions`'s
// gate and `crate::tools`'s sandbox containment reuse this exact proven
// logic rather than each re-implementing (and, in the permissions gate's
// case, getting wrong) their own. See `crate::safe_path`'s module doc
// comment for the full story and the two-views-of-a-path explanation every
// doc comment below used to carry inline.
//
// Every one of this module's 23 tests (see `tests` below) still exercises
// these names directly and is UNCHANGED — that is the proof this extraction
// is behavior-preserving.

/// Is `rel` (a project-relative, `/`-separated path) a hard floor this
/// module refuses to snapshot INTO or restore OVER, regardless of config?
/// `.git` (and everything under it) is unconditional — checkpoint must
/// never touch the user's real git repo even if `permissions.protected_paths`
/// (module 13) is off. `extra_globs` layers `Config::permissions_protected_paths`
/// on top when the caller has one (restore only — capture-time protection
/// is already covered because [`CheckpointObserver::before_write`] only
/// ever fires for a write the P5-1 permission gate already approved, which
/// already folds `protected_paths` in — see that method's own doc comment).
/// See `crate::safe_path::is_protected` for the implementation.
fn is_protected(rel: &str, extra_globs: &[String]) -> bool {
    crate::safe_path::is_protected(rel, extra_globs)
}

/// Up-front rejection for a manifest-declared path that could never have
/// come from a legitimate capture: `record_pre_image` only ever stores a
/// clean, `/`-separated, project-relative path (see
/// [`CheckpointFileEntry::path`]'s doc comment), so an absolute path or one
/// containing a `..` (`ParentDir`), root, or Windows-prefix component is by
/// definition hostile or corrupt. Returns the refusal reason, or `None` if
/// `rel` is clean. Called BEFORE any raw-string pattern match (e.g.
/// [`is_protected`]) so a traversal entry like `x/../.git/config` — which
/// does not literally string-match the `.git/` floor — is refused before
/// it can ever be compared against anything. See
/// `crate::safe_path::reject_unsafe_rel_path` for the implementation.
fn reject_unsafe_manifest_path(rel: &str) -> Option<String> {
    crate::safe_path::reject_unsafe_rel_path(rel)
}

/// Lexically normalize `path` (expected to be `root.join(rel)` for some
/// manifest-declared `rel`) via the SAME collapse [`contained`] uses, then —
/// if the normalized form is still under `root` — return its
/// project-relative, `/`-separated tail. Callers (currently only
/// [`CheckpointStore::restore`]) compute this ONCE per entry and feed the
/// single result to [`is_protected`], so the protected-path floor sees
/// EXACTLY the same normalized path [`contained`]'s containment check
/// computes. See `crate::safe_path::normalized_project_rel` for the
/// implementation.
fn normalized_project_rel(root: &Path, path: &Path) -> Option<String> {
    crate::safe_path::normalized_project_rel(root, path)
}

/// Symlink- and traversal-safe containment check: is `path` (absolute,
/// possibly not-yet-existing) confined under `root`? Fails closed (`false`)
/// on any resolution error. See `crate::safe_path::contained` for the
/// implementation.
fn contained(root: &Path, path: &Path) -> bool {
    crate::safe_path::contained(root, path)
}

/// Resolved (symlink-following) counterpart to [`normalized_project_rel`]:
/// canonicalizes `path`'s longest existing ancestor (resolving any symlink
/// along the way — see `crate::safe_path::resolve_real`) and returns the
/// resulting absolute path's tail relative to `root`'s own canonical form, as a
/// `/`-separated string — or `None` if resolution fails, or the resolved
/// path lands outside `root` entirely (that case is already refused by
/// [`contained`]; this function only needs to report a rel path when
/// there IS one). [`CheckpointStore::restore`] feeds this to
/// [`is_protected`] IN ADDITION TO the lexical [`normalized_project_rel`]
/// result, closing the gap where a symlink resolves into `.git` (or a
/// `protected_globs` match) even though its LEXICAL path never mentions
/// `.git` at all and it never leaves `root` (so `contained` alone would
/// accept it) — see the call site's doc comment for the exact repro this
/// closes. See `crate::safe_path::resolved_project_rel` for the
/// implementation.
fn resolved_project_rel(root: &Path, path: &Path) -> Option<String> {
    crate::safe_path::resolved_project_rel(root, path)
}

#[derive(Debug, Default)]
struct ObserverState {
    /// The checkpoint currently open for the in-flight turn.
    current: Option<CheckpointId>,
    /// Project-relative paths already captured under `current` — first
    /// write per turn wins the pre-image; every write after the first is a
    /// no-op capture (the manifest already holds the earliest state).
    captured: HashSet<String>,
}

/// [`WriteObserver`] implementation backing `[capabilities.checkpoint]`.
/// One instance per [`crate::Agent`] (installed on its [`crate::tools::ToolContext`]
/// AND held directly so `crate::Agent::run_loop` can call
/// [`Self::begin_turn`] once per user turn — see that method's call site's
/// doc comment).
#[derive(Debug)]
pub struct CheckpointObserver {
    store: CheckpointStore,
    project_root: PathBuf,
    retain: usize,
    protected: Vec<String>,
    /// BP-7 (§3.1 `capabilities.checkpoint.restore`): see
    /// [`Self::restore_enabled`].
    restore_enabled: bool,
    state: Mutex<ObserverState>,
    /// Set once on any I/O failure — graceful degrade (§ "git-absent /
    /// unwritable state dir ⇒ warn + disable, never crash"), not a panic
    /// and not a blocked tool call. `Relaxed` throughout: this is a
    /// best-effort circuit breaker, not a correctness-critical ordering.
    disabled: AtomicBool,
}

impl CheckpointObserver {
    /// `protected` layers extra glob patterns (typically
    /// `Config::permissions_protected_paths`, when module 13 is active) on
    /// top of the unconditional `.git/**` floor — consulted by
    /// [`Self::restore`].
    pub fn new(
        store: CheckpointStore,
        project_root: PathBuf,
        retain: usize,
        protected: Vec<String>,
    ) -> Self {
        Self::with_restore(store, project_root, retain, protected, true)
    }

    /// BP-7: [`Self::new`] with the restore half explicitly gated — see
    /// [`Self::restore_enabled`].
    pub fn with_restore(
        store: CheckpointStore,
        project_root: PathBuf,
        retain: usize,
        protected: Vec<String>,
        restore_enabled: bool,
    ) -> Self {
        CheckpointObserver {
            store,
            project_root,
            retain: retain.max(1),
            protected,
            restore_enabled,
            state: Mutex::new(ObserverState::default()),
            disabled: AtomicBool::new(false),
        }
    }

    /// Read-only access to the underlying store (e.g. so a caller can
    /// `list`/`turn_diff`/`restore` without re-deriving the root path).
    pub fn store(&self) -> &CheckpointStore {
        &self.store
    }

    /// List every checkpoint, newest first — see [`CheckpointStore::list`].
    pub fn list(&self) -> Result<Vec<CheckpointMeta>> {
        self.store.list()
    }

    /// D3 turn-diff for one checkpoint — see [`CheckpointStore::turn_diff`].
    pub fn turn_diff(&self, id: &str) -> Result<Vec<String>> {
        self.store.turn_diff(id)
    }

    /// BP-7: the turn's cumulative unified diff against THIS observer's own
    /// project root — see [`CheckpointStore::turn_patch`].
    pub fn turn_patch(&self, id: &str) -> Result<String> {
        self.store.turn_patch(id, &self.project_root)
    }

    /// BP-7 (§3.1 `capabilities.checkpoint.restore`): whether this
    /// observer may put files back. `false` is the turn-diff-only posture
    /// cx-parity takes — Codex tracks each turn's diff but has no code
    /// restore at all (its `ghost_snapshot` is a stripped legacy no-op), so
    /// a preset that transcribes Codex must be able to arm the tracking
    /// half without the restoring half.
    pub fn restore_enabled(&self) -> bool {
        self.restore_enabled
    }

    /// D4-adjacent revert: restore this project's working files to
    /// checkpoint `id`, honoring THIS observer's own `project_root` and
    /// `protected` globs (the fields set at construction) — see
    /// [`CheckpointStore::restore`] for the full security contract.
    pub fn restore(&self, id: &str) -> Result<RestoreReport> {
        if !self.restore_enabled {
            return Err(Error::Other(
                "checkpoint restore is off for this harness                  (`[capabilities.checkpoint] restore = false`) — this preset tracks each                  turn's diff but has no code-restore surface"
                    .to_string(),
            ));
        }
        self.store.restore(id, &self.project_root, &self.protected)
    }

    /// Whether this observer has disabled itself after an I/O failure.
    pub fn is_disabled(&self) -> bool {
        self.disabled.load(Ordering::Relaxed)
    }

    /// Open a fresh checkpoint for a new turn — called once at the top of
    /// `crate::Agent::run_loop` (i.e. once per `Agent::send`/
    /// `send_with_files`/`send_with_images` call, cc's "per-prompt
    /// file-history-snapshot"). `label` is a short excerpt of the turn's
    /// prompt, display-only. Also prunes past the retention bound here
    /// (once per turn, not once per write) — see [`CheckpointStore::prune`].
    /// Returns `None` when disabled (config-off is never routed here at
    /// all — see [`observer_for_config`] — so `None` here specifically
    /// means an I/O failure already tripped the breaker).
    pub fn begin_turn(&self, label: &str) -> Option<CheckpointId> {
        if self.disabled.load(Ordering::Relaxed) {
            return None;
        }
        let short: String = label.chars().take(120).collect();
        match self.store.create_checkpoint(&short) {
            Ok(id) => {
                if let Ok(mut st) = self.state.lock() {
                    st.current = Some(id.clone());
                    st.captured.clear();
                }
                if let Err(e) = self.store.prune(self.retain) {
                    eprintln!("warning: checkpoint: prune failed: {e}");
                }
                Some(id)
            }
            Err(e) => {
                eprintln!(
                    "warning: checkpoint disabled for the rest of this session — \
                     failed to open a new checkpoint: {e}"
                );
                self.disabled.store(true, Ordering::Relaxed);
                None
            }
        }
    }

    /// The checkpoint currently open for the in-flight turn, if any.
    pub fn current(&self) -> Option<CheckpointId> {
        self.state.lock().ok().and_then(|s| s.current.clone())
    }
}

#[async_trait::async_trait]
impl WriteObserver for CheckpointObserver {
    async fn before_write(&self, path: &Path) {
        if self.disabled.load(Ordering::Relaxed) {
            return;
        }
        if !contained(&self.project_root, path) {
            // Outside the project root — out of this module's scope (§ "an
            // honest gap", never a crash or a wrong snapshot).
            return;
        }
        let Some(normalized) = crate::tools::normalize(path) else {
            return;
        };
        let Some(root_normalized) = crate::tools::normalize(&self.project_root) else {
            return;
        };
        let Ok(rel_path) = normalized.strip_prefix(&root_normalized) else {
            return;
        };
        let rel = rel_path.to_string_lossy().replace('\\', "/");
        if rel.is_empty() || rel == ".git" || rel.starts_with(".git/") {
            return;
        }

        // The ENTIRE check-read-record sequence runs under one lock, so two
        // concurrent writes to the SAME path (e.g. a `run_tools_concurrently`
        // batch, or a P5-6 background job racing a foreground write) can
        // never both read-and-lose a torn pre-image: the second one to
        // arrive here always sees `captured` already contains `rel` and
        // skips entirely, never re-reading a post-first-write state.
        let mut st = match self.state.lock() {
            Ok(g) => g,
            Err(poisoned) => poisoned.into_inner(),
        };
        if st.current.is_none() {
            // A write reached this seam with no open turn (e.g. a caller
            // driving the tool registry directly, outside `Agent::send`) —
            // self-heal with an ad-hoc checkpoint rather than silently
            // dropping the capture. `begin_turn` takes this same lock, so
            // it must be called with `st` released first.
            drop(st);
            self.begin_turn("untracked");
            st = match self.state.lock() {
                Ok(g) => g,
                Err(poisoned) => poisoned.into_inner(),
            };
        }
        if st.captured.contains(&rel) {
            return;
        }
        let Some(id) = st.current.clone() else {
            return; // begin_turn's own failure already warned + disabled
        };
        let content = std::fs::read(path).ok(); // None => doesn't exist yet (a create)
        match self.store.record_pre_image(&id, &rel, content) {
            Ok(()) => {
                st.captured.insert(rel);
            }
            Err(e) => {
                eprintln!(
                    "warning: checkpoint disabled for the rest of this session — \
                     failed to record a snapshot: {e}"
                );
                self.disabled.store(true, Ordering::Relaxed);
            }
        }
    }

    async fn after_write(&self, _path: &Path) -> Option<String> {
        // P5-11: `formatters`/`lsp` now occupy this hook (via
        // `crate::tools::WriteObserverChain`, installed AFTER this observer
        // in `crate::agent::build_tool_context`'s chain) — checkpoint itself
        // still has nothing to do after a write completes, and returning
        // `None` keeps the tool-result text this hook contributes
        // byte-identical to before P5-11 whenever checkpoint is the only
        // observer installed.
        None
    }
}

/// A stable per-project-directory tag — the same hash-of-canonicalized-cwd
/// idea `crates/cli/src/main.rs::cwd_tag` uses for session naming, kept
/// separately here (a `core`-crate concern, and `cli` depends on `core` not
/// the reverse) so two different projects never share one shadow store even
/// though they'd otherwise both resolve to the same `$SUPERCODE_HOME`-
/// derived parent directory.
///
/// BP-10: `pub(crate)` because the persisted approval cache
/// (`crate::permissions::approval`) keys its own per-project store the same
/// way — the SAME tag function, not a second hash with the same idea, so
/// one project's checkpoints and its remembered approvals can never
/// disagree about which project they belong to.
pub(crate) fn project_tag(cwd: &Path) -> String {
    use std::hash::{Hash, Hasher};
    let canon = std::fs::canonicalize(cwd).unwrap_or_else(|_| cwd.to_path_buf());
    let mut h = std::collections::hash_map::DefaultHasher::new();
    canon.hash(&mut h);
    format!("{:016x}", h.finish())
}

/// The DEFAULT shadow-store root for `config.cwd` when
/// [`crate::Config::checkpoint_dir`] is unset: `$SUPERCODE_HOME/checkpoints/<project_tag>`
/// (`crate::agent::global_instructions_dir` is the same `$SUPERCODE_HOME`
/// resolver the global instruction tier and `checkpoint` both use).
fn default_shadow_root(cwd: &Path) -> PathBuf {
    crate::agent::global_instructions_dir()
        .join("checkpoints")
        .join(project_tag(cwd))
}

/// Build the [`CheckpointObserver`] a fresh [`crate::Agent`] should install,
/// given a resolved [`crate::Config`] — called once, from
/// `crate::agent::build_tool_context`. `Config::checkpoint_enabled` is the
/// ONE gate: `false` (the default) returns `None` WITHOUT touching the
/// filesystem at all (no `CheckpointStore::open`, no directory created) —
/// the default-off byte-identity guarantee. `true` opens (creating if
/// needed) the shadow store at `Config::checkpoint_dir`, or
/// `default_shadow_root` when that's unset; an I/O failure (unwritable
/// state dir) is reported via a one-time `eprintln!` warning and returns
/// `None` — graceful degrade, never a crash, never a blocked `Agent::new`.
/// BP-7: one side of a [`CheckpointStore::turn_patch`] entry as text.
/// `None` (absent file) decodes to the empty string — a create diffs
/// against nothing and a delete diffs to nothing, which is what a unified
/// diff of those cases should show. Non-UTF-8 bytes return `None`, which
/// the caller renders as a "binary files differ" line rather than diffing
/// them into garbage.
fn decode_side(bytes: Option<&[u8]>) -> Option<String> {
    match bytes {
        None => Some(String::new()),
        Some(b) => String::from_utf8(b.to_vec()).ok(),
    }
}

pub fn observer_for_config(config: &crate::Config) -> Option<std::sync::Arc<CheckpointObserver>> {
    if !config.checkpoint_enabled {
        return None;
    }
    let root = config
        .checkpoint_dir
        .clone()
        .unwrap_or_else(|| default_shadow_root(&config.cwd));
    match CheckpointStore::open(&root) {
        Ok(store) => Some(std::sync::Arc::new(CheckpointObserver::with_restore(
            store,
            config.cwd.clone(),
            config.checkpoint_retain,
            config.permissions_protected_paths.clone(),
            config.checkpoint_restore,
        ))),
        Err(e) => {
            eprintln!(
                "warning: [capabilities.checkpoint] is enabled but the shadow store at \
                 {} could not be opened — checkpoint is disabled for this session: {e}",
                root.display()
            );
            None
        }
    }
}