feat: add macos container backend scaffold

tests/unit/test_backend_selection.py

@@ -44,8 +44,11 @@ class TestGetBottleBackend(unittest.TestCase):
 
 
 class TestKnownBackendNames(unittest.TestCase):
-    def test_returns_both_backends_sorted(self):
-        self.assertEqual(("docker", "smolmachines"), known_backend_names())
+    def test_returns_backends_sorted(self):
+        self.assertEqual(
+            ("docker", "macos-container", "smolmachines"),
+            known_backend_names(),
+        )
 
 
 class TestEnumerateActiveAgents(unittest.TestCase):

tests/unit/test_macos_container_bottle.py

@@ -0,0 +1,71 @@
+"""Unit: Apple Container bottle command construction."""
+
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from bot_bottle.backend.macos_container.bottle import MacosContainerBottle
+
+
+class TestMacosContainerBottle(unittest.TestCase):
+    def test_agent_argv_uses_container_exec(self):
+        bottle = MacosContainerBottle(
+            "bot-bottle-dev-abc",
+            lambda: None,
+            None,
+            agent_command="codex",
+        )
+        self.assertEqual(
+            [
+                "container", "exec", "--interactive", "--tty",
+                "bot-bottle-dev-abc", "codex", "run",
+            ],
+            bottle.agent_argv(["run"]),
+        )
+
+    def test_agent_argv_includes_workdir(self):
+        bottle = MacosContainerBottle(
+            "bot-bottle-dev-abc",
+            lambda: None,
+            None,
+            agent_workdir="/home/node/workspace",
+        )
+        self.assertEqual(
+            [
+                "container", "exec", "--interactive", "--tty",
+                "--workdir", "/home/node/workspace",
+                "bot-bottle-dev-abc", "claude",
+            ],
+            bottle.agent_argv([]),
+        )
+
+    def test_exec_pipes_script_to_shell(self):
+        bottle = MacosContainerBottle("bot-bottle-dev-abc", lambda: None, None)
+        with patch("bot_bottle.backend.macos_container.bottle.subprocess.run") as run:
+            run.return_value.returncode = 7
+            run.return_value.stdout = "out"
+            run.return_value.stderr = "err"
+            result = bottle.exec("echo hi", user="root")
+        self.assertEqual(7, result.returncode)
+        self.assertEqual(
+            [
+                "container", "exec", "--user", "root", "--interactive",
+                "bot-bottle-dev-abc", "sh", "-s",
+            ],
+            run.call_args.args[0],
+        )
+        self.assertEqual("echo hi", run.call_args.kwargs["input"])
+
+    def test_cp_in_uses_container_cp(self):
+        bottle = MacosContainerBottle("bot-bottle-dev-abc", lambda: None, None)
+        with patch("bot_bottle.backend.macos_container.bottle.subprocess.run") as run:
+            bottle.cp_in("/tmp/src", "/home/node/src")
+        self.assertEqual(
+            ["container", "cp", "/tmp/src", "bot-bottle-dev-abc:/home/node/src"],
+            run.call_args.args[0],
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_macos_container_cleanup.py

@@ -0,0 +1,67 @@
+"""Unit: Apple Container cleanup/enumeration helpers."""
+
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from bot_bottle.backend.macos_container import cleanup, enumerate as enum_mod
+from bot_bottle.backend.macos_container.bottle_cleanup_plan import (
+    MacosContainerBottleCleanupPlan,
+)
+
+
+class TestMacosContainerCleanup(unittest.TestCase):
+    def test_lists_prefixed_containers(self):
+        completed = cleanup.subprocess.CompletedProcess(
+            args=[],
+            returncode=0,
+            stdout="bot-bottle-a\nbot-bottle-sidecars-a\nother\n",
+            stderr="",
+        )
+        with patch.object(cleanup.subprocess, "run", return_value=completed):
+            self.assertEqual(
+                ["bot-bottle-a", "bot-bottle-sidecars-a"],
+                cleanup._list_prefixed_containers(),
+            )
+
+    def test_cleanup_deletes_containers_and_networks(self):
+        plan = MacosContainerBottleCleanupPlan(
+            containers=("bot-bottle-a",),
+            networks=("bot-bottle-net-a",),
+        )
+        with patch.object(cleanup.subprocess, "run") as run:
+            cleanup.cleanup(plan)
+        self.assertEqual(
+            ["container", "delete", "--force", "bot-bottle-a"],
+            run.call_args_list[0].args[0],
+        )
+        self.assertEqual(
+            ["container", "network", "delete", "bot-bottle-net-a"],
+            run.call_args_list[1].args[0],
+        )
+
+
+class TestMacosContainerEnumerate(unittest.TestCase):
+    def test_enumerate_active_reads_metadata(self):
+        completed = enum_mod.subprocess.CompletedProcess(
+            args=[], returncode=0, stdout="bot-bottle-a\nother\n", stderr="",
+        )
+
+        class _Metadata:
+            agent_name = "impl"
+            started_at = "2026-06-10T00:00:00Z"
+            label = "Implement"
+            color = "blue"
+
+        with patch.object(enum_mod.subprocess, "run", return_value=completed), \
+             patch.object(enum_mod, "read_metadata", return_value=_Metadata()):
+            agents = enum_mod.enumerate_active()
+        self.assertEqual(1, len(agents))
+        self.assertEqual("macos-container", agents[0].backend_name)
+        self.assertEqual("a", agents[0].slug)
+        self.assertEqual("impl", agents[0].agent_name)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_macos_container_util.py

@@ -0,0 +1,60 @@
+"""Unit: Apple Container utility helpers."""
+
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from bot_bottle.backend.macos_container import util
+
+
+class TestMacosContainerAvailability(unittest.TestCase):
+    def test_available_only_on_macos_with_container(self):
+        with patch.object(util.platform, "system", return_value="Darwin"), \
+             patch.object(util.shutil, "which", return_value="/usr/local/bin/container"):
+            self.assertTrue(util.is_available())
+
+    def test_not_available_off_macos(self):
+        with patch.object(util.platform, "system", return_value="Linux"), \
+             patch.object(util.shutil, "which", return_value="/usr/local/bin/container"):
+            self.assertFalse(util.is_available())
+
+    def test_require_container_dies_when_missing(self):
+        with patch.object(util.platform, "system", return_value="Darwin"), \
+             patch.object(util.shutil, "which", return_value=None), \
+             patch.object(util, "die", side_effect=SystemExit("die")):
+            with self.assertRaises(SystemExit):
+                util.require_container()
+
+
+class TestMacosContainerCommands(unittest.TestCase):
+    def test_build_image(self):
+        with patch.object(util.subprocess, "run") as run:
+            util.build_image("bot-bottle-agent:latest", "/repo", dockerfile="/repo/Dockerfile")
+        self.assertEqual(
+            [
+                "container", "build", "-t", "bot-bottle-agent:latest",
+                "-f", "/repo/Dockerfile", "/repo",
+            ],
+            run.call_args.args[0],
+        )
+        self.assertTrue(run.call_args.kwargs["check"])
+
+    def test_container_exists_parses_quiet_list(self):
+        completed = util.subprocess.CompletedProcess(
+            args=[], returncode=0, stdout="bot-bottle-a\nother\n", stderr="",
+        )
+        with patch.object(util.subprocess, "run", return_value=completed):
+            self.assertTrue(util.container_exists("bot-bottle-a"))
+            self.assertFalse(util.container_exists("bot-bottle-b"))
+
+    def test_image_id_reads_json_digest(self):
+        completed = util.subprocess.CompletedProcess(
+            args=[], returncode=0, stdout='{"digest":"sha256:abc"}', stderr="",
+        )
+        with patch.object(util.subprocess, "run", return_value=completed):
+            self.assertEqual("sha256:abc", util.image_id("demo:latest"))
+
+
+if __name__ == "__main__":
+    unittest.main()