Harden default environment pull behavior

Fix the default one-shot install path so empty bundled profile directories no longer win over OCI-backed environment pulls or leave broken cached symlinks behind.

Treat cached installs as valid only when the manifest and boot artifacts are all present, repair invalid installs on the next pull, and add human-mode phase markers for env pull and run without changing JSON output.

Align the Python lifecycle example and public docs with the current exec_vm/vm_exec auto-clean semantics, and validate the slice with focused pytest coverage, make check, make dist-check, and a real default-path pull/inspect/run smoke.

src/pyro_mcp/vm_environments.py

@@ -185,6 +185,10 @@ def _serialize_environment(environment: VmEnvironment) -> dict[str, object]:
     }
 
 
+def _artifacts_ready(root: Path) -> bool:
+    return (root / "vmlinux").is_file() and (root / "rootfs.ext4").is_file()
+
+
 class EnvironmentStore:
     """Install and inspect curated environments in a local cache."""
 
@@ -228,7 +232,7 @@ class EnvironmentStore:
         spec = get_environment(name, runtime_paths=self._runtime_paths)
         install_dir = self._install_dir(spec)
         metadata_path = install_dir / "environment.json"
-        installed = metadata_path.exists() and (install_dir / "vmlinux").exists()
+        installed = self._load_installed_environment(spec) is not None
         payload = _serialize_environment(spec)
         payload.update(
             {
@@ -245,29 +249,12 @@ class EnvironmentStore:
     def ensure_installed(self, name: str) -> InstalledEnvironment:
         spec = get_environment(name, runtime_paths=self._runtime_paths)
         self._platform_dir.mkdir(parents=True, exist_ok=True)
-        install_dir = self._install_dir(spec)
-        metadata_path = install_dir / "environment.json"
-        if metadata_path.exists():
-            kernel_image = install_dir / "vmlinux"
-            rootfs_image = install_dir / "rootfs.ext4"
-            if kernel_image.exists() and rootfs_image.exists():
-                metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
-                source = str(metadata.get("source", "cache"))
-                raw_digest = metadata.get("source_digest")
-                digest = raw_digest if isinstance(raw_digest, str) else None
-                return InstalledEnvironment(
-                    name=spec.name,
-                    version=spec.version,
-                    install_dir=install_dir,
-                    kernel_image=kernel_image,
-                    rootfs_image=rootfs_image,
-                    source=source,
-                    source_digest=digest,
-                    installed=True,
-                )
+        installed = self._load_installed_environment(spec)
+        if installed is not None:
+            return installed
 
         source_dir = self._runtime_paths.artifacts_dir / spec.source_profile
-        if source_dir.exists():
+        if _artifacts_ready(source_dir):
             return self._install_from_local_source(spec, source_dir)
         if (
             spec.oci_registry is not None
@@ -313,6 +300,10 @@ class EnvironmentStore:
             if spec.version != raw_version:
                 shutil.rmtree(child, ignore_errors=True)
                 deleted.append(child.name)
+                continue
+            if self._load_installed_environment(spec, install_dir=child) is None:
+                shutil.rmtree(child, ignore_errors=True)
+                deleted.append(child.name)
         return {"deleted_environment_dirs": sorted(deleted), "count": len(deleted)}
 
     def _install_dir(self, spec: VmEnvironment) -> Path:
@@ -349,6 +340,33 @@ class EnvironmentStore:
             installed=True,
         )
 
+    def _load_installed_environment(
+        self, spec: VmEnvironment, *, install_dir: Path | None = None
+    ) -> InstalledEnvironment | None:
+        resolved_install_dir = install_dir or self._install_dir(spec)
+        metadata_path = resolved_install_dir / "environment.json"
+        if not metadata_path.is_file() or not _artifacts_ready(resolved_install_dir):
+            return None
+        try:
+            metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return None
+        if not isinstance(metadata, dict):
+            return None
+        source = str(metadata.get("source", "cache"))
+        raw_digest = metadata.get("source_digest")
+        digest = raw_digest if isinstance(raw_digest, str) else None
+        return InstalledEnvironment(
+            name=spec.name,
+            version=spec.version,
+            install_dir=resolved_install_dir,
+            kernel_image=resolved_install_dir / "vmlinux",
+            rootfs_image=resolved_install_dir / "rootfs.ext4",
+            source=source,
+            source_digest=digest,
+            installed=True,
+        )
+
     def _install_from_archive(self, spec: VmEnvironment, archive_url: str) -> InstalledEnvironment:
         install_dir = self._install_dir(spec)
         temp_dir = Path(tempfile.mkdtemp(prefix=".partial-", dir=self._platform_dir))