iron-shell 14.0.3

//! Reversible sessions: let the agent work, and be able to rewind it.
//!
//! 6.0.0 bought safety with friction — 166 builtins now stop and ask. That is
//! the expensive currency: every approval is a round-trip, a stall, and a
//! chance the agent gives up or routes around it. Reversibility buys the same
//! safety with a cheaper one. If a write can be undone, it does not need to be
//! prevented, and the user's question changes from *"should I allow this?"* to
//! *"do I keep it?"* — asked once, at the end, with the results in front of them.
//!
//! Before a `WriteLocal` or `Destructive` builtin runs, the prior contents of
//! every file it might touch are recorded here. [`undo`] puts them back.
//!
//! Undo can itself be undone. When [`undo`] restores a path it first captures
//! the state that the undone step had produced, and [`redo`] writes that state
//! back. Recording a new step discards the redo stack, the usual editor rule:
//! once the history has moved on, the undone future is no longer reachable.
//!
//! # What this cannot do, stated plainly
//!
//! Undo covers **local file contents and nothing else**. A `Network` call
//! cannot be unsent, an `Exec`'d process cannot be un-run, a killed process
//! cannot be revived, and a directory tree is not snapshotted. The journal
//! therefore records *irreversible* steps too, as explicit entries, so that a
//! rewind reports what it could not restore instead of quietly restoring part
//! of the world and reporting success.
//!
//! That last point is the whole design. A partial undo that claims completeness
//! is worse than no undo, because it converts a recoverable situation into one
//! where the user believes they have already recovered.

use crate::safety::Effect;
use crate::value::Value;
use std::path::{Component, Path, PathBuf};
use std::sync::{Mutex, MutexGuard};

#[cfg(unix)]
use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};

/// Largest single file captured. Beyond this the step is recorded as
/// irreversible rather than silently skipped.
const MAX_FILE_BYTES: usize = 8 * 1024 * 1024;

/// Ceiling on everything held at once (journal and redo together), so a long
/// session cannot exhaust memory.
const MAX_TOTAL_BYTES: usize = 64 * 1024 * 1024;

/// What was there before a step ran.
#[derive(Clone, Debug, PartialEq)]
pub enum Before {
    /// The file existed with these bytes.
    Contents(Vec<u8>),
    /// The path did not exist, so undoing means removing whatever was created:
    /// a file, or a directory that is still empty.
    Absent,
    /// An empty directory was there, so undoing means creating it again.
    Directory,
    /// Seen, but not recoverable — with the reason, which is reported verbatim
    /// on rewind rather than being flattened into a failure count.
    Irreversible(String),
}

/// The state a path was left in by a step: the SHA-256 of its bytes, or nothing
/// there. Recorded once the step has run, so that [`undo`] can tell whether the
/// file has been changed since, outside the journal.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Fingerprint {
    /// The path did not exist.
    Absent,
    /// The SHA-256 of the file's bytes, in lowercase hex.
    Digest(String),
}

impl Fingerprint {
    /// The text form kept on disk: `absent`, or the hex digest.
    fn encode(&self) -> String {
        match self {
            Fingerprint::Absent => "absent".to_string(),
            Fingerprint::Digest(hex) => hex.clone(),
        }
    }

    fn decode(text: &str) -> Fingerprint {
        if text == "absent" {
            Fingerprint::Absent
        } else {
            Fingerprint::Digest(text.to_string())
        }
    }

    /// The state a step leaves its path in, when the step's `before` is what
    /// the path is written with (a redo). None when it is not known.
    fn of_before(before: &Before) -> Option<Fingerprint> {
        match before {
            Before::Contents(bytes) => {
                use ironcrypto::core_types::traits::Digest;
                let digest = ironcrypto::hash::Sha256::digest(bytes.as_slice()).ok()?;
                Some(Fingerprint::Digest(hex::encode(digest)))
            }
            Before::Absent => Some(Fingerprint::Absent),
            Before::Directory | Before::Irreversible(_) => None,
        }
    }

    /// The state of `path` now, read in chunks. None for a directory, which no
    /// step's undo is checked against.
    fn of_path(path: &str) -> Option<Fingerprint> {
        use ironcrypto::core_types::traits::Digest;
        use std::io::Read;
        let p = Path::new(path);
        if !p.exists() {
            return Some(Fingerprint::Absent);
        }
        if !p.is_file() {
            return None;
        }
        let mut file = std::fs::File::open(p).ok()?;
        let mut hasher = ironcrypto::hash::Sha256::new();
        let mut buf = vec![0u8; 1 << 20];
        loop {
            let n = file.read(&mut buf).ok()?;
            if n == 0 {
                break;
            }
            hasher.update(&buf[..n]);
        }
        Some(Fingerprint::Digest(hex::encode(hasher.finalize().ok()?)))
    }
}

#[derive(Clone, Debug)]
pub struct Entry {
    pub seq: usize,
    pub builtin: String,
    pub effect: String,
    pub path: String,
    pub before: Before,
    /// The state the step left `path` in, once the step has run. None for a
    /// step recorded before this was kept (its undo is not checked against
    /// later hand edits), and for a step that was never sealed.
    pub after: Option<Fingerprint>,
    /// Entries recorded by one call that changed several paths (a move changes
    /// both ends) share this id, and undo and redo count them as one step. None
    /// for a call that changed one path.
    pub group: Option<usize>,
}

impl Entry {
    pub fn reversible(&self) -> bool {
        !matches!(self.before, Before::Irreversible(_))
    }
}

/// A step that was undone and can be re-applied. `after` is the state of
/// `path` just before undo restored it: the state the undone step produced.
#[derive(Clone, Debug)]
pub struct RedoEntry {
    pub seq: usize,
    pub builtin: String,
    pub effect: String,
    pub path: String,
    /// Always `Contents`, `Absent` or `Directory`; anything else is never pushed.
    pub after: Before,
    /// The group of the undone entry: see [`Entry::group`].
    pub group: Option<usize>,
}

#[derive(Default)]
struct State {
    journal: Vec<Entry>,
    redo: Vec<RedoEntry>,
    /// The lowest id not yet handed out in this session. See [`take_seq`].
    next_id: usize,
}

lazy_static::lazy_static! {
    static ref STATE: Mutex<State> = Mutex::new(State::default());
    /// The session directory the state was last loaded from. Loading lists
    /// that directory; doing it once per directory, rather than on every
    /// builtin call while the journal happens to be empty, is the difference
    /// between a read per session and a read per call.
    static ref HYDRATED_FROM: Mutex<Option<Option<PathBuf>>> = Mutex::new(None);
}

/// Where this session's journal lives. The redo stack lives in the `redo`
/// subdirectory of the same place.
///
/// Persistence is not a nicety here. The Python SDK runs `ish -c <code>` per
/// call, so an in-memory journal would be empty in the process that runs
/// `undo` — the feature would appear to work and reverse nothing, which is the
/// exact failure this module is written to avoid.
fn session_dir() -> Option<PathBuf> {
    if let Ok(d) = std::env::var("IRONSHELL_SESSION_DIR") {
        return Some(PathBuf::from(d).join("journal"));
    }
    let key = std::env::var("IRONSHELL_SESSION").ok().unwrap_or_else(|| {
        let cwd = std::env::current_dir()
            .map(|p| p.to_string_lossy().into_owned())
            .unwrap_or_default();
        // MD5 names a directory, not a secret. IronCrypto has no MD5, and another hash would orphan existing journals.
        format!("{:x}", md5::compute(cwd.as_bytes()))
    });
    dirs::cache_dir().map(|c| c.join("ironshell").join("journal").join(key))
}

fn redo_dir() -> Option<PathBuf> {
    session_dir().map(|d| d.join("redo"))
}

