feat(box): add box.enabled toggle and gate consumers on availability

Make the Box sandbox runtime optional. When ``box.enabled`` is false in
config (or when an enabled Box fails to connect), every dependent feature
degrades to the same disabled-state UX rather than crashing or silently
falling back to less safe code paths.

Backend:

- config.yaml: new top-level ``box.enabled: true`` flag (default true)
- BoxService:
  - Read box.enabled on construction
  - initialize() short-circuits when disabled — no remote WS connect, no
    stdio subprocess fork
  - _on_runtime_disconnect is a no-op when disabled (no reconnect loop
    on a deliberately-off service)
  - get_status() now exposes ``enabled`` so the frontend can tell
    "disabled in config" from "configured but failed"
- MCP stdio loader (mcp_stdio.uses_box_stdio): requires box_service to
  be available, not just installed
- MCP _init_stdio_python_server: when ap.box_service exists but is
  unavailable, refuse the stdio server with an actionable error instead
  of silently falling through to host-stdio (which bypasses the sandbox
  the operator asked for). Setups without ap.box_service installed at
  all keep the legacy host-stdio fallback for pre-Box dev mode
- SkillService._require_box_for_write: refuses create/update/install/
  write_skill_file when ap.box_service is installed but unavailable.
  Distinguishes disabled vs failed in the error message so the UI can
  surface the right hint. Legacy setups (no ap.box_service) keep the
  local fallback path — that distinction is what keeps the existing
  local-skills tests valid

Tests:
- Box disabled-state behavior (4 cases)
- Skill write refusal in disabled & failed states (7 cases)
- MCP stdio runtime info policy updated to match new refuse-when-down
  behavior

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

tests/unit_tests/box/test_box_service.py

