refactor(bottle): finish bottle package move

Add tests for all exception paths (Die/ManifestError from resolve, Die
from _launch_bottle, Die from freezer) plus the macos-container
fall-through branch in destroy. Add TestDestroyDocker and
TestDestroySmolmachines to exercise the backend helpers directly.

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

Dockerfile.sidecars

@@ -18,7 +18,7 @@
 #   /git-gate-entrypoint.sh              docker-cp'd at start time
 #   /git-gate/creds/*                    docker-cp'd at start time
 #   /git/*                               bare repos, populated at runtime
-#   /run/supervise/queue/                bind-mounted at run time
+#   /run/supervise/bot-bottle.db         bind-mounted at run time
 #   /home/mitmproxy/.mitmproxy/          mitmproxy CA dir
 #
 # Exposed ports inside the container:
@@ -66,6 +66,12 @@ COPY bot_bottle/egress_dlp_config.py /app/egress_dlp_config.py
 COPY bot_bottle/egress_addon.py      /app/egress_addon.py
 COPY bot_bottle/dlp_detectors.py     /app/dlp_detectors.py
 COPY bot_bottle/yaml_subset.py       /app/yaml_subset.py
+COPY bot_bottle/migrations.py        /app/migrations.py
+COPY bot_bottle/db_store.py          /app/db_store.py
+COPY bot_bottle/supervise_types.py   /app/supervise_types.py
+COPY bot_bottle/queue_store.py       /app/queue_store.py
+COPY bot_bottle/audit_store.py       /app/audit_store.py
+COPY bot_bottle/store_manager.py     /app/store_manager.py
 COPY bot_bottle/supervise.py         /app/supervise.py
 COPY bot_bottle/supervise_server.py  /app/supervise_server.py
 COPY bot_bottle/sidecar_init.py      /app/sidecar_init.py
@@ -81,7 +87,7 @@ RUN mkdir -p \
       /etc/git-gate \
       /git-gate/creds \
       /git \
-      /run/supervise/queue \
+      /run/supervise \
       /home/mitmproxy/.mitmproxy
 
 # Documentation only — the compose renderer publishes whichever

README.md