/// Serialisable form of an entry. The captured bytes travel with it: a journal
/// that persisted only the metadata could list what it would restore and then
/// restore nothing.
#[derive(serde::Serialize, serde::Deserialize)]
struct StoredEntry {
    seq: usize,
    builtin: String,
    effect: String,
    path: String,
    /// `None` = the path was absent; `Some(bytes)` = it held these.
    contents: Option<Vec<u8>>,
    /// Set when the step could not be captured, with the reason.
    irreversible: Option<String>,
    /// The state the step left the path in: `absent` or a hex digest. Absent
    /// from entries an earlier version wrote, which keep the old undo.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    after: Option<String>,
    /// The step group, when the call changed several paths. Absent from entries
    /// an earlier version wrote, which are single-path steps.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    group: Option<usize>,
    /// Set for [`Before::Directory`]: an empty directory was there before.
    #[serde(default, skip_serializing_if = "is_false")]
    directory: bool,
}

fn is_false(b: &bool) -> bool {
    !*b
}

impl From<&Entry> for StoredEntry {
    fn from(e: &Entry) -> Self {
        let (contents, irreversible, directory) = match &e.before {
            Before::Contents(b) => (Some(b.clone()), None, false),
            Before::Absent => (None, None, false),
            Before::Directory => (None, None, true),
            Before::Irreversible(why) => (None, Some(why.clone()), false),
        };
        StoredEntry {
            seq: e.seq,
            builtin: e.builtin.clone(),
            effect: e.effect.clone(),
            path: e.path.clone(),
            contents,
            irreversible,
            after: e.after.as_ref().map(Fingerprint::encode),
            group: e.group,
            directory,
        }
    }
}

impl From<StoredEntry> for Entry {
    fn from(s: StoredEntry) -> Self {
        let before = match (s.contents, s.irreversible) {
            (_, Some(why)) => Before::Irreversible(why),
            (Some(b), None) => Before::Contents(b),
            (None, None) if s.directory => Before::Directory,
            (None, None) => Before::Absent,
        };
        Entry {
            seq: s.seq,
            builtin: s.builtin,
            effect: s.effect,
            path: s.path,
            before,
            after: s.after.as_deref().map(Fingerprint::decode),
            group: s.group,
        }
    }
}

/// Read the entries persisted in `dir`, oldest first. Only files whose stem is
/// a number are entries, so the `redo` subdirectory of the journal directory is
/// never mistaken for one.
fn load_dir(dir: &Path) -> Vec<Entry> {
    let Ok(entries) = std::fs::read_dir(dir) else {
        return Vec::new();
    };
    let mut files: Vec<(usize, PathBuf)> = entries
        .filter_map(|e| e.ok())
        .filter_map(|e| {
            let p = e.path();
            if !p.is_file() {
                return None;
            }
            let stem = p.file_stem()?.to_string_lossy().into_owned();
            stem.parse::<usize>().ok().map(|n| (n, p))
        })
        .collect();
    files.sort_by_key(|(n, _)| *n);
    files
        .into_iter()
        .filter_map(|(_, p)| {
            let raw = std::fs::read(&p).ok()?;
            serde_json::from_slice::<StoredEntry>(&raw)
                .ok()
                .map(Entry::from)
        })
        .collect()
}

/// Create `dir` and make it private to the user. This runs on every persist, so
/// a directory an earlier version made with default modes is tightened too; the
/// entries it already holds are then shielded by the directory's mode.
///
/// Fails if the mode did not take: a directory that is not private must not
/// receive the captured contents.
fn make_private_dir(dir: &Path) -> std::io::Result<()> {
    std::fs::create_dir_all(dir)?;
    #[cfg(unix)]
    {
        std::fs::set_permissions(dir, std::fs::Permissions::from_mode(0o700))?;
        if std::fs::metadata(dir)?.permissions().mode() & 0o077 != 0 {
            return Err(std::io::Error::new(
                std::io::ErrorKind::PermissionDenied,
                "the directory's mode did not become private",
            ));
        }
    }
    Ok(())
}

/// Write `bytes` to `path`, private to the user on Unix. A file that already
/// exists is narrowed to 0600 before its contents are written.
pub(crate) fn write_private(path: &Path, bytes: &[u8]) -> std::io::Result<()> {
    #[cfg(not(unix))]
    return std::fs::write(path, bytes);
    #[cfg(unix)]
    {
        use std::io::Write;
        let existed = path.exists();
        let mut file = std::fs::OpenOptions::new()
            .write(true)
            .create(true)
            .truncate(true)
            .mode(0o600)
            .open(path)?;
        if existed {
            file.set_permissions(std::fs::Permissions::from_mode(0o600))?;
        }
        file.write_all(bytes)
    }
}

/// Persist one entry. If the directory cannot be made private, or the entry
/// cannot be written, nothing is written and a warning says so: the in-memory
/// entry stays usable for this process.
fn persist_in(dir: Option<PathBuf>, e: &Entry) {
    let Some(dir) = dir else { return };
    let path = dir.join(format!("{:08}.json", e.seq));
    let written = make_private_dir(&dir).and_then(|()| {
        let json = serde_json::to_vec(&StoredEntry::from(e))
            .map_err(|err| std::io::Error::new(std::io::ErrorKind::InvalidData, err))?;
        write_private(&path, &json)
    });
    if let Err(err) = written {
        tracing::warn!(
            target: "journal",
            "undo entry {} was not persisted, so it will not survive this process: {}: {err}",
            e.seq,
            path.display()
        );
    }
}

fn forget_in(dir: Option<PathBuf>, seq: usize) {
    if let Some(dir) = dir {
        let path = dir.join(format!("{seq:08}.json"));
        if let Err(err) = remove_if_present(std::fs::remove_file(&path)) {
            warn_left_behind(&path, &err);
        }
    }
}

/// A path that is already gone is what removing it was for.
fn remove_if_present(removed: std::io::Result<()>) -> std::io::Result<()> {
    match removed {
        Err(e) if e.kind() != std::io::ErrorKind::NotFound => Err(e),
        _ => Ok(()),
    }
}

/// A later process loads what is left here, so a step this process forgot can
/// come back; and it may hold the contents of a file that was overwritten.
fn warn_left_behind(path: &Path, err: &std::io::Error) {
    tracing::warn!(
        target: "journal",
        "{} could not be removed, so a later process may load it: {err}",
        path.display()
    );
}

fn persist(e: &Entry) {
    persist_in(session_dir(), e);
}

fn forget_persisted(seq: usize) {
    forget_in(session_dir(), seq);
}

fn persist_redo(r: &RedoEntry) {
    persist_in(redo_dir(), &redo_as_entry(r));
}

fn forget_redo_persisted(seq: usize) {
    forget_in(redo_dir(), seq);
}

fn redo_as_entry(r: &RedoEntry) -> Entry {
    Entry {
        seq: r.seq,
        builtin: r.builtin.clone(),
        effect: r.effect.clone(),
        path: r.path.clone(),
        before: r.after.clone(),
        after: None,
        group: r.group,
    }
}

/// Merge the persisted state into memory so this process sees steps recorded
/// by earlier ones. Once per session directory; a stack that is already
/// populated in memory is never overwritten by what is on disk.
fn hydrate(s: &mut State) {
    let dir = session_dir();
    {
        let mut h = HYDRATED_FROM.lock().unwrap_or_else(|e| e.into_inner());
        if h.as_ref() == Some(&dir) {
            return;
        }
        *h = Some(dir);
    }
    if s.journal.is_empty() {
        s.journal = load_dir(&session_dir().unwrap_or_default());
    }
    if s.redo.is_empty() {
        s.redo = load_dir(&redo_dir().unwrap_or_default())
            .into_iter()
            .filter_map(|e| match e.before {
                Before::Irreversible(_) => None,
                after => Some(RedoEntry {
                    seq: e.seq,
                    builtin: e.builtin,
                    effect: e.effect,
                    path: e.path,
                    after,
                    group: e.group,
                }),
            })
            .collect();
    }
}

/// The hydrated state, locked. Every reader and writer goes through here.
fn state() -> MutexGuard<'static, State> {
    let mut s = STATE.lock().unwrap_or_else(|e| e.into_inner());
    hydrate(&mut s);
    s
}

