@@ -29,3 +29,6 @@ plans/
 .mcp.json
 .ai/review/**/*.json
 /tests/logs/snowflake-cli.log
+
+# mission-ops artifacts
+.claude/missions/
@@ -24,6 +24,8 @@
 * `snow upgrade` is now generally available. It upgrades a direct install of Snowflake CLI and is listed in `snow --help` without a feature flag. Other install channels refuse and print the direct-install command.
 
 ## Fixes and improvements
+* `snow streamlit deploy --replace` now applies `main_file` changes to existing versioned apps in place, preserving the app, grants and version history. Files are uploaded before the entrypoint changes; `--prune` runs only after the change succeeds. Accounts that reject the update receive an actionable error.
+* Streamlit deploy now refuses to recreate an existing app with no live stage unless a legacy `ROOT_LOCATION` is known, and rejects `--prune` with an unset `main_file` when the active entrypoint is absent from the bundle.
 * Upgraded the Python interpreter embedded in Linux binaries from 3.10.22 to 3.12.15. macOS and Windows binaries now embed Python 3.12 as well.
 
 
 
@@ -477,6 +477,24 @@ def _check_file_exists_if_not_default(ctx: click.Context, value):
             " option, the command removes files that exist in the stage, but not files "
             "in the local filesystem.",
         ),
