refactor(manifest): raise ManifestError instead of die()

Review feedback on #102: a manifest that can't be read should raise an
exception, not call die() (a SystemExit). That SystemExit was the whole
reason the dashboard had to special-case Die.

manifest.py now raises ManifestError (a plain Exception) for every
validation failure. The CLI dispatcher catches it and prints+exits 1
(same UX as before); the dashboard catches it with a normal
`except ManifestError` and degrades to a status-line warning. Manifest
tests assert on ManifestError + its message.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/unit/test_manifest_agent_git_user.py

@@ -12,8 +12,6 @@ a temp-dir case locks the md loader (the `_AGENT_KEYS` allow + the
 
 from __future__ import annotations
 
-import contextlib
-import io
 import os
 import shutil
 import tempfile
@@ -21,18 +19,16 @@ import textwrap
 import unittest
 from pathlib import Path
 
-from bot_bottle.log import Die
-from bot_bottle.manifest import Manifest
+from bot_bottle.manifest import ManifestError, Manifest
 
 
-def _die_message(callable_, *args, **kwargs) -> str:
-    buf = io.StringIO()
-    with contextlib.redirect_stderr(buf):
-        try:
-            callable_(*args, **kwargs)
-        except Die:
-            return buf.getvalue()
-    raise AssertionError("expected Die was not raised")
+def _error_message(callable_, *args, **kwargs) -> str:
+    """Run `callable_` expecting a ManifestError; return its message."""
+    try:
+        callable_(*args, **kwargs)
+    except ManifestError as e:
+        return str(e)
+    raise AssertionError("expected ManifestError was not raised")
 
 
 def _manifest(*, bottle_user=None, agent_git=None) -> Manifest:
@@ -120,19 +116,19 @@ class TestAgentGitUserOverlay(unittest.TestCase):
 
 class TestAgentGitUserRejections(unittest.TestCase):
     def test_agent_remotes_dies_bottle_only(self):
-        msg = _die_message(_manifest, agent_git={
+        msg = _error_message(_manifest, agent_git={
             "remotes": {"h": {"Name": "r", "Upstream": "ssh://x/y.git"}},
         })
         self.assertIn("git.remotes", msg)
         self.assertIn("bottle-only", msg)
 
     def test_agent_unknown_git_subkey_dies(self):
-        msg = _die_message(_manifest, agent_git={"nope": {}})
+        msg = _error_message(_manifest, agent_git={"nope": {}})
         self.assertIn("not allowed at the agent level", msg)
 
     def test_agent_git_user_both_empty_dies(self):
         # Reuses GitUser.from_dict validation.
-        msg = _die_message(_manifest, agent_git={"user": {"name": "", "email": ""}})
+        msg = _error_message(_manifest, agent_git={"user": {"name": "", "email": ""}})
         self.assertIn("neither name nor email", msg)
 
 
@@ -239,7 +235,7 @@ class TestAgentGitUserMdLoader(unittest.TestCase):
     def test_md_agent_remotes_dies(self):
         self._write("bottles/dev.md", _BOTTLE_DEV)
         self._write("agents/impl.md", _AGENT_WITH_REMOTES)
-        msg = _die_message(Manifest.resolve, str(self.home))
+        msg = _error_message(Manifest.resolve, str(self.home))
         self.assertIn("git.remotes", msg)
         self.assertIn("bottle-only", msg)
 

tests/unit/test_manifest_egress.py

@@ -7,8 +7,7 @@ auth omission means unauthenticated."""
 
 import unittest
 
-from bot_bottle.log import Die
-from bot_bottle.manifest import EgressRoute, Manifest
+from bot_bottle.manifest import ManifestError, EgressRoute, Manifest
 
 
 def _bottle(routes):
@@ -41,15 +40,15 @@ class TestMinimalRoute(unittest.TestCase):
         self.assertEqual("", r.TokenRef)
 
     def test_host_required(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{}])
 
     def test_host_must_be_non_empty(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{"host": ""}])
 
     def test_unknown_top_level_key_dies(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{"host": "x.example", "wat": "yes"}])
 
 
@@ -59,15 +58,15 @@ class TestPathAllowlist(unittest.TestCase):
         self.assertEqual((), b.egress.routes[0].PathAllowlist)
 
     def test_must_be_array(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{"host": "x.example", "path_allowlist": "/x/"}])
 
     def test_items_must_be_strings(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{"host": "x.example", "path_allowlist": [42]}])
 
     def test_items_must_be_absolute_paths(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{"host": "x.example", "path_allowlist": ["nope/"]}])
 
     def test_full_list(self):
@@ -100,25 +99,25 @@ class TestAuth(unittest.TestCase):
     def test_empty_auth_block_rejected(self):
         # Per PRD 0017: `auth: {}` is an error, not a synonym for
         # "no auth" — that's what omission is for.
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{"host": "x.example", "auth": {}}])
 
     def test_missing_scheme_rejected(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{
                 "host": "x.example",
                 "auth": {"token_ref": "T"},
             }])
 
     def test_missing_token_ref_rejected(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{
                 "host": "x.example",
                 "auth": {"scheme": "Bearer"},
             }])
 
     def test_unknown_scheme_rejected(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{
                 "host": "x.example",
                 "auth": {"scheme": "Basic", "token_ref": "T"},
@@ -133,7 +132,7 @@ class TestAuth(unittest.TestCase):
         self.assertEqual("token", b.egress.routes[0].AuthScheme)
 
     def test_unknown_auth_key_rejected(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{
                 "host": "x.example",
                 "auth": {"scheme": "Bearer", "token_ref": "T", "extra": "no"},
@@ -166,22 +165,22 @@ class TestRole(unittest.TestCase):
     def test_unknown_role_rejected(self):
         # The role enum is locked down — typos shouldn't silently
         # become no-op markers.
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{"host": "x.example", "role": "totally-made-up"}])
 
     def test_non_string_role_rejected(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{"host": "x.example", "role": 42}])
 
     def test_list_with_non_string_item_rejected(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{"host": "x.example",
                       "role": ["claude_code_oauth", 42]}])
 
     def test_singleton_claude_code_oauth_enforced(self):
         # Two routes both claiming the role would make "which one
         # drives the placeholder env?" ambiguous.
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([
                 {"host": "api.anthropic.com", "role": "claude_code_oauth",
                  "auth": {"scheme": "Bearer", "token_ref": "T1"}},
@@ -199,7 +198,7 @@ class TestRole(unittest.TestCase):
         self.assertEqual(("codex_auth",), b.egress.routes[0].Role)
 
     def test_claude_role_rejected_for_codex_provider(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _provider_bottle("codex", [{
                 "host": "api.anthropic.com",
                 "role": "claude_code_oauth",
@@ -207,7 +206,7 @@ class TestRole(unittest.TestCase):
             }])
 
     def test_codex_role_rejected_for_default_claude_provider(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{
                 "host": "api.openai.com",
                 "role": "codex_auth",
@@ -239,32 +238,32 @@ class TestPipelockPolicy(unittest.TestCase):
         self.assertEqual((), b.egress.routes[0].Pipelock.SsrfIpAllowlist)
 
     def test_pipelock_policy_must_be_object(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{"host": "x.example", "pipelock": True}])
 
     def test_tls_passthrough_must_be_bool(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{
                 "host": "x.example",
                 "pipelock": {"tls_passthrough": "yes"},
             }])
 
     def test_ssrf_ip_allowlist_must_be_array(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{
                 "host": "x.example",
                 "pipelock": {"ssrf_ip_allowlist": "100.78.141.42/32"},
             }])
 
     def test_ssrf_ip_allowlist_items_must_be_cidr_or_ip(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{
                 "host": "x.example",
                 "pipelock": {"ssrf_ip_allowlist": ["not-an-ip"]},
             }])
 
     def test_unknown_pipelock_key_rejected(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([{"host": "x.example", "pipelock": {"wat": True}}])
 
 
@@ -273,14 +272,14 @@ class TestRouteValidation(unittest.TestCase):
         # Routes match by exact host; duplicates leave the choice
         # ambiguous, so we reject them up front rather than picking
         # the first/last silently.
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([
                 {"host": "github.com"},
                 {"host": "github.com", "path_allowlist": ["/x/"]},
             ])
 
     def test_duplicate_host_case_insensitive(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             _bottle([
                 {"host": "GitHub.com"},
                 {"host": "github.com"},
@@ -301,7 +300,7 @@ class TestRouteValidation(unittest.TestCase):
 
 class TestConfigShape(unittest.TestCase):
     def test_unknown_egress_key_rejected(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj({
                 "bottles": {"dev": {"egress": {"wat": []}}},
                 "agents": {"demo": {"skills": [], "prompt": "",

tests/unit/test_manifest_extends.py

@@ -10,22 +10,18 @@ it here covers both."""
 
 from __future__ import annotations
 
-import contextlib
-import io
 import unittest
 
-from bot_bottle.log import Die
-from bot_bottle.manifest import Manifest
+from bot_bottle.manifest import ManifestError, Manifest
 
 
-def _die_message(callable_, *args, **kwargs) -> str:
-    buf = io.StringIO()
-    with contextlib.redirect_stderr(buf):
-        try:
-            callable_(*args, **kwargs)
-        except Die:
-            return buf.getvalue()
-    raise AssertionError("expected Die was not raised")
+def _error_message(callable_, *args, **kwargs) -> str:
+    """Run `callable_` expecting a ManifestError; return its message."""
+    try:
+        callable_(*args, **kwargs)
+    except ManifestError as e:
+        return str(e)
+    raise AssertionError("expected ManifestError was not raised")
 
 
 def _build(**bottles) -> Manifest:
@@ -295,16 +291,16 @@ class TestExtendsChain(unittest.TestCase):
 
 class TestExtendsErrors(unittest.TestCase):
     def test_missing_parent_dies(self):
-        msg = _die_message(_build, child={"extends": "ghost"})
+        msg = _error_message(_build, child={"extends": "ghost"})
         self.assertIn("extends 'ghost'", msg)
         self.assertIn("not defined", msg)
 
     def test_self_extends_dies(self):
-        msg = _die_message(_build, loop={"extends": "loop"})
+        msg = _error_message(_build, loop={"extends": "loop"})
         self.assertIn("extends itself", msg)
 
     def test_two_node_cycle_dies(self):
-        msg = _die_message(
+        msg = _error_message(
             _build,
             a={"extends": "b"},
             b={"extends": "a"},
@@ -315,7 +311,7 @@ class TestExtendsErrors(unittest.TestCase):
         self.assertIn("b", msg)
 
     def test_three_node_cycle_dies(self):
-        msg = _die_message(
+        msg = _error_message(
             _build,
             a={"extends": "b"},
             b={"extends": "c"},
@@ -324,7 +320,7 @@ class TestExtendsErrors(unittest.TestCase):
         self.assertIn("extends cycle", msg)
 
     def test_non_string_extends_dies(self):
-        msg = _die_message(_build, child={"extends": ["base"]})
+        msg = _error_message(_build, child={"extends": ["base"]})
         self.assertIn("extends must be a string", msg)
 
 

tests/unit/test_manifest_git.py

@@ -2,8 +2,7 @@
 
 import unittest
 
-from bot_bottle.log import Die
-from bot_bottle.manifest import Manifest
+from bot_bottle.manifest import ManifestError, Manifest
 
 
 def _manifest(git_entries):
@@ -63,28 +62,28 @@ class TestGitEntryParsing(unittest.TestCase):
         self.assertEqual("", m.bottles["dev"].git[0].KnownHostKey)
 
     def test_missing_name_dies(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj(_manifest([{
                 "Upstream": "ssh://git@github.com/foo.git",
                 "IdentityFile": "/dev/null",
             }]))
 
     def test_missing_upstream_dies(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj(_manifest([{
                 "Name": "foo",
                 "IdentityFile": "/dev/null",
             }]))
 
     def test_missing_identity_file_dies(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj(_manifest([{
                 "Name": "foo",
                 "Upstream": "ssh://git@github.com/foo.git",
             }]))
 
     def test_non_ssh_upstream_dies(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj(_manifest([{
                 "Name": "foo",
                 "Upstream": "https://github.com/didericis/foo.git",
@@ -94,7 +93,7 @@ class TestGitEntryParsing(unittest.TestCase):
     def test_scp_style_upstream_dies(self):
         # SCP-style "git@host:path" is intentionally not supported in
         # v1 — ssh:// only.
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj(_manifest([{
                 "Name": "foo",
                 "Upstream": "git@github.com:didericis/foo.git",
@@ -102,7 +101,7 @@ class TestGitEntryParsing(unittest.TestCase):
             }]))
 
     def test_upstream_without_user_dies(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj(_manifest([{
                 "Name": "foo",
                 "Upstream": "ssh://github.com/foo.git",
@@ -110,7 +109,7 @@ class TestGitEntryParsing(unittest.TestCase):
             }]))
 
     def test_upstream_without_path_dies(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj(_manifest([{
                 "Name": "foo",
                 "Upstream": "ssh://git@github.com",
@@ -118,7 +117,7 @@ class TestGitEntryParsing(unittest.TestCase):
             }]))
 
     def test_non_numeric_port_dies(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj(_manifest([{
                 "Name": "foo",
                 "Upstream": "ssh://git@github.com:notaport/foo.git",
@@ -146,7 +145,7 @@ class TestGitEntryExtraHosts(unittest.TestCase):
         self.assertEqual({"gitea.dideric.is": "100.78.141.42"}, eh)
 
     def test_extra_hosts_must_be_object(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj(_manifest([{
                 "Name": "foo",
                 "Upstream": "ssh://git@github.com/foo.git",
@@ -155,7 +154,7 @@ class TestGitEntryExtraHosts(unittest.TestCase):
             }]))
 
     def test_extra_hosts_ip_must_be_string(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj(_manifest([{
                 "Name": "foo",
                 "Upstream": "ssh://git@github.com/foo.git",
@@ -164,7 +163,7 @@ class TestGitEntryExtraHosts(unittest.TestCase):
             }]))
 
     def test_extra_hosts_empty_ip_dies(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj(_manifest([{
                 "Name": "foo",
                 "Upstream": "ssh://git@github.com/foo.git",
@@ -175,7 +174,7 @@ class TestGitEntryExtraHosts(unittest.TestCase):
 
 class TestGitEntryCrossValidation(unittest.TestCase):
     def test_duplicate_name_dies(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj({
                 "bottles": {"dev": {"git": {"remotes": {
                     "a.example": {
@@ -193,7 +192,7 @@ class TestGitEntryCrossValidation(unittest.TestCase):
             })
 
     def test_remote_key_must_match_upstream_host(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj({
                 "bottles": {"dev": {"git": {"remotes": {
                     "wrong.example": {
@@ -224,7 +223,7 @@ class TestGitEntryCrossValidation(unittest.TestCase):
     def test_legacy_ssh_field_dies_with_hint(self):
         # PRD 0009: bottle.ssh is removed; manifests carrying it must
         # fail loudly with a hint pointing at bottle.git.
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj({
                 "bottles": {
                     "dev": {
@@ -250,7 +249,7 @@ class TestEmptyGitField(unittest.TestCase):
         self.assertEqual((), m.bottles["dev"].git)
 
     def test_git_object_type_required(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             Manifest.from_json_obj({
                 "bottles": {"dev": {"git": "not-a-list"}},
                 "agents": {"demo": {"skills": [], "prompt": "", "bottle": "dev"}},

tests/unit/test_manifest_git_user.py

@@ -1,25 +1,17 @@
 """Unit: Bottle git.user manifest parsing + validation (issue #86)."""
 
-import contextlib
-import io
 import unittest
 
-from bot_bottle.log import Die
-from bot_bottle.manifest import GitUser, Manifest
+from bot_bottle.manifest import ManifestError, GitUser, Manifest
 
 
-def _die_message(callable_, *args, **kwargs) -> str:
-    """Run `callable_` expecting it to die, return the stderr text
-    so tests can assert specifics. `die()` prints to stderr then
-    raises Die(1) — the exit code is in the exception, the human
-    message is in stderr."""
-    buf = io.StringIO()
-    with contextlib.redirect_stderr(buf):
-        try:
-            callable_(*args, **kwargs)
-        except Die:
-            return buf.getvalue()
-    raise AssertionError("expected Die was not raised")
+def _error_message(callable_, *args, **kwargs) -> str:
+    """Run `callable_` expecting a ManifestError; return its message."""
+    try:
+        callable_(*args, **kwargs)
+    except ManifestError as e:
+        return str(e)
+    raise AssertionError("expected ManifestError was not raised")
 
 
 def _manifest(git_user):
@@ -66,13 +58,13 @@ class TestGitUserParsing(unittest.TestCase):
         # An explicit `git.user: {name: "", email: ""}` is a typo
         # /  half-finished edit; fail loudly rather than silently
         # no-op (the operator clearly meant to configure something).
-        msg = _die_message(
+        msg = _error_message(
             Manifest.from_json_obj, _manifest({"name": "", "email": ""}),
         )
         self.assertIn("neither name nor email", msg)
 
     def test_unknown_key_dies(self):
-        msg = _die_message(
+        msg = _error_message(
             Manifest.from_json_obj,
             _manifest({"name": "Bot", "username": "bot"}),
         )
@@ -80,19 +72,19 @@ class TestGitUserParsing(unittest.TestCase):
         self.assertIn("username", msg)
 
     def test_non_string_name_dies(self):
-        msg = _die_message(
+        msg = _error_message(
             Manifest.from_json_obj, _manifest({"name": 42}),
         )
         self.assertIn("git.user.name must be a string", msg)
 
     def test_non_string_email_dies(self):
-        msg = _die_message(
+        msg = _error_message(
             Manifest.from_json_obj, _manifest({"email": ["x@y.z"]}),
         )
         self.assertIn("git.user.email must be a string", msg)
 
     def test_legacy_top_level_git_user_dies(self):
-        msg = _die_message(
+        msg = _error_message(
             Manifest.from_json_obj,
             {
                 "bottles": {"dev": {"git_user": {"name": "Bot"}}},

tests/unit/test_manifest_md_load.py

@@ -11,8 +11,7 @@ import textwrap
 import unittest
 from pathlib import Path
 
-from bot_bottle.log import Die
-from bot_bottle.manifest import Manifest
+from bot_bottle.manifest import ManifestError, Manifest
 
 
 def _write(p: Path, text: str) -> None:
@@ -238,7 +237,7 @@ class TestUnknownAgentKeyDies(_ResolveCase):
             ...
             """,
         )
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             self.resolve()
 
 
@@ -257,7 +256,7 @@ class TestUnknownBottleKeyDies(_ResolveCase):
             """,
         )
         _write(self.home_cb / "agents" / "implementer.md", _AGENT_IMPL)
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             self.resolve()
 
 
@@ -268,7 +267,7 @@ class TestStaleJsonDies(_ResolveCase):
 
     def test_dies(self):
         (self.home_root / "bot-bottle.json").write_text('{"bottles": {}}')
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             self.resolve()
 
 
@@ -277,7 +276,7 @@ class TestNoManifestDies(_ResolveCase):
     pointer at the new layout."""
 
     def test_dies(self):
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             self.resolve()
 
     def test_missing_ok_returns_empty_manifest(self):
@@ -300,7 +299,7 @@ class TestUnknownBottleReferenceDies(_ResolveCase):
             ---
             """,
         )
-        with self.assertRaises(Die):
+        with self.assertRaises(ManifestError):
             self.resolve()
 
 

tests/unit/test_manifest_runtime.py

@@ -7,8 +7,7 @@ silently ignoring."""
 import unittest
 from typing import Any
 
-from bot_bottle.log import Die
-from bot_bottle.manifest import Bottle, Manifest
+from bot_bottle.manifest import ManifestError, Bottle, Manifest
 
 
 def _manifest_with_runtime(value: object) -> dict[str, Any]:
@@ -32,7 +31,7 @@ class TestManifestRuntimeRemoved(unittest.TestCase):
     def test_any_runtime_value_is_rejected(self):
         for value in ("runsc", "runc", "kata-runtime", "", 42, None):
             with self.subTest(value=value):
-                with self.assertRaises(Die):
+                with self.assertRaises(ManifestError):
                     Manifest.from_json_obj(_manifest_with_runtime(value))