feat: expose stable Python API for programmatic bottle orchestration

Add bot_bottle/api.py with four public functions the orchestrator uses:
start_headless, resume_headless, freeze, and destroy. These let a
ProgrammaticBottleRunner call directly into bot_bottle instead of
shelling out to the CLI; call sites in lifecycle.py stay unchanged.

Key changes:
- BottleSpec gains forge_env field for forge sidecar credentials
- _launch_bottle returns (slug, exit_code) instead of int so start_headless
  can return the slug to callers
- All four API functions convert Die and non-zero exits to BottleError
- 27 new unit tests; existing tests updated for the new return type

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

tests/unit/test_cli_start_selector.py

@@ -45,7 +45,7 @@ class TestCmdStartSelector(unittest.TestCase):
 
         self._launch_patch = patch(
             "bot_bottle.cli.start._launch_bottle",
-            return_value=0,
+            return_value=("", 0),
         )
         self._launch_mock = self._launch_patch.start()
 
@@ -211,7 +211,7 @@ class TestCmdStartLabelCollision(unittest.TestCase):
         self._manifest = _make_manifest(["researcher"], ["claude"])
         patch("bot_bottle.cli.start.ManifestIndex.resolve", return_value=self._manifest).start()
         self._launch_mock = patch(
-            "bot_bottle.cli.start._launch_bottle", return_value=0,
+            "bot_bottle.cli.start._launch_bottle", return_value=("", 0),
         ).start()
         # Stub the bottle picker to always return a selection.
         patch.object(tui_mod, "filter_multiselect", return_value=["claude"]).start()