Function record_turn

atomic-agent/src/record/mod.rs:138–508

Record an agent turn as an Atomic change. This is the function that bridges the agent world into the VCS world. It builds a `ChangeHeader`, `Provenance`, and `SessionEnvelope`, then calls the repository's `record()` method to create a proper content-addressed, hashable, pushable Atomic change. # Arguments `repo_root` — Path to the repository root (where `.atomic/` lives). The repository is open

(
    repo_root: &Path,
    options: &TurnRecordOptions<'_>,
)

/// (no files changed since the last recorded state).
/// Returns `AgentError::RecordFailed` if the repository record operation fails.
pub fn record_turn(
    repo_root: &Path,
    options: &TurnRecordOptions<'_>,
) -> AgentResult<TurnRecordOutcome> {
    let manifest = scope::manifest(options)?;
    if let Some(files) = &manifest {
        scope::validate(repo_root, files, options)?;
        if files.is_empty() {
            return Err(AgentError::EmptyTurn {
                session_id: options.session.session_id.clone(),
                turn_number: options.turn_number,
            });
        }
    }
    // Step 1: Open the repository read-only for the initial status check.
    // This can coexist with other readers. Wait for a transient incompatible
    // writer before deciding whether work or untracked files exist.
    let mut repo = atomic_repository::Repository::open_readonly_wait(
        repo_root,
        std::time::Duration::from_secs(10),
    )
    .map_err(|e| AgentError::RecordFailed {
        session_id: options.session.session_id.clone(),
        turn_number: options.turn_number,
        reason: format!("Failed to open repository (readonly): {}", e),
    })?;

    // `status()` reads current_view, while `record()` writes to session.view_name.
    // Align the read-only handle before the first status check; this keeps the
    // no-lock fast path and prevents direct callers from seeing false EmptyTurn.
    repo.set_current_view_in_memory(&options.session.view_name);

    // Step 2: Status — find out what the agent changed.
    // Include untracked files because agent turns commonly create new source,
    // config, and test files. Those must be auto-added before recording so the
    // turn produces an Atomic change with provenance instead of leaving files
    // untracked in the working copy.
    let status = repo
        .status(atomic_repository::status::StatusOptions::fast().with_untracked(true))
        .map_err(|e| AgentError::RecordFailed {
            session_id: options.session.session_id.clone(),
            turn_number: options.turn_number,
            reason: format!("Failed to get repository status: {}", e),
        })?;

    let status = scope::filter(status, manifest.as_ref());

    // Check if there's anything to record at all
    if status.is_clean() && status.untracked_count() == 0 {
        return Err(AgentError::EmptyTurn {
            session_id: options.session.session_id.clone(),
            turn_number: options.turn_number,
        });
    }

    // Step 3: Add — track any new files the agent created
    // Agents create new files all the time (new modules, tests, configs).
    // These show up as "untracked" in status. We add them before recording