/// Journalling is on in agent mode and off for humans, matching the rest of the
/// dual-surface split: the agent surface pays a little I/O for recoverability,
/// the human REPL behaves exactly as before. `IRONSHELL_JOURNAL=on`/`off` forces it.
pub fn enabled() -> bool {
    match std::env::var_os("IRONSHELL_JOURNAL")
        .as_deref()
        .and_then(|v| v.to_str())
    {
        Some("on") | Some("1") | Some("true") => true,
        Some("off") | Some("0") | Some("false") => false,
        _ => crate::safety::current_mode() == crate::safety::Mode::Agent,
    }
}

/// Builtins that operate on the journal itself. Recording their writes would
/// make `undo` undo its own restoration, and would make `redo` discard the very
/// stack it is consuming.
fn is_journal_builtin(name: &str) -> bool {
    matches!(
        name,
        "undo"
            | "journal"
            | "journal_clear"
            | "rewind"
            | "session_undo"
            | "session_redo"
            | "session_end"
            | "session_history"
            | "tx_begin"
            | "tx_savepoint"
            | "tx_commit"
            | "tx_rollback"
            | "tx_rollback_to"
    )
}

fn total_bytes(entries: &[Entry]) -> usize {
    entries
        .iter()
        .map(|e| match &e.before {
            Before::Contents(b) => b.len(),
            _ => 0,
        })
        .sum()
}

fn redo_bytes(entries: &[RedoEntry]) -> usize {
    entries
        .iter()
        .map(|e| match &e.after {
            Before::Contents(b) => b.len(),
            _ => 0,
        })
        .sum()
}

/// Bytes held by the journal and the redo stack together.
fn held_bytes(s: &State) -> usize {
    total_bytes(&s.journal) + redo_bytes(&s.redo)
}

/// The file, beside the entries, that holds the next id to hand out. Its name is
/// not a number, so [`load_dir`] never reads it as an entry.
const NEXT_ID_FILE: &str = "next_id";

fn read_next_id(dir: Option<&Path>) -> usize {
    dir.and_then(|d| std::fs::read_to_string(d.join(NEXT_ID_FILE)).ok())
        .and_then(|text| text.trim().parse::<usize>().ok())
        .unwrap_or(0)
}

fn persist_next_id(dir: Option<PathBuf>, next: usize) {
    let Some(dir) = dir else { return };
    let path = dir.join(NEXT_ID_FILE);
    let written =
        make_private_dir(&dir).and_then(|()| write_private(&path, next.to_string().as_bytes()));
    if let Err(err) = written {
        tracing::warn!(
            target: "journal",
            "the next undo id was not persisted, so a later process may reuse one: {}: {err}",
            path.display()
        );
    }
}

/// The id for a new step. Ids only grow within a session: an id is never handed
/// out twice, not after its step is undone, re-applied or cleared, so a saved id
/// cannot come to name a different step. The largest id still held is not enough
/// for that (an undone step's id is gone from the journal), so the next free id
/// is kept on disk beside the entries and read here, since each process loads
/// the journal afresh.
fn take_seq(s: &mut State) -> usize {
    let dir = session_dir();
    let held = s
        .journal
        .iter()
        .map(|e| e.seq)
        .chain(s.redo.iter().map(|r| r.seq))
        .max()
        .unwrap_or(0);
    let id = s.next_id.max(read_next_id(dir.as_deref())).max(held + 1);
    s.next_id = id + 1;
    persist_next_id(dir, s.next_id);
    id
}

/// The argument that names the file a builtin writes, for the builtins that
/// write one named file.
///
/// Keyed by the canonical name, so aliases (`write_file`, `text_write`) share
/// the entry. Without this, the generic rule in [`candidate_paths`] guessed
/// from every string argument, and a bare filename with no directory part
/// (`a1.txt`) never passed its plausibility test: creating such a file left no
/// step, so `undo` reverted an older unrelated step instead.
fn written_path_argument(builtin: &str) -> Option<usize> {
    let canonical = crate::signature::signature_of(builtin).map_or(builtin, |s| s.name);
    match canonical {
        "file_write" | "file_append" | "json_set" | "save_json" | "file_patch" | "file_replace"
        | "file_insert" | "file_edit" | "touch" | "rm" | "tee" => Some(0),
        "file_copy" => Some(1),
        _ => None,
    }
}

/// The path a named-path builtin will write, resolved the way the builtin
/// resolves it, so the entry names the file the step touched whatever the
/// working directory is. Empty when the argument is not a usable path.
fn written_path_candidates(builtin: &str, args: &[Value]) -> Option<Vec<String>> {
    let index = written_path_argument(builtin)?;
    // A string argument this journal can record as a path.
    let usable = |v: Option<&Value>| match v {
        Some(Value::Str(s))
            if !s.is_empty()
                && s.len() <= 4096
                && !s.contains('\n')
                && !s.contains('\0')
                && !crate::safety::names_a_remote_share(s) =>
        {
            Some(crate::safety::resolve_path_str(s))
        }
        _ => None,
    };
    let out = match usable(args.get(index)) {
        Some(mut target) => {
            // A copy into an existing directory writes the file inside it, as
            // `cp` does, so that is the path the step names.
            if index == 1 {
                if let Some(source) = usable(args.first()) {
                    target = crate::builtins::file_copy_target(&source, &target);
                }
            }
            vec![normalized_path(&target)]
        }
        None => Vec::new(),
    };
    Some(out)
}

/// The form every journal entry records a path in: absolute (joined to the
/// working directory when relative), with `.` and `..` resolved lexically and
/// one separator style. `sub/../m2` and `m2` name the same file, so they must
/// be the same entry, or undo checks the wrong spelling and reports a file that
/// exists as absent. Undo restores the same file either way; only the recorded
/// spelling changes. Every recording goes through here.
pub fn normalized_path(path: &str) -> String {
    let p = Path::new(path);
    let absolute: PathBuf = if p.is_absolute() {
        p.to_path_buf()
    } else {
        match std::env::current_dir() {
            Ok(cwd) => cwd.join(p),
            Err(_) => p.to_path_buf(),
        }
    };
    let mut out = PathBuf::new();
    for component in absolute.components() {
        match component {
            Component::CurDir => {}
            Component::ParentDir => {
                // Only a normal name is resolved away. `..` at a root stays at
                // the root; a leading `..` that climbs out is kept.
                let last_is_name =
                    matches!(out.components().next_back(), Some(Component::Normal(_)));
                let at_root = matches!(
                    out.components().next_back(),
                    Some(Component::RootDir) | Some(Component::Prefix(_))
                );
                if last_is_name {
                    out.pop();
                } else if !at_root {
                    out.push("..");
                }
            }
            other => out.push(other.as_os_str()),
        }
    }
    out.display().to_string()
}

/// A string argument that plausibly names a file this call could write.
///
/// Deliberately generous: capturing a path the builtin never touches costs one
/// file read and restores identical bytes on undo, which is harmless. Missing
/// one loses the ability to recover it, which is not. The asymmetry decides the
/// bias. Builtins in [`written_path_argument`] name their file explicitly and
/// skip this guess.
fn candidate_paths(builtin: &str, args: &[Value]) -> Vec<String> {
    if let Some(paths) = written_path_candidates(builtin, args) {
        return paths;
    }
    let mut out = Vec::new();
    for a in args {
        if let Value::Str(s) = a {
            if s.is_empty() || s.len() > 4096 || s.contains('\n') || s.contains('\0') {
                continue;
            }
            // Asking whether a remote share exists opens a session to its host,
            // before the call site's jail has refused it; a share is not captured.
            if crate::safety::names_a_remote_share(s) {
                continue;
            }
            let p = Path::new(s);
            let plausible = p.is_file()
                || p.parent()
                    .map(|d| !d.as_os_str().is_empty() && d.is_dir())
                    .unwrap_or(false);
            let absolute = normalized_path(s);
            if plausible && !out.contains(&absolute) {
                out.push(absolute);
            }
        }
    }
    out
}