+        plain_text(
+            "For an existing versioned app, ",
+            code("--replace"),
+            " applies changes to ",
+            code("main_file"),
+            " in place. Files are uploaded before the "
+            "entrypoint changes, and pruning runs after a successful change. If the "
+            "account does not support the update, deploy reports an error and keeps "
+            "the existing app.",
+        ),
+        plain_text(
+            "If the app has no live version stage, restore its live version before "
+            "redeploying. When ",
+            code("main_file"),
+            " is unset, ",
+            code("--prune"),
+            " requires the app's current entrypoint to be included in the bundle.",
+        ),
     ),
     examples=(
         Example(
 
@@ -1,5 +1,6 @@
 import json
 import logging
+from functools import partial
 from pathlib import Path
 from typing import Any, Dict, NamedTuple, Optional
 
@@ -38,6 +39,7 @@
 # Snowflake errno / SQLSTATE for "live version already exists" (same codes as
 # SnowflakeAppManager.ensure_workspace_live_version).
 _LIVE_VERSION_EXISTS_ERRNO = 99106
+_MAIN_FILE_UNSUPPORTED_ERRNO = 92824
 _RESTART_STREAMLIT_FUNCTION = "SYSTEM$RESTART_STREAMLIT"
 
 
@@ -441,10 +443,12 @@ def _list(v: Any) -> list:
         if from_stage_name:
             clauses.append(f"ROOT_LOCATION = {to_string_literal(from_stage_name)}")
 
-        if legacy:
-            desired = _str(self._entity_model.main_file)
-            if not current or _str(cur.get("main_file")) != desired:
-                clauses.append(f"MAIN_FILE = {to_string_literal(desired)}")
+        if self.model.main_file == "":
+            raise CliError(
+                "main_file cannot be empty. Set it to the app's entrypoint file."
+            )
+        if self._main_file_changed(cur):
+            clauses.append(f"MAIN_FILE = {to_string_literal(self.model.main_file)}")
 
         # Only snowflake.yml changes the warehouse of an existing app. Falling
         # back to the connection here would rewrite a live warehouse, or fail
@@ -706,8 +710,11 @@ def _is_legacy_deployment(self) -> bool:
         """Check if the existing streamlit uses legacy ROOT_LOCATION deployment."""
         try:
             result = self.describe().fetchone()
-            # Versioned deployments have live_version_location_uri, legacy ones don't
-            return result.get("live_version_location_uri") is None
+            # A versioned app can also lack a live version. Only a positive
+            # ROOT_LOCATION identifies an app eligible for legacy conversion.
+            return bool(result.get("root_location")) and not result.get(
+                "live_version_location_uri"
+            )
         except (ProgrammingError, AttributeError, KeyError):
             # If we can't determine, assume it doesn't exist or is inaccessible
             return False
@@ -852,13 +859,27 @@ def _restart_running_app(self) -> None:
         )
         self._sql_executor.execute_query_with_params(restart_sql, (identifier,))
 
+    def _main_file_changed(self, current: Dict[str, Any]) -> bool:
+        """Compare entrypoints exactly, preserving whitespace in file names."""
+        desired = self.model.main_file
+        return desired is not None and desired != current.get("main_file")
+
+    @staticmethod
+    def _entrypoint_is_bundled(bundle_map: BundleMap, main_file: Optional[str]) -> bool:
+        return bool(
+            main_file
+            and bundle_map.to_project_path(Path(main_file)) is not None
+            and (bundle_map.deploy_root() / main_file).is_file()
+        )
+
     def _deploy_versioned(
         self,
         bundle_map: BundleMap,
         prune: bool = False,
         object_exists: bool = False,
     ):
         restart_after_upload = False
+        deferred_alter_sql = None
         if object_exists:
             current = self.describe().fetchone() or {}
             stage_root = current.get("live_version_location_uri")
@@ -867,6 +888,12 @@ def _deploy_versioned(
                 # ALTER + ADD LIVE VERSION on an object that still has
                 # ROOT_LOCATION (unverified / leaves a hybrid state).
                 old_root = current.get("root_location")
+                if not old_root:
+                    raise CliError(
+                        "The existing Streamlit app has no live version stage. "
+                        "Restore its live version or deploy with a different "
+                        "identifier, then retry. The existing app was not recreated."
+                    )
                 self._execute_query(
                     self.get_deploy_sql(
                         replace=True,
@@ -877,12 +904,30 @@ def _deploy_versioned(
                 stage_root = self._ensure_live_version_location_uri()
                 self._copy_legacy_stage_if_present(old_root, stage_root)
             else:
-                # Already versioned — update properties in place and upload to
-                # the existing live URI (do not re-issue ADD LIVE VERSION).
+                if prune and self.model.main_file is None:
+                    active_main = current.get("main_file")
+                    if not self._entrypoint_is_bundled(bundle_map, active_main):
+                        raise CliError(
+                            "Cannot prune with main_file unset when the app's current "
+                            "entrypoint is missing from the bundle. Include the existing "
+                            "entrypoint in artifacts or set main_file before pruning."
+                        )
+                # Upload a new entrypoint before switching to it. Keep the old
+                # file until ALTER succeeds, even when --prune was requested.
                 alter_sql = self.get_alter_sql(current=current)
-                if alter_sql:
-                    self._execute_query(alter_sql)
-                self._sync_tags()
+                if self._main_file_changed(current):
+                    if not self._entrypoint_is_bundled(
+                        bundle_map, self.model.main_file
+                    ):
+                        raise CliError(
+                            "The new main_file is not a file in the deployment bundle. "
+                            "Set main_file to the app's entrypoint file before deploying."
+                        )
+                    deferred_alter_sql = alter_sql
+                else:
+                    if alter_sql:
+                        self._execute_query(alter_sql)
+                    self._sync_tags()
                 # DESCRIBE, not snowflake.yml: a content-only project can omit
                 # runtime_name while the live object is already SPCS v2.
                 restart_after_upload = _describe_row_is_spcs_v2(current)
@@ -908,16 +953,37 @@ def _deploy_versioned(
                 ) from exc
         stage_path_parts = StageManager().stage_path_parts_from_str(stage_root)
 
-        diff = sync_deploy_root_with_stage(
+        sync_bundle = partial(
+            sync_deploy_root_with_stage,
             console=self._workspace_ctx.console,
             deploy_root=bundle_map.deploy_root(),
             bundle_map=bundle_map,
-            prune=prune,
             recursive=True,
             stage_path_parts=stage_path_parts,
             print_diff=True,
             force_overwrite=True,  # files copied to streamlit vstage need to be overwritten
         )
+        diff = sync_bundle(
+            prune=prune and not deferred_alter_sql,
+            warn_on_preserved_files=not (prune and deferred_alter_sql),
+        )
+
+        if deferred_alter_sql:
+            try:
+                self._execute_query(deferred_alter_sql)
+            except ProgrammingError as exc:
+                if getattr(exc, "errno", None) != _MAIN_FILE_UNSUPPORTED_ERRNO:
+                    raise
+                raise CliError(
+                    "This account does not support changing main_file on a versioned "
+                    "Streamlit app. Keep the existing main_file or deploy with a "
+                    "different identifier. The existing app was not recreated."
+                ) from exc
+            self._sync_tags()
+            if prune:
+                prune_diff = sync_bundle(prune=True)
+                if prune_diff.has_changes():
+                    diff = prune_diff
 
         StreamlitManager(connection=self._conn).grant_privileges(self.model)
         # Property-only ALTER does not clear ScriptCache. Skip when the stage
 
@@ -93,6 +93,7 @@ def sync_deploy_root_with_stage(
     local_paths_to_sync: List[Path] | None = None,
     print_diff: bool = True,
     force_overwrite: bool = False,
+    warn_on_preserved_files: bool = True,
 ) -> DiffResult:
     """
     Ensures that the files on our remote stage match the artifacts we have in
@@ -112,6 +113,7 @@ def sync_deploy_root_with_stage(
         local paths. Note that providing an empty list here is equivalent to None.
         print_diff (bool): Whether to print the diff between the local files and the remote stage. Defaults to True
         force_overwrite (bool): Some resources (e.g. streamlit) need to overwrite files on the stage. Defaults to False.
+        warn_on_preserved_files (bool): Warn about stage-only files when not pruning. Defaults to True.
 
     Returns:
         A `DiffResult` instance describing the changes that were performed.
@@ -192,7 +194,7 @@ def sync_deploy_root_with_stage(
         files_not_removed = [str(path) for path in diff.only_on_stage]
         diff.only_on_stage = []
 
-        if len(files_not_removed) > 0:
+        if files_not_removed and warn_on_preserved_files:
             files_not_removed_str = "\n".join(files_not_removed)
             console.warning(
                 f"The following files exist only on the stage:\n{files_not_removed_str}\n\nUse the --prune flag to delete them from the stage."
 
@@ -16363,6 +16363,15 @@
   |                                                                              |
   | If you specify the --prune option, the command removes files that exist in   |
   | the stage, but not files in the local filesystem.                            |
+  |                                                                              |
+  | For an existing versioned app, --replace applies changes to main_file in     |
+  | place. Files are uploaded before the entrypoint changes, and pruning runs    |
+  | after a successful change. If the account does not support the update,       |
+  | deploy reports an error and keeps the existing app.                          |
+  |                                                                              |
+  | If the app has no live version stage, restore its live version before        |
+  | redeploying. When main_file is unset, --prune requires the app's current     |
+  | entrypoint to be included in the bundle.                                     |
   +------------------------------------------------------------------------------+
   +- Examples -------------------------------------------------------------------+
   | snow streamlit deploy demo_app --replace                                     |
 
@@ -241,18 +241,21 @@ def test_sync_deploy_root_with_stage_subdir(
 @mock.patch(f"{ENTITIES_UTILS_MODULE}.sync_local_diff_with_stage")
 @mock.patch(f"{ENTITIES_UTILS_MODULE}.compute_stage_diff")
 @pytest.mark.parametrize(
-    "prune,only_on_stage_files,expected_warn",
+    "prune,only_on_stage_files,warn_on_preserved_files,expected_warn",
     [
         [
             True,
             [StagePathType("only-stage.txt")],
+            None,
             False,
         ],
         [
             False,
             [StagePathType("only-stage-1.txt"), StagePathType("only-stage-2.txt")],
+            None,
             True,
         ],
+        [False, [StagePathType("old-entrypoint.py")], False, False],
     ],
 )
 def test_sync_deploy_root_with_stage_prune(
@@ -262,6 +265,7 @@ def test_sync_deploy_root_with_stage_prune(
     mock_stage_exists,
     prune,
     only_on_stage_files,
+    warn_on_preserved_files,
     expected_warn,
     temporary_directory,
 ):
@@ -279,6 +283,11 @@ def test_sync_deploy_root_with_stage_prune(
     package_name = pkg_model.fqn.name
     stage_fqn = f"{package_name}.{pkg_model.stage}"
     mock_console = mock.MagicMock()
+    warning_options = (
+        {}
+        if warn_on_preserved_files is None
+        else {"warn_on_preserved_files": warn_on_preserved_files}
+    )
     sync_deploy_root_with_stage(
         console=mock_console,
         deploy_root=dm.project_root / pkg_model.deploy_root,
@@ -288,8 +297,12 @@ def test_sync_deploy_root_with_stage_prune(
         prune=prune,
         recursive=True,
         stage_path_parts=DefaultStagePathParts.from_fqn(stage_fqn),
+        **warning_options,
     )
 
+    if not prune:
+        assert mock_compute_stage_diff.return_value.only_on_stage == []
+
     if expected_warn:
         files_str = "\n".join([str(f) for f in only_on_stage_files])
         warn_message = f"""The following files exist only on the stage:
 
@@ -1,8 +1,14 @@
+from pathlib import Path
 from re import match
 from typing import List
 from unittest import mock
 
 from snowflake.cli._plugins.stage.diff import DiffResult
+from snowflake.cli._plugins.streamlit.streamlit_entity import StreamlitEntity
+from snowflake.cli._plugins.streamlit.streamlit_entity_model import StreamlitEntityModel
+from snowflake.cli._plugins.workspace.context import WorkspaceContext
+from snowflake.cli.api.console.abc import AbstractConsole
+from snowflake.cli.api.secure_path import SecurePath
 
 from tests.conftest import MockCursor
 
@@ -51,6 +57,34 @@ def stage_diff_unchanged() -> DiffResult:
 
 
 class StreamlitTestClass:
+    @staticmethod
+    def _create_entity(
+        project_root: Path,
+        main_file: str,
+        artifacts,
+        include_project_definition: bool = False,
+    ):
+        workspace_ctx = WorkspaceContext(
+            console=mock.MagicMock(spec=AbstractConsole),
+            project_root=project_root,
+            get_default_role=lambda: "mock_role",
+            get_default_warehouse=lambda: "mock_warehouse",
+        )
+        model = StreamlitEntityModel(
+            type="streamlit",
+            identifier="test_streamlit",
+            main_file=main_file,
+            artifacts=artifacts,
+            include_project_definition=include_project_definition,
+        )
+        model.set_entity_id("test_streamlit")
+        return StreamlitEntity(workspace_ctx=workspace_ctx, entity_model=model)
+
+    @staticmethod
+    def _write_file(path: Path, content: str = ""):
+        SecurePath(path.parent).mkdir(parents=True, exist_ok=True)
+        SecurePath(path).write_text(content)
+
     def setup_method(self):
         self.mock_conn = mock.patch(
             "snowflake.cli._plugins.streamlit.streamlit_entity.StreamlitEntity._conn"
@@ -98,7 +132,8 @@ def setup_method(self):
         ).start()
         mock_cursor = mock.Mock()
         mock_cursor.fetchone.return_value = {
-            "live_version_location_uri": f"snow://streamlit/DB.PUBLIC.{STREAMLIT_NAME}/versions/live/"
+            "live_version_location_uri": f"snow://streamlit/DB.PUBLIC.{STREAMLIT_NAME}/versions/live/",
+            "main_file": "streamlit_app.py",
         }
         self.mock_describe.return_value = mock_cursor