@@ -5,8 +5,8 @@
 # bot-bottle
 
 [![test](https://gitea.dideric.is/didericis/bot-bottle/actions/workflows/test.yml/badge.svg?branch=main)](https://gitea.dideric.is/didericis/bot-bottle/actions?workflow=test.yml)
-[![coverage](https://img.shields.io/badge/coverage-84%25-brightgreen)](https://coverage.readthedocs.io/)
-[![core coverage](https://img.shields.io/badge/core%20coverage-96%25-brightgreen)](https://gitea.dideric.is/didericis/bot-bottle/src/branch/main/docs/decisions/0004-coverage-policy.md)
+[![coverage](https://img.shields.io/badge/coverage-83%25-brightgreen)](https://coverage.readthedocs.io/)
+[![core coverage](https://img.shields.io/badge/core%20coverage-95%25-brightgreen)](https://gitea.dideric.is/didericis/bot-bottle/src/branch/main/docs/decisions/0004-coverage-policy.md)
 
 **Problem:** Developer wants to run a coding agent without supervision, but they don't want a prompt injected or misbehaving agent wrecking their environment or exfiltrating sensitive data.
 

bot_bottle/__init__.py

@@ -1 +1,11 @@
 """bot-bottle: Python implementation of the agent container launcher."""
+
+from .bottle import BottleError, destroy, freeze, resume_headless, start_headless
+
+__all__ = [
+    "BottleError",
+    "destroy",
+    "freeze",
+    "resume_headless",
+    "start_headless",
+]

bot_bottle/agent_provider.py

@@ -209,6 +209,15 @@ class AgentProvider(ABC):
         the supervise sidecar is reachable. No-op when
         `plan.supervise_plan is None`."""
 
+    @abstractmethod
+    def headless_prompt(self, prompt: str) -> list[str]:
+        """Return the agent CLI args that deliver `prompt` as the
+        initial task in a non-interactive (headless) session.
+
+        Called only when ``--prompt`` is passed to
+        ``./cli.py start --headless``; the returned args are appended
+        after the provider's ``bypass_args`` and ``startup_args``."""
+
     def provision_ca(self, bottle: "Bottle", plan: "BottlePlan") -> None:
         """Install the egress MITM CA into the agent's trust store.
 

bot_bottle/api.py

@@ -0,0 +1,14 @@
+"""Compatibility wrapper for the public bottle runner API.
+
+The implementation lives in :mod:`bot_bottle.bottle.runner`.
+"""
+
+from .bottle.runner import BottleError, destroy, freeze, resume_headless, start_headless
+
+__all__ = [
+    "BottleError",
+    "destroy",
+    "freeze",
+    "resume_headless",
+    "start_headless",
+]

bot_bottle/audit_store.py

@@ -0,0 +1,91 @@
+"""SQLite-backed audit store for supervise (PRD 0013)."""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+try:
+    from .supervise_types import AuditEntry, host_db_path
+    from .db_store import DbStore
+    from .migrations import TableMigrations
+except ImportError:
+    from supervise_types import AuditEntry, host_db_path  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from db_store import DbStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from migrations import TableMigrations  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+
+
+class AuditStore(DbStore):
+    """SQLite-backed persistent store for supervise audit entries."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        # One entry per schema version: migrations[0] brings a fresh DB to
+        # version 1, [1] to version 2, etc.  Add new entries at the end; never
+        # edit existing ones.
+        migrations = TableMigrations("audit_store", [
+            # v1 — initial schema
+            """
+            CREATE TABLE IF NOT EXISTS supervise_audit_entries (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                timestamp TEXT NOT NULL,
+                bottle_slug TEXT NOT NULL,
+                component TEXT NOT NULL,
+                operator_action TEXT NOT NULL,
+                operator_notes TEXT NOT NULL,
+                justification TEXT NOT NULL,
+                diff TEXT NOT NULL
+            )
+            """,
+        ])
+        super().__init__(db_path or host_db_path(), migrations)
+
+    def write_audit_entry(self, entry: AuditEntry) -> Path:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO supervise_audit_entries (
+                    timestamp, bottle_slug, component, operator_action,
+                    operator_notes, justification, diff
+                ) VALUES (?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    entry.timestamp,
+                    entry.bottle_slug,
+                    entry.component,
+                    entry.operator_action,
+                    entry.operator_notes,
+                    entry.justification,
+                    entry.diff,
+                ),
+            )
+        self._chmod()
+        return self.db_path
+
+    def read_audit_entries(self, component: str, slug: str) -> list[AuditEntry]:
+        if not self.db_path.is_file():
+            return []
+        with self._connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT * FROM supervise_audit_entries
+                WHERE component = ? AND bottle_slug = ?
+                ORDER BY id
+                """,
+                (component, slug),
+            ).fetchall()
+        return [self._row_to_entry(row) for row in rows]
+
+    @staticmethod
+    def _row_to_entry(row: sqlite3.Row) -> AuditEntry:
+        return AuditEntry(
+            timestamp=row["timestamp"],
+            bottle_slug=row["bottle_slug"],
+            component=row["component"],
+            operator_action=row["operator_action"],
+            operator_notes=row["operator_notes"],
+            justification=row["justification"],
+            diff=row["diff"],
+        )
+
+
+__all__ = ["AuditStore"]

bot_bottle/backend/__init__.py

@@ -37,7 +37,7 @@ import shlex
 import sys
 from abc import ABC, abstractmethod
 from contextlib import AbstractContextManager
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Generic, Sequence, TypeVar
 
@@ -75,6 +75,11 @@ class BottleSpec:
     # Ordered bottle names selected at launch (issue #269). When non-empty
     # they are merged in order and replace the agent's `bottle:` field.
     bottle_names: tuple[str, ...] = ()
+    # Forge sidecar env vars (PRD forge-native-integration, chunk 1).
+    # Passed by the orchestrator at launch time; the forge sidecar reads
+    # them to connect to Gitea. Empty for non-forge runs. The agent
+    # process itself does not receive these.
+    forge_env: dict[str, str] = field(default_factory=dict)
 
 
 @dataclass(frozen=True)

bot_bottle/backend/docker/cleanup.py

@@ -31,7 +31,7 @@ from ... import supervise as _supervise
 from ...log import info, warn
 from . import util as docker_mod
 from .bottle_cleanup_plan import DockerBottleCleanupPlan
-from ...bottle_state import bottle_state_dir, is_preserved
+from ...bottle.state import bottle_state_dir, is_preserved
 from .compose import COMPOSE_PROJECT_PREFIX, list_compose_projects
 
 

bot_bottle/backend/docker/compose.py

@@ -34,7 +34,7 @@ from ...egress import (
 from ...git_gate import GIT_GATE_HOSTNAME
 from ...log import die, warn
 from ...supervise import (
-    QUEUE_DIR_IN_CONTAINER,
+    DB_PATH_IN_CONTAINER,
     SUPERVISE_HOSTNAME,
     SUPERVISE_PORT,
 )
@@ -163,16 +163,15 @@ def _sidecar_bundle_service(plan: DockerBottlePlan) -> dict[str, Any]:
     if sp is not None:
         env += [
             f"SUPERVISE_BOTTLE_SLUG={plan.slug}",
-            f"SUPERVISE_QUEUE_DIR={QUEUE_DIR_IN_CONTAINER}",
+            f"SUPERVISE_DB_PATH={DB_PATH_IN_CONTAINER}",
             f"SUPERVISE_PORT={SUPERVISE_PORT}",
         ]
         volumes.append({
             "type": "bind",
-            "source": str(sp.queue_dir),
-            "target": QUEUE_DIR_IN_CONTAINER,
+            "source": str(sp.db_path),
+            "target": DB_PATH_IN_CONTAINER,
             "read_only": False,
         })
-
     internal_aliases = [EGRESS_HOSTNAME]
     if gp.upstreams:
         internal_aliases.append(GIT_GATE_HOSTNAME)

bot_bottle/backend/docker/enumerate.py

@@ -15,7 +15,7 @@ from __future__ import annotations
 import subprocess
 
 from .. import ActiveAgent
-from ...bottle_state import read_metadata
+from ...bottle.state import read_metadata
 from .compose import compose_project_name, list_active_slugs
 
 

bot_bottle/backend/docker/launch.py

@@ -37,13 +37,16 @@ from pathlib import Path
 from typing import Callable, Generator
 
 from ...egress import egress_resolve_token_values
-from ...git_gate import revoke_git_gate_provisioned_keys
+from ...git_gate import (
+    provision_git_gate_dynamic_keys,
+    revoke_git_gate_provisioned_keys,
+)
 from ...log import info, warn
 from . import network as network_mod
 from . import util as docker_mod
 from .bottle import DockerBottle
 from .bottle_plan import DockerBottlePlan
-from ...bottle_state import (
+from ...bottle.state import (
     bottle_state_dir,
     egress_state_dir,
     git_gate_state_dir,
@@ -118,6 +121,11 @@ def launch(
 
         git_gate_plan = plan.git_gate_plan
         if git_gate_plan.upstreams:
+            git_gate_plan = provision_git_gate_dynamic_keys(
+                plan.manifest.bottle,
+                git_gate_plan,
+                git_gate_state_dir(plan.slug),
+            )
             git_gate_plan = dataclasses.replace(
                 git_gate_plan,
                 internal_network=internal_network,

bot_bottle/backend/egress_apply.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from pathlib import Path
 
-from ..bottle_state import egress_state_dir
+from ..bottle.state import egress_state_dir
 from ..egress import EGRESS_ROUTES_FILENAME
 from ..egress_addon_core import LOG_OFF, load_config
 

bot_bottle/backend/freeze.py

@@ -16,7 +16,7 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 
 from . import ActiveAgent
-from ..bottle_state import mark_preserved, write_committed_image
+from ..bottle.state import mark_preserved, write_committed_image
 from ..log import die, info
 
 
@@ -66,7 +66,7 @@ class Freezer(ABC):
 
     def commit_slug(self, slug: str) -> None:
         """Convenience entry for cmd_commit when only a slug is available."""
-        from ..bottle_state import read_metadata
+        from ..bottle.state import read_metadata
         metadata = read_metadata(slug)
         agent = ActiveAgent(
             backend_name=self.backend_name,

bot_bottle/backend/macos_container/enumerate.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import subprocess
 
-from ...bottle_state import read_metadata
+from ...bottle.state import read_metadata
 from .. import ActiveAgent
 
 _PREFIX = "bot-bottle-"

bot_bottle/backend/macos_container/launch.py

@@ -17,7 +17,7 @@ from contextlib import ExitStack, contextmanager
 from pathlib import Path
 from typing import Callable, Generator
 
-from ...bottle_state import (
+from ...bottle.state import (
     egress_state_dir,
     git_gate_state_dir,
     read_committed_image,
@@ -28,9 +28,12 @@ from ...egress import (
     egress_resolve_token_values,
     egress_sidecar_env_entries,
 )
-from ...git_gate import revoke_git_gate_provisioned_keys
+from ...git_gate import (
+    provision_git_gate_dynamic_keys,
+    revoke_git_gate_provisioned_keys,
+)
 from ...log import die, info, warn
-from ...supervise import QUEUE_DIR_IN_CONTAINER, SUPERVISE_PORT
+from ...supervise import DB_PATH_IN_CONTAINER, SUPERVISE_PORT
 from ...util import expand_tilde
 from ..docker.egress import EGRESS_CA_IN_CONTAINER, EGRESS_PORT
 from ..docker.git_gate import (
@@ -98,6 +101,8 @@ def launch(
         egress_network = egress_network_name(plan.slug)
         _create_networks(internal_network, egress_network, stack)
 
+        plan = _provision_git_gate_keys(plan)
+
         sidecar_name = sidecar_container_name(plan.slug)
         container_mod.force_remove_container(sidecar_name)
         _start_sidecar_bundle(plan, sidecar_name, internal_network, egress_network)
@@ -241,6 +246,19 @@ def _stamp_agent_urls(
     )
 
 
+def _provision_git_gate_keys(
+    plan: MacosContainerBottlePlan,
+) -> MacosContainerBottlePlan:
+    if not plan.git_gate_plan.upstreams:
+        return plan
+    git_gate_plan = provision_git_gate_dynamic_keys(
+        plan.manifest.bottle,
+        plan.git_gate_plan,
+        git_gate_state_dir(plan.slug),
+    )
+    return dataclasses.replace(plan, git_gate_plan=git_gate_plan)
+
+
 def _stage_git_gate(plan: MacosContainerBottlePlan, sidecar_name: str) -> None:
     gp = plan.git_gate_plan
     if not gp.upstreams:
@@ -361,7 +379,7 @@ def _sidecar_env_entries(plan: MacosContainerBottlePlan) -> tuple[str, ...]:
     if plan.supervise_plan is not None:
         env += [
             f"SUPERVISE_BOTTLE_SLUG={plan.slug}",
-            f"SUPERVISE_QUEUE_DIR={QUEUE_DIR_IN_CONTAINER}",
+            f"SUPERVISE_DB_PATH={DB_PATH_IN_CONTAINER}",
             f"SUPERVISE_PORT={SUPERVISE_PORT}",
         ]
     return tuple(env)
@@ -387,7 +405,15 @@ def _sidecar_mounts(
 
     sp = plan.supervise_plan
     if sp is not None:
-        mounts.append((str(sp.queue_dir), QUEUE_DIR_IN_CONTAINER, False))
+        # `container run --mount type=bind` only accepts directory
+        # sources (a file source fails with "is not a directory") —
+        # mount db_path's dedicated parent dir instead of the file
+        # itself, same as the CA/routes mounts above.
+        mounts.append((
+            str(sp.db_path.parent),
+            str(Path(DB_PATH_IN_CONTAINER).parent),
+            False,
+        ))
 
     return tuple(mounts)
 

bot_bottle/backend/resolve_common.py

@@ -15,7 +15,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from ..agent_provider import AgentProvisionPlan
-from ..bottle_state import (
+from ..bottle.state import (
     BottleMetadata,
     agent_state_dir,
     bottle_identity,

bot_bottle/backend/smolmachines/enumerate.py

@@ -23,7 +23,7 @@ import json
 import subprocess
 
 from .. import ActiveAgent
-from ...bottle_state import read_metadata
+from ...bottle.state import read_metadata
 from . import sidecar_bundle as _bundle
 
 

bot_bottle/backend/smolmachines/freezer.py

@@ -18,7 +18,7 @@ from ..freeze import Freezer
 from ..docker import util as docker_mod
 from .local_registry import crane_push_tarball, ephemeral_registry
 from .smolvm import machine_cp, machine_exec, pack_create
-from ...bottle_state import bottle_state_dir
+from ...bottle.state import bottle_state_dir
 from ...log import die, info
 
 

bot_bottle/backend/smolmachines/launch.py

@@ -27,7 +27,7 @@ from ...egress import (
     egress_resolve_token_values,
     egress_sidecar_env_entries,
 )
-from ...supervise import QUEUE_DIR_IN_CONTAINER, SUPERVISE_PORT
+from ...supervise import DB_PATH_IN_CONTAINER, SUPERVISE_PORT
 from ...util import expand_tilde
 from ..docker import util as docker_mod
 from ..docker.egress import (
@@ -41,9 +41,12 @@ from ..docker.git_gate import (
     GIT_GATE_ENTRYPOINT_IN_CONTAINER,
     GIT_GATE_HOOK_IN_CONTAINER,
 )
-from ...git_gate import revoke_git_gate_provisioned_keys
+from ...git_gate import (
+    provision_git_gate_dynamic_keys,
+    revoke_git_gate_provisioned_keys,
+)
 from ...log import info, warn
-from ...bottle_state import (
+from ...bottle.state import (
     egress_state_dir,
     git_gate_state_dir,
     read_committed_image,
@@ -174,6 +177,7 @@ def _start_bundle(
 ) -> SmolmachinesBottlePlan:
     """Build the BundleLaunchSpec, resolve token env, start the
     sidecar bundle container, and register teardown."""
+    plan = _provision_git_gate_keys(plan)
     bundle_spec = _bundle_launch_spec(plan, network, loopback_ip)
     token_env = _resolve_token_env(plan, dict(os.environ))
     _bundle.ensure_bundle_image(bundle_spec.image)
@@ -182,6 +186,19 @@ def _start_bundle(
     return plan
 
 
+def _provision_git_gate_keys(
+    plan: SmolmachinesBottlePlan,
+) -> SmolmachinesBottlePlan:
+    if not plan.git_gate_plan.upstreams:
+        return plan
+    git_gate_plan = provision_git_gate_dynamic_keys(
+        plan.manifest.bottle,
+        plan.git_gate_plan,
+        git_gate_state_dir(plan.slug),
+    )
+    return dataclasses.replace(plan, git_gate_plan=git_gate_plan)
+
+
 def _discover_urls(
     plan: SmolmachinesBottlePlan,
     loopback_ip: str,
@@ -352,10 +369,10 @@ def _bundle_launch_spec(
         daemons.append("supervise")
         env += [
             f"SUPERVISE_BOTTLE_SLUG={plan.slug}",
-            f"SUPERVISE_QUEUE_DIR={QUEUE_DIR_IN_CONTAINER}",
+            f"SUPERVISE_DB_PATH={DB_PATH_IN_CONTAINER}",
             f"SUPERVISE_PORT={SUPERVISE_PORT}",
         ]
-        volumes.append((str(sp.queue_dir), QUEUE_DIR_IN_CONTAINER, False))
+        volumes.append((str(sp.db_path), DB_PATH_IN_CONTAINER, False))
 
     # Container ports the agent reaches from the smolvm guest —
     # published on host loopback so the guest can dial via TSI +

bot_bottle/bottle/__init__.py

@@ -0,0 +1,11 @@
+"""Bottle lifecycle primitives."""
+
+from .runner import BottleError, destroy, freeze, resume_headless, start_headless
+
+__all__ = [
+    "BottleError",
+    "destroy",
+    "freeze",
+    "resume_headless",
+    "start_headless",
+]

bot_bottle/bottle/runner.py

@@ -0,0 +1,258 @@
+"""Public Python API for programmatic bottle orchestration.
+
+Stable surface for bot-bottle-orchestrator (and other Python callers) to
+drive bottles without invoking the CLI as a subprocess.  Every function
+converts ``Die`` and non-zero agent exit codes to ``BottleError`` so
+callers use exception handling rather than inspecting return values.
+
+The Protocol the orchestrator's ``BottleRunner`` targets looks like::
+
+    class BottleRunner(Protocol):
+        def start(self, agent: str, *, prompt: str, ...) -> str: ...
+        def resume(self, slug: str, *, prompt: str) -> None: ...
+        def freeze(self, slug: str) -> None: ...
+        def destroy(self, slug: str) -> None: ...
+
+A ``SubprocessBottleRunner`` calls ``./cli.py`` for each operation.  A
+``ProgrammaticBottleRunner`` calls these functions directly; the Protocol
+call sites in ``lifecycle.py`` are unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, cast
+
+from ..backend import BottleSpec
+from ..backend.freeze import CommitCancelled, get_freezer
+from .state import cleanup_state, clear_preserve_marker, read_metadata
+from ..cli._common import USER_CWD
+from ..cli.start import _launch_bottle, _peek_agent_bottle, _uniquify_label_headless
+from ..log import Die
+from ..manifest import ManifestError, ManifestIndex
+
+
+class BottleError(Exception):
+    """Raised when a bottle operation fails.
+
+    ``exit_code`` carries the agent process's exit code when the failure is
+    a non-zero agent exit; 1 for all other failure modes (missing state,
+    backend errors, etc.)."""
+
+    def __init__(self, message: str, *, exit_code: int = 1) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+def start_headless(
+    agent_name: str,
+    *,
+    prompt: str,
+    bottles: Sequence[str] | None = None,
+    label: str | None = None,
+    color: str | None = None,
+    backend_name: str | None = None,
+    copy_cwd: bool = False,
+    forge_env: dict[str, str] | None = None,
+    user_cwd: str | None = None,
+) -> str:
+    """Launch a new bottle headlessly.  Returns the bottle slug.
+
+    ``forge_env`` is passed through to the forge sidecar (not the agent)
+    when the bottle is forge-targeted; it carries the credentials and
+    context the sidecar needs to call the forge API.
+
+    Raises ``BottleError`` on configuration errors or if the agent exits
+    non-zero.  The returned slug can be passed to ``freeze()``,
+    ``resume_headless()``, or ``destroy()`` for subsequent lifecycle
+    operations."""
+    cwd = user_cwd or USER_CWD
+    try:
+        manifest = ManifestIndex.resolve(cwd)
+        manifest.require_agent(agent_name)
+    except (Die, ManifestError) as exc:
+        raise BottleError(str(exc)) from exc
+
+    if bottles:
+        bottle_names: tuple[str, ...] = tuple(bottles)
+    else:
+        default_bottle = _peek_agent_bottle(manifest, agent_name)
+        if not default_bottle:
+            raise BottleError(
+                f"agent '{agent_name}' has no default bottle; "
+                f"pass bottles=[...]"
+            )
+        bottle_names = (default_bottle,)
+
+    spec = BottleSpec(
+        manifest=manifest,
+        agent_name=agent_name,
+        copy_cwd=copy_cwd,
+        user_cwd=cwd,
+        label=_uniquify_label_headless(label or agent_name),
+        color=color or "",
+        bottle_names=bottle_names,
+        forge_env=dict(forge_env) if forge_env else {},
+    )
+    try:
+        slug, exit_code = _launch_bottle(
+            spec,
+            dry_run=False,
+            backend_name=backend_name,
+            assume_yes=True,
+            headless_prompt_text=prompt,
+        )
+    except Die as exc:
+        raise BottleError(exc.message, exit_code=cast(int, exc.code)) from exc
+    if exit_code != 0:
+        raise BottleError(
+            f"agent exited {exit_code} (slug={slug!r})", exit_code=exit_code
+        )
+    return slug
+
+
+def resume_headless(
+    slug: str,
+    *,
+    prompt: str,
+    backend_name: str | None = None,
+    forge_env: dict[str, str] | None = None,
+) -> None:
+    """Resume a frozen bottle headlessly with ``prompt``.
+
+    ``forge_env`` re-supplies forge context for the new session (the
+    sidecar is relaunched alongside the agent on resume).
+
+    Raises ``BottleError`` on missing state, backend errors, or non-zero
+    agent exit."""
+    metadata = read_metadata(slug)
+    if metadata is None:
+        raise BottleError(
+            f"no state recorded for slug {slug!r}; "
+            f"check ~/.bot-bottle/state/ or call start_headless() to create a new bottle"
+        )
+
+    try:
+        manifest = ManifestIndex.resolve(metadata.cwd or USER_CWD)
+        manifest.require_agent(metadata.agent_name)
+    except (Die, ManifestError) as exc:
+        raise BottleError(str(exc)) from exc
+
+    spec = BottleSpec(
+        manifest=manifest,
+        agent_name=metadata.agent_name,
+        copy_cwd=metadata.copy_cwd,
+        user_cwd=metadata.cwd or USER_CWD,
+        identity=metadata.identity,
+        bottle_names=tuple(metadata.bottle_names),
+        forge_env=dict(forge_env) if forge_env else {},
+    )
+    try:
+        _, exit_code = _launch_bottle(
+            spec,
+            dry_run=False,
+            backend_name=backend_name or metadata.backend or None,
+            assume_yes=True,
+            headless_prompt_text=prompt,
+        )
+    except Die as exc:
+        raise BottleError(exc.message, exit_code=cast(int, exc.code)) from exc
+    if exit_code != 0:
+        raise BottleError(
+            f"agent exited {exit_code} resuming {slug!r}", exit_code=exit_code
+        )
+
+
+def freeze(slug: str, *, backend_name: str | None = None) -> None:
+    """Freeze the named bottle to a resumable artifact.
+
+    Reads the bottle's backend from its metadata when ``backend_name`` is
+    not supplied.  Raises ``BottleError`` if the freeze fails."""
+    metadata = read_metadata(slug)
+    resolved_backend = backend_name or (metadata.backend if metadata else "") or "docker"
+    try:
+        get_freezer(resolved_backend).commit_slug(slug)
+    except CommitCancelled as exc:
+        raise BottleError(f"freeze cancelled for {slug!r}") from exc
+    except Die as exc:
+        raise BottleError(exc.message, exit_code=cast(int, exc.code)) from exc
+
+
+def destroy(slug: str, *, backend_name: str | None = None) -> None:
+    """Destroy the named bottle, removing all resources and state.
+
+    Brings down any running resources for ``slug``, then removes the
+    per-bottle state directory.  Idempotent: a slug with no running
+    resources or no state directory is not an error."""
+    metadata = read_metadata(slug)
+    resolved_backend = backend_name or (metadata.backend if metadata else "") or "docker"
+    try:
+        if resolved_backend == "docker":
+            _destroy_docker(slug)
+        elif resolved_backend == "smolmachines":
+            _destroy_smolmachines(slug)
+        # macos-container: the container is torn down inside the launch
+        # context manager; no persistent VM survives, so nothing extra is
+        # needed at destroy time beyond the state-dir removal below.
+    except Die as exc:
+        raise BottleError(exc.message, exit_code=cast(int, exc.code)) from exc
+    clear_preserve_marker(slug)
+    cleanup_state(slug)
+
+
+# --- backend-specific helpers -----------------------------------------------
+
+
+def _destroy_docker(slug: str) -> None:
+    """Best-effort ``docker compose down`` for a Docker bottle.
+
+    No-op when the compose file is absent — the project was already
+    brought down (normal for a frozen bottle) or was never created."""
+    from ..backend.docker.compose import (
+        compose_down,
+        compose_file_path,
+        compose_project_name,
+    )
+    from .state import bottle_state_dir
+
+    state_dir = bottle_state_dir(slug)
+    compose_file = compose_file_path(state_dir)
+    if compose_file.exists():
+        compose_down(compose_project_name(slug), compose_file)
+
+
+def _destroy_smolmachines(slug: str) -> None:
+    """Best-effort stop + delete for a smolmachines bottle.
+
+    Both steps are best-effort: a machine that is already gone does not
+    cause an error; partial failures are logged as warnings."""
+    import subprocess
+
+    from ..log import warn
+
+    machine = f"bot-bottle-{slug}"
+    subprocess.run(
+        ["smolvm", "machine", "stop", "--name", machine],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        check=False,
+    )
+    r = subprocess.run(
+        ["smolvm", "machine", "delete", "-f", machine],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if r.returncode != 0:
+        warn(
+            f"smolvm machine delete -f {machine!r} failed "
+            f"(may already be gone): {(r.stderr or '').strip()}"
+        )
+
+
+__all__ = [
+    "BottleError",
+    "destroy",
+    "freeze",
+    "resume_headless",
+    "start_headless",
+]

bot_bottle/bottle/state.py

@@ -0,0 +1,364 @@
+"""Per-bottle persistent state.
+
+Holds optional per-bottle Dockerfile overrides, the transcript snapshot
+the state-preservation helper saves before teardown, and the launch metadata that lets
+`cli.py resume <identity>` reconstruct a bottle's spec. State
+lives at:
+
+    ~/.bot-bottle/state/<identity>/
+        metadata.json     — agent_name + cwd + started_at (for resume)
+        Dockerfile        — per-bottle override (absent → use repo's)
+        transcript/       — last snapshotted agent state (best-effort)
+
+When the per-bottle Dockerfile is present, the launch step builds
+the agent image with a per-bottle tag (bot-bottle-rebuilt-<id>)
+from this file rather than the repo's. The build context is still
+the repo root so the Dockerfile can COPY bot_bottle source files
+the same way the original does.
+
+Identity model:
+- Every `cli.py start <agent>` mints a fresh identity via
+  `bottle_identity(agent_name)`: slug-prefix for readability plus a
+  5-char random suffix for parallel-safe uniqueness. The metadata
+  written at launch time pins (agent_name, cwd) to that identity.
+- `cli.py resume <identity>` reads the metadata and re-launches a
+  bottle pinned to the same identity, picking up any per-bottle
+  Dockerfile and transcript snapshot.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import secrets
+import string
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+from .. import supervise as _supervise
+
+
+# Directory layout: ~/.bot-bottle/state/<identity>/...
+_STATE_SUBDIR = "state"
+_PER_BOTTLE_DOCKERFILE_NAME = "Dockerfile"
+_COMMITTED_IMAGE_NAME = "committed-image"
+_TRANSCRIPT_SUBDIR = "transcript"
+# Per-sidecar scratch subdirs. PRD 0018 chunk 2: bind-mount sources
+# live here so chunk 3's `docker compose up` can find them at stable
+# paths. Each sidecar's `prepare()` writes config + CAs into its own
+# subdir; the launch step is unchanged today (still `docker cp`).
+_EGRESS_SUBDIR = "egress"
+_GIT_GATE_SUBDIR = "git-gate"
+_SUPERVISE_SUBDIR = "supervise"
+_AGENT_SUBDIR = "agent"
+_METADATA_NAME = "metadata.json"
+# Live-config dir bind-mounted into the supervise sidecar (read-only).
+# Host's apply paths keep these files fresh so supervise's
+# `list-egress-routes` MCP tool returns the current state —
+# not a snapshot from launch time.
+_LIVE_CONFIG_SUBDIR = "live-config"
+LIVE_CONFIG_ROUTES_NAME = "routes.yaml"
+LIVE_CONFIG_ALLOWLIST_NAME = "allowlist"
+# Empty marker file. Session preservation writes it before teardown so
+# cli.py's session-end cleanup knows to preserve the state dir for
+# `cli.py resume <identity>`. Absent = clean up.
+_PRESERVE_MARKER = ".preserve"
+
+# 5 chars of base36 alphabet ≈ 60M combinations. Plenty for human
+# operators starting bottles by hand; collision-free in practice.
+_RANDOM_SUFFIX_LEN = 5
+_SUFFIX_ALPHABET = string.ascii_lowercase + string.digits
+
+
+def bottle_identity(agent_name: str) -> str:
+    """Mint a fresh per-launch bottle identity. The slug-prefix is
+    `slugify(agent_name)` for readability; the suffix is 5 random
+    base36 chars so two simultaneous `start <agent>` invocations
+    don't collide on container/network names.
+
+    Every call produces a different identity (non-deterministic).
+    To continue an existing bottle's state, use the recorded
+    identity from BottleMetadata via `cli.py resume <identity>`,
+    not this function."""
+    from ..backend.docker import util as docker_mod
+    slug = docker_mod.slugify(agent_name)
+    suffix = "".join(secrets.choice(_SUFFIX_ALPHABET) for _ in range(_RANDOM_SUFFIX_LEN))
+    return f"{slug}-{suffix}"
+
+
+@dataclass(frozen=True)
+class BottleMetadata:
+    """Persistent record of how a bottle was launched, written at
+    start time and read by `cli.py resume`. Lives at
+    ~/.bot-bottle/state/<identity>/metadata.json."""
+
+    identity: str
+    agent_name: str
+    cwd: str           # empty string when --cwd was not passed
+    copy_cwd: bool
+    started_at: str    # ISO 8601 UTC
+    # PRD 0018 chunk 3: derivable from identity via
+    # `compose_project_name(identity)`, but persisted explicitly so
+    # dashboard / cleanup / resume tooling can read it without
+    # importing the compose module. Empty string for state dirs
+    # written before chunk 3 (resume / inspect should fall back to
+    # deriving from identity in that case).
+    compose_project: str = ""
+    # PRD 0040: backend name ("docker" or "smolmachines"). Empty string
+    # for state dirs written before PRD 0040; callers default to "docker"
+    # for backward compatibility.
+    backend: str = ""
+    label: str = ""
+    color: str = ""
+    # Ordered bottle names selected at launch (issue #269). Empty tuple
+    # for state dirs written before this change; resume falls back to
+    # the agent's `bottle:` field in that case.
+    bottle_names: tuple[str, ...] = ()
+
+
+def metadata_path(identity: str) -> Path:
+    return bottle_state_dir(identity) / _METADATA_NAME
+
+
+def write_metadata(metadata: BottleMetadata) -> Path:
+    """Persist `metadata` to ~/.bot-bottle/state/<identity>/metadata.json.
+    Mode 0o644 — no secrets, just (agent_name, cwd, timestamp)."""
+    path = metadata_path(metadata.identity)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(dataclasses.asdict(metadata), indent=2) + "\n")
+    path.chmod(0o644)
+    return path
+
+
+def read_metadata(identity: str) -> BottleMetadata | None:
+    """Return the metadata for `identity`, or None if no state has
+    been recorded for it. Used by `cli.py resume` to reconstruct
+    the launch spec."""
+    path = metadata_path(identity)
+    if not path.is_file():
+        return None
+    raw = json.loads(path.read_text())
+    if not isinstance(raw, dict):
+        return None
+    raw_typed = cast(dict[str, object], raw)
+    raw_bottle_names = raw_typed.get("bottle_names", [])
+    bottle_names: tuple[str, ...] = ()
+    if isinstance(raw_bottle_names, list):
+        bottle_names = tuple(str(n) for n in raw_bottle_names if isinstance(n, str))
+    return BottleMetadata(
+        identity=str(raw_typed.get("identity", identity)),
+        agent_name=str(raw_typed.get("agent_name", "")),
+        cwd=str(raw_typed.get("cwd", "")),
+        copy_cwd=bool(raw_typed.get("copy_cwd", False)),
+        started_at=str(raw_typed.get("started_at", "")),
+        compose_project=str(raw_typed.get("compose_project", "")),
+        backend=str(raw_typed.get("backend", "")),
+        label=str(raw_typed.get("label", "")),
+        color=str(raw_typed.get("color", "")),
+        bottle_names=bottle_names,
+    )
+
+
+def bottle_state_dir(identity: str) -> Path:
+    """Per-bottle state directory on the host. Created lazily by the
+    write helpers; readers tolerate its absence."""
+    return _supervise.bot_bottle_root() / _STATE_SUBDIR / identity
+
+
+def per_bottle_dockerfile_path(identity: str) -> Path:
+    return bottle_state_dir(identity) / _PER_BOTTLE_DOCKERFILE_NAME
+
+
+def per_bottle_dockerfile(identity: str) -> str | None:
+    """Return the per-bottle Dockerfile content if present, else
+    None. None means: use the provider or manifest Dockerfile."""
+    p = per_bottle_dockerfile_path(identity)
+    if p.is_file():
+        return p.read_text()
+    return None
+
+
+def write_per_bottle_dockerfile(identity: str, content: str) -> Path:
+    p = per_bottle_dockerfile_path(identity)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(content)
+    p.chmod(0o644)
+    return p
+
+
+def committed_image_path(identity: str) -> Path:
+    return bottle_state_dir(identity) / _COMMITTED_IMAGE_NAME
+
+
+def write_committed_image(identity: str, image_tag: str) -> Path:
+    """Persist the committed image tag for `identity`. The next
+    `cli.py resume <identity>` will boot from this image instead of
+    rebuilding from the Dockerfile."""
+    path = committed_image_path(identity)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(image_tag.strip() + "\n")
+    path.chmod(0o644)
+    return path
+
+
+def read_committed_image(identity: str) -> str | None:
+    """Return the committed image tag for `identity`, or None if no
+    commit has been recorded. Used by the Docker launch step to skip
+    the Dockerfile build when a committed snapshot exists."""
+    path = committed_image_path(identity)
+    if not path.is_file():
+        return None
+    tag = path.read_text().strip()
+    return tag or None
+
+
+def per_bottle_image_tag(identity: str) -> str:
+    """Image tag for a rebuilt bottle. Distinct from the base
+    bot-bottle-claude:latest so per-bottle rebuilds don't collide in
+    the docker image cache."""
+    return f"bot-bottle-rebuilt-{identity}:latest"
+
+
+def live_config_dir(identity: str) -> Path:
+    """Per-bottle live-config dir. Bind-mounted read-only into the
+    supervise sidecar; the host's apply paths refresh the files on
+    every operator approval so the agent's `list-*` MCP tools always
+    return current state."""
+    return bottle_state_dir(identity) / _LIVE_CONFIG_SUBDIR
+
+
+def live_routes_path(identity: str) -> Path:
+    return live_config_dir(identity) / LIVE_CONFIG_ROUTES_NAME
+
+
+def live_allowlist_path(identity: str) -> Path:
+    return live_config_dir(identity) / LIVE_CONFIG_ALLOWLIST_NAME
+
+
+def write_live_config(
+    identity: str, *, routes: str = "", allowlist: str = "",
+) -> Path:
+    """Initialise (or refresh) the live-config dir. Empty-string args
+    leave the existing file alone (caller passes only what it knows).
+    Returns the live-config dir path."""
+    d = live_config_dir(identity)
+    d.mkdir(parents=True, exist_ok=True)
+    if routes:
+        p = live_routes_path(identity)
+        p.write_text(routes)
+        p.chmod(0o644)
+    if allowlist:
+        p = live_allowlist_path(identity)
+        p.write_text(allowlist)
+        p.chmod(0o644)
+    return d
+
+
+def transcript_snapshot_dir(identity: str) -> Path:
+    """Where agent session snapshots are kept for resume flows."""
+    return bottle_state_dir(identity) / _TRANSCRIPT_SUBDIR
+
+
+# --- Per-sidecar scratch subdirs (PRD 0018 chunk 2) ------------------------
+#
+# Each sidecar gets its own subdir under the bottle's state dir for
+# bind-mount sources (config, CAs, hooks, etc.). Prepare-time writes
+# land here; the state dir's normal cleanup (`cleanup_state`) reaps
+# them along with everything else when the bottle session ends and
+# nothing requested preservation.
+
+
+def egress_state_dir(identity: str) -> Path:
+    """State subdir for the egress sidecar: routes.yaml + the
+    per-bottle mitmproxy CA. Bind-mount source from chunk 3 onward."""
+    return bottle_state_dir(identity) / _EGRESS_SUBDIR
+
+
+def git_gate_state_dir(identity: str) -> Path:
+    """State subdir for the git-gate sidecar: entrypoint + hooks +
+    per-upstream known_hosts. Bind-mount source from chunk 3
+    onward."""
+    return bottle_state_dir(identity) / _GIT_GATE_SUBDIR
+
+
+def supervise_state_dir(identity: str) -> Path:
+    """State subdir reserved for supervise sidecar bind-mount sources.
+    The queue dir is intentionally NOT under here — it lives at
+    ~/.bot-bottle/queue/<slug>/ alongside the audit logs, so it
+    survives state-dir cleanup."""
+    return bottle_state_dir(identity) / _SUPERVISE_SUBDIR
+
+
+def agent_state_dir(identity: str) -> Path:
+    """State subdir for the agent's prepare-time scratch files: the
+    env file (docker --env-file source) and the prompt file."""
+    return bottle_state_dir(identity) / _AGENT_SUBDIR
+
+
+# --- Preserve-on-close marker ----------------------------------------------
+
+
+def preserve_marker_path(identity: str) -> Path:
+    return bottle_state_dir(identity) / _PRESERVE_MARKER
+
+
+def mark_preserved(identity: str) -> Path:
+    """Mark this bottle's state for preservation across session
+    teardown so cli.py's session-end cleanup leaves the state dir
+    intact for a subsequent `cli.py resume`."""
+    path = preserve_marker_path(identity)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.touch()
+    return path
+
+
+def is_preserved(identity: str) -> bool:
+    return preserve_marker_path(identity).exists()
+
+
+def clear_preserve_marker(identity: str) -> None:
+    """Idempotent removal. Called at fresh launch (start or resume)
+    so a marker left from a prior preserved session doesn't keep
+    state alive past the next normal session-end."""
+    try:
+        preserve_marker_path(identity).unlink()
+    except FileNotFoundError:
+        pass
+
+
+def cleanup_state(identity: str) -> None:
+    """Remove the per-bottle state dir entirely. Called by cli.py
+    when a bottle session ends and is_preserved(identity) is False.
+    Idempotent — missing dir is success."""
+    import shutil
+    state_dir = bottle_state_dir(identity)
+    if state_dir.is_dir():
+        shutil.rmtree(state_dir, ignore_errors=True)
+
+
+__all__ = [
+    "BottleMetadata",
+    "agent_state_dir",
+    "bottle_identity",
+    "bottle_state_dir",
+    "cleanup_state",
+    "clear_preserve_marker",
+    "committed_image_path",
+    "egress_state_dir",
+    "git_gate_state_dir",
+    "is_preserved",
+    "mark_preserved",
+    "metadata_path",
+    "per_bottle_dockerfile",
+    "per_bottle_dockerfile_path",
+    "per_bottle_image_tag",
+    "preserve_marker_path",
+    "read_committed_image",
+    "read_metadata",
+    "supervise_state_dir",
+    "transcript_snapshot_dir",
+    "write_committed_image",
+    "write_metadata",
+    "write_per_bottle_dockerfile",
+]

bot_bottle/bottle_state.py

@@ -1,364 +1,6 @@
-"""Per-bottle persistent state.
+"""Compatibility wrapper for per-bottle persistent state.
 
-Holds optional per-bottle Dockerfile overrides, the transcript snapshot
-the state-preservation helper saves before teardown, and the launch metadata that lets
-`cli.py resume <identity>` reconstruct a bottle's spec. State
-lives at:
-
-    ~/.bot-bottle/state/<identity>/
-        metadata.json     — agent_name + cwd + started_at (for resume)
-        Dockerfile        — per-bottle override (absent → use repo's)
-        transcript/       — last snapshotted agent state (best-effort)
-
-When the per-bottle Dockerfile is present, the launch step builds
-the agent image with a per-bottle tag (bot-bottle-rebuilt-<id>)
-from this file rather than the repo's. The build context is still
-the repo root so the Dockerfile can COPY bot_bottle source files
-the same way the original does.
-
-Identity model:
-- Every `cli.py start <agent>` mints a fresh identity via
-  `bottle_identity(agent_name)`: slug-prefix for readability plus a
-  5-char random suffix for parallel-safe uniqueness. The metadata
-  written at launch time pins (agent_name, cwd) to that identity.
-- `cli.py resume <identity>` reads the metadata and re-launches a
-  bottle pinned to the same identity, picking up any per-bottle
-  Dockerfile and transcript snapshot.
+The implementation lives in :mod:`bot_bottle.bottle.state`.
 """
 
-from __future__ import annotations
-
-import dataclasses
-import json
-import secrets
-import string
-from dataclasses import dataclass
-from pathlib import Path
-from typing import cast
-
-from . import supervise as _supervise
-
-
-# Directory layout: ~/.bot-bottle/state/<identity>/...
-_STATE_SUBDIR = "state"
-_PER_BOTTLE_DOCKERFILE_NAME = "Dockerfile"
-_COMMITTED_IMAGE_NAME = "committed-image"
-_TRANSCRIPT_SUBDIR = "transcript"
-# Per-sidecar scratch subdirs. PRD 0018 chunk 2: bind-mount sources
-# live here so chunk 3's `docker compose up` can find them at stable
-# paths. Each sidecar's `prepare()` writes config + CAs into its own
-# subdir; the launch step is unchanged today (still `docker cp`).
-_EGRESS_SUBDIR = "egress"
-_GIT_GATE_SUBDIR = "git-gate"
-_SUPERVISE_SUBDIR = "supervise"
-_AGENT_SUBDIR = "agent"
-_METADATA_NAME = "metadata.json"
-# Live-config dir bind-mounted into the supervise sidecar (read-only).
-# Host's apply paths keep these files fresh so supervise's
-# `list-egress-routes` MCP tool returns the current state —
-# not a snapshot from launch time.
-_LIVE_CONFIG_SUBDIR = "live-config"
-LIVE_CONFIG_ROUTES_NAME = "routes.yaml"
-LIVE_CONFIG_ALLOWLIST_NAME = "allowlist"
-# Empty marker file. Session preservation writes it before teardown so
-# cli.py's session-end cleanup knows to preserve the state dir for
-# `cli.py resume <identity>`. Absent = clean up.
-_PRESERVE_MARKER = ".preserve"
-
-# 5 chars of base36 alphabet ≈ 60M combinations. Plenty for human
-# operators starting bottles by hand; collision-free in practice.
-_RANDOM_SUFFIX_LEN = 5
-_SUFFIX_ALPHABET = string.ascii_lowercase + string.digits
-
-
-def bottle_identity(agent_name: str) -> str:
-    """Mint a fresh per-launch bottle identity. The slug-prefix is
-    `slugify(agent_name)` for readability; the suffix is 5 random
-    base36 chars so two simultaneous `start <agent>` invocations
-    don't collide on container/network names.
-
-    Every call produces a different identity (non-deterministic).
-    To continue an existing bottle's state, use the recorded
-    identity from BottleMetadata via `cli.py resume <identity>`,
-    not this function."""
-    from .backend.docker import util as docker_mod
-    slug = docker_mod.slugify(agent_name)
-    suffix = "".join(secrets.choice(_SUFFIX_ALPHABET) for _ in range(_RANDOM_SUFFIX_LEN))
-    return f"{slug}-{suffix}"
-
-
-@dataclass(frozen=True)
-class BottleMetadata:
-    """Persistent record of how a bottle was launched, written at
-    start time and read by `cli.py resume`. Lives at
-    ~/.bot-bottle/state/<identity>/metadata.json."""
-
-    identity: str
-    agent_name: str
-    cwd: str           # empty string when --cwd was not passed
-    copy_cwd: bool
-    started_at: str    # ISO 8601 UTC
-    # PRD 0018 chunk 3: derivable from identity via
-    # `compose_project_name(identity)`, but persisted explicitly so
-    # dashboard / cleanup / resume tooling can read it without
-    # importing the compose module. Empty string for state dirs
-    # written before chunk 3 (resume / inspect should fall back to
-    # deriving from identity in that case).
-    compose_project: str = ""
-    # PRD 0040: backend name ("docker" or "smolmachines"). Empty string
-    # for state dirs written before PRD 0040; callers default to "docker"
-    # for backward compatibility.
-    backend: str = ""
-    label: str = ""
-    color: str = ""
-    # Ordered bottle names selected at launch (issue #269). Empty tuple
-    # for state dirs written before this change; resume falls back to
-    # the agent's `bottle:` field in that case.
-    bottle_names: tuple[str, ...] = ()
-
-
-def metadata_path(identity: str) -> Path:
-    return bottle_state_dir(identity) / _METADATA_NAME
-
-
-def write_metadata(metadata: BottleMetadata) -> Path:
-    """Persist `metadata` to ~/.bot-bottle/state/<identity>/metadata.json.
-    Mode 0o644 — no secrets, just (agent_name, cwd, timestamp)."""
-    path = metadata_path(metadata.identity)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(dataclasses.asdict(metadata), indent=2) + "\n")
-    path.chmod(0o644)
-    return path
-
-
-def read_metadata(identity: str) -> BottleMetadata | None:
-    """Return the metadata for `identity`, or None if no state has
-    been recorded for it. Used by `cli.py resume` to reconstruct
-    the launch spec."""
-    path = metadata_path(identity)
-    if not path.is_file():
-        return None
-    raw = json.loads(path.read_text())
-    if not isinstance(raw, dict):
-        return None
-    raw_typed = cast(dict[str, object], raw)
-    raw_bottle_names = raw_typed.get("bottle_names", [])
-    bottle_names: tuple[str, ...] = ()
-    if isinstance(raw_bottle_names, list):
-        bottle_names = tuple(str(n) for n in raw_bottle_names if isinstance(n, str))
-    return BottleMetadata(
-        identity=str(raw_typed.get("identity", identity)),
-        agent_name=str(raw_typed.get("agent_name", "")),
-        cwd=str(raw_typed.get("cwd", "")),
-        copy_cwd=bool(raw_typed.get("copy_cwd", False)),
-        started_at=str(raw_typed.get("started_at", "")),
-        compose_project=str(raw_typed.get("compose_project", "")),
-        backend=str(raw_typed.get("backend", "")),
-        label=str(raw_typed.get("label", "")),
-        color=str(raw_typed.get("color", "")),
-        bottle_names=bottle_names,
-    )
-
-
-def bottle_state_dir(identity: str) -> Path:
-    """Per-bottle state directory on the host. Created lazily by the
-    write helpers; readers tolerate its absence."""
-    return _supervise.bot_bottle_root() / _STATE_SUBDIR / identity
-
-
-def per_bottle_dockerfile_path(identity: str) -> Path:
-    return bottle_state_dir(identity) / _PER_BOTTLE_DOCKERFILE_NAME
-
-
-def per_bottle_dockerfile(identity: str) -> str | None:
-    """Return the per-bottle Dockerfile content if present, else
-    None. None means: use the provider or manifest Dockerfile."""
-    p = per_bottle_dockerfile_path(identity)
-    if p.is_file():
-        return p.read_text()
-    return None
-
-
-def write_per_bottle_dockerfile(identity: str, content: str) -> Path:
-    p = per_bottle_dockerfile_path(identity)
-    p.parent.mkdir(parents=True, exist_ok=True)
-    p.write_text(content)
-    p.chmod(0o644)
-    return p
-
-
-def committed_image_path(identity: str) -> Path:
-    return bottle_state_dir(identity) / _COMMITTED_IMAGE_NAME
-
-
-def write_committed_image(identity: str, image_tag: str) -> Path:
-    """Persist the committed image tag for `identity`. The next
-    `cli.py resume <identity>` will boot from this image instead of
-    rebuilding from the Dockerfile."""
-    path = committed_image_path(identity)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(image_tag.strip() + "\n")
-    path.chmod(0o644)
-    return path
-
-
-def read_committed_image(identity: str) -> str | None:
-    """Return the committed image tag for `identity`, or None if no
-    commit has been recorded. Used by the Docker launch step to skip
-    the Dockerfile build when a committed snapshot exists."""
-    path = committed_image_path(identity)
-    if not path.is_file():
-        return None
-    tag = path.read_text().strip()
-    return tag or None
-
-
-def per_bottle_image_tag(identity: str) -> str:
-    """Image tag for a rebuilt bottle. Distinct from the base
-    bot-bottle-claude:latest so per-bottle rebuilds don't collide in
-    the docker image cache."""
-    return f"bot-bottle-rebuilt-{identity}:latest"
-
-
-def live_config_dir(identity: str) -> Path:
-    """Per-bottle live-config dir. Bind-mounted read-only into the
-    supervise sidecar; the host's apply paths refresh the files on
-    every operator approval so the agent's `list-*` MCP tools always
-    return current state."""
-    return bottle_state_dir(identity) / _LIVE_CONFIG_SUBDIR
-
-
-def live_routes_path(identity: str) -> Path:
-    return live_config_dir(identity) / LIVE_CONFIG_ROUTES_NAME
-
-
-def live_allowlist_path(identity: str) -> Path:
-    return live_config_dir(identity) / LIVE_CONFIG_ALLOWLIST_NAME
-
-
-def write_live_config(
-    identity: str, *, routes: str = "", allowlist: str = "",
-) -> Path:
-    """Initialise (or refresh) the live-config dir. Empty-string args
-    leave the existing file alone (caller passes only what it knows).
-    Returns the live-config dir path."""
-    d = live_config_dir(identity)
-    d.mkdir(parents=True, exist_ok=True)
-    if routes:
-        p = live_routes_path(identity)
-        p.write_text(routes)
-        p.chmod(0o644)
-    if allowlist:
-        p = live_allowlist_path(identity)
-        p.write_text(allowlist)
-        p.chmod(0o644)
-    return d
-
-
-def transcript_snapshot_dir(identity: str) -> Path:
-    """Where agent session snapshots are kept for resume flows."""
-    return bottle_state_dir(identity) / _TRANSCRIPT_SUBDIR
-
-
-# --- Per-sidecar scratch subdirs (PRD 0018 chunk 2) ------------------------
-#
-# Each sidecar gets its own subdir under the bottle's state dir for
-# bind-mount sources (config, CAs, hooks, etc.). Prepare-time writes
-# land here; the state dir's normal cleanup (`cleanup_state`) reaps
-# them along with everything else when the bottle session ends and
-# nothing requested preservation.
-
-
-def egress_state_dir(identity: str) -> Path:
-    """State subdir for the egress sidecar: routes.yaml + the
-    per-bottle mitmproxy CA. Bind-mount source from chunk 3 onward."""
-    return bottle_state_dir(identity) / _EGRESS_SUBDIR
-
-
-def git_gate_state_dir(identity: str) -> Path:
-    """State subdir for the git-gate sidecar: entrypoint + hooks +
-    per-upstream known_hosts. Bind-mount source from chunk 3
-    onward."""
-    return bottle_state_dir(identity) / _GIT_GATE_SUBDIR
-
-
-def supervise_state_dir(identity: str) -> Path:
-    """State subdir reserved for supervise sidecar bind-mount sources.
-    The queue dir is intentionally NOT under here — it lives at
-    ~/.bot-bottle/queue/<slug>/ alongside the audit logs, so it
-    survives state-dir cleanup."""
-    return bottle_state_dir(identity) / _SUPERVISE_SUBDIR
-
-
-def agent_state_dir(identity: str) -> Path:
-    """State subdir for the agent's prepare-time scratch files: the
-    env file (docker --env-file source) and the prompt file."""
-    return bottle_state_dir(identity) / _AGENT_SUBDIR
-
-
-# --- Preserve-on-close marker ----------------------------------------------
-
-
-def preserve_marker_path(identity: str) -> Path:
-    return bottle_state_dir(identity) / _PRESERVE_MARKER
-
-
-def mark_preserved(identity: str) -> Path:
-    """Mark this bottle's state for preservation across session
-    teardown so cli.py's session-end cleanup leaves the state dir
-    intact for a subsequent `cli.py resume`."""
-    path = preserve_marker_path(identity)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.touch()
-    return path
-
-
-def is_preserved(identity: str) -> bool:
-    return preserve_marker_path(identity).exists()
-
-
-def clear_preserve_marker(identity: str) -> None:
-    """Idempotent removal. Called at fresh launch (start or resume)
-    so a marker left from a prior preserved session doesn't keep
-    state alive past the next normal session-end."""
-    try:
-        preserve_marker_path(identity).unlink()
-    except FileNotFoundError:
-        pass
-
-
-def cleanup_state(identity: str) -> None:
-    """Remove the per-bottle state dir entirely. Called by cli.py
-    when a bottle session ends and is_preserved(identity) is False.
-    Idempotent — missing dir is success."""
-    import shutil
-    state_dir = bottle_state_dir(identity)
-    if state_dir.is_dir():
-        shutil.rmtree(state_dir, ignore_errors=True)
-
-
-__all__ = [
-    "BottleMetadata",
-    "agent_state_dir",
-    "bottle_identity",
-    "bottle_state_dir",
-    "cleanup_state",
-    "clear_preserve_marker",
-    "committed_image_path",
-    "egress_state_dir",
-    "git_gate_state_dir",
-    "is_preserved",
-    "mark_preserved",
-    "metadata_path",
-    "per_bottle_dockerfile",
-    "per_bottle_dockerfile_path",
-    "per_bottle_image_tag",
-    "preserve_marker_path",
-    "read_committed_image",
-    "read_metadata",
-    "supervise_state_dir",
-    "transcript_snapshot_dir",
-    "write_committed_image",
-    "write_metadata",
-    "write_per_bottle_dockerfile",
-]
+from .bottle.state import *  # noqa: F403

bot_bottle/cli/__init__.py

@@ -9,6 +9,7 @@ import sys
 
 from ..log import Die, die, error
 from ..manifest import ManifestError
+from ..store_manager import StoreManager
 from ._common import PROG
 from . import list as _list_mod
 from .cleanup import cmd_cleanup
@@ -74,6 +75,19 @@ def main(argv: list[str] | None = None) -> int:
     if handler is None:
         usage()
         die(f"unknown command: {command}")
+    mgr = StoreManager.instance()
+    if not mgr.is_migrated():
+        sys.stderr.write("bot-bottle: database schema is out of date\n")
+        sys.stderr.write("Migrate now? [y/N] ")
+        sys.stderr.flush()
+        try:
+            answer = sys.stdin.readline().strip().lower()
+        except EOFError:
+            answer = ""
+        if answer != "y":
+            error("migration required — re-run and confirm to migrate")
+            return 1
+        mgr.migrate()
     try:
         return handler(rest) or 0
     except ManifestError as e:

bot_bottle/cli/commit.py

@@ -14,7 +14,7 @@ import argparse
 
 from ..backend import enumerate_active_agents
 from ..backend.freeze import CommitCancelled, get_freezer
-from ..bottle_state import read_metadata
+from ..bottle.state import read_metadata
 from ..log import die
 from ._common import PROG
 from . import tui

bot_bottle/cli/resume.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 import argparse
 
 from ..backend import BottleSpec
-from ..bottle_state import read_metadata
+from ..bottle.state import read_metadata
 from ..log import die
 from ..manifest import ManifestIndex
 from ._common import PROG, USER_CWD
@@ -27,12 +27,34 @@ from .start import _launch_bottle
 def cmd_resume(argv: list[str]) -> int:
     parser = argparse.ArgumentParser(prog=f"{PROG} resume", add_help=True)
     parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument(
+        "--headless",
+        action="store_true",
+        help=(
+            "non-interactive rehydrate: deliver --prompt to the agent and "
+            "skip the y/N preflight. For orchestrators / the freeze-rehydrate "
+            "loop."
+        ),
+    )
+    parser.add_argument(
+        "--prompt",
+        default=None,
+        help="follow-up prompt delivered to the agent (required with --headless)",
+    )
     parser.add_argument(
         "identity",
         help="bottle identity from a prior `start` (see its session-end output)",
     )
     args = parser.parse_args(argv)
 
+    if args.prompt and not args.headless:
+        die("--prompt is only valid with --headless")
+    if args.headless and not args.prompt:
+        die(
+            "--headless requires --prompt: "
+            "./cli.py resume <identity> --headless --prompt 'Address the review'"
+        )
+
     metadata = read_metadata(args.identity)
     if metadata is None:
         die(
@@ -52,8 +74,11 @@ def cmd_resume(argv: list[str]) -> int:
         bottle_names=tuple(metadata.bottle_names),
     )
     backend_name = metadata.backend or None
-    return _launch_bottle(
+    _, rc = _launch_bottle(
         spec,
         dry_run=args.dry_run,
         backend_name=backend_name,
+        assume_yes=args.headless,
+        headless_prompt_text=args.prompt or "",
     )
+    return rc

bot_bottle/cli/start.py

@@ -2,6 +2,11 @@
 interactive claude-code session. The container is torn down when the
 session ends.
 
+`--headless` selects a non-interactive launch (agent/bottles/label from
+flags, no TUI selectors, no y/N prompt) for orchestrators,
+CI, and webhook dispatch. The agent still execs on the inherited
+stdio/PTY, so an orchestrator that allocates the PTY drives the session.
+
 The launch core is shared with `cli.py resume <identity>` through
 the private orchestrator `_launch_bottle`.
 """
@@ -16,7 +21,7 @@ import tempfile
 from pathlib import Path
 from typing import Callable
 
-from ..agent_provider import runtime_for
+from ..agent_provider import get_provider, runtime_for
 from ..backend import (
     Bottle,
     BottleSpec,
@@ -26,12 +31,12 @@ from ..backend import (
 )
 from ..backend.docker import util as docker_mod
 from ..backend.docker.bottle_plan import DockerBottlePlan
-from ..bottle_state import (
+from ..bottle.state import (
     cleanup_state,
     is_preserved,
     mark_preserved,
 )
-from ..log import info
+from ..log import info, die
 from ..manifest import Manifest, ManifestIndex
 from ._common import PROG, USER_CWD, read_tty_line
 from . import tui
@@ -50,6 +55,39 @@ def cmd_start(argv: list[str]) -> int:
             "or host auto-selection). Overrides the env var when set."
         ),
     )
+    parser.add_argument(
+        "--headless",
+        action="store_true",
+        help=(
+            "non-interactive launch: take agent/bottles/label from flags, "
+            "skip all prompts. For orchestrators, CI, and webhooks."
+        ),
+    )
+    parser.add_argument(
+        "--bottle",
+        action="append",
+        default=None,
+        metavar="NAME",
+        help=(
+            "bottle to compose, repeatable (order = merge order). In "
+            "--headless, defaults to the agent's own bottle when omitted."
+        ),
+    )
+    parser.add_argument(
+        "--label",
+        default=None,
+        help="bottle label / terminal title (--headless default: agent name)",
+    )
+    parser.add_argument(
+        "--color",
+        default=None,
+        help="bottle color, one of the 16 ANSI color names (--headless default: none)",
+    )
+    parser.add_argument(
+        "--prompt",
+        default=None,
+        help="initial task prompt delivered to the agent (required with --headless)",
+    )
     parser.add_argument(
         "name",
         nargs="?",
@@ -61,6 +99,12 @@ def cmd_start(argv: list[str]) -> int:
     dry_run = args.dry_run or os.environ.get("BOT_BOTTLE_DRY_RUN") == "1"
 
     manifest = ManifestIndex.resolve(USER_CWD)
+    backend_name: str | None = args.backend
+
+    if args.headless:
+        return _start_headless(
+            manifest, args, dry_run=dry_run, backend_name=backend_name
+        )
 
     agent_name: str | None = args.name
     if agent_name is None:
@@ -71,8 +115,6 @@ def cmd_start(argv: list[str]) -> int:
         if agent_name is None:
             return 0
 
-    backend_name: str | None = args.backend
-
     # Bottle multiselect: always show after agent selection so operators
     # can compose bottles at launch time without editing agent manifests.
     available_bottles = manifest.all_bottle_names
@@ -102,11 +144,90 @@ def cmd_start(argv: list[str]) -> int:
         color=color,
         bottle_names=bottle_names,
     )
-    return _launch_bottle(
+    _, rc = _launch_bottle(
         spec,
         dry_run=dry_run,
         backend_name=backend_name,
     )
+    return rc
+
+
+# --- Headless launch -----------------------------------------------------
+
+
+def _start_headless(
+    manifest: ManifestIndex,
+    args: argparse.Namespace,
+    *,
+    dry_run: bool,
+    backend_name: str | None,
+) -> int:
+    """Non-interactive launch path for orchestrators / CI / webhooks.
+
+    Resolves agent, bottles, label, and color from flags + manifest
+    defaults instead of the TUI selectors, and auto-confirms the
+    preflight. Otherwise runs the same launch core as the interactive
+    path, so the agent still execs on the inherited stdio/PTY — an
+    orchestrator allocates that PTY and relays it to its
+    desktop/mobile clients."""
+    agent_name = args.name
+    if not agent_name:
+        die("--headless requires an agent name: ./cli.py start <agent> --headless")
+    manifest.require_agent(agent_name)  # raises ManifestError if unknown
+
+    prompt = args.prompt
+    if not prompt:
+        die(
+            "--headless requires --prompt: "
+            "./cli.py start <agent> --headless --prompt 'Do the thing'"
+        )
+
+    if args.bottle:
+        bottle_names: tuple[str, ...] = tuple(args.bottle)
+    else:
+        default_bottle = _peek_agent_bottle(manifest, agent_name)
+        if not default_bottle:
+            die(
+                f"--headless: agent '{agent_name}' has no default bottle; "
+                f"pass one or more --bottle NAME"
+            )
+        bottle_names = (default_bottle,)
+
+    label = _uniquify_label_headless(args.label or agent_name)
+
+    spec = BottleSpec(
+        manifest=manifest,
+        agent_name=agent_name,
+        copy_cwd=args.cwd,
+        user_cwd=USER_CWD,
+        label=label,
+        color=args.color or "",
+        bottle_names=bottle_names,
+    )
+    _, rc = _launch_bottle(
+        spec,
+        dry_run=dry_run,
+        backend_name=backend_name,
+        assume_yes=True,
+        headless_prompt_text=prompt,
+    )
+    return rc
+
+
+def _uniquify_label_headless(label: str) -> str:
+    """Non-interactive analog of `_resolve_unique_label`: if the label's
+    slug collides with a running bottle, append -2, -3, … until free,
+    logging the chosen label. Orchestrators fire-and-forget many bottles,
+    so silently picking a free name beats erroring on every collision."""
+    active_slugs = {a.slug for a in enumerate_active_agents()}
+    if docker_mod.slugify(label) not in active_slugs:
+        return label
+    n = 2
+    while docker_mod.slugify(f"{label}-{n}") in active_slugs:
+        n += 1
+    chosen = f"{label}-{n}"
+    info(f"label '{label}' already in use; using '{chosen}'")
+    return chosen
 
 
 # --- Launch helpers ------------------------------------------------------
@@ -376,31 +497,53 @@ def _launch_bottle(
     *,
     dry_run: bool,
     backend_name: str | None = None,
-) -> int:
+    assume_yes: bool = False,
+    headless_prompt_text: str = "",
+) -> tuple[str, int]:
     """Shared launch core for `start` and `resume`. Builds the plan,
     prints / dry-runs / prompts as appropriate, brings the bottle up,
-    attaches claude, and prints the resume hint on session end."""
+    attaches claude, and prints the resume hint on session end.
+
+    Returns ``(slug, exit_code)`` where ``slug`` is the bottle identity
+    (empty string when the launch was aborted before a slug was minted)
+    and ``exit_code`` is the agent process's exit code (0 on clean exit
+    or when launch was aborted before the agent ran).
+
+    `assume_yes` skips the interactive y/N confirmation (headless /
+    orchestrator launches), where there is no human at the prompt.
+
+    `headless_prompt_text` is passed to the provider's `headless_prompt`
+    method and the resulting args are appended to startup_args so the
+    agent receives the initial task without interactive input."""
     stage_dir = Path(tempfile.mkdtemp(prefix="bot-bottle-stage."))
     identity = ""
+    exit_code = 0
     try:
         plan, identity = prepare_with_preflight(
             spec,
             stage_dir=stage_dir,
             render_preflight=_text_render_preflight(),
-            prompt_yes=_text_prompt_yes,
+            prompt_yes=(lambda: True) if assume_yes else _text_prompt_yes,
             dry_run=dry_run,
             backend_name=backend_name,
         )
         if plan is None:
-            return 0
+            return identity, 0
 
         backend = get_bottle_backend(backend_name)
         with backend.launch(plan) as bottle:
             agent_provider_template = getattr(plan, "agent_provider_template", "claude")
+            extra_args: tuple[str, ...] = ()
+            if headless_prompt_text:
+                extra_args = tuple(
+                    get_provider(agent_provider_template).headless_prompt(
+                        headless_prompt_text
+                    )
+                )
             exit_code = attach_agent(
                 bottle,
                 agent_provider_template=agent_provider_template,
-                startup_args=plan.agent_provision.startup_args,
+                startup_args=plan.agent_provision.startup_args + extra_args,
             )
             info(
                 f"session ended (exit {exit_code}); "
@@ -412,7 +555,7 @@ def _launch_bottle(
             # Ctrl-Cs / OOM kills before cleanup removes the state dir.
             if agent_provider_template == "claude":
                 capture_claude_session_state(identity, exit_code)
-        return 0
+        return identity, exit_code
     finally:
         # PRD 0018 chunk 2: prepare now writes the bottle's bind-mount
         # sources under state/<slug>/. If we never reached the

bot_bottle/cli/supervise.py

@@ -20,7 +20,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from .. import supervise as _supervise
-from ..bottle_state import read_metadata
+from ..bottle.state import read_metadata
 from ..backend.docker.egress_apply import (
     EgressApplyError,
     applicator as _docker_applicator,
@@ -45,7 +45,7 @@ from ..supervise import (
     TOOL_EGRESS_BLOCK,
     TOOL_GITLEAKS_ALLOW,
     TOOL_EGRESS_TOKEN_ALLOW,
-    list_pending_proposals,
+    list_all_pending_proposals,
     render_diff,
     write_audit_entry,
     write_response,
@@ -63,10 +63,9 @@ _REPORT_ONLY_TOOLS: tuple[str, ...] = (TOOL_GITLEAKS_ALLOW, TOOL_EGRESS_TOKEN_AL
 
 @dataclass(frozen=True)
 class QueuedProposal:
-    """A pending proposal plus the queue dir it was found in."""
+    """A pending proposal from the supervise queue."""
 
     proposal: Proposal
-    queue_dir: Path
 
 
 # Errors any remediation engine may raise. Caught by the TUI key
@@ -86,16 +85,11 @@ def apply_routes_change(slug: str, content: str) -> tuple[str, str]:
 
 
 def discover_pending() -> list[QueuedProposal]:
-    """Walk ~/.bot-bottle/queue/* and collect pending proposals."""
-    queue_root = _supervise.bot_bottle_root() / "queue"
-    if not queue_root.is_dir():
-        return []
-    out: list[QueuedProposal] = []
-    for slug_dir in sorted(queue_root.iterdir()):
-        if not slug_dir.is_dir():
-            continue
-        for proposal in list_pending_proposals(slug_dir):
-            out.append(QueuedProposal(proposal=proposal, queue_dir=slug_dir))
+    """Collect pending proposals across bottles."""
+    out = [
+        QueuedProposal(proposal=proposal)
+        for proposal in list_all_pending_proposals()
+    ]
     out.sort(key=lambda q: q.proposal.arrival_timestamp)
     return out
 
@@ -118,7 +112,6 @@ def _detail_lines(
         (f"tool: {p.tool}", 0),
         (f"id: {p.id}", 0),
         (f"arrived: {p.arrival_timestamp}", 0),
-        (f"queue: {qp.queue_dir}", 0),
         ("", 0),
         ("justification:", 0),
     ]
@@ -165,7 +158,7 @@ def approve(
         notes=notes,
         final_file=final_file,
     )
-    write_response(qp.queue_dir, response)
+    write_response(qp.proposal.bottle_slug, response)
     _write_audit(
         qp, action=status, notes=notes,
         diff_before=diff_before, diff_after=diff_after,
@@ -179,7 +172,7 @@ def reject(qp: QueuedProposal, *, reason: str) -> None:
         notes=reason,
         final_file=None,
     )
-    write_response(qp.queue_dir, response)
+    write_response(qp.proposal.bottle_slug, response)
     _write_audit(qp, action=STATUS_REJECTED, notes=reason, diff_before="", diff_after="")
 
 

bot_bottle/contrib/claude/agent_provider.py

@@ -217,7 +217,7 @@ class ClaudeAgentProvider(AgentProvider):
         if not agent.skills:
             return
         skills_dir = _skills_dir(plan.guest_home)
-        bottle.exec(f"mkdir -p {skills_dir}", user="root")
+        bottle.exec(f"mkdir -p {shlex.quote(skills_dir)}", user="root")
         for name in agent.skills:
             src = host_skill_dir(name)
             if not os.path.isdir(src):
@@ -227,9 +227,13 @@ class ClaudeAgentProvider(AgentProvider):
                 )
             dst = f"{skills_dir}/{name}"
             info(f"copying skill {name} into {bottle.name}:{dst}")
-            bottle.exec(f"rm -rf {dst} && mkdir -p {dst}", user="root")
+            # Defense in depth: skill names are validated kebab-case at
+            # manifest load, but quote the path so a future unvalidated
+            # field can't inject shell metacharacters here either.
+            dst_q = shlex.quote(dst)
+            bottle.exec(f"rm -rf {dst_q} && mkdir -p {dst_q}", user="root")
             bottle.cp_in(f"{src}/.", f"{dst}/")
-            bottle.exec(f"chown -R node:node {dst}", user="root")
+            bottle.exec(f"chown -R node:node {dst_q}", user="root")
 
     def provision_prompt(self, plan: "BottlePlan", bottle: "Bottle") -> str | None:
         """Copy the prompt file into the guest, fix ownership/mode.
@@ -309,6 +313,9 @@ class ClaudeAgentProvider(AgentProvider):
                 f"claude mcp add --scope user --transport http supervise {supervise_url}"
             )
 
+    def headless_prompt(self, prompt: str) -> list[str]:
+        return ["-p", prompt]
+
 
 def _exec(bottle: "Bottle", script: str, error: str) -> None:
     result = bottle.exec(script, user="root")

bot_bottle/contrib/codex/agent_provider.py

@@ -183,7 +183,7 @@ class CodexAgentProvider(AgentProvider):
         if not agent.skills:
             return
         skills_dir = _skills_dir(plan.guest_home)
-        bottle.exec(f"mkdir -p {skills_dir}", user="root")
+        bottle.exec(f"mkdir -p {shlex.quote(skills_dir)}", user="root")
         for name in agent.skills:
             src = host_skill_dir(name)
             if not os.path.isdir(src):
@@ -193,9 +193,13 @@ class CodexAgentProvider(AgentProvider):
                 )
             dst = f"{skills_dir}/{name}"
             info(f"copying skill {name} into {bottle.name}:{dst}")
-            bottle.exec(f"rm -rf {dst} && mkdir -p {dst}", user="root")
+            # Defense in depth: skill names are validated kebab-case at
+            # manifest load, but quote the path so a future unvalidated
+            # field can't inject shell metacharacters here either.
+            dst_q = shlex.quote(dst)
+            bottle.exec(f"rm -rf {dst_q} && mkdir -p {dst_q}", user="root")
             bottle.cp_in(f"{src}/.", f"{dst}/")
-            bottle.exec(f"chown -R node:node {dst}", user="root")
+            bottle.exec(f"chown -R node:node {dst_q}", user="root")
 
     def provision_prompt(self, plan: "BottlePlan", bottle: "Bottle") -> str | None:
         """Copy the prompt file into the guest, fix ownership/mode.
@@ -275,6 +279,9 @@ class CodexAgentProvider(AgentProvider):
                 f"codex mcp add supervise --url {shlex.quote(supervise_url)}"
             )
 
+    def headless_prompt(self, prompt: str) -> list[str]:
+        return [prompt]
+
 
 def _exec(bottle: "Bottle", script: str, error: str) -> None:
     result = bottle.exec(script, user="root")

bot_bottle/contrib/forge/base.py

@@ -0,0 +1,165 @@
+"""Forge abstraction (PRD forge-native-integration, chunk 3).
+
+The `Forge` abstract class is the provider-agnostic surface a forge
+sidecar dispatches to: read issues/comments, post comments, edit
+descriptions, and the membership / PR lookups the orchestrator needs.
+Each forge (Gitea first) implements it; the sidecar protocol and the
+agent prompt stay forge-agnostic.
+
+`signal_done` is deliberately *not* a `Forge` method — completion is a
+sidecar concept relayed to the orchestrator over a queue dir, not a
+forge API operation.
+
+`ScopedForge` enforces the PRD's **read-anywhere / write-scoped** model:
+reads pass through to any issue/PR for context; writes are rejected
+unless the target is the assigned issue or one of its PRs. This bounds
+the blast radius of a prompt-injected agent below repo-wide API-key
+permissions.
+"""
+
+from __future__ import annotations
+
+import abc
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Issue:
+    """A forge issue (not a PR — see `PullRequest`)."""
+
+    number: int
+    title: str
+    body: str
+    state: str  # "open" | "closed"
+
+
+@dataclass(frozen=True)
+class PullRequest:
+    """A forge pull request. Kept distinct from `Issue` even though some
+    forges model PRs as issues on the wire: the domain objects carry
+    different data (a PR has merge state) and are read through different
+    methods (`read_pr` vs `read_issue`)."""
+
+    number: int
+    title: str
+    body: str
+    state: str  # "open" | "closed"
+    merged: bool
+
+
+@dataclass(frozen=True)
+class Comment:
+    id: int
+    user: str  # login of the comment author
+    body: str
+
+
+class ForgeScopeError(PermissionError):
+    """Raised by `ScopedForge` when a write targets an issue/PR outside
+    the assigned scope."""
+
+
+class Forge(abc.ABC):
+    """Provider-agnostic forge operations. Implementations wrap a
+    per-provider HTTP client and translate to `Issue` / `Comment`."""
+
+    @abc.abstractmethod
+    def read_issue(self, number: int) -> Issue:
+        """Read an issue body (read-anywhere)."""
+
+    @abc.abstractmethod
+    def read_pr(self, number: int) -> PullRequest:
+        """Read a pull request, including its merge state (read-anywhere)."""
+
+    @abc.abstractmethod
+    def read_comments(self, number: int) -> list[Comment]:
+        """Read a thread's comments (read-anywhere)."""
+
+    @abc.abstractmethod
+    def post_comment(self, number: int, body: str) -> None:
+        """Post a comment to an issue or PR (write-scoped)."""
+
+    @abc.abstractmethod
+    def update_description(self, number: int, body: str) -> None:
+        """Replace an issue or PR body (write-scoped)."""
+
+    @abc.abstractmethod
+    def is_org_member(self, org: str, username: str) -> bool:
+        """Whether `username` is a member of `org`."""
+
+    @abc.abstractmethod
+    def get_pr_for_issue(self, number: int) -> int | None:
+        """The PR number linked to an issue, or None when there is none."""
+
+    @abc.abstractmethod
+    def is_pr_open(self, number: int) -> bool:
+        """Whether the given PR is still open."""
+
+
+class ScopedForge(Forge):
+    """Read-anywhere / write-scoped wrapper around a concrete `Forge`.
+
+    `post_comment` and `update_description` are rejected with
+    `ForgeScopeError` unless the target number is the assigned issue or
+    one of the assigned PRs. Every other method delegates unchanged, so
+    reads, membership checks, and PR lookups work against any number for
+    context.
+
+    The writable set is fixed at construction. The sidecar reconstructs
+    a `ScopedForge` when a PR is discovered (`get_pr_for_issue`) so the
+    new PR becomes writable; this class does not mutate its own scope.
+    """
+
+    def __init__(
+        self,
+        inner: Forge,
+        *,
+        assigned_issue: int,
+        assigned_prs: Iterable[int] = (),
+    ) -> None:
+        self._inner = inner
+        self._assigned_issue = assigned_issue
+        self._writable = {assigned_issue, *assigned_prs}
+
+    @property
+    def writable(self) -> frozenset[int]:
+        return frozenset(self._writable)
+
+    def _check_write(self, number: int) -> None:
+        if number not in self._writable:
+            allowed = ", ".join(str(n) for n in sorted(self._writable))
+            raise ForgeScopeError(
+                f"write to #{number} denied: out of assigned scope "
+                f"(writable: {allowed})"
+            )
+
+    # --- read-anywhere: pass through --------------------------------------
+
+    def read_issue(self, number: int) -> Issue:
+        return self._inner.read_issue(number)
+
+    def read_pr(self, number: int) -> PullRequest:
+        return self._inner.read_pr(number)
+
+    def read_comments(self, number: int) -> list[Comment]:
+        return self._inner.read_comments(number)
+
+    def is_org_member(self, org: str, username: str) -> bool:
+        return self._inner.is_org_member(org, username)
+
+    def get_pr_for_issue(self, number: int) -> int | None:
+        return self._inner.get_pr_for_issue(number)
+
+    def is_pr_open(self, number: int) -> bool:
+        return self._inner.is_pr_open(number)
+
+    # --- write-scoped: check then delegate --------------------------------
+
+    def post_comment(self, number: int, body: str) -> None:
+        self._check_write(number)
+        self._inner.post_comment(number, body)
+
+    def update_description(self, number: int, body: str) -> None:
+        self._check_write(number)
+        self._inner.update_description(number, body)

bot_bottle/contrib/gitea/client.py

@@ -0,0 +1,174 @@
+"""Gitea HTTP client + `GiteaForge` (PRD forge-native-integration, chunk 3).
+
+`GiteaClient` is the thin stdlib-only HTTP transport (mirrors
+`deploy_key_provisioner.py`: `urllib.request`, bounded timeouts,
+structured error bodies). `GiteaForge` adapts it to the provider-agnostic
+`Forge` surface.
+
+Unlike the option-2 design, the token is held here (the sidecar process
+owns it) and passed to the client directly — there is no agent-side
+cred-proxy route, because the agent never makes forge calls. The HTTP
+client is the one piece shared with `GiteaDeployKeyProvisioner`; the two
+are deliberately *not* unified behind a common abstract base (see the
+deferral note in the PRD).
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+from ..forge.base import Comment, Forge, Issue, PullRequest
+
+# Bound every Gitea call: a hung instance must not stall the sidecar.
+_API_TIMEOUT_SECS = 30
+
+
+class GiteaClient:
+    """Thin authenticated HTTP client for one repo's Gitea API.
+
+    `api_url` is the API base *including* `/api/v1` (matching the
+    `FORGE_GITEA_API` env var), e.g. `https://gitea.example.com/api/v1`.
+    """
+
+    def __init__(self, *, api_url: str, owner: str, repo: str, token: str) -> None:
+        self._api_url = api_url.rstrip("/")
+        self._owner = owner
+        self._repo = repo
+        self._token = token
+
+    # --- low-level request -------------------------------------------------
+
+    def _request(
+        self, method: str, path: str, *, body: dict[str, Any] | None = None
+    ) -> tuple[int, Any]:
+        """Issue an authenticated request. Returns `(status, parsed_json)`;
+        parsed_json is None when the response has no body. Raises
+        `RuntimeError` on any non-2xx except where callers special-case
+        the HTTPError themselves (membership 404)."""
+        url = f"{self._api_url}{path}"
+        data = json.dumps(body).encode() if body is not None else None
+        headers = {"Authorization": f"token {self._token}"}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        with urllib.request.urlopen(req, timeout=_API_TIMEOUT_SECS) as resp:
+            raw = resp.read()
+            parsed = json.loads(raw) if raw else None
+            return resp.status, parsed
+
+    def _repo_path(self, suffix: str) -> str:
+        return f"/repos/{self._owner}/{self._repo}{suffix}"
+
+    # --- operations --------------------------------------------------------
+
+    def is_org_member(self, org: str, username: str) -> bool:
+        """GET /orgs/{org}/members/{username}: 2xx → member, 404 → not.
+        Other errors propagate so a misconfigured token fails loudly."""
+        url = f"{self._api_url}/orgs/{org}/members/{username}"
+        req = urllib.request.Request(
+            url, headers={"Authorization": f"token {self._token}"}, method="GET"
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=_API_TIMEOUT_SECS):
+                return True
+        except urllib.error.HTTPError as exc:
+            if exc.code == 404:
+                return False
+            raise RuntimeError(
+                f"org membership check failed for {org}/{username}: "
+                f"HTTP {exc.code} — {_read_error_body(exc)}"
+            ) from exc
+
+    def get_issue(self, number: int) -> dict[str, Any]:
+        _status, body = self._request("GET", self._repo_path(f"/issues/{number}"))
+        return body or {}
+
+    def get_comments(self, number: int) -> list[dict[str, Any]]:
+        _status, body = self._request(
+            "GET", self._repo_path(f"/issues/{number}/comments")
+        )
+        return body or []
+
+    def post_comment(self, number: int, body: str) -> None:
+        self._request(
+            "POST",
+            self._repo_path(f"/issues/{number}/comments"),
+            body={"body": body},
+        )
+
+    def patch_issue_body(self, number: int, body: str) -> None:
+        self._request(
+            "PATCH", self._repo_path(f"/issues/{number}"), body={"body": body}
+        )
+
+    def get_pull(self, number: int) -> dict[str, Any]:
+        _status, body = self._request("GET", self._repo_path(f"/pulls/{number}"))
+        return body or {}
+
+
+class GiteaForge(Forge):
+    """`Forge` over a `GiteaClient`."""
+
+    def __init__(self, client: GiteaClient) -> None:
+        self._client = client
+
+    def read_issue(self, number: int) -> Issue:
+        raw = self._client.get_issue(number)
+        return Issue(
+            number=int(raw.get("number", number)),
+            title=str(raw.get("title", "")),
+            body=str(raw.get("body", "") or ""),
+            state=str(raw.get("state", "")),
+        )
+
+    def read_pr(self, number: int) -> PullRequest:
+        raw = self._client.get_pull(number)
+        return PullRequest(
+            number=int(raw.get("number", number)),
+            title=str(raw.get("title", "")),
+            body=str(raw.get("body", "") or ""),
+            state=str(raw.get("state", "")),
+            merged=bool(raw.get("merged", False)),
+        )
+
+    def read_comments(self, number: int) -> list[Comment]:
+        return [
+            Comment(
+                id=int(c.get("id", 0)),
+                user=str((c.get("user") or {}).get("login", "")),
+                body=str(c.get("body", "") or ""),
+            )
+            for c in self._client.get_comments(number)
+        ]
+
+    def post_comment(self, number: int, body: str) -> None:
+        self._client.post_comment(number, body)
+
+    def update_description(self, number: int, body: str) -> None:
+        self._client.patch_issue_body(number, body)
+
+    def is_org_member(self, org: str, username: str) -> bool:
+        return self._client.is_org_member(org, username)
+
+    def get_pr_for_issue(self, number: int) -> int | None:
+        """Gitea models a PR as an issue with the same number, exposing a
+        `pull_request` object on the issue. When the queried number is
+        itself a PR, return it; otherwise None. (The orchestrator tracks
+        the issue→PR mapping in forge state for the cross-number case.)"""
+        raw = self._client.get_issue(number)
+        if raw.get("pull_request"):
+            return int(raw.get("number", number))
+        return None
+
+    def is_pr_open(self, number: int) -> bool:
+        return self.read_pr(number).state == "open"
+
+
+def _read_error_body(exc: urllib.error.HTTPError) -> str:
+    try:
+        return exc.read().decode("utf-8", errors="replace")
+    except Exception:  # pylint: disable=broad-exception-caught
+        return ""

bot_bottle/contrib/gitea/forge_state.py

@@ -0,0 +1,171 @@
+"""Forge state persistence (PRD forge-native-integration, chunk 2).
+
+The orchestrator tracks one record per forge-targeted issue so it can
+map an incoming webhook back to the bottle handling it, drive the
+freeze / rehydrate loop, and run the watchdog.
+
+State is stored in a local SQLite database in `~/.bot-bottle/`. Access
+goes through the thin `ForgeStateStore` CRUD interface so the backing
+store (location or engine) can be swapped without touching callers;
+`SqliteForgeStateStore` is the first implementation.
+"""
+
+from __future__ import annotations
+
+import abc
+import json
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ...supervise import bot_bottle_root
+
+_DB_FILENAME = "bot-bottle.db"
+
+# Lifecycle: a bottle is launched (running), frozen on the done signal,
+# and destroyed when the PR closes.
+STATUS_RUNNING = "running"
+STATUS_FROZEN = "frozen"
+STATUS_DESTROYED = "destroyed"
+
+
+@dataclass
+class ForgeState:
+    """One forge-targeted issue's bottle lifecycle record."""
+
+    owner: str
+    repo: str
+    issue_number: int
+    slug: str
+    agent_name: str
+    bottle_names: list[str] = field(default_factory=list)
+    backend_name: str = ""
+    agent_git_user: str = ""
+    pr_number: int | None = None
+    status: str = STATUS_RUNNING
+    last_checkin_at: str = ""
+
+
+class ForgeStateStore(abc.ABC):
+    """Thin CRUD surface over forge state. Implementations back it with a
+    concrete store; callers depend only on this interface so the storage
+    location/engine is swappable."""
+
+    @abc.abstractmethod
+    def upsert(self, state: ForgeState) -> None:
+        """Insert or replace the record keyed by (owner, repo, issue)."""
+
+    @abc.abstractmethod
+    def get(self, owner: str, repo: str, issue_number: int) -> ForgeState | None:
+        """Fetch one record, or None when absent."""
+
+    @abc.abstractmethod
+    def delete(self, owner: str, repo: str, issue_number: int) -> None:
+        """Remove a record. Missing is success (idempotent)."""
+
+    @abc.abstractmethod
+    def all(self) -> list[ForgeState]:
+        """Every record, for the status table and the watchdog sweep."""
+
+
+def default_db_path() -> Path:
+    return bot_bottle_root() / _DB_FILENAME
+
+
+class SqliteForgeStateStore(ForgeStateStore):
+    """SQLite-backed `ForgeStateStore`. The database lives at
+    `~/.bot-bottle/bot-bottle.db` by default; pass `db_path` to point at
+    a different location (tests, alternate homes)."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self._db_path = db_path or default_db_path()
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        with self._connect() as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS forge_state (
+                    owner           TEXT    NOT NULL,
+                    repo            TEXT    NOT NULL,
+                    issue_number    INTEGER NOT NULL,
+                    slug            TEXT    NOT NULL,
+                    agent_name      TEXT    NOT NULL,
+                    bottle_names    TEXT    NOT NULL,
+                    backend_name    TEXT    NOT NULL,
+                    agent_git_user  TEXT    NOT NULL,
+                    pr_number       INTEGER,
+                    status          TEXT    NOT NULL,
+                    last_checkin_at TEXT    NOT NULL,
+                    PRIMARY KEY (owner, repo, issue_number)
+                )
+                """
+            )
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._db_path)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def upsert(self, state: ForgeState) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO forge_state (
+                    owner, repo, issue_number, slug, agent_name,
+                    bottle_names, backend_name, agent_git_user,
+                    pr_number, status, last_checkin_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    state.owner,
+                    state.repo,
+                    state.issue_number,
+                    state.slug,
+                    state.agent_name,
+                    json.dumps(state.bottle_names),
+                    state.backend_name,
+                    state.agent_git_user,
+                    state.pr_number,
+                    state.status,
+                    state.last_checkin_at,
+                ),
+            )
+
+    def get(self, owner: str, repo: str, issue_number: int) -> ForgeState | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT * FROM forge_state "
+                "WHERE owner = ? AND repo = ? AND issue_number = ?",
+                (owner, repo, issue_number),
+            ).fetchone()
+        return _row_to_state(row) if row is not None else None
+
+    def delete(self, owner: str, repo: str, issue_number: int) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                "DELETE FROM forge_state "
+                "WHERE owner = ? AND repo = ? AND issue_number = ?",
+                (owner, repo, issue_number),
+            )
+
+    def all(self) -> list[ForgeState]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT * FROM forge_state ORDER BY owner, repo, issue_number"
+            ).fetchall()
+        return [_row_to_state(row) for row in rows]
+
+
+def _row_to_state(row: sqlite3.Row) -> ForgeState:
+    return ForgeState(
+        owner=row["owner"],
+        repo=row["repo"],
+        issue_number=row["issue_number"],
+        slug=row["slug"],
+        agent_name=row["agent_name"],
+        bottle_names=json.loads(row["bottle_names"]),
+        backend_name=row["backend_name"],
+        agent_git_user=row["agent_git_user"],
+        pr_number=row["pr_number"],
+        status=row["status"],
+        last_checkin_at=row["last_checkin_at"],
+    )

bot_bottle/contrib/pi/agent_provider.py

@@ -238,7 +238,7 @@ class PiAgentProvider(AgentProvider):
         if not agent.skills:
             return
         skills_dir = _skills_dir(plan.guest_home)
-        bottle.exec(f"mkdir -p {skills_dir}", user="root")
+        bottle.exec(f"mkdir -p {shlex.quote(skills_dir)}", user="root")
         for name in agent.skills:
             src = host_skill_dir(name)
             if not os.path.isdir(src):
@@ -248,9 +248,13 @@ class PiAgentProvider(AgentProvider):
                 )
             dst = f"{skills_dir}/{name}"
             info(f"copying skill {name} into {bottle.name}:{dst}")
-            bottle.exec(f"rm -rf {dst} && mkdir -p {dst}", user="root")
+            # Defense in depth: skill names are validated kebab-case at
+            # manifest load, but quote the path so a future unvalidated
+            # field can't inject shell metacharacters here either.
+            dst_q = shlex.quote(dst)
+            bottle.exec(f"rm -rf {dst_q} && mkdir -p {dst_q}", user="root")
             bottle.cp_in(f"{src}/.", f"{dst}/")
-            bottle.exec(f"chown -R node:node {dst}", user="root")
+            bottle.exec(f"chown -R node:node {dst_q}", user="root")
 
     def provision_prompt(self, plan: "BottlePlan", bottle: "Bottle") -> str | None:
         prompt_path = _prompt_path(plan.guest_home)
@@ -311,6 +315,9 @@ class PiAgentProvider(AgentProvider):
     ) -> None:
         del plan, bottle, supervise_url
 
+    def headless_prompt(self, prompt: str) -> list[str]:
+        return ["-p", prompt]
+
 
 def _exec(bottle: "Bottle", script: str, error: str) -> None:
     result = bottle.exec(script, user="root")

bot_bottle/db_store.py

@@ -0,0 +1,59 @@
+"""Shared SQLite-backed store base class for bot-bottle (PRD 0013)."""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+try:
+    from .migrations import TableMigrations
+except ImportError:
+    from migrations import TableMigrations  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+
+
+class DbVersionError(Exception):
+    """Raised when the on-disk schema is behind the current migration list."""
+
+
+class DbStore:
+    """Base for SQLite-backed stores. Subclasses resolve db_path then call super().__init__."""
+
+    def __init__(self, db_path: Path, migrations: TableMigrations) -> None:
+        self.db_path = db_path
+        self._migrations = migrations
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def is_migrated(self) -> bool:
+        """Return True if the DB is fully up-to-date, False if migration is needed."""
+        if not self.db_path.exists():
+            return False
+        try:
+            with self._connect() as conn:
+                row = conn.execute(
+                    "SELECT version FROM schema_versions WHERE module = ?",
+                    (self._migrations.schema_key,),
+                ).fetchone()
+        except sqlite3.OperationalError:
+            return False
+        version = row[0] if row else 0
+        return version == len(self._migrations.migrations)
+
+    def migrate(self) -> None:
+        """Apply any pending migrations and set permissions on the DB file."""
+        with self._connect() as conn:
+            self._migrations.apply(conn)
+        self._chmod()
+
+    def _chmod(self) -> None:
+        try:
+            self.db_path.chmod(0o600)
+        except OSError:
+            pass
+
+
+__all__ = ["DbStore", "DbVersionError"]

bot_bottle/egress_addon.py

@@ -79,14 +79,13 @@ class EgressAddon:
         # only — a restart re-prompts. Mutated only from the asyncio loop that
         # runs the addon hooks, so no lock is needed.
         self.safe_tokens: set[str] = set()
-        self._supervise_queue_dir = os.environ.get("SUPERVISE_QUEUE_DIR", "").strip()
         self._supervise_slug = os.environ.get("SUPERVISE_BOTTLE_SLUG", "").strip()
         self._token_allow_timeout = _token_allow_timeout_from_env(os.environ)
         self._reload(initial=True)
         self._install_sighup()
 
     def _supervise_available(self) -> bool:
-        return bool(self._supervise_queue_dir and self._supervise_slug)
+        return bool(self._supervise_slug)
 
     def _reload(self, *, initial: bool = False) -> None:
         try:
@@ -393,9 +392,8 @@ class EgressAddon:
             justification=_TOKEN_ALLOW_JUSTIFICATION,
             current_file_hash=_sv.sha256_hex(payload),
         )
-        queue_dir = Path(self._supervise_queue_dir)
         try:
-            _sv.write_proposal(queue_dir, proposal)
+            _sv.write_proposal(proposal)
         except OSError as e:
             sys.stderr.write(
                 f"egress: could not queue token-allow proposal: {e}; "
@@ -411,8 +409,8 @@ class EgressAddon:
             **self._req_ctx(flow),
         }) + "\n")
 
-        response = await self._await_token_response(queue_dir, proposal.id)
-        _sv.archive_proposal(queue_dir, proposal.id)
+        response = await self._await_token_response(proposal.id)
+        _sv.archive_proposal(self._supervise_slug, proposal.id)
 
         if response is not None and response.status in (
             _sv.STATUS_APPROVED, _sv.STATUS_MODIFIED,
@@ -439,16 +437,15 @@ class EgressAddon:
 
     async def _await_token_response(
         self,
-        queue_dir: Path,
         proposal_id: str,
     ) -> "_sv.Response | None":
-        """Poll the queue dir for the operator's response without blocking the
+        """Poll the DB for the operator's response without blocking the
         proxy event loop. Returns the Response, or None on timeout."""
         loop = asyncio.get_running_loop()
         deadline = loop.time() + self._token_allow_timeout
         while True:
             try:
-                return _sv.read_response(queue_dir, proposal_id)
+                return _sv.read_response(self._supervise_slug, proposal_id)
             except (OSError, ValueError, KeyError):
                 # Not written yet, or a partial/malformed write — retry until
                 # the deadline, then fail closed.

bot_bottle/git_gate.py

@@ -30,7 +30,6 @@ backend-specific and lives on concrete subclasses (see
 
 from __future__ import annotations
 
-import dataclasses
 from abc import ABC
 from dataclasses import dataclass
 from pathlib import Path
@@ -53,6 +52,7 @@ from .git_gate_render import (
     _gitconfig_validate_value,
 )
 from .git_gate_provision import (
+    provision_git_gate_dynamic_keys,
     revoke_git_gate_provisioned_keys,
     _provision_dynamic_key,
     _resolve_identity_file,
@@ -93,20 +93,14 @@ class GitGate(ABC):
         entrypoint, pre-receive hook, and access-hook scripts (mode
         600) under `stage_dir`. Pure host-side, no docker subprocess.
 
-        For `gitea` key entries, also generates and registers
-        a fresh deploy key via the forge API and writes the private key
-        + key ID to `stage_dir`.
+        For `gitea` key entries, the returned upstream intentionally
+        has an empty identity file. Backend launch fills that in after
+        the operator confirms the preflight.
 
         Returned plan is incomplete: the launch step must fill
         `internal_network` / `egress_network` via `dataclasses.replace`
         before passing the plan to `.start`."""
-        upstreams_list = list(git_gate_upstreams_for_bottle(bottle))
-        for i, entry in enumerate(bottle.git):
-            upstreams_list[i] = dataclasses.replace(
-                upstreams_list[i],
-                identity_file=_resolve_identity_file(entry, slug, stage_dir),
-            )
-        upstreams = tuple(upstreams_list)
+        upstreams = git_gate_upstreams_for_bottle(bottle)
         entrypoint = stage_dir / "git_gate_entrypoint.sh"
         entrypoint.write_text(git_gate_render_entrypoint(upstreams))
         entrypoint.chmod(0o600)
@@ -162,6 +156,7 @@ __all__ = [
     "git_gate_render_entrypoint",
     "git_gate_render_hook",
     "git_gate_render_access_hook",
+    "provision_git_gate_dynamic_keys",
     "revoke_git_gate_provisioned_keys",
     "_gitconfig_validate_value",
     "_provision_dynamic_key",

bot_bottle/git_gate_provision.py

@@ -9,10 +9,16 @@ imported (`deploy_key_provisioner`) to keep its cost off the host path.
 from __future__ import annotations
 
 import os
+import dataclasses
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 from .log import info
 from .manifest import ManifestBottle, ManifestGitEntry
+from .git_gate_render import GitGateUpstream
+
+if TYPE_CHECKING:
+    from .git_gate import GitGatePlan
 
 def _provision_dynamic_key(
     entry: ManifestGitEntry,
@@ -95,8 +101,45 @@ def _resolve_identity_file(entry: ManifestGitEntry, slug: str, stage_dir: Path)
     return entry.IdentityFile
 
 
+def provision_git_gate_dynamic_keys(
+    bottle: ManifestBottle,
+    plan: "GitGatePlan",
+    stage_dir: Path,
+) -> "GitGatePlan":
+    """Provision dynamic git-gate keys and return an updated plan.
+
+    This runs during backend launch, after the operator confirms the
+    preflight. Plan preparation intentionally stays side-effect-light:
+    dry-runs and aborted launches must not create remote deploy keys.
+    """
+    if not plan.upstreams:
+        return plan
+
+    upstreams_by_name: dict[str, GitGateUpstream] = {
+        upstream.name: upstream for upstream in plan.upstreams
+    }
+    updated: list[GitGateUpstream] = []
+    for entry in bottle.git:
+        upstream = upstreams_by_name.get(entry.Name)
+        if upstream is None:
+            continue
+        if entry.Key.provider == "gitea":
+            identity_file = _provision_dynamic_key(entry, plan.slug, stage_dir)
+            upstream = dataclasses.replace(upstream, identity_file=identity_file)
+        updated.append(upstream)
+
+    if len(updated) != len(plan.upstreams):
+        updated_names = {u.name for u in updated}
+        for upstream in plan.upstreams:
+            if upstream.name not in updated_names:
+                updated.append(upstream)
+
+    return dataclasses.replace(plan, upstreams=tuple(updated))
+
+
 __all__ = [
     "revoke_git_gate_provisioned_keys",
+    "provision_git_gate_dynamic_keys",
     "_provision_dynamic_key",
     "_resolve_identity_file",
 ]

bot_bottle/git_gate_render.py

@@ -234,13 +234,13 @@ import hashlib
 import json
 import os
 import sys
-import uuid
 from pathlib import Path
 
+from bot_bottle import supervise as _sv
+
 report_path = Path(sys.argv[1])
-queue_dir = os.environ.get("SUPERVISE_QUEUE_DIR", "")
 slug = os.environ.get("SUPERVISE_BOTTLE_SLUG", "")
-if not queue_dir or not slug:
+if not slug:
     sys.exit(2)
 
 try:
@@ -277,31 +277,19 @@ for i, finding in enumerate(raw, 1):
     ])
 
 payload = "\n".join(lines).rstrip() + "\n"
-proposal_id = str(uuid.uuid4())
-proposal = {
-    "id": proposal_id,
-    "bottle_slug": slug,
-    "tool": "gitleaks-allow",
-    "proposed_file": payload,
-    "justification": (
+proposal = _sv.Proposal.new(
+    bottle_slug=slug,
+    tool=_sv.TOOL_GITLEAKS_ALLOW,
+    proposed_file=payload,
+    justification=(
         "git-gate found gitleaks findings hidden by # gitleaks:allow; "
         "approve only for dummy test fixtures or confirmed false positives"
     ),
-    "arrival_timestamp": datetime.datetime.now(
-        datetime.timezone.utc
-    ).isoformat(),
-    "current_file_hash": hashlib.sha256(payload.encode("utf-8")).hexdigest(),
-}
-queue = Path(queue_dir)
-queue.mkdir(parents=True, exist_ok=True)
-path = queue / f"{proposal_id}.proposal.json"
-tmp = path.with_suffix(path.suffix + ".tmp")
-with tmp.open("w", encoding="utf-8") as f:
-    json.dump(proposal, f, indent=2)
-    f.write("\n")
-os.chmod(tmp, 0o600)
-os.replace(tmp, path)
-print(proposal_id)
+    current_file_hash=hashlib.sha256(payload.encode("utf-8")).hexdigest(),
+    now=datetime.datetime.now(datetime.timezone.utc),
+)
+_sv.write_proposal(proposal)
+print(proposal.id)
 PY
   )
   rc=$?
@@ -314,8 +302,7 @@ PY
     return 1
   fi
 
-  queue_dir=${SUPERVISE_QUEUE_DIR:-}
-  response_file="$queue_dir/${proposal_id}.response.json"
+  slug=${SUPERVISE_BOTTLE_SLUG:-}
   timeout=${SUPERVISE_GITLEAKS_ALLOW_TIMEOUT_SECONDS:-300}
   case "$timeout" in
     ''|*[!0-9]*)
@@ -327,26 +314,35 @@ PY
   echo "git-gate: approve with './cli.py supervise' to continue this push" >&2
   waited=0
   while [ "$waited" -lt "$timeout" ]; do
-    if [ -f "$response_file" ]; then
-      status=$(python3 - "$response_file" <<'PY'
-import json
+    status=$(python3 - "$slug" "$proposal_id" <<'PY'
 import sys
+
+from bot_bottle import supervise as _sv
+
+slug = sys.argv[1]
 try:
-    with open(sys.argv[1], encoding="utf-8") as f:
-        raw = json.load(f)
-except (OSError, json.JSONDecodeError):
-    sys.exit(1)
-status = raw.get("status")
-if not isinstance(status, str):
-    sys.exit(1)
-print(status)
+    response = _sv.read_response(slug, sys.argv[2])
+except FileNotFoundError:
+    sys.exit(2)
+print(response.status)
 PY
-      ) || status=""
+    )
+    rc=$?
+    if [ "$rc" -eq 2 ]; then
+      status=""
+    elif [ "$rc" -ne 0 ]; then
+      status="invalid"
+    fi
+    if [ -n "$status" ]; then
       case "$status" in
         approved|modified)
-          mkdir -p "$queue_dir/processed"
-          mv -f "$queue_dir/${proposal_id}.proposal.json" "$queue_dir/processed/" 2>/dev/null || true
-          mv -f "$queue_dir/${proposal_id}.response.json" "$queue_dir/processed/" 2>/dev/null || true
+          python3 - "$slug" "$proposal_id" <<'PY' || true
+import sys
+
+from bot_bottle import supervise as _sv
+
+_sv.archive_proposal(sys.argv[1], sys.argv[2])
+PY
           echo "git-gate: supervisor approved # gitleaks:allow for $ref" >&2
           return 0
           ;;
@@ -499,4 +495,3 @@ if ! git -C "$repo_dir" rev-parse --verify HEAD >/dev/null 2>&1; then
 fi
 exit 0
 """
-

bot_bottle/git_http_backend.py

@@ -16,11 +16,16 @@ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 from urllib.parse import urlsplit
 
-from .git_gate import GIT_GATE_TIMEOUT_SECS
-
 
 DEFAULT_PORT = 9420
 
+# Mirrors git_gate_render.GIT_GATE_TIMEOUT_SECS. Duplicated rather than
+# imported: this module ships as a flat top-level sibling in the sidecar
+# bundle image (see Dockerfile.sidecars), not as part of the bot_bottle
+# package, so `bot_bottle.git_gate` and its dependency chain aren't
+# available at runtime.
+GIT_GATE_TIMEOUT_SECS = 15
+
 # Bound memory use while still allowing ordinary git push packfiles.
 MAX_BODY_BYTES = 100 * 1024 * 1024
 

bot_bottle/manifest.py

@@ -62,15 +62,25 @@ from dataclasses import dataclass, field, replace
 from pathlib import Path
 from typing import Mapping
 
+from .log import warn
 from .manifest_util import ManifestError, as_json_object
 from .manifest_agent import ManifestAgent, ManifestAgentProvider
+from .manifest_bottle import ManifestBottle
 from .manifest_egress import (
     EGRESS_AUTH_SCHEMES,
     ManifestEgressConfig,
     ManifestEgressRoute,
 )
-from .manifest_git import ManifestGitEntry, ManifestGitUser, ManifestKeyConfig, parse_git_gate_config
-from .manifest_schema import BOTTLE_KEYS
+from .manifest_extends import merge_bottles_runtime, resolve_bottles
+from .manifest_git import ManifestGitEntry, ManifestGitUser, ManifestKeyConfig
+from .manifest_loader import (
+    check_stale_json,
+    load_bottle_chain_from_dir,
+    scan_agent_names,
+    scan_bottle_names,
+)
+from .manifest_schema import validate_agent_frontmatter_keys
+from .yaml_subset import YamlSubsetError, parse_frontmatter
 
 # Re-export everything that callers currently import from this module.
 __all__ = [
@@ -89,10 +99,6 @@ __all__ = [
 ]
 
 
-def _empty_str_dict() -> dict[str, str]:
-    return {}
-
-
 def _section_dict(value: object, label: str) -> dict[str, object]:
     """Like as_json_object but treats absent/null as an empty section."""
     if value is None:
@@ -100,107 +106,6 @@ def _section_dict(value: object, label: str) -> dict[str, object]:
     return as_json_object(value, label)
 
 
-@dataclass(frozen=True)
-class ManifestBottle:
-    env: Mapping[str, str] = field(default_factory=_empty_str_dict)
-    agent_provider: ManifestAgentProvider = field(default_factory=ManifestAgentProvider)
-    git: tuple[ManifestGitEntry, ...] = ()
-    # Per-bottle git identity (issue #86). Empty default — bottles
-    # that don't set `git-gate.user:` in the manifest skip the
-    # `git config --global` step entirely. A bottle can declare a user
-    # identity without any git-gate.repos upstreams, and vice versa.
-    git_user: ManifestGitUser = field(default_factory=ManifestGitUser)
-    egress: ManifestEgressConfig = field(default_factory=ManifestEgressConfig)
-    # Per-bottle stuck-recovery sidecar (PRD 0013). When true (the
-    # default, issue #249), the launch step brings up a supervise
-    # sidecar that exposes egress MCP tools to the agent. Set
-    # `supervise: false` to skip the sidecar.
-    supervise: bool = True
-
-    @classmethod
-    def from_dict(cls, name: str, raw: object) -> "ManifestBottle":
-        d = as_json_object(raw, f"bottle '{name}'")
-
-        if "runtime" in d:
-            raise ManifestError(
-                f"bottle '{name}' has a 'runtime' field, which is no longer "
-                f"supported. gVisor (runsc) is now auto-detected by the "
-                f"backend; remove the 'runtime' field from the bottle "
-                f"definition."
-            )
-
-        if "ssh" in d:
-            raise ManifestError(
-                f"bottle '{name}' has an 'ssh' field, which has been removed "
-                f"(PRD 0009). Declare upstreams under 'git-gate.repos' with "
-                f"url + identity + host_key; the git-gate sidecar (PRD 0008) "
-                f"holds the credential and gitleaks-scans pushes."
-            )
-
-        if "git" in d:
-            raise ManifestError(
-                f"bottle '{name}' uses 'git' which has been replaced by "
-                f"'git-gate' (PRD 0047). Move git.user → git-gate.user "
-                f"and git.remotes → git-gate.repos (fields: url, identity, host_key)."
-            )
-
-        if "git_user" in d:
-            raise ManifestError(
-                f"bottle '{name}' has a 'git_user' field, which has been "
-                f"removed. Move it under 'git-gate.user'."
-            )
-
-        unknown = set(d.keys()) - BOTTLE_KEYS
-        if unknown:
-            allowed = ", ".join(sorted(BOTTLE_KEYS))
-            raise ManifestError(
-                f"bottle '{name}' has unknown key(s) {sorted(unknown)}; "
-                f"allowed keys are {allowed}."
-            )
-
-        env: dict[str, str] = {}
-        env_raw = d.get("env")
-        if env_raw is not None:
-            env_dict = as_json_object(env_raw, f"bottle '{name}' env")
-            for var, value in env_dict.items():
-                if not isinstance(value, str):
-                    raise ManifestError(
-                        f"env entry {var} in bottle '{name}' must be a JSON string "
-                        f"(was {type(value).__name__}). Use \"?<message>\" for prompt-at-runtime."
-                    )
-                env[var] = value
-
-        git: tuple[ManifestGitEntry, ...] = ()
-        git_user = ManifestGitUser()
-        git_raw = d.get("git-gate")
-        if git_raw is not None:
-            git, git_user = parse_git_gate_config(name, git_raw)
-
-        agent_provider = (
-            ManifestAgentProvider.from_dict(name, d["agent_provider"])
-            if "agent_provider" in d
-            else ManifestAgentProvider()
-        )
-
-        egress = (
-            ManifestEgressConfig.from_dict(name, d["egress"])
-            if "egress" in d
-            else ManifestEgressConfig()
-        )
-
-        supervise_raw = d.get("supervise", True)
-        if not isinstance(supervise_raw, bool):
-            raise ManifestError(
-                f"bottle '{name}' supervise must be a boolean "
-                f"(was {type(supervise_raw).__name__})"
-            )
-
-        return cls(
-            env=env, agent_provider=agent_provider, git=git,
-            git_user=git_user, egress=egress, supervise=supervise_raw,
-        )
-
-
 def _merge_git_user(
     agent_user: ManifestGitUser, base_user: ManifestGitUser
 ) -> ManifestGitUser:
@@ -237,8 +142,6 @@ def _resolve_effective_bottle_eager(
 
     When bottle_names is non-empty they are merged in order. When empty, falls
     back to agent.bottle. Raises ManifestError when neither is set."""
-    from .manifest_extends import merge_bottles_runtime
-
     if bottle_names:
         resolved: list[ManifestBottle] = []
         for bn in bottle_names:
@@ -270,9 +173,6 @@ def _resolve_effective_bottle_lazy(
     When bottle_names is non-empty they are resolved from disk and merged in
     order. When empty, falls back to agent_bottle. Raises ManifestError when
     neither is set."""
-    from .manifest_extends import merge_bottles_runtime
-    from .manifest_loader import load_bottle_chain_from_dir
-
     if bottle_names:
         resolved = [load_bottle_chain_from_dir(bn, bottles_dir) for bn in bottle_names]
         return merge_bottles_runtime(resolved)
@@ -358,8 +258,6 @@ class ManifestIndex:
         home_md = home_dir / ".bot-bottle"
         cwd_md = cwd_dir / ".bot-bottle"
 
-        from .manifest_loader import check_stale_json
-
         check_stale_json(home_dir, home_md, "$HOME")
         if cwd_dir.resolve() != home_dir.resolve():
             check_stale_json(cwd_dir, cwd_md, "$CWD")
@@ -399,7 +297,6 @@ class ManifestIndex:
                 files = sorted(stale_bottles.glob("*.md"))
                 if files:
                     names = ", ".join(p.name for p in files)
-                    from .log import warn
                     warn(
                         f"ignoring bottle file(s) under "
                         f"{stale_bottles}: {names}. Bottles can only "
@@ -421,7 +318,6 @@ class ManifestIndex:
         raw_bottles: dict[str, dict[str, object]] = {}
         for n, b in raw_bottles_obj.items():
             raw_bottles[n] = as_json_object(b, f"bottle '{n}'")
-        from .manifest_extends import resolve_bottles
 
         bottles = resolve_bottles(raw_bottles)
 
@@ -439,7 +335,6 @@ class ManifestIndex:
         filenames without reading their content. In eager mode (from
         from_json_obj) it returns the pre-parsed bottles' names."""
         if self.home_md is not None:
-            from .manifest_loader import scan_bottle_names
             return scan_bottle_names(self.home_md / "bottles")
         return sorted(self.bottles.keys())
 
@@ -451,7 +346,6 @@ class ManifestIndex:
         filenames without reading their content. In eager mode (from
         from_json_obj) it returns the pre-parsed agents' names."""
         if self.home_md is not None:
-            from .manifest_loader import scan_agent_names
             home_names = set(scan_agent_names(self.home_md / "agents").keys())
             cwd_names: set[str] = set()
             if self.cwd_md is not None:
@@ -509,10 +403,6 @@ class ManifestIndex:
         """Lazy path (resolve/from_md_dirs): read and parse the agent file and
         its bottle chain from disk for the first time here."""
         assert self.home_md is not None  # guaranteed by load_for_agent dispatch
-        from .manifest_loader import scan_agent_names
-        from .manifest_schema import validate_agent_frontmatter_keys
-        from .yaml_subset import YamlSubsetError, parse_frontmatter
-
         # Locate the agent file; cwd wins over home on name collision.
         home_agents = scan_agent_names(self.home_md / "agents")
         cwd_agents: dict[str, Path] = {}

bot_bottle/manifest_agent.py

@@ -8,7 +8,7 @@ from typing import cast
 from .agent_provider import PROVIDER_TEMPLATES
 from .manifest_util import ManifestError, as_json_object
 from .manifest_git import ManifestGitUser
-from .manifest_schema import AGENT_MODEL_KEYS
+from .manifest_schema import AGENT_MODEL_KEYS, is_valid_entity_name
 
 
 @dataclass(frozen=True)
@@ -161,6 +161,16 @@ class ManifestAgent:
                         f"agent '{name}' skills[{i}] must be a string "
                         f"(was {type(skill).__name__})"
                     )
+                # Skill names become host/guest path segments and are
+                # interpolated into provisioning shell commands, so they
+                # must fit the same kebab-case convention as bottle/agent
+                # filenames — rejecting anything that could break out of a
+                # path segment or inject shell metacharacters.
+                if not is_valid_entity_name(skill):
+                    raise ManifestError(
+                        f"agent '{name}' skills[{i}] {skill!r} is not a valid "
+                        f"skill name; must match [a-z][a-z0-9-]*"
+                    )
                 collected.append(skill)
             skills = tuple(collected)
 

bot_bottle/manifest_bottle.py

@@ -0,0 +1,129 @@
+"""The `ManifestBottle` value type.
+
+Split out of `manifest.py` so the `extends:`/loader resolvers can import it
+without a circular dependency: `manifest.py` imports those resolvers, while
+they only need this value type. Everything here depends on leaf modules
+(`manifest_util`, `manifest_agent`, `manifest_egress`, `manifest_git`,
+`manifest_schema`), so this module sits at the bottom of the manifest layer.
+
+`manifest.py` re-exports `ManifestBottle`, so existing
+`from .manifest import ManifestBottle` callers are unaffected.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping
+
+from .manifest_util import ManifestError, as_json_object
+from .manifest_agent import ManifestAgentProvider
+from .manifest_egress import ManifestEgressConfig
+from .manifest_git import ManifestGitEntry, ManifestGitUser, parse_git_gate_config
+from .manifest_schema import BOTTLE_KEYS
+
+__all__ = ["ManifestBottle"]
+
+
+def _empty_str_dict() -> dict[str, str]:
+    return {}
+
+
+@dataclass(frozen=True)
+class ManifestBottle:
+    env: Mapping[str, str] = field(default_factory=_empty_str_dict)
+    agent_provider: ManifestAgentProvider = field(default_factory=ManifestAgentProvider)
+    git: tuple[ManifestGitEntry, ...] = ()
+    # Per-bottle git identity (issue #86). Empty default — bottles
+    # that don't set `git-gate.user:` in the manifest skip the
+    # `git config --global` step entirely. A bottle can declare a user
+    # identity without any git-gate.repos upstreams, and vice versa.
+    git_user: ManifestGitUser = field(default_factory=ManifestGitUser)
+    egress: ManifestEgressConfig = field(default_factory=ManifestEgressConfig)
+    # Per-bottle stuck-recovery sidecar (PRD 0013). When true (the
+    # default, issue #249), the launch step brings up a supervise
+    # sidecar that exposes egress MCP tools to the agent. Set
+    # `supervise: false` to skip the sidecar.
+    supervise: bool = True
+
+    @classmethod
+    def from_dict(cls, name: str, raw: object) -> "ManifestBottle":
+        d = as_json_object(raw, f"bottle '{name}'")
+
+        if "runtime" in d:
+            raise ManifestError(
+                f"bottle '{name}' has a 'runtime' field, which is no longer "
+                f"supported. gVisor (runsc) is now auto-detected by the "
+                f"backend; remove the 'runtime' field from the bottle "
+                f"definition."
+            )
+
+        if "ssh" in d:
+            raise ManifestError(
+                f"bottle '{name}' has an 'ssh' field, which has been removed "
+                f"(PRD 0009). Declare upstreams under 'git-gate.repos' with "
+                f"url + identity + host_key; the git-gate sidecar (PRD 0008) "
+                f"holds the credential and gitleaks-scans pushes."
+            )
+
+        if "git" in d:
+            raise ManifestError(
+                f"bottle '{name}' uses 'git' which has been replaced by "
+                f"'git-gate' (PRD 0047). Move git.user → git-gate.user "
+                f"and git.remotes → git-gate.repos (fields: url, identity, host_key)."
+            )
+
+        if "git_user" in d:
+            raise ManifestError(
+                f"bottle '{name}' has a 'git_user' field, which has been "
+                f"removed. Move it under 'git-gate.user'."
+            )
+
+        unknown = set(d.keys()) - BOTTLE_KEYS
+        if unknown:
+            allowed = ", ".join(sorted(BOTTLE_KEYS))
+            raise ManifestError(
+                f"bottle '{name}' has unknown key(s) {sorted(unknown)}; "
+                f"allowed keys are {allowed}."
+            )
+
+        env: dict[str, str] = {}
+        env_raw = d.get("env")
+        if env_raw is not None:
+            env_dict = as_json_object(env_raw, f"bottle '{name}' env")
+            for var, value in env_dict.items():
+                if not isinstance(value, str):
+                    raise ManifestError(
+                        f"env entry {var} in bottle '{name}' must be a JSON string "
+                        f"(was {type(value).__name__}). Use \"?<message>\" for prompt-at-runtime."
+                    )
+                env[var] = value
+
+        git: tuple[ManifestGitEntry, ...] = ()
+        git_user = ManifestGitUser()
+        git_raw = d.get("git-gate")
+        if git_raw is not None:
+            git, git_user = parse_git_gate_config(name, git_raw)
+
+        agent_provider = (
+            ManifestAgentProvider.from_dict(name, d["agent_provider"])
+            if "agent_provider" in d
+            else ManifestAgentProvider()
+        )
+
+        egress = (
+            ManifestEgressConfig.from_dict(name, d["egress"])
+            if "egress" in d
+            else ManifestEgressConfig()
+        )
+
+        supervise_raw = d.get("supervise", True)
+        if not isinstance(supervise_raw, bool):
+            raise ManifestError(
+                f"bottle '{name}' supervise must be a boolean "
+                f"(was {type(supervise_raw).__name__})"
+            )
+
+        return cls(
+            env=env, agent_provider=agent_provider, git=git,
+            git_user=git_user, egress=egress, supervise=supervise_raw,
+        )

bot_bottle/manifest_extends.py

@@ -2,11 +2,10 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from .manifest import ManifestBottle
-    from .manifest_egress import ManifestEgressConfig
+from .manifest_bottle import ManifestBottle
+from .manifest_egress import ManifestEgressConfig, validate_egress_routes
+from .manifest_git import ManifestGitUser, parse_git_gate_config
+from .manifest_util import ManifestError, as_json_object
 
 
 def merge_bottles_runtime(bottles: "list[ManifestBottle]") -> "ManifestBottle":
@@ -27,9 +26,6 @@ def merge_bottles_runtime(bottles: "list[ManifestBottle]") -> "ManifestBottle":
 
 
 def _merge_two_bottles_runtime(base: "ManifestBottle", override: "ManifestBottle") -> "ManifestBottle":
-    from .manifest import ManifestBottle, ManifestGitUser
-    from .manifest_egress import ManifestEgressConfig
-
     merged_env = {**base.env, **override.env}
 
     merged_git_user = ManifestGitUser(
@@ -81,8 +77,6 @@ def _resolve_one_bottle(
     repos_cache: dict[str, dict[str, object]],
     seen: tuple[str, ...],
 ) -> ManifestBottle:
-    from .manifest import ManifestBottle, ManifestError
-
     if name in cache:
         return cache[name]
     if name in seen:
@@ -174,11 +168,6 @@ def _fold_two_bottles(
     later_repos_raw: dict[str, object],
 ) -> tuple[ManifestBottle, dict[str, object]]:
     """Combine two resolved parent bottles; later wins over earlier."""
-    from .manifest import ManifestBottle, ManifestGitUser
-    from .manifest_egress import ManifestEgressConfig
-    from .manifest_git import parse_git_gate_config
-    from .manifest_util import as_json_object
-
     merged_env = {**earlier.env, **later.env}
 
     merged_git_user = ManifestGitUser(
@@ -227,10 +216,6 @@ def _merge_bottles(
     name: str,
 ) -> ManifestBottle:
     """Apply PRD 0025 merge rules."""
-    from .manifest import ManifestBottle, ManifestGitUser
-    from .manifest_egress import validate_egress_routes
-    from .manifest_util import as_json_object
-
     # git-gate.repos: when the child declares repos, inject the already
     # name-merged repo set (computed by _resolve_repos_raw) so the child
     # parses with the full inherited+overridden list (issue #237).
@@ -303,8 +288,6 @@ def _resolve_repos_raw(
     inherits the parent's set verbatim; an explicit empty dict clears it.
     Otherwise parent and child unite by name, with same-name entries
     field-merged (parent fields are defaults, child fields win)."""
-    from .manifest_util import as_json_object
-
     if not _child_declares_git_gate_repos(child_raw):
         return parent_repos
     child_repos = _declared_repos_raw(child_raw)
@@ -324,8 +307,6 @@ def _resolve_repos_raw(
 def _declared_repos_raw(child_raw: dict[str, object]) -> dict[str, object]:
     """Return the child's explicitly declared git-gate.repos as raw dicts,
     or an empty dict when none are declared."""
-    from .manifest_util import as_json_object
-
     if not _child_declares_git_gate_repos(child_raw):
         return {}
     git_raw = as_json_object(child_raw.get("git-gate", {}), "child git-gate")
@@ -333,8 +314,6 @@ def _declared_repos_raw(child_raw: dict[str, object]) -> dict[str, object]:
 
 
 def _child_declares_git_gate_repos(child_raw: dict[str, object]) -> bool:
-    from .manifest_util import as_json_object
-
     git_raw = child_raw.get("git-gate")
     if git_raw is None:
         return False
@@ -347,9 +326,6 @@ def _merge_egress(
     child: ManifestEgressConfig,
     child_raw: dict[str, object],
 ) -> ManifestEgressConfig:
-    from .manifest_egress import ManifestEgressConfig
-    from .manifest_util import as_json_object
-
     child_egress_raw = as_json_object(child_raw.get("egress"), "child egress")
     routes = parent.routes + child.routes
     log = child.Log if "log" in child_egress_raw else parent.Log

bot_bottle/manifest_loader.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import TYPE_CHECKING
 
 from .log import warn
+from .manifest_bottle import ManifestBottle
+from .manifest_extends import resolve_bottles
 from .manifest_schema import (
     entity_name_from_path,
     validate_bottle_frontmatter_keys,
@@ -13,9 +14,6 @@ from .manifest_schema import (
 from .manifest_util import ManifestError
 from .yaml_subset import YamlSubsetError, parse_frontmatter
 
-if TYPE_CHECKING:
-    from .manifest import ManifestBottle
-
 
 def check_stale_json(dir_path: Path, md_dir: Path, label: str) -> None:
     """Die if `<dir_path>/bot-bottle.json` exists but `md_dir` does
@@ -78,8 +76,6 @@ def load_bottle_chain_from_dir(
 
     Only the files in the extends chain are read — unrelated bottle files
     are never touched. Raises ManifestError on parse or validation failure."""
-    from .manifest_extends import resolve_bottles
-
     raws: dict[str, dict[str, object]] = {}
     to_load = [bottle_name]
     while to_load:

bot_bottle/manifest_schema.py

@@ -33,13 +33,20 @@ AGENT_KEYS = (
 AGENT_MODEL_KEYS = AGENT_KEYS | frozenset({"prompt"})
 
 
+def is_valid_entity_name(name: str) -> bool:
+    """True if `name` fits the kebab-case `[a-z][a-z0-9-]*` convention
+    shared by bottle/agent filenames and skill names. Names that satisfy
+    this are also safe to interpolate into a host/guest path segment."""
+    return bool(_FILENAME_RX.match(name))
+
+
 def entity_name_from_path(path: Path) -> str | None:
     """Return the entity name implied by the filename, or None if the
     filename does not fit the [a-z][a-z0-9-]* convention."""
     if path.suffix != ".md":
         return None
     stem = path.stem
-    if not _FILENAME_RX.match(stem):
+    if not is_valid_entity_name(stem):
         return None
     return stem
 

bot_bottle/migrations.py

@@ -0,0 +1,37 @@
+"""SQLite migration runner for bot-bottle stores."""
+
+from __future__ import annotations
+
+import sqlite3
+
+
+class TableMigrations:
+    """Runs a sequential list of DDL migrations tracked by schema_key in schema_versions."""
+
+    def __init__(self, schema_key: str, migrations: list[str]) -> None:
+        self.schema_key = schema_key
+        self.migrations = migrations
+
+    def apply(self, conn: sqlite3.Connection) -> None:
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS schema_versions (
+                module TEXT PRIMARY KEY,
+                version INTEGER NOT NULL DEFAULT 0
+            )
+            """
+        )
+        row = conn.execute(
+            "SELECT version FROM schema_versions WHERE module = ?",
+            (self.schema_key,),
+        ).fetchone()
+        version = row[0] if row else 0
+        for i, sql in enumerate(self.migrations[version:], start=version + 1):
+            conn.execute(sql)
+            conn.execute(
+                "INSERT OR REPLACE INTO schema_versions (module, version) VALUES (?, ?)",
+                (self.schema_key, i),
+            )
+
+
+__all__ = ["TableMigrations"]

bot_bottle/queue_store.py

@@ -0,0 +1,215 @@
+"""SQLite-backed queue store for supervise proposals and responses (PRD 0013)."""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from pathlib import Path
+
+try:
+    from .supervise_types import Proposal, Response, host_db_path
+    from .db_store import DbStore
+    from .migrations import TableMigrations
+except ImportError:
+    from supervise_types import Proposal, Response, host_db_path  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from db_store import DbStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from migrations import TableMigrations  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+
+
+class QueueStore(DbStore):
+    """SQLite-backed persistent store for supervise proposals and responses."""
+
+    def __init__(self, queue_key: str, db_path: Path | None = None) -> None:
+        self.queue_key = queue_key
+        if db_path is not None:
+            resolved = db_path
+        else:
+            # In the sidecar container SUPERVISE_DB_PATH points at the
+            # bind-mounted host DB. On the host this env var is never set,
+            # so we always fall through to host_db_path().
+            env_path = os.environ.get("SUPERVISE_DB_PATH", "").strip()
+            resolved = Path(env_path) if env_path else host_db_path()
+        # One entry per schema version: migrations[0] brings a fresh DB to
+        # version 1, [1] to version 2, etc.  Add new entries at the end; never
+        # edit existing ones.
+        migrations = TableMigrations("queue_store", [
+            # v1 — proposals table
+            """
+            CREATE TABLE IF NOT EXISTS supervise_proposals (
+                queue_key TEXT NOT NULL,
+                id TEXT NOT NULL,
+                bottle_slug TEXT NOT NULL,
+                tool TEXT NOT NULL,
+                proposed_file TEXT NOT NULL,
+                justification TEXT NOT NULL,
+                arrival_timestamp TEXT NOT NULL,
+                current_file_hash TEXT NOT NULL,
+                archived INTEGER NOT NULL DEFAULT 0,
+                PRIMARY KEY (queue_key, id)
+            )
+            """,
+            # v2 — responses table
+            """
+            CREATE TABLE IF NOT EXISTS supervise_responses (
+                queue_key TEXT NOT NULL,
+                proposal_id TEXT NOT NULL,
+                status TEXT NOT NULL,
+                notes TEXT NOT NULL,
+                final_file TEXT,
+                archived INTEGER NOT NULL DEFAULT 0,
+                PRIMARY KEY (queue_key, proposal_id)
+            )
+            """,
+        ])
+        super().__init__(resolved, migrations)
+
+    def write_proposal(self, proposal: Proposal) -> Path:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO supervise_proposals (
+                    queue_key, id, bottle_slug, tool, proposed_file, justification,
+                    arrival_timestamp, current_file_hash, archived
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)
+                """,
+                (
+                    self.queue_key,
+                    proposal.id,
+                    proposal.bottle_slug,
+                    proposal.tool,
+                    proposal.proposed_file,
+                    proposal.justification,
+                    proposal.arrival_timestamp,
+                    proposal.current_file_hash,
+                ),
+            )
+        self._chmod()
+        return self.db_path
+
+    def read_proposal(self, proposal_id: str) -> Proposal:
+        with self._connect() as conn:
+            row = conn.execute(
+                """
+                SELECT * FROM supervise_proposals
+                WHERE queue_key = ? AND id = ? AND archived = 0
+                """,
+                (self.queue_key, proposal_id),
+            ).fetchone()
+        if row is None:
+            raise FileNotFoundError(proposal_id)
+        return self._row_to_proposal(row)
+
+    def list_pending_proposals(self) -> list[Proposal]:
+        if not self.db_path.is_file():
+            return []
+        with self._connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT p.* FROM supervise_proposals p
+                WHERE p.archived = 0
+                  AND p.queue_key = ?
+                  AND NOT EXISTS (
+                    SELECT 1 FROM supervise_responses r
+                    WHERE r.queue_key = p.queue_key
+                      AND r.proposal_id = p.id
+                      AND r.archived = 0
+                  )
+                ORDER BY p.arrival_timestamp, p.id
+                """,
+                (self.queue_key,),
+            ).fetchall()
+        return [self._row_to_proposal(row) for row in rows]
+
+    def list_all_pending_proposals(self) -> list[Proposal]:
+        if not self.db_path.is_file():
+            return []
+        with self._connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT p.* FROM supervise_proposals p
+                WHERE p.archived = 0
+                  AND NOT EXISTS (
+                    SELECT 1 FROM supervise_responses r
+                    WHERE r.queue_key = p.queue_key
+                      AND r.proposal_id = p.id
+                      AND r.archived = 0
+                  )
+                ORDER BY p.arrival_timestamp, p.id
+                """
+            ).fetchall()
+        return [self._row_to_proposal(row) for row in rows]
+
+    def write_response(self, response: Response) -> Path:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO supervise_responses (
+                    queue_key, proposal_id, status, notes, final_file, archived
+                ) VALUES (?, ?, ?, ?, ?, 0)
+                """,
+                (
+                    self.queue_key,
+                    response.proposal_id,
+                    response.status,
+                    response.notes,
+                    response.final_file,
+                ),
+            )
+        self._chmod()
+        return self.db_path
+
+    def read_response(self, proposal_id: str) -> Response:
+        with self._connect() as conn:
+            row = conn.execute(
+                """
+                SELECT * FROM supervise_responses
+                WHERE queue_key = ? AND proposal_id = ? AND archived = 0
+                """,
+                (self.queue_key, proposal_id),
+            ).fetchone()
+        if row is None:
+            raise FileNotFoundError(proposal_id)
+        return self._row_to_response(row)
+
+    def archive_proposal(self, proposal_id: str) -> None:
+        if not self.db_path.is_file():
+            return
+        with self._connect() as conn:
+            conn.execute(
+                """
+                UPDATE supervise_proposals SET archived = 1
+                WHERE queue_key = ? AND id = ?
+                """,
+                (self.queue_key, proposal_id),
+            )
+            conn.execute(
+                """
+                UPDATE supervise_responses SET archived = 1
+                WHERE queue_key = ? AND proposal_id = ?
+                """,
+                (self.queue_key, proposal_id),
+            )
+
+    @staticmethod
+    def _row_to_proposal(row: sqlite3.Row) -> Proposal:
+        return Proposal(
+            id=row["id"],
+            bottle_slug=row["bottle_slug"],
+            tool=row["tool"],
+            proposed_file=row["proposed_file"],
+            justification=row["justification"],
+            arrival_timestamp=row["arrival_timestamp"],
+            current_file_hash=row["current_file_hash"],
+        )
+
+    @staticmethod
+    def _row_to_response(row: sqlite3.Row) -> Response:
+        return Response(
+            proposal_id=row["proposal_id"],
+            status=row["status"],
+            notes=row["notes"],
+            final_file=row["final_file"],
+        )
+
+
+__all__ = ["QueueStore"]

bot_bottle/store_manager.py

@@ -0,0 +1,60 @@
+"""Singleton manager for all bot-bottle SQLite stores (PRD 0013)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+try:
+    from .audit_store import AuditStore
+    from .queue_store import QueueStore
+except ImportError:
+    from audit_store import AuditStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from queue_store import QueueStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+
+_instance: StoreManager | None = None
+
+
+class StoreManager:
+    """Owns db_path and delegates migrate/is_migrated across all stores.
+
+    Use instance() for normal access. Call reset(db_path) in tests to swap
+    the singleton to a temp path, then reset() with no args to restore the
+    default."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        if db_path is None:
+            # Lazy import to avoid a circular dependency: supervise imports
+            # StoreManager at module level; StoreManager must not import
+            # supervise at module level in return.
+            try:
+                from .supervise import host_db_path
+            except ImportError:
+                from supervise import host_db_path  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+            db_path = host_db_path()
+        self.db_path = db_path
+
+    @classmethod
+    def instance(cls) -> StoreManager:
+        global _instance
+        if _instance is None:
+            _instance = cls()
+        return _instance
+
+    @classmethod
+    def reset(cls, db_path: Path | None = None) -> None:
+        """Replace the singleton. Pass db_path for test isolation; omit to restore default."""
+        global _instance
+        _instance = cls(db_path)
+
+    def is_migrated(self) -> bool:
+        return (
+            QueueStore("", self.db_path).is_migrated()
+            and AuditStore(self.db_path).is_migrated()
+        )
+
+    def migrate(self) -> None:
+        QueueStore("", self.db_path).migrate()
+        AuditStore(self.db_path).migrate()
+
+
+__all__ = ["StoreManager"]

bot_bottle/supervise.py

@@ -9,15 +9,14 @@ calls when it needs an operator-reviewed egress change:
 
 Each tool call: the agent passes the full proposed file plus a
 justification text. The sidecar validates the proposal syntactically,
-writes it to the host's per-bottle queue dir, and holds the tool-call
+writes it to the host SQLite queue table, and holds the tool-call
 connection open. The operator's supervise TUI
 (bot_bottle.cli.supervise) sees the proposal, accepts
-approve / modify / reject, and writes a response file alongside the
-proposal. The sidecar sees the response and returns `{status, notes}`
-to the agent.
+approve / modify / reject, and writes a response row. The sidecar sees
+the response and returns `{status, notes}` to the agent.
 
 This module defines the host-side library: dataclasses for the queue
-file shapes, queue read/write helpers, the audit log writer, and the
+record shapes, queue read/write helpers, the audit log writer, and the
 diff renderer. The in-container sidecar lives in
 bot_bottle/supervise_server.py; the supervise daemon's container
 lifecycle is owned by the sidecar bundle (PRD 0024).
@@ -31,37 +30,56 @@ remediation engines that wire real config changes land in PRDs 0014,
 
 from __future__ import annotations
 
-import dataclasses
 import difflib
 import hashlib
-import json
-import os
 import time
-import uuid
 from abc import ABC
 from dataclasses import dataclass
-from datetime import datetime, timezone
 from pathlib import Path
 
+try:
+    from .supervise_types import (
+        ACTION_OPERATOR_EDIT,
+        AuditEntry,
+        HOST_DB_FILENAME,
+        Proposal,
+        Response,
+        STATUSES,
+        STATUS_APPROVED,
+        STATUS_MODIFIED,
+        STATUS_REJECTED,
+        TOOLS,
+        TOOL_EGRESS_ALLOW,
+        TOOL_EGRESS_BLOCK,
+        TOOL_EGRESS_TOKEN_ALLOW,
+        TOOL_GITLEAKS_ALLOW,
+        TOOL_LIST_EGRESS_ROUTES,
+        bot_bottle_root,
+    )
+except ImportError:
+    from supervise_types import (  # type: ignore[import-not-found,no-redef]  # pylint: disable=import-error,no-name-in-module
+        ACTION_OPERATOR_EDIT,
+        AuditEntry,
+        HOST_DB_FILENAME,
+        Proposal,
+        Response,
+        STATUSES,
+        STATUS_APPROVED,
+        STATUS_MODIFIED,
+        STATUS_REJECTED,
+        TOOLS,
+        TOOL_EGRESS_ALLOW,
+        TOOL_EGRESS_BLOCK,
+        TOOL_EGRESS_TOKEN_ALLOW,
+        TOOL_GITLEAKS_ALLOW,
+        TOOL_LIST_EGRESS_ROUTES,
+        bot_bottle_root,
+    )
+
 
 SUPERVISE_HOSTNAME = "supervise"
 SUPERVISE_PORT = 9100
 
-TOOL_EGRESS_BLOCK = "egress-block"
-TOOL_EGRESS_ALLOW = "egress-allow"
-TOOL_GITLEAKS_ALLOW = "gitleaks-allow"
-# Written directly by the egress addon (not an agent-facing MCP tool) when an
-# outbound DLP token block is routed to the operator for override (PRD 0062).
-TOOL_EGRESS_TOKEN_ALLOW = "egress-token-allow"
-TOOL_LIST_EGRESS_ROUTES = "list-egress-routes"
-TOOLS: tuple[str, ...] = (
-    TOOL_EGRESS_ALLOW,
-    TOOL_EGRESS_BLOCK,
-    TOOL_GITLEAKS_ALLOW,
-    TOOL_EGRESS_TOKEN_ALLOW,
-    TOOL_LIST_EGRESS_ROUTES,
-)
-
 # The supervise sidecar uses these to query egress's
 # introspection endpoint for the `list-egress-routes` MCP
 # tool. The hostname + port match egress's docker network
@@ -77,236 +95,77 @@ COMPONENT_FOR_TOOL: dict[str, str] = {
     TOOL_EGRESS_BLOCK: "egress",
 }
 
-STATUS_APPROVED = "approved"
-STATUS_MODIFIED = "modified"
-STATUS_REJECTED = "rejected"
-STATUSES: tuple[str, ...] = (STATUS_APPROVED, STATUS_MODIFIED, STATUS_REJECTED)
-
-# Operator-initiated audit entries (no tool call). PRD 0014's
-# `routes edit <bottle>` verb writes entries with this action.
-ACTION_OPERATOR_EDIT = "operator-edit"
-
-QUEUE_DIR_IN_CONTAINER = "/run/supervise/queue"
+DB_PATH_IN_CONTAINER = "/run/supervise/bot-bottle.db"
 DEFAULT_POLL_INTERVAL_SEC = 0.5
 
 
 # --- Paths -----------------------------------------------------------------
 
 
-def bot_bottle_root() -> Path:
-    return Path.home() / ".bot-bottle"
-
-
-def queue_dir_for_slug(slug: str) -> Path:
-    return bot_bottle_root() / "queue" / slug
-
-
 def audit_dir() -> Path:
     return bot_bottle_root() / "audit"
 
 
+def host_db_path() -> Path:
+    # Calls bot_bottle_root() through this module's globals so that patches
+    # on supervise.bot_bottle_root propagate to callers going through
+    # supervise.host_db_path().
+    #
+    # Kept in its own "db" subdirectory (see supervise_types.host_db_path
+    # for why) — must stay in sync with that copy.
+    return bot_bottle_root() / "db" / HOST_DB_FILENAME
+
+
 def audit_log_path(component: str, slug: str) -> Path:
     return audit_dir() / f"{component}-{slug}.log"
 
 
-# --- Dataclasses -----------------------------------------------------------
-
-
-@dataclass(frozen=True)
-class Proposal:
-    """One pending tool-call from the agent. The sidecar writes one
-    of these to the queue dir on a tool call; the operator's TUI
-    reads them; the sidecar polls for a matching Response."""
-
-    id: str
-    bottle_slug: str
-    tool: str
-    proposed_file: str
-    justification: str
-    arrival_timestamp: str
-    current_file_hash: str
-
-    @classmethod
-    def new(
-        cls,
-        *,
-        bottle_slug: str,
-        tool: str,
-        proposed_file: str,
-        justification: str,
-        current_file_hash: str,
-        now: datetime | None = None,
-    ) -> "Proposal":
-        ts = (now or datetime.now(timezone.utc)).isoformat()
-        return cls(
-            id=str(uuid.uuid4()),
-            bottle_slug=bottle_slug,
-            tool=tool,
-            proposed_file=proposed_file,
-            justification=justification,
-            arrival_timestamp=ts,
-            current_file_hash=current_file_hash,
-        )
-
-    def to_dict(self) -> dict[str, object]:
-        return dataclasses.asdict(self)
-
-    @classmethod
-    def from_dict(cls, raw: dict[str, object]) -> "Proposal":
-        tool = _require_str(raw, "tool")
-        if tool not in TOOLS:
-            raise ValueError(f"tool must be one of {TOOLS}; got {tool!r}")
-        return cls(
-            id=_require_str(raw, "id"),
-            bottle_slug=_require_str(raw, "bottle_slug"),
-            tool=tool,
-            proposed_file=_require_str(raw, "proposed_file"),
-            justification=_require_str(raw, "justification"),
-            arrival_timestamp=_require_str(raw, "arrival_timestamp"),
-            current_file_hash=_require_str(raw, "current_file_hash"),
-        )
-
-
-@dataclass(frozen=True)
-class Response:
-    """The operator's decision on a proposal. The TUI writes one of
-    these to the queue dir; the sidecar reads it and returns the
-    `{status, notes}` pair to the agent's tool call.
-
-    `final_file` carries the file content the supervisor will
-    actually apply: for `approved`, equal to the proposal's
-    `proposed_file`; for `modified`, the operator's edited version
-    (the audit diff is current → final_file, not current →
-    proposed_file); for `rejected`, None."""
-
-    proposal_id: str
-    status: str
-    notes: str
-    final_file: str | None = None
-
-    def to_dict(self) -> dict[str, object]:
-        return dataclasses.asdict(self)
-
-    @classmethod
-    def from_dict(cls, raw: dict[str, object]) -> "Response":
-        status = _require_str(raw, "status")
-        if status not in STATUSES:
-            raise ValueError(
-                f"response status must be one of {STATUSES}; got {status!r}"
-            )
-        final = raw.get("final_file")
-        if final is not None and not isinstance(final, str):
-            raise ValueError(
-                f"final_file must be a string or null; got {type(final).__name__}"
-            )
-        return cls(
-            proposal_id=_require_str(raw, "proposal_id"),
-            status=status,
-            notes=_require_str(raw, "notes"),
-            final_file=final,
-        )
-
-
-@dataclass(frozen=True)
-class AuditEntry:
-    """One row of the per-bottle audit log. JSON-Lines, append-only."""
-
-    timestamp: str
-    bottle_slug: str
-    component: str
-    operator_action: str
-    operator_notes: str
-    justification: str
-    diff: str
-
-    def to_dict(self) -> dict[str, object]:
-        return dataclasses.asdict(self)
+try:
+    from .queue_store import QueueStore
+    from .audit_store import AuditStore
+    from .store_manager import StoreManager
+except ImportError:
+    # Sidecar bundle: files are flat-copied under /app, not a package.
+    from queue_store import QueueStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from audit_store import AuditStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
+    from store_manager import StoreManager  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
 
 
 # --- Queue I/O -------------------------------------------------------------
 
 
-def _proposal_filename(proposal_id: str) -> str:
-    return f"{proposal_id}.proposal.json"
-
-
-def _response_filename(proposal_id: str) -> str:
-    return f"{proposal_id}.response.json"
-
-
-def _id_from_proposal_filename(path: Path) -> str | None:
-    name = path.name
-    if not name.endswith(".proposal.json"):
-        return None
-    return name[: -len(".proposal.json")]
-
-
-def write_proposal(queue_dir: Path, proposal: Proposal) -> Path:
-    """Persist `proposal` as JSON in the queue dir, mode 0o600.
+def write_proposal(proposal: Proposal) -> Path:
+    """Persist `proposal` in the queue database, mode 0o600.
     Directory is created if missing."""
-    queue_dir.mkdir(parents=True, exist_ok=True)
-    path = queue_dir / _proposal_filename(proposal.id)
-    payload = json.dumps(proposal.to_dict(), indent=2) + "\n"
-    _atomic_write(path, payload, mode=0o600)
-    return path
+    return QueueStore(proposal.bottle_slug).write_proposal(proposal)
 
 
-def read_proposal(queue_dir: Path, proposal_id: str) -> Proposal:
-    path = queue_dir / _proposal_filename(proposal_id)
-    with path.open() as f:
-        raw = json.load(f)
-    if not isinstance(raw, dict):
-        raise ValueError(f"{path}: top-level must be an object")
-    return Proposal.from_dict(raw)
+def read_proposal(bottle_slug: str, proposal_id: str) -> Proposal:
+    return QueueStore(bottle_slug).read_proposal(proposal_id)
 
 
-def list_pending_proposals(queue_dir: Path) -> list[Proposal]:
-    """All proposals in `queue_dir` that do not yet have a matching
-    response file. Sorted by `arrival_timestamp` so the operator
+def list_pending_proposals(bottle_slug: str) -> list[Proposal]:
+    """All proposals for `bottle_slug` that do not yet have a matching
+    response. Sorted by `arrival_timestamp` so the operator
     sees the queue FIFO."""
-    if not queue_dir.is_dir():
-        return []
-    out: list[Proposal] = []
-    for path in sorted(queue_dir.glob("*.proposal.json")):
-        proposal_id = _id_from_proposal_filename(path)
-        if proposal_id is None:
-            continue
-        if (queue_dir / _response_filename(proposal_id)).exists():
-            continue
-        try:
-            with path.open() as f:
-                raw = json.load(f)
-        except (OSError, json.JSONDecodeError):
-            continue
-        if not isinstance(raw, dict):
-            continue
-        try:
-            out.append(Proposal.from_dict(raw))
-        except (KeyError, ValueError):
-            continue
-    out.sort(key=lambda p: p.arrival_timestamp)
-    return out
+    return QueueStore(bottle_slug).list_pending_proposals()
 
 
-def write_response(queue_dir: Path, response: Response) -> Path:
-    queue_dir.mkdir(parents=True, exist_ok=True)
-    path = queue_dir / _response_filename(response.proposal_id)
-    payload = json.dumps(response.to_dict(), indent=2) + "\n"
-    _atomic_write(path, payload, mode=0o600)
-    return path
+def list_all_pending_proposals() -> list[Proposal]:
+    """All pending proposals across bottles, sorted FIFO."""
+    return QueueStore("").list_all_pending_proposals()
 
 
-def read_response(queue_dir: Path, proposal_id: str) -> Response:
-    path = queue_dir / _response_filename(proposal_id)
-    with path.open() as f:
-        raw = json.load(f)
-    if not isinstance(raw, dict):
-        raise ValueError(f"{path}: top-level must be an object")
-    return Response.from_dict(raw)
+def write_response(bottle_slug: str, response: Response) -> Path:
+    return QueueStore(bottle_slug).write_response(response)
+
+
+def read_response(bottle_slug: str, proposal_id: str) -> Response:
+    return QueueStore(bottle_slug).read_response(proposal_id)
 
 
 def wait_for_response(
-    queue_dir: Path,
+    bottle_slug: str,
     proposal_id: str,
     *,
     poll_interval: float = DEFAULT_POLL_INTERVAL_SEC,
@@ -317,90 +176,35 @@ def wait_for_response(
     which the wait raises TimeoutError. None waits forever — the
     natural shape, since the operator's response time is unbounded.
 
-    Polls the filesystem so the implementation stays portable and
-    stdlib-only."""
-    path = queue_dir / _response_filename(proposal_id)
+    Polls SQLite so the implementation stays portable and stdlib-only."""
+    store = QueueStore(bottle_slug)
     while True:
-        if path.exists():
-            try:
-                with path.open() as f:
-                    raw = json.load(f)
-            except (OSError, json.JSONDecodeError):
-                raw = None
-            if isinstance(raw, dict):
-                try:
-                    return Response.from_dict(raw)
-                except (KeyError, ValueError):
-                    pass
+        try:
+            return store.read_response(proposal_id)
+        except FileNotFoundError:
+            pass
         if deadline is not None and time.monotonic() >= deadline:
             raise TimeoutError(f"no response for proposal {proposal_id!r}")
         time.sleep(poll_interval)
 
 
-def archive_proposal(queue_dir: Path, proposal_id: str) -> None:
-    """Move both proposal and response files to `<queue_dir>/processed/`.
-    Idempotent — missing files are silently skipped."""
-    processed = queue_dir / "processed"
-    processed.mkdir(parents=True, exist_ok=True)
-    for name in (_proposal_filename(proposal_id), _response_filename(proposal_id)):
-        src = queue_dir / name
-        if src.exists():
-            src.rename(processed / name)
+def archive_proposal(bottle_slug: str, proposal_id: str) -> None:
+    """Mark both proposal and response rows processed.
+    Idempotent — missing rows are silently skipped."""
+    QueueStore(bottle_slug).archive_proposal(proposal_id)
 
 
 # --- Audit log -------------------------------------------------------------
 
 
 def write_audit_entry(entry: AuditEntry) -> Path:
-    """Append `entry` as one JSON-Lines record to the per-bottle
-    audit log. Acquires an advisory exclusive lock so concurrent
-    writers don't interleave bytes."""
-    path = audit_log_path(entry.component, entry.bottle_slug)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    line = json.dumps(entry.to_dict(), sort_keys=False) + "\n"
-    fd = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
-    try:
-        _try_flock(fd)
-        try:
-            os.write(fd, line.encode("utf-8"))
-        finally:
-            _try_funlock(fd)
-    finally:
-        os.close(fd)
-    return path
+    """Append `entry` to the host supervise audit table."""
+    return AuditStore().write_audit_entry(entry)
 
 
 def read_audit_entries(component: str, slug: str) -> list[AuditEntry]:
-    """Load all audit entries for the given component+slug. Empty
-    list if the log doesn't exist."""
-    path = audit_log_path(component, slug)
-    if not path.is_file():
-        return []
-    out: list[AuditEntry] = []
-    with path.open() as f:
-        for raw_line in f:
-            raw_line = raw_line.strip()
-            if not raw_line:
-                continue
-            try:
-                raw = json.loads(raw_line)
-            except json.JSONDecodeError:
-                continue
-            if not isinstance(raw, dict):
-                continue
-            try:
-                out.append(AuditEntry(
-                    timestamp=_require_str(raw, "timestamp"),
-                    bottle_slug=_require_str(raw, "bottle_slug"),
-                    component=_require_str(raw, "component"),
-                    operator_action=_require_str(raw, "operator_action"),
-                    operator_notes=_require_str(raw, "operator_notes"),
-                    justification=_require_str(raw, "justification"),
-                    diff=_require_str(raw, "diff"),
-                ))
-            except ValueError:
-                continue
-    return out
+    """Load all audit entries for the given component+slug."""
+    return AuditStore().read_audit_entries(component, slug)
 
 
 # --- Diff rendering --------------------------------------------------------
@@ -433,89 +237,47 @@ def sha256_hex(content: str) -> str:
 class SupervisePlan:
     """Output of Supervise.prepare; consumed by .start.
 
-    `queue_dir` is the host directory bind-mounted into the sidecar
-    at /run/supervise/queue. `internal_network` is empty at prepare
-    time; the backend's launch step fills it via dataclasses.replace
-    before calling .start."""
+    `db_path` is the host database bind-mounted into the sidecar at
+    /run/supervise/bot-bottle.db. `internal_network` is empty at
+    prepare time; the backend's launch step fills it via
+    dataclasses.replace before calling .start."""
 
     slug: str
-    queue_dir: Path
+    db_path: Path
     internal_network: str = ""
 
 
 class Supervise(ABC):
-    """Per-bottle supervise sidecar. Encapsulates the host-side
-    prepare (queue dir staging); the sidecar's start/stop lifecycle
-    is backend-specific."""
+    """Per-bottle supervise sidecar. Encapsulates host-side database
+    staging; the sidecar's start/stop lifecycle is backend-specific."""
 
     def prepare(
         self,
         slug: str,
         stage_dir: Path,
     ) -> SupervisePlan:
-        """Stage the per-bottle queue dir on the host. Returns the
-        plan; `internal_network` must be set by the launch step before
-        .start runs."""
+        """Stage the host database. Returns the plan; `internal_network`
+        must be set by the launch step before .start runs."""
         del stage_dir
-        queue_dir = queue_dir_for_slug(slug)
-        queue_dir.mkdir(parents=True, exist_ok=True)
+        mgr = StoreManager.instance()
+        mgr.migrate()
         return SupervisePlan(
             slug=slug,
-            queue_dir=queue_dir,
+            db_path=mgr.db_path,
         )
 
-# --- Helpers ---------------------------------------------------------------
-
-
-def _require_str(raw: dict[str, object], key: str) -> str:
-    value = raw.get(key)
-    if not isinstance(value, str):
-        raise ValueError(f"missing or non-string field {key!r}")
-    return value
-
-
-def _atomic_write(path: Path, content: str, *, mode: int) -> None:
-    """Atomic: write to a sibling tmp file, fsync, rename."""
-    tmp = path.with_suffix(path.suffix + ".tmp")
-    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, mode)
-    try:
-        os.write(fd, content.encode("utf-8"))
-        os.fsync(fd)
-    finally:
-        os.close(fd)
-    os.replace(tmp, path)
-
-
-try:
-    import fcntl as _fcntl
-
-    def _try_flock(fd: int) -> None:  # type: ignore[reportRedeclaration]
-        try:
-            _fcntl.flock(fd, _fcntl.LOCK_EX)
-        except OSError:
-            pass
-
-    def _try_funlock(fd: int) -> None:  # type: ignore[reportRedeclaration]
-        try:
-            _fcntl.flock(fd, _fcntl.LOCK_UN)
-        except OSError:
-            pass
-except ImportError:  # pragma: no cover — Windows path
-    def _try_flock(fd: int) -> None:  # noqa: F841 — Windows fallback
-        return None
-
-    def _try_funlock(fd: int) -> None:  # noqa: F841 — Windows fallback
-        return None
-
 
 __all__ = [
     "ACTION_OPERATOR_EDIT",
     "AuditEntry",
+    "AuditStore",
     "COMPONENT_FOR_TOOL",
     "DEFAULT_POLL_INTERVAL_SEC",
+    "DB_PATH_IN_CONTAINER",
     "Proposal",
-    "QUEUE_DIR_IN_CONTAINER",
+    "QueueStore",
     "Response",
+    "StoreManager",
     "STATUSES",
     "STATUS_APPROVED",
     "STATUS_MODIFIED",
@@ -536,8 +298,9 @@ __all__ = [
     "audit_dir",
     "audit_log_path",
     "bot_bottle_root",
+    "host_db_path",
     "list_pending_proposals",
-    "queue_dir_for_slug",
+    "list_all_pending_proposals",
     "read_audit_entries",
     "read_proposal",
     "read_response",

bot_bottle/supervise_server.py

@@ -7,14 +7,13 @@ config changes when stuck. The tools are `egress-allow`,
 Each queued tool call:
 
   1. Validates the proposed file syntactically.
-  2. Writes a Proposal to /run/supervise/queue/ (bind-mounted from
-     the host's ~/.bot-bottle/queue/<slug>/).
-  3. Blocks polling for a matching Response file.
+  2. Writes a Proposal to the host SQLite database.
+  3. Blocks polling for a matching Response row.
   4. Returns the operator's `{status, notes}` to the agent.
 
 The bottle slug arrives via SUPERVISE_BOTTLE_SLUG env (stamped at
-container creation by the backend's start step). The queue dir comes
-from SUPERVISE_QUEUE_DIR (default `/run/supervise/queue`).
+container creation by the backend's start step). SUPERVISE_DB_PATH
+points at the bind-mounted host database.
 
 Speaks MCP over HTTP+JSON-RPC. Methods handled:
 
@@ -42,7 +41,6 @@ import typing
 import urllib.error
 import urllib.request
 from dataclasses import dataclass
-from pathlib import Path
 
 try:
     # Same-directory imports inside the bundle container; these files are
@@ -277,7 +275,6 @@ def validate_proposed_file(tool: str, content: str) -> None:
 @dataclass(frozen=True)
 class ServerConfig:
     bottle_slug: str
-    queue_dir: Path
     response_timeout_seconds: float = DEFAULT_RESPONSE_TIMEOUT_SECONDS
 
 
@@ -376,7 +373,7 @@ def handle_tools_call(
         current_file_hash=_sv.sha256_hex(proposed_file),
     )
     try:
-        _sv.write_proposal(config.queue_dir, proposal)
+        _sv.write_proposal(proposal)
     except OSError as e:
         raise _RpcInternalError(f"failed to write proposal to queue: {e}") from e
     sys.stderr.write(
@@ -387,7 +384,7 @@ def handle_tools_call(
     deadline = time.monotonic() + config.response_timeout_seconds
     try:
         response = _sv.wait_for_response(
-            config.queue_dir,
+            config.bottle_slug,
             proposal.id,
             poll_interval=MIN_RESPONSE_POLL_INTERVAL_SECONDS,
             deadline=deadline,
@@ -399,7 +396,7 @@ def handle_tools_call(
             "isError": False,
         }
     try:
-        _sv.archive_proposal(config.queue_dir, proposal.id)
+        _sv.archive_proposal(config.bottle_slug, proposal.id)
     except OSError as e:
         raise _RpcInternalError(f"failed to archive proposal: {e}") from e
 
@@ -539,7 +536,7 @@ class MCPHandler(http.server.BaseHTTPRequestHandler):
 class MCPServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
     allow_reuse_address = True
     daemon_threads = True
-    config: ServerConfig = ServerConfig(bottle_slug="", queue_dir=Path())
+    config: ServerConfig = ServerConfig(bottle_slug="")
 
 
 # --- Entry point -----------------------------------------------------------
@@ -548,21 +545,18 @@ class MCPServer(socketserver.ThreadingMixIn, http.server.HTTPServer):
 def serve(
     *,
     bottle_slug: str,
-    queue_dir: Path,
     port: int = _sv.SUPERVISE_PORT,
     bind: str = "0.0.0.0",
     response_timeout_seconds: float = DEFAULT_RESPONSE_TIMEOUT_SECONDS,
 ) -> typing.NoReturn:
-    queue_dir.mkdir(parents=True, exist_ok=True)
     server = MCPServer((bind, port), MCPHandler)
     server.config = ServerConfig(
         bottle_slug=bottle_slug,
-        queue_dir=queue_dir,
         response_timeout_seconds=response_timeout_seconds,
     )
     sys.stderr.write(
         f"supervise listening on {bind}:{port}; "
-        f"slug={bottle_slug!r}; queue={queue_dir}; "
+        f"slug={bottle_slug!r}; "
         f"tools: {', '.join(t['name'] for t in TOOL_DEFINITIONS)}\n"  # type: ignore[arg-type]
     )
     sys.stderr.flush()
@@ -581,7 +575,6 @@ def main(argv: list[str]) -> int:
     if not bottle_slug:
         sys.stderr.write("supervise: SUPERVISE_BOTTLE_SLUG env is unset\n")
         return 2
-    queue_dir = Path(os.environ.get("SUPERVISE_QUEUE_DIR", _sv.QUEUE_DIR_IN_CONTAINER))
     port = int(os.environ.get("SUPERVISE_PORT", str(_sv.SUPERVISE_PORT)))
     bind = os.environ.get("SUPERVISE_BIND", "0.0.0.0")
     try:
@@ -591,7 +584,6 @@ def main(argv: list[str]) -> int:
         return 2
     serve(
         bottle_slug=bottle_slug,
-        queue_dir=queue_dir,
         port=port,
         bind=bind,
         response_timeout_seconds=response_timeout_seconds,

bot_bottle/supervise_types.py

@@ -0,0 +1,189 @@
+"""Shared types and path helpers for supervise stores (PRD 0013).
+
+Extracted from supervise.py so queue_store and audit_store can import
+Proposal, Response, AuditEntry, and host_db_path without creating a
+circular import (supervise imports from queue_store/audit_store and
+vice-versa).
+
+Patching bot_bottle_root on this module propagates through host_db_path
+because host_db_path looks up bot_bottle_root via sys.modules[__name__]
+at call time rather than capturing it at import time.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import sys
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+HOST_DB_FILENAME = "bot-bottle.db"
+
+TOOL_EGRESS_BLOCK = "egress-block"
+TOOL_EGRESS_ALLOW = "egress-allow"
+TOOL_GITLEAKS_ALLOW = "gitleaks-allow"
+TOOL_EGRESS_TOKEN_ALLOW = "egress-token-allow"
+TOOL_LIST_EGRESS_ROUTES = "list-egress-routes"
+TOOLS: tuple[str, ...] = (
+    TOOL_EGRESS_ALLOW,
+    TOOL_EGRESS_BLOCK,
+    TOOL_GITLEAKS_ALLOW,
+    TOOL_EGRESS_TOKEN_ALLOW,
+    TOOL_LIST_EGRESS_ROUTES,
+)
+
+STATUS_APPROVED = "approved"
+STATUS_MODIFIED = "modified"
+STATUS_REJECTED = "rejected"
+STATUSES: tuple[str, ...] = (STATUS_APPROVED, STATUS_MODIFIED, STATUS_REJECTED)
+
+ACTION_OPERATOR_EDIT = "operator-edit"
+
+
+def bot_bottle_root() -> Path:
+    return Path.home() / ".bot-bottle"
+
+
+def host_db_path() -> Path:
+    # Look up bot_bottle_root through this module's live namespace so that
+    # monkey-patches on supervise_types.bot_bottle_root take effect.
+    #
+    # Lives in its own "db" subdirectory, not directly under
+    # bot_bottle_root(), so backends that can only bind-mount
+    # directories (macos_container's `container run --mount`, which
+    # rejects file sources with "is not a directory") can share this
+    # one file with a sidecar without also exposing bot_bottle_root()'s
+    # other contents (git-gate keys, per-bottle state, etc.).
+    return sys.modules[__name__].bot_bottle_root() / "db" / HOST_DB_FILENAME
+
+
+def _require_str(raw: dict[str, object], key: str) -> str:
+    value = raw.get(key)
+    if not isinstance(value, str):
+        raise ValueError(f"missing or non-string field {key!r}")
+    return value
+
+
+@dataclass(frozen=True)
+class Proposal:
+    """One pending tool-call from the agent."""
+
+    id: str
+    bottle_slug: str
+    tool: str
+    proposed_file: str
+    justification: str
+    arrival_timestamp: str
+    current_file_hash: str
+
+    @classmethod
+    def new(
+        cls,
+        *,
+        bottle_slug: str,
+        tool: str,
+        proposed_file: str,
+        justification: str,
+        current_file_hash: str,
+        now: datetime | None = None,
+    ) -> "Proposal":
+        ts = (now or datetime.now(timezone.utc)).isoformat()
+        return cls(
+            id=str(uuid.uuid4()),
+            bottle_slug=bottle_slug,
+            tool=tool,
+            proposed_file=proposed_file,
+            justification=justification,
+            arrival_timestamp=ts,
+            current_file_hash=current_file_hash,
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return dataclasses.asdict(self)
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, object]) -> "Proposal":
+        tool = _require_str(raw, "tool")
+        if tool not in TOOLS:
+            raise ValueError(f"tool must be one of {TOOLS}; got {tool!r}")
+        return cls(
+            id=_require_str(raw, "id"),
+            bottle_slug=_require_str(raw, "bottle_slug"),
+            tool=tool,
+            proposed_file=_require_str(raw, "proposed_file"),
+            justification=_require_str(raw, "justification"),
+            arrival_timestamp=_require_str(raw, "arrival_timestamp"),
+            current_file_hash=_require_str(raw, "current_file_hash"),
+        )
+
+
+@dataclass(frozen=True)
+class Response:
+    """The operator's decision on a proposal."""
+
+    proposal_id: str
+    status: str
+    notes: str
+    final_file: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return dataclasses.asdict(self)
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, object]) -> "Response":
+        status = _require_str(raw, "status")
+        if status not in STATUSES:
+            raise ValueError(
+                f"response status must be one of {STATUSES}; got {status!r}"
+            )
+        final = raw.get("final_file")
+        if final is not None and not isinstance(final, str):
+            raise ValueError(
+                f"final_file must be a string or null; got {type(final).__name__}"
+            )
+        return cls(
+            proposal_id=_require_str(raw, "proposal_id"),
+            status=status,
+            notes=_require_str(raw, "notes"),
+            final_file=final,
+        )
+
+
+@dataclass(frozen=True)
+class AuditEntry:
+    """One row of the per-bottle audit log."""
+
+    timestamp: str
+    bottle_slug: str
+    component: str
+    operator_action: str
+    operator_notes: str
+    justification: str
+    diff: str
+
+    def to_dict(self) -> dict[str, object]:
+        return dataclasses.asdict(self)
+
+
+__all__ = [
+    "ACTION_OPERATOR_EDIT",
+    "AuditEntry",
+    "HOST_DB_FILENAME",
+    "Proposal",
+    "Response",
+    "STATUSES",
+    "STATUS_APPROVED",
+    "STATUS_MODIFIED",
+    "STATUS_REJECTED",
+    "TOOLS",
+    "TOOL_EGRESS_ALLOW",
+    "TOOL_EGRESS_BLOCK",
+    "TOOL_EGRESS_TOKEN_ALLOW",
+    "TOOL_GITLEAKS_ALLOW",
+    "TOOL_LIST_EGRESS_ROUTES",
+    "bot_bottle_root",
+    "host_db_path",
+]

docs/prds/0067-sqlite-local-storage.md

@@ -0,0 +1,135 @@
+# PRD 0067: SQLite local storage
+
+- **Status:** Active
+- **Author:** codex
+- **Created:** 2026-07-01
+- **Issue:** #319
+
+## Summary
+
+Add a small stdlib SQLite storage layer for bot-bottle host runtime state,
+starting with the supervise queue and audit log. This replaces scattered JSON
+queue files and JSONL audit logs with structured tables while preserving the
+existing public supervise helper functions and sidecar queue mount contract.
+
+## Problem
+
+Bot-bottle currently stores supervise proposals and responses as individual JSON
+files under `~/.bot-bottle/queue/<slug>/`, and audit entries as JSONL files
+under `~/.bot-bottle/audit/`. That worked for the original interactive TUI, but
+new forge-native orchestration needs durable, queryable local state for queues,
+audit trails, watchdogs, and lifecycle records. PR #318 started introducing
+SQLite-shaped boilerplate for forge state; the storage foundation should live in
+its own PR so forge work can build on the shared runtime store instead of adding
+one-off persistence.
+
+## Goals / Success Criteria
+
+1. Supervise proposals and responses are persisted through SQLite.
+2. Audit entries are persisted through SQLite.
+3. Supervise queue helpers use the bottle slug / queue key instead of a queue
+   directory path.
+4. The sidecar receives the host database mount across docker, smolmachines,
+   and macOS-container backends.
+5. The implementation stays stdlib-only.
+6. Schema migrations use a `PRAGMA user_version` runner — no third-party deps.
+7. Unit tests cover queue round-trips, pending discovery, response waits,
+   archive semantics, audit round-trips, and path creation.
+
+## Non-goals
+
+- Migrating old JSON queue files or JSONL audit logs.
+- Adding forge orchestration state tables.
+- Adding egress metering or budget tables.
+- Changing the supervise TUI workflow or remediation behavior.
+- Introducing a third-party ORM or migration library.
+
+## Design
+
+### Database locations
+
+Queue and audit state use the host-level local database:
+
+```text
+~/.bot-bottle/bot-bottle.db
+```
+
+The supervise sidecar receives that database as a writable bind mount at
+`/run/supervise/bot-bottle.db` and gets the path through `SUPERVISE_DB_PATH`.
+No per-slug queue directory is mounted into the sidecar. This creates the shared
+host database that later forge/native lifecycle work can extend in separate
+PRDs.
+
+### Tables
+
+`supervise_proposals` lives in the host database:
+
+```sql
+CREATE TABLE supervise_proposals (
+    queue_key TEXT NOT NULL,
+    id TEXT NOT NULL,
+    bottle_slug TEXT NOT NULL,
+    tool TEXT NOT NULL,
+    proposed_file TEXT NOT NULL,
+    justification TEXT NOT NULL,
+    arrival_timestamp TEXT NOT NULL,
+    current_file_hash TEXT NOT NULL,
+    archived INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (queue_key, id)
+);
+```
+
+`supervise_responses` lives in the host database:
+
+```sql
+CREATE TABLE supervise_responses (
+    queue_key TEXT NOT NULL,
+    proposal_id TEXT NOT NULL,
+    status TEXT NOT NULL,
+    notes TEXT NOT NULL,
+    final_file TEXT,
+    archived INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (queue_key, proposal_id)
+);
+```
+
+`supervise_audit_entries` lives in the host database:
+
+```sql
+CREATE TABLE supervise_audit_entries (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp TEXT NOT NULL,
+    bottle_slug TEXT NOT NULL,
+    component TEXT NOT NULL,
+    operator_action TEXT NOT NULL,
+    operator_notes TEXT NOT NULL,
+    justification TEXT NOT NULL,
+    diff TEXT NOT NULL
+);
+```
+
+### Compatibility
+
+The queue helpers take a bottle slug / queue key and perform equivalent
+operations against `~/.bot-bottle/bot-bottle.db`:
+
+- `list_pending_proposals` returns non-archived proposals without a non-archived
+  response, sorted by arrival time.
+- `archive_proposal` marks matching proposal/response rows archived instead of
+  moving files into `processed/`.
+- `wait_for_response` keeps the current polling behavior but polls SQLite.
+
+The old audit path helpers (`audit_dir`, `audit_log_path`) stay available for
+compatibility. `audit_log_path` no longer describes the active storage location;
+callers should use `read_audit_entries`.
+
+## Implementation chunks
+
+1. Add SQLite store helpers for supervise queue and audit state.
+2. Rewire `bot_bottle.supervise` queue/audit functions to the store.
+3. Update supervise CLI discovery tests and queue/audit unit tests.
+4. Run unit tests, pyright, and pylint for touched modules.
+
+## Open questions
+
+None.

docs/prds/prd-new-forge-native-integration.md

@@ -0,0 +1,439 @@
+# PRD prd-new: Forge native integration
+
+- **Status:** Draft
+- **Author:** claude
+- **Created:** 2026-06-29
+- **Issue:** #317
+
+## Summary
+
+Add a webhook-driven orchestration layer that lets Gitea issues and PR comments
+drive bot-bottle sessions end-to-end with no operator in the loop for the happy
+path. An issue assigned to a member of the configured agent org and labelled
+with an agent name triggers a headless bottle launch; the bottle processes the
+issue, opens a PR, and interacts with the forge through a **forge sidecar** —
+the agent never touches the Gitea API or its credentials directly. The agent
+calls `signal_done(status, summary)` on the sidecar when a work unit is
+complete; the sidecar relays that to the orchestrator over a queue dir (the same
+pattern as the supervise sidecar), so completion is an unambiguous in-band
+signal rather than a comment the orchestrator has to parse. The orchestrator
+freezes the bottle. Subsequent PR comments rehydrate the frozen bottle. The
+bottle is destroyed when the PR closes.
+
+The forge sidecar is backed by a `Forge` abstract class with per-provider
+implementations (Gitea first), so the agent's prompts and the sidecar protocol
+stay forge-agnostic. The sidecar logs forge operations semantically ("read PR
+description", "posted comment", "signalled done"), giving richer provenance than
+post-hoc egress-byte parsing, and enforces a **read-anywhere / write-scoped**
+permission model: the agent may read for context but may only write to the
+issue and PRs it was assigned.
+
+Run provenance is exposed through a **provenance API** (the sidecar's structured
+operation log plus the run's metadata), not posted back into the forge. We do
+not surface a provenance footer in the PR — the audit record lives behind the
+API where it can be retained and queried, rather than as an editable comment.
+
+The separation of concerns across the two layers: bot-bottle owns the headless
+launch primitives, the forge sidecar + `Forge` abstraction, and forge state.
+`bot-bottle-orchestrator` (separate binary) owns the webhook listener, bottle
+lifecycle loop, and monitoring dashboard; it calls into bot-bottle via
+`./cli.py orchestrate`, a thin wrapper command. This PRD covers bot-bottle's
+side of that contract.
+
+## Problem
+
+Today an operator must open the TUI, select an agent and bottle, confirm the
+preflight, and type prompts interactively. This blocks "issue → PR" automation
+and produces no durable audit record of what the agent did. The security model
+already provides the right isolation and egress controls, and `start --headless`
+(#315) already gives `bot-bottle-orchestrator` a non-interactive launch path.
+The missing pieces are a headless `resume` counterpart for rehydrating frozen
+bottles, a forge-interaction surface the agent uses to read context, post
+comments, and signal completion, and the provenance trail that makes the audit
+story legible to reviewers on every PR.
+
+That forge-interaction surface could be built two ways: (2) give the agent the
+Gitea API directly with cred-proxy injecting the token, or (3) put a forge
+sidecar between the agent and the forge. This PRD takes **option 3**. The
+deciding factors: a sidecar `signal_done` call is an unambiguous completion
+signal where comment-parsing is a correctness risk that surfaces in production;
+the sidecar produces a semantic audit trail rather than HTTP bytes, which is
+load-bearing for provenance (the stated product priority); and the sidecar can
+enforce scope tighter than repo-wide API-key permissions, reducing blast radius
+for a prompt-injected agent. The costs — a second sidecar process per forge run,
+a new failure mode if it crashes, and per-forge implementation cost — are
+accepted as the price of those properties.
+
+## Goals / Success Criteria
+
+1. Headless launch already exists: `./cli.py start <agent> --headless --prompt`
+   (#315) runs non-interactively with no TUI selectors or y/N preflight. This
+   PRD builds on it rather than re-introducing it. The remaining gap is a
+   matching headless `resume` path (`./cli.py resume --headless`), since
+   rehydrating a frozen bottle for a new prompt is required by the freeze /
+   rehydrate loop and `resume` has no non-interactive entry point today.
+2. An issue assigned to a member of the configured org (`FORGE_ORG`, default
+   `bot-bottle`) and labelled `bot-bottle:<agent-name>` is the trigger
+   convention. Org membership is verified via the Gitea API at event time.
+3. Forge-targeted bottles run a **forge sidecar** that exposes a small,
+   forge-agnostic API (comment/issue/PR CRUD plus `signal_done`) over the same
+   queue-dir + HTTP/JSON-RPC machinery as the supervise sidecar. The agent calls
+   the sidecar; it never sees the forge token or forge-specific endpoints.
+4. The sidecar is backed by a `Forge` abstract class. Gitea is the first
+   concrete implementation; adding a forge means a new subclass, not changes to
+   the agent prompt or sidecar protocol. The sidecar enforces a read-anywhere /
+   write-scoped model: writes are limited to the assigned issue and its PRs;
+   reads are unrestricted for context.
+5. The agent calls `signal_done(status, summary)` on the sidecar when a work
+   unit is complete; the sidecar relays it to the orchestrator over a queue dir.
+   This is the done signal — no comment parsing. A watchdog timeout
+   (configurable, default 30 min) causes the orchestrator to treat the run as
+   done-without-self-report if the agent exits without signalling.
+6. Run provenance (agent name, bottle name(s), slug, timing, exit code,
+   gitleaks result, egress summary, and the sidecar's semantic operation log)
+   is available through a provenance API. It is **not** surfaced as a PR footer
+   or any other forge comment.
+7. Forge state (issue → slug, status) is persisted in a local SQLite database
+   under `~/.bot-bottle/` and survives orchestrator restarts.
+8. `./cli.py orchestrate status` lists active forge-managed bottles and their
+   issue/PR URLs.
+9. Unit tests cover: label parsing, org-membership check path, forge state
+   store CRUD (SQLite), headless launch arg construction, forge env var
+   injection, sidecar request dispatch through the `Forge` abstraction,
+   write-scope enforcement (reject writes outside the assigned issue/PRs), and
+   `signal_done` queue relay.
+
+## Non-goals
+
+- Webhook signature verification (HMAC-SHA256). Added as a follow-up.
+- The `bot-bottle-orchestrator` binary itself — this PRD covers bot-bottle's
+  side of the interface only. The orchestrator is a separate project.
+- GitHub or GitLab support.
+- Multiple simultaneous forge bottles per issue.
+- Automatic retry on agent error exit.
+- Bottle destruction on issue close (PR close only; issue close is ambiguous).
+- Concurrent multi-issue handling (one blocking run per orchestrator process).
+- A monitoring dashboard (orchestrator-side concern).
+- Folding `DeployKeyProvisioner` into the `Forge` abstraction. Deploy-key
+  provisioning runs at bottle-provision time on the host; the forge sidecar runs
+  inside the bottle at agent time. The two have different lifecycles and actors,
+  so coupling them into one class is deferred to a follow-up. This PRD only
+  shares the Gitea HTTP client between them.
+
+## Design
+
+### Targeting convention
+
+An issue is forge-targeted when **both** hold:
+
+- At least one assignee is a member of the Gitea org named by `FORGE_ORG`
+  (default `bot-bottle`). Checked via `GET /api/v1/orgs/{org}/members/{user}`.
+- At least one label has the prefix `bot-bottle:`. The suffix names the agent
+  manifest, e.g. `bot-bottle:implementer` → agent `implementer`.
+
+`FORGE_ORG` is read at orchestrate-command startup. It is not embedded in
+manifests or state files; the orchestrator stamps its value into log output for
+auditability.
+
+An optional label `bot-bottle-bottle:<name>` overrides bottle selection. When
+absent the agent's default bottle is used.
+
+### `./cli.py orchestrate` — the thin wrapper
+
+```
+./cli.py orchestrate start  --agent AGENT [--bottle BOTTLE ...] --prompt PROMPT
+                            [--label LABEL] [--backend BACKEND]
+./cli.py orchestrate resume --slug SLUG --prompt PROMPT [--backend BACKEND]
+./cli.py orchestrate status
+```
+
+`orchestrate start` is a thin shim over the already-shipped `start --headless`
+(#315): it forwards agent / bottle / label / prompt and adds the forge-specific
+wiring (`forge_env`, sidecar launch). It does not re-implement headless launch.
+The caller (`bot-bottle-orchestrator`) manages freeze, state, and the forge
+sidecar's done signal around it.
+
+`orchestrate resume` is the shim over the new `resume --headless` (below).
+
+`orchestrate status` prints the forge state table.
+
+### Headless primitives — what exists vs. what's new
+
+Headless **start** already shipped in #315 and this PRD reuses it as-is:
+
+- `./cli.py start <agent> --headless --prompt TEXT` — no TUI selectors, no y/N
+  preflight. Internally `_start_headless()` calls the shared `_launch_bottle()`
+  with `assume_yes=True` and `headless_prompt_text=prompt`.
+- The prompt is delivered through `AgentProvider.headless_prompt(prompt)` —
+  claude `-p`, codex positional, pi `-p`. The orchestrator does **not** hand-roll
+  agent args; it relies on this provider abstraction. (An earlier draft proposed
+  `start_headless` / `attach_agent_headless` helpers that constructed
+  `--no-interactive`/`-p` directly — those are dropped as redundant with, and
+  divergent from, what #315 merged.)
+
+Two additions are needed on top of #315:
+
+**1. A `forge_env` hook on the headless launch path.** The orchestrator needs to
+pass forge context + token through to the forge sidecar launched alongside the
+agent. This is a parameter threaded into `_launch_bottle` (the same core
+`start --headless` already uses), not a parallel launch function. The agent
+process itself does not receive the token.
+
+**2. `resume --headless`** — new in `bot_bottle/cli/resume.py`, mirroring the
+`--headless` flag on `start`:
+
+```
+./cli.py resume <slug> --headless --prompt TEXT
+```
+
+It rehydrates a frozen bottle and runs one headless prompt via the same
+`assume_yes` + `headless_prompt` path, returning the agent's exit code. `resume`
+has no non-interactive entry point today, so this is genuinely new work rather
+than a rename of an existing helper.
+
+### Forge sidecar
+
+Forge-targeted bottles run a forge sidecar alongside the agent, mirroring the
+supervise sidecar: a per-bottle process that exposes an HTTP/JSON-RPC endpoint
+over a Unix socket and relays events to the orchestrator through a queue dir.
+The agent calls the sidecar; the sidecar holds the forge token and makes the
+actual forge API calls. The agent never receives the credential and never sees a
+forge-specific endpoint — swapping Gitea for another forge does not change the
+agent prompt or the sidecar protocol.
+
+The sidecar is configured at launch from the forge context (owner, repo, issue,
+PR) and the token, supplied by the orchestrator — not baked into the agent
+manifest. Because the sidecar owns the token, forge traffic does not need a
+cred-proxy egress route on the agent; the agent's egress policy is unchanged by
+forge targeting.
+
+**Sidecar protocol** (forge-agnostic; each method maps to a `Forge` call):
+
+| Method | Scope | Purpose |
+|---|---|---|
+| `read_issue(number)` | read-anywhere | Read an issue body for context |
+| `read_pr(number)` | read-anywhere | Read a PR (incl. merge state) for context |
+| `read_comments(number)` | read-anywhere | Read a thread for context |
+| `post_comment(number, body)` | write-scoped | Post to the assigned issue/PR |
+| `update_description(number, body)` | write-scoped | Edit the assigned issue/PR body |
+| `signal_done(status, summary)` | — | Relay completion to the orchestrator |
+
+Issues and PRs are distinct domain objects (`Issue` vs `PullRequest`) read
+through distinct methods; a PR carries merge state an issue does not.
+
+**Scope enforcement** is read-anywhere / write-scoped: read methods accept any
+issue/PR number for context; write methods are rejected unless the target is the
+assigned issue or one of its PRs. This is tighter than Gitea's repo-wide API-key
+permissions and bounds the blast radius of a prompt-injected agent. Rejections
+are logged semantically (operation, target, reason) so the audit trail records
+attempted out-of-scope writes, not just allowed ones.
+
+**Semantic audit**: every sidecar call is logged as a structured operation
+("read PR #318 description", "posted comment to #317", "signalled done:
+success") rather than as opaque HTTP bytes. This log feeds provenance directly,
+with no post-hoc egress-log parsing.
+
+### `Forge` abstraction — `bot_bottle/contrib/forge/`
+
+The sidecar dispatches to a `Forge` abstract class. Each provider implements the
+operations behind the sidecar protocol:
+
+```python
+class Forge(abc.ABC):
+    @abc.abstractmethod
+    def read_issue(self, number: int) -> Issue: ...
+    @abc.abstractmethod
+    def read_pr(self, number: int) -> PullRequest: ...
+    @abc.abstractmethod
+    def read_comments(self, number: int) -> list[Comment]: ...
+    @abc.abstractmethod
+    def post_comment(self, number: int, body: str) -> None: ...
+    @abc.abstractmethod
+    def update_description(self, number: int, body: str) -> None: ...
+    @abc.abstractmethod
+    def is_org_member(self, org: str, username: str) -> bool: ...
+    @abc.abstractmethod
+    def get_pr_for_issue(self, number: int) -> int | None: ...
+    @abc.abstractmethod
+    def is_pr_open(self, number: int) -> bool: ...
+```
+
+`Issue` and `PullRequest` are separate frozen dataclasses — a PR adds `merged`.
+`ScopedForge` wraps a concrete `Forge` to enforce the read-anywhere /
+write-scoped model (`post_comment` / `update_description` raise `ForgeScopeError`
+outside the assigned issue and PRs).
+
+`GiteaForge` is the first and only concrete implementation in this PRD. It wraps
+the Gitea HTTP client (below). Adding GitHub or GitLab later is a new subclass;
+the sidecar, protocol, and agent prompt are untouched.
+
+> **Deferred:** `DeployKeyProvisioner` is *not* folded into `Forge` here.
+> Deploy-key provisioning runs on the host at provision time; the sidecar runs
+> in the bottle at agent time. They have different lifecycles and actors, so a
+> shared abstract base would couple two unrelated auth contexts. For now they
+> only share the Gitea HTTP client; a later PRD can revisit unification.
+
+### Forge env vars
+
+The orchestrator passes forge context to the **sidecar** (not the agent) at
+launch. The agent does not need owner/repo/issue env vars to construct API
+calls, since it only names issue/PR numbers to the sidecar:
+
+| Var | Example | Purpose |
+|---|---|---|
+| `FORGE_GITEA_API` | `https://gitea.dideric.is/api/v1` | Base URL the sidecar calls |
+| `FORGE_OWNER` | `didericis` | Repo owner |
+| `FORGE_REPO` | `bot-bottle` | Repo name |
+| `FORGE_ISSUE_NUMBER` | `317` | Assigned issue (defines write scope) |
+| `FORGE_PR_NUMBER` | `318` | Assigned PR (empty until PR exists) |
+
+The agent's forge-specific prompt instructs it to call `signal_done` on the
+sidecar when a work unit is complete, and to use the sidecar for any
+comment/description writes. The instruction is forge-agnostic and is part of the
+forge prompt overlay, not the base agent manifest, so non-forge runs are
+unaffected.
+
+### Done signal and watchdog
+
+The agent calls `signal_done(status, summary)` on the sidecar when it finishes a
+work unit. The sidecar writes the event to its queue dir; the orchestrator reads
+it and:
+
+1. Reads the forge state for `(owner, repo, issue_number)`.
+2. If `status == "running"`, treats the event as the done signal: freezes the
+   bottle and sets `status = "frozen"`. Provenance is recorded via the
+   provenance API — no comment is posted to the forge.
+
+Because completion is an explicit `signal_done` call, the orchestrator does not
+parse comment text to detect "done", and intermediate comments the agent posts
+mid-run cannot be mistaken for completion.
+
+**Watchdog**: the orchestrator tracks `last_checkin_at` in forge state, updated
+on each sidecar event. A background thread wakes every minute. If
+`now - last_checkin_at > FORGE_WATCHDOG_TIMEOUT` (default 30 min, configurable
+via env) and `status == "running"`, the orchestrator treats the run as
+done-without-self-report and freezes the bottle, flagging the run as incomplete
+in the provenance record.
+
+**Sidecar-death failure mode**: if the forge sidecar crashes mid-run the agent
+loses forge access while the bottle is otherwise healthy. The orchestrator
+detects a dead sidecar (socket/queue gone) the same way it detects a stalled
+agent and falls back to the watchdog path.
+
+### Forge state — `bot_bottle/contrib/gitea/forge_state.py`
+
+State is stored in a local SQLite database at `~/.bot-bottle/bot-bottle.db`.
+Access goes through a thin CRUD interface, `ForgeStateStore`, so the storage
+location/engine can be swapped without touching callers. `SqliteForgeStateStore`
+is the first implementation.
+
+The `forge_state` table is keyed by `(owner, repo, issue_number)` and carries:
+`slug`, `agent_name`, `bottle_names` (JSON), `backend_name`, `agent_git_user`,
+`pr_number` (nullable), `status`, `last_checkin_at`.
+
+`status`: `"running"` | `"frozen"` | `"destroyed"`.
+
+Store interface:
+
+```python
+class ForgeStateStore(abc.ABC):
+    def upsert(self, state: ForgeState) -> None: ...
+    def get(self, owner: str, repo: str, issue_number: int) -> ForgeState | None: ...
+    def delete(self, owner: str, repo: str, issue_number: int) -> None: ...
+    def all(self) -> list[ForgeState]: ...
+
+class SqliteForgeStateStore(ForgeStateStore):
+    def __init__(self, db_path: Path | None = None) -> None: ...
+```
+
+`upsert` uses `INSERT OR REPLACE` so a re-run for the same issue overwrites in
+place. The schema is created on first open.
+
+### Provenance API
+
+Run provenance — agent, bottle(s), slug, timing, exit code, gitleaks result,
+egress summary, watchdog-fired flag, and the sidecar's semantic operation log —
+is exposed through a **provenance API**, not posted into the forge. There is no
+provenance footer or run-summary comment.
+
+The rationale (per the monetization positioning): a PR comment is mutable by any
+maintainer, unsigned, and per-PR, so it is worthless as an audit record and
+invites false trust. The authoritative record therefore lives behind the API,
+where it can be retained, queried, and (eventually) signed. Whether any
+projection of it ever appears in the forge is a separate, out-of-scope decision;
+this PR does not build one.
+
+The API surface itself (schema, transport, signing, retention) is **out of scope
+for this PRD** and belongs with the orchestrator / control-plane work. bot-bottle
+here only produces the raw material: the sidecar's semantic operation log and the
+run metadata the orchestrator collects.
+
+### Gitea HTTP client — `bot_bottle/contrib/gitea/client.py`
+
+`GiteaForge` (and the existing `GiteaDeployKeyProvisioner`) share one thin HTTP
+client. Unlike the option-2 design, the token is held by the sidecar process and
+passed to the client directly — there is no agent-side cred-proxy route to
+inject it, because the agent never makes forge calls.
+
+```python
+class GiteaClient:
+    def __init__(self, *, api_url: str, owner: str, repo: str, token: str) -> None: ...
+    def is_org_member(self, org: str, username: str) -> bool: ...
+    def get_issue(self, number: int) -> dict: ...
+    def get_comments(self, number: int) -> list[dict]: ...
+    def post_comment(self, number: int, body: str) -> None: ...
+    def patch_issue_body(self, number: int, body: str) -> None: ...
+    def get_pull(self, number: int) -> dict: ...
+```
+
+`GiteaForge` adapts this client to the `Forge` surface (mapping raw JSON to
+`Issue` / `PullRequest` / `Comment`). Sharing only the HTTP client (not an
+abstract base) is the deliberate boundary between the sidecar and the deploy-key
+provisioner — see the deferral note under the `Forge` abstraction.
+
+### Implementation chunks
+
+1. **Headless additions on top of #315** — thread a `forge_env` parameter into
+   the existing `_launch_bottle` core (the one `start --headless` already uses);
+   add a `--headless` path to `cli/resume.py` reusing `assume_yes` +
+   `headless_prompt`. No new `start_headless`/`attach_agent_headless` helpers.
+   Tests: `forge_env` reaches the sidecar/`guest_env`; `resume --headless` skips
+   the TUI and y/N preflight and returns the agent exit code.
+
+2. **Forge state** — `contrib/gitea/forge_state.py`: `ForgeState` dataclass,
+   `ForgeStateStore` CRUD interface, `SqliteForgeStateStore`. Tests: round-trip,
+   missing → None, `INSERT OR REPLACE` upsert, delete idempotent, `all()`
+   ordering, persistence across store instances.
+
+3. **`Forge` abstraction + Gitea client** — `contrib/forge/base.py` (`Forge`
+   ABC, `ScopedForge`, `Issue` / `PullRequest` / `Comment`) and
+   `contrib/gitea/client.py` + `GiteaForge`: `is_org_member`, `read_issue`,
+   `read_pr`, `read_comments`, `post_comment`, `update_description`,
+   `get_pr_for_issue`, `is_pr_open`. Tests: mock `urllib.request.urlopen`,
+   assert payloads and 404-as-false for membership; `ScopedForge` write-scope
+   enforcement.
+
+4. **Forge sidecar** — sidecar process exposing the protocol over a Unix socket,
+   queue-dir relay, write-scope enforcement, semantic op log, `signal_done`.
+   Reuses the supervise sidecar bundle machinery. Tests: dispatch each method to
+   the `Forge`, reject out-of-scope writes, `signal_done` writes a queue event,
+   scope-rejection is logged.
+
+5. **`./cli.py orchestrate`** — `cli/orchestrate.py` with `start`, `resume`,
+   `status` subcommands wired into `cli.py`; `start` launches the forge sidecar
+   alongside the agent for forge-targeted runs. Tests: arg parsing, `start`
+   delegates to `start --headless`, `resume` delegates to `resume --headless`.
+
+## Provenance
+
+Run provenance is captured (sidecar semantic operation log + run metadata) and
+exposed through a provenance API. It is deliberately **not** surfaced in the
+forge — no footer, no run-summary comment. A mutable, unsigned PR comment is not
+an audit record; the authoritative record lives behind the API where it can be
+retained and signed. The `watchdog_fired` flag marks runs where the agent did
+not self-report completion so consumers of the API know the record may be
+incomplete.
+
+The provenance API's schema, transport, signing, and retention are out of scope
+for this PRD (control-plane work); bot-bottle here produces the raw material
+only.

scripts/critical-modules.txt

@@ -22,4 +22,4 @@ bot_bottle/git_gate_provision.py
 bot_bottle/git_http_backend.py
 bot_bottle/supervise.py
 bot_bottle/yaml_subset.py
-bot_bottle/bottle_state.py
+bot_bottle/bottle/state.py

tests/integration/test_sandbox_escape.py

@@ -30,7 +30,7 @@ import unittest
 from pathlib import Path
 
 from bot_bottle.backend import BottleSpec, get_bottle_backend
-from bot_bottle.bottle_state import cleanup_state
+from bot_bottle.bottle.state import cleanup_state
 from bot_bottle.manifest import ManifestIndex
 from tests._docker import skip_unless_docker
 

tests/unit/test_api.py

@@ -0,0 +1,400 @@
+"""Unit: bot_bottle public Python API (bot_bottle/__init__.py surface).
+
+Covers start_headless, resume_headless, freeze, and destroy — the four
+operations the bot-bottle-orchestrator's ProgrammaticBottleRunner uses.
+All I/O is stubbed so no container is created.
+"""
+
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from bot_bottle import BottleError, destroy, freeze, resume_headless, start_headless
+from bot_bottle.log import Die
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_manifest(agent_name: str = "implementer", bottle_name: str = "claude"):
+    manifest = MagicMock()
+    manifest.agents = {agent_name: MagicMock(bottle=bottle_name)}
+    manifest.all_agent_names = [agent_name]
+    manifest.all_bottle_names = [bottle_name]
+    manifest.home_md = None  # eager mode — _peek_agent_bottle uses agents dict
+    manifest.require_agent = MagicMock(return_value=None)
+    return manifest
+
+
+def _metadata(
+    slug: str = "implementer-abc12",
+    agent_name: str = "implementer",
+    backend: str = "docker",
+):
+    md = MagicMock()
+    md.identity = slug
+    md.agent_name = agent_name
+    md.cwd = "/repo"
+    md.copy_cwd = False
+    md.bottle_names = ["claude"]
+    md.backend = backend
+    return md
+
+
+# ---------------------------------------------------------------------------
+# start_headless
+# ---------------------------------------------------------------------------
+
+
+class TestCompatibilityImports(unittest.TestCase):
+    def test_legacy_api_module_reexports_public_runner_api(self):
+        from bot_bottle import api
+        from bot_bottle.bottle import runner
+
+        self.assertIs(api.BottleError, runner.BottleError)
+        self.assertIs(api.start_headless, runner.start_headless)
+
+
+class TestStartHeadless(unittest.TestCase):
+    def setUp(self) -> None:
+        self._manifest = _make_manifest()
+        patch("bot_bottle.bottle.runner.ManifestIndex.resolve", return_value=self._manifest).start()
+        self._launch = patch(
+            "bot_bottle.bottle.runner._launch_bottle", return_value=("implementer-abc12", 0)
+        ).start()
+        patch(
+            "bot_bottle.bottle.runner._uniquify_label_headless", side_effect=str
+        ).start()
+        self.addCleanup(patch.stopall)
+
+    def _spec(self):
+        self._launch.assert_called_once()
+        return self._launch.call_args[0][0]
+
+    def test_returns_slug_on_success(self):
+        slug = start_headless("implementer", prompt="Do it")
+        self.assertEqual("implementer-abc12", slug)
+
+    def test_passes_assume_yes_and_prompt(self):
+        start_headless("implementer", prompt="Do it")
+        kwargs = self._launch.call_args[1]
+        self.assertTrue(kwargs["assume_yes"])
+        self.assertEqual("Do it", kwargs["headless_prompt_text"])
+
+    def test_explicit_bottles_forwarded(self):
+        start_headless("implementer", prompt="Do it", bottles=["dev", "claude"])
+        self.assertEqual(("dev", "claude"), self._spec().bottle_names)
+
+    def test_default_bottle_resolved_from_manifest(self):
+        start_headless("implementer", prompt="Do it")
+        self.assertEqual(("claude",), self._spec().bottle_names)
+
+    def test_forge_env_on_spec(self):
+        env = {"FORGE_GITEA_API": "https://gitea.example.com/api/v1", "FORGE_OWNER": "acme"}
+        start_headless("implementer", prompt="Do it", forge_env=env)
+        self.assertEqual(env, self._spec().forge_env)
+
+    def test_no_forge_env_defaults_to_empty_dict(self):
+        start_headless("implementer", prompt="Do it")
+        self.assertEqual({}, self._spec().forge_env)
+
+    def test_nonzero_exit_raises_bottle_error(self):
+        self._launch.return_value = ("implementer-abc12", 1)
+        with self.assertRaises(BottleError) as ctx:
+            start_headless("implementer", prompt="Do it")
+        self.assertEqual(1, ctx.exception.exit_code)
+
+    def test_no_default_bottle_raises_bottle_error(self):
+        manifest = _make_manifest(bottle_name="")
+        with patch("bot_bottle.bottle.runner.ManifestIndex.resolve", return_value=manifest):
+            with self.assertRaises(BottleError):
+                start_headless("implementer", prompt="Do it")
+        self._launch.assert_not_called()
+
+    def test_manifest_error_in_resolve_raises_bottle_error(self):
+        from bot_bottle.manifest import ManifestError
+        patch(
+            "bot_bottle.bottle.runner.ManifestIndex.resolve", side_effect=ManifestError("bad")
+        ).start()
+        with self.assertRaises(BottleError):
+            start_headless("implementer", prompt="Do it")
+        self._launch.assert_not_called()
+
+    def test_die_from_launch_bottle_raises_bottle_error(self):
+        self._launch.side_effect = Die(3, "backend exploded")
+        with self.assertRaises(BottleError) as ctx:
+            start_headless("implementer", prompt="Do it")
+        self.assertEqual(3, ctx.exception.exit_code)
+
+    def test_backend_name_forwarded(self):
+        start_headless("implementer", prompt="Do it", backend_name="docker")
+        self.assertEqual("docker", self._launch.call_args[1]["backend_name"])
+
+    def test_label_forwarded_to_spec(self):
+        start_headless("implementer", prompt="Do it", label="nightly")
+        self.assertEqual("nightly", self._spec().label)
+
+    def test_color_forwarded_to_spec(self):
+        start_headless("implementer", prompt="Do it", color="green")
+        self.assertEqual("green", self._spec().color)
+
+
+# ---------------------------------------------------------------------------
+# resume_headless
+# ---------------------------------------------------------------------------
+
+
+class TestResumeHeadless(unittest.TestCase):
+    def setUp(self) -> None:
+        self._md = _metadata()
+        patch("bot_bottle.bottle.runner.read_metadata", return_value=self._md).start()
+        manifest = _make_manifest()
+        patch("bot_bottle.bottle.runner.ManifestIndex.resolve", return_value=manifest).start()
+        self._launch = patch(
+            "bot_bottle.bottle.runner._launch_bottle", return_value=("implementer-abc12", 0)
+        ).start()
+        self.addCleanup(patch.stopall)
+
+    def _spec(self):
+        self._launch.assert_called_once()
+        return self._launch.call_args[0][0]
+
+    def test_passes_assume_yes_and_prompt(self):
+        resume_headless("implementer-abc12", prompt="Address review")
+        kwargs = self._launch.call_args[1]
+        self.assertTrue(kwargs["assume_yes"])
+        self.assertEqual("Address review", kwargs["headless_prompt_text"])
+
+    def test_identity_set_on_spec(self):
+        resume_headless("implementer-abc12", prompt="Prompt")
+        self.assertEqual("implementer-abc12", self._spec().identity)
+
+    def test_forge_env_on_spec(self):
+        env = {"FORGE_ISSUE_NUMBER": "42"}
+        resume_headless("implementer-abc12", prompt="Prompt", forge_env=env)
+        self.assertEqual(env, self._spec().forge_env)
+
+    def test_missing_state_raises_bottle_error(self):
+        with patch("bot_bottle.bottle.runner.read_metadata", return_value=None):
+            with self.assertRaises(BottleError):
+                resume_headless("no-such-abc12", prompt="Prompt")
+        self._launch.assert_not_called()
+
+    def test_nonzero_exit_raises_bottle_error(self):
+        self._launch.return_value = ("implementer-abc12", 2)
+        with self.assertRaises(BottleError) as ctx:
+            resume_headless("implementer-abc12", prompt="Prompt")
+        self.assertEqual(2, ctx.exception.exit_code)
+
+    def test_manifest_error_in_resolve_raises_bottle_error(self):
+        from bot_bottle.manifest import ManifestError
+        patch(
+            "bot_bottle.bottle.runner.ManifestIndex.resolve", side_effect=ManifestError("bad")
+        ).start()
+        with self.assertRaises(BottleError):
+            resume_headless("implementer-abc12", prompt="Prompt")
+        self._launch.assert_not_called()
+
+    def test_die_from_launch_bottle_raises_bottle_error(self):
+        self._launch.side_effect = Die(5, "resume failed")
+        with self.assertRaises(BottleError) as ctx:
+            resume_headless("implementer-abc12", prompt="Prompt")
+        self.assertEqual(5, ctx.exception.exit_code)
+
+    def test_backend_from_metadata_when_not_supplied(self):
+        resume_headless("implementer-abc12", prompt="Prompt")
+        self.assertEqual("docker", self._launch.call_args[1]["backend_name"])
+
+    def test_explicit_backend_overrides_metadata(self):
+        resume_headless(
+            "implementer-abc12", prompt="Prompt", backend_name="smolmachines"
+        )
+        self.assertEqual("smolmachines", self._launch.call_args[1]["backend_name"])
+
+
+# ---------------------------------------------------------------------------
+# freeze
+# ---------------------------------------------------------------------------
+
+
+class TestFreeze(unittest.TestCase):
+    def setUp(self) -> None:
+        patch("bot_bottle.bottle.runner.read_metadata", return_value=_metadata()).start()
+        self._freezer = MagicMock()
+        self._get_freezer = patch(
+            "bot_bottle.bottle.runner.get_freezer", return_value=self._freezer
+        ).start()
+        self.addCleanup(patch.stopall)
+
+    def test_calls_commit_slug(self):
+        freeze("implementer-abc12")
+        self._freezer.commit_slug.assert_called_once_with("implementer-abc12")
+
+    def test_backend_from_metadata_when_not_supplied(self):
+        freeze("implementer-abc12")
+        self._get_freezer.assert_called_once_with("docker")
+
+    def test_explicit_backend_used(self):
+        freeze("implementer-abc12", backend_name="smolmachines")
+        self._get_freezer.assert_called_once_with("smolmachines")
+
+    def test_commit_cancelled_raises_bottle_error(self):
+        from bot_bottle.backend.freeze import CommitCancelled
+        self._freezer.commit_slug.side_effect = CommitCancelled("declined")
+        with self.assertRaises(BottleError):
+            freeze("implementer-abc12")
+
+    def test_die_from_freezer_raises_bottle_error(self):
+        self._freezer.commit_slug.side_effect = Die(2, "commit exploded")
+        with self.assertRaises(BottleError) as ctx:
+            freeze("implementer-abc12")
+        self.assertEqual(2, ctx.exception.exit_code)
+
+
+# ---------------------------------------------------------------------------
+# destroy
+# ---------------------------------------------------------------------------
+
+
+class TestDestroy(unittest.TestCase):
+    def setUp(self) -> None:
+        patch("bot_bottle.bottle.runner.read_metadata", return_value=_metadata()).start()
+        self._dd = patch("bot_bottle.bottle.runner._destroy_docker").start()
+        patch("bot_bottle.bottle.runner.clear_preserve_marker").start()
+        self._cleanup = patch("bot_bottle.bottle.runner.cleanup_state").start()
+        self.addCleanup(patch.stopall)
+
+    def test_docker_backend_calls_destroy_docker(self):
+        destroy("implementer-abc12")
+        self._dd.assert_called_once_with("implementer-abc12")
+
+    def test_state_dir_always_cleaned(self):
+        destroy("implementer-abc12")
+        self._cleanup.assert_called_once_with("implementer-abc12")
+
+    def test_smolmachines_backend_calls_destroy_smolmachines(self):
+        patch(
+            "bot_bottle.bottle.runner.read_metadata",
+            return_value=_metadata(backend="smolmachines"),
+        ).start()
+        ds = patch("bot_bottle.bottle.runner._destroy_smolmachines").start()
+        destroy("implementer-abc12")
+        ds.assert_called_once_with("implementer-abc12")
+        self._dd.assert_not_called()
+
+    def test_other_backend_skips_docker_and_smolmachines(self):
+        patch(
+            "bot_bottle.bottle.runner.read_metadata",
+            return_value=_metadata(backend="macos-container"),
+        ).start()
+        ds = patch("bot_bottle.bottle.runner._destroy_smolmachines").start()
+        destroy("implementer-abc12")
+        self._dd.assert_not_called()
+        ds.assert_not_called()
+        self._cleanup.assert_called_once_with("implementer-abc12")
+
+    def test_missing_metadata_defaults_to_docker(self):
+        patch("bot_bottle.bottle.runner.read_metadata", return_value=None).start()
+        destroy("no-state-abc12")
+        self._dd.assert_called_once_with("no-state-abc12")
+
+    def test_explicit_backend_overrides_metadata(self):
+        ds = patch("bot_bottle.bottle.runner._destroy_smolmachines").start()
+        destroy("implementer-abc12", backend_name="smolmachines")
+        ds.assert_called_once_with("implementer-abc12")
+        self._dd.assert_not_called()
+
+    def test_die_from_backend_raises_bottle_error(self):
+        self._dd.side_effect = Die(1, "compose failed")
+        with self.assertRaises(BottleError):
+            destroy("implementer-abc12")
+
+
+# ---------------------------------------------------------------------------
+# _destroy_docker (helper)
+# ---------------------------------------------------------------------------
+
+
+class TestDestroyDocker(unittest.TestCase):
+    def setUp(self) -> None:
+        self._compose_down = patch(
+            "bot_bottle.backend.docker.compose.compose_down"
+        ).start()
+        self._compose_project_name = patch(
+            "bot_bottle.backend.docker.compose.compose_project_name",
+            return_value="bb-proj",
+        ).start()
+        self._state_dir = patch(
+            "bot_bottle.bottle.state.bottle_state_dir",
+            return_value=Path("/fake/state"),
+        ).start()
+        self.addCleanup(patch.stopall)
+
+    def _run(self, exists: bool) -> None:
+        fake_file = MagicMock()
+        fake_file.exists.return_value = exists
+        with patch(
+            "bot_bottle.backend.docker.compose.compose_file_path",
+            return_value=fake_file,
+        ):
+            from bot_bottle.bottle.runner import _destroy_docker
+            _destroy_docker("slug-1")
+
+    def test_calls_compose_down_when_file_exists(self) -> None:
+        self._run(exists=True)
+        self._compose_down.assert_called_once()
+
+    def test_noop_when_compose_file_absent(self) -> None:
+        self._run(exists=False)
+        self._compose_down.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# _destroy_smolmachines (helper)
+# ---------------------------------------------------------------------------
+
+
+class TestDestroySmolmachines(unittest.TestCase):
+    def setUp(self) -> None:
+        self._run = patch("subprocess.run").start()
+        self._run.return_value = MagicMock(returncode=0, stderr="", stdout="")
+        self.addCleanup(patch.stopall)
+
+    def _call(self) -> None:
+        from bot_bottle.bottle.runner import _destroy_smolmachines
+        _destroy_smolmachines("slug-7")
+
+    def test_issues_stop_then_delete(self) -> None:
+        self._call()
+        self.assertEqual(2, self._run.call_count)
+        first_argv = self._run.call_args_list[0][0][0]
+        self.assertIn("stop", first_argv)
+        second_argv = self._run.call_args_list[1][0][0]
+        self.assertIn("delete", second_argv)
+
+    def test_nonzero_delete_does_not_raise(self) -> None:
+        self._run.side_effect = [
+            MagicMock(returncode=0),
+            MagicMock(returncode=1, stderr="not found", stdout=""),
+        ]
+        self._call()  # must not raise
+
+
+# ---------------------------------------------------------------------------
+# public surface exported from bot_bottle.__init__
+# ---------------------------------------------------------------------------
+
+
+class TestPublicSurface(unittest.TestCase):
+    def test_importable_from_package(self):
+        import bot_bottle
+        for name in ("BottleError", "start_headless", "resume_headless", "freeze", "destroy"):
+            self.assertTrue(hasattr(bot_bottle, name), f"missing: {name}")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_bottle_state.py

@@ -8,7 +8,7 @@ from pathlib import Path
 
 from bot_bottle import supervise
 from bot_bottle import bottle_state
-from bot_bottle.bottle_state import (
+from bot_bottle.bottle.state import (
     BottleMetadata,
     read_metadata,
     write_metadata,
@@ -31,6 +31,15 @@ class _FakeHomeMixin:
         self._tmp.cleanup()
 
 
+class TestCompatibilityImports(unittest.TestCase):
+    def test_legacy_bottle_state_module_reexports_state_api(self):
+        from bot_bottle import bottle_state as legacy
+        from bot_bottle.bottle import state
+
+        self.assertIs(legacy.BottleMetadata, state.BottleMetadata)
+        self.assertIs(legacy.read_metadata, state.read_metadata)
+
+
 class TestPerBottleDockerfile(_FakeHomeMixin, unittest.TestCase):
     def setUp(self):
         self._setup_fake_home()

tests/unit/test_cli_dispatch.py

@@ -12,11 +12,19 @@ from unittest.mock import patch
 
 import bot_bottle.cli as climod
 from bot_bottle.cli import main
+from bot_bottle.db_store import DbStore
 from bot_bottle.log import Die
 from bot_bottle.manifest import ManifestError
+from bot_bottle.store_manager import StoreManager
 
 
 class TestMainDispatch(unittest.TestCase):
+    def setUp(self) -> None:
+        patcher = patch.object(DbStore, "is_migrated", return_value=True)
+        self._mock_check = patcher.start()
+        self.addCleanup(patcher.stop)
+        self.addCleanup(StoreManager.reset)
+
     def test_no_args_prints_usage_returns_2(self) -> None:
         with patch("sys.stderr", io.StringIO()):
             self.assertEqual(2, main([]))

tests/unit/test_cli_resume_headless.py

@@ -0,0 +1,75 @@
+"""Unit: `cli.py resume --headless` non-interactive rehydrate path.
+
+The freeze / rehydrate loop needs a non-interactive `resume`: deliver a
+follow-up prompt and skip the y/N preflight, reusing the same launch
+core (`assume_yes` + `headless_prompt_text`) as `start --headless`.
+"""
+
+from __future__ import annotations
+
+import unittest
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import bot_bottle.cli.resume as resume_mod
+from bot_bottle.log import Die
+
+
+def _metadata():
+    md = MagicMock()
+    md.agent_name = "implementer"
+    md.copy_cwd = False
+    md.cwd = "/repo"
+    md.identity = "implementer-abc12"
+    md.bottle_names = ["claude"]
+    md.backend = "docker"
+    return md
+
+
+class ResumeHeadlessTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self._launch = patch.object(
+            resume_mod, "_launch_bottle", return_value=("implementer-abc12", 0)
+        ).start()
+        patch.object(
+            resume_mod, "read_metadata", return_value=_metadata()
+        ).start()
+        manifest = MagicMock()
+        manifest.require_agent = MagicMock(return_value=None)
+        patch.object(
+            resume_mod.ManifestIndex, "resolve", return_value=manifest
+        ).start()
+        self.addCleanup(patch.stopall)
+
+    def _launch_kwargs(self) -> dict[str, Any]:
+        self._launch.assert_called_once()
+        return dict(self._launch.call_args.kwargs)
+
+    def test_headless_passes_assume_yes_and_prompt(self):
+        rc = resume_mod.cmd_resume(
+            ["implementer-abc12", "--headless", "--prompt", "Address the review"]
+        )
+        self.assertEqual(0, rc)
+        kwargs = self._launch_kwargs()
+        self.assertTrue(kwargs["assume_yes"])
+        self.assertEqual("Address the review", kwargs["headless_prompt_text"])
+
+    def test_interactive_resume_unchanged(self):
+        resume_mod.cmd_resume(["implementer-abc12"])
+        kwargs = self._launch_kwargs()
+        self.assertFalse(kwargs["assume_yes"])
+        self.assertEqual("", kwargs["headless_prompt_text"])
+
+    def test_headless_without_prompt_errors(self):
+        with self.assertRaises(Die):
+            resume_mod.cmd_resume(["implementer-abc12", "--headless"])
+        self._launch.assert_not_called()
+
+    def test_prompt_without_headless_errors(self):
+        with self.assertRaises(Die):
+            resume_mod.cmd_resume(["implementer-abc12", "--prompt", "hi"])
+        self._launch.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_cli_start_headless.py

@@ -0,0 +1,188 @@
+"""Unit: `cli.py start --headless` non-interactive launch path.
+
+Headless is the keystone for orchestrators, CI, and webhook
+dispatch: agent/bottles/label come from flags + manifest defaults, no
+TUI selectors fire, and the preflight y/N is auto-confirmed
+(`assume_yes=True`). All actual launch work is stubbed so no container
+is created.
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+from unittest.mock import MagicMock, patch
+
+import bot_bottle.cli.start as start_mod
+import bot_bottle.cli.tui as tui_mod
+from bot_bottle.backend import ActiveAgent
+from bot_bottle.log import Die
+from bot_bottle.manifest import ManifestError
+
+
+def _make_manifest(
+    agent_names: list[str],
+    bottle_names: list[str] | None = None,
+    agent_bottle: str = "",
+):
+    manifest = MagicMock()
+    manifest.agents = {name: MagicMock(bottle=agent_bottle) for name in agent_names}
+    manifest.all_agent_names = sorted(agent_names)
+    manifest.all_bottle_names = sorted(bottle_names or [])
+    manifest.home_md = None  # eager mode so _peek_agent_bottle uses agents dict
+    manifest.require_agent = MagicMock(return_value=None)
+    return manifest
+
+
+def _active_agent(slug: str) -> ActiveAgent:
+    return ActiveAgent(
+        backend_name="docker",
+        slug=slug,
+        agent_name="demo",
+        started_at="2026-01-01T00:00:00+00:00",
+        services=(),
+    )
+
+
+class TestCmdStartHeadless(unittest.TestCase):
+    """Drive `cmd_start --headless` with launch + TUI stubbed out."""
+
+    def setUp(self):
+        self._manifest = _make_manifest(
+            ["researcher", "implementer"], ["claude", "dev"], agent_bottle="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)
+        ).start()
+        # No bottles running by default → no label collision.
+        patch(
+            "bot_bottle.cli.start.enumerate_active_agents", return_value=[]
+        ).start()
+        # If any TUI picker fires in headless mode, that's a bug.
+        self._agent_picker = patch.object(tui_mod, "filter_select").start()
+        self._bottle_picker = patch.object(tui_mod, "filter_multiselect").start()
+        self._modal = patch.object(tui_mod, "name_color_modal").start()
+        patch.dict(os.environ, {}, clear=False).start()
+        os.environ.pop("BOT_BOTTLE_BACKEND", None)
+        self.addCleanup(patch.stopall)
+
+    def _spec(self):
+        self._launch_mock.assert_called_once()
+        return self._launch_mock.call_args[0][0]
+
+    # -- no TUI in headless --------------------------------------------
+
+    def test_headless_fires_no_pickers(self):
+        rc = start_mod.cmd_start(
+            ["--headless", "researcher", "--bottle", "claude", "--prompt", "Do it"]
+        )
+        self.assertEqual(0, rc)
+        self._agent_picker.assert_not_called()
+        self._bottle_picker.assert_not_called()
+        self._modal.assert_not_called()
+
+    def test_headless_assume_yes_forwarded(self):
+        start_mod.cmd_start(
+            ["--headless", "researcher", "--bottle", "claude", "--prompt", "Do it"]
+        )
+        self.assertTrue(self._launch_mock.call_args[1]["assume_yes"])
+
+    # -- prompt --------------------------------------------------------
+
+    def test_headless_without_prompt_dies(self):
+        with self.assertRaises(Die):
+            start_mod.cmd_start(["--headless", "researcher", "--bottle", "claude"])
+        self._launch_mock.assert_not_called()
+
+    def test_headless_prompt_forwarded_to_launch(self):
+        start_mod.cmd_start(
+            ["--headless", "researcher", "--bottle", "claude",
+             "--prompt", "Implement issue #42"]
+        )
+        self.assertEqual(
+            "Implement issue #42",
+            self._launch_mock.call_args[1]["headless_prompt_text"],
+        )
+
+    # -- bottle resolution ---------------------------------------------
+
+    def test_explicit_bottles_forwarded_in_order(self):
+        start_mod.cmd_start(
+            ["--headless", "researcher", "--bottle", "dev", "--bottle", "claude",
+             "--prompt", "Do it"]
+        )
+        self.assertEqual(("dev", "claude"), self._spec().bottle_names)
+
+    def test_omitted_bottle_falls_back_to_agent_default(self):
+        start_mod.cmd_start(["--headless", "implementer", "--prompt", "Do it"])
+        self.assertEqual(("claude",), self._spec().bottle_names)
+
+    def test_no_bottle_and_no_default_dies(self):
+        manifest = _make_manifest(["researcher"], ["claude"], agent_bottle="")
+        with patch(
+            "bot_bottle.cli.start.ManifestIndex.resolve", return_value=manifest
+        ):
+            with self.assertRaises(Die):
+                start_mod.cmd_start(
+                    ["--headless", "researcher", "--prompt", "Do it"]
+                )
+        self._launch_mock.assert_not_called()
+
+    # -- agent resolution ----------------------------------------------
+
+    def test_missing_agent_name_dies(self):
+        with self.assertRaises(Die):
+            start_mod.cmd_start(["--headless"])
+        self._launch_mock.assert_not_called()
+
+    def test_unknown_agent_raises_manifest_error(self):
+        self._manifest.require_agent.side_effect = ManifestError("agent 'x' not defined")
+        with self.assertRaises(ManifestError):
+            start_mod.cmd_start(
+                ["--headless", "x", "--bottle", "claude", "--prompt", "Do it"]
+            )
+        self._launch_mock.assert_not_called()
+
+    # -- label / color -------------------------------------------------
+
+    def test_label_defaults_to_agent_name(self):
+        start_mod.cmd_start(
+            ["--headless", "researcher", "--bottle", "claude", "--prompt", "Do it"]
+        )
+        self.assertEqual("researcher", self._spec().label)
+
+    def test_explicit_label_and_color_forwarded(self):
+        start_mod.cmd_start(
+            ["--headless", "researcher", "--bottle", "claude",
+             "--label", "nightly", "--color", "green", "--prompt", "Do it"]
+        )
+        spec = self._spec()
+        self.assertEqual("nightly", spec.label)
+        self.assertEqual("green", spec.color)
+
+    def test_label_collision_uniquifies(self):
+        with patch(
+            "bot_bottle.cli.start.enumerate_active_agents",
+            return_value=[_active_agent("researcher")],
+        ):
+            start_mod.cmd_start(
+                ["--headless", "researcher", "--bottle", "claude", "--prompt", "Do it"]
+            )
+        self.assertEqual("researcher-2", self._spec().label)
+
+    # -- backend wiring ------------------------------------------------
+
+    def test_backend_flag_forwarded(self):
+        start_mod.cmd_start(
+            ["--headless", "--backend=docker", "researcher", "--bottle", "claude",
+             "--prompt", "Do it"]
+        )
+        self.assertEqual("docker", self._launch_mock.call_args[1]["backend_name"])
+
+
+if __name__ == "__main__":
+    unittest.main()

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()

tests/unit/test_compose.py

@@ -107,7 +107,7 @@ def _egress_plan(
 def _supervise_plan() -> SupervisePlan:
     return SupervisePlan(
         slug=SLUG,
-        queue_dir=STATE / "supervise" / "queue",
+        db_path=STATE / "bot-bottle.db",
         internal_network=f"bot-bottle-net-{SLUG}",
     )
 
@@ -392,7 +392,7 @@ class TestSidecarBundleShape(unittest.TestCase):
         sc = self._render(supervise=True)["services"]["sidecars"]
         env_strings = sc["environment"]
         self.assertIn(f"SUPERVISE_BOTTLE_SLUG={SLUG}", env_strings)
-        self.assertTrue(any(e.startswith("SUPERVISE_QUEUE_DIR=") for e in env_strings))
+        self.assertIn("SUPERVISE_DB_PATH=/run/supervise/bot-bottle.db", env_strings)
         self.assertTrue(any(e.startswith("SUPERVISE_PORT=") for e in env_strings))
 
     def test_volumes_always_includes_egress_ca(self):
@@ -408,8 +408,7 @@ class TestSidecarBundleShape(unittest.TestCase):
         self.assertIn("/etc/egress", targets)
         self.assertIn("/git-gate-entrypoint.sh", targets)
         self.assertIn("/git-gate/creds/upstream-known_hosts", targets)
-        self.assertTrue(any("supervise/queue" in t or t.startswith("/run/supervise")
-                            for t in targets))
+        self.assertIn("/run/supervise/bot-bottle.db", targets)
 
     def test_extra_hosts_omitted_for_git_upstreams(self):
         sc = self._render(with_git=True)["services"]["sidecars"]

tests/unit/test_contrib_claude_provider.py

@@ -74,7 +74,7 @@ def _plan(
     if supervise:
         supervise_plan = SupervisePlan(
             slug="demo-abc12",
-            queue_dir=Path("/tmp/queue"),
+            db_path=Path("/tmp/bot-bottle.db"),
         )
     return DockerBottlePlan(
         spec=spec,
@@ -343,5 +343,14 @@ class TestClaudeSuperviseMcp(unittest.TestCase):
         )
 
 
+class TestClaudeHeadlessPrompt(unittest.TestCase):
+    def test_returns_p_flag_and_prompt(self):
+        self.assertEqual(["-p", "Do the task"], ClaudeAgentProvider().headless_prompt("Do the task"))
+
+    def test_preserves_prompt_text_verbatim(self):
+        text = "Fix issue #42: the widget breaks on empty input"
+        self.assertEqual(["-p", text], ClaudeAgentProvider().headless_prompt(text))
+
+
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_contrib_codex_provider.py

@@ -77,7 +77,7 @@ def _plan(
     if supervise:
         supervise_plan = SupervisePlan(
             slug="demo-abc12",
-            queue_dir=Path("/tmp/queue"),
+            db_path=Path("/tmp/bot-bottle.db"),
         )
     return DockerBottlePlan(
         spec=spec,
@@ -314,5 +314,14 @@ class TestCodexSuperviseMcp(unittest.TestCase):
         )
 
 
+class TestCodexHeadlessPrompt(unittest.TestCase):
+    def test_returns_prompt_as_positional_arg(self):
+        self.assertEqual(["Do the task"], CodexAgentProvider().headless_prompt("Do the task"))
+
+    def test_preserves_prompt_text_verbatim(self):
+        text = "Fix issue #42: the widget breaks on empty input"
+        self.assertEqual([text], CodexAgentProvider().headless_prompt(text))
+
+
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_contrib_forge_base.py

@@ -0,0 +1,107 @@
+"""Unit: Forge abstraction + ScopedForge (PRD forge-native-integration)."""
+
+from __future__ import annotations
+
+import unittest
+
+from bot_bottle.contrib.forge.base import (
+    Comment,
+    Forge,
+    ForgeScopeError,
+    Issue,
+    PullRequest,
+    ScopedForge,
+)
+
+
+class _RecordingForge(Forge):
+    """In-memory fake that records writes."""
+
+    def __init__(self) -> None:
+        self.comments: list[tuple[int, str]] = []
+        self.descriptions: list[tuple[int, str]] = []
+
+    def read_issue(self, number: int) -> Issue:
+        return Issue(number=number, title="t", body="b", state="open")
+
+    def read_pr(self, number: int) -> PullRequest:
+        return PullRequest(
+            number=number, title="pr", body="b", state="open", merged=False
+        )
+
+    def read_comments(self, number: int) -> list[Comment]:
+        return [Comment(id=1, user="alice", body="hi")]
+
+    def post_comment(self, number: int, body: str) -> None:
+        self.comments.append((number, body))
+
+    def update_description(self, number: int, body: str) -> None:
+        self.descriptions.append((number, body))
+
+    def is_org_member(self, org: str, username: str) -> bool:
+        return username == "member"
+
+    def get_pr_for_issue(self, number: int) -> int | None:
+        return 99 if number == 17 else None
+
+    def is_pr_open(self, number: int) -> bool:
+        return True
+
+
+class TestScopedForgeReads(unittest.TestCase):
+    def setUp(self) -> None:
+        self.inner = _RecordingForge()
+        self.scoped = ScopedForge(self.inner, assigned_issue=17, assigned_prs=[42])
+
+    def test_reads_pass_through_to_any_number(self):
+        # A number well outside the writable scope still reads fine.
+        self.assertEqual(123, self.scoped.read_issue(123).number)
+        self.assertEqual("alice", self.scoped.read_comments(500)[0].user)
+
+    def test_read_pr_passes_through(self):
+        pr = self.scoped.read_pr(999)
+        self.assertIsInstance(pr, PullRequest)
+        self.assertEqual(999, pr.number)
+        self.assertFalse(pr.merged)
+
+    def test_membership_and_pr_lookups_delegate(self):
+        self.assertTrue(self.scoped.is_org_member("bot-bottle", "member"))
+        self.assertFalse(self.scoped.is_org_member("bot-bottle", "stranger"))
+        self.assertEqual(99, self.scoped.get_pr_for_issue(17))
+        self.assertTrue(self.scoped.is_pr_open(8000))
+
+
+class TestScopedForgeWrites(unittest.TestCase):
+    def setUp(self) -> None:
+        self.inner = _RecordingForge()
+        self.scoped = ScopedForge(self.inner, assigned_issue=17, assigned_prs=[42])
+
+    def test_writable_set_is_issue_plus_prs(self):
+        self.assertEqual(frozenset({17, 42}), self.scoped.writable)
+
+    def test_write_to_assigned_issue_allowed(self):
+        self.scoped.post_comment(17, "done")
+        self.assertEqual([(17, "done")], self.inner.comments)
+
+    def test_write_to_assigned_pr_allowed(self):
+        self.scoped.update_description(42, "new body")
+        self.assertEqual([(42, "new body")], self.inner.descriptions)
+
+    def test_comment_outside_scope_rejected(self):
+        with self.assertRaises(ForgeScopeError) as ctx:
+            self.scoped.post_comment(500, "spam")
+        self.assertIn("500", str(ctx.exception))
+        self.assertEqual([], self.inner.comments)
+
+    def test_description_outside_scope_rejected(self):
+        with self.assertRaises(ForgeScopeError):
+            self.scoped.update_description(500, "tamper")
+        self.assertEqual([], self.inner.descriptions)
+
+    def test_scope_error_is_permission_error(self):
+        # Sidecars can catch the stdlib base type.
+        self.assertIn(PermissionError, ForgeScopeError.__mro__)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_contrib_gitea_client.py

@@ -0,0 +1,145 @@
+"""Unit: GiteaClient + GiteaForge (PRD forge-native-integration)."""
+
+from __future__ import annotations
+
+import json
+import unittest
+import urllib.error
+from io import BytesIO
+from unittest.mock import MagicMock, patch
+
+from bot_bottle.contrib.gitea.client import GiteaClient, GiteaForge
+
+
+def _client() -> GiteaClient:
+    return GiteaClient(
+        api_url="https://gitea.example.com/api/v1",
+        owner="didericis",
+        repo="bot-bottle",
+        token="test-token",
+    )
+
+
+def _resp(body: object, status: int = 200) -> MagicMock:
+    resp = MagicMock()
+    resp.read.return_value = json.dumps(body).encode() if body is not None else b""
+    resp.status = status
+    resp.__enter__ = lambda s: s  # type: ignore
+    resp.__exit__ = MagicMock(return_value=False)
+    return resp
+
+
+def _http_error(code: int, body: str = "") -> urllib.error.HTTPError:
+    return urllib.error.HTTPError(
+        url="http://x", code=code, msg="err", hdrs=None,  # type: ignore[arg-type]
+        fp=BytesIO(body.encode()),
+    )
+
+
+_URLOPEN = "bot_bottle.contrib.gitea.client.urllib.request.urlopen"
+
+
+class TestOrgMembership(unittest.TestCase):
+    def test_member_returns_true_on_2xx(self):
+        with patch(_URLOPEN, return_value=_resp(None, 204)) as m:
+            self.assertTrue(_client().is_org_member("bot-bottle", "alice"))
+        req = m.call_args.args[0]
+        self.assertIn("/orgs/bot-bottle/members/alice", req.full_url)
+
+    def test_nonmember_returns_false_on_404(self):
+        with patch(_URLOPEN, side_effect=_http_error(404)):
+            self.assertFalse(_client().is_org_member("bot-bottle", "stranger"))
+
+    def test_other_http_error_raises(self):
+        with patch(_URLOPEN, side_effect=_http_error(403, "forbidden")):
+            with self.assertRaises(RuntimeError) as ctx:
+                _client().is_org_member("bot-bottle", "alice")
+        self.assertIn("403", str(ctx.exception))
+
+
+class TestForgeReads(unittest.TestCase):
+    def test_read_issue_maps_fields(self):
+        raw = {"number": 17, "title": "Bug", "body": "broken", "state": "open"}
+        with patch(_URLOPEN, return_value=_resp(raw)) as m:
+            issue = GiteaForge(_client()).read_issue(17)
+        self.assertEqual((17, "Bug", "broken", "open"),
+                         (issue.number, issue.title, issue.body, issue.state))
+        self.assertIn("/repos/didericis/bot-bottle/issues/17",
+                      m.call_args.args[0].full_url)
+
+    def test_read_issue_tolerates_null_body(self):
+        raw = {"number": 17, "title": "T", "body": None, "state": "open"}
+        with patch(_URLOPEN, return_value=_resp(raw)):
+            self.assertEqual("", GiteaForge(_client()).read_issue(17).body)
+
+    def test_read_comments_maps_user_login(self):
+        raw = [
+            {"id": 1, "user": {"login": "alice"}, "body": "hi"},
+            {"id": 2, "user": {"login": "bob"}, "body": "yo"},
+        ]
+        with patch(_URLOPEN, return_value=_resp(raw)):
+            comments = GiteaForge(_client()).read_comments(17)
+        self.assertEqual(["alice", "bob"], [c.user for c in comments])
+        self.assertEqual([1, 2], [c.id for c in comments])
+
+
+class TestForgeWrites(unittest.TestCase):
+    def test_post_comment_payload_and_url(self):
+        with patch(_URLOPEN, return_value=_resp(None, 201)) as m:
+            GiteaForge(_client()).post_comment(17, "done ✓")
+        req = m.call_args.args[0]
+        self.assertEqual("POST", req.method)
+        self.assertIn("/repos/didericis/bot-bottle/issues/17/comments", req.full_url)
+        self.assertEqual("done ✓", json.loads(req.data)["body"])
+
+    def test_update_description_patches_issue(self):
+        with patch(_URLOPEN, return_value=_resp(None, 200)) as m:
+            GiteaForge(_client()).update_description(17, "edited")
+        req = m.call_args.args[0]
+        self.assertEqual("PATCH", req.method)
+        self.assertTrue(req.full_url.endswith("/issues/17"))
+        self.assertEqual("edited", json.loads(req.data)["body"])
+
+    def test_auth_header_sent(self):
+        with patch(_URLOPEN, return_value=_resp(None, 201)) as m:
+            GiteaForge(_client()).post_comment(17, "x")
+        self.assertEqual("token test-token",
+                         m.call_args.args[0].headers["Authorization"])
+
+
+class TestPRHelpers(unittest.TestCase):
+    def test_get_pr_for_issue_returns_number_when_issue_is_pr(self):
+        raw = {"number": 18, "pull_request": {"merged": False}}
+        with patch(_URLOPEN, return_value=_resp(raw)):
+            self.assertEqual(18, GiteaForge(_client()).get_pr_for_issue(18))
+
+    def test_get_pr_for_issue_none_for_plain_issue(self):
+        raw = {"number": 17, "pull_request": None}
+        with patch(_URLOPEN, return_value=_resp(raw)):
+            self.assertIsNone(GiteaForge(_client()).get_pr_for_issue(17))
+
+    def test_is_pr_open_true_when_state_open(self):
+        with patch(_URLOPEN, return_value=_resp({"state": "open"})):
+            self.assertTrue(GiteaForge(_client()).is_pr_open(18))
+
+    def test_is_pr_open_false_when_closed(self):
+        with patch(_URLOPEN, return_value=_resp({"state": "closed"})):
+            self.assertFalse(GiteaForge(_client()).is_pr_open(18))
+
+    def test_read_pr_maps_fields_including_merged(self):
+        raw = {"number": 18, "title": "Fix", "body": "patch",
+               "state": "closed", "merged": True}
+        with patch(_URLOPEN, return_value=_resp(raw)) as m:
+            pr = GiteaForge(_client()).read_pr(18)
+        self.assertEqual((18, "Fix", "patch", "closed", True),
+                         (pr.number, pr.title, pr.body, pr.state, pr.merged))
+        self.assertIn("/repos/didericis/bot-bottle/pulls/18",
+                      m.call_args.args[0].full_url)
+
+    def test_read_pr_merged_defaults_false(self):
+        with patch(_URLOPEN, return_value=_resp({"number": 18, "state": "open"})):
+            self.assertFalse(GiteaForge(_client()).read_pr(18).merged)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_contrib_gitea_forge_state.py

@@ -0,0 +1,99 @@
+"""Unit: SQLite forge state store (PRD forge-native-integration)."""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from dataclasses import replace
+from pathlib import Path
+
+from bot_bottle.contrib.gitea.forge_state import (
+    STATUS_FROZEN,
+    STATUS_RUNNING,
+    ForgeState,
+    SqliteForgeStateStore,
+)
+
+
+def _state(**over: object) -> ForgeState:
+    base = ForgeState(
+        owner="didericis",
+        repo="bot-bottle",
+        issue_number=17,
+        slug="implementer-abc12",
+        agent_name="implementer",
+        bottle_names=["claude"],
+        backend_name="docker",
+        agent_git_user="didericis-claude",
+        pr_number=42,
+        status=STATUS_FROZEN,
+        last_checkin_at="2026-06-29T12:04:12-04:00",
+    )
+    return replace(base, **over)
+
+
+class ForgeStateStoreTest(unittest.TestCase):
+    def setUp(self) -> None:
+        tmp = Path(self.enterContext(tempfile.TemporaryDirectory()))  # pylint: disable=consider-using-with
+        self.store = SqliteForgeStateStore(tmp / "sub" / "bot-bottle.db")
+
+    def test_round_trip(self):
+        self.store.upsert(_state())
+        self.assertEqual(_state(), self.store.get("didericis", "bot-bottle", 17))
+
+    def test_missing_returns_none(self):
+        self.assertIsNone(self.store.get("nobody", "nope", 1))
+
+    def test_creates_db_parent_dirs(self):
+        # setUp pointed at a non-existent 'sub/' dir; init must create it.
+        self.assertIsNone(self.store.get("x", "y", 1))  # no raise
+
+    def test_upsert_replaces(self):
+        self.store.upsert(_state(status=STATUS_RUNNING))
+        self.store.upsert(_state(status=STATUS_FROZEN))
+        got = self.store.get("didericis", "bot-bottle", 17)
+        assert got is not None
+        self.assertEqual(STATUS_FROZEN, got.status)
+        # Still one row, not two.
+        self.assertEqual(1, len(self.store.all()))
+
+    def test_delete_is_idempotent(self):
+        self.store.upsert(_state())
+        self.store.delete("didericis", "bot-bottle", 17)
+        self.store.delete("didericis", "bot-bottle", 17)  # no raise
+        self.assertIsNone(self.store.get("didericis", "bot-bottle", 17))
+
+    def test_all_lists_across_repos_sorted(self):
+        self.store.upsert(_state(issue_number=18, slug="other"))
+        self.store.upsert(_state(issue_number=17))
+        self.store.upsert(_state(owner="acme", repo="widget", issue_number=3))
+        states = self.store.all()
+        self.assertEqual(3, len(states))
+        self.assertEqual(
+            [("acme", 3), ("didericis", 17), ("didericis", 18)],
+            [(s.owner, s.issue_number) for s in states],
+        )
+
+    def test_all_empty(self):
+        self.assertEqual([], self.store.all())
+
+    def test_bottle_names_list_preserved(self):
+        self.store.upsert(_state(bottle_names=["claude", "dev"]))
+        got = self.store.get("didericis", "bot-bottle", 17)
+        assert got is not None
+        self.assertEqual(["claude", "dev"], got.bottle_names)
+
+    def test_pr_number_nullable(self):
+        self.store.upsert(_state(pr_number=None))
+        got = self.store.get("didericis", "bot-bottle", 17)
+        assert got is not None
+        self.assertIsNone(got.pr_number)
+
+    def test_persists_across_store_instances(self):
+        self.store.upsert(_state())
+        reopened = SqliteForgeStateStore(self.store._db_path)  # pylint: disable=protected-access
+        self.assertEqual(_state(), reopened.get("didericis", "bot-bottle", 17))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_contrib_pi_provider.py

@@ -223,5 +223,14 @@ class TestPiDockerfile(unittest.TestCase):
         self.assertIn("chmod 1777 /tmp /var/tmp", dockerfile)
 
 
+class TestPiHeadlessPrompt(unittest.TestCase):
+    def test_returns_p_flag_and_prompt(self):
+        self.assertEqual(["-p", "Do the task"], PiAgentProvider().headless_prompt("Do the task"))
+
+    def test_preserves_prompt_text_verbatim(self):
+        text = "Fix issue #42: the widget breaks on empty input"
+        self.assertEqual(["-p", text], PiAgentProvider().headless_prompt(text))
+
+
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_docker_provision_git_user.py

@@ -38,6 +38,7 @@ class _Provider(AgentProvider):
     def provision_prompt(self, plan, bottle): ...  # type: ignore[override]
     def provision(self, plan, bottle): ...  # type: ignore[override]
     def provision_supervise_mcp(self, plan, bottle, supervise_url): ...  # type: ignore[override]
+    def headless_prompt(self, prompt): return []  # type: ignore[override]
 
 
 _PROVIDER = _Provider()

tests/unit/test_egress_addon_log_redaction.py

@@ -47,7 +47,6 @@ def _addon() -> EgressAddon:
     a: EgressAddon = EgressAddon.__new__(EgressAddon)
     a.config = Config(routes=(), log=LOG_FULL)
     a.safe_tokens = set()
-    a._supervise_queue_dir = ""
     a._supervise_slug = ""
     a._token_allow_timeout = 300.0
     return a

tests/unit/test_egress_addon_request_flow.py

@@ -212,7 +212,6 @@ def _addon(config: Config) -> EgressAddon:
     a: EgressAddon = EgressAddon.__new__(EgressAddon)
     a.config = config
     a.safe_tokens = set()
-    a._supervise_queue_dir = ""
     a._supervise_slug = ""
     a._token_allow_timeout = 300.0
     a.routes_path = "/nonexistent/routes.yaml"
@@ -386,10 +385,10 @@ def _fake_sv(response_status: str | None) -> types.SimpleNamespace:
     def _sha256_hex(_payload: Any) -> str:
         return "hash"
 
-    def _noop(_a: Any, _b: Any) -> None:
+    def _noop(*_args: Any) -> None:
         return None
 
-    def _read_response(_qd: Any, _pid: Any) -> Any:
+    def _read_response(_slug: Any, _pid: Any) -> Any:
         if response_status is None:
             raise OSError("not written yet")  # forces poll -> timeout
         return types.SimpleNamespace(status=response_status)
@@ -409,7 +408,6 @@ def _fake_sv(response_status: str | None) -> types.SimpleNamespace:
 class TestSuperviseBranch(unittest.TestCase):
     def _supervised_addon(self) -> EgressAddon:
         addon = _addon(Config(routes=(Route(host="api.example.com"),)))
-        addon._supervise_queue_dir = "/tmp/egress-queue"
         addon._supervise_slug = "test-bottle"
         addon._token_allow_timeout = 0.05
         return addon
@@ -632,14 +630,13 @@ class TestRedactSurfaces(unittest.TestCase):
 class TestSuperviseWriteFailure(unittest.TestCase):
     def test_write_proposal_oserror_blocks(self) -> None:
         addon = _addon(Config(routes=(Route(host="api.example.com"),)))
-        addon._supervise_queue_dir = "/tmp/egress-queue"
         addon._supervise_slug = "test-bottle"
         addon._token_allow_timeout = 0.05
         flow = _Flow(_Request(host="api.example.com", method="POST", body=f"k={_OPENAI_KEY}"))
 
         fake = _fake_sv("approved")
 
-        def _raise(_qd: Any, _p: Any) -> None:
+        def _raise(_p: Any) -> None:
             raise OSError("disk full")
 
         fake.write_proposal = _raise

tests/unit/test_git_gate.py

@@ -14,6 +14,7 @@ from bot_bottle.git_gate import (
     git_gate_render_access_hook,
     git_gate_render_entrypoint,
     git_gate_render_hook,
+    provision_git_gate_dynamic_keys,
     revoke_git_gate_provisioned_keys,
     _resolve_identity_file,
     git_gate_upstreams_for_bottle,
@@ -209,8 +210,9 @@ class TestHookRender(unittest.TestCase):
         # the suppressed findings for human approval.
         self.assertIn("--ignore-gitleaks-allow", hook)
         self.assertIn("--report-format=json", hook)
-        self.assertIn('"tool": "gitleaks-allow"', hook)
-        self.assertIn("SUPERVISE_QUEUE_DIR", hook)
+        self.assertIn("tool=_sv.TOOL_GITLEAKS_ALLOW", hook)
+        self.assertIn("_sv.write_proposal", hook)
+        self.assertIn("_sv.read_response", hook)
         self.assertIn("SUPERVISE_BOTTLE_SLUG", hook)
         self.assertIn("supervisor approved # gitleaks:allow", hook)
         self.assertIn("supervisor rejected # gitleaks:allow", hook)
@@ -371,6 +373,27 @@ class TestDynamicKeyProvisioning(unittest.TestCase):
             self.assertEqual("/tmp/provisioned-key", _resolve_identity_file(entry, "demo", self.stage))
         mock_provision.assert_called_once()
 
+    def test_prepare_defers_gitea_key_provisioning(self):
+        bottle = self._gitea_manifest().bottles["dev"]
+        with patch("bot_bottle.git_gate_provision._provision_dynamic_key") as mock_provision:
+            plan = _StubGate().prepare(bottle, "demo", self.stage)
+
+        mock_provision.assert_not_called()
+        self.assertEqual("", plan.upstreams[0].identity_file)
+
+    def test_launch_time_helper_provisions_gitea_keys(self):
+        bottle = self._gitea_manifest().bottles["dev"]
+        plan = _StubGate().prepare(bottle, "demo", self.stage)
+
+        with patch(
+            "bot_bottle.git_gate_provision._provision_dynamic_key",
+            return_value="/tmp/provisioned-key",
+        ) as mock_provision:
+            updated = provision_git_gate_dynamic_keys(bottle, plan, self.stage)
+
+        mock_provision.assert_called_once_with(bottle.git[0], "demo", self.stage)
+        self.assertEqual("/tmp/provisioned-key", updated.upstreams[0].identity_file)
+
     def test_revoke_skips_non_gitea_and_missing_id_file(self):
         revoke_git_gate_provisioned_keys(fixture_with_git().bottles["dev"], self.stage)
 

tests/unit/test_macos_container_launch.py

@@ -71,7 +71,9 @@ def _plan(
     else:
         git_gate_plan = SimpleNamespace(upstreams=())
     supervise_plan = (
-        SimpleNamespace(queue_dir=Path("/state/supervise/queue"))
+        SimpleNamespace(
+            db_path=Path("/state/bot-bottle.db"),
+        )
         if supervise else None
     )
     agent_provision = SimpleNamespace(
@@ -137,7 +139,7 @@ class TestMacosContainerLaunchArgv(unittest.TestCase):
             argv,
         )
         self.assertIn(
-            "type=bind,source=/state/supervise/queue,target=/run/supervise/queue",
+            "type=bind,source=/state,target=/run/supervise",
             argv,
         )
 

tests/unit/test_manifest_validation.py

@@ -165,6 +165,22 @@ class TestAgentValidation(unittest.TestCase):
         with self.assertRaises(ManifestError):
             ManifestAgent.from_dict("a", {"skills": [5]}, set())
 
+    def test_skill_name_rejects_shell_metacharacters(self) -> None:
+        # Skill names become host/guest path segments interpolated into
+        # provisioning shell commands; anything outside kebab-case is
+        # rejected at load so it can never reach a `bottle.exec` string.
+        for bad in ("foo; rm -rf /", "../escape", "foo bar", "Foo", "-leading"):
+            with self.assertRaises(ManifestError):
+                ManifestAgent.from_dict("a", {"skills": [bad]}, set())
+
+    def test_skill_name_accepts_kebab_case(self) -> None:
+        agent = ManifestAgent.from_dict(
+            "a", {"skills": ["init-entry", "quality-eval", "skill0"]}, set()
+        )
+        self.assertEqual(
+            agent.skills, ("init-entry", "quality-eval", "skill0")
+        )
+
     def test_prompt_not_string(self) -> None:
         with self.assertRaises(ManifestError):
             ManifestAgent.from_dict("a", {"prompt": 5}, set())

tests/unit/test_smolmachines_provision.py

@@ -49,6 +49,7 @@ class _Provider(AgentProvider):
     def provision_prompt(self, plan, bottle): ...  # type: ignore[override]
     def provision(self, plan, bottle): ...  # type: ignore[override]
     def provision_supervise_mcp(self, plan, bottle, supervise_url): ...  # type: ignore[override]
+    def headless_prompt(self, prompt): return []  # type: ignore[override]
 
 
 _PROVIDER = _Provider()
@@ -129,7 +130,7 @@ def _plan(
     if supervise:
         supervise_plan = SupervisePlan(
             slug="demo-abc12",
-            queue_dir=Path("/tmp/queue"),
+            db_path=Path("/tmp/bot-bottle.db"),
         )
     return SmolmachinesBottlePlan(
         spec=spec,
@@ -421,6 +422,14 @@ class TestBundleLaunchSpec(unittest.TestCase):
             spec.environment,
         )
 
+    def test_supervise_adds_daemon_volume_and_env(self):
+        from bot_bottle.supervise import DB_PATH_IN_CONTAINER
+        plan = _plan(supervise=True)
+        spec = _bundle_launch_spec(plan, "net", "127.0.0.16")
+        self.assertIn("supervise", spec.daemons_csv)
+        self.assertIn(f"SUPERVISE_DB_PATH={DB_PATH_IN_CONTAINER}", spec.environment)
+        self.assertIn(("/tmp/bot-bottle.db", DB_PATH_IN_CONTAINER, False), spec.volumes)
+
     def test_canary_env_visible_to_smolvm_guest(self):
         plan = _plan(canary=True)
         with patch.object(

tests/unit/test_supervise.py

@@ -1,6 +1,5 @@
 """Unit: supervise queue + audit log + diff helpers (PRD 0013)."""
 
-import json
 import tempfile
 import threading
 import time
@@ -9,6 +8,9 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from bot_bottle import supervise
+from bot_bottle import supervise_types as sv_types
+from bot_bottle.audit_store import AuditStore
+from bot_bottle.queue_store import QueueStore
 from bot_bottle.supervise import (
     AuditEntry,
     Proposal,
@@ -19,7 +21,7 @@ from bot_bottle.supervise import (
     TOOL_EGRESS_ALLOW,
     TOOL_GITLEAKS_ALLOW,
     archive_proposal,
-    audit_log_path,
+    host_db_path,
     list_pending_proposals,
     read_audit_entries,
     read_proposal,
@@ -112,32 +114,52 @@ class TestResponseRoundtrip(unittest.TestCase):
 class TestQueueIO(unittest.TestCase):
     def setUp(self):
         self._tmp = tempfile.TemporaryDirectory(prefix="bot-bottle-supervise-test.")
-        self.queue_dir = Path(self._tmp.name)
+        self._home_patch = self._patch_home(Path(self._tmp.name))
+        self.slug = "dev"
+        QueueStore("").migrate()
 
     def tearDown(self):
+        self._home_patch()
         self._tmp.cleanup()
 
+    def _patch_home(self, fake_home: Path):
+        original_sv = supervise.bot_bottle_root
+        original_svt = sv_types.bot_bottle_root
+
+        def fake_root() -> Path:
+            return fake_home / ".bot-bottle"
+
+        supervise.bot_bottle_root = fake_root  # type: ignore[assignment]
+        sv_types.bot_bottle_root = fake_root  # type: ignore[assignment]
+
+        def restore() -> None:
+            supervise.bot_bottle_root = original_sv  # type: ignore[assignment]
+            sv_types.bot_bottle_root = original_svt  # type: ignore[assignment]
+
+        return restore
+
     def test_write_and_read_proposal(self):
         p = _proposal()
-        path = write_proposal(self.queue_dir, p)
+        path = write_proposal(p)
         self.assertTrue(path.exists())
+        self.assertEqual(host_db_path(), path)
         self.assertEqual(0o600, path.stat().st_mode & 0o777)
-        loaded = read_proposal(self.queue_dir, p.id)
+        loaded = read_proposal(self.slug, p.id)
         self.assertEqual(p, loaded)
 
     def test_list_pending_excludes_responded(self):
         a = _proposal(justification="first")
         b = _proposal(justification="second")
-        write_proposal(self.queue_dir, a)
-        write_proposal(self.queue_dir, b)
-        write_response(self.queue_dir, Response(
+        write_proposal(a)
+        write_proposal(b)
+        write_response(self.slug, Response(
             proposal_id=a.id, status=STATUS_APPROVED, notes="",
         ))
-        pending = list_pending_proposals(self.queue_dir)
+        pending = list_pending_proposals(self.slug)
         self.assertEqual([b.id], [p.id for p in pending])
 
-    def test_list_pending_returns_empty_for_missing_dir(self):
-        self.assertEqual([], list_pending_proposals(self.queue_dir / "nope"))
+    def test_list_pending_returns_empty_for_missing_slug(self):
+        self.assertEqual([], list_pending_proposals("nope"))
 
     def test_list_pending_sorted_by_arrival(self):
         # Fabricate two with explicit timestamps.
@@ -154,30 +176,30 @@ class TestQueueIO(unittest.TestCase):
             now=datetime(2026, 5, 25, 14, 0, 0, tzinfo=timezone.utc),
         )
         # Write in reverse order.
-        write_proposal(self.queue_dir, b)
-        write_proposal(self.queue_dir, a)
-        ordered = list_pending_proposals(self.queue_dir)
+        write_proposal(b)
+        write_proposal(a)
+        ordered = list_pending_proposals(self.slug)
         self.assertEqual([a.id, b.id], [p.id for p in ordered])
 
     def test_write_and_read_response(self):
         r = Response(proposal_id="xyz", status=STATUS_REJECTED, notes="no")
-        write_response(self.queue_dir, r)
-        self.assertEqual(r, read_response(self.queue_dir, "xyz"))
+        write_response(self.slug, r)
+        self.assertEqual(r, read_response(self.slug, "xyz"))
 
     def test_wait_for_response_returns_when_file_appears(self):
         p = _proposal()
-        write_proposal(self.queue_dir, p)
+        write_proposal(p)
 
         def write_after_delay():
             time.sleep(0.05)
-            write_response(self.queue_dir, Response(
+            write_response(self.slug, Response(
                 proposal_id=p.id, status=STATUS_APPROVED, notes="ok",
             ))
 
         t = threading.Thread(target=write_after_delay)
         t.start()
         try:
-            r = wait_for_response(self.queue_dir, p.id, poll_interval=0.01)
+            r = wait_for_response(self.slug, p.id, poll_interval=0.01)
         finally:
             t.join()
         self.assertEqual(STATUS_APPROVED, r.status)
@@ -187,44 +209,51 @@ class TestQueueIO(unittest.TestCase):
         deadline = time.monotonic() + 0.05
         with self.assertRaises(TimeoutError):
             wait_for_response(
-                self.queue_dir, "never",
+                self.slug, "never",
                 poll_interval=0.01, deadline=deadline,
             )
 
-    def test_archive_proposal_moves_both_files(self):
+    def test_archive_proposal_hides_rows(self):
         p = _proposal()
-        write_proposal(self.queue_dir, p)
-        write_response(self.queue_dir, Response(
+        write_proposal(p)
+        write_response(self.slug, Response(
             proposal_id=p.id, status=STATUS_APPROVED, notes="",
         ))
-        archive_proposal(self.queue_dir, p.id)
-        self.assertFalse((self.queue_dir / f"{p.id}.proposal.json").exists())
-        self.assertFalse((self.queue_dir / f"{p.id}.response.json").exists())
-        self.assertTrue((self.queue_dir / "processed" / f"{p.id}.proposal.json").exists())
-        self.assertTrue((self.queue_dir / "processed" / f"{p.id}.response.json").exists())
+        archive_proposal(self.slug, p.id)
+        self.assertEqual([], list_pending_proposals(self.slug))
+        with self.assertRaises(FileNotFoundError):
+            read_response(self.slug, p.id)
 
     def test_archive_is_idempotent_on_missing_files(self):
         # Should not raise.
-        archive_proposal(self.queue_dir, "nope")
+        archive_proposal(self.slug, "nope")
 
 
 class TestAuditLog(unittest.TestCase):
     def setUp(self):
         self._tmp = tempfile.TemporaryDirectory(prefix="bot-bottle-supervise-audit.")
         self._home_patch = self._patch_home(Path(self._tmp.name))
+        AuditStore().migrate()
 
     def tearDown(self):
         self._home_patch()
         self._tmp.cleanup()
 
     def _patch_home(self, fake_home: Path):
-        original = supervise.bot_bottle_root
+        original_sv = supervise.bot_bottle_root
+        original_svt = sv_types.bot_bottle_root
 
         def fake_root() -> Path:
             return fake_home / ".bot-bottle"
 
         supervise.bot_bottle_root = fake_root  # type: ignore[assignment]
-        return lambda: setattr(supervise, "bot_bottle_root", original)
+        sv_types.bot_bottle_root = fake_root  # type: ignore[assignment]
+
+        def restore() -> None:
+            supervise.bot_bottle_root = original_sv  # type: ignore[assignment]
+            sv_types.bot_bottle_root = original_svt  # type: ignore[assignment]
+
+        return restore
 
     def test_write_then_read_single_entry(self):
         e = AuditEntry(
@@ -237,6 +266,7 @@ class TestAuditLog(unittest.TestCase):
             diff="--- before\n+++ after\n",
         )
         path = write_audit_entry(e)
+        self.assertEqual(host_db_path(), path)
         self.assertEqual(0o600, path.stat().st_mode & 0o777)
         loaded = read_audit_entries("cred-proxy", "dev")
         self.assertEqual([e], loaded)
@@ -252,12 +282,13 @@ class TestAuditLog(unittest.TestCase):
                 justification="",
                 diff="",
             ))
-        path = audit_log_path("egress", "dev")
-        with path.open() as f:
-            lines = [line for line in f if line.strip()]
-        self.assertEqual(3, len(lines))
-        for line in lines:
-            self.assertTrue(json.loads(line))  # each line is valid JSON
+        entries = read_audit_entries("egress", "dev")
+        self.assertEqual(3, len(entries))
+        self.assertEqual(
+            ["2026-05-25T12:00:00+00:00", "2026-05-25T12:00:01+00:00",
+             "2026-05-25T12:00:02+00:00"],
+            [entry.timestamp for entry in entries],
+        )
 
     def test_separate_logs_per_component_slug(self):
         write_audit_entry(AuditEntry(
@@ -369,17 +400,24 @@ class TestSupervisePrepare(unittest.TestCase):
         self._tmp.cleanup()
 
     def _patch_home(self, fake_home: Path):
-        original = supervise.bot_bottle_root
+        original_sv = supervise.bot_bottle_root
+        original_svt = sv_types.bot_bottle_root
 
         def fake_root() -> Path:
             return fake_home / ".bot-bottle"
 
         supervise.bot_bottle_root = fake_root  # type: ignore[assignment]
-        return lambda: setattr(supervise, "bot_bottle_root", original)
+        sv_types.bot_bottle_root = fake_root  # type: ignore[assignment]
+
+        def restore() -> None:
+            supervise.bot_bottle_root = original_sv  # type: ignore[assignment]
+            sv_types.bot_bottle_root = original_svt  # type: ignore[assignment]
+
+        return restore
 
     def test_prepare_creates_queue(self):
         plan = _StubSupervise().prepare("dev", self.stage_dir)
-        self.assertTrue(plan.queue_dir.is_dir())
+        self.assertTrue(plan.db_path.is_file())
         self.assertEqual("dev", plan.slug)
         self.assertEqual("", plan.internal_network)
 

tests/unit/test_supervise_cli.py

@@ -12,7 +12,10 @@ from pathlib import Path
 from unittest.mock import patch
 
 from bot_bottle import supervise
+from bot_bottle import supervise_types as sv_types
+from bot_bottle.audit_store import AuditStore
 from bot_bottle.cli import supervise as supervise_cli
+from bot_bottle.queue_store import QueueStore
 from bot_bottle.supervise import (
     Proposal,
     STATUS_APPROVED,
@@ -52,13 +55,22 @@ class _FakeHomeMixin:
 
     def _setup_fake_home(self):
         self._tmp = tempfile.TemporaryDirectory(prefix="supervise-test.")
-        original = supervise.bot_bottle_root
+        original_sv = supervise.bot_bottle_root
+        original_svt = sv_types.bot_bottle_root
 
         def fake_root() -> Path:
             return Path(self._tmp.name) / ".bot-bottle"
 
         supervise.bot_bottle_root = fake_root  # type: ignore[assignment]
-        self._restore_home = lambda: setattr(supervise, "bot_bottle_root", original)
+        sv_types.bot_bottle_root = fake_root  # type: ignore[assignment]
+
+        def restore() -> None:
+            supervise.bot_bottle_root = original_sv  # type: ignore[assignment]
+            sv_types.bot_bottle_root = original_svt  # type: ignore[assignment]
+
+        self._restore_home = restore
+        QueueStore("").migrate()
+        AuditStore().migrate()
 
     def _teardown_fake_home(self):
         self._restore_home()
@@ -77,9 +89,7 @@ class TestDiscoverPending(_FakeHomeMixin, unittest.TestCase):
 
     def test_walks_all_slug_subdirs(self):
         for slug in ("dev", "api"):
-            qdir = supervise.queue_dir_for_slug(slug)
-            qdir.mkdir(parents=True)
-            supervise.write_proposal(qdir, _proposal(slug=slug))
+            supervise.write_proposal(_proposal(slug=slug))
         pending = supervise_cli.discover_pending()
         self.assertEqual({"dev", "api"}, {qp.proposal.bottle_slug for qp in pending})
 
@@ -97,18 +107,14 @@ class TestDiscoverPending(_FakeHomeMixin, unittest.TestCase):
             now=datetime(2026, 5, 25, 14, 0, 0, tzinfo=timezone.utc),
         )
         for p in (late, early):
-            qdir = supervise.queue_dir_for_slug(p.bottle_slug)
-            qdir.mkdir(parents=True, exist_ok=True)
-            supervise.write_proposal(qdir, p)
+            supervise.write_proposal(p)
         pending = supervise_cli.discover_pending()
         self.assertEqual([early.id, late.id], [qp.proposal.id for qp in pending])
 
     def test_excludes_already_responded(self):
         p = _proposal()
-        qdir = supervise.queue_dir_for_slug("dev")
-        qdir.mkdir(parents=True)
-        supervise.write_proposal(qdir, p)
-        supervise.write_response(qdir, supervise.Response(
+        supervise.write_proposal(p)
+        supervise.write_response("dev", supervise.Response(
             proposal_id=p.id, status=STATUS_APPROVED, notes="",
         ))
         self.assertEqual([], supervise_cli.discover_pending())
@@ -123,10 +129,8 @@ class TestApproveReject(_FakeHomeMixin, unittest.TestCase):
 
     def _enqueue(self, tool: str = TOOL_EGRESS_ALLOW):
         p = _proposal(tool=tool)
-        qdir = supervise.queue_dir_for_slug("dev")
-        qdir.mkdir(parents=True, exist_ok=True)
-        supervise.write_proposal(qdir, p)
-        return supervise_cli.QueuedProposal(proposal=p, queue_dir=qdir)
+        supervise.write_proposal(p)
+        return supervise_cli.QueuedProposal(proposal=p)
 
     def test_approve_writes_response(self):
         qp = self._enqueue()
@@ -135,7 +139,7 @@ class TestApproveReject(_FakeHomeMixin, unittest.TestCase):
             return_value=("routes: []\n", "routes:\n  - host: example.com\n"),
         ):
             supervise_cli.approve(qp)
-        resp = read_response(qp.queue_dir, qp.proposal.id)
+        resp = read_response(qp.proposal.bottle_slug, qp.proposal.id)
         self.assertEqual(STATUS_APPROVED, resp.status)
         self.assertIsNone(resp.final_file)
 
@@ -150,7 +154,7 @@ class TestApproveReject(_FakeHomeMixin, unittest.TestCase):
                 final_file="routes:\n  - host: edited.example.com\n",
                 notes="tweaked",
             )
-        resp = read_response(qp.queue_dir, qp.proposal.id)
+        resp = read_response(qp.proposal.bottle_slug, qp.proposal.id)
         self.assertEqual(STATUS_MODIFIED, resp.status)
         self.assertEqual("routes:\n  - host: edited.example.com\n", resp.final_file)
         self.assertEqual("tweaked", resp.notes)
@@ -158,7 +162,7 @@ class TestApproveReject(_FakeHomeMixin, unittest.TestCase):
     def test_reject_writes_rejection(self):
         qp = self._enqueue()
         supervise_cli.reject(qp, reason="nope")
-        resp = read_response(qp.queue_dir, qp.proposal.id)
+        resp = read_response(qp.proposal.bottle_slug, qp.proposal.id)
         self.assertEqual(STATUS_REJECTED, resp.status)
         self.assertEqual("nope", resp.notes)
 
@@ -181,36 +185,33 @@ class TestApproveReject(_FakeHomeMixin, unittest.TestCase):
     def test_approve_gitleaks_allow_leaves_response_for_gate(self):
         qp = self._enqueue(tool=TOOL_GITLEAKS_ALLOW)
         supervise_cli.approve(qp, notes="dummy fixture")
-        # Gate polls the queue dir for the response; TUI must not archive it.
-        resp = read_response(qp.queue_dir, qp.proposal.id)
+        # Gate polls the DB for the response; TUI must not archive it.
+        resp = read_response(qp.proposal.bottle_slug, qp.proposal.id)
         self.assertEqual(STATUS_APPROVED, resp.status)
         self.assertEqual("dummy fixture", resp.notes)
-        self.assertFalse((qp.queue_dir / "processed").exists())
 
     def test_tui_gitleaks_allow_requires_reason(self):
         qp = self._enqueue(tool=TOOL_GITLEAKS_ALLOW)
         with patch.object(supervise_cli, "_prompt", return_value=""):
             status = supervise_cli._approve_from_tui(None, qp)  # type: ignore[arg-type]
         self.assertEqual("approve aborted (empty reason)", status)
-        self.assertFalse((qp.queue_dir / "processed").exists())
 
     def test_tui_gitleaks_allow_writes_reason(self):
         qp = self._enqueue(tool=TOOL_GITLEAKS_ALLOW)
         with patch.object(supervise_cli, "_prompt", return_value="test fixture"):
             status = supervise_cli._approve_from_tui(None, qp)  # type: ignore[arg-type]
         self.assertIn("approved gitleaks-allow", status)
-        resp = read_response(qp.queue_dir, qp.proposal.id)
+        resp = read_response(qp.proposal.bottle_slug, qp.proposal.id)
         self.assertEqual("test fixture", resp.notes)
 
     def test_approve_token_allow_leaves_response_for_egress(self):
         qp = self._enqueue(tool=TOOL_EGRESS_TOKEN_ALLOW)
         supervise_cli.approve(qp, notes="false positive")
-        # The egress addon polls the queue dir for the response; the TUI must
+        # The egress addon polls the DB for the response; the TUI must
         # not archive it (the addon archives after reading).
-        resp = read_response(qp.queue_dir, qp.proposal.id)
+        resp = read_response(qp.proposal.bottle_slug, qp.proposal.id)
         self.assertEqual(STATUS_APPROVED, resp.status)
         self.assertEqual("false positive", resp.notes)
-        self.assertFalse((qp.queue_dir / "processed").exists())
 
     def test_token_allow_writes_no_audit_log(self):
         qp = self._enqueue(tool=TOOL_EGRESS_TOKEN_ALLOW)
@@ -222,14 +223,13 @@ class TestApproveReject(_FakeHomeMixin, unittest.TestCase):
         with patch.object(supervise_cli, "_prompt", return_value=""):
             status = supervise_cli._approve_from_tui(None, qp)  # type: ignore[arg-type]
         self.assertEqual("approve aborted (empty reason)", status)
-        self.assertFalse((qp.queue_dir / "processed").exists())
 
     def test_tui_token_allow_writes_reason(self):
         qp = self._enqueue(tool=TOOL_EGRESS_TOKEN_ALLOW)
         with patch.object(supervise_cli, "_prompt", return_value="legit"):
             status = supervise_cli._approve_from_tui(None, qp)  # type: ignore[arg-type]
         self.assertIn("approved egress-token-allow", status)
-        resp = read_response(qp.queue_dir, qp.proposal.id)
+        resp = read_response(qp.proposal.bottle_slug, qp.proposal.id)
         self.assertEqual("legit", resp.notes)
 
     def test_suffix_for_token_allow_is_txt(self):

tests/unit/test_supervise_edge.py

@@ -4,7 +4,6 @@ fallback paths."""
 
 from __future__ import annotations
 
-import os
 import tempfile
 import time
 import unittest
@@ -12,14 +11,19 @@ from pathlib import Path
 from unittest.mock import patch
 
 from bot_bottle import supervise
+from bot_bottle.audit_store import AuditStore
+from bot_bottle.queue_store import QueueStore
 from bot_bottle.supervise import (
+    AuditEntry,
     Proposal,
+    STATUS_APPROVED,
     TOOL_EGRESS_ALLOW,
     list_pending_proposals,
     read_audit_entries,
     read_proposal,
     read_response,
     wait_for_response,
+    write_audit_entry,
 )
 
 
@@ -37,58 +41,59 @@ class TestPathHelpers(unittest.TestCase):
     def test_bot_bottle_root(self) -> None:
         self.assertTrue(str(supervise.bot_bottle_root()).endswith(".bot-bottle"))
 
-    def test_queue_dir_for_slug(self) -> None:
-        self.assertIn("slug", str(supervise.queue_dir_for_slug("slug")))
-
-    def test_id_from_non_proposal_filename(self) -> None:
-        self.assertIsNone(supervise._id_from_proposal_filename(Path("x.response.json")))
-
 
 class TestReadMalformed(unittest.TestCase):
-    def test_read_proposal_non_dict(self) -> None:
+    def test_read_proposal_missing_row(self) -> None:
         with tempfile.TemporaryDirectory() as d:
-            (Path(d) / "p.proposal.json").write_text("[]")
-            with self.assertRaises(ValueError):
-                read_proposal(Path(d), "p")
+            with patch.dict("os.environ", {"HOME": d}):
+                QueueStore("slug").migrate()
+                with self.assertRaises(FileNotFoundError):
+                    read_proposal("slug", "p")
 
-    def test_read_response_non_dict(self) -> None:
+    def test_read_response_missing_row(self) -> None:
         with tempfile.TemporaryDirectory() as d:
-            (Path(d) / "p.response.json").write_text("[]")
-            with self.assertRaises(ValueError):
-                read_response(Path(d), "p")
+            with patch.dict("os.environ", {"HOME": d}):
+                QueueStore("slug").migrate()
+                with self.assertRaises(FileNotFoundError):
+                    read_response("slug", "p")
 
-    def test_list_pending_skips_malformed(self) -> None:
+    def test_list_pending_reads_db_only(self) -> None:
         with tempfile.TemporaryDirectory() as d:
-            qd = Path(d)
-            (qd / "bad.proposal.json").write_text("{ not json")
-            (qd / "arr.proposal.json").write_text("[]")
-            (qd / "incomplete.proposal.json").write_text("{}")  # from_dict raises
-            supervise.write_proposal(qd, _proposal())  # one valid
-            pending = list_pending_proposals(qd)
+            with patch.dict("os.environ", {"HOME": d}):
+                QueueStore("slug").migrate()
+                supervise.write_proposal(_proposal())
+                pending = list_pending_proposals("slug")
             self.assertEqual(1, len(pending))
             self.assertEqual("slug", pending[0].bottle_slug)
 
     def test_list_pending_skips_when_response_present(self) -> None:
         with tempfile.TemporaryDirectory() as d:
-            qd = Path(d)
-            p = _proposal()
-            supervise.write_proposal(qd, p)
-            (qd / f"{p.id}.response.json").write_text("{}")  # response exists -> skipped
-            self.assertEqual([], list_pending_proposals(qd))
+            with patch.dict("os.environ", {"HOME": d}):
+                QueueStore("slug").migrate()
+                p = _proposal()
+                supervise.write_proposal(p)
+                supervise.write_response("slug", supervise.Response(
+                    proposal_id=p.id,
+                    status=STATUS_APPROVED,
+                    notes="",
+                ))
+                self.assertEqual([], list_pending_proposals("slug"))
 
 
 class TestWaitForResponse(unittest.TestCase):
-    def test_malformed_response_then_timeout(self) -> None:
+    def test_missing_response_times_out(self) -> None:
         with tempfile.TemporaryDirectory() as d:
-            (Path(d) / "p.response.json").write_text("{ not json")
-            with self.assertRaises(TimeoutError):
-                wait_for_response(Path(d), "p", deadline=time.monotonic())
+            with patch.dict("os.environ", {"HOME": d}):
+                QueueStore("slug").migrate()
+                with self.assertRaises(TimeoutError):
+                    wait_for_response("slug", "p", deadline=time.monotonic())
 
-    def test_incomplete_response_then_timeout(self) -> None:
+    def test_empty_db_response_does_not_count(self) -> None:
         with tempfile.TemporaryDirectory() as d:
-            (Path(d) / "p.response.json").write_text("{}")  # dict but from_dict raises
-            with self.assertRaises(TimeoutError):
-                wait_for_response(Path(d), "p", deadline=time.monotonic())
+            with patch.dict("os.environ", {"HOME": d}):
+                QueueStore("slug").migrate()
+                with self.assertRaises(TimeoutError):
+                    wait_for_response("slug", "p", deadline=time.monotonic())
 
 
 class TestReadAuditEntries(unittest.TestCase):
@@ -97,35 +102,102 @@ class TestReadAuditEntries(unittest.TestCase):
                 patch.dict("os.environ", {"HOME": home}):
             self.assertEqual([], read_audit_entries("egress", "nope"))
 
-    def test_skips_malformed_lines(self) -> None:
+    def test_reads_entries_from_db(self) -> None:
         with tempfile.TemporaryDirectory() as home, \
                 patch.dict("os.environ", {"HOME": home}):
-            path = supervise.audit_log_path("egress", "slug")
-            path.parent.mkdir(parents=True, exist_ok=True)
-            valid = (
-                '{"timestamp": "t", "bottle_slug": "slug", "component": "egress",'
-                ' "operator_action": "approve", "operator_notes": "",'
-                ' "justification": "", "diff": ""}'
-            )
-            path.write_text(
-                "\n"               # blank line skipped
-                "{ not json\n"     # JSONDecodeError skipped
-                "[]\n"             # not a dict skipped
-                "{}\n"             # missing fields -> ValueError skipped
-                + valid + "\n"
-            )
+            AuditStore().migrate()
+            write_audit_entry(AuditEntry(
+                timestamp="t",
+                bottle_slug="slug",
+                component="egress",
+                operator_action="approve",
+                operator_notes="",
+                justification="",
+                diff="",
+            ))
+            write_audit_entry(AuditEntry(
+                timestamp="t",
+                bottle_slug="other",
+                component="egress",
+                operator_action="reject",
+                operator_notes="",
+                justification="",
+                diff="",
+            ))
             entries = read_audit_entries("egress", "slug")
             self.assertEqual(1, len(entries))
             self.assertEqual("approve", entries[0].operator_action)
 
+    def test_legacy_audit_log_file_does_not_count(self) -> None:
+        with tempfile.TemporaryDirectory() as home, \
+                patch.dict("os.environ", {"HOME": home}):
+            path = supervise.audit_log_path("egress", "slug")
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(
+                '{"timestamp": "t", "bottle_slug": "slug", "component": "egress",'
+                ' "operator_action": "approve", "operator_notes": "",'
+                ' "justification": "", "diff": ""}\n'
+            )
+            entries = read_audit_entries("egress", "slug")
+            self.assertEqual([], entries)
 
-class TestFlockFallback(unittest.TestCase):
-    def test_flock_on_closed_fd_is_swallowed(self) -> None:
-        # flock on a closed fd raises OSError(EBADF), which the helpers swallow.
-        fd = os.open(os.devnull, os.O_RDONLY)
-        os.close(fd)
-        supervise._try_flock(fd)
-        supervise._try_funlock(fd)
+
+class TestStoreGuardBranches(unittest.TestCase):
+    """Direct QueueStore / AuditStore construction and early-return guard branches."""
+
+    def test_queue_store_explicit_db_path(self):
+        with tempfile.TemporaryDirectory() as d:
+            db = Path(d) / "q.db"
+            store = QueueStore("key", db_path=db)
+            store.migrate()
+            self.assertTrue(db.is_file())
+            self.assertEqual(db, store.db_path)
+
+    def test_queue_store_missing_db_list_pending_returns_empty(self):
+        with tempfile.TemporaryDirectory() as d:
+            db = Path(d) / "q.db"
+            store = QueueStore("key", db_path=db)
+            store.migrate()
+            db.unlink()
+            self.assertEqual([], store.list_pending_proposals())
+
+    def test_queue_store_missing_db_list_all_returns_empty(self):
+        with tempfile.TemporaryDirectory() as d:
+            db = Path(d) / "q.db"
+            store = QueueStore("key", db_path=db)
+            store.migrate()
+            db.unlink()
+            self.assertEqual([], store.list_all_pending_proposals())
+
+    def test_queue_store_missing_db_archive_is_noop(self):
+        with tempfile.TemporaryDirectory() as d:
+            db = Path(d) / "q.db"
+            store = QueueStore("key", db_path=db)
+            store.migrate()
+            db.unlink()
+            store.archive_proposal("anything")  # must not raise
+
+    def test_queue_store_chmod_oserror_is_swallowed(self):
+        with tempfile.TemporaryDirectory() as d:
+            db = Path(d) / "q.db"
+            store = QueueStore("key", db_path=db)
+            with patch("pathlib.Path.chmod", side_effect=OSError("ro")):
+                store.migrate()  # must not raise
+
+    def test_audit_store_missing_db_read_returns_empty(self):
+        with tempfile.TemporaryDirectory() as d:
+            db = Path(d) / "a.db"
+            store = AuditStore(db_path=db)
+            store.migrate()
+            db.unlink()
+            self.assertEqual([], store.read_audit_entries("egress", "slug"))
+
+    def test_audit_store_chmod_oserror_is_swallowed(self):
+        with tempfile.TemporaryDirectory() as d:
+            db = Path(d) / "a.db"
+            store = AuditStore(db_path=db)
+            with patch("pathlib.Path.chmod", side_effect=OSError("ro")):
+                store.migrate()  # must not raise
 
 
 if __name__ == "__main__":

tests/unit/test_supervise_server.py

@@ -17,8 +17,12 @@ from unittest.mock import patch
 # bare name `supervise`.
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent / "bot_bottle"))
 import supervise as _sv  # noqa: E402  # type: ignore
+import queue_store as _qs  # noqa: E402  # type: ignore
+import audit_store as _as  # noqa: E402  # type: ignore
+import supervise_types as svt_flat  # noqa: E402  # type: ignore
 
 from bot_bottle import supervise_server  # noqa: E402
+from bot_bottle import supervise_types as svt_pkg  # noqa: E402
 from bot_bottle.supervise_server import (
     ERR_INTERNAL,
     ERR_INVALID_PARAMS,
@@ -112,7 +116,7 @@ class TestRpcErrorTaxonomy(unittest.TestCase):
             validate_proposed_file(_sv.TOOL_EGRESS_ALLOW, "routes: nope\n")
 
     def test_unknown_tool_in_tools_call_is_client_error(self):
-        config = ServerConfig(bottle_slug="dev", queue_dir=Path("/unused"))
+        config = ServerConfig(bottle_slug="dev")
         with self.assertRaises(_RpcClientError) as cm:
             handle_tools_call({"name": "no-such-tool", "arguments": {}}, config)
         self.assertEqual(ERR_INVALID_PARAMS, cm.exception.code)
@@ -122,9 +126,9 @@ class TestRpcInternalErrorOnIoFailure(unittest.TestCase):
     def test_write_proposal_os_error_raises_internal(self):
         config = ServerConfig(
             bottle_slug="dev",
-            queue_dir=Path("/dev/null/cannot-exist"),
         )
-        with self.assertRaises(_RpcInternalError) as cm:
+        with patch.object(_sv, "write_proposal", side_effect=OSError("disk full")), \
+                self.assertRaises(_RpcInternalError) as cm:
             handle_tools_call(
                 {
                     "name": _sv.TOOL_EGRESS_ALLOW,
@@ -265,21 +269,43 @@ class TestHandleToolsList(unittest.TestCase):
 class TestHandleToolsCall(unittest.TestCase):
     def setUp(self):
         self._tmp = tempfile.TemporaryDirectory(prefix="supervise-server-test.")
-        self.queue_dir = Path(self._tmp.name)
-        self.config = ServerConfig(bottle_slug="dev", queue_dir=self.queue_dir)
+        self._home_patch = self._patch_home(Path(self._tmp.name))
+        self.config = ServerConfig(bottle_slug="dev")
+        _qs.QueueStore("dev").migrate()
+        _as.AuditStore().migrate()
 
     def tearDown(self):
+        self._home_patch()
         self._tmp.cleanup()
 
+    def _patch_home(self, fake_home: Path):
+        original_sv = _sv.bot_bottle_root
+        original_flat = svt_flat.bot_bottle_root
+        original_pkg = svt_pkg.bot_bottle_root
+
+        def fake_root() -> Path:
+            return fake_home / ".bot-bottle"
+
+        _sv.bot_bottle_root = fake_root  # type: ignore[assignment]
+        svt_flat.bot_bottle_root = fake_root  # type: ignore[assignment]
+        svt_pkg.bot_bottle_root = fake_root  # type: ignore[assignment]
+
+        def restore() -> None:
+            _sv.bot_bottle_root = original_sv  # type: ignore[assignment]
+            svt_flat.bot_bottle_root = original_flat  # type: ignore[assignment]
+            svt_pkg.bot_bottle_root = original_pkg  # type: ignore[assignment]
+
+        return restore
+
     def _respond_when_proposal_appears(self, status: str, notes: str = "") -> threading.Thread:
         """Background thread: poll the queue for a fresh proposal, write a
         matching response. Returns the thread so the test can join it."""
         def runner():
             for _ in range(200):
-                pending = _sv.list_pending_proposals(self.queue_dir)
+                pending = _sv.list_pending_proposals("dev")
                 if pending:
                     p = pending[0]
-                    _sv.write_response(self.queue_dir, _sv.Response(
+                    _sv.write_response("dev", _sv.Response(
                         proposal_id=p.id, status=status, notes=notes,
                     ))
                     return
@@ -412,15 +438,11 @@ class TestHandleToolsCall(unittest.TestCase):
         finally:
             responder.join()
         # No pending proposals left after archive.
-        self.assertEqual([], _sv.list_pending_proposals(self.queue_dir))
-        # Both files moved to processed/.
-        processed = list((self.queue_dir / "processed").glob("*.json"))
-        self.assertEqual(2, len(processed))
+        self.assertEqual([], _sv.list_pending_proposals("dev"))
 
     def test_pending_response_times_out_without_archive(self):
         config = ServerConfig(
             bottle_slug="dev",
-            queue_dir=self.queue_dir,
             response_timeout_seconds=0.05,
         )
         result = handle_tools_call(
@@ -438,8 +460,7 @@ class TestHandleToolsCall(unittest.TestCase):
         text = result["content"][0]["text"]  # type: ignore[index]
         self.assertIn("status: pending", text)
         self.assertIn("proposal remains queued", text)
-        self.assertEqual(1, len(_sv.list_pending_proposals(self.queue_dir)))
-        self.assertFalse((self.queue_dir / "processed").exists())
+        self.assertEqual(1, len(_sv.list_pending_proposals("dev")))
 
 
 class TestHandleListEgressRoutes(unittest.TestCase):
@@ -461,7 +482,7 @@ class TestHandleListEgressRoutes(unittest.TestCase):
         with patch.object(supervise_server.urllib.request, "build_opener", return_value=_Opener()):
             result = handle_list_egress_routes(
                 {},
-                ServerConfig(bottle_slug="dev", queue_dir=Path("/unused")),
+                ServerConfig(bottle_slug="dev"),
             )
 
         self.assertFalse(result["isError"])  # type: ignore[index]
@@ -476,7 +497,7 @@ class TestHandleListEgressRoutes(unittest.TestCase):
         with patch.object(supervise_server.urllib.request, "build_opener", return_value=_Opener()):
             result = handle_list_egress_routes(
                 {},
-                ServerConfig(bottle_slug="dev", queue_dir=Path("/unused")),
+                ServerConfig(bottle_slug="dev"),
             )
 
         self.assertTrue(result["isError"])  # type: ignore[index]
@@ -544,7 +565,6 @@ class TestHttpEndToEnd(unittest.TestCase):
 
     def setUp(self):
         self._tmp = tempfile.TemporaryDirectory(prefix="supervise-http-test.")
-        self.queue_dir = Path(self._tmp.name)
         # Pick a random port by binding to :0 first.
         import socket
         s = socket.socket()
@@ -552,7 +572,7 @@ class TestHttpEndToEnd(unittest.TestCase):
         self.port = s.getsockname()[1]
         s.close()
         self.server = MCPServer(("127.0.0.1", self.port), MCPHandler)
-        self.server.config = ServerConfig(bottle_slug="dev", queue_dir=self.queue_dir)
+        self.server.config = ServerConfig(bottle_slug="dev")
         self.thread = threading.Thread(
             target=self.server.serve_forever, daemon=True,
         )