/// The current state of `path`, captured for the journal, or the reason it
/// cannot be. `used` is the bytes already held, so the session-wide budget is
/// respected.
fn capture(path: &str, used: usize) -> Result<Before, String> {
    let p = Path::new(path);
    if p.is_file() {
        let size = std::fs::metadata(p)
            .map(|m| m.len() as usize)
            .map_err(|e| format!("unstattable: {e}"))?;
        if size > MAX_FILE_BYTES {
            return Err(format!(
                "{size} bytes exceeds the {MAX_FILE_BYTES}-byte capture limit"
            ));
        }
        if used + size > MAX_TOTAL_BYTES {
            return Err("session capture budget exhausted".into());
        }
        std::fs::read(p)
            .map(Before::Contents)
            .map_err(|e| format!("unreadable: {e}"))
    } else if p.exists() {
        // A directory: restoring a tree is out of scope, and pretending
        // otherwise is the failure this module exists to avoid.
        Err("path is a directory; trees are not captured".into())
    } else {
        Ok(Before::Absent)
    }
}

/// [`capture`], except that an empty directory is captured as one: undo recreates
/// it, and a redo removes it again. Used where a step's own state is read back
/// (after an undo, or before a redo), not for the paths a call might write.
fn capture_state(path: &str, used: usize) -> Result<Before, String> {
    let p = Path::new(path);
    let is_real_dir = std::fs::symlink_metadata(p).is_ok_and(|m| m.is_dir());
    if is_real_dir && std::fs::read_dir(p).is_ok_and(|mut d| d.next().is_none()) {
        return Ok(Before::Directory);
    }
    capture(path, used)
}

/// Record the pre-state of anything `builtin` might overwrite. Call immediately
/// before dispatch.
///
/// A mutating step discards the redo stack whether or not it touches a
/// candidate path: a new action ends the undone future.
pub fn record_before(builtin: &str, effect: Effect, args: &[Value]) {
    NO_CHANGE.with(|c| c.set(false));
    if !enabled() || is_journal_builtin(builtin) || records_its_own_steps(builtin) {
        return;
    }
    if !matches!(effect, Effect::WriteLocal | Effect::Destructive) {
        return;
    }
    let paths = candidate_paths(builtin, args);
    let mut s = state();
    discard_redo(&mut s);
    for path in paths {
        push_capture(&mut s, builtin, effect, path, None);
    }
}

/// Builtins that record their own steps, because the dispatcher's guess at their
/// paths is wrong for them: a move changes both ends ([`record_group`]), and a
/// directory removal is recorded as irreversible ([`record_irreversible`]). The
/// guess resolves a relative name against the process directory, not the
/// workspace, so it captured the wrong path.
///
/// The archive and compression builtins are here too: the guess takes every
/// string argument that is a file, which is the file they only read (the
/// archive being extracted, the source being compressed), while the files they
/// write are never an argument. Each records the files it writes, before it
/// writes them: an extraction every member and created directory, a creator its
/// new output, `zip_add` and `file_backup` the file they replace.
fn records_its_own_steps(builtin: &str) -> bool {
    let canonical = crate::signature::signature_of(builtin).map_or(builtin, |s| s.name);
    matches!(
        canonical,
        "file_move"
            | "file_mkdir"
            | "rmdir"
            | "zip_extract"
            | "tar_extract"
            | "zip_create"
            | "zip_add"
            | "tar_create"
            | "gzip_compress"
            | "gzip_decompress"
            | "bzip2_compress"
            | "bzip2_decompress"
            | "xz_compress"
            | "xz_decompress"
            | "zstd_compress"
            | "zstd_decompress"
            | "file_backup"
            | "ssh_keygen"
            | "db_sqlite_backup"
            | "openssl_genrsa"
            | "gpg_encrypt"
            | "gpg_decrypt"
            | "age_encrypt"
            | "age_decrypt"
            | "age_keygen"
            | "dd_copy"
            | "db_sqlite_create"
            | "db_sqlite_open"
            | "db_sqlite_insert"
            | "db_sqlite_update"
            | "db_sqlite_delete"
            | "db_sqlite_create_table"
            | "db_sqlite_drop_table"
            | "db_sqlite_vacuum"
            | "db_sqlite_import"
            | "db_sqlite_to_csv"
            | "db_json_to_sqlite"
            | "db_kv_set"
            | "db_kv_delete"
            | "db_kv_store"
    )
}

/// Record the pre-state of the one file `builtin` is about to write or create,
/// as one step, unless the call in flight already recorded it. For a builtin
/// that writes a file no argument names as a bare path (a database it opens, an
/// output it creates): absent before is recorded as absent, so undo removes a
/// file the call created instead of restoring an empty one.
///
/// A builtin that reaches its writer more than once in a call (`db_kv_set`
/// creates its table, then inserts) records one step: the entry just before is
/// the same path, and a step the dispatcher has settled is sealed, so an
/// unsealed last entry for the path belongs to this call.
pub fn record_file_once(builtin: &str, path: &str) {
    if !enabled() || is_journal_builtin(builtin) || path.is_empty() || path == ":memory:" {
        return;
    }
    let normalized = normalized_path(path);
    let mut s = state();
    if let Some(last) = s.journal.last() {
        if last.path == normalized && last.after.is_none() && last.reversible() {
            return;
        }
    }
    discard_redo(&mut s);
    let group = Some(take_seq(&mut s));
    push_capture(&mut s, builtin, Effect::WriteLocal, normalized, group);
}

/// Write `bytes` over `path` for an undo or a redo. A file that is read-only
/// refuses the write (on Windows always), and the step being undone may be the
/// `chmod` that made it so: the content is then written under the owner's write
/// bit, which is the mode the file had when the step began. A file that was
/// already read-only before the step cannot have been written by one.
#[allow(clippy::permissions_set_readonly_false)]
fn write_over(path: &str, bytes: &[u8]) -> std::io::Result<()> {
    match std::fs::write(path, bytes) {
        Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
            let mut perms = std::fs::metadata(path)?.permissions();
            if !perms.readonly() {
                return Err(e);
            }
            #[cfg(unix)]
            perms.set_mode(perms.mode() | 0o200);
            #[cfg(not(unix))]
            perms.set_readonly(false);
            std::fs::set_permissions(path, perms)?;
            std::fs::write(path, bytes)
        }
        other => other,
    }
}

/// Record the pre-state of named paths that a builtin is about to write or
/// delete, for a caller that knows its targets without an argument to parse.
/// `apply` uses it once per op, before the op runs, so that each file a plan
/// touches can be undone. Same rules as [`record_before`].
pub fn record_paths(builtin: &str, effect: Effect, paths: Vec<String>) {
    if !enabled() || is_journal_builtin(builtin) {
        return;
    }
    if !matches!(effect, Effect::WriteLocal | Effect::Destructive) {
        return;
    }
    let mut s = state();
    discard_redo(&mut s);
    for path in paths {
        push_capture(&mut s, builtin, effect, path, None);
    }
}

/// Record the pre-state of every path one call changes, as one step: undo puts
/// all of them back in a single `undo()`, and redo re-applies them together. For
/// a call whose single argument does not name every path it writes, such as a
/// move, which removes its source and replaces its destination. Same rules as
/// [`record_before`]; call it after the call's approval has passed and before
/// it changes anything.
pub fn record_group(builtin: &str, effect: Effect, paths: Vec<String>) {
    if !enabled() || is_journal_builtin(builtin) {
        return;
    }
    if !matches!(effect, Effect::WriteLocal | Effect::Destructive) {
        return;
    }
    let mut s = state();
    discard_redo(&mut s);
    let group = Some(take_seq(&mut s));
    for path in paths {
        push_capture(&mut s, builtin, effect, path, group);
    }
}

