Function record_turn

atomic-agent/src/record/mod.rs:136–437

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> {
    // Step 1: Open the repository read-only for the initial status check.
    // This avoids blocking on the redb write lock — we only need read access
    // to decide whether there's work to do and which files are untracked.
    let mut repo = atomic_repository::Repository::open_readonly(repo_root).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),
        })?;

    // 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
    // so they're included in the change.
    //
    // We filter out common large directories (node_modules, target, etc.)
    // that agents may create as side effects (e.g., `npm install`). These
    // would make the hook extremely slow and are never intended to be
    // version-controlled. The .atomicignore file provides user-level control,
    // but these defaults protect against the common case where no ignore
    // file exists yet.
    let untracked_paths: Vec<String> = status
        .untracked()
        .map(|e| e.path().to_string_lossy().to_string())
        .filter(|p| !should_ignore_untracked(p))
        .collect();