Improve security and error handling for VM state and guest file operations; clarify permissions requirements in documentation.

tests/test_state.py

@@ -6,9 +6,11 @@ import tempfile
 import unittest
 from dataclasses import replace
 from pathlib import Path
+from unittest.mock import patch
 
 from uvm.config import Settings
 from uvm.domain import VmRecord
+from uvm.errors import StateError
 from uvm.state import StateStore
 
 
@@ -97,3 +99,14 @@ class StateStoreTests(unittest.TestCase):
         self.store.load()
 
         self.assertEqual(stat.S_IMODE(self.settings.state_path.stat().st_mode), 0o600)
+
+    def test_load_explains_when_registry_permissions_require_root(self) -> None:
+        self.base.mkdir(parents=True)
+        self.settings.state_path.write_text('{"vms": {}}', encoding="utf-8")
+        self.settings.state_path.chmod(0o644)
+
+        with (
+            patch("uvm.state.os.chmod", side_effect=PermissionError),
+            self.assertRaisesRegex(StateError, "Run this command with sudo"),
+        ):
+            self.store.load()