/// Whether [`record_before`] would keep the bytes of `path`, so that undo can
/// put them back: the journal is on, and the path is a regular file within the
/// capture limits. A delete asks this before it runs, so that the approval it
/// is asked for says `reversible` only when the journal will restore the file.
pub fn would_capture(path: &str) -> bool {
    if !enabled() {
        return false;
    }
    let Ok(meta) = std::fs::metadata(path) else {
        return false;
    };
    if !meta.is_file() {
        return false;
    }
    let size = meta.len() as usize;
    size <= MAX_FILE_BYTES && held_bytes(&state()) + size <= MAX_TOTAL_BYTES
}

/// Capture `path` as a new step. The caller holds the journal lock, so the
/// budget it measures and the entry it pushes are one decision.
fn push_capture(s: &mut State, builtin: &str, effect: Effect, path: String, group: Option<usize>) {
    let path = normalized_path(&path);
    let used = held_bytes(s);
    let before = match capture(&path, used) {
        Ok(before) => before,
        Err(why) => Before::Irreversible(why),
    };
    let seq = take_seq(s);
    let entry = Entry {
        seq,
        builtin: builtin.to_string(),
        effect: effect.as_str().to_string(),
        path,
        before,
        after: None,
        group,
    };
    persist(&entry);
    s.journal.push(entry);
}

thread_local! {
    /// Set by a builtin that completed without changing the file it was asked
    /// to change (`file_patch` with no pattern found). The dispatcher drops the
    /// step recorded for that call, so `undo` does not report a restore that
    /// never happened.
    static NO_CHANGE: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
}

/// Called by a builtin that completed but changed nothing.
pub fn report_no_change() {
    NO_CHANGE.with(|c| c.set(true));
}

/// Whether the call that just ran reported no change. Clears the report.
pub fn take_no_change() -> bool {
    NO_CHANGE.with(|c| c.replace(false))
}

/// Note a step that changed the world in a way no snapshot can capture, so a
/// later rewind can say so. Like [`record_before`], this discards the redo
/// stack.
pub fn record_irreversible(builtin: &str, effect: Effect, why: &str) {
    if !enabled() || is_journal_builtin(builtin) {
        return;
    }
    let mut s = state();
    discard_redo(&mut s);
    let seq = take_seq(&mut s);
    let entry = Entry {
        seq,
        builtin: builtin.to_string(),
        effect: effect.as_str().to_string(),
        path: String::new(),
        before: Before::Irreversible(why.to_string()),
        after: None,
        group: None,
    };
    persist(&entry);
    s.journal.push(entry);
}

/// Note the removal of the directory at `path`, before it happens. An empty
/// directory is recorded as one that undo recreates; anything else cannot be
/// restored, so it is recorded as irreversible with `tree_why` as the reason.
/// Like [`record_before`], this discards the redo stack. A removal that fails
/// leaves no step: the dispatcher settles the call.
pub fn record_removed_directory(builtin: &str, effect: Effect, path: &str, tree_why: &str) {
    if !enabled() || is_journal_builtin(builtin) {
        return;
    }
    if !matches!(effect, Effect::WriteLocal | Effect::Destructive) {
        return;
    }
    let path = normalized_path(path);
    let mut s = state();
    discard_redo(&mut s);
    let before = match capture_state(&path, held_bytes(&s)) {
        Ok(before) => before,
        Err(_) => Before::Irreversible(tree_why.to_string()),
    };
    let seq = take_seq(&mut s);
    let entry = Entry {
        seq,
        builtin: builtin.to_string(),
        effect: effect.as_str().to_string(),
        path,
        before,
        after: None,
        group: None,
    };
    persist(&entry);
    s.journal.push(entry);
}

/// Once a journalled call has run: a call that failed, or that reported no
/// change, leaves no step; a call that succeeded has its new steps sealed with
/// the state they left. `mark` is the journal length before the call.
pub fn settle(mark: usize, ok: bool) {
    if !ok || take_no_change() {
        rollback_to(mark);
    } else {
        seal_since(mark);
    }
}

/// Seal the steps recorded after `mark` with the state they left their paths
/// in, for a caller that settles its own steps instead of going through the
/// dispatcher (`apply` does: its effect is `Exec`, so the dispatcher does not).
pub fn seal_steps(mark: usize) {
    seal_since(mark);
}

/// Record the state that each step recorded after `mark` left its path in.
/// A step that is already sealed (an inner call of the same operation) keeps
/// its seal, since the state it was sealed in is the state it left.
fn seal_since(mark: usize) {
    let mut s = state();
    for e in s.journal.iter_mut().skip(mark) {
        if e.after.is_some() || e.path.is_empty() || !e.reversible() {
            continue;
        }
        if let Some(after) = Fingerprint::of_path(&e.path) {
            e.after = Some(after);
            persist(e);
        }
    }
}

/// Forget the redo stack, in memory and on disk.
fn discard_redo(s: &mut State) {
    s.redo.clear();
    if let Some(dir) = redo_dir() {
        if let Err(err) = remove_if_present(std::fs::remove_dir_all(&dir)) {
            warn_left_behind(&dir, &err);
        }
    }
}

/// The outcome of rewinding or re-applying one entry.
#[derive(Clone, Debug, PartialEq)]
pub enum Outcome {
    Restored(String),
    Removed(String),
    /// Re-applied by [`redo`]: the file was written with its post-step bytes.
    Reapplied(String),
    Skipped {
        what: String,
        why: String,
    },
    Failed {
        what: String,
        why: String,
    },
}

/// One outcome of [`undo`] or [`undo_by_id`], with the id of the step it came
/// from, so the record names the step the way `journal()` does. `seq` is None
/// only for an outcome that belongs to no step.
#[derive(Clone, Debug, PartialEq)]
pub struct Rewound {
    pub seq: Option<usize>,
    pub outcome: Outcome,
}

/// Undo the last `n` recorded steps, most recent first.
///
/// Returns an outcome per entry — including the ones it could not reverse.
/// Callers must surface those: a rewind that reports only its successes is how
/// a partial restore gets mistaken for a complete one.
///
/// A step whose restore fails stays in the journal, and the undo stops there,
/// so the step can be retried and no older step is undone past it.
///
/// Each step that is actually reversed is pushed onto the redo stack, so
/// [`redo`] can put it back. A file that holds something undo cannot keep, such
/// as a version over the capture limit, is left alone and the undo stops there:
/// it may have changed since the step, and overwriting it would lose that
/// version for good. Moving the file away lets the step be undone.
///
/// A step that recorded the state it left its file in is refused when the file
/// has changed since, unless `force` is set: those changes would be discarded.
/// When the first step in line is refused nothing has been undone, and the
/// path and whether it was removed since the step are returned as the error. A
/// later step's refusal is an outcome, as the others are, and ends the undo.
pub fn undo(n: usize, force: bool) -> Result<Vec<Rewound>, (String, bool)> {
    let mut s = state();
    let mut out = Vec::new();
    // Steps counted so far, and the group of the step in progress: the entries
    // of one group are one step, however many there are.
    let mut steps = 0;
    let mut group: Option<usize> = None;
    while let Some(top) = s.journal.last() {
        let top_group = top.group;
        if group.is_none() || top_group != group {
            if steps == n {
                break;
            }
            steps += 1;
            group = top_group;
        }
        let index = s.journal.len() - 1;
        match undo_at(&mut s, index, force, &mut out) {
            Step::Next => {}
            Step::Stop => {
                report_not_reached(&s, index, n, steps, group, &mut out);
                break;
            }
            Step::Refused(refusal) => return Err(refusal),
        }
    }
    Ok(out)
}

/// An undo that stopped at `index` did not touch the older steps it was asked
/// for. Each is listed as skipped, so the record accounts for every step in the
/// range: one that is missing from `steps` reads as one that was undone.
/// `steps` and `group` are the undo's own count so far, as in [`undo`].
fn report_not_reached(
    s: &State,
    index: usize,
    n: usize,
    mut steps: usize,
    mut group: Option<usize>,
    out: &mut Vec<Rewound>,
) {
    let blocker = s.journal.get(index).map(|e| e.seq);
    for e in s.journal[..index.min(s.journal.len())].iter().rev() {
        if group.is_none() || e.group != group {
            if steps == n {
                break;
            }
            steps += 1;
            group = e.group;
        }
        let what = if e.path.is_empty() {
            e.builtin.clone()
        } else {
            e.path.clone()
        };
        let why = match blocker {
            Some(b) => format!(
                "not reached: the undo stopped at step {b} and does not go past it; this step is still in the journal"
            ),
            None => "not reached: the undo stopped at a newer step and does not go past it; this step is still in the journal".to_string(),
        };
        out.push(Rewound {
            seq: Some(e.seq),
            outcome: Outcome::Skipped { what, why },
        });
    }
}

