Struct RunState 

pub struct RunState {

    pub run_id: String,
    pub status: RunStatus,
    pub machine_state: MachineState,
    pub spec_json_path: PathBuf,
    pub spec_md_path: Option<PathBuf>,
    pub branch: String,
    pub current_story: Option<String>,
    pub iteration: u32,
    pub review_iteration: u32,
    pub started_at: DateTime<Utc>,
    pub finished_at: Option<DateTime<Utc>>,
    pub iterations: Vec<IterationRecord>,
    pub config: Option<Config>,
    pub knowledge: ProjectKnowledge,
    pub pre_story_commit: Option<String>,
    pub session_id: Option<String>,
    pub total_usage: Option<ClaudeUsage>,
    pub phase_usage: HashMap<String, ClaudeUsage>,
}

Fields

run_id: String

status: RunStatus

machine_state: MachineState

spec_json_path: PathBuf

spec_md_path: Option<PathBuf>

branch: String

current_story: Option<String>

iteration: u32

review_iteration: u32

Tracks the current review cycle (1, 2, or 3) during the review loop

started_at: DateTime<Utc>

finished_at: Option<DateTime<Utc>>

iterations: Vec<IterationRecord>

config: Option<Config>

Configuration snapshot taken at run start. This ensures resumed runs use the same config they started with.

knowledge: ProjectKnowledge

Cumulative project knowledge tracked across agent runs. Contains file info, decisions, patterns, and story changes.

pre_story_commit: Option<String>

Git commit hash captured before starting each story. Used to calculate diffs for what changed during the story.

session_id: Option<String>

Session identifier for worktree-based parallel execution. Deterministic ID derived from worktree path (or “main” for main repo).

total_usage: Option<ClaudeUsage>

Total accumulated token usage across all phases of the run.

phase_usage: HashMap<String, ClaudeUsage>

Token usage broken down by phase. Keys are story IDs (e.g., “US-001”) or pseudo-phase names:

• “Planning”: spec generation
• “US-001”, “US-002”, etc.: user story implementation
• “Final Review”: review iterations + corrections
• “PR & Commit”: commit generation + PR creation

Implementations

impl RunState

pub fn new(spec_json_path: PathBuf, branch: String) -> Self

pub fn new_with_config( spec_json_path: PathBuf, branch: String, config: Config, ) -> Self

Create a new RunState with a config snapshot.

pub fn new_with_session( spec_json_path: PathBuf, branch: String, session_id: String, ) -> Self

Create a new RunState with a session ID.

pub fn new_with_config_and_session( spec_json_path: PathBuf, branch: String, config: Config, session_id: String, ) -> Self

Create a new RunState with config and session ID.

pub fn from_spec(spec_md_path: PathBuf, spec_json_path: PathBuf) -> Self

pub fn from_spec_with_config( spec_md_path: PathBuf, spec_json_path: PathBuf, config: Config, ) -> Self

Create a RunState from spec with a config snapshot.

pub fn from_spec_with_config_and_session( spec_md_path: PathBuf, spec_json_path: PathBuf, config: Config, session_id: String, ) -> Self

Create a RunState from spec with config and session ID.

pub fn effective_config(&self) -> Config

Get the effective config for this run. Returns the stored config if available, otherwise the default.

pub fn transition_to(&mut self, state: MachineState)

pub fn start_iteration(&mut self, story_id: &str)

pub fn finish_iteration( &mut self, status: IterationStatus, output_snippet: String, )

pub fn set_work_summary(&mut self, summary: Option<String>)

Set the work summary on the current (last) iteration

pub fn current_iteration_duration(&self) -> u64

pub fn run_duration_secs(&self) -> u64

Get the total run duration in seconds.

Returns the time between started_at and finished_at (or now if not finished).

pub fn capture_pre_story_state(&mut self)

Capture the current HEAD commit before starting a story.

This stores the commit hash so we can later calculate what changed during the story implementation. For non-git projects, this is a no-op.

On the first call (when baseline_commit is not set), this also captures the baseline commit for the entire run. This is used to track which files autom8 touched vs external changes (US-010).

pub fn record_story_changes( &mut self, story_id: &str, commit_hash: Option<String>, )

Record changes made during a story and update project knowledge.

This method:

1. Captures the git diff since pre_story_commit
2. Creates a StoryChanges record
3. Adds it to the project knowledge

For non-git projects or if pre_story_commit is not set, this creates an empty StoryChanges record.

Arguments

• story_id - The ID of the story that was just implemented
• commit_hash - Optional commit hash if the changes were committed

pub fn capture_story_knowledge( &mut self, story_id: &str, agent_output: &str, commit_hash: Option<String>, )

Capture story knowledge after agent completion.

This method combines two sources of truth:

1. Git diff data for empirical knowledge of what files were created/modified
2. Agent-provided semantic information (files context, decisions, patterns)

The method:

• Gets git diff since pre_story_commit (if available)
• Filters changes to only include files autom8 touched (see US-010)
• Extracts structured context from the agent’s output
• Creates a StoryChanges record combining both sources
• Merges file info into the knowledge.files registry
• Appends decisions and patterns to knowledge

For non-git projects, only agent-provided context is used.

Arguments

• story_id - The ID of the story that was just implemented
• agent_output - The full output from the Claude agent
• commit_hash - Optional commit hash if the changes were committed

pub fn capture_usage(&mut self, phase_key: &str, usage: Option<ClaudeUsage>)

Capture usage from a Claude call and add it to the appropriate phase.

This method:

1. Adds the usage to the specified phase in phase_usage
2. Accumulates the usage into total_usage

If usage is None, this is a no-op.

Arguments

• phase_key - The phase identifier (e.g., “Planning”, “US-001”, “Final Review”, “PR & Commit”)
• usage - The usage data from the Claude call, or None if not available

pub fn set_iteration_usage(&mut self, usage: Option<ClaudeUsage>)

Set usage on the current (last) iteration.

This stores the usage data in the IterationRecord for per-story tracking. If usage is None, this is a no-op.

Trait Implementations

impl Clone for RunState

fn clone(&self) -> RunState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RunState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for RunState

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for RunState

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.