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_resume_headless.py

@@ -29,7 +29,7 @@ def _metadata():
 class ResumeHeadlessTest(unittest.TestCase):
     def setUp(self) -> None:
         self._launch = patch.object(
-            resume_mod, "_launch_bottle", return_value=0
+            resume_mod, "_launch_bottle", return_value=("implementer-abc12", 0)
         ).start()
         patch.object(
             resume_mod, "read_metadata", return_value=_metadata()