/// What one call to [`undo_at`] did, and what the caller does next.
enum Step {
    /// The entry was undone, or finished with, and left the journal.
    Next,
    /// The undo ends here: a step was left alone, or its restore failed.
    Stop,
    /// The first step in line was refused because its file changed: the path,
    /// and whether it was removed since the step.
    Refused((String, bool)),
}

/// Undo the journal entry at `index`, which the caller has checked is in the
/// journal. The outcome is pushed onto `out`, tagged with the entry's id; the
/// entry leaves the journal when it is finished with.
fn undo_at(s: &mut State, index: usize, force: bool, out: &mut Vec<Rewound>) -> Step {
    let seq = s.journal.get(index).map(|e| e.seq);
    // Checked before anything is taken: a step left alone stays in the
    // journal, and nothing older is undone past it, so the order is kept.
    if let Some(why) = s
        .journal
        .get(index)
        .and_then(|e| crate::safety::rewind_refused(&e.path))
    {
        let what = s
            .journal
            .get(index)
            .map(|e| e.path.clone())
            .unwrap_or_default();
        out.push(Rewound {
            seq,
            outcome: Outcome::Skipped { what, why },
        });
        return Step::Stop;
    }
    // Cloned, not popped. The entry stays in the journal and on disk until
    // its restore has succeeded, because it holds the only copy of what the
    // file held before the step: a failed restore that had already dropped
    // it would leave the caller nothing to retry with.
    let Some(entry) = s.journal.get(index).cloned() else {
        return Step::Stop;
    };
    // The entry is still counted in held_bytes, so it is taken out for the
    // capture below: the budget is what it was when the entry was popped.
    let used = held_bytes(s).saturating_sub(total_bytes(std::slice::from_ref(&entry)));
    let what = if entry.path.is_empty() {
        entry.builtin.clone()
    } else {
        entry.path.clone()
    };
    // The file is not restored over what a later hand edit (or a step the
    // journal did not see) put there. Nothing is undone when that is the
    // first step; otherwise the refusal ends the undo as an outcome.
    // A file the step left in place that is now absent was removed since:
    // undoing would recreate it, so that is a change too. A step that
    // removed the file (sealed absent) and finds it still absent is the
    // ordinary undo, and is not refused.
    if let (false, Some(sealed)) = (force, &entry.after) {
        let now = Fingerprint::of_path(&entry.path);
        // Only an undo that writes the file back recreates it. Undoing a step
        // that created the file removes nothing, and nothing is recreated.
        let restores = matches!(entry.before, Before::Contents(_) | Before::Directory);
        let removed =
            restores && now == Some(Fingerprint::Absent) && *sealed != Fingerprint::Absent;
        let changed = if now == Some(Fingerprint::Absent) {
            removed
        } else {
            now.as_ref() != Some(sealed)
        };
        if changed {
            if out.is_empty() {
                return Step::Refused((entry.path.clone(), removed));
            }
            out.push(Rewound {
                seq,
                outcome: Outcome::Skipped {
                    what,
                    why: if removed {
                        REMOVED_SINCE_STEP.to_string()
                    } else {
                        CHANGED_SINCE_STEP.to_string()
                    },
                },
            });
            return Step::Stop;
        }
    }
    let after = capture_state(&entry.path, used);
    // As in redo: a file is not overwritten or removed unless what it holds
    // now is first kept. A path that is not a file is not touched by this
    // check; the restore below reports it.
    if !matches!(entry.before, Before::Irreversible(_)) && Path::new(&entry.path).is_file() {
        if let Err(why) = &after {
            out.push(Rewound {
                seq,
                outcome: Outcome::Skipped {
                    what,
                    why: format!(
                        "current contents could not be kept for redo, so left as they are: {why}. Move the file away to undo this step"
                    ),
                },
            });
            return Step::Stop;
        }
    }
    let outcome = match &entry.before {
        Before::Contents(bytes) => match write_over(&entry.path, bytes) {
            Ok(()) => {
                push_redo(s, &entry, after);
                Outcome::Restored(what)
            }
            Err(e) => Outcome::Failed {
                what,
                why: e.to_string(),
            },
        },
        Before::Absent => {
            let outcome = remove_created(&entry.path, what, ABSENT_BEFORE_AND_NOW);
            if matches!(outcome, Outcome::Removed(_)) {
                push_redo(s, &entry, after);
            }
            outcome
        }
        Before::Directory => {
            let outcome = restore_directory(&entry.path, what);
            if matches!(outcome, Outcome::Restored(_)) {
                push_redo(s, &entry, after);
            }
            outcome
        }
        Before::Irreversible(why) => Outcome::Skipped {
            what,
            why: why.clone(),
        },
    };
    if matches!(outcome, Outcome::Failed { .. }) {
        // The step stays where it was, for a retry. Older steps are not
        // undone past it.
        out.push(Rewound { seq, outcome });
        return Step::Stop;
    }
    // Restored, removed, or finished with (nothing to take back): the step
    // is done with, so it leaves the journal and the disk now.
    s.journal.remove(index);
    forget_persisted(entry.seq);
    out.push(Rewound { seq, outcome });
    Step::Next
}

/// Why [`undo_by_id`] leaves a step alone.
#[derive(Debug)]
pub enum UndoRefusal {
    /// No journal entry has that id.
    NotFound,
    /// A later step recorded one of the same paths, so putting this step's
    /// file back would undo that later change too.
    LaterStep { seq: usize, path: String },
    /// The file changed after the step (or was removed), as [`undo`] refuses.
    Changed { path: String, removed: bool },
}

/// Undo one journal entry, by its id (the `seq` the journal listing shows), and
/// leave the other steps in place.
///
/// An entry that shares its group with others (a move) is undone with the whole
/// group, as [`undo`] counts a group as one step. Unless `force` is set, the step
/// is refused when a later entry recorded one of its paths: restoring that path
/// would also undo the later change. The same checks as [`undo`] apply to each
/// entry undone.
pub fn undo_by_id(seq: usize, force: bool) -> Result<Vec<Rewound>, UndoRefusal> {
    let mut s = state();
    let first = s
        .journal
        .iter()
        .position(|e| e.seq == seq)
        .ok_or(UndoRefusal::NotFound)?;
    let group = s.journal[first].group;
    let members: Vec<usize> = match group {
        None => vec![first],
        Some(g) => (0..s.journal.len())
            .filter(|&i| s.journal[i].group == Some(g))
            .collect(),
    };
    let last = members.last().copied().unwrap_or(first);
    if !force {
        for later in s.journal.iter().skip(last + 1) {
            if !later.path.is_empty() && members.iter().any(|&m| s.journal[m].path == later.path) {
                return Err(UndoRefusal::LaterStep {
                    seq: later.seq,
                    path: later.path.clone(),
                });
            }
        }
    }
    let mut out = Vec::new();
    // Newest first, so removing an entry does not move the ones still to undo.
    for &index in members.iter().rev() {
        match undo_at(&mut s, index, force, &mut out) {
            Step::Next => {}
            Step::Stop => break,
            Step::Refused((path, removed)) => return Err(UndoRefusal::Changed { path, removed }),
        }
    }
    Ok(out)
}

/// Why undo leaves a file alone that changed after its step.
const CHANGED_SINCE_STEP: &str = "changed after this step, so undoing would discard those changes; left as it is. Read the file, or undo({force: true}) to restore it anyway";

/// Why undo leaves a path alone that was removed after its step.
const REMOVED_SINCE_STEP: &str = "was removed after this step; undoing would recreate it; left as it is. undo({force: true}) recreates it";

