create-workframe 0.1.0

package/workframe-api/tests/test_runtime_identity_backfill.py

@@ -0,0 +1,34 @@
+"""Runtime identity backfill from template profiles."""
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+import server
+
+
+class RuntimeIdentityBackfillTests(unittest.TestCase):
+    def test_backfill_copies_missing_soul_and_skills_only(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            template = root / "profiles" / "workframe-agent"
+            runtime = root / "profiles" / "u-user-workframe-agent"
+            template.mkdir(parents=True)
+            runtime.mkdir(parents=True)
+            (template / "SOUL.md").write_text("template soul\n", encoding="utf-8")
+            (runtime / "SOUL.md").write_text("custom soul\n", encoding="utf-8")
+            skill = template / "skills" / "devops" / "botfather" / "SKILL.md"
+            skill.parent.mkdir(parents=True)
+            skill.write_text("botfather\n", encoding="utf-8")
+
+            with mock.patch.object(server, "_profile_dir", side_effect=lambda p: root / "profiles" / p):
+                server._backfill_runtime_identity("u-user-workframe-agent", "workframe-agent")
+
+            self.assertEqual((runtime / "SOUL.md").read_text(encoding="utf-8"), "custom soul\n")
+            self.assertTrue((runtime / "skills" / "devops" / "botfather" / "SKILL.md").is_file())
+
+
+if __name__ == "__main__":
+    unittest.main()

package/workframe-api/tests/test_site_meta.py

@@ -0,0 +1,81 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+import site_meta
+import stack_config
+
+
+class SiteMetaTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmpdir = tempfile.TemporaryDirectory()
+        stack_config.DATA_DIR = Path(self._tmpdir.name)
+        stack_config.CONFIG_PATH = stack_config.DATA_DIR / "stack_config.json"
+
+    def tearDown(self) -> None:
+        self._tmpdir.cleanup()
+
+    def test_defaults_before_install(self) -> None:
+        meta = site_meta.resolve_site_meta(
+            app_base_url="https://dev.alanborger.com",
+            install_complete=False,
+        )
+        self.assertEqual(meta["title"], "Workframe")
+        self.assertIn("Hermes", meta["description"])
+        self.assertTrue(meta["og_image"].endswith("/assets/branding/og-default.png"))
+        self.assertEqual(meta["source"]["title"], "default")
+
+    def test_workspace_identity_when_configured(self) -> None:
+        meta = site_meta.resolve_site_meta(
+            app_base_url="https://dev.alanborger.com",
+            install_complete=True,
+            workspace={
+                "display_name": "Acme Labs",
+                "description": "Agent ops for the product team",
+                "tagline": "Ship with agents",
+                "avatar_url": "/assets/project-logos/7.png",
+            },
+            normalize_logo=lambda url: url,
+        )
+        self.assertEqual(meta["title"], "Acme Labs")
+        self.assertEqual(meta["description"], "Agent ops for the product team")
+        self.assertEqual(meta["tagline"], "Ship with agents")
+        self.assertTrue(meta["og_image"].endswith("/assets/project-logos/7.png"))
+        self.assertEqual(meta["source"]["title"], "workspace")
+
+    def test_stack_overrides_win(self) -> None:
+        stack_config.patch_stack_config(
+            {
+                "site_branding": {
+                    "title": "Custom Public Name",
+                    "description": "Custom public pitch",
+                },
+            },
+        )
+        meta = site_meta.resolve_site_meta(
+            app_base_url="https://dev.alanborger.com",
+            install_complete=True,
+            workspace={"display_name": "Acme Labs", "description": "ignored"},
+        )
+        self.assertEqual(meta["title"], "Custom Public Name")
+        self.assertEqual(meta["description"], "Custom public pitch")
+        self.assertEqual(meta["source"]["title"], "stack")
+
+    def test_uploaded_og_image_url(self) -> None:
+        site_meta.save_branding_asset("og", b"\x89PNG\r\n\x1a\n", "image/png")
+        meta = site_meta.resolve_site_meta(app_base_url="https://dev.alanborger.com", install_complete=False)
+        self.assertIn("/api/public/branding/og", meta["og_image"])
+        self.assertEqual(meta["source"]["og_image"], "upload")
+
+    def test_loopback_base_uses_relative_browser_assets(self) -> None:
+        meta = site_meta.resolve_site_meta(
+            app_base_url="http://127.0.0.1:28644",
+            install_complete=False,
+        )
+        self.assertEqual(meta["favicon"], "/favicon.svg")
+        self.assertEqual(meta["manifest_url"], "/manifest.webmanifest")
+        self.assertTrue(meta["og_image"].startswith("/assets/"))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/workframe-api/tests/test_soul_stub.py

@@ -0,0 +1,42 @@
+"""SOUL stub detection and Workframe identity rendering."""
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+import server
+
+
+class SoulStubTests(unittest.TestCase):
+    def test_stub_detects_test_placeholder(self) -> None:
+        self.assertTrue(server._soul_is_stub("test"))
+        self.assertTrue(server._soul_is_stub("{nativeAgentName} concierge"))
+
+    def test_profile_soul_text_falls_back_to_template(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            template = root / "profiles" / "workframe-agent"
+            runtime = root / "profiles" / "u-user-workframe-agent"
+            template.mkdir(parents=True)
+            runtime.mkdir(parents=True)
+            (template / "SOUL.md").write_text(
+                "# {nativeAgentName}\n\nWorkframe concierge for {projectName}.\n" + ("x" * 80),
+                encoding="utf-8",
+            )
+            (runtime / "SOUL.md").write_text("test", encoding="utf-8")
+
+            with mock.patch.object(server, "_profile_dir", side_effect=lambda p: root / "profiles" / p), mock.patch.object(
+                server, "PROJECT_NAME", "Workframe"
+            ), mock.patch.object(server, "NATIVE_PROFILE", "workframe-agent"), mock.patch.object(
+                server, "_runtime_template_slug", return_value="workframe-agent"
+            ), mock.patch.object(server, "_is_runtime_profile_slug", return_value=True):
+                text = server._profile_soul_text("u-user-workframe-agent")
+                self.assertIn("Workframe Agent", text)
+                self.assertIn("Workframe concierge", text)
+                self.assertNotIn("OWL", text.split("\n")[0])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/workframe-api/tests/test_space_member_sync.py

@@ -0,0 +1,99 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+import server
+from db_setup import ensure_workframe_schemas
+
+
+class SpaceMemberSyncTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+        self._old_data_dir = server.DATA_DIR
+        self._old_auth_db_path = server.AUTH_DB_PATH
+        server.DATA_DIR = Path(self._tmp.name)
+        server.AUTH_DB_PATH = Path(self._tmp.name) / "auth.db"
+        ensure_workframe_schemas()
+        self.workspace_id = "ws-space"
+        self.owner_id = "user-owner"
+        self.member_id = "user-member"
+        conn = server._workframe_db()
+        try:
+            now = "1"
+            for uid, name in ((self.owner_id, "Owner"), (self.member_id, "Member")):
+                conn.execute(
+                    "INSERT INTO users (id, display_name, role, status, created_at, updated_at) VALUES (?,?,?,?,?,?)",
+                    (uid, name, "member", "active", now, now),
+                )
+            conn.execute(
+                """
+                INSERT INTO workspaces (id, slug, display_name, owner_id, status, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                """,
+                (self.workspace_id, "biz", "My Business", self.owner_id, "active", now, now),
+            )
+            for uid, role in ((self.owner_id, "owner"), (self.member_id, "member")):
+                conn.execute(
+                    """
+                    INSERT INTO workspace_memberships (id, workspace_id, user_id, role, status, created_at, updated_at)
+                    VALUES (?, ?, ?, ?, ?, ?, ?)
+                    """,
+                    (f"wm-{uid}", self.workspace_id, uid, role, "active", now, now),
+                )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def tearDown(self) -> None:
+        server.DATA_DIR = self._old_data_dir
+        server.AUTH_DB_PATH = self._old_auth_db_path
+
+    def test_new_space_adds_all_workspace_members(self) -> None:
+        status, payload = server._create_room(
+            self.workspace_id,
+            {"name": "Engineering", "slug": "engineering", "room_type": "channel"},
+            self.owner_id,
+        )
+        self.assertEqual(status, 201)
+        room_id = payload["room"]["id"]
+
+        conn = server._workframe_db()
+        try:
+            self.assertTrue(server._user_can_access_room(conn, room_id, self.owner_id))
+            self.assertTrue(server._user_can_access_room(conn, room_id, self.member_id))
+        finally:
+            conn.close()
+
+    def test_onboard_joins_existing_spaces(self) -> None:
+        status, payload = server._create_room(
+            self.workspace_id,
+            {"name": "Engineering", "slug": "engineering", "room_type": "channel"},
+            self.owner_id,
+        )
+        self.assertEqual(status, 201)
+        room_id = payload["room"]["id"]
+
+        late_user = "user-late"
+        conn = server._workframe_db()
+        try:
+            conn.execute(
+                "INSERT INTO users (id, display_name, role, status, created_at, updated_at) VALUES (?,?,?,?,?,?)",
+                (late_user, "Late", "member", "active", "2", "2"),
+            )
+            conn.execute(
+                """
+                INSERT INTO workspace_memberships (id, workspace_id, user_id, role, status, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                """,
+                ("wm-late", self.workspace_id, late_user, "member", "active", "2", "2"),
+            )
+            server._onboard_workspace_member_rooms(conn, self.workspace_id, late_user)
+            conn.commit()
+            self.assertTrue(server._user_can_access_room(conn, room_id, late_user))
+        finally:
+            conn.close()
+
+
+if __name__ == "__main__":
+    unittest.main()

package/workframe-api/tests/test_stripe_stack_config.py

@@ -0,0 +1,37 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+import stack_config
+
+
+class StripeStackConfigTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmpdir = tempfile.TemporaryDirectory()
+        stack_config.DATA_DIR = Path(self._tmpdir.name)
+        stack_config.CONFIG_PATH = stack_config.DATA_DIR / "stack_config.json"
+
+    def tearDown(self) -> None:
+        self._tmpdir.cleanup()
+
+    def test_stripe_connect_patch_and_public_payload(self) -> None:
+        stack_config.patch_stack_config(
+            {
+                "stripe_connect": {
+                    "client_id": "ca_test123",
+                    "client_secret": "sk_test_secret",
+                },
+            },
+        )
+        resolved = stack_config.resolved_stripe_connect()
+        self.assertEqual(resolved["client_id"], "ca_test123")
+        self.assertEqual(resolved["client_secret"], "sk_test_secret")
+        public = stack_config.get_stack_config()["stripe_connect"]
+        self.assertEqual(public["client_id"], "ca_test123")
+        self.assertTrue(public["has_secret"])
+        self.assertTrue(public["enabled"])
+        self.assertNotIn("client_secret", public)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/workframe-api/tests/test_supervisor_lifecycle.py

@@ -0,0 +1,52 @@
+import importlib.util
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+ROOT = Path(__file__).resolve().parents[2]
+SUPERVISOR = ROOT / "workframe-supervisor" / "server.py"
+API = ROOT / "workframe-api" / "server.py"
+
+
+def _load(path: Path, name: str):
+    spec = importlib.util.spec_from_file_location(name, path)
+    mod = importlib.util.module_from_spec(spec)
+    assert spec and spec.loader
+    spec.loader.exec_module(mod)
+    return mod
+
+
+class SupervisorAuthTest(unittest.TestCase):
+    def test_secrets_compare(self) -> None:
+        sup = _load(SUPERVISOR, "workframe_supervisor")
+        self.assertTrue(sup.secrets_compare("abc", "abc"))
+        self.assertFalse(sup.secrets_compare("abc", "abd"))
+
+
+class SecureModeLifecycleTest(unittest.TestCase):
+    def test_secure_mode_delegates_start_to_supervisor(self) -> None:
+        api = _load(API, "workframe_api")
+        with patch.object(api, "SECURE_MODE", True), patch.object(
+            api, "_primary_profile", return_value="workframe-agent"
+        ), patch.object(api, "resolve_validated_profile", return_value="architect"), patch.object(
+            api, "_supervisor_profile_lifecycle", return_value={"ok": True, "profile": "architect"}
+        ) as delegate:
+            out = api.profile_gateway_lifecycle("architect", "start")
+            delegate.assert_called_once_with("architect", "start")
+            self.assertTrue(out["ok"])
+
+    def test_secure_mode_gateway_exec_uses_supervisor(self) -> None:
+        api = _load(API, "workframe_api")
+        with patch.object(api, "SECURE_MODE", True), patch.object(
+            api, "resolve_validated_profile", return_value="architect"
+        ), patch.object(
+            api, "_supervisor_gateway_exec", return_value=(0, "ok")
+        ) as delegate:
+            code, out = api._gateway_exec("architect", ["gateway", "start"])
+            delegate.assert_called_once_with("architect", ["gateway", "start"])
+            self.assertEqual(code, 0)
+            self.assertEqual(out, "ok")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/workframe-api/tests/test_turn_credential_vault.py

@@ -0,0 +1,125 @@
+"""Per-run credential vault + lease tests."""
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+import credential_vault
+import server
+import turn_credentials
+import vault_kek
+from db_setup import ensure_workframe_schemas
+
+
+class TurnCredentialVaultTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+        self._old_data = server.DATA_DIR
+        self._old_auth = server.AUTH_DB_PATH
+        self._old_hermes = server.HERMES_DATA
+        server.DATA_DIR = Path(self._tmp.name) / "api-data"
+        server.DATA_DIR.mkdir(parents=True)
+        server.AUTH_DB_PATH = server.DATA_DIR / "auth.db"
+        server.HERMES_DATA = Path(self._tmp.name) / "hermes"
+        (server.HERMES_DATA / "profiles").mkdir(parents=True)
+        (server._profile_dir("workframe-agent")).mkdir(parents=True, exist_ok=True)
+        credential_vault.DATA_DIR = server.DATA_DIR
+        credential_vault.VAULT_DB = server.DATA_DIR / "credential_vault.db"
+        vault_kek.DATA_DIR = server.DATA_DIR
+        vault_kek.VAULT_KEK_FILE = server.DATA_DIR / ".vault_kek"
+        turn_credentials.DATA_DIR = server.DATA_DIR
+        turn_credentials.WORKFRAME_DB = server.DATA_DIR / "workframe.db"
+        ensure_workframe_schemas()
+        credential_vault.ensure_schema()
+        credential_vault.unseal_for_tests()
+        turn_credentials.ensure_schema()
+
+    def tearDown(self) -> None:
+        server.DATA_DIR = self._old_data
+        server.AUTH_DB_PATH = self._old_auth
+        server.HERMES_DATA = self._old_hermes
+
+    def test_store_user_credential_uses_vault_not_agents_env(self) -> None:
+        user_id = "user-vault-1"
+        payload = server._store_user_credential(
+            user_id, "openrouter", "api_key", "sk-secret", "OPENROUTER_API_KEY", "test",
+        )
+        self.assertTrue(str(payload["credential_ref"]).startswith("vault:"))
+        env_path = server._user_hermes_env_path(user_id)
+        if env_path.is_file():
+            self.assertNotIn("sk-secret", env_path.read_text(encoding="utf-8"))
+        bid = credential_vault.parse_vault_ref(payload["credential_ref"])
+        self.assertEqual(credential_vault.read_secret(bid), "sk-secret")
+
+    @patch.object(server, "_wait_profile_api_healthy", return_value=True)
+    def test_overlay_writes_lease_token_not_raw_secret(self, _wait_mock) -> None:
+        user_id = "user-vault-overlay-1"
+        workspace_id = "ws-vault-test"
+        self.workspace_id = workspace_id
+        self.user_a = user_id
+        conn = server._workframe_db()
+        try:
+            now = "1"
+            conn.execute(
+                "INSERT INTO workspaces (id, slug, display_name, owner_id, status, created_at, updated_at) VALUES (?,?,?,?,?,?,?)",
+                (workspace_id, "ws-vault-test", "Iso", user_id, "active", now, now),
+            )
+            conn.execute(
+                "INSERT INTO users (id, display_name, role, status, created_at, updated_at) VALUES (?,?,?,?,?,?)",
+                (user_id, "Fab", "member", "active", now, now),
+            )
+            conn.execute(
+                """
+                INSERT INTO workspace_memberships (id, workspace_id, user_id, role, status, created_at, updated_at)
+                VALUES (?, ?, ?, 'member', 'active', ?, ?)
+                """,
+                ("wm-1", workspace_id, user_id, now, now),
+            )
+            conn.execute(
+                """
+                INSERT INTO agent_profiles (id, workspace_id, slug, display_name, is_native, status, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, 'available', ?, ?)
+                """,
+                ("ap-arch", workspace_id, "architect", "Architect", 0, now, now),
+            )
+            cred_id = "cred-or-1"
+            conn.execute(
+                """
+                INSERT INTO credential_bindings (
+                    id, workspace_id, user_id, agent_profile_id, provider,
+                    credential_type, credential_ref, label, is_active,
+                    expires_at, created_by, created_at, updated_at, deleted_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    cred_id, None, user_id, None, "openrouter",
+                    "api_key", credential_vault.vault_ref(cred_id), "OR", 1, None, user_id,
+                    now, now, None,
+                ),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+        credential_vault.store_secret(cred_id, "sk-fab-only", env_var="OPENROUTER_API_KEY", provider="openrouter", user_id=user_id)
+        runtime = server._runtime_profile_slug(user_id, "architect")
+        prof_dir = server._profile_dir(runtime)
+        prof_dir.mkdir(parents=True, exist_ok=True)
+        run_id = "run-test-1"
+        server._overlay_turn_provider_env(runtime, user_id, workspace_id, "openrouter", run_id)
+        text = (prof_dir / ".env").read_text(encoding="utf-8")
+        self.assertIn("wf_rt_", text)
+        self.assertNotIn("sk-fab-only", text)
+        lease_line = [ln for ln in text.splitlines() if "OPENROUTER_API_KEY" in ln][0]
+        token = lease_line.split("=", 1)[1].strip().strip("\"'")
+        meta = turn_credentials.validate_lease(token)
+        self.assertIsNotNone(meta)
+        assert meta is not None
+        self.assertEqual(meta["run_id"], run_id)
+        server._revoke_turn_credential_lease(run_id, runtime)
+        self.assertIsNone(turn_credentials.validate_lease(token))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/workframe-api/tests/test_updates.py

@@ -0,0 +1,176 @@
+"""Stack update checks — version compare + safe apply hooks."""
+import json
+import os
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+import updates
+
+
+class UpdatesModuleTests(unittest.TestCase):
+    def test_version_lt(self) -> None:
+        self.assertTrue(updates._version_lt("0.1.0", "0.1.1"))
+        self.assertFalse(updates._version_lt("0.1.0", "0.1.0"))
+        self.assertFalse(updates._version_lt("0.2.0", "0.1.9"))
+
+    def test_parse_hermes_version_output(self) -> None:
+        self.assertEqual(
+            updates.parse_hermes_version_output("Hermes Agent v0.17.0 (2026.6.19) · upstream 50386786"),
+            "0.17.0",
+        )
+        self.assertEqual(updates.parse_hermes_version_output(""), "")
+
+    @mock.patch.object(updates, "_http_json")
+    def test_docker_hub_digest_prefers_tag_digest_over_first_image(self, http_json: mock.MagicMock) -> None:
+        http_json.return_value = {
+            "digest": "sha256:tag-level",
+            "images": [{"digest": "sha256:arm64-first", "architecture": "arm64", "os": "linux"}],
+        }
+        self.assertEqual(updates._docker_hub_digest("nousresearch/hermes-agent", "latest"), "sha256:tag-level")
+
+    @mock.patch.object(updates, "_http_json")
+    def test_docker_hub_digest_prefers_amd64_when_no_tag_digest(self, http_json: mock.MagicMock) -> None:
+        http_json.return_value = {
+            "images": [
+                {"digest": "sha256:arm64", "architecture": "arm64", "os": "linux"},
+                {"digest": "sha256:amd64", "architecture": "amd64", "os": "linux"},
+            ],
+        }
+        self.assertEqual(updates._docker_hub_digest("repo", "latest"), "sha256:amd64")
+
+    @mock.patch.object(updates, "_npm_latest_version", return_value="0.1.1")
+    @mock.patch.object(updates, "_container_image_digest", return_value=("digest-a", "nousresearch/hermes-agent:latest"))
+    @mock.patch.object(updates, "_docker_hub_digest", return_value="digest-b")
+    @mock.patch.object(updates.Path, "exists", return_value=True)
+    def test_updates_available_flags_workframe_and_hermes(
+        self,
+        _exists: mock.MagicMock,
+        _hub: mock.MagicMock,
+        _container: mock.MagicMock,
+        _npm: mock.MagicMock,
+    ) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "workframe-manifest.json").write_text(
+                json.dumps({"package_version": "0.1.0"}),
+                encoding="utf-8",
+            )
+            (root / "docker-compose.yml").write_text("services: {}\n", encoding="utf-8")
+            with mock.patch.dict(
+                os.environ,
+                {
+                    "WORKFRAME_PROJECT_ROOT": str(root),
+                    "WORKFRAME_COMPOSE_DIR": str(root),
+                    "WORKFRAME_API_VERSION": "0.1.0",
+                },
+                clear=False,
+            ):
+                status = updates.updates_available(desktop_version="0.0.9")
+        self.assertTrue(status["workframe"]["update_available"])
+        self.assertTrue(status["hermes"]["update_available"])
+        self.assertTrue(status["desktop"]["update_available"])
+        self.assertFalse(status["workframe"]["can_update"])
+        self.assertFalse(status["hermes"]["can_update"])
+        self.assertIn("WORKFRAME_HOST_COMPOSE_DIR", status["workframe"]["reason"] or "")
+
+    @mock.patch.object(updates, "_npm_latest_version", return_value="0.1.1")
+    @mock.patch.object(updates, "_container_image_digest", return_value=("digest-a", "nousresearch/hermes-agent:latest"))
+    @mock.patch.object(updates, "_docker_hub_digest", return_value="digest-b")
+    @mock.patch.object(updates, "_script_path")
+    @mock.patch.object(updates.Path, "exists", return_value=True)
+    def test_updates_available_can_update_when_host_compose_ready(
+        self,
+        _exists: mock.MagicMock,
+        script_path: mock.MagicMock,
+        _hub: mock.MagicMock,
+        _container: mock.MagicMock,
+        _npm: mock.MagicMock,
+    ) -> None:
+        script_path.side_effect = lambda name: Path(f"/tmp/{name}")
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "workframe-manifest.json").write_text(
+                json.dumps({"package_version": "0.1.0"}),
+                encoding="utf-8",
+            )
+            (root / "docker-compose.yml").write_text("services: {}\n", encoding="utf-8")
+            with mock.patch.dict(
+                os.environ,
+                {
+                    "WORKFRAME_PROJECT_ROOT": str(root),
+                    "WORKFRAME_COMPOSE_DIR": str(root),
+                    "WORKFRAME_HOST_COMPOSE_DIR": str(root),
+                    "WORKFRAME_API_VERSION": "0.1.0",
+                },
+                clear=False,
+            ):
+                status = updates.updates_available()
+        self.assertTrue(status["hermes"]["can_update"])
+        self.assertTrue(status["hermes"]["can_restart_gateway"])
+        self.assertEqual(status["hermes"]["state"], "available")
+
+    @mock.patch.object(updates, "_npm_latest_version", return_value="0.1.0")
+    @mock.patch.object(updates, "_container_image_digest", return_value=("digest-a", "img"))
+    @mock.patch.object(updates, "_docker_hub_digest", return_value="digest-a")
+    @mock.patch.object(updates.Path, "exists", return_value=True)
+    def test_updates_available_when_digest_unknown_no_hermes_flag(
+        self,
+        _exists: mock.MagicMock,
+        _hub: mock.MagicMock,
+        _container: mock.MagicMock,
+        _npm: mock.MagicMock,
+    ) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "workframe-manifest.json").write_text(
+                json.dumps({"package_version": "0.1.0"}),
+                encoding="utf-8",
+            )
+            with mock.patch.dict(
+                os.environ,
+                {"WORKFRAME_PROJECT_ROOT": str(root), "WORKFRAME_COMPOSE_DIR": str(root)},
+                clear=False,
+            ):
+                status = updates.updates_available()
+        self.assertFalse(status["hermes"]["update_available"])
+        self.assertFalse(status["workframe"]["update_available"])
+
+    @mock.patch.object(updates.subprocess, "run")
+    @mock.patch.object(updates, "_script_path")
+    @mock.patch.object(updates.Path, "exists", return_value=True)
+    def test_apply_update_runs_scripts(
+        self,
+        _exists: mock.MagicMock,
+        script_path: mock.MagicMock,
+        run: mock.MagicMock,
+    ) -> None:
+        script_path.side_effect = lambda name: Path(f"/tmp/{name}")
+        run.return_value = mock.Mock(returncode=0, stdout="ok", stderr="")
+        with mock.patch.dict(os.environ, {"WORKFRAME_COMPOSE_DIR": "/tmp", "WORKFRAME_PROJECT_ROOT": "/tmp", "WORKFRAME_ENABLE_ADMIN_UPDATES": "1"}, clear=False):
+            result = updates.apply_update("hermes")
+        self.assertTrue(result["ok"])
+        run.assert_called_once()
+
+    @mock.patch.object(updates.subprocess, "run")
+    @mock.patch.object(updates, "_script_path")
+    @mock.patch.object(updates, "_docker_apply_ready", return_value=(True, None))
+    @mock.patch.object(updates.Path, "exists", return_value=True)
+    def test_restart_gateway_runs_script(
+        self,
+        _exists: mock.MagicMock,
+        _ready: mock.MagicMock,
+        script_path: mock.MagicMock,
+        run: mock.MagicMock,
+    ) -> None:
+        script_path.return_value = Path("/tmp/restart-gateway-hermes.sh")
+        run.return_value = mock.Mock(returncode=0, stdout="ok", stderr="")
+        with mock.patch.dict(os.environ, {"WORKFRAME_COMPOSE_DIR": "/tmp", "WORKFRAME_PROJECT_ROOT": "/tmp", "WORKFRAME_ENABLE_ADMIN_UPDATES": "1"}, clear=False):
+            result = updates.restart_gateway()
+        self.assertTrue(result["ok"])
+        run.assert_called_once()
+
+
+if __name__ == "__main__":
+    unittest.main()