Hmbown/CodeWhale · error · std::io::Error

Session id '{trimmed}' collides with a reserved checkpoint f

Error message

Session id '{trimmed}' collides with a reserved checkpoint file

What it means

validated_checkpoint_path() rejects a caller-supplied session id whose trimmed value names a reserved file inside the checkpoints/ directory (e.g. offline_queue.json). This is a generic guard on untrusted session-id input: firing means the id would address a fixed control file instead of a per-session checkpoint, risking overwrite of durable queue/manifest state.

Source

Thrown at crates/tui/src/session_manager.rs:1012

            Err(error) => return Err(error),
        };
        if metadata.file_type().is_symlink() || !metadata.is_file() {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                format!("Session goal {} must be a regular file", path.display()),
            ));
        }
        Ok(true)
    }

    fn validated_checkpoint_path(&self, session_id: &str) -> std::io::Result<PathBuf> {
        let trimmed = self.validated_session_id(session_id)?;
        // Reserved file names inside `checkpoints/` must never collide with a
        // per-session checkpoint file.
        if format!("{trimmed}.json") == LEGACY_CHECKPOINT_FILE
            || format!("{trimmed}.json") == OFFLINE_QUEUE_FILE
        {
            return Err(std::io::Error::new(
                std::io::ErrorKind::InvalidInput,
                format!("Session id '{trimmed}' collides with a reserved checkpoint file"),
            ));
        }
        Ok(self.checkpoints_dir().join(format!("{trimmed}.json")))
    }

    /// Create a new `SessionManager` with the specified sessions directory
    pub fn new(sessions_dir: PathBuf) -> std::io::Result<Self> {
        let sessions_dir = normalize_managed_dir(sessions_dir)?;
        // Ensure the sessions directory exists
        fs::create_dir_all(&sessions_dir)?;
        Ok(Self { sessions_dir })
    }

    /// Create a `SessionManager` using the default location.
    pub fn default_location() -> std::io::Result<Self> {
        Self::new(default_sessions_dir()?)

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Choose a different session id that does not equal a reserved checkpoint file name
2. Sanitize/namespace user-supplied ids before passing them to session_manager APIs
3. Add the reserved-name check earlier, at session creation time, so colliding ids never enter the system

When it happens

Trigger: Thrown at crates/tui/src/session_manager.rs:1012 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/f8be4f1e0ea7047d. Report an issue: GitHub.