/// Why a step leaves a path alone that it created: it is no longer absent-before.
const ABSENT_BEFORE_AND_NOW: &str = "was absent before and is absent now";

/// Why a created directory is left alone: something was put in it afterwards,
/// and removing it would remove that too.
const NOT_EMPTY_SINCE_STEP: &str = "holds files this step did not record, so it is left as it is";

/// Remove what a step created at `path`: a file, or a directory that is still
/// empty. A directory with anything in it is left alone and reported, not
/// removed with its contents. `absent_why` is the reason when nothing is there.
fn remove_created(path: &str, what: String, absent_why: &str) -> Outcome {
    let p = Path::new(path);
    if p.is_file() {
        return match std::fs::remove_file(p) {
            Ok(()) => Outcome::Removed(what),
            Err(e) => Outcome::Failed {
                what,
                why: e.to_string(),
            },
        };
    }
    if std::fs::symlink_metadata(p).is_ok_and(|m| m.is_dir()) {
        return match std::fs::remove_dir(p) {
            Ok(()) => Outcome::Removed(what),
            Err(e) if crate::safety::dir_not_empty(&e) => Outcome::Skipped {
                what,
                why: NOT_EMPTY_SINCE_STEP.into(),
            },
            Err(e) => Outcome::Failed {
                what,
                why: e.to_string(),
            },
        };
    }
    // Never created, or already gone: there is nothing to take back.
    Outcome::Skipped {
        what,
        why: absent_why.into(),
    }
}

/// Recreate the empty directory a step removed. A directory that is there and
/// empty already is as it was. Anything else in its place is left alone.
fn restore_directory(path: &str, what: String) -> Outcome {
    let p = Path::new(path);
    match std::fs::symlink_metadata(p) {
        Ok(m) if m.is_dir() => {
            if std::fs::read_dir(p).is_ok_and(|mut d| d.next().is_none()) {
                Outcome::Restored(what)
            } else {
                Outcome::Skipped {
                    what,
                    why: "exists now and holds files, so it is left as it is".into(),
                }
            }
        }
        Ok(_) => Outcome::Failed {
            what,
            why: "a file is in its place".into(),
        },
        Err(_) => match std::fs::create_dir(p) {
            Ok(()) => Outcome::Restored(what),
            Err(e) => Outcome::Failed {
                what,
                why: e.to_string(),
            },
        },
    }
}

/// Push the state an undone step produced onto the redo stack. Pushes nothing
/// when that state could not be captured or would exceed the budget: the undo
/// has already happened and its outcome stands.
fn push_redo(s: &mut State, undone: &Entry, after: Result<Before, String>) {
    let Ok(after) = after else { return };
    let r = RedoEntry {
        // The undone step keeps the id it was recorded under, so the undone list
        // and the journal name a step the same way.
        seq: undone.seq,
        builtin: undone.builtin.clone(),
        effect: undone.effect.clone(),
        path: undone.path.clone(),
        after,
        group: undone.group,
    };
    persist_redo(&r);
    s.redo.push(r);
}

/// Re-apply the last `n` undone steps, most recently undone first.
///
/// The state being replaced is captured as a new journal entry before the
/// write, so the redo is itself undoable. That capture does not touch the redo
/// stack: the stack is only consumed here.
///
/// As with [`undo`], a step whose re-apply fails stays on the redo stack, and
/// the redo stops there, so it can be retried.
pub fn redo(n: usize) -> Vec<Outcome> {
    let mut s = state();
    let mut out = Vec::new();
    // As in undo: the entries of one group are one step.
    let mut steps = 0;
    let mut group: Option<usize> = None;
    while let Some(top) = s.redo.last() {
        if group.is_none() || top.group != group {
            if steps == n {
                break;
            }
            steps += 1;
            group = top.group;
        }
        if let Some(why) = s
            .redo
            .last()
            .and_then(|r| crate::safety::rewind_refused(&r.path))
        {
            let what = s.redo.last().map(|r| r.path.clone()).unwrap_or_default();
            out.push(Outcome::Skipped { what, why });
            break;
        }
        // Cloned, not popped: the step stays on the redo stack, and on disk,
        // until it has been re-applied, so a failed re-apply can be retried.
        let Some(r) = s.redo.last().cloned() else {
            break;
        };
        // As in undo: the entry is still counted in held_bytes, so take it out
        // for the capture below.
        let used = held_bytes(&s).saturating_sub(redo_bytes(std::slice::from_ref(&r)));
        let what = if r.path.is_empty() {
            r.builtin.clone()
        } else {
            r.path.clone()
        };
        // The file is not touched unless what it holds now is first kept. If
        // that cannot be kept, the file is left alone and the step stays on the
        // redo stack, so the redo stops here.
        let current = match capture_state(&r.path, used) {
            Ok(current) => current,
            Err(why) => {
                out.push(Outcome::Skipped {
                    what,
                    why: format!("current state not captured, so left as it is: {why}"),
                });
                break;
            }
        };
        let outcome = match &r.after {
            Before::Contents(bytes) => match write_over(&r.path, bytes) {
                Ok(()) => Outcome::Reapplied(what),
                Err(e) => Outcome::Failed {
                    what,
                    why: e.to_string(),
                },
            },
            Before::Absent => {
                remove_created(&r.path, what, "was absent after the step and is absent now")
            }
            Before::Directory => match restore_directory(&r.path, what) {
                Outcome::Restored(what) => Outcome::Reapplied(what),
                other => other,
            },
            Before::Irreversible(why) => Outcome::Skipped {
                what,
                why: why.clone(),
            },
        };
        if matches!(outcome, Outcome::Failed { .. }) {
            // Still on the redo stack, and on disk, for a retry. Nothing newer
            // or older is re-applied past it.
            out.push(outcome);
            break;
        }
        // Re-applied, removed, or finished with: the step leaves the redo stack.
        s.redo.pop();
        forget_redo_persisted(r.seq);
        if matches!(outcome, Outcome::Reapplied(_) | Outcome::Removed(_)) {
            // Only a write that actually happened is recorded, so the redo is
            // itself undoable.
            let seq = take_seq(&mut s);
            let entry = Entry {
                seq,
                builtin: r.builtin,
                effect: r.effect,
                path: r.path,
                before: current,
                // The state this re-apply wrote, so a later undo of it is
                // checked the same way as any other step.
                after: Fingerprint::of_before(&r.after),
                group: r.group,
            };
            persist(&entry);
            s.journal.push(entry);
        }
        out.push(outcome);
    }
    out
}

/// Every recorded step, oldest first.
pub fn entries() -> Vec<Entry> {
    let s = state();
    s.journal
        .iter()
        .map(|e| Entry {
            // The captured bytes are never handed out; they would be a second
            // copy of the data in the agent's context for no benefit.
            before: match &e.before {
                Before::Contents(b) => Before::Contents(vec![0; b.len().min(1)]),
                other => other.clone(),
            },
            ..e.clone()
        })
        .collect()
}

/// Every undone step that can still be re-applied, most recently undone last.
/// Captured bytes are not handed out, as with [`entries`].
pub fn undone() -> Vec<RedoEntry> {
    let s = state();
    s.redo
        .iter()
        .map(|r| RedoEntry {
            after: match &r.after {
                Before::Contents(b) => Before::Contents(vec![0; b.len().min(1)]),
                other => other.clone(),
            },
            ..r.clone()
        })
        .collect()
}

/// How many undone steps can still be re-applied.
pub fn redo_count() -> usize {
    state().redo.len()
}

/// How many recorded steps can actually be reversed.
pub fn reversible_count() -> usize {
    state().journal.iter().filter(|e| e.reversible()).count()
}

/// The current end of the journal, for [`rollback_to`].
pub fn mark() -> usize {
    state().journal.len()
}

