Fix managed provider launches, recovery, and rewind checkpoints

.github/workflows/electron-build.yml

@@ -100,6 +100,12 @@ jobs:
         if: matrix.os == 'windows-2022'
         run: cargo test --locked -p freshell-platform --lib cli_launch::cli_argv_goldens_file::native_windows_generated_claude_hooks_work_in_shells
 
+      # Exercise the real Windows owner-SID and ProfileList APIs for SYSTEM's
+      # profile. The Linux Rust/browser jobs cannot cover this Windows branch.
+      - name: Test Windows SYSTEM checkpoint-home rejection
+        if: matrix.os == 'windows-2022'
+        run: cargo test --locked -p freshell-server --bin freshell-server checkpoints::tests::windows_system_profile_is_rejected_as_checkpoint_scope
+
       - name: Run Electron unit tests
         run: pnpm run test:electron
 

AGENTS.md

@@ -327,4 +327,6 @@ All components **must** be accessible for browser-use automation and WCAG compli
 
 ## Subagent polling policy
 
+Managed provider environment and recovery repair: [implementation plan](docs/plans/2026-10-05-managed-provider-environment.md).
+
 When idle-waiting on subagents, always call `wait_agent` with `timeout_ms=3600000` (the 1-hour maximum). `wait_agent` wakes immediately on any subagent message or completion, so long timeouts add no latency — but every wait return (including a no-op timeout) costs a full model turn that re-sends the entire context. Never poll on shorter timeouts. Have workers `send_message` to `/root` at milestones so the parent wakes exactly when there is news.

crates/freshell-agent-runtime/src/host_actor.rs

