Struct StateManager 

pub struct StateManager { /* private fields */ }

Manages session state storage with per-session directory structure.

State is stored in: ~/.config/autom8/<project>/sessions/<session-id>/ Each session has:

• state.json - The full run state
• metadata.json - Quick metadata for session listing

The spec/ and runs/ directories remain at the project level (shared across sessions).

Implementations

impl StateManager

pub fn new() -> Result<Self>

Create a StateManager using the config directory for the current project. Auto-detects session ID from the current working directory. Uses ~/.config/autom8/<project-name>/ as the base directory.

pub fn with_session(session_id: String) -> Result<Self>

Create a StateManager for a specific session. Uses ~/.config/autom8/<project-name>/ as the base directory.

pub fn for_project(project_name: &str) -> Result<Self>

Create a StateManager for a specific project name. Auto-detects session ID from the current working directory. Uses ~/.config/autom8/<project-name>/ as the base directory.

pub fn for_project_session( project_name: &str, session_id: String, ) -> Result<Self>

Create a StateManager for a specific project and session. Uses ~/.config/autom8/<project-name>/ as the base directory.

pub fn with_dir(dir: PathBuf) -> Self

Create a StateManager with a custom base directory (for testing).

pub fn with_dir_and_session(dir: PathBuf, session_id: String) -> Self

Create a StateManager with a custom base directory and session ID (for testing).

pub fn session_id(&self) -> &str

Get the session ID for this manager.

pub fn runs_dir(&self) -> PathBuf

Path to the runs directory (archived runs)

pub fn spec_dir(&self) -> PathBuf

Path to the spec directory

pub fn ensure_dirs(&self) -> Result<()>

pub fn ensure_spec_dir(&self) -> Result<PathBuf>

Ensure spec directory exists

pub fn list_specs(&self) -> Result<Vec<PathBuf>>

List all spec JSON files in the config directory’s spec/, sorted by modification time (newest first)

pub fn load_current(&self) -> Result<Option<RunState>>

pub fn load_metadata(&self) -> Result<Option<SessionMetadata>>

Load the metadata for the current session.

pub fn save(&self, state: &RunState) -> Result<()>

Save the run state and update session metadata.

pub fn clear_current(&self) -> Result<()>

pub fn save_live(&self, live_state: &LiveState) -> Result<()>

Save live state atomically (write to temp file, then rename).

Atomic writes prevent the monitor from reading a partial/corrupted file.

pub fn load_live(&self) -> Option<LiveState>

Load live state, returning None if file doesn’t exist or is corrupted.

Gracefully handles missing or malformed files so the monitor can recover without crashing.

pub fn clear_live(&self) -> Result<()>

Remove the live state file.

pub fn archive(&self, state: &RunState) -> Result<PathBuf>

pub fn list_archived(&self) -> Result<Vec<RunState>>

pub fn has_active_run(&self) -> Result<bool>

pub fn list_sessions(&self) -> Result<Vec<SessionMetadata>>

List all sessions for this project with their metadata.

Returns sessions sorted by last_active_at descending (most recent first). Sessions without valid metadata are skipped.

pub fn get_session(&self, session_id: &str) -> Option<StateManager>

Get a specific session by ID.

Returns a new StateManager configured for the specified session. Returns None if the session doesn’t exist.

pub fn list_sessions_with_status(&self) -> Result<Vec<SessionStatus>>

List all sessions with enriched status information.

Returns sessions sorted with current session first, then by last_active_at descending. Includes state details (machine state, current story) and marks stale sessions (deleted worktrees).

pub fn find_session_for_branch( &self, branch: &str, ) -> Result<Option<SessionMetadata>>

Find the most recent session that worked on the specified branch.

Searches all sessions in the project and returns the one with the most recent last_active_at timestamp that matches the branch name. This is used by the improve command to load accumulated knowledge from previous runs on the same branch.

Both worktree sessions and main repo sessions are searched.

Arguments

• branch - The branch name to search for

Returns

• Ok(Some(metadata)) - Found a session that worked on this branch
• Ok(None) - No session found for this branch (graceful degradation)
• Err - Error reading session data

pub fn check_branch_conflict( &self, branch_name: &str, ) -> Result<Option<SessionMetadata>>

Check for branch conflicts with other active sessions.

Returns the conflicting session metadata if another session is already using the specified branch. A session “owns” a branch only while it is actively running (status == Running).

Stale sessions (where the worktree directory no longer exists) are automatically skipped and do not cause conflicts.

Arguments

• branch_name - The branch name to check for conflicts

Returns

• Ok(Some(metadata)) - Another session is using this branch
• Ok(None) - No conflict, branch is available
• Err - Error reading session data