@agentikos/omega-os 0.1.0 → 0.19.5

package/omega/Agentik_Engine/tests/test_managed_agent.py

@@ -0,0 +1,363 @@
+"""Tests for omega_engine.managed_agent — Anthropic Managed Agents wrapper.
+
+Strategy: mock urllib.request.urlopen at the boundary so we exercise the
+real serialization, header injection, error handling, SSE stream parser,
+cache, and Provider integration without ever hitting the network.
+"""
+from __future__ import annotations
+
+import io
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE.parent))
+
+from omega_engine import managed_agent as MA  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# Fake urllib helpers
+# ---------------------------------------------------------------------------
+
+
+class _FakeResponse:
+    """Minimal stand-in for the object returned by urlopen()."""
+
+    def __init__(self, body: bytes, status: int = 200):
+        self._buf = io.BytesIO(body)
+        self.status = status
+
+    def read(self) -> bytes:
+        return self._buf.read()
+
+    def __iter__(self):
+        # Yield line by line (with trailing \n) — matches what SSE does.
+        self._buf.seek(0)
+        for raw in self._buf:
+            yield raw
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+    def close(self):
+        self._buf.close()
+
+
+def _json_response(payload: dict) -> _FakeResponse:
+    return _FakeResponse(json.dumps(payload).encode("utf-8"))
+
+
+def _sse_response(events: list[dict]) -> _FakeResponse:
+    """Build a fake SSE body from a list of event dicts."""
+    body = b""
+    for ev in events:
+        body += b"data: " + json.dumps(ev).encode("utf-8") + b"\n\n"
+    return _FakeResponse(body)
+
+
+# ---------------------------------------------------------------------------
+# Client — REST shape
+# ---------------------------------------------------------------------------
+
+
+class TestClientHeaders(unittest.TestCase):
+    def _captured_request(self, urlopen_patch):
+        # urlopen_patch.call_args[0][0] is the Request object.
+        req = urlopen_patch.call_args[0][0]
+        return req
+
+    def test_create_agent_sends_beta_header(self):
+        c = MA.ManagedAgentClient(api_key="sk-test")
+        with mock.patch("urllib.request.urlopen",
+                        return_value=_json_response({"id": "agent_1", "version": 1})) as uo:
+            c.create_agent(name="x", model="claude-opus-4-7", system="hi")
+        req = self._captured_request(uo)
+        self.assertEqual(req.get_header("X-api-key"), "sk-test")
+        self.assertEqual(req.get_header("Anthropic-beta"),
+                         "managed-agents-2026-04-01")
+        self.assertEqual(req.get_header("Anthropic-version"), "2023-06-01")
+        # Body is the agent definition
+        body = json.loads(req.data.decode("utf-8"))
+        self.assertEqual(body["name"], "x")
+        self.assertEqual(body["model"], "claude-opus-4-7")
+        self.assertEqual(body["system"], "hi")
+        self.assertEqual(body["tools"], [{"type": "agent_toolset_20260401"}])
+
+    def test_create_agent_defaults_tools_to_full_toolset(self):
+        c = MA.ManagedAgentClient(api_key="sk-test")
+        with mock.patch("urllib.request.urlopen",
+                        return_value=_json_response({"id": "agent_2"})) as uo:
+            c.create_agent(name="x")
+        body = json.loads(uo.call_args[0][0].data.decode("utf-8"))
+        self.assertEqual(body["tools"], [{"type": "agent_toolset_20260401"}])
+
+    def test_create_environment_defaults_to_cloud_unrestricted(self):
+        c = MA.ManagedAgentClient(api_key="sk-test")
+        with mock.patch("urllib.request.urlopen",
+                        return_value=_json_response({"id": "env_1"})) as uo:
+            c.create_environment(name="quickstart")
+        body = json.loads(uo.call_args[0][0].data.decode("utf-8"))
+        self.assertEqual(body["name"], "quickstart")
+        self.assertEqual(body["config"]["type"], "cloud")
+        self.assertEqual(body["config"]["networking"]["type"], "unrestricted")
+
+    def test_send_user_message_shape(self):
+        c = MA.ManagedAgentClient(api_key="sk-test")
+        with mock.patch("urllib.request.urlopen",
+                        return_value=_json_response({})) as uo:
+            c.send_user_message("sess_1", "hello world")
+        body = json.loads(uo.call_args[0][0].data.decode("utf-8"))
+        self.assertEqual(body["events"][0]["type"], "user.message")
+        self.assertEqual(body["events"][0]["content"][0]["text"], "hello world")
+
+    def test_http_error_raises_managed_agent_error(self):
+        import urllib.error
+        c = MA.ManagedAgentClient(api_key="sk-test")
+        err = urllib.error.HTTPError(
+            "http://x", 401,
+            "Unauthorized", {}, io.BytesIO(b'{"error":"bad key"}'),
+        )
+        with mock.patch("urllib.request.urlopen", side_effect=err):
+            with self.assertRaises(MA.ManagedAgentError) as ctx:
+                c.create_agent(name="x")
+            self.assertIn("HTTP 401", str(ctx.exception))
+
+
+# ---------------------------------------------------------------------------
+# SSE stream parser
+# ---------------------------------------------------------------------------
+
+
+class TestStreamParser(unittest.TestCase):
+    def test_stream_yields_each_event(self):
+        c = MA.ManagedAgentClient(api_key="sk-test")
+        events = [
+            {"type": "agent.message",
+             "content": [{"type": "text", "text": "hi"}]},
+            {"type": "agent.tool_use", "name": "bash"},
+            {"type": "session.status_idle"},
+        ]
+        with mock.patch("urllib.request.urlopen",
+                        return_value=_sse_response(events)):
+            out = list(c.stream_events("sess_x"))
+        self.assertEqual(len(out), 3)
+        self.assertEqual(out[0]["type"], "agent.message")
+        self.assertEqual(out[2]["type"], "session.status_idle")
+
+    def test_stream_stops_on_idle_when_stop_on_idle(self):
+        c = MA.ManagedAgentClient(api_key="sk-test")
+        events = [
+            {"type": "agent.message",
+             "content": [{"type": "text", "text": "a"}]},
+            {"type": "session.status_idle"},
+            # These MUST be ignored when stop_on_idle=True
+            {"type": "agent.message",
+             "content": [{"type": "text", "text": "leak"}]},
+        ]
+        with mock.patch("urllib.request.urlopen",
+                        return_value=_sse_response(events)):
+            out = list(c.stream_events("sess_x", stop_on_idle=True))
+        self.assertEqual(len(out), 2)
+        self.assertEqual(out[-1]["type"], "session.status_idle")
+
+    def test_stream_ignores_malformed_lines(self):
+        c = MA.ManagedAgentClient(api_key="sk-test")
+        body = (
+            b"\n"                              # blank
+            b": comment\n"                     # SSE comment
+            b"data: not-json\n\n"              # malformed payload
+            b'data: {"type":"agent.message","content":[{"type":"text","text":"ok"}]}\n\n'
+            b'data: {"type":"session.status_idle"}\n\n'
+        )
+        with mock.patch("urllib.request.urlopen",
+                        return_value=_FakeResponse(body)):
+            out = list(c.stream_events("sess_x"))
+        # Two valid events parsed; malformed line silently skipped
+        self.assertEqual(len(out), 2)
+        self.assertEqual(out[0]["type"], "agent.message")
+
+
+# ---------------------------------------------------------------------------
+# Cache
+# ---------------------------------------------------------------------------
+
+
+class TestCache(unittest.TestCase):
+    def test_round_trip(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cache = MA.ManagedAgentCache(Path(tmp))
+            self.assertIsNone(cache.get_agent("a"))
+            cache.set_agent("a", "agent_123")
+            cache.set_environment("env-a", "env_456")
+            self.assertEqual(cache.get_agent("a"), "agent_123")
+            self.assertEqual(cache.get_environment("env-a"), "env_456")
+
+    def test_atomic_write_no_tmp_left_behind(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cache = MA.ManagedAgentCache(Path(tmp))
+            cache.set_agent("x", "agent_1")
+            p = MA._cache_path(Path(tmp))
+            # No .tmp.* siblings
+            leftovers = list(p.parent.glob("*.tmp.*"))
+            self.assertEqual(leftovers, [])
+
+    def test_corrupt_cache_yields_empty(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            p = MA._cache_path(Path(tmp))
+            p.parent.mkdir(parents=True, exist_ok=True)
+            p.write_text("{not valid")
+            cache = MA.ManagedAgentCache(Path(tmp))
+            self.assertIsNone(cache.get_agent("x"))
+
+
+# ---------------------------------------------------------------------------
+# Provider — full path
+# ---------------------------------------------------------------------------
+
+
+class TestProvider(unittest.TestCase):
+    def test_run_creates_agent_env_session_and_aggregates_text(self):
+        from omega_engine.provider import AgentRequest
+
+        # Mock the network: 1 POST /agents + 1 POST /environments +
+        # 1 POST /sessions + 1 POST /sessions/<id>/events + 1 GET /stream (SSE)
+        calls: list[str] = []
+
+        def fake_urlopen(req, timeout=None):
+            url = req.full_url
+            calls.append(req.get_method() or "GET")
+            if url.endswith("/agents") and req.get_method() == "POST":
+                return _json_response({"id": "agent_X", "version": 1})
+            if url.endswith("/environments") and req.get_method() == "POST":
+                return _json_response({"id": "env_X"})
+            if url.endswith("/sessions") and req.get_method() == "POST":
+                return _json_response({"id": "sess_X"})
+            if "events" in url and req.get_method() == "POST":
+                return _json_response({})
+            if "stream" in url:
+                return _sse_response([
+                    {"type": "agent.message",
+                     "content": [{"type": "text", "text": "hello "},
+                                 {"type": "text", "text": "world"}]},
+                    {"type": "agent.tool_use", "name": "bash"},
+                    {"type": "session.status_idle"},
+                ])
+            raise AssertionError(f"unmocked: {req.get_method()} {url}")
+
+        with tempfile.TemporaryDirectory() as tmp:
+            with mock.patch("urllib.request.urlopen",
+                            side_effect=fake_urlopen):
+                p = MA.ManagedAgentProvider(
+                    api_key="sk-test", omega_home=Path(tmp),
+                )
+                result = p.run(AgentRequest(
+                    role="worker", prompt="do the thing",
+                    system="", context=None,
+                ))
+        self.assertEqual(result.text, "hello world")
+        self.assertEqual(result.artifacts["managed_agent"]["session_id"],
+                         "sess_X")
+        self.assertEqual(result.artifacts["managed_agent"]["tool_uses"],
+                         ["bash"])
+
+    def test_run_reuses_cached_agent_and_env_on_second_call(self):
+        """Second run should NOT re-POST /agents or /environments."""
+        from omega_engine.provider import AgentRequest
+
+        post_calls: list[str] = []
+
+        def fake_urlopen(req, timeout=None):
+            url = req.full_url
+            if req.get_method() == "POST":
+                post_calls.append(url)
+            if url.endswith("/agents") and req.get_method() == "POST":
+                return _json_response({"id": "agent_A"})
+            if url.endswith("/environments") and req.get_method() == "POST":
+                return _json_response({"id": "env_A"})
+            if url.endswith("/sessions") and req.get_method() == "POST":
+                return _json_response({"id": "sess_Y"})
+            if "events" in url and req.get_method() == "POST":
+                return _json_response({})
+            if "stream" in url:
+                return _sse_response([
+                    {"type": "agent.message",
+                     "content": [{"type": "text", "text": "ok"}]},
+                    {"type": "session.status_idle"},
+                ])
+            raise AssertionError(f"unmocked: {req.get_method()} {url}")
+
+        with tempfile.TemporaryDirectory() as tmp:
+            with mock.patch("urllib.request.urlopen",
+                            side_effect=fake_urlopen):
+                p = MA.ManagedAgentProvider(api_key="sk-test", omega_home=Path(tmp))
+                p.run(AgentRequest(role="worker", prompt="one", system="", context=None))
+                # Reset post_calls — only count the second invocation
+                post_calls.clear()
+                p2 = MA.ManagedAgentProvider(api_key="sk-test", omega_home=Path(tmp))
+                p2.run(AgentRequest(role="worker", prompt="two", system="", context=None))
+        # Second run: NO /agents, NO /environments. Only /sessions + /events.
+        for url in post_calls:
+            self.assertFalse(
+                url.endswith("/agents"), f"unexpected re-create: {url}")
+            self.assertFalse(
+                url.endswith("/environments"), f"unexpected re-create: {url}")
+
+    def test_constructor_rejects_missing_api_key(self):
+        # Patch env to be empty
+        with mock.patch.dict(os.environ, {}, clear=True):
+            with self.assertRaises(ValueError):
+                MA.ManagedAgentProvider(api_key=None)
+
+    def test_is_available_reflects_env(self):
+        with mock.patch.dict(os.environ, {"ANTHROPIC_API_KEY": "sk-x"}):
+            self.assertTrue(MA.ManagedAgentProvider.is_available())
+        with mock.patch.dict(os.environ, {}, clear=True):
+            self.assertFalse(MA.ManagedAgentProvider.is_available())
+
+    def test_run_with_system_prompt_prepended(self):
+        from omega_engine.provider import AgentRequest
+
+        captured_event_body = {}
+
+        def fake_urlopen(req, timeout=None):
+            url = req.full_url
+            if url.endswith("/agents"):
+                return _json_response({"id": "agent_S"})
+            if url.endswith("/environments"):
+                return _json_response({"id": "env_S"})
+            if url.endswith("/sessions"):
+                return _json_response({"id": "sess_S"})
+            if "events" in url:
+                captured_event_body["body"] = json.loads(
+                    req.data.decode("utf-8")
+                )
+                return _json_response({})
+            if "stream" in url:
+                return _sse_response([{"type": "session.status_idle"}])
+            raise AssertionError(f"unmocked: {url}")
+
+        with tempfile.TemporaryDirectory() as tmp:
+            with mock.patch("urllib.request.urlopen",
+                            side_effect=fake_urlopen):
+                p = MA.ManagedAgentProvider(api_key="sk-test", omega_home=Path(tmp))
+                p.run(AgentRequest(
+                    role="worker", prompt="do X",
+                    system="be careful", context=None,
+                ))
+        text = captured_event_body["body"]["events"][0]["content"][0]["text"]
+        self.assertIn("[system] be careful", text)
+        self.assertIn("do X", text)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/omega/Agentik_Engine/tests/test_max_provider_and_menu.py

@@ -0,0 +1,231 @@
+"""Tests for the ClaudeMaxProvider + the interactive menu wiring.
+
+The Max provider subprocesses ``claude -p`` — we don't actually run real
+Claude in tests (cost + dependency). We mock subprocess.run to feed the
+provider a canned JSON response and verify it parses correctly.
+
+For the menu, we test the wiring: bare `omega` invocation dispatches to
+``cmd_menu``, and ``run_menu`` refuses cleanly when whiptail is missing.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE.parent))
+
+
+# ---------------------------------------------------------------------------
+# ClaudeMaxProvider
+# ---------------------------------------------------------------------------
+
+
+_CANNED_CLAUDE_JSON = {
+    "type": "result", "subtype": "success", "is_error": False,
+    "duration_ms": 4344, "duration_api_ms": 1760, "num_turns": 1,
+    "result": "Done.",
+    "stop_reason": "end_turn",
+    "session_id": "fake-session-abc",
+    "total_cost_usd": 0.0123,
+    "usage": {
+        "input_tokens": 12, "output_tokens": 34,
+        "cache_read_input_tokens": 0,
+        "cache_creation_input_tokens": 100,
+    },
+    "modelUsage": {"claude-opus-4-7": {"costUSD": 0.0123}},
+}
+
+
+def _fake_proc(stdout: str = "", returncode: int = 0, stderr: str = ""):
+    return subprocess.CompletedProcess(
+        args=[], returncode=returncode, stdout=stdout, stderr=stderr,
+    )
+
+
+class TestClaudeMaxAvailability(unittest.TestCase):
+    def test_unavailable_when_claude_missing(self):
+        from omega_engine.provider import ClaudeMaxProvider
+        with mock.patch("shutil.which", return_value=None):
+            self.assertFalse(ClaudeMaxProvider.is_available())
+
+    def test_available_when_version_responds(self):
+        from omega_engine.provider import ClaudeMaxProvider
+        with mock.patch("shutil.which", return_value="/usr/bin/claude"), \
+             mock.patch("subprocess.run", return_value=_fake_proc("claude 1.0.0", 0)):
+            self.assertTrue(ClaudeMaxProvider.is_available())
+
+
+class TestClaudeMaxRun(unittest.TestCase):
+    def _provider(self):
+        from omega_engine.provider import ClaudeMaxProvider
+        return ClaudeMaxProvider(model="sonnet")
+
+    def test_parses_canned_response(self):
+        from omega_engine.provider import AgentRequest
+        p = self._provider()
+        with mock.patch(
+            "subprocess.run",
+            return_value=_fake_proc(json.dumps(_CANNED_CLAUDE_JSON), 0),
+        ):
+            result = p.run(AgentRequest(
+                role="worker", prompt="say done",
+            ))
+        self.assertEqual(result.text, "Done.")
+        self.assertTrue(result.claimed_done)
+        self.assertEqual(result.usage["input_tokens"], 12)
+        self.assertEqual(result.usage["output_tokens"], 34)
+        self.assertAlmostEqual(result.usage["cost_usd"], 0.0123)
+        self.assertEqual(result.artifacts["session_id"], "fake-session-abc")
+        self.assertEqual(result.artifacts["num_turns"], 1)
+
+    def test_subprocess_command_carries_system_prompt(self):
+        from omega_engine.provider import AgentRequest
+        p = self._provider()
+        captured: dict = {}
+
+        def fake_run(cmd, **kw):
+            captured["cmd"] = cmd
+            return _fake_proc(json.dumps(_CANNED_CLAUDE_JSON), 0)
+
+        with mock.patch("subprocess.run", side_effect=fake_run):
+            p.run(AgentRequest(
+                role="worker", prompt="hi",
+                system="You are a focused worker.",
+            ))
+        # --append-system-prompt is on the command line
+        self.assertIn("--append-system-prompt", captured["cmd"])
+        self.assertIn("You are a focused worker.", captured["cmd"])
+        # --dangerously-skip-permissions is set (headless Max)
+        self.assertIn("--dangerously-skip-permissions", captured["cmd"])
+        # --output-format json is on
+        self.assertIn("--output-format", captured["cmd"])
+        self.assertIn("json", captured["cmd"])
+
+    def test_resume_session(self):
+        from omega_engine.provider import AgentRequest
+        p = self._provider()
+        captured: dict = {}
+
+        def fake_run(cmd, **kw):
+            captured["cmd"] = cmd
+            return _fake_proc(json.dumps(_CANNED_CLAUDE_JSON), 0)
+
+        with mock.patch("subprocess.run", side_effect=fake_run):
+            p.run(AgentRequest(
+                role="oracle", prompt="next step",
+                context={"session_id": "prev-abc"},
+            ))
+        self.assertIn("--resume", captured["cmd"])
+        self.assertIn("prev-abc", captured["cmd"])
+
+    def test_failure_surfaces_clean_error(self):
+        from omega_engine.provider import AgentRequest
+        p = self._provider()
+        with mock.patch(
+            "subprocess.run",
+            return_value=_fake_proc("", 1, "rate limit hit"),
+        ):
+            with self.assertRaises(RuntimeError) as ctx:
+                p.run(AgentRequest(role="worker", prompt="hi"))
+        self.assertIn("rate limit", str(ctx.exception))
+
+
+class TestRouterAuto(unittest.TestCase):
+    def test_auto_picks_claude_max_when_available(self):
+        from omega_engine.router import ModelRouter
+        from omega_engine.provider import ClaudeMaxProvider
+        with mock.patch.object(ClaudeMaxProvider, "is_available",
+                                return_value=True):
+            router = ModelRouter.auto()
+        self.assertEqual(router.resolve("worker").id, "claude-max")
+
+    def test_auto_falls_back_to_api_when_max_unavailable(self):
+        from omega_engine.router import ModelRouter
+        from omega_engine.provider import ClaudeMaxProvider
+        with mock.patch.object(ClaudeMaxProvider, "is_available",
+                                return_value=False), \
+             mock.patch.dict("os.environ", {"ANTHROPIC_API_KEY": "sk-x"}):
+            router = ModelRouter.auto()
+        self.assertEqual(router.resolve("worker").id, "claude")
+
+    def test_auto_falls_back_to_mock_when_nothing(self):
+        from omega_engine.router import ModelRouter
+        from omega_engine.provider import ClaudeMaxProvider
+        with mock.patch.object(ClaudeMaxProvider, "is_available",
+                                return_value=False), \
+             mock.patch.dict("os.environ", {}, clear=True):
+            router = ModelRouter.auto()
+        self.assertEqual(router.resolve("worker").id, "mock")
+
+
+# ---------------------------------------------------------------------------
+# Menu wiring
+# ---------------------------------------------------------------------------
+
+
+class TestMenuDispatch(unittest.TestCase):
+    def test_bare_omega_dispatches_to_menu(self):
+        """parse_args([]) should set fn to cmd_menu — i.e. `omega`
+        with no subcommand opens the interactive menu, doesn't error."""
+        from omega_engine.cli import _build_parser, cmd_menu
+        parser = _build_parser()
+        # argparse with optional subparser → no args parses cleanly
+        args = parser.parse_args([])
+        self.assertEqual(args.fn, cmd_menu)
+
+    def test_run_menu_falls_back_to_text_when_whiptail_missing(self):
+        """Behaviour changed in v0.19.4: a bare `omega` MUST NEVER exit
+        silently when whiptail is missing — it falls back to a stdin/stdout
+        text menu. Without this fix, Mac users hit `omega` and got nothing
+        ("se passe rien" — the v0.19.3 regression)."""
+        from omega_engine.menu import run_menu
+        import io, contextlib
+        # whiptail absent → text fallback. User picks "0" (quit).
+        with mock.patch("omega_engine.menu._have", return_value=False), \
+             mock.patch("builtins.input", side_effect=["0"]):
+            with contextlib.redirect_stdout(io.StringIO()) as buf:
+                rc = run_menu()
+        self.assertEqual(rc, 0, "text fallback must exit cleanly on user quit")
+        # The text menu must actually print SOMETHING — the silent return
+        # was the bug we're guarding against.
+        self.assertIn("Omega OS", buf.getvalue())
+
+    def test_run_menu_quits_cleanly(self):
+        from omega_engine.menu import run_menu
+        # Simulate user choosing "quit" from the main menu.
+        with mock.patch("omega_engine.menu._have", return_value=True), \
+             mock.patch("omega_engine.menu._whiptail_menu",
+                        return_value="quit"):
+            rc = run_menu()
+        self.assertEqual(rc, 0)
+
+
+class TestMenuHelpers(unittest.TestCase):
+    def test_run_capture_invokes_omega_bin(self):
+        from omega_engine.menu import _run_capture
+
+        captured: dict = {}
+
+        def fake_run(cmd, **kw):
+            captured["cmd"] = cmd
+            return _fake_proc("ok\n", 0)
+
+        with mock.patch("subprocess.run", side_effect=fake_run):
+            out = _run_capture("doctor")
+        self.assertEqual(out, "ok")
+        # The omega args land in cmd[1:], whatever the binary path is.
+        self.assertEqual(captured["cmd"][1], "doctor")
+        # The first arg is a real path (resolved omega bin or sys.argv[0]).
+        self.assertGreater(len(captured["cmd"][0]), 0)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/omega/Agentik_Engine/tests/test_menu_coverage.py

@@ -0,0 +1,72 @@
+"""Coverage tests for the interactive menu — make sure the new v0.19.1
+entries (genesis, plan, worker, handoff, hermes, hermes-desktop,
+memory, learn, update, ua, ma) all have:
+
+  * an entry in _MAIN_ITEMS
+  * a corresponding _menu_<name> function
+  * a dispatch arm in run_menu
+
+So the next time we add a top-level CLI command, the test reminds the
+maintainer to wire it into the menu too.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+import unittest
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE.parent))
+
+from omega_engine import menu as M  # noqa: E402
+
+
+# Every key here MUST appear in _MAIN_ITEMS AND have a _menu_<key>
+# function (with the hyphen normalised to underscore for the func name).
+_EXPECTED_KEYS_V019 = {
+    "mission", "genesis", "plan", "worker", "handoff",
+    "hermes", "hermes-desktop", "tmux", "aisb-chat",
+    "projects", "accounts", "audit", "skills",
+    "memory", "learn", "update", "ua", "ma",
+    "maintenance", "settings", "status", "doctor",
+}
+
+
+class TestMenuCoverage(unittest.TestCase):
+    def test_main_items_count(self):
+        """We added 11 new entries in v0.19.1. Floor: 22 (not counting quit)."""
+        non_quit = [k for k, _ in M._MAIN_ITEMS if k != "quit"]
+        self.assertGreaterEqual(len(non_quit), 22,
+            f"main menu shrank below 22 entries: {non_quit}")
+
+    def test_all_expected_keys_present(self):
+        keys = {k for k, _ in M._MAIN_ITEMS}
+        missing = _EXPECTED_KEYS_V019 - keys
+        self.assertEqual(missing, set(),
+            f"missing menu entries: {missing}")
+
+    def test_every_main_item_has_handler_or_is_leaf(self):
+        """For every non-leaf entry, _menu_<name> MUST exist."""
+        # 'quit', 'status', 'doctor' are leaves (no sub-menu).
+        leaves = {"quit", "status", "doctor"}
+        for key, _ in M._MAIN_ITEMS:
+            if key in leaves:
+                continue
+            func_name = "_menu_" + key.replace("-", "_")
+            self.assertTrue(
+                hasattr(M, func_name),
+                f"main menu entry {key!r} has no {func_name}() function",
+            )
+
+    def test_no_duplicate_keys(self):
+        keys = [k for k, _ in M._MAIN_ITEMS]
+        self.assertEqual(len(keys), len(set(keys)),
+                         "duplicate menu keys")
+
+    def test_quit_is_present(self):
+        keys = {k for k, _ in M._MAIN_ITEMS}
+        self.assertIn("quit", keys)
+
+
+if __name__ == "__main__":
+    unittest.main()