Function record_turn

atomic-agent/src/record/mod.rs:140–553

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 mut manifest = scope::manifest(options)?;
    // 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),
        })?;

    // Restart-proof the deletion scope. The plugin's ownership claims live in
    // its process memory; a plugin restart mid-session (e.g. after an
    // ambiguity lockout) silently drops every claim, and deletions of files
    // this session recorded earlier then sit unrecorded forever — no later
    // manifest will ever mention them again. Those deletions are still
    // attributable from the persisted session state: `files_touched` holds
    // exactly the paths this session's own changes introduced or modified.
    // Augment the manifest with their Deleted status entries so a lost claim
    // cannot strand a deletion. Files the session never recorded stay
    // unclaimed, keeping foreign edits out of scope.
    if let Some(files) = manifest.as_mut() {
        let touched: std::collections::HashSet<&str> = options
            .session
            .files_touched
            .iter()
            .map(String::as_str)
            .collect();
        for entry in status.entries() {
            if entry.status() != atomic_repository::status::FileStatus::Deleted {
                continue;
            }
            let path = entry.path().to_string_lossy().to_string();