@@ -152,8 +152,10 @@ def make_app(
     profile: str = 'default',
     host_root: str = '',
     workspace_quota_mb: int | None = None,
+    enabled: bool = True,
 ):
     box_config = {
+        'enabled': enabled,
         'backend': 'local',
         'runtime': {'endpoint': ''},
         'local': {
@@ -1225,6 +1227,65 @@ class TestBoxHostMountModeNone:
             )
 
 
+class TestBoxDisabledByConfig:
+    """``box.enabled = false`` must keep the BoxService usable as a status
+    surface but skip every connection attempt and report unavailable."""
+
+    @pytest.mark.asyncio
+    async def test_initialize_skips_connector_when_disabled(self):
+        logger = Mock()
+        app = make_app(logger, enabled=False)
+        client = Mock(spec=BoxRuntimeClient)
+        client.initialize = AsyncMock()
+        service = BoxService(app, client=client)
+
+        await service.initialize()
+
+        # The client must not be touched; we did not even open a connection.
+        client.initialize.assert_not_awaited()
+        assert service.enabled is False
+        assert service.available is False
+        # The reason is captured so the dashboard / UI can show it.
+        assert 'disabled' in service._connector_error.lower()
+
+    @pytest.mark.asyncio
+    async def test_get_status_reports_disabled(self):
+        logger = Mock()
+        service = BoxService(make_app(logger, enabled=False), client=Mock(spec=BoxRuntimeClient))
+        await service.initialize()
+
+        status = await service.get_status()
+
+        assert status['available'] is False
+        assert status['enabled'] is False
+        assert 'disabled' in status['connector_error'].lower()
+
+    @pytest.mark.asyncio
+    async def test_get_status_distinguishes_enabled_but_unavailable(self):
+        logger = Mock()
+        client = Mock(spec=BoxRuntimeClient)
+        client.initialize = AsyncMock(side_effect=RuntimeError('docker daemon not running'))
+        service = BoxService(make_app(logger, enabled=True), client=client)
+
+        await service.initialize()
+
+        status = await service.get_status()
+        assert status['available'] is False
+        assert status['enabled'] is True
+        assert 'docker daemon' in status['connector_error']
+
+    @pytest.mark.asyncio
+    async def test_disconnect_callback_is_no_op_when_disabled(self):
+        logger = Mock()
+        service = BoxService(make_app(logger, enabled=False), client=Mock(spec=BoxRuntimeClient))
+
+        # Should be safe to fire; must not flip reconnect state on a disabled
+        # service. If it tried to schedule a reconnect, the test would hang.
+        await service._on_runtime_disconnect(connector=Mock())
+
+        assert service._reconnecting is False
+
+
 class TestBuildSkillExtraMounts:
     """Robustness of skill mount construction against a stale skill cache.
 

tests/unit_tests/provider/test_mcp_box_integration.py

@@ -561,7 +561,12 @@ class TestGetRuntimeInfoDict:
         assert info['box_session_id'] == 'mcp-shared'
         assert info['box_enabled'] is True
 
-    def test_stdio_session_waits_for_unavailable_box_runtime(self, mcp_module):
+    def test_stdio_session_refuses_when_box_unavailable(self, mcp_module):
+        """Policy: when Box is configured but unavailable (disabled in config
+        OR connection failed), stdio MCP servers are NOT treated as box-stdio.
+        ``_init_stdio_python_server`` will raise a clear refusal at start
+        time; until then, the runtime info simply omits box_session_id so the
+        UI can render the disabled state cleanly."""
         ap = _make_ap()
         ap.box_service.available = False
         s = _make_session(
@@ -576,8 +581,8 @@ class TestGetRuntimeInfoDict:
             ap=ap,
         )
         info = s.get_runtime_info_dict()
-        assert info['box_session_id'] == 'mcp-shared'
-        assert info['box_enabled'] is True
+        assert 'box_session_id' not in info
+        assert 'box_enabled' not in info
 
     def test_stdio_session_without_box_service_uses_local_stdio(self, mcp_module):
         ap = _make_ap()

tests/unit_tests/test_skill_service.py

@@ -72,6 +72,90 @@ def test_scan_directory_errors_when_skill_is_deeper_than_two_levels(skill_servic
         skill_service.scan_directory(str(tmp_path))
 
 
+class TestRequireBoxForWrite:
+    """Writes must refuse when ``ap.box_service`` is installed but unavailable
+    (disabled in config OR connection failed). Legacy setups without
+    ``ap.box_service`` continue to use the local fallback."""
+
+    def _ap_with_disabled_box(self):
+        return SimpleNamespace(
+            skill_mgr=SimpleNamespace(reload_skills=AsyncMock()),
+            box_service=SimpleNamespace(
+                available=False,
+                enabled=False,
+                _connector_error='Box runtime is disabled in config (box.enabled = false)',
+            ),
+        )
+
+    def _ap_with_failed_box(self):
+        return SimpleNamespace(
+            skill_mgr=SimpleNamespace(reload_skills=AsyncMock()),
+            box_service=SimpleNamespace(
+                available=False,
+                enabled=True,
+                _connector_error='docker daemon not running',
+            ),
+        )
+
+    @pytest.mark.asyncio
+    async def test_create_skill_refused_when_box_disabled(self):
+        service = SkillService(self._ap_with_disabled_box())
+        with pytest.raises(ValueError, match='disabled in config'):
+            await service.create_skill({'name': 'x'})
+
+    @pytest.mark.asyncio
+    async def test_create_skill_refused_when_box_failed(self):
+        service = SkillService(self._ap_with_failed_box())
+        with pytest.raises(ValueError, match='docker daemon not running'):
+            await service.create_skill({'name': 'x'})
+
+    @pytest.mark.asyncio
+    async def test_update_skill_refused_when_box_disabled(self):
+        service = SkillService(self._ap_with_disabled_box())
+        with pytest.raises(ValueError, match='Editing a skill requires the Box runtime'):
+            await service.update_skill('x', {})
+
+    @pytest.mark.asyncio
+    async def test_write_skill_file_refused_when_box_disabled(self):
+        service = SkillService(self._ap_with_disabled_box())
+        with pytest.raises(ValueError, match='Editing skill files requires the Box runtime'):
+            await service.write_skill_file('x', 'a.txt', 'hi')
+
+    @pytest.mark.asyncio
+    async def test_install_from_github_refused_when_box_disabled(self):
+        service = SkillService(self._ap_with_disabled_box())
+        with pytest.raises(ValueError, match='Installing a skill from GitHub'):
+            await service.install_from_github({'owner': 'o', 'repo': 'r', 'asset_url': 'https://example/x.zip'})
+
+    @pytest.mark.asyncio
+    async def test_install_from_zip_upload_refused_when_box_disabled(self):
+        service = SkillService(self._ap_with_disabled_box())
+        with pytest.raises(ValueError, match='Installing a skill from upload'):
+            await service.install_from_zip_upload(file_bytes=b'', filename='x.zip')
+
+    @pytest.mark.asyncio
+    async def test_legacy_setup_without_box_service_still_allows_local_create(self, tmp_path, monkeypatch):
+        """Setups that never installed ap.box_service (pre-Box dev mode) keep
+        using the local-skills fallback path — that's the whole point of the
+        ``getattr`` distinguisher in _require_box_for_write."""
+        monkeypatch.setenv('LANGBOT_DATA_ROOT', str(tmp_path / 'data'))
+        service = SkillService(SimpleNamespace(skill_mgr=SimpleNamespace(reload_skills=AsyncMock())))
+        service.get_skill_by_name = AsyncMock(return_value=None)
+        service.get_skill = AsyncMock(
+            return_value={
+                'name': 'local-skill',
+                'package_root': str(tmp_path / 'data' / 'skills' / 'local-skill'),
+                'description': '',
+                'instructions': '',
+            }
+        )
+
+        # Does not raise — gate is a no-op without ap.box_service.
+        await service.create_skill(
+            {'name': 'local-skill', 'display_name': 'Local', 'description': '', 'instructions': 'hi'}
+        )
+
+
 @pytest.mark.asyncio
 async def test_create_skill_import_preserves_existing_skill_content_when_form_fields_blank(tmp_path, monkeypatch):
     source_dir = tmp_path / 'external-skills' / 'manual-skill'