/// Discard entries recorded after `mark`, because the call they were recorded
/// for did not happen.
///
/// Found by using the shell as an agent: a `file_write` refused by the
/// workspace jail still left a journal entry, so `undo()` answered
/// `complete: false, skipped: 1` about an operation that never ran. The report
/// was honest but the entry was fiction, and an agent reading `complete: false`
/// would reasonably conclude something was left unreversed.
pub fn rollback_to(mark: usize) {
    let mut s = state();
    while s.journal.len() > mark {
        if let Some(e) = s.journal.pop() {
            forget_persisted(e.seq);
        }
    }
}

/// Forget everything recorded, the journal and the redo stack alike. Does not
/// touch the filesystem outside the session directory.
pub fn clear() {
    if let Err((dir, err)) = try_clear() {
        warn_left_behind(&dir, &err);
    }
}

/// [`clear`], saying which directory survived. What is left there comes back in
/// a later process and may hold the contents of overwritten files, so a caller
/// that tells someone the steps are gone has to know.
pub fn try_clear() -> Result<(), (PathBuf, std::io::Error)> {
    // The lock is held through the removal. A step recorded on another thread
    // persists into this directory only while it holds the same lock, so none
    // can create a file in the directory while it is being emptied.
    let mut s = STATE.lock().unwrap_or_else(|e| e.into_inner());
    s.journal.clear();
    s.redo.clear();
    // Read before the directory goes: a process that cleared without taking an
    // id of its own knows only what the file says.
    let next = s.next_id.max(read_next_id(session_dir().as_deref()));
    if let Some(dir) = session_dir() {
        // Windows reports a directory as Access denied while another process
        // holds one of its files (a virus scanner, the indexer) or a delete is
        // still pending. Retry briefly there; elsewhere one attempt is enough.
        let attempts = if cfg!(windows) { REMOVE_ATTEMPTS } else { 1 };
        let removed = remove_dir_retrying(
            &dir,
            attempts,
            |d| std::fs::remove_dir_all(d),
            std::thread::sleep,
        );
        remove_if_present(removed).map_err(|err| (dir.clone(), err))?;
        // A cleared journal is not a fresh session: the ids handed out so far
        // stay handed out.
        if next > 0 {
            persist_next_id(Some(dir), next);
        }
    }
    Ok(())
}

/// How many times [`try_clear`] tries to remove the journal directory on
/// Windows, with [`REMOVE_PAUSES`] between tries: at most half a second.
const REMOVE_ATTEMPTS: u32 = 5;
const REMOVE_PAUSES: [std::time::Duration; 4] = [
    std::time::Duration::from_millis(50),
    std::time::Duration::from_millis(100),
    std::time::Duration::from_millis(150),
    std::time::Duration::from_millis(200),
];

/// Run `remove` on `dir`, up to `attempts` times, pausing between tries, while
/// it fails with a refusal that another process can cause and that goes away
/// (Access denied, or a sharing violation). Any other error is returned at
/// once, as is the last one when every attempt fails.
fn remove_dir_retrying(
    dir: &Path,
    attempts: u32,
    mut remove: impl FnMut(&Path) -> std::io::Result<()>,
    mut pause: impl FnMut(std::time::Duration),
) -> std::io::Result<()> {
    let mut tries = 1;
    loop {
        match remove(dir) {
            Ok(()) => return Ok(()),
            Err(e)
                if tries < attempts
                    && (e.kind() == std::io::ErrorKind::PermissionDenied
                        || e.raw_os_error() == Some(32)) =>
            {
                let wait = REMOVE_PAUSES[(tries as usize - 1).min(REMOVE_PAUSES.len() - 1)];
                pause(wait);
                tries += 1;
            }
            Err(e) => return Err(e),
        }
    }
}

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

    fn access_denied() -> std::io::Error {
        std::io::Error::new(std::io::ErrorKind::PermissionDenied, "Access is denied.")
    }

    #[test]
    fn a_refusal_to_remove_that_goes_away_is_retried() {
        // Windows: a file still held by another process for two tries.
        let mut calls = 0;
        let mut pauses = Vec::new();
        let r = remove_dir_retrying(
            Path::new("journal"),
            REMOVE_ATTEMPTS,
            |_| {
                calls += 1;
                if calls < 3 {
                    Err(access_denied())
                } else {
                    Ok(())
                }
            },
            |p| pauses.push(p),
        );
        assert!(r.is_ok());
        assert_eq!(calls, 3);
        assert_eq!(pauses.len(), 2);
    }

    #[test]
    fn a_refusal_that_persists_is_reported_within_half_a_second() {
        let mut calls = 0;
        let mut waited = std::time::Duration::ZERO;
        let r = remove_dir_retrying(
            Path::new("journal"),
            REMOVE_ATTEMPTS,
            |_| {
                calls += 1;
                Err(access_denied())
            },
            |p| waited += p,
        );
        assert_eq!(r.unwrap_err().kind(), std::io::ErrorKind::PermissionDenied);
        assert_eq!(calls, REMOVE_ATTEMPTS);
        assert!(
            waited <= std::time::Duration::from_millis(500),
            "{waited:?}"
        );
    }

    #[test]
    fn an_error_that_is_not_a_transient_refusal_is_not_retried() {
        let mut calls = 0;
        let r = remove_dir_retrying(
            Path::new("journal"),
            REMOVE_ATTEMPTS,
            |_| {
                calls += 1;
                Err(std::io::Error::other("disk on fire"))
            },
            |_| panic!("paused before a non-transient error"),
        );
        assert!(r.is_err());
        assert_eq!(calls, 1);
    }

    #[test]
    fn an_oversized_file_is_recorded_as_irreversible_not_skipped() {
        // Silently declining to capture would leave the user believing the step
        // was covered.
        let e = Entry {
            seq: 1,
            builtin: "file_write".into(),
            effect: "write_local".into(),
            path: "big.bin".into(),
            before: Before::Irreversible("too big".into()),
            after: None,
            group: None,
        };
        assert!(!e.reversible());
    }

    #[test]
    fn a_directory_target_is_refused_rather_than_half_captured() {
        let e = Entry {
            seq: 1,
            builtin: "rm".into(),
            effect: "destructive".into(),
            path: ".".into(),
            before: Before::Irreversible("path is a directory; trees are not captured".into()),
            after: None,
            group: None,
        };
        assert!(!e.reversible());
    }

    #[test]
    fn journal_builtins_are_never_recorded() {
        // Otherwise undo would journal its own restoration and a second undo
        // would put the damage back.
        assert!(is_journal_builtin("undo"));
        assert!(is_journal_builtin("journal"));
        assert!(is_journal_builtin("session_redo"));
        assert!(!is_journal_builtin("file_write"));
    }

    #[cfg(unix)]
    #[test]
    fn a_persisted_entry_is_private_and_tightens_its_directory() {
        use std::os::unix::fs::PermissionsExt;
        // A directory of the test's own: persist_in takes the directory as an
        // argument, so the real journal is never touched.
        let dir =
            std::env::temp_dir().join(format!("ironshell-journal-private-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o755)).unwrap();
        // An entry as an earlier version wrote it, at the default mode.
        let stale = dir.join("00000001.json");
        std::fs::write(&stale, b"{}").unwrap();
        std::fs::set_permissions(&stale, std::fs::Permissions::from_mode(0o644)).unwrap();

        let e = Entry {
            seq: 1,
            builtin: "file_write".into(),
            effect: "write_local".into(),
            path: "secret.txt".into(),
            before: Before::Contents(b"secret".to_vec()),
            after: None,
            group: None,
        };
        persist_in(Some(dir.clone()), &e);

        let dir_mode = std::fs::metadata(&dir).unwrap().permissions().mode() & 0o777;
        let file_mode = std::fs::metadata(&stale).unwrap().permissions().mode() & 0o777;
        let stored = std::fs::read(&stale).unwrap();
        let _ = std::fs::remove_dir_all(&dir);
        assert_eq!(dir_mode, 0o700);
        assert_eq!(file_mode, 0o600);
        assert!(
            serde_json::from_slice::<StoredEntry>(&stored).is_ok(),
            "the entry was written"
        );
    }
}