Record an agent turn as an Atomic change, or classify a clean turn. 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. When the working copy is clean, `EmptyTurn` is NOT returned (RFC §10.2 remove
(
repo_root: &Path,
options: &TurnRecordOptions<'_>,
)
| 1064 | /// |
| 1065 | /// Returns `AgentError::RecordFailed` if the repository record operation fails. |
| 1066 | pub fn record_turn( |
| 1067 | repo_root: &Path, |
| 1068 | options: &TurnRecordOptions<'_>, |
| 1069 | ) -> AgentResult<TurnRecordResult> { |
| 1070 | let mut manifest = scope::manifest(options)?; |
| 1071 | // Step 1: Open the repository read-only for the initial status check. |
| 1072 | // This can coexist with other readers. Wait for a transient incompatible |
| 1073 | // writer before deciding whether work or untracked files exist. |
| 1074 | let mut repo = atomic_repository::Repository::open_readonly_wait( |
| 1075 | repo_root, |
| 1076 | std::time::Duration::from_secs(10), |
| 1077 | ) |
| 1078 | .map_err(|e| AgentError::RecordFailed { |
| 1079 | session_id: options.session.session_id.clone(), |
| 1080 | turn_number: options.turn_number, |
| 1081 | reason: format!("Failed to open repository (readonly): {}", e), |
| 1082 | })?; |
| 1083 | |
| 1084 | // Preserve the read-only fast path when the persisted desired view already |
| 1085 | // matches the session. Non-sandbox recording intentionally targets the |
| 1086 | // session view, so repair or align it before status. A provisioned sandbox's |
| 1087 | // persistent working-copy record is authoritative and is never repointed here. |
| 1088 | let session_view_needs_alignment = !repo.is_sandbox() |
| 1089 | && (repo.current_view() != options.session.view_name |
| 1090 | || matches!( |
| 1091 | repo.get_view_info(&options.session.view_name), |
| 1092 | Err(atomic_repository::RepositoryError::ViewNotFound { .. }) |
| 1093 | )); |
| 1094 | if session_view_needs_alignment { |
| 1095 | drop(repo); |
| 1096 | let mut repair_repo = atomic_repository::Repository::open_existing_wait( |
| 1097 | repo_root, |
| 1098 | std::time::Duration::from_secs(10), |
| 1099 | ) |
| 1100 | .map_err(|error| AgentError::RecordFailed { |
| 1101 | session_id: options.session.session_id.clone(), |
| 1102 | turn_number: options.turn_number, |
| 1103 | reason: format!("Failed to open repository for view alignment: {}", error), |
| 1104 | })?; |
| 1105 | align_or_repair_session_view(&mut repair_repo, options)?; |
| 1106 | drop(repair_repo); |
| 1107 | repo = atomic_repository::Repository::open_readonly_wait( |
| 1108 | repo_root, |
| 1109 | std::time::Duration::from_secs(10), |
| 1110 | ) |
| 1111 | .map_err(|error| AgentError::RecordFailed { |
| 1112 | session_id: options.session.session_id.clone(), |
| 1113 | turn_number: options.turn_number, |
| 1114 | reason: format!( |
| 1115 | "Failed to reopen repository after view alignment: {}", |
| 1116 | error |
| 1117 | ), |
| 1118 | })?; |
| 1119 | } |
| 1120 | |
| 1121 | let working_copy = |
| 1122 | repo.require_working_copy_id() |
| 1123 | .map_err(|error| AgentError::RecordFailed { |