@@ -102,7 +102,7 @@ impl FreshAgentProfile {
         if self
             .provider_launch_context
             .as_ref()
-            .is_some_and(|context| context.validate(self.provider.as_str()).is_err())
+            .is_some_and(|context| context.validate(self.provider.native_provider()).is_err())
         {
             return Err(ActorError::InvalidProfile);
         }
@@ -201,6 +201,18 @@ pub trait FreshAgentTransport: Send + Sync {
         text: &str,
         profile: &FreshAgentProfile,
     ) -> Result<DispatchAck, DispatchFailure>;
+    /// Dispatches a send whose checkpoint attempt identity must reach the
+    /// provider-native turn receipt. Legacy transports remain compatible and
+    /// ignore the optional metadata by delegating to `dispatch`.
+    async fn dispatch_with_checkpoint_identity(
+        &self,
+        request_id: &RequestId,
+        text: &str,
+        profile: &FreshAgentProfile,
+        _logical_attempt_id: Option<&str>,
+    ) -> Result<DispatchAck, DispatchFailure> {
+        self.dispatch(request_id, text, profile).await
+    }
     async fn resolve_permission(
         &self,
         decision_id: &str,
@@ -312,6 +324,8 @@ struct PersistedDecision {
 struct PersistedActorState {
     schema_version: u32,
     profile: FreshAgentProfile,
+    #[serde(default)]
+    initialization_state: Option<CommandState>,
     commands: BTreeMap<String, PersistedCommand>,
     #[serde(default)]
     completed_forks: BTreeMap<String, ForkTransition>,
@@ -327,6 +341,7 @@ impl PersistedActorState {
         Self {
             schema_version: 1,
             profile,
+            initialization_state: None,
             commands: BTreeMap::new(),
             completed_forks: BTreeMap::new(),
             decisions: BTreeMap::new(),
@@ -414,32 +429,74 @@ impl FreshAgentHostActor {
         fs::create_dir_all(&state_dir).map_err(persist)?;
         let writer_lock = WriterLock::acquire(&state_dir.join("fresh-agent-writer.lock"))?;
         let state_path = state_dir.join("fresh-agent-state.json");
-        let mut state = if state_path.exists() {
-            let bytes = fs::read(&state_path).map_err(persist)?;
-            let mut loaded: PersistedActorState =
-                serde_json::from_slice(&bytes).map_err(persist)?;
-            let mut expected_profile = profile.clone();
-            if expected_profile.native_session_id.is_none() {
-                expected_profile.native_session_id = loaded.profile.native_session_id.clone();
-            }
-            if loaded.profile != expected_profile {
-                return Err(ActorError::NativeIdentityMismatch);
-            }
-            for command in loaded.commands.values_mut() {
-                if matches!(command.state, CommandState::Dispatching) {
-                    command.state = CommandState::Ambiguous;
+        let (mut state, newly_initialized) = match fs::read(&state_path) {
+            Ok(bytes) => {
+                let mut loaded: PersistedActorState =
+                    serde_json::from_slice(&bytes).map_err(persist)?;
+                // A successful transport start may still have returned no
+                // identity. Reopening that durable actor must not create a
+                // second conversation from missing metadata alone.
+                if loaded.profile.native_session_id.is_none() {
+                    return Err(ActorError::AmbiguousDispatch);
                 }
-            }
-            for decision in loaded.decisions.values_mut() {
-                if matches!(decision.state, DecisionState::Dispatching) {
-                    decision.state = DecisionState::Ambiguous;
+                let mut expected_profile = profile.clone();
+                if expected_profile.native_session_id.is_none() {
+                    expected_profile.native_session_id = loaded.profile.native_session_id.clone();
+                }
+                // The host validates a fresh preparation for each incarnation.
+                // Its grant and resource generation may change while the durable
+                // conversation and every other launch setting remain the same.
+                let current_preparation = expected_profile.provider_launch_context.take();
+                let current_references = expected_profile.provider_secret_references.clone();
+                if current_preparation.is_some() {
+                    // Configuration-file references belong to the host-validated
+                    // preparation. Legacy OneCLI grants remain durable settings.
+                    if !current_references
+                        .iter()
+                        .filter(|reference| !reference.profile.is_configuration_file())
+                        .eq(loaded
+                            .profile
+                            .provider_secret_references
+                            .iter()
+                            .filter(|reference| !reference.profile.is_configuration_file()))
+                    {
+                        return Err(ActorError::NativeIdentityMismatch);
+                    }
+                    expected_profile.provider_secret_references =
+                        loaded.profile.provider_secret_references.clone();
+                    expected_profile.provider_launch_context =
+                        loaded.profile.provider_launch_context.clone();
+                }
+                if loaded.profile != expected_profile {
+                    return Err(ActorError::NativeIdentityMismatch);
+                }
+                loaded.profile.provider_launch_context = current_preparation;
+                loaded.profile.provider_secret_references = current_references;
+                for command in loaded.commands.values_mut() {
+                    if matches!(command.state, CommandState::Dispatching) {
+                        command.state = CommandState::Ambiguous;
+                    }
                 }
+                for decision in loaded.decisions.values_mut() {
+                    if matches!(decision.state, DecisionState::Dispatching) {
+                        decision.state = DecisionState::Ambiguous;
+                    }
+                }
+                (loaded, false)
             }
-            loaded
-        } else {
-            PersistedActorState::new(profile)
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                (PersistedActorState::new(profile), true)
+            }
+            Err(error) => return Err(persist(error)),
         };
 
+        if newly_initialized {
+            // Publish intent before the first provider creation. A resumed
+            // actor keeps its accepted preparation until exact identity is
+            // verified below.
+            state.initialization_state = Some(CommandState::Dispatching);
+            write_state(&state_dir, &state)?;
+        }
         let started = transport
             .start(&state.profile)
             .await
@@ -457,6 +514,7 @@ impl FreshAgentHostActor {
                 event_count_cap,
             )?;
         }
+        state.initialization_state = Some(CommandState::Completed);
         write_state(&state_dir, &state)?;
         let actor = Arc::new(Self {
             state_dir,
@@ -525,12 +583,33 @@ impl FreshAgentHostActor {
         request_id: RequestId,
         text: String,
         settings: Option<FreshAgentTurnSettings>,
+    ) -> Result<CommandState, ActorError> {
+        self.dispatch_with_checkpoint_identity(request_id, text, settings, None)
+            .await
+    }
+
+    pub async fn dispatch_with_checkpoint_identity(
+        &self,
+        request_id: RequestId,
+        text: String,
+        settings: Option<FreshAgentTurnSettings>,
+        logical_attempt_id: Option<String>,
     ) -> Result<CommandState, ActorError> {
         // One provider conversation has one ordered input lane. Keep the
         // durability transition and provider acceptance boundary within the
         // same fence so concurrent gateways cannot become double writers.
         let _dispatch_guard = self.dispatch_lock.lock().await;
-        let command_material = serde_json::to_vec(&(text.as_str(), &settings)).map_err(persist)?;
+        // Preserve the exact historical digest for legacy sends so a command
+        // journal created before this field existed remains idempotent after
+        // upgrade. A modern checkpointed send additionally fences the logical
+        // attempt identity into durable request-ID conflict detection.
+        let command_material = match logical_attempt_id.as_deref() {
+            Some(logical_attempt_id) => {
+                serde_json::to_vec(&(text.as_str(), &settings, logical_attempt_id))
+            }
+            None => serde_json::to_vec(&(text.as_str(), &settings)),
+        }
+        .map_err(persist)?;
         let digest = digest(&command_material);
         let dispatch_profile;
         {
@@ -572,7 +651,12 @@ impl FreshAgentHostActor {
 
         let result = self
             .transport
-            .dispatch(&request_id, &text, &dispatch_profile)
+            .dispatch_with_checkpoint_identity(
+                &request_id,
+                &text,
+                &dispatch_profile,
+                logical_attempt_id.as_deref(),
+            )
             .await;
         let mut state = self.state.lock().await;
         let command = state