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

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

@@ -45,10 +45,6 @@ PROVIDER_TEMPLATES = frozenset({PROVIDER_CLAUDE, PROVIDER_CODEX, PROVIDER_PI})
 # forward_host_credentials is enabled. Pipelock must pass these through
 # (no TLS MITM) or its header DLP blocks the injected JWT.
 CODEX_HOST_CREDENTIAL_HOSTS = ("api.openai.com", "chatgpt.com")
-
-# Host that egress injects the host Claude bearer on when Claude
-# forward_host_credentials is enabled.
-CLAUDE_HOST_CREDENTIAL_HOSTS = ("api.anthropic.com",)
 PromptMode = Literal[
     "append_file",
     "read_prompt_file",

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

@@ -46,7 +46,7 @@ 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,

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,
@@ -33,7 +33,7 @@ from ...git_gate import (
     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 (
@@ -379,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)
@@ -405,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 (
@@ -46,7 +46,7 @@ from ...git_gate import (
     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,
@@ -369,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

@@ -31,7 +31,7 @@ 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,
@@ -144,11 +144,12 @@ 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 -----------------------------------------------------
@@ -203,13 +204,14 @@ def _start_headless(
         color=args.color or "",
         bottle_names=bottle_names,
     )
-    return _launch_bottle(
+    _, 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:
@@ -497,11 +499,16 @@ def _launch_bottle(
     backend_name: str | None = None,
     assume_yes: bool = False,
     headless_prompt_text: str = "",
-) -> int:
+) -> 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.
 
+    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.
 
@@ -510,6 +517,7 @@ def _launch_bottle(
     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,
@@ -520,7 +528,7 @@ def _launch_bottle(
             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:
@@ -547,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

@@ -23,9 +23,8 @@ from ...agent_provider import (
     provider_startup_args,
 )
 from ...backend.docker import util as docker_mod
-from ...egress import CLAUDE_HOST_CREDENTIAL_TOKEN_REF, EgressRoute
+from ...egress import EgressRoute
 from ...log import die, info, warn
-from .claude_auth import claude_host_access_token
 
 
 if TYPE_CHECKING:
@@ -116,6 +115,7 @@ class ClaudeAgentProvider(AgentProvider):
         color: str = "",
         provider_settings: dict[str, object] | None = None,
     ) -> AgentProvisionPlan:
+        del forward_host_credentials, host_env
         resolved_guest_env = dict(guest_env or {})
         startup_args = provider_startup_args(provider_settings)
         guest_home = self.guest_home
@@ -177,24 +177,13 @@ class ClaudeAgentProvider(AgentProvider):
                 claude_settings,
                 f"{guest_home}/.claude/settings.json",
             ))
-        provisioned_env: dict[str, str] = {}
-        if forward_host_credentials:
-            _host_env = host_env or dict(os.environ)
-            provisioned_env[CLAUDE_HOST_CREDENTIAL_TOKEN_REF] = (
-                claude_host_access_token(_host_env)
-            )
-
-        cred_token_ref = (
-            CLAUDE_HOST_CREDENTIAL_TOKEN_REF if forward_host_credentials
-            else auth_token
-        )
         egress_routes = (EgressRoute(
             host="api.anthropic.com",
-            auth_scheme="Bearer" if (auth_token or forward_host_credentials) else "",
-            token_ref=cred_token_ref,
+            auth_scheme="Bearer" if auth_token else "",
+            token_ref=auth_token,
         ),)
         hidden_env_names: frozenset[str] = frozenset()
-        if auth_token or forward_host_credentials:
+        if auth_token:
             env_vars["CLAUDE_CODE_OAUTH_TOKEN"] = "egress-placeholder"
             hidden_env_names = frozenset({"CLAUDE_CODE_OAUTH_TOKEN"})
 
@@ -216,7 +205,6 @@ class ClaudeAgentProvider(AgentProvider):
             files=tuple(files),
             egress_routes=egress_routes,
             hidden_env_names=hidden_env_names,
-            provisioned_env=provisioned_env,
         )
 
     def provision_skills(self, plan: "BottlePlan", bottle: "Bottle") -> None:

bot_bottle/contrib/claude/claude_auth.py

@@ -1,114 +0,0 @@
-"""Host Claude auth helpers.
-
-Reads the host's Claude Code credentials and returns only the access
-token needed by egress. Does not expose refresh tokens or raw payloads.
-
-Credential storage by platform:
-  Linux  — ~/.claude/.credentials.json
-  macOS  — macOS Keychain, service "Claude Code-credentials"
-            (file path is tried first; Keychain is the fallback)
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import subprocess
-import sys
-from datetime import datetime, timezone
-from pathlib import Path
-
-from ...log import die
-
-
-_KEYCHAIN_SERVICE = "Claude Code-credentials"
-
-
-def claude_auth_path(host_env: dict[str, str] | None = None) -> Path:
-    env = os.environ if host_env is None else host_env
-    home = env.get("HOME")
-    if home:
-        return Path(home) / ".claude" / ".credentials.json"
-    return Path.home() / ".claude" / ".credentials.json"
-
-
-def _read_keychain() -> dict[str, object] | None:
-    """Try the macOS Keychain. Returns parsed JSON dict or None."""
-    if sys.platform != "darwin":
-        return None
-    try:
-        result = subprocess.run(
-            ["security", "find-generic-password", "-s", _KEYCHAIN_SERVICE, "-w"],
-            capture_output=True,
-            text=True,
-            timeout=10,
-        )
-    except (FileNotFoundError, subprocess.TimeoutExpired):
-        return None
-    if result.returncode != 0 or not result.stdout.strip():
-        return None
-    try:
-        raw = json.loads(result.stdout.strip())
-    except json.JSONDecodeError:
-        return None
-    return raw if isinstance(raw, dict) else None
-
-
-def claude_host_access_token(
-    host_env: dict[str, str] | None = None,
-    *,
-    now: datetime | None = None,
-) -> str:
-    path = claude_auth_path(host_env)
-    raw: dict[str, object] | None = None
-
-    if path.is_file():
-        try:
-            raw = json.loads(path.read_text())
-        except (OSError, json.JSONDecodeError) as e:
-            die(f"claude host credentials: could not read valid JSON at {path}: {e}")
-        if not isinstance(raw, dict):
-            die(f"claude host credentials: {path} must contain a JSON object")
-    else:
-        raw = _read_keychain()
-        if raw is None:
-            die(
-                f"claude host credentials: auth file missing at {path} and "
-                f"macOS Keychain lookup for '{_KEYCHAIN_SERVICE}' failed. "
-                "Run `claude login` on the host or disable "
-                "agent_provider.forward_host_credentials."
-            )
-
-    oauth = raw.get("claudeAiOauth")
-    if not isinstance(oauth, dict):
-        die(
-            "claude host credentials: claudeAiOauth is missing from credentials. "
-            "Run `claude login` on the host or disable "
-            "agent_provider.forward_host_credentials."
-        )
-
-    access_token = oauth.get("accessToken")
-    if not isinstance(access_token, str) or not access_token:
-        die(
-            "claude host credentials: claudeAiOauth.accessToken is missing or empty. "
-            "Run `claude login` on the host and restart the bottle."
-        )
-
-    # expiresAt is in milliseconds
-    expires_at = oauth.get("expiresAt")
-    if isinstance(expires_at, (int, float)):
-        check_now = now or datetime.now(timezone.utc)
-        exp_dt = datetime.fromtimestamp(float(expires_at) / 1000.0, timezone.utc)
-        if exp_dt <= check_now:
-            die(
-                "claude host credentials: host Claude access token is expired. "
-                "Run `claude login` on the host and restart the bottle."
-            )
-
-    return access_token
-
-
-__all__ = [
-    "claude_auth_path",
-    "claude_host_access_token",
-]

bot_bottle/contrib/forge/base.py

@@ -1,52 +1,165 @@
-"""Scoped forge wrapper: read-anywhere / write-scoped access control.
+"""Forge abstraction (PRD forge-native-integration, chunk 3).
 
-`ScopedForge` wraps any forge object and restricts write operations to
-the set of issue/PR numbers the agent is explicitly assigned to. Read
-operations always pass through unconditionally.
+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
 
-from typing import Any
+import abc
+from collections.abc import Iterable
+from dataclasses import dataclass
 
 
-class ScopedForge:
-    """Delegates all forge calls to an inner forge, raising `PermissionError`
-    on write calls for numbers outside the assigned scope."""
+@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,
-        forge: Any,
+        inner: Forge,
         *,
         assigned_issue: int,
-        assigned_prs: list[int],
+        assigned_prs: Iterable[int] = (),
     ) -> None:
-        self._forge = forge
-        self._allowed_writes: frozenset[int] = frozenset({assigned_issue, *assigned_prs})
+        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._allowed_writes:
-            raise PermissionError(
-                f"write to #{number} is outside the assigned scope "
-                f"(allowed: {sorted(self._allowed_writes)})"
+        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._forge.is_org_member(org, username)
+        return self._inner.is_org_member(org, username)
 
-    def read_issue(self, number: int) -> dict[str, Any]:
-        return self._forge.read_issue(number)
+    def get_pr_for_issue(self, number: int) -> int | None:
+        return self._inner.get_pr_for_issue(number)
 
-    def read_pr(self, number: int) -> dict[str, Any]:
-        return self._forge.read_pr(number)
+    def is_pr_open(self, number: int) -> bool:
+        return self._inner.is_pr_open(number)
 
-    def read_comments(self, number: int) -> list[dict[str, Any]]:
-        return self._forge.read_comments(number)
+    # --- write-scoped: check then delegate --------------------------------
 
     def post_comment(self, number: int, body: str) -> None:
         self._check_write(number)
-        self._forge.post_comment(number, body)
+        self._inner.post_comment(number, body)
 
     def update_description(self, number: int, body: str) -> None:
         self._check_write(number)
-        self._forge.update_description(number, body)
+        self._inner.update_description(number, body)

bot_bottle/contrib/gitea/client.py

@@ -1,12 +1,16 @@
-"""Gitea API client and forge adapter (PRD prd-new: fold orchestrator).
+"""Gitea HTTP client + `GiteaForge` (PRD forge-native-integration, chunk 3).
 
-`GiteaClient` is a thin HTTP wrapper (stdlib `urllib.request` only — no
-new runtime dependencies). `GiteaForge` composes a client and exposes
-the forge protocol used by the orchestrator's sidecar and lifecycle.
+`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.
 
-Required Gitea token scopes:
-- Repository: Read & Write (issues, comments, PR descriptions)
-- Organization: Read (org membership check)
+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
@@ -16,97 +20,155 @@ import urllib.error
 import urllib.request
 from typing import Any
 
-_TIMEOUT_SECS = 30
+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:
-    """Low-level HTTP wrapper for the Gitea REST API."""
+    """Thin authenticated HTTP client for one repo's Gitea API.
 
-    def __init__(
-        self, *, api_url: str, owner: str, repo: str, token: str
-    ) -> None:
-        self._base = api_url.rstrip("/")
+    `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._headers = {
-            "Authorization": f"token {token}",
-            "Content-Type": "application/json",
-            "Accept": "application/json",
-        }
+        self._token = token
+
+    # --- low-level request -------------------------------------------------
 
     def _request(
-        self,
-        method: str,
-        path: str,
-        body: dict[str, Any] | None = None,
-    ) -> Any:
-        url = f"{self._base}{path}"
+        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
-        req = urllib.request.Request(
-            url, data=data, headers=self._headers, method=method
-        )
-        with urllib.request.urlopen(req, timeout=_TIMEOUT_SECS) as resp:
+        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()
-            return json.loads(raw) if raw else None
+            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:
-        url = f"{self._base}/orgs/{org}/members/{username}"
-        req = urllib.request.Request(url, headers=self._headers, method="GET")
+        """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:
-            urllib.request.urlopen(req, timeout=_TIMEOUT_SECS).close()
-            return True
-        except urllib.error.HTTPError:
-            return False
+            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]:
-        return self._request("GET", f"/repos/{self._owner}/{self._repo}/issues/{number}")
+        _status, body = self._request("GET", self._repo_path(f"/issues/{number}"))
+        return body or {}
 
-    def get_pull(self, number: int) -> dict[str, Any]:
-        return self._request("GET", f"/repos/{self._owner}/{self._repo}/pulls/{number}")
+    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 list_comments(self, number: int) -> list[dict[str, Any]]:
-        return self._request("GET", f"/repos/{self._owner}/{self._repo}/issues/{number}/comments")
-
-    def create_comment(self, number: int, body: str) -> None:
+    def post_comment(self, number: int, body: str) -> None:
         self._request(
             "POST",
-            f"/repos/{self._owner}/{self._repo}/issues/{number}/comments",
-            {"body": body},
+            self._repo_path(f"/issues/{number}/comments"),
+            body={"body": body},
         )
 
-    def update_issue(self, number: int, body: str) -> None:
+    def patch_issue_body(self, number: int, body: str) -> None:
         self._request(
-            "PATCH",
-            f"/repos/{self._owner}/{self._repo}/issues/{number}",
-            {"body": body},
+            "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:
-    """Adapts `GiteaClient` to the forge protocol expected by the orchestrator.
 
-    The forge protocol is duck-typed: any object with `is_org_member`,
-    `read_issue`, `read_pr`, `read_comments`, `post_comment`, and
-    `update_description` methods satisfies it.
-    """
+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 read_issue(self, number: int) -> dict[str, Any]:
-        return self._client.get_issue(number)
+    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 read_pr(self, number: int) -> dict[str, Any]:
-        return self._client.get_pull(number)
+    def is_pr_open(self, number: int) -> bool:
+        return self.read_pr(number).state == "open"
 
-    def read_comments(self, number: int) -> list[dict[str, Any]]:
-        return self._client.list_comments(number)
 
-    def post_comment(self, number: int, body: str) -> None:
-        self._client.create_comment(number, body)
-
-    def update_description(self, number: int, body: str) -> None:
-        self._client.update_issue(number, body)
+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

@@ -1,25 +1,37 @@
-"""Forge state persistence for the orchestrator (PRD prd-new: fold orchestrator).
+"""Forge state persistence (PRD forge-native-integration, chunk 2).
 
-`ForgeState` is a dataclass that mirrors the orchestrator's `RunRecord`
-field-for-field, held here so the store implementation is in bot-bottle
-where the Gitea contrib lives.
+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.
 
-`SqliteForgeStateStore` backs it with a single SQLite table. The DB path
-is optional; passing `None` uses `:memory:` (useful for tests and status
-commands that don't need persistence).
+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:
-    """Persisted state for one forge-targeted issue's bottle lifecycle."""
+    """One forge-targeted issue's bottle lifecycle record."""
 
     owner: str
     repo: str
@@ -30,95 +42,117 @@ class ForgeState:
     backend_name: str = ""
     agent_git_user: str = ""
     pr_number: int | None = None
-    status: str = ""
+    status: str = STATUS_RUNNING
     last_checkin_at: str = ""
 
 
-_DDL = """
-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 DEFAULT '[]',
-    backend_name TEXT NOT NULL DEFAULT '',
-    agent_git_user TEXT NOT NULL DEFAULT '',
-    pr_number    INTEGER,
-    status       TEXT NOT NULL DEFAULT '',
-    last_checkin_at TEXT NOT NULL DEFAULT '',
-    PRIMARY KEY (owner, repo, issue_number)
-)
-"""
+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."""
 
 
-class SqliteForgeStateStore:
-    """SQLite-backed `ForgeState` store.
+def default_db_path() -> Path:
+    return bot_bottle_root() / _DB_FILENAME
 
-    Thread-safety: a single connection is used; callers that share a
-    store across threads must serialise access externally.
-    """
 
-    def __init__(self, db_path: Path | None) -> None:
-        path = str(db_path) if db_path is not None else ":memory:"
-        self._conn = sqlite3.connect(path, check_same_thread=False)
-        self._conn.row_factory = sqlite3.Row
-        self._conn.execute(_DDL)
-        self._conn.commit()
+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:
-        self._conn.execute(
-            """
-            INSERT INTO forge_state
-                (owner, repo, issue_number, slug, agent_name,
-                 bottle_names, backend_name, agent_git_user,
-                 pr_number, status, last_checkin_at)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-            ON CONFLICT(owner, repo, issue_number) DO UPDATE SET
-                slug            = excluded.slug,
-                agent_name      = excluded.agent_name,
-                bottle_names    = excluded.bottle_names,
-                backend_name    = excluded.backend_name,
-                agent_git_user  = excluded.agent_git_user,
-                pr_number       = excluded.pr_number,
-                status          = excluded.status,
-                last_checkin_at = excluded.last_checkin_at
-            """,
-            (
-                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,
-            ),
-        )
-        self._conn.commit()
+        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:
-        row = self._conn.execute(
-            "SELECT * FROM forge_state WHERE owner=? AND repo=? AND issue_number=?",
-            (owner, repo, issue_number),
-        ).fetchone()
+        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:
-        self._conn.execute(
-            "DELETE FROM forge_state WHERE owner=? AND repo=? AND issue_number=?",
-            (owner, repo, issue_number),
-        )
-        self._conn.commit()
+        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]:
-        rows = self._conn.execute(
-            "SELECT * FROM forge_state ORDER BY owner, repo, issue_number"
-        ).fetchall()
-        return [_row_to_state(r) for r in rows]
+        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:

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

@@ -29,7 +29,6 @@ if TYPE_CHECKING:
     from .manifest import ManifestBottle
 
 CODEX_HOST_CREDENTIAL_TOKEN_REF = "BOT_BOTTLE_CODEX_HOST_ACCESS_TOKEN"
-CLAUDE_HOST_CREDENTIAL_TOKEN_REF = "BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN"
 
 EGRESS_HOSTNAME = "egress"
 
@@ -398,7 +397,6 @@ class Egress(ABC):
         )
 
 __all__ = [
-    "CLAUDE_HOST_CREDENTIAL_TOKEN_REF",
     "CODEX_HOST_CREDENTIAL_TOKEN_REF",
     "EGRESS_HOSTNAME",
     "EGRESS_ROUTES_FILENAME",

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_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/manifest_agent.py

@@ -25,9 +25,8 @@ class ManifestAgentProvider:
     header, and sets a placeholder CLAUDE_CODE_OAUTH_TOKEN in the agent
     so the Claude Code CLI starts.
 
-    `forward_host_credentials` forwards the host provider auth token into
-    the egress sidecar (Codex and Claude). For Codex this reads
-    `~/.codex/auth.json`; for Claude it reads `~/.claude.json`.
+    `forward_host_credentials` forwards the host Codex auth token into
+    the egress sidecar (Codex only).
     """
 
     template: str = "claude"
@@ -93,15 +92,10 @@ class ManifestAgentProvider:
                 f"is only supported for built-in templates "
                 f"({', '.join(sorted(PROVIDER_TEMPLATES))})"
             )
-        if forward_host_credentials and template not in {"codex", "claude"}:
+        if forward_host_credentials and template != "codex":
             raise ManifestError(
                 f"bottle '{bottle_name}' agent_provider.forward_host_credentials "
-                "is only supported for templates 'codex' and 'claude'"
-            )
-        if forward_host_credentials and auth_token:
-            raise ManifestError(
-                f"bottle '{bottle_name}' agent_provider.forward_host_credentials "
-                "and auth_token both set; use one or the other"
+                "is currently only supported for template 'codex'"
             )
         settings = _parse_provider_settings(bottle_name, template, d.get("settings"))
         return cls(

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/orchestrator/__init__.py

@@ -1,8 +0,0 @@
-"""bot-bottle-orchestrator: forge-native orchestration for bot-bottle.
-
-The package is stdlib-only. The core (events, targeting, lifecycle,
-watchdog, sidecar, webhook) depends on its collaborators — a forge, a
-state store, a bottle runner — through duck-typed interfaces, so it runs
-and tests without bot-bottle installed. `bootstrap` is the single module
-that imports `bot_bottle` and wires the concrete implementations.
-"""

bot_bottle/orchestrator/__main__.py

@@ -1,51 +0,0 @@
-"""CLI entry point: `python -m bot_bottle.orchestrator <command>`.
-
-Commands:
-  run      start the webhook server + watchdog + done-signal relay
-  status   print the tracked runs (issue -> slug, status)
-"""
-
-from __future__ import annotations
-
-import argparse
-import sys
-
-from .config import Config
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog="python -m bot_bottle.orchestrator")
-    sub = parser.add_subparsers(dest="command", required=True)
-    sub.add_parser("run", help="start the webhook server, watchdog, and relay")
-    sub.add_parser("status", help="list tracked runs")
-    args = parser.parse_args(argv)
-
-    config = Config.from_env()
-
-    if args.command == "run":
-        from . import bootstrap  # pylint: disable=import-outside-toplevel
-
-        print(
-            f"orchestrator listening on "
-            f"http://{config.webhook_host}:{config.webhook_port}/webhook",
-            file=sys.stderr,
-        )
-        bootstrap.run(config)
-        return 0
-
-    if args.command == "status":
-        from .bootstrap import (  # pylint: disable=import-outside-toplevel
-            BotBottleStateStore,
-        )
-
-        store = BotBottleStateStore(config.db_path)
-        for r in store.all():
-            pr = f"PR#{r.pr_number}" if r.pr_number else "-"
-            print(f"{r.owner}/{r.repo}#{r.issue_number}\t{r.slug}\t{r.status}\t{pr}")
-        return 0
-
-    return 2
-
-
-if __name__ == "__main__":
-    sys.exit(main())

bot_bottle/orchestrator/bootstrap.py

@@ -1,155 +0,0 @@
-"""Wire the concrete bot-bottle implementations into the core.
-
-This is the ONLY module that imports from `bot_bottle.contrib`. It adapts
-`SqliteForgeStateStore` to our `StateStore`, builds `GiteaForge`s (and
-scope-wrapped forges for sidecars), constructs the `Orchestrator`, and
-runs the webhook server + watchdog + done-signal relay.
-
-Imports are direct (no lazy loading) because the orchestrator is now part
-of the same package installation.
-"""
-
-from __future__ import annotations
-
-import os
-import threading
-from pathlib import Path
-from typing import Any
-
-from ..contrib.forge.base import ScopedForge
-from ..contrib.gitea.client import GiteaClient, GiteaForge
-from ..contrib.gitea.forge_state import ForgeState, SqliteForgeStateStore
-from .config import Config
-from .lifecycle import Orchestrator
-from .model import RunRecord
-from .runner import SubprocessBottleRunner
-from .sidecar import ForgeSidecar, OpLog, drain_done_events
-from .watchdog import Watchdog
-from .webhook import WebhookServer
-
-_RELAY_TICK_SECS = 2.0
-
-
-def _token() -> str:
-    tok = os.environ.get("GITEA_TOKEN") or os.environ.get("FORGE_GITEA_TOKEN")
-    if not tok:
-        raise RuntimeError("set GITEA_TOKEN (or FORGE_GITEA_TOKEN)")
-    return tok
-
-
-class BotBottleStateStore:
-    """Adapts `SqliteForgeStateStore` to our `StateStore`, translating
-    `RunRecord` <-> `ForgeState` field-for-field."""
-
-    def __init__(self, db_path: Path | None) -> None:
-        self._inner = SqliteForgeStateStore(db_path)
-
-    def upsert(self, record: RunRecord) -> None:
-        self._inner.upsert(_to_forge_state(record))
-
-    def get(self, owner: str, repo: str, issue_number: int) -> RunRecord | None:
-        state = self._inner.get(owner, repo, issue_number)
-        return _to_record(state) if state is not None else None
-
-    def delete(self, owner: str, repo: str, issue_number: int) -> None:
-        self._inner.delete(owner, repo, issue_number)
-
-    def all(self) -> list[RunRecord]:
-        return [_to_record(s) for s in self._inner.all()]
-
-
-def _to_forge_state(r: RunRecord) -> ForgeState:
-    return ForgeState(
-        owner=r.owner, repo=r.repo, issue_number=r.issue_number, slug=r.slug,
-        agent_name=r.agent_name, bottle_names=list(r.bottle_names),
-        backend_name=r.backend_name, agent_git_user=r.agent_git_user,
-        pr_number=r.pr_number, status=r.status, last_checkin_at=r.last_checkin_at,
-    )
-
-
-def _to_record(s: ForgeState) -> RunRecord:
-    return RunRecord(
-        owner=s.owner, repo=s.repo, issue_number=s.issue_number, slug=s.slug,
-        agent_name=s.agent_name, bottle_names=list(s.bottle_names),
-        backend_name=s.backend_name, agent_git_user=s.agent_git_user,
-        pr_number=s.pr_number, status=s.status, last_checkin_at=s.last_checkin_at,
-    )
-
-
-def make_forge(config: Config, owner: str, repo: str) -> Any:
-    """A `GiteaForge` bound to one repo."""
-    client = GiteaClient(
-        api_url=config.gitea_api, owner=owner, repo=repo, token=_token()
-    )
-    return GiteaForge(client)
-
-
-def make_sidecar(
-    config: Config, owner: str, repo: str, issue_number: int, assigned_prs: list[int]
-) -> ForgeSidecar:
-    """A scope-enforced sidecar for one run (read-anywhere / write-scoped)."""
-    scoped = ScopedForge(
-        make_forge(config, owner, repo),
-        assigned_issue=issue_number,
-        assigned_prs=assigned_prs,
-    )
-    op_log = OpLog(config.queue_dir / f"{owner}-{repo}-{issue_number}.oplog.jsonl")
-    return ForgeSidecar(
-        forge=scoped,
-        op_log=op_log,
-        queue_dir=config.queue_dir,
-        run_key=(owner, repo, issue_number),
-    )
-
-
-def build(config: Config) -> tuple[WebhookServer, Watchdog, Orchestrator]:
-    store = BotBottleStateStore(config.db_path)
-    runner = SubprocessBottleRunner(cli=config.bot_bottle_cli, base_env=dict(os.environ))
-    membership_forge = make_forge(config, "_", "_")
-    orchestrator = Orchestrator(
-        forge=membership_forge,
-        store=store,
-        runner=runner,
-        org=config.forge_org,
-        gitea_api=config.gitea_api,
-        forge_env_base={
-            "GITEA_TOKEN": _token(),
-            "FORGE_QUEUE_DIR": str(config.queue_dir),
-            "FORGE_SIDECAR_SOCKET": str(config.sidecar_socket),
-        },
-    )
-    watchdog = Watchdog(
-        store=store, runner=runner, timeout_secs=config.watchdog_timeout_secs
-    )
-    server = WebhookServer(
-        (config.webhook_host, config.webhook_port),
-        orchestrator=orchestrator,
-        store=store,
-    )
-    return server, watchdog, orchestrator
-
-
-def _relay_loop(config: Config, orchestrator: Orchestrator, stop: threading.Event) -> None:
-    while not stop.wait(_RELAY_TICK_SECS):
-        for ev in drain_done_events(config.queue_dir):
-            orchestrator.on_done_signal(
-                ev["owner"], ev["repo"], int(ev["issue_number"]),
-                str(ev.get("status", "")), str(ev.get("summary", "")),
-            )
-
-
-def run(config: Config) -> None:
-    """Blocking run: webhook server + watchdog + done-signal relay."""
-    server, watchdog, orchestrator = build(config)
-    watchdog.start()
-    stop = threading.Event()
-    relay = threading.Thread(
-        target=_relay_loop, args=(config, orchestrator, stop), daemon=True
-    )
-    relay.start()
-    try:
-        server.serve_forever()
-    finally:
-        stop.set()
-        watchdog.stop()
-        server.server_close()

bot_bottle/orchestrator/config.py

@@ -1,52 +0,0 @@
-"""Configuration, loaded from the environment (stdlib `os` only).
-
-Everything the orchestrator needs to run is an env var so a deploy is a
-process with an environment, no config file to manage. `FORGE_*` names
-match the bot-bottle forge-native PRD.
-"""
-
-from __future__ import annotations
-
-import os
-from dataclasses import dataclass
-from pathlib import Path
-
-# The label that marks an issue as agent-targeted: `bot-bottle:<agent>`.
-LABEL_PREFIX = "bot-bottle:"
-# Optional bottle override: `bot-bottle-bottle:<name>`.
-BOTTLE_LABEL_PREFIX = "bot-bottle-bottle:"
-
-
-@dataclass(frozen=True)
-class Config:
-    """Resolved orchestrator configuration."""
-
-    forge_org: str
-    gitea_api: str
-    watchdog_timeout_secs: int
-    webhook_host: str
-    webhook_port: int
-    bot_bottle_cli: str
-    queue_dir: Path
-    sidecar_socket: Path
-    db_path: Path | None
-
-    @staticmethod
-    def from_env(env: dict[str, str] | None = None) -> "Config":
-        e = os.environ if env is None else env
-        home = Path(e.get("HOME", str(Path.home())))
-        default_root = home / ".bot-bottle"
-        db = e.get("FORGE_DB_PATH")
-        return Config(
-            forge_org=e.get("FORGE_ORG", "bot-bottle"),
-            gitea_api=e.get("FORGE_GITEA_API", ""),
-            watchdog_timeout_secs=int(e.get("FORGE_WATCHDOG_TIMEOUT", "1800")),
-            webhook_host=e.get("FORGE_WEBHOOK_HOST", "127.0.0.1"),
-            webhook_port=int(e.get("FORGE_WEBHOOK_PORT", "8477")),
-            bot_bottle_cli=e.get("BOT_BOTTLE_CLI", "cli.py"),
-            queue_dir=Path(e.get("FORGE_QUEUE_DIR", str(default_root / "forge-queue"))),
-            sidecar_socket=Path(
-                e.get("FORGE_SIDECAR_SOCKET", str(default_root / "forge-sidecar.sock"))
-            ),
-            db_path=Path(db) if db else None,
-        )

bot_bottle/orchestrator/events.py

@@ -1,85 +0,0 @@
-"""Parse Gitea webhook payloads into typed `ForgeEvent`s.
-
-Only the fields the orchestrator acts on are extracted; unknown payloads
-and event types return None so the webhook layer can ignore them.
-
-Gitea sends the event kind in the `X-Gitea-Event` header and the payload
-as JSON. The relevant kinds:
-
-- `issues` with `action == "assigned"`  -> IssueAssigned
-- `issue_comment` with `action == "created"` -> CommentCreated
-- `pull_request` with `action == "closed"` -> PullRequestClosed
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-from .model import CommentCreated, ForgeEvent, IssueAssigned, PullRequestClosed
-
-
-def _repo_owner(payload: dict[str, Any]) -> tuple[str, str]:
-    repo = payload.get("repository") or {}
-    owner = (repo.get("owner") or {}).get("login", "")
-    return str(owner), str(repo.get("name", ""))
-
-
-def parse_event(event_kind: str, payload: dict[str, Any]) -> ForgeEvent | None:
-    """Map (X-Gitea-Event, payload) to a `ForgeEvent`, or None to ignore."""
-    if event_kind == "issues":
-        return _parse_issue(payload)
-    if event_kind == "issue_comment":
-        return _parse_comment(payload)
-    if event_kind == "pull_request":
-        return _parse_pull_request(payload)
-    return None
-
-
-def _parse_issue(payload: dict[str, Any]) -> IssueAssigned | None:
-    if payload.get("action") != "assigned":
-        return None
-    owner, repo = _repo_owner(payload)
-    issue = payload.get("issue") or {}
-    assignees = tuple(
-        str(a.get("login", "")) for a in (issue.get("assignees") or [])
-    )
-    labels = tuple(str(l.get("name", "")) for l in (issue.get("labels") or []))
-    return IssueAssigned(
-        owner=owner,
-        repo=repo,
-        issue_number=int(issue.get("number", 0)),
-        title=str(issue.get("title", "")),
-        body=str(issue.get("body", "") or ""),
-        assignees=assignees,
-        labels=labels,
-    )
-
-
-def _parse_comment(payload: dict[str, Any]) -> CommentCreated | None:
-    if payload.get("action") != "created":
-        return None
-    owner, repo = _repo_owner(payload)
-    issue = payload.get("issue") or {}
-    comment = payload.get("comment") or {}
-    return CommentCreated(
-        owner=owner,
-        repo=repo,
-        issue_number=int(issue.get("number", 0)),
-        comment_id=int(comment.get("id", 0)),
-        author=str((comment.get("user") or {}).get("login", "")),
-        body=str(comment.get("body", "") or ""),
-        is_pull=bool(issue.get("pull_request")),
-    )
-
-
-def _parse_pull_request(payload: dict[str, Any]) -> PullRequestClosed | None:
-    if payload.get("action") != "closed":
-        return None
-    owner, repo = _repo_owner(payload)
-    pr = payload.get("pull_request") or {}
-    return PullRequestClosed(
-        owner=owner,
-        repo=repo,
-        pr_number=int(pr.get("number", 0)),
-        merged=bool(pr.get("merged", False)),
-    )

bot_bottle/orchestrator/lifecycle.py

@@ -1,180 +0,0 @@
-"""The orchestration lifecycle: forge events -> bottle transitions.
-
-`Orchestrator.handle(event)` is the single entry point the webhook layer
-calls. `on_done_signal(...)` is called by the sidecar relay when an agent
-signals completion. All collaborators (forge, store, runner) are
-injected and duck-typed; `now` and `label_for` are injectable for tests.
-
-Transitions:
-  IssueAssigned (targeted, new)  -> start bottle, record = running
-  signal_done (running)          -> freeze bottle, record = frozen
-  CommentCreated (frozen)        -> resume bottle, record = running
-  PullRequestClosed (tracked)    -> destroy bottle, record removed
-"""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from datetime import datetime
-
-from .model import (
-    STATUS_DESTROYED,
-    STATUS_FROZEN,
-    STATUS_RUNNING,
-    CommentCreated,
-    ForgeEvent,
-    IssueAssigned,
-    PullRequestClosed,
-    RunRecord,
-)
-from .runner import BottleRunner
-from .store import StateStore
-from .targeting import Membership, Target, resolve_target
-
-
-def _iso_now() -> str:
-    return datetime.now().astimezone().isoformat(timespec="seconds")
-
-
-def _default_label(agent: str, event: IssueAssigned) -> str:
-    # Embed the issue identity so slugs are unique per issue and never
-    # get renamed on collision.
-    return f"{agent}-{event.owner}-{event.repo}-{event.issue_number}"
-
-
-class Orchestrator:
-    def __init__(
-        self,
-        *,
-        forge: Membership,
-        store: StateStore,
-        runner: BottleRunner,
-        org: str,
-        gitea_api: str = "",
-        forge_env_base: dict[str, str] | None = None,
-        now: Callable[[], str] = _iso_now,
-        label_for: Callable[[str, IssueAssigned], str] = _default_label,
-    ) -> None:
-        self._forge = forge
-        self._store = store
-        self._runner = runner
-        self._org = org
-        self._gitea_api = gitea_api
-        self._forge_env_base = forge_env_base or {}
-        self._now = now
-        self._label_for = label_for
-
-    # --- entry points ------------------------------------------------------
-
-    def handle(self, event: ForgeEvent) -> None:
-        if isinstance(event, IssueAssigned):
-            self._on_issue_assigned(event)
-        elif isinstance(event, CommentCreated):
-            self._on_comment(event)
-        else:
-            self._on_pr_closed(event)
-
-    def on_done_signal(  # pylint: disable=unused-argument
-        self, owner: str, repo: str, issue_number: int, status: str, summary: str
-    ) -> None:
-        """Sidecar relay: an agent signalled completion. Freeze the bottle.
-        `status`/`summary` are recorded by provenance (via the op log), not
-        acted on here."""
-        record = self._store.get(owner, repo, issue_number)
-        if record is None or record.status != STATUS_RUNNING:
-            return
-        self._runner.freeze(record.slug)
-        record.status = STATUS_FROZEN
-        record.last_checkin_at = self._now()
-        self._store.upsert(record)
-
-    def link_pr(self, owner: str, repo: str, issue_number: int, pr_number: int) -> None:
-        """Record the PR a tracked issue produced, so PR comments and the
-        PR-close event route back to this record."""
-        record = self._store.get(owner, repo, issue_number)
-        if record is not None:
-            record.pr_number = pr_number
-            self._store.upsert(record)
-
-    # --- handlers ----------------------------------------------------------
-
-    def _on_issue_assigned(self, event: IssueAssigned) -> None:
-        target = resolve_target(event, self._forge, self._org)
-        if target is None:
-            return
-        # Idempotent: a webhook redelivery must not launch a second bottle.
-        if self._store.get(event.owner, event.repo, event.issue_number) is not None:
-            return
-        self._launch(event, target)
-
-    def _launch(self, event: IssueAssigned, target: Target) -> None:
-        label = self._label_for(target.agent_name, event)
-        bottles = [target.bottle_override] if target.bottle_override else []
-        result = self._runner.start(
-            agent=target.agent_name,
-            bottles=bottles,
-            label=label,
-            prompt=event.body,
-            forge_env=self._forge_env(event.owner, event.repo, event.issue_number),
-        )
-        self._store.upsert(
-            RunRecord(
-                owner=event.owner,
-                repo=event.repo,
-                issue_number=event.issue_number,
-                slug=result.slug,
-                agent_name=target.agent_name,
-                bottle_names=bottles,
-                status=STATUS_RUNNING,
-                last_checkin_at=self._now(),
-            )
-        )
-
-    def _on_comment(self, event: CommentCreated) -> None:
-        record = self._route_comment(event)
-        if record is None or record.status != STATUS_FROZEN:
-            return
-        # Echo-loop guard: ignore the agent's own comments.
-        if record.agent_git_user and event.author == record.agent_git_user:
-            return
-        self._runner.resume(record.slug, event.body)
-        record.status = STATUS_RUNNING
-        record.last_checkin_at = self._now()
-        self._store.upsert(record)
-
-    def _route_comment(self, event: CommentCreated) -> RunRecord | None:
-        # A comment on the issue routes by issue number; a comment on a PR
-        # routes by the recorded pr_number.
-        direct = self._store.get(event.owner, event.repo, event.issue_number)
-        if direct is not None:
-            return direct
-        if event.is_pull:
-            return self._find_by_pr(event.owner, event.repo, event.issue_number)
-        return None
-
-    def _on_pr_closed(self, event: PullRequestClosed) -> None:
-        record = self._find_by_pr(event.owner, event.repo, event.pr_number)
-        if record is None:
-            return
-        self._runner.destroy(record.slug)
-        record.status = STATUS_DESTROYED
-        self._store.delete(record.owner, record.repo, record.issue_number)
-
-    def _find_by_pr(self, owner: str, repo: str, pr_number: int) -> RunRecord | None:
-        for record in self._store.all():
-            if (
-                record.owner == owner
-                and record.repo == repo
-                and record.pr_number == pr_number
-            ):
-                return record
-        return None
-
-    def _forge_env(self, owner: str, repo: str, issue_number: int) -> dict[str, str]:
-        env = dict(self._forge_env_base)
-        if self._gitea_api:
-            env["FORGE_GITEA_API"] = self._gitea_api
-        env["FORGE_OWNER"] = owner
-        env["FORGE_REPO"] = repo
-        env["FORGE_ISSUE_NUMBER"] = str(issue_number)
-        return env

bot_bottle/orchestrator/model.py

@@ -1,108 +0,0 @@
-"""Domain model: run records, forge events, provenance.
-
-These are the orchestrator's own dataclasses. `RunRecord` mirrors
-bot-bottle's `ForgeState` field-for-field so the bootstrap adapter can
-translate between them with no loss; keeping our own copy is what lets
-the core stay import-free of bot-bottle.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-
-# Run 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 RunRecord:
-    """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 = ""
-
-
-# --- Forge events (parsed webhook payloads) --------------------------------
-
-
-@dataclass(frozen=True)
-class IssueAssigned:
-    """An issue gained an assignee — the trigger to consider a launch."""
-
-    owner: str
-    repo: str
-    issue_number: int
-    title: str
-    body: str
-    assignees: tuple[str, ...]
-    labels: tuple[str, ...]
-
-
-@dataclass(frozen=True)
-class CommentCreated:
-    """A comment was posted on an issue or PR — a rehydrate trigger."""
-
-    owner: str
-    repo: str
-    issue_number: int
-    comment_id: int
-    author: str
-    body: str
-    is_pull: bool
-
-
-@dataclass(frozen=True)
-class PullRequestClosed:
-    """A PR closed (merged or not) — the teardown trigger."""
-
-    owner: str
-    repo: str
-    pr_number: int
-    merged: bool
-
-
-# Union of everything the webhook layer can emit.
-ForgeEvent = IssueAssigned | CommentCreated | PullRequestClosed
-
-
-# --- Provenance ------------------------------------------------------------
-
-
-@dataclass(frozen=True)
-class ForgeOp:
-    """One semantic forge operation the sidecar recorded."""
-
-    at: str          # ISO timestamp
-    op: str          # e.g. "post_comment", "read_pr", "signal_done"
-    target: int | None
-    detail: str
-
-
-@dataclass(frozen=True)
-class Provenance:
-    """The audit record for one run, served by the provenance API. Never
-    posted into the forge."""
-
-    slug: str
-    owner: str
-    repo: str
-    issue_number: int
-    agent_name: str
-    bottle_names: tuple[str, ...]
-    started_at: str
-    finished_at: str
-    exit_code: int | None
-    watchdog_fired: bool
-    ops: tuple[ForgeOp, ...]

bot_bottle/orchestrator/provenance.py

@@ -1,71 +0,0 @@
-"""Provenance assembly + serialization.
-
-Provenance is the run's audit record: the `RunRecord` metadata plus the
-sidecar's semantic operation log. It is exposed through the provenance
-API (see `webhook.ProvenanceHandler`) and deliberately never posted back
-into the forge — a mutable PR comment is not an audit record.
-
-This module only assembles and serializes; retention/signing of the
-record is a control-plane concern out of scope here.
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-from .model import ForgeOp, Provenance, RunRecord
-
-
-def ops_from_log(entries: list[dict[str, Any]]) -> tuple[ForgeOp, ...]:
-    return tuple(
-        ForgeOp(
-            at=str(e.get("at", "")),
-            op=str(e.get("op", "")),
-            target=e.get("target"),
-            detail=str(e.get("detail", "")),
-        )
-        for e in entries
-    )
-
-
-def build_provenance(
-    record: RunRecord,
-    *,
-    ops: tuple[ForgeOp, ...],
-    started_at: str,
-    finished_at: str,
-    exit_code: int | None,
-    watchdog_fired: bool,
-) -> Provenance:
-    return Provenance(
-        slug=record.slug,
-        owner=record.owner,
-        repo=record.repo,
-        issue_number=record.issue_number,
-        agent_name=record.agent_name,
-        bottle_names=tuple(record.bottle_names),
-        started_at=started_at,
-        finished_at=finished_at,
-        exit_code=exit_code,
-        watchdog_fired=watchdog_fired,
-        ops=ops,
-    )
-
-
-def provenance_to_dict(p: Provenance) -> dict[str, Any]:
-    return {
-        "slug": p.slug,
-        "owner": p.owner,
-        "repo": p.repo,
-        "issue_number": p.issue_number,
-        "agent": p.agent_name,
-        "bottles": list(p.bottle_names),
-        "started_at": p.started_at,
-        "finished_at": p.finished_at,
-        "exit_code": p.exit_code,
-        "watchdog_fired": p.watchdog_fired,
-        "ops": [
-            {"at": o.at, "op": o.op, "target": o.target, "detail": o.detail}
-            for o in p.ops
-        ],
-    }

bot_bottle/orchestrator/runner.py

@@ -1,118 +0,0 @@
-"""Bottle runner: drive the bot-bottle CLI to manage a bottle's life.
-
-`BottleRunner` is the interface the lifecycle depends on;
-`SubprocessBottleRunner` shells out to the bot-bottle `cli.py`
-(`start --headless`, `commit`, `resume --headless`). The subprocess
-callable is injectable so tests never spawn a process.
-
-The slug is derived from the label via `slugify`, matching bot-bottle's
-container-slug rule; the orchestrator picks labels that embed the issue
-identity so slugs are unique and collisions never rename them.
-"""
-
-from __future__ import annotations
-
-import re
-import subprocess
-import sys
-from collections.abc import Callable, Sequence
-from dataclasses import dataclass
-from typing import Protocol
-
-
-@dataclass(frozen=True)
-class RunResult:
-    slug: str
-    exit_code: int
-
-
-class BottleRunner(Protocol):
-    def start(
-        self,
-        *,
-        agent: str,
-        bottles: Sequence[str],
-        label: str,
-        prompt: str,
-        forge_env: dict[str, str],
-    ) -> RunResult: ...
-
-    def freeze(self, slug: str) -> int: ...
-
-    def resume(self, slug: str, prompt: str) -> RunResult: ...
-
-    def destroy(self, slug: str) -> int: ...
-
-
-_SLUG_RE = re.compile(r"[^a-z0-9]+")
-
-
-def slugify(label: str) -> str:
-    """Lowercase, collapse non-alphanumerics to single hyphens, strip
-    leading/trailing hyphens — matches bot-bottle's slug rule."""
-    return _SLUG_RE.sub("-", label.lower()).strip("-")
-
-
-# A subprocess.run-shaped callable, injectable for tests.
-RunFn = Callable[[Sequence[str], dict[str, str]], int]
-
-
-def _default_run(argv: Sequence[str], env: dict[str, str]) -> int:
-    return subprocess.run(list(argv), env=env, check=False).returncode
-
-
-class SubprocessBottleRunner:
-    """Shells the bot-bottle CLI. `cli` is the path to `cli.py`; `python`
-    is the interpreter to run it with; `base_env` is the environment the
-    child inherits (the orchestrator's, minus per-run additions)."""
-
-    def __init__(
-        self,
-        *,
-        cli: str,
-        base_env: dict[str, str],
-        python: str = sys.executable,
-        run: RunFn = _default_run,
-    ) -> None:
-        self._cli = cli
-        self._python = python
-        self._base_env = base_env
-        self._run = run
-
-    def _argv(self, *args: str) -> list[str]:
-        return [self._python, self._cli, *args]
-
-    def start(
-        self,
-        *,
-        agent: str,
-        bottles: Sequence[str],
-        label: str,
-        prompt: str,
-        forge_env: dict[str, str],
-    ) -> RunResult:
-        argv = self._argv(
-            "start", agent, "--headless", "--label", label, "--prompt", prompt
-        )
-        for bottle in bottles:
-            argv += ["--bottle", bottle]
-        code = self._run(argv, {**self._base_env, **forge_env})
-        return RunResult(slug=slugify(label), exit_code=code)
-
-    def freeze(self, slug: str) -> int:
-        # bot-bottle's `commit` snapshots a running bottle's state.
-        return self._run(self._argv("commit", slug), self._base_env)
-
-    def resume(self, slug: str, prompt: str) -> RunResult:
-        code = self._run(
-            self._argv("resume", slug, "--headless", "--prompt", prompt),
-            self._base_env,
-        )
-        return RunResult(slug=slug, exit_code=code)
-
-    def destroy(self, slug: str) -> int:
-        # NOTE: bot-bottle `cleanup` currently targets all bottles; a
-        # per-slug teardown command is a known integration follow-up
-        # (tracked in docs/JOURNAL.md). Kept behind this method so the
-        # call site does not change when that lands.
-        return self._run(self._argv("cleanup", slug), self._base_env)

bot_bottle/orchestrator/sidecar.py

@@ -1,171 +0,0 @@
-"""Forge sidecar: the agent's only door to the forge.
-
-The agent calls the sidecar over a line-delimited JSON-RPC AF_UNIX
-socket; the sidecar dispatches to an injected `forge` (already
-scope-wrapped by bootstrap) and holds the token, so the agent never sees
-a credential or a forge endpoint. Every call is appended to a semantic
-operation log (the provenance raw material). `signal_done` additionally
-drops an event file in the queue dir the orchestrator drains.
-
-`dispatch` is pure and testable; `serve` wraps it in a socket server.
-"""
-
-from __future__ import annotations
-
-import dataclasses
-import json
-import socketserver
-import uuid
-from collections.abc import Callable
-from datetime import datetime
-from pathlib import Path
-from typing import Any
-
-_READ_METHODS = {"read_issue", "read_pr", "read_comments"}
-_WRITE_METHODS = {"post_comment", "update_description"}
-
-
-def _iso_now() -> str:
-    return datetime.now().astimezone().isoformat(timespec="seconds")
-
-
-def _jsonable(value: Any) -> Any:
-    if dataclasses.is_dataclass(value) and not isinstance(value, type):
-        return dataclasses.asdict(value)
-    if isinstance(value, list):
-        return [_jsonable(v) for v in value]
-    return value
-
-
-class OpLog:
-    """Append-only JSONL log of semantic forge operations."""
-
-    def __init__(self, path: Path, *, now: Callable[[], str] = _iso_now) -> None:
-        self._path = path
-        self._now = now
-        path.parent.mkdir(parents=True, exist_ok=True)
-
-    def record(self, op: str, target: int | None, detail: str) -> None:
-        entry = {"at": self._now(), "op": op, "target": target, "detail": detail}
-        with self._path.open("a", encoding="utf-8") as fh:
-            fh.write(json.dumps(entry) + "\n")
-
-    def read(self) -> list[dict[str, Any]]:
-        if not self._path.exists():
-            return []
-        return [
-            json.loads(line)
-            for line in self._path.read_text(encoding="utf-8").splitlines()
-            if line.strip()
-        ]
-
-
-def write_done_event(queue_dir: Path, event: dict[str, Any]) -> Path:
-    """Atomically drop a done-signal event file in the queue dir."""
-    queue_dir.mkdir(parents=True, exist_ok=True)
-    path = queue_dir / f"done-{uuid.uuid4().hex}.json"
-    tmp = path.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(event), encoding="utf-8")
-    tmp.replace(path)
-    return path
-
-
-def drain_done_events(queue_dir: Path) -> list[dict[str, Any]]:
-    """Read and remove every queued done-signal event."""
-    if not queue_dir.is_dir():
-        return []
-    events: list[dict[str, Any]] = []
-    for path in sorted(queue_dir.glob("done-*.json")):
-        try:
-            events.append(json.loads(path.read_text(encoding="utf-8")))
-        except (OSError, ValueError):
-            continue
-        finally:
-            path.unlink(missing_ok=True)
-    return events
-
-
-class ForgeSidecar:
-    """Dispatches sidecar protocol calls to the forge, logging each and
-    relaying `signal_done` to the queue dir. `run_key` is the
-    (owner, repo, issue_number) the run is bound to."""
-
-    def __init__(
-        self,
-        *,
-        forge: object,
-        op_log: OpLog,
-        queue_dir: Path,
-        run_key: tuple[str, str, int],
-    ) -> None:
-        self._forge = forge
-        self._log = op_log
-        self._queue_dir = queue_dir
-        self._owner, self._repo, self._issue = run_key
-
-    def dispatch(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
-        try:
-            result = self._invoke(method, params)
-        except Exception as exc:  # noqa: BLE001 — surface as JSON-RPC error
-            self._log.record(method, params.get("number"), f"error: {exc}")
-            return {"ok": False, "error": str(exc)}
-        return {"ok": True, "result": result}
-
-    def _invoke(self, method: str, params: dict[str, Any]) -> Any:
-        if method in _READ_METHODS:
-            number = int(params["number"])
-            result = getattr(self._forge, method)(number)
-            self._log.record(method, number, "ok")
-            return _jsonable(result)
-        if method in _WRITE_METHODS:
-            number = int(params["number"])
-            getattr(self._forge, method)(number, params["body"])
-            self._log.record(method, number, "ok")
-            return None
-        if method == "signal_done":
-            status = str(params.get("status", ""))
-            summary = str(params.get("summary", ""))
-            self._log.record("signal_done", None, f"{status}: {summary}")
-            write_done_event(
-                self._queue_dir,
-                {
-                    "owner": self._owner,
-                    "repo": self._repo,
-                    "issue_number": self._issue,
-                    "status": status,
-                    "summary": summary,
-                },
-            )
-            return None
-        raise ValueError(f"unknown method: {method}")
-
-
-class _Handler(socketserver.StreamRequestHandler):
-    def handle(self) -> None:
-        line = self.rfile.readline()
-        if not line:
-            return
-        try:
-            req = json.loads(line)
-        except ValueError:
-            self.wfile.write(b'{"ok": false, "error": "invalid json"}\n')
-            return
-        resp = self.server.sidecar.dispatch(  # type: ignore[attr-defined]
-            str(req.get("method", "")), dict(req.get("params", {}))
-        )
-        self.wfile.write((json.dumps(resp) + "\n").encode())
-
-
-class _Server(socketserver.ThreadingUnixStreamServer):
-    def __init__(self, socket_path: str, sidecar: ForgeSidecar) -> None:
-        super().__init__(socket_path, _Handler)
-        self.sidecar = sidecar
-
-
-def serve(sidecar: ForgeSidecar, socket_path: Path) -> _Server:
-    """Bind a threaded AF_UNIX server for `sidecar`. Caller runs
-    `serve_forever()` (or `handle_request()` in tests) and closes it."""
-    if socket_path.exists():
-        socket_path.unlink()
-    socket_path.parent.mkdir(parents=True, exist_ok=True)
-    return _Server(str(socket_path), sidecar)

bot_bottle/orchestrator/store.py

@@ -1,48 +0,0 @@
-"""State store interface + an in-memory implementation.
-
-The orchestrator persists one `RunRecord` per forge-targeted issue. At
-runtime `bootstrap` supplies an adapter over bot-bottle's
-`SqliteForgeStateStore`; the in-memory store here backs tests and a
-`--no-bot-bottle` dry mode.
-"""
-
-from __future__ import annotations
-
-from typing import Protocol
-
-from .model import RunRecord
-
-
-class StateStore(Protocol):
-    """Thin CRUD surface. Mirrors bot-bottle's `ForgeStateStore` so the
-    bootstrap adapter is a straight pass-through."""
-
-    def upsert(self, record: RunRecord) -> None: ...
-
-    def get(self, owner: str, repo: str, issue_number: int) -> RunRecord | None: ...
-
-    def delete(self, owner: str, repo: str, issue_number: int) -> None: ...
-
-    def all(self) -> list[RunRecord]: ...
-
-
-class InMemoryStateStore:
-    """Dict-backed `StateStore`, keyed by (owner, repo, issue_number)."""
-
-    def __init__(self) -> None:
-        self._by_key: dict[tuple[str, str, int], RunRecord] = {}
-
-    def upsert(self, record: RunRecord) -> None:
-        self._by_key[(record.owner, record.repo, record.issue_number)] = record
-
-    def get(self, owner: str, repo: str, issue_number: int) -> RunRecord | None:
-        return self._by_key.get((owner, repo, issue_number))
-
-    def delete(self, owner: str, repo: str, issue_number: int) -> None:
-        self._by_key.pop((owner, repo, issue_number), None)
-
-    def all(self) -> list[RunRecord]:
-        return sorted(
-            self._by_key.values(),
-            key=lambda r: (r.owner, r.repo, r.issue_number),
-        )

bot_bottle/orchestrator/targeting.py

@@ -1,51 +0,0 @@
-"""Decide whether an assigned issue is agent-targeted, and for whom.
-
-An issue is forge-targeted when BOTH hold:
-- it carries a `bot-bottle:<agent>` label naming the agent, and
-- at least one assignee is a member of the configured org.
-
-An optional `bot-bottle-bottle:<name>` label overrides bottle selection.
-The forge is duck-typed: any object with `is_org_member(org, user)`.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Protocol
-
-from .config import BOTTLE_LABEL_PREFIX, LABEL_PREFIX
-from .model import IssueAssigned
-
-
-class Membership(Protocol):
-    def is_org_member(self, org: str, username: str) -> bool: ...
-
-
-@dataclass(frozen=True)
-class Target:
-    agent_name: str
-    bottle_override: str | None
-
-
-def parse_labels(labels: tuple[str, ...]) -> tuple[str | None, str | None]:
-    """Return (agent_name, bottle_override) parsed from labels."""
-    agent: str | None = None
-    bottle: str | None = None
-    for label in labels:
-        if label.startswith(BOTTLE_LABEL_PREFIX):
-            bottle = label[len(BOTTLE_LABEL_PREFIX):] or None
-        elif label.startswith(LABEL_PREFIX):
-            agent = label[len(LABEL_PREFIX):] or None
-    return agent, bottle
-
-
-def resolve_target(
-    event: IssueAssigned, forge: Membership, org: str
-) -> Target | None:
-    """Return the `Target` for a forge-targeted issue, or None to ignore."""
-    agent, bottle = parse_labels(event.labels)
-    if not agent:
-        return None
-    if not any(forge.is_org_member(org, a) for a in event.assignees):
-        return None
-    return Target(agent_name=agent, bottle_override=bottle)

bot_bottle/orchestrator/watchdog.py

@@ -1,68 +0,0 @@
-"""Watchdog: freeze runs whose agent exited without signalling done.
-
-`sweep(now)` is the pure, testable core: any `running` record whose
-`last_checkin_at` is older than the timeout is frozen as
-done-without-self-report and returned so provenance can flag it.
-`Watchdog.start()` runs `sweep` on a daemon thread once a minute.
-"""
-
-from __future__ import annotations
-
-import threading
-from datetime import datetime, timedelta
-
-from .model import STATUS_FROZEN, STATUS_RUNNING, RunRecord
-from .runner import BottleRunner
-from .store import StateStore
-
-_TICK_SECS = 60.0
-
-
-def _parse(ts: str) -> datetime | None:
-    try:
-        return datetime.fromisoformat(ts)
-    except (ValueError, TypeError):
-        return None
-
-
-class Watchdog:
-    def __init__(
-        self,
-        *,
-        store: StateStore,
-        runner: BottleRunner,
-        timeout_secs: int,
-    ) -> None:
-        self._store = store
-        self._runner = runner
-        self._timeout = timedelta(seconds=timeout_secs)
-        self._stop = threading.Event()
-        self._thread: threading.Thread | None = None
-
-    def sweep(self, now: datetime) -> list[RunRecord]:
-        """Freeze stale running records. Returns the ones fired."""
-        fired: list[RunRecord] = []
-        for record in self._store.all():
-            if record.status != STATUS_RUNNING:
-                continue
-            checkin = _parse(record.last_checkin_at)
-            if checkin is None or now - checkin <= self._timeout:
-                continue
-            self._runner.freeze(record.slug)
-            record.status = STATUS_FROZEN
-            self._store.upsert(record)
-            fired.append(record)
-        return fired
-
-    def start(self) -> None:
-        self._thread = threading.Thread(target=self._loop, daemon=True)
-        self._thread.start()
-
-    def stop(self) -> None:
-        self._stop.set()
-        if self._thread is not None:
-            self._thread.join(timeout=_TICK_SECS)
-
-    def _loop(self) -> None:
-        while not self._stop.wait(_TICK_SECS):
-            self.sweep(datetime.now().astimezone())

bot_bottle/orchestrator/webhook.py

@@ -1,123 +0,0 @@
-"""HTTP surface: the Gitea webhook receiver and the provenance API.
-
-`POST /webhook`   — a Gitea event; parsed and dispatched to the orchestrator.
-`GET  /healthz`   — liveness.
-`GET  /provenance?owner=&repo=&issue=` — the run's audit record (never
-                    posted to the forge).
-
-Webhook signature verification is optional: set a secret and the handler
-rejects bodies whose `X-Gitea-Signature` HMAC-SHA256 does not match.
-"""
-
-from __future__ import annotations
-
-import hmac
-import json
-from collections.abc import Callable
-from hashlib import sha256
-from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
-from typing import Any
-from urllib.parse import parse_qs, urlparse
-
-from .events import parse_event
-from .lifecycle import Orchestrator
-from .provenance import build_provenance, ops_from_log, provenance_to_dict
-from .store import StateStore
-
-# (record) -> that run's op-log entries, injected by bootstrap.
-OpLogReader = Callable[[Any], list[dict[str, Any]]]
-
-
-class WebhookServer(ThreadingHTTPServer):
-    def __init__(
-        self,
-        address: tuple[str, int],
-        *,
-        orchestrator: Orchestrator,
-        store: StateStore,
-        secret: bytes | None = None,
-        op_log_reader: OpLogReader | None = None,
-    ) -> None:
-        super().__init__(address, _Handler)
-        self.orchestrator = orchestrator
-        self.store = store
-        self.secret = secret
-        self.op_log_reader = op_log_reader
-
-
-def verify_signature(secret: bytes, body: bytes, signature: str) -> bool:
-    expected = hmac.new(secret, body, sha256).hexdigest()
-    return hmac.compare_digest(expected, signature or "")
-
-
-class _Handler(BaseHTTPRequestHandler):
-    server: WebhookServer  # type: ignore[assignment]
-
-    def log_message(  # pylint: disable=redefined-builtin
-        self, format: str, *args: Any
-    ) -> None:  # quiet by default
-        pass
-
-    def _send(self, code: int, payload: dict[str, Any]) -> None:
-        body = json.dumps(payload).encode()
-        self.send_response(code)
-        self.send_header("Content-Type", "application/json")
-        self.send_header("Content-Length", str(len(body)))
-        self.end_headers()
-        self.wfile.write(body)
-
-    def do_POST(self) -> None:  # noqa: N802  # pylint: disable=invalid-name
-        if urlparse(self.path).path != "/webhook":
-            self._send(404, {"error": "not found"})
-            return
-        length = int(self.headers.get("Content-Length", "0"))
-        body = self.rfile.read(length)
-        if self.server.secret is not None:
-            sig = self.headers.get("X-Gitea-Signature", "")
-            if not verify_signature(self.server.secret, body, sig):
-                self._send(401, {"error": "bad signature"})
-                return
-        try:
-            payload = json.loads(body)
-        except ValueError:
-            self._send(400, {"error": "invalid json"})
-            return
-        kind = self.headers.get("X-Gitea-Event", "")
-        event = parse_event(kind, payload)
-        if event is not None:
-            self.server.orchestrator.handle(event)
-        self._send(200, {"ok": True, "handled": event is not None})
-
-    def do_GET(self) -> None:  # noqa: N802  # pylint: disable=invalid-name
-        parsed = urlparse(self.path)
-        if parsed.path == "/healthz":
-            self._send(200, {"ok": True})
-            return
-        if parsed.path == "/provenance":
-            self._provenance(parse_qs(parsed.query))
-            return
-        self._send(404, {"error": "not found"})
-
-    def _provenance(self, query: dict[str, list[str]]) -> None:
-        try:
-            owner = query["owner"][0]
-            repo = query["repo"][0]
-            issue = int(query["issue"][0])
-        except (KeyError, IndexError, ValueError):
-            self._send(400, {"error": "owner, repo, issue required"})
-            return
-        record = self.server.store.get(owner, repo, issue)
-        if record is None:
-            self._send(404, {"error": "no such run"})
-            return
-        reader = self.server.op_log_reader
-        ops = ops_from_log(reader(record) if reader is not None else [])
-        prov = build_provenance(
-            record,
-            ops=ops,
-            started_at="",
-            finished_at=record.last_checkin_at,
-            exit_code=None,
-            watchdog_fired=False,
-        )
-        self._send(200, provenance_to_dict(prov))

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-claude-forward-host-credentials.md

@@ -1,146 +0,0 @@
-# PRD prd-new: Claude forward_host_credentials
-
-- **Status:** Draft
-- **Author:** claude
-- **Created:** 2026-07-01
-- **Issue:** #325
-
-## Summary
-
-Add `agent_provider.forward_host_credentials: true` support for the
-`claude` template, mirroring the existing Codex flow. When enabled,
-bot-bottle reads the host's Claude OAuth session key from
-`~/.claude.json` at launch, forwards it only to the egress sidecar,
-and injects a placeholder `CLAUDE_CODE_OAUTH_TOKEN` into the agent so
-Claude Code starts without ever seeing the real credential.
-
-## Problem
-
-Running a Claude agent in a container today requires the operator to
-manually extract a long-lived OAuth token (`claude setup-token`), export
-it as `BOT_BOTTLE_CLAUDE_OAUTH_TOKEN`, and reference it explicitly in
-the manifest with `agent_provider.auth_token:
-"BOT_BOTTLE_CLAUDE_OAUTH_TOKEN"`. This is a two-step manual ceremony
-that is easy to skip or do incorrectly.
-
-The host already stores a valid Claude session in `~/.claude.json` after
-`claude login` or `claude setup-token`. Codex already automates an
-equivalent extraction from `~/.codex/auth.json`. There is no reason
-Claude bottles cannot do the same.
-
-## Goals / Success Criteria
-
-- A Claude bottle with `forward_host_credentials: true` in the manifest
-  uses the host's `~/.claude.json` session key at launch with no
-  additional operator steps.
-- The agent container receives only `CLAUDE_CODE_OAUTH_TOKEN=egress-placeholder`
-  — never the real token.
-- The real session key lives only in the egress sidecar's environment.
-- Missing, malformed, or expired host Claude auth fails launch with a
-  clear operator-facing message.
-- Existing `auth_token` behavior is unchanged.
-- `forward_host_credentials: true` is rejected in the manifest when both
-  `auth_token` and `forward_host_credentials` are set, since they serve
-  the same purpose.
-
-## Non-goals
-
-- Refreshing Claude OAuth tokens in the sidecar.
-- Writing a dummy `~/.claude.json` auth state to the agent (unlike the
-  Codex flow, Claude Code reads its credential from `CLAUDE_CODE_OAUTH_TOKEN`
-  in env, not from an auth file — no guest-side auth marker is needed).
-- Supporting `forward_host_credentials` for providers other than `codex`
-  and `claude`.
-
-## Design
-
-### Manifest schema
-
-```yaml
-agent_provider:
-  template: claude
-  forward_host_credentials: true
-```
-
-Rejects in manifest validation when:
-- Template is not `codex` or `claude`.
-- Both `auth_token` and `forward_host_credentials` are set.
-
-### Host auth extraction (`contrib/claude/claude_auth.py`)
-
-Claude Code credential storage varies by platform:
-
-- **Linux**: `~/.claude/.credentials.json`
-- **macOS**: macOS Keychain, service `"Claude Code-credentials"`
-  (the file path is tried first; Keychain is the fallback when the file
-  is absent)
-
-`~/.claude.json` contains only UI state and profile metadata — no token.
-
-The credentials JSON schema (same whether from file or Keychain):
-
-```json
-{
-  "claudeAiOauth": {
-    "accessToken": "sk-ant-oat01-...",
-    "refreshToken": "sk-ant-ort01-...",
-    "expiresAt": 1748276587173,
-    "scopes": ["user:inference", "user:profile"]
-  }
-}
-```
-
-`expiresAt` is in **milliseconds** (not seconds).
-
-At prepare/launch time, when `forward_host_credentials: true`:
-
-1. Try `~/.claude/.credentials.json`; on macOS, if absent, run
-   `security find-generic-password -s "Claude Code-credentials" -w`
-   and parse its stdout as JSON.
-2. Require a `claudeAiOauth` dict.
-3. Require a non-empty `claudeAiOauth.accessToken` string.
-4. If `claudeAiOauth.expiresAt` is present, divide by 1000 and require
-   the result to be in the future.
-5. Return only the access token to the launch path.
-
-Errors name the missing or invalid condition and point the operator at
-`claude login`, without printing token values.
-
-### Egress route
-
-When `forward_host_credentials: true`:
-
-- Provision the session key in `provisioned_env` under
-  `BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN` (new constant in `egress.py`).
-- Set up the `api.anthropic.com` egress route with `auth_scheme: Bearer`
-  and `token_ref: BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN`.
-- Set `CLAUDE_CODE_OAUTH_TOKEN=egress-placeholder` in the agent env and
-  add it to `hidden_env_names`.
-
-No dummy auth file and no `verify` step are needed — Claude Code reads
-the credential from the env var, not from a file.
-
-### Constants
-
-- `CLAUDE_HOST_CREDENTIAL_TOKEN_REF = "BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN"`
-  in `egress.py` (alongside the existing `CODEX_HOST_CREDENTIAL_TOKEN_REF`).
-- `CLAUDE_HOST_CREDENTIAL_HOSTS = ("api.anthropic.com",)` in
-  `agent_provider.py` (alongside the existing `CODEX_HOST_CREDENTIAL_HOSTS`).
-
-### Data flow
-
-```
-Host ~/.claude.json  →  bot-bottle launch
-                            │
-                            ├──► egress sidecar env (real token only)
-                            │
-                            └──► agent env: CLAUDE_CODE_OAUTH_TOKEN=egress-placeholder
-
-Agent  →  HTTPS to api.anthropic.com (via egress)
-Egress →  injects Authorization: Bearer <real token>
-Egress →  forwards to api.anthropic.com
-```
-
-## Open questions
-
-None — the Codex precedent makes the design clear.

docs/prds/prd-new-fold-orchestrator-subpackage.md

@@ -1,132 +0,0 @@
-# PRD prd-new: Fold bot-bottle-orchestrator into this repo
-
-- **Status:** Active
-- **Author:** didericis
-- **Created:** 2026-07-01
-- **Issue:** #321
-
-## Summary
-
-Move the `bot-bottle-orchestrator` binary into `bot_bottle/orchestrator/` as a
-first-class subpackage. `pip install bot-bottle` gets you everything; the
-orchestrator's entry point becomes `python -m bot_bottle.orchestrator run`. The
-cross-repo CLI contract becomes an internal boundary, and the forge integration
-layer (`GiteaClient`, `ScopedForge`, `SqliteForgeStateStore`) is promoted to
-`bot_bottle/contrib/` where it belongs.
-
-## Problem
-
-The orchestrator and bot-bottle are tightly coupled:
-- It always deploys on the same host.
-- It imports from `bot_bottle` for the forge/state layer.
-- Its runner shims (`start --headless`, `commit`, `resume`) map 1:1 to CLI
-  commands in `cli.py` — a breaking CLI change silently breaks the orchestrator
-  with no CI signal.
-- Two repos means two version pins, two CI pipelines, and two install steps
-  every time the deploy environment is rebuilt.
-
-## Goals / Success Criteria
-
-- All orchestrator modules live under `bot_bottle/orchestrator/` and the package
-  is importable as `from bot_bottle.orchestrator import ...`.
-- `python -m bot_bottle.orchestrator run` starts the webhook server.
-- `python -m bot_bottle.orchestrator status` prints tracked runs.
-- The forge integration layer (`GiteaClient`, `GiteaForge`, `ScopedForge`,
-  `ForgeState`, `SqliteForgeStateStore`) lives in `bot_bottle/contrib/` and is
-  covered by tests in `tests/unit/orchestrator/`.
-- All orchestrator unit tests pass under bot-bottle's existing CI
-  (`python -m unittest discover -s tests/unit`).
-- No functional change to the orchestrator's external behaviour: same
-  HTTP surface, same webhook protocol, same env-var config, same CLI flags.
-
-## Non-goals
-
-- Replacing `SubprocessBottleRunner` with a direct programmatic runner — the
-  subprocess shim stays; the `BottleRunner` protocol remains the internal
-  abstraction point.
-- Merging the orchestrator's SQLite DB with any other bot-bottle state store.
-- Archiving `bot-bottle-orchestrator` (that happens after this ships and the
-  deploy is updated; out of scope for this PR).
-
-## Design
-
-### Package layout
-
-```
-bot_bottle/
-  orchestrator/
-    __init__.py
-    __main__.py       # python -m bot_bottle.orchestrator
-    bootstrap.py      # wires contrib modules → orchestrator core
-    config.py
-    events.py
-    lifecycle.py
-    model.py
-    provenance.py
-    runner.py
-    sidecar.py
-    store.py
-    targeting.py
-    watchdog.py
-    webhook.py
-  contrib/
-    forge/
-      __init__.py
-      base.py         # ScopedForge: read-anywhere / write-scoped wrapper
-    gitea/
-      client.py       # GiteaClient (urllib.request), GiteaForge
-      forge_state.py  # ForgeState dataclass + SqliteForgeStateStore
-
-tests/unit/orchestrator/
-  __init__.py
-  _fakes.py
-  test_config.py
-  test_events.py
-  test_lifecycle.py
-  test_provenance.py
-  test_runner.py
-  test_sidecar.py
-  test_store.py
-  test_targeting.py
-  test_watchdog.py
-  test_webhook.py
-```
-
-### Module moves
-
-Every `orchestrator/` source file moves verbatim into `bot_bottle/orchestrator/`.
-Internal imports are already relative (`from .config import Config`) so no
-changes are needed inside the orchestrator modules themselves.
-
-`bootstrap.py` is the only file that changes meaningfully: the lazy `bot_bottle`
-imports become direct relative imports (`from ..contrib.gitea.client import …`),
-and the `_require_bot_bottle()` guard is removed since the package is always
-present.
-
-### New contrib modules
-
-**`bot_bottle/contrib/forge/base.py` — `ScopedForge`**
-
-Wraps any forge object and enforces read-anywhere / write-scoped access: reads
-pass through unconditionally; `post_comment` and `update_description` raise
-`PermissionError` for issue/PR numbers outside the assigned set.
-
-**`bot_bottle/contrib/gitea/client.py` — `GiteaClient`, `GiteaForge`**
-
-`GiteaClient` is a thin `urllib.request`-only HTTP wrapper (no new Python
-dependencies). `GiteaForge` composes a client and exposes the forge protocol:
-`is_org_member`, `read_issue`, `read_pr`, `read_comments`, `post_comment`,
-`update_description`.
-
-**`bot_bottle/contrib/gitea/forge_state.py` — `ForgeState`, `SqliteForgeStateStore`**
-
-`ForgeState` is a dataclass mirroring `RunRecord` field-for-field. `SqliteForgeStateStore`
-backs it with SQLite (stdlib `sqlite3`): a single `forge_state` table with one
-row per (owner, repo, issue\_number).
-
-### Test migration
-
-All orchestrator test files move to `tests/unit/orchestrator/` with absolute
-imports updated from `orchestrator.X` to `bot_bottle.orchestrator.X`. The unit
-discovery command (`-s tests/unit`) picks them up automatically — no CI changes
-required.

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/orchestrator/_fakes.py

@@ -1,69 +0,0 @@
-"""Shared test doubles: a duck-typed forge and bottle runner."""
-
-# Test doubles mirror an API shape; some params are intentionally unused.
-# pylint: disable=unused-argument
-
-from __future__ import annotations
-
-from collections.abc import Sequence
-
-from bot_bottle.orchestrator.runner import RunResult, slugify
-
-
-class FakeForge:
-    def __init__(self, members: tuple[str, ...] = ()) -> None:
-        self.members = set(members)
-        self.comments: list[tuple[int, str]] = []
-        self.descriptions: list[tuple[int, str]] = []
-        self.scope_denied: set[int] = set()
-
-    def is_org_member(self, org: str, username: str) -> bool:
-        return username in self.members
-
-    def read_issue(self, number: int) -> dict[str, object]:
-        return {"number": number, "kind": "issue"}
-
-    def read_pr(self, number: int) -> dict[str, object]:
-        return {"number": number, "merged": False}
-
-    def read_comments(self, number: int) -> list[dict[str, object]]:
-        return [{"id": 1, "user": "alice", "body": "hi"}]
-
-    def post_comment(self, number: int, body: str) -> None:
-        if number in self.scope_denied:
-            raise PermissionError(f"write to #{number} denied")
-        self.comments.append((number, body))
-
-    def update_description(self, number: int, body: str) -> None:
-        if number in self.scope_denied:
-            raise PermissionError(f"write to #{number} denied")
-        self.descriptions.append((number, body))
-
-
-class FakeRunner:
-    def __init__(self) -> None:
-        self.calls: list[tuple[object, ...]] = []
-
-    def start(
-        self,
-        *,
-        agent: str,
-        bottles: Sequence[str],
-        label: str,
-        prompt: str,
-        forge_env: dict[str, str],
-    ) -> RunResult:
-        self.calls.append(("start", agent, tuple(bottles), label, prompt, dict(forge_env)))
-        return RunResult(slug=slugify(label), exit_code=0)
-
-    def freeze(self, slug: str) -> int:
-        self.calls.append(("freeze", slug))
-        return 0
-
-    def resume(self, slug: str, prompt: str) -> RunResult:
-        self.calls.append(("resume", slug, prompt))
-        return RunResult(slug=slug, exit_code=0)
-
-    def destroy(self, slug: str) -> int:
-        self.calls.append(("destroy", slug))
-        return 0

tests/unit/orchestrator/test_bootstrap.py

@@ -1,179 +0,0 @@
-"""Unit: BotBottleStateStore, _token, conversions, make_forge/make_sidecar, build."""
-
-from __future__ import annotations
-
-import os
-import tempfile
-import unittest
-from pathlib import Path
-from unittest.mock import patch
-
-from bot_bottle.orchestrator.bootstrap import (
-    BotBottleStateStore,
-    _to_forge_state,
-    _to_record,
-    _token,
-    build,
-    make_forge,
-    make_sidecar,
-)
-from bot_bottle.orchestrator.config import Config
-from bot_bottle.orchestrator.model import RunRecord
-
-
-def _config(tmp: str) -> Config:
-    return Config(
-        forge_org="org",
-        gitea_api="http://g/api/v1",
-        watchdog_timeout_secs=1800,
-        webhook_host="127.0.0.1",
-        webhook_port=0,
-        bot_bottle_cli="cli.py",
-        queue_dir=Path(tmp) / "q",
-        sidecar_socket=Path(tmp) / "s.sock",
-        db_path=None,
-    )
-
-
-def _record(**kw: object) -> RunRecord:
-    defaults: dict[str, object] = {
-        "owner": "o", "repo": "r", "issue_number": 1, "slug": "s1", "agent_name": "a",
-        "bottle_names": ["claude"], "backend_name": "docker", "agent_git_user": "bot",
-        "pr_number": 5, "status": "running", "last_checkin_at": "2026-01-01T00:00:00+00:00",
-    }
-    defaults.update(kw)
-    return RunRecord(**defaults)  # type: ignore[arg-type]
-
-
-class TokenTest(unittest.TestCase):
-    def test_gitea_token_env(self):
-        with patch.dict(os.environ, {"GITEA_TOKEN": "tok123"}):
-            self.assertEqual("tok123", _token())
-
-    def test_forge_gitea_token_fallback(self):
-        clean = {k: v for k, v in os.environ.items()
-                 if k not in ("GITEA_TOKEN", "FORGE_GITEA_TOKEN")}
-        with patch.dict(os.environ, {**clean, "FORGE_GITEA_TOKEN": "tok456"}, clear=True):
-            self.assertEqual("tok456", _token())
-
-    def test_missing_token_raises(self):
-        clean = {k: v for k, v in os.environ.items()
-                 if k not in ("GITEA_TOKEN", "FORGE_GITEA_TOKEN")}
-        with patch.dict(os.environ, clean, clear=True):
-            with self.assertRaises(RuntimeError):
-                _token()
-
-
-class ConversionRoundTripTest(unittest.TestCase):
-    def test_record_survives_forge_state_roundtrip(self):
-        rec = _record()
-        result = _to_record(_to_forge_state(rec))
-        self.assertEqual(rec.owner, result.owner)
-        self.assertEqual(rec.repo, result.repo)
-        self.assertEqual(rec.issue_number, result.issue_number)
-        self.assertEqual(rec.slug, result.slug)
-        self.assertEqual(rec.agent_name, result.agent_name)
-        self.assertEqual(rec.bottle_names, result.bottle_names)
-        self.assertEqual(rec.backend_name, result.backend_name)
-        self.assertEqual(rec.agent_git_user, result.agent_git_user)
-        self.assertEqual(rec.pr_number, result.pr_number)
-        self.assertEqual(rec.status, result.status)
-        self.assertEqual(rec.last_checkin_at, result.last_checkin_at)
-
-    def test_none_pr_number_preserved(self):
-        rec = _record(pr_number=None)
-        result = _to_record(_to_forge_state(rec))
-        self.assertIsNone(result.pr_number)
-
-
-class BotBottleStateStoreTest(unittest.TestCase):
-    def setUp(self):
-        self.store = BotBottleStateStore(None)
-
-    def test_upsert_and_get(self):
-        self.store.upsert(_record())
-        got = self.store.get("o", "r", 1)
-        assert got is not None
-        self.assertEqual("s1", got.slug)
-
-    def test_get_missing(self):
-        self.assertIsNone(self.store.get("o", "r", 99))
-
-    def test_upsert_replaces(self):
-        self.store.upsert(_record())
-        self.store.upsert(_record(slug="new-slug"))
-        got = self.store.get("o", "r", 1)
-        assert got is not None
-        self.assertEqual("new-slug", got.slug)
-
-    def test_delete(self):
-        self.store.upsert(_record())
-        self.store.delete("o", "r", 1)
-        self.assertIsNone(self.store.get("o", "r", 1))
-
-    def test_all_returns_all_records(self):
-        self.store.upsert(_record(issue_number=1, slug="s1"))
-        self.store.upsert(_record(issue_number=2, slug="s2"))
-        recs = self.store.all()
-        self.assertEqual(2, len(recs))
-        slugs = {r.slug for r in recs}
-        self.assertEqual({"s1", "s2"}, slugs)
-
-    def test_all_empty(self):
-        self.assertEqual([], self.store.all())
-
-    def test_bottle_names_preserved(self):
-        self.store.upsert(_record(bottle_names=["claude", "dev"]))
-        got = self.store.get("o", "r", 1)
-        assert got is not None
-        self.assertEqual(["claude", "dev"], got.bottle_names)
-
-
-class MakeForgeTest(unittest.TestCase):
-    def test_returns_gitea_forge(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            config = _config(tmp)
-            with patch.dict(os.environ, {"GITEA_TOKEN": "tok"}):
-                forge = make_forge(config, "owner", "repo")
-        from bot_bottle.contrib.gitea.client import GiteaForge
-        self.assertIsInstance(forge, GiteaForge)
-
-
-class MakeSidecarTest(unittest.TestCase):
-    def test_returns_forge_sidecar(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            config = _config(tmp)
-            with patch.dict(os.environ, {"GITEA_TOKEN": "tok"}):
-                sidecar = make_sidecar(config, "owner", "repo", 1, [])
-        from bot_bottle.orchestrator.sidecar import ForgeSidecar
-        self.assertIsInstance(sidecar, ForgeSidecar)
-
-
-class BuildTest(unittest.TestCase):
-    def test_returns_server_watchdog_orchestrator(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            config = _config(tmp)
-            with patch.dict(os.environ, {"GITEA_TOKEN": "tok"}):
-                server, watchdog, orch = build(config)
-            server.server_close()
-
-        from bot_bottle.orchestrator.lifecycle import Orchestrator
-        from bot_bottle.orchestrator.watchdog import Watchdog
-        from bot_bottle.orchestrator.webhook import WebhookServer
-        self.assertIsInstance(server, WebhookServer)
-        self.assertIsInstance(watchdog, Watchdog)
-        self.assertIsInstance(orch, Orchestrator)
-
-    def test_server_binds_to_configured_host(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            config = _config(tmp)
-            with patch.dict(os.environ, {"GITEA_TOKEN": "tok"}):
-                server, _, _ = build(config)
-            addr = server.server_address
-            server.server_close()
-        self.assertEqual("127.0.0.1", addr[0])
-        self.assertGreater(addr[1], 0)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/orchestrator/test_config.py

@@ -1,38 +0,0 @@
-"""Unit: Config.from_env."""
-
-from __future__ import annotations
-
-import unittest
-from pathlib import Path
-
-from bot_bottle.orchestrator.config import Config
-
-
-class ConfigTest(unittest.TestCase):
-    def test_defaults(self):
-        c = Config.from_env({"HOME": "/home/x"})
-        self.assertEqual("bot-bottle", c.forge_org)
-        self.assertEqual(1800, c.watchdog_timeout_secs)
-        self.assertEqual("127.0.0.1", c.webhook_host)
-        self.assertEqual(8477, c.webhook_port)
-        self.assertEqual(Path("/home/x/.bot-bottle/forge-queue"), c.queue_dir)
-        self.assertIsNone(c.db_path)
-
-    def test_overrides(self):
-        c = Config.from_env({
-            "HOME": "/home/x",
-            "FORGE_ORG": "agents",
-            "FORGE_WATCHDOG_TIMEOUT": "60",
-            "FORGE_GITEA_API": "https://g.example/api/v1",
-            "FORGE_WEBHOOK_PORT": "9000",
-            "FORGE_DB_PATH": "/data/bb.db",
-        })
-        self.assertEqual("agents", c.forge_org)
-        self.assertEqual(60, c.watchdog_timeout_secs)
-        self.assertEqual("https://g.example/api/v1", c.gitea_api)
-        self.assertEqual(9000, c.webhook_port)
-        self.assertEqual(Path("/data/bb.db"), c.db_path)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/orchestrator/test_events.py

@@ -1,68 +0,0 @@
-"""Unit: webhook payload parsing."""
-
-from __future__ import annotations
-
-import unittest
-
-from bot_bottle.orchestrator.events import parse_event
-from bot_bottle.orchestrator.model import CommentCreated, IssueAssigned, PullRequestClosed
-
-_REPO = {"repository": {"name": "bot-bottle", "owner": {"login": "didericis"}}}
-
-
-class ParseEventTest(unittest.TestCase):
-    def test_issue_assigned(self):
-        payload = {
-            **_REPO,
-            "action": "assigned",
-            "issue": {
-                "number": 17,
-                "title": "Fix it",
-                "body": "please",
-                "assignees": [{"login": "agent-bot"}],
-                "labels": [{"name": "bot-bottle:implementer"}],
-            },
-        }
-        ev = parse_event("issues", payload)
-        self.assertIsInstance(ev, IssueAssigned)
-        assert isinstance(ev, IssueAssigned)
-        self.assertEqual(("didericis", "bot-bottle", 17), (ev.owner, ev.repo, ev.issue_number))
-        self.assertEqual(("agent-bot",), ev.assignees)
-        self.assertEqual(("bot-bottle:implementer",), ev.labels)
-
-    def test_issue_non_assigned_ignored(self):
-        self.assertIsNone(parse_event("issues", {**_REPO, "action": "opened", "issue": {}}))
-
-    def test_comment_created(self):
-        payload = {
-            **_REPO,
-            "action": "created",
-            "issue": {"number": 42, "pull_request": {"x": 1}},
-            "comment": {"id": 5, "user": {"login": "reviewer"}, "body": "redo"},
-        }
-        ev = parse_event("issue_comment", payload)
-        assert isinstance(ev, CommentCreated)
-        self.assertEqual(42, ev.issue_number)
-        self.assertEqual("reviewer", ev.author)
-        self.assertTrue(ev.is_pull)
-
-    def test_pull_request_closed(self):
-        payload = {**_REPO, "action": "closed", "pull_request": {"number": 8, "merged": True}}
-        ev = parse_event("pull_request", payload)
-        assert isinstance(ev, PullRequestClosed)
-        self.assertEqual(8, ev.pr_number)
-        self.assertTrue(ev.merged)
-
-    def test_pull_request_non_closed_ignored(self):
-        self.assertIsNone(parse_event("pull_request", {**_REPO, "action": "opened"}))
-
-    def test_comment_non_created_action_ignored(self):
-        payload = {**_REPO, "action": "edited", "issue": {}, "comment": {}}
-        self.assertIsNone(parse_event("issue_comment", payload))
-
-    def test_unknown_kind_ignored(self):
-        self.assertIsNone(parse_event("push", {**_REPO}))
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/orchestrator/test_forge_state.py

@@ -1,75 +0,0 @@
-"""Unit: ForgeState + SqliteForgeStateStore."""
-
-from __future__ import annotations
-
-import unittest
-
-from bot_bottle.contrib.gitea.forge_state import ForgeState, SqliteForgeStateStore
-
-
-def _state(**kw: object) -> ForgeState:
-    defaults: dict[str, object] = dict(
-        owner="alice", repo="myrepo", issue_number=1,
-        slug="impl-alice-myrepo-1", agent_name="impl",
-    )
-    defaults.update(kw)
-    return ForgeState(**defaults)  # type: ignore[arg-type]
-
-
-class ForgeStateStoreTest(unittest.TestCase):
-    def setUp(self):
-        self.store = SqliteForgeStateStore(None)
-
-    def test_upsert_and_get(self):
-        s = _state()
-        self.store.upsert(s)
-        got = self.store.get("alice", "myrepo", 1)
-        assert got is not None
-        self.assertEqual("impl-alice-myrepo-1", got.slug)
-        self.assertEqual("impl", got.agent_name)
-
-    def test_get_missing(self):
-        self.assertIsNone(self.store.get("alice", "myrepo", 99))
-
-    def test_upsert_replaces(self):
-        self.store.upsert(_state(status="running"))
-        self.store.upsert(_state(status="frozen"))
-        got = self.store.get("alice", "myrepo", 1)
-        assert got is not None
-        self.assertEqual("frozen", got.status)
-
-    def test_delete(self):
-        self.store.upsert(_state())
-        self.store.delete("alice", "myrepo", 1)
-        self.assertIsNone(self.store.get("alice", "myrepo", 1))
-
-    def test_delete_missing_no_error(self):
-        self.store.delete("alice", "myrepo", 99)
-
-    def test_all_sorted(self):
-        self.store.upsert(_state(owner="z", issue_number=2))
-        self.store.upsert(_state(owner="a", issue_number=1))
-        rows = self.store.all()
-        self.assertEqual(("a", "z"), (rows[0].owner, rows[1].owner))
-
-    def test_bottle_names_roundtrip(self):
-        self.store.upsert(_state(bottle_names=["claude", "dev"]))
-        got = self.store.get("alice", "myrepo", 1)
-        assert got is not None
-        self.assertEqual(["claude", "dev"], got.bottle_names)
-
-    def test_pr_number_none_roundtrip(self):
-        self.store.upsert(_state(pr_number=None))
-        got = self.store.get("alice", "myrepo", 1)
-        assert got is not None
-        self.assertIsNone(got.pr_number)
-
-    def test_pr_number_int_roundtrip(self):
-        self.store.upsert(_state(pr_number=42))
-        got = self.store.get("alice", "myrepo", 1)
-        assert got is not None
-        self.assertEqual(42, got.pr_number)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/orchestrator/test_lifecycle.py

@@ -1,163 +0,0 @@
-"""Unit: the orchestration lifecycle."""
-
-from __future__ import annotations
-
-import unittest
-from typing import cast
-
-from bot_bottle.orchestrator.lifecycle import Orchestrator
-from bot_bottle.orchestrator.model import (
-    STATUS_FROZEN,
-    STATUS_RUNNING,
-    CommentCreated,
-    IssueAssigned,
-    PullRequestClosed,
-)
-from bot_bottle.orchestrator.store import InMemoryStateStore
-
-from ._fakes import FakeForge, FakeRunner
-
-
-def _assigned(
-    labels: tuple[str, ...] = ("bot-bottle:impl",),
-    assignees: tuple[str, ...] = ("agent-bot",),
-) -> IssueAssigned:
-    return IssueAssigned(
-        owner="didericis", repo="bot-bottle", issue_number=17,
-        title="t", body="the task", assignees=tuple(assignees), labels=tuple(labels),
-    )
-
-
-class LifecycleTest(unittest.TestCase):
-    def setUp(self):
-        self.forge = FakeForge(members=("agent-bot",))
-        self.store = InMemoryStateStore()
-        self.runner = FakeRunner()
-        self.orch = Orchestrator(
-            forge=self.forge, store=self.store, runner=self.runner,
-            org="bot-bottle", gitea_api="https://g/api/v1",
-            now=lambda: "2026-07-01T00:00:00-04:00",
-        )
-
-    def _record(self):
-        return self.store.get("didericis", "bot-bottle", 17)
-
-    def test_assigned_targeted_launches(self):
-        self.orch.handle(_assigned())
-        rec = self._record()
-        assert rec is not None
-        self.assertEqual(STATUS_RUNNING, rec.status)
-        self.assertEqual("impl-didericis-bot-bottle-17", rec.slug)
-        self.assertEqual("start", self.runner.calls[0][0])
-        # forge context injected into the child env.
-        env = cast("dict[str, str]", self.runner.calls[0][5])
-        self.assertEqual("didericis", env["FORGE_OWNER"])
-        self.assertEqual("17", env["FORGE_ISSUE_NUMBER"])
-
-    def test_untargeted_ignored(self):
-        self.orch.handle(_assigned(labels=("bug",)))
-        self.assertIsNone(self._record())
-        self.assertEqual([], self.runner.calls)
-
-    def test_assigned_is_idempotent(self):
-        self.orch.handle(_assigned())
-        self.orch.handle(_assigned())  # redelivery
-        starts = [c for c in self.runner.calls if c[0] == "start"]
-        self.assertEqual(1, len(starts))
-
-    def test_done_signal_freezes(self):
-        self.orch.handle(_assigned())
-        self.orch.on_done_signal("didericis", "bot-bottle", 17, "success", "done")
-        rec = self._record()
-        assert rec is not None
-        self.assertEqual(STATUS_FROZEN, rec.status)
-        self.assertIn(("freeze", "impl-didericis-bot-bottle-17"), self.runner.calls)
-
-    def test_done_signal_ignored_when_not_running(self):
-        # No record yet -> no freeze.
-        self.orch.on_done_signal("didericis", "bot-bottle", 17, "s", "")
-        self.assertEqual([], self.runner.calls)
-
-    def test_comment_on_frozen_resumes(self):
-        self.orch.handle(_assigned())
-        self.orch.on_done_signal("didericis", "bot-bottle", 17, "s", "")
-        self.orch.handle(CommentCreated(
-            owner="didericis", repo="bot-bottle", issue_number=17,
-            comment_id=1, author="reviewer", body="please redo", is_pull=False,
-        ))
-        rec = self._record()
-        assert rec is not None
-        self.assertEqual(STATUS_RUNNING, rec.status)
-        self.assertIn(("resume", "impl-didericis-bot-bottle-17", "please redo"),
-                      self.runner.calls)
-
-    def test_comment_echo_guard(self):
-        self.orch.handle(_assigned())
-        self.orch.on_done_signal("didericis", "bot-bottle", 17, "s", "")
-        rec = self._record()
-        assert rec is not None
-        rec.agent_git_user = "agent-bot"
-        self.store.upsert(rec)
-        self.orch.handle(CommentCreated(
-            owner="didericis", repo="bot-bottle", issue_number=17,
-            comment_id=2, author="agent-bot", body="I finished", is_pull=False,
-        ))
-        # Still frozen, no resume triggered by the agent's own comment.
-        self.assertEqual(STATUS_FROZEN, self._record().status)  # type: ignore[union-attr]
-        self.assertNotIn("resume", [c[0] for c in self.runner.calls])
-
-    def test_comment_on_running_ignored(self):
-        self.orch.handle(_assigned())  # running
-        self.orch.handle(CommentCreated(
-            owner="didericis", repo="bot-bottle", issue_number=17,
-            comment_id=1, author="reviewer", body="hi", is_pull=False,
-        ))
-        self.assertNotIn("resume", [c[0] for c in self.runner.calls])
-
-    def test_pr_comment_routes_via_link(self):
-        self.orch.handle(_assigned())
-        self.orch.on_done_signal("didericis", "bot-bottle", 17, "s", "")
-        self.orch.link_pr("didericis", "bot-bottle", 17, 42)
-        # Comment arrives on PR #42 (issue_number == PR number in Gitea).
-        self.orch.handle(CommentCreated(
-            owner="didericis", repo="bot-bottle", issue_number=42,
-            comment_id=9, author="reviewer", body="fix", is_pull=True,
-        ))
-        self.assertIn(("resume", "impl-didericis-bot-bottle-17", "fix"),
-                      self.runner.calls)
-
-    def test_pr_closed_destroys_and_removes(self):
-        self.orch.handle(_assigned())
-        self.orch.link_pr("didericis", "bot-bottle", 17, 42)
-        self.orch.handle(PullRequestClosed(
-            owner="didericis", repo="bot-bottle", pr_number=42, merged=True,
-        ))
-        self.assertIn(("destroy", "impl-didericis-bot-bottle-17"), self.runner.calls)
-        self.assertIsNone(self._record())
-
-    def test_comment_on_untracked_issue_ignored(self):
-        # No record in store and is_pull=False -> _route_comment returns None.
-        self.orch.handle(CommentCreated(
-            owner="didericis", repo="bot-bottle", issue_number=99,
-            comment_id=1, author="reviewer", body="hi", is_pull=False,
-        ))
-        self.assertEqual([], self.runner.calls)
-
-    def test_pr_closed_untracked_pr_ignored(self):
-        # _find_by_pr finds nothing -> _on_pr_closed exits early.
-        self.orch.handle(PullRequestClosed(
-            owner="didericis", repo="bot-bottle", pr_number=999, merged=True,
-        ))
-        self.assertEqual([], self.runner.calls)
-
-
-class IsoNowTest(unittest.TestCase):
-    def test_returns_iso_string(self):
-        from bot_bottle.orchestrator.lifecycle import _iso_now
-        ts = _iso_now()
-        self.assertIsInstance(ts, str)
-        self.assertIn("T", ts)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/orchestrator/test_main.py

@@ -1,88 +0,0 @@
-"""Unit: __main__ CLI entry points (run and status commands)."""
-
-from __future__ import annotations
-
-import io
-import unittest
-from unittest.mock import patch
-
-from bot_bottle.orchestrator.__main__ import main
-from bot_bottle.orchestrator.config import Config
-from bot_bottle.orchestrator.model import RunRecord
-
-
-def _config() -> Config:
-    return Config.from_env({"HOME": "/tmp"})
-
-
-class MainRunTest(unittest.TestCase):
-    def test_run_delegates_to_bootstrap(self):
-        config = _config()
-        with patch.object(Config, "from_env", return_value=config), \
-             patch("bot_bottle.orchestrator.bootstrap.run") as mock_run:
-            rc = main(["run"])
-        self.assertEqual(0, rc)
-        mock_run.assert_called_once_with(config)
-
-    def test_run_prints_listen_address_to_stderr(self):
-        config = _config()
-        err = io.StringIO()
-        with patch.object(Config, "from_env", return_value=config), \
-             patch("bot_bottle.orchestrator.bootstrap.run"), \
-             patch("sys.stderr", err):
-            main(["run"])
-        self.assertIn(str(config.webhook_port), err.getvalue())
-
-
-class MainStatusTest(unittest.TestCase):
-    def test_status_empty_store(self):
-        config = _config()
-        with patch.object(Config, "from_env", return_value=config), \
-             patch("bot_bottle.orchestrator.bootstrap.BotBottleStateStore") as MockStore:
-            MockStore.return_value.all.return_value = []
-            rc = main(["status"])
-        self.assertEqual(0, rc)
-
-    def test_status_prints_records(self):
-        config = _config()
-        rec = RunRecord(
-            owner="o", repo="r", issue_number=1, slug="my-slug",
-            agent_name="a", pr_number=7, status="frozen",
-        )
-        out = io.StringIO()
-        with patch.object(Config, "from_env", return_value=config), \
-             patch("bot_bottle.orchestrator.bootstrap.BotBottleStateStore") as MockStore, \
-             patch("sys.stdout", out):
-            MockStore.return_value.all.return_value = [rec]
-            rc = main(["status"])
-        self.assertEqual(0, rc)
-        self.assertIn("my-slug", out.getvalue())
-        self.assertIn("PR#7", out.getvalue())
-
-    def test_status_no_pr_prints_dash(self):
-        config = _config()
-        rec = RunRecord(
-            owner="o", repo="r", issue_number=2, slug="s2",
-            agent_name="a", pr_number=None, status="running",
-        )
-        out = io.StringIO()
-        with patch.object(Config, "from_env", return_value=config), \
-             patch("bot_bottle.orchestrator.bootstrap.BotBottleStateStore") as MockStore, \
-             patch("sys.stdout", out):
-            MockStore.return_value.all.return_value = [rec]
-            main(["status"])
-        self.assertIn("-", out.getvalue())
-
-
-class MainArgparseTest(unittest.TestCase):
-    def test_no_command_exits(self):
-        with self.assertRaises(SystemExit):
-            main([])
-
-    def test_unknown_command_exits(self):
-        with self.assertRaises(SystemExit):
-            main(["bogus"])
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/orchestrator/test_provenance.py

@@ -1,53 +0,0 @@
-"""Unit: provenance assembly + serialization."""
-
-from __future__ import annotations
-
-import unittest
-
-from bot_bottle.orchestrator.model import RunRecord
-from bot_bottle.orchestrator.provenance import build_provenance, ops_from_log, provenance_to_dict
-
-
-def _record() -> RunRecord:
-    return RunRecord(
-        owner="didericis", repo="bot-bottle", issue_number=17,
-        slug="impl-17", agent_name="impl", bottle_names=["claude"],
-        last_checkin_at="2026-07-01T00:05:00-04:00",
-    )
-
-
-class ProvenanceTest(unittest.TestCase):
-    def test_ops_from_log(self):
-        ops = ops_from_log([
-            {"at": "T1", "op": "read_pr", "target": 5, "detail": "ok"},
-            {"at": "T2", "op": "signal_done", "target": None, "detail": "success: done"},
-        ])
-        self.assertEqual(2, len(ops))
-        self.assertEqual("read_pr", ops[0].op)
-        self.assertIsNone(ops[1].target)
-
-    def test_build_and_serialize(self):
-        ops = ops_from_log([{"at": "T1", "op": "post_comment", "target": 17, "detail": "ok"}])
-        prov = build_provenance(
-            _record(), ops=ops, started_at="2026-07-01T00:00:00-04:00",
-            finished_at="2026-07-01T00:05:00-04:00", exit_code=0, watchdog_fired=False,
-        )
-        d = provenance_to_dict(prov)
-        self.assertEqual("impl-17", d["slug"])
-        self.assertEqual("didericis", d["owner"])
-        self.assertEqual(["claude"], d["bottles"])
-        self.assertEqual(0, d["exit_code"])
-        self.assertFalse(d["watchdog_fired"])
-        self.assertEqual(1, len(d["ops"]))
-        self.assertEqual("post_comment", d["ops"][0]["op"])
-
-    def test_watchdog_flag_serialized(self):
-        prov = build_provenance(
-            _record(), ops=(), started_at="", finished_at="",
-            exit_code=None, watchdog_fired=True,
-        )
-        self.assertTrue(provenance_to_dict(prov)["watchdog_fired"])
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/orchestrator/test_runner.py

@@ -1,81 +0,0 @@
-"""Unit: SubprocessBottleRunner + slugify (injected run fn)."""
-
-from __future__ import annotations
-
-import unittest
-from collections.abc import Sequence
-
-from bot_bottle.orchestrator.runner import SubprocessBottleRunner, slugify
-
-
-class SlugifyTest(unittest.TestCase):
-    def test_basic(self):
-        self.assertEqual("impl-didericis-bot-bottle-17",
-                         slugify("impl-didericis-bot-bottle-17"))
-
-    def test_collapses_and_strips(self):
-        self.assertEqual("a-b-c", slugify("  A_B/C!! "))
-
-
-class SubprocessRunnerTest(unittest.TestCase):
-    def setUp(self):
-        self.argvs: list[list[str]] = []
-        self.envs: list[dict[str, str]] = []
-
-        def fake_run(argv: Sequence[str], env: dict[str, str]) -> int:
-            self.argvs.append(list(argv))
-            self.envs.append(dict(env))
-            return 0
-
-        self.runner = SubprocessBottleRunner(
-            cli="/x/cli.py", base_env={"PATH": "/bin"}, python="/py", run=fake_run
-        )
-
-    def test_start_argv_and_env(self):
-        result = self.runner.start(
-            agent="impl", bottles=["claude", "dev"], label="impl-r-17",
-            prompt="do it", forge_env={"FORGE_OWNER": "didericis"},
-        )
-        self.assertEqual("impl-r-17", result.slug)
-        argv = self.argvs[0]
-        self.assertEqual(["/py", "/x/cli.py", "start", "impl", "--headless",
-                          "--label", "impl-r-17", "--prompt", "do it",
-                          "--bottle", "claude", "--bottle", "dev"], argv)
-        # forge_env merged over base_env for the child.
-        self.assertEqual("didericis", self.envs[0]["FORGE_OWNER"])
-        self.assertEqual("/bin", self.envs[0]["PATH"])
-
-    def test_start_no_bottles_omits_flag(self):
-        self.runner.start(agent="impl", bottles=[], label="l", prompt="p", forge_env={})
-        self.assertNotIn("--bottle", self.argvs[0])
-
-    def test_freeze_calls_commit(self):
-        self.runner.freeze("slug-1")
-        self.assertEqual(["/py", "/x/cli.py", "commit", "slug-1"], self.argvs[0])
-
-    def test_resume_headless(self):
-        r = self.runner.resume("slug-1", "address review")
-        self.assertEqual("slug-1", r.slug)
-        self.assertEqual(
-            ["/py", "/x/cli.py", "resume", "slug-1", "--headless", "--prompt",
-             "address review"], self.argvs[0])
-
-    def test_destroy_calls_cleanup(self):
-        code = self.runner.destroy("slug-7")
-        self.assertEqual(0, code)
-        self.assertEqual(["/py", "/x/cli.py", "cleanup", "slug-7"], self.argvs[0])
-
-
-class DefaultRunTest(unittest.TestCase):
-    def test_calls_subprocess_and_returns_code(self):
-        from unittest.mock import MagicMock, patch
-        from bot_bottle.orchestrator.runner import _default_run
-        with patch("subprocess.run") as mock_run:
-            mock_run.return_value = MagicMock(returncode=42)
-            code = _default_run(["echo", "hi"], {"PATH": "/bin"})
-        self.assertEqual(42, code)
-        mock_run.assert_called_once_with(["echo", "hi"], env={"PATH": "/bin"}, check=False)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/orchestrator/test_scoped_forge.py

@@ -1,75 +0,0 @@
-"""Unit: ScopedForge — read-anywhere / write-scoped access control."""
-
-from __future__ import annotations
-
-import unittest
-
-from bot_bottle.contrib.forge.base import ScopedForge
-
-from ._fakes import FakeForge
-
-
-class ScopedForgeTest(unittest.TestCase):
-    def setUp(self):
-        self.inner = FakeForge()
-        self.scoped = ScopedForge(
-            self.inner, assigned_issue=10, assigned_prs=[20, 30]
-        )
-
-    # --- reads always pass through -----------------------------------------
-
-    def test_read_issue_allowed_anywhere(self):
-        for number in (10, 20, 99):
-            result = self.scoped.read_issue(number)
-            self.assertEqual(number, result["number"])
-
-    def test_read_pr_allowed_anywhere(self):
-        for number in (10, 20, 99):
-            result = self.scoped.read_pr(number)
-            self.assertEqual(number, result["number"])
-
-    def test_read_comments_allowed_anywhere(self):
-        comments = self.scoped.read_comments(99)
-        self.assertTrue(len(comments) > 0)
-
-    def test_is_org_member_passes_through(self):
-        inner = FakeForge(members=("alice",))
-        scoped = ScopedForge(inner, assigned_issue=1, assigned_prs=[])
-        self.assertTrue(scoped.is_org_member("org", "alice"))
-        self.assertFalse(scoped.is_org_member("org", "bob"))
-
-    # --- writes: assigned numbers allowed ----------------------------------
-
-    def test_post_comment_on_assigned_issue(self):
-        self.scoped.post_comment(10, "hi")
-        self.assertIn((10, "hi"), self.inner.comments)
-
-    def test_post_comment_on_assigned_pr(self):
-        self.scoped.post_comment(20, "lgtm")
-        self.assertIn((20, "lgtm"), self.inner.comments)
-
-    def test_update_description_on_assigned(self):
-        self.scoped.update_description(30, "updated")
-        self.assertIn((30, "updated"), self.inner.descriptions)
-
-    # --- writes: unassigned numbers denied ---------------------------------
-
-    def test_post_comment_denied_for_unassigned(self):
-        with self.assertRaises(PermissionError):
-            self.scoped.post_comment(99, "nope")
-        self.assertEqual([], self.inner.comments)
-
-    def test_update_description_denied_for_unassigned(self):
-        with self.assertRaises(PermissionError):
-            self.scoped.update_description(99, "nope")
-        self.assertEqual([], self.inner.descriptions)
-
-    def test_error_message_names_number(self):
-        try:
-            self.scoped.post_comment(99, "nope")
-        except PermissionError as exc:
-            self.assertIn("99", str(exc))
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/orchestrator/test_sidecar.py

@@ -1,204 +0,0 @@
-"""Unit: forge sidecar dispatch, op log, queue relay, socket server."""
-
-from __future__ import annotations
-
-import dataclasses
-import json
-import socket
-import tempfile
-import threading
-import unittest
-from pathlib import Path
-
-from bot_bottle.orchestrator.sidecar import (
-    ForgeSidecar,
-    OpLog,
-    _jsonable,
-    drain_done_events,
-    serve,
-    write_done_event,
-)
-
-from ._fakes import FakeForge
-
-
-class SidecarDispatchTest(unittest.TestCase):
-    def setUp(self):
-        self.tmp = Path(self.enterContext(tempfile.TemporaryDirectory()))  # pylint: disable=consider-using-with
-        self.forge = FakeForge()
-        self.log = OpLog(self.tmp / "ops.jsonl", now=lambda: "T")
-        self.queue = self.tmp / "queue"
-        self.sc = ForgeSidecar(
-            forge=self.forge, op_log=self.log, queue_dir=self.queue,
-            run_key=("o", "r", 17),
-        )
-
-    def test_read_pr_ok_and_logged(self):
-        resp = self.sc.dispatch("read_pr", {"number": 5})
-        self.assertTrue(resp["ok"])
-        self.assertEqual(5, resp["result"]["number"])
-        self.assertEqual([("read_pr", 5, "ok")],
-                         [(o["op"], o["target"], o["detail"]) for o in self.log.read()])
-
-    def test_post_comment_writes_and_logs(self):
-        resp = self.sc.dispatch("post_comment", {"number": 17, "body": "done"})
-        self.assertTrue(resp["ok"])
-        self.assertEqual([(17, "done")], self.forge.comments)
-
-    def test_scope_denied_write_returns_error_and_audits_rejection(self):
-        self.forge.scope_denied.add(999)
-        resp = self.sc.dispatch("post_comment", {"number": 999, "body": "x"})
-        self.assertFalse(resp["ok"])
-        self.assertIn("denied", resp["error"])
-        # The rejection is recorded in the op log, not just the allows.
-        self.assertIn("error", self.log.read()[-1]["detail"])
-        self.assertEqual([], self.forge.comments)
-
-    def test_signal_done_queues_event(self):
-        resp = self.sc.dispatch("signal_done", {"status": "success", "summary": "ok"})
-        self.assertTrue(resp["ok"])
-        events = drain_done_events(self.queue)
-        self.assertEqual(1, len(events))
-        self.assertEqual(("o", "r", 17, "success"),
-                         (events[0]["owner"], events[0]["repo"],
-                          events[0]["issue_number"], events[0]["status"]))
-
-    def test_unknown_method(self):
-        resp = self.sc.dispatch("delete_repo", {})
-        self.assertFalse(resp["ok"])
-
-
-class JsonableTest(unittest.TestCase):
-    def test_plain_value_passthrough(self):
-        self.assertEqual(42, _jsonable(42))
-        self.assertEqual("s", _jsonable("s"))
-
-    def test_dataclass_converted_to_dict(self):
-        @dataclasses.dataclass
-        class Thing:
-            x: int
-            y: str = "hi"
-        self.assertEqual({"x": 99, "y": "hi"}, _jsonable(Thing(x=99)))
-
-    def test_list_recursed(self):
-        self.assertEqual([1, 2, 3], _jsonable([1, 2, 3]))
-
-    def test_list_of_dataclasses(self):
-        @dataclasses.dataclass
-        class Item:
-            v: int
-        result = _jsonable([Item(v=1), Item(v=2)])
-        self.assertEqual([{"v": 1}, {"v": 2}], result)
-
-
-class QueueTest(unittest.TestCase):
-    def test_drain_removes_events(self):
-        tmp = Path(self.enterContext(tempfile.TemporaryDirectory()))  # pylint: disable=consider-using-with
-        write_done_event(tmp, {"owner": "o", "repo": "r", "issue_number": 1})
-        self.assertEqual(1, len(drain_done_events(tmp)))
-        self.assertEqual([], drain_done_events(tmp))  # drained
-
-    def test_drain_missing_dir(self):
-        self.assertEqual([], drain_done_events(Path("/nonexistent/queue")))
-
-    def test_drain_skips_corrupted_file(self):
-        tmp = Path(self.enterContext(tempfile.TemporaryDirectory()))  # pylint: disable=consider-using-with
-        (tmp / "done-bad.json").write_text("not json", encoding="utf-8")
-        events = drain_done_events(tmp)
-        self.assertEqual([], events)
-        # The corrupted file is removed by the finally block.
-        self.assertFalse((tmp / "done-bad.json").exists())
-
-
-class OpLogReadTest(unittest.TestCase):
-    def test_read_missing_file_returns_empty(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            log = OpLog(Path(tmp) / "sub" / "ops.jsonl")
-            # File not written yet — read() should return [].
-            self.assertEqual([], log.read())
-
-
-class SocketServerTest(unittest.TestCase):
-    def _make_server(self, tmp: Path):
-        sock = tmp / "s.sock"
-        if len(str(sock)) > 100:
-            self.skipTest("temp socket path too long for AF_UNIX")
-        sidecar = ForgeSidecar(
-            forge=FakeForge(), op_log=OpLog(tmp / "ops.jsonl"),
-            queue_dir=tmp / "q", run_key=("o", "r", 1),
-        )
-        return serve(sidecar, sock), sock
-
-    def test_round_trip_over_unix_socket(self):
-        tmp = tempfile.mkdtemp()
-        sock = Path(tmp) / "s.sock"
-        if len(str(sock)) > 100:  # AF_UNIX path limit; skip on long tmp paths
-            self.skipTest("temp socket path too long for AF_UNIX")
-        sidecar = ForgeSidecar(
-            forge=FakeForge(), op_log=OpLog(Path(tmp) / "ops.jsonl"),
-            queue_dir=Path(tmp) / "q", run_key=("o", "r", 1),
-        )
-        srv = serve(sidecar, sock)
-        t = threading.Thread(target=srv.handle_request, daemon=True)
-        t.start()
-        try:
-            client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
-            client.connect(str(sock))
-            client.sendall(b'{"method": "read_issue", "params": {"number": 3}}\n')
-            line = client.makefile().readline()
-            client.close()
-        finally:
-            t.join(timeout=5)
-            srv.server_close()
-        resp = json.loads(line)
-        self.assertTrue(resp["ok"])
-        self.assertEqual(3, resp["result"]["number"])
-
-
-    def test_handler_invalid_json_returns_error(self):
-        tmp = Path(tempfile.mkdtemp())
-        srv, sock = self._make_server(tmp)
-        t = threading.Thread(target=srv.handle_request, daemon=True)
-        t.start()
-        try:
-            client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
-            client.connect(str(sock))
-            client.sendall(b"not valid json!\n")
-            line = client.makefile().readline()
-            client.close()
-        finally:
-            t.join(timeout=5)
-            srv.server_close()
-        resp = json.loads(line)
-        self.assertFalse(resp["ok"])
-        self.assertIn("invalid json", resp["error"])
-
-    def test_handler_empty_line_closes_silently(self):
-        tmp = Path(tempfile.mkdtemp())
-        srv, sock = self._make_server(tmp)
-        t = threading.Thread(target=srv.handle_request, daemon=True)
-        t.start()
-        try:
-            client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
-            client.connect(str(sock))
-            client.close()  # immediate EOF -> readline() returns b""
-        finally:
-            t.join(timeout=5)
-            srv.server_close()
-
-    def test_serve_removes_existing_socket_path(self):
-        tmp = Path(tempfile.mkdtemp())
-        sock = tmp / "existing.sock"
-        if len(str(sock)) > 100:
-            self.skipTest("temp socket path too long for AF_UNIX")
-        sock.touch()  # pre-existing file at socket path
-        sidecar = ForgeSidecar(
-            forge=FakeForge(), op_log=OpLog(tmp / "ops.jsonl"),
-            queue_dir=tmp / "q", run_key=("o", "r", 1),
-        )
-        srv = serve(sidecar, sock)  # should unlink the pre-existing file
-        srv.server_close()
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/orchestrator/test_store.py

@@ -1,50 +0,0 @@
-"""Unit: InMemoryStateStore."""
-
-from __future__ import annotations
-
-import unittest
-
-from bot_bottle.orchestrator.model import RunRecord
-from bot_bottle.orchestrator.store import InMemoryStateStore
-
-
-def _rec(issue: int, owner: str = "o") -> RunRecord:
-    return RunRecord(owner=owner, repo="r", issue_number=issue, slug=f"s{issue}",
-                     agent_name="a")
-
-
-class InMemoryStoreTest(unittest.TestCase):
-    def setUp(self):
-        self.store = InMemoryStateStore()
-
-    def test_upsert_get(self):
-        self.store.upsert(_rec(1))
-        got = self.store.get("o", "r", 1)
-        assert got is not None
-        self.assertEqual("s1", got.slug)
-
-    def test_get_missing(self):
-        self.assertIsNone(self.store.get("o", "r", 99))
-
-    def test_upsert_replaces(self):
-        self.store.upsert(_rec(1))
-        r = _rec(1)
-        r.slug = "changed"
-        self.store.upsert(r)
-        self.assertEqual("changed", self.store.get("o", "r", 1).slug)  # type: ignore[union-attr]
-        self.assertEqual(1, len(self.store.all()))
-
-    def test_delete(self):
-        self.store.upsert(_rec(1))
-        self.store.delete("o", "r", 1)
-        self.assertIsNone(self.store.get("o", "r", 1))
-
-    def test_all_sorted(self):
-        self.store.upsert(_rec(2, owner="b"))
-        self.store.upsert(_rec(1, owner="a"))
-        self.assertEqual([("a", 1), ("b", 2)],
-                         [(r.owner, r.issue_number) for r in self.store.all()])
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/orchestrator/test_targeting.py

@@ -1,60 +0,0 @@
-"""Unit: targeting (labels + org membership)."""
-
-from __future__ import annotations
-
-import unittest
-
-from bot_bottle.orchestrator.model import IssueAssigned
-from bot_bottle.orchestrator.targeting import parse_labels, resolve_target
-
-from ._fakes import FakeForge
-
-
-def _issue(
-    assignees: tuple[str, ...] = ("agent-bot",),
-    labels: tuple[str, ...] = ("bot-bottle:implementer",),
-) -> IssueAssigned:
-    return IssueAssigned(
-        owner="didericis", repo="bot-bottle", issue_number=17,
-        title="t", body="b", assignees=tuple(assignees), labels=tuple(labels),
-    )
-
-
-class ParseLabelsTest(unittest.TestCase):
-    def test_agent_label(self):
-        self.assertEqual(("implementer", None), parse_labels(("bot-bottle:implementer",)))
-
-    def test_bottle_override_not_confused_with_agent(self):
-        agent, bottle = parse_labels(("bot-bottle:impl", "bot-bottle-bottle:dev"))
-        self.assertEqual(("impl", "dev"), (agent, bottle))
-
-    def test_no_agent_label(self):
-        self.assertEqual((None, None), parse_labels(("bug", "p1")))
-
-
-class ResolveTargetTest(unittest.TestCase):
-    def setUp(self):
-        self.forge = FakeForge(members=("agent-bot",))
-
-    def test_targeted(self):
-        target = resolve_target(_issue(), self.forge, "bot-bottle")
-        assert target is not None
-        self.assertEqual("implementer", target.agent_name)
-        self.assertIsNone(target.bottle_override)
-
-    def test_bottle_override(self):
-        ev = _issue(labels=("bot-bottle:impl", "bot-bottle-bottle:dev"))
-        target = resolve_target(ev, self.forge, "bot-bottle")
-        assert target is not None
-        self.assertEqual("dev", target.bottle_override)
-
-    def test_no_label_not_targeted(self):
-        self.assertIsNone(resolve_target(_issue(labels=("bug",)), self.forge, "bot-bottle"))
-
-    def test_non_member_assignee_not_targeted(self):
-        ev = _issue(assignees=("random-user",))
-        self.assertIsNone(resolve_target(ev, self.forge, "bot-bottle"))
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/orchestrator/test_watchdog.py

@@ -1,80 +0,0 @@
-"""Unit: watchdog sweep."""
-
-from __future__ import annotations
-
-import time
-import unittest
-import unittest.mock
-from datetime import datetime, timedelta
-
-from bot_bottle.orchestrator.model import STATUS_FROZEN, STATUS_RUNNING, RunRecord
-from bot_bottle.orchestrator.store import InMemoryStateStore
-from bot_bottle.orchestrator.watchdog import Watchdog
-
-from ._fakes import FakeRunner
-
-_NOW = datetime(2026, 7, 1, 12, 0, 0).astimezone()
-
-
-def _record(issue: int, status: str, checkin: str) -> RunRecord:
-    return RunRecord(
-        owner="o", repo="r", issue_number=issue, slug=f"s{issue}",
-        agent_name="a", status=status, last_checkin_at=checkin,
-    )
-
-
-class WatchdogSweepTest(unittest.TestCase):
-    def setUp(self):
-        self.store = InMemoryStateStore()
-        self.runner = FakeRunner()
-        self.wd = Watchdog(store=self.store, runner=self.runner, timeout_secs=1800)
-
-    def _status(self, issue: int) -> str:
-        rec = self.store.get("o", "r", issue)
-        assert rec is not None
-        return rec.status
-
-    def test_stale_running_is_frozen(self):
-        stale = (_NOW - timedelta(minutes=31)).isoformat()
-        self.store.upsert(_record(1, STATUS_RUNNING, stale))
-        fired = self.wd.sweep(_NOW)
-        self.assertEqual([1], [r.issue_number for r in fired])
-        self.assertEqual(STATUS_FROZEN, self._status(1))
-        self.assertIn(("freeze", "s1"), self.runner.calls)
-
-    def test_fresh_running_untouched(self):
-        fresh = (_NOW - timedelta(minutes=5)).isoformat()
-        self.store.upsert(_record(2, STATUS_RUNNING, fresh))
-        self.assertEqual([], self.wd.sweep(_NOW))
-        self.assertEqual(STATUS_RUNNING, self._status(2))
-
-    def test_non_running_ignored(self):
-        stale = (_NOW - timedelta(hours=2)).isoformat()
-        self.store.upsert(_record(3, STATUS_FROZEN, stale))
-        self.assertEqual([], self.wd.sweep(_NOW))
-
-    def test_unparseable_checkin_skipped(self):
-        self.store.upsert(_record(4, STATUS_RUNNING, "not-a-time"))
-        self.assertEqual([], self.wd.sweep(_NOW))
-
-    def test_start_and_stop(self):
-        # Exercises the daemon-thread start/stop path; stop sets the event
-        # so the loop's wait returns immediately.
-        self.wd.start()
-        self.wd.stop()
-
-    def test_loop_sweeps_stale_record(self):
-        # Patch tick to near-zero so the loop iterates quickly.
-        stale = (_NOW - timedelta(hours=1)).isoformat()
-        self.store.upsert(_record(5, STATUS_RUNNING, stale))
-        with unittest.mock.patch("bot_bottle.orchestrator.watchdog._TICK_SECS", 0.01):
-            self.wd.start()
-            time.sleep(0.05)  # enough for several iterations at 0.01s tick
-            self.wd.stop()
-        rec = self.store.get("o", "r", 5)
-        assert rec is not None
-        self.assertEqual(STATUS_FROZEN, rec.status)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/orchestrator/test_webhook.py

@@ -1,161 +0,0 @@
-"""Unit: webhook HTTP surface (signature + routing over a real server)."""
-
-from __future__ import annotations
-
-import hashlib
-import hmac
-import json
-import threading
-import unittest
-import urllib.request
-from urllib.error import HTTPError
-
-from bot_bottle.orchestrator.model import RunRecord
-from bot_bottle.orchestrator.store import InMemoryStateStore
-from bot_bottle.orchestrator.webhook import WebhookServer, verify_signature
-
-_ISSUE_ASSIGNED = {
-    "action": "assigned",
-    "repository": {"name": "bot-bottle", "owner": {"login": "didericis"}},
-    "issue": {
-        "number": 17, "title": "t", "body": "b",
-        "assignees": [{"login": "agent-bot"}],
-        "labels": [{"name": "bot-bottle:impl"}],
-    },
-}
-
-
-class _RecordingOrch:
-    def __init__(self) -> None:
-        self.events: list[object] = []
-
-    def handle(self, event: object) -> None:
-        self.events.append(event)
-
-
-class SignatureTest(unittest.TestCase):
-    def test_verify(self):
-        secret = b"s3cret"
-        body = b'{"x":1}'
-        sig = hmac.new(secret, body, hashlib.sha256).hexdigest()
-        self.assertTrue(verify_signature(secret, body, sig))
-        self.assertFalse(verify_signature(secret, body, "deadbeef"))
-
-
-class WebhookServerTest(unittest.TestCase):
-    # _serve is the per-test setup; attributes are assigned there.
-    # pylint: disable=attribute-defined-outside-init
-    def _serve(self, **kwargs: object) -> None:
-        self.orch = _RecordingOrch()
-        kwargs.setdefault("store", InMemoryStateStore())
-        self.server = WebhookServer(
-            ("127.0.0.1", 0), orchestrator=self.orch, **kwargs,  # type: ignore[arg-type]
-        )
-        self.port = self.server.server_address[1]
-        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
-        self.thread.start()
-        self.addCleanup(self._shutdown)
-
-    def _shutdown(self) -> None:
-        self.server.shutdown()
-        self.server.server_close()
-        self.thread.join(timeout=5)
-
-    def _post(
-        self, path: str, body: bytes, headers: dict[str, str] | None = None
-    ) -> tuple[int, dict[str, object]]:
-        req = urllib.request.Request(
-            f"http://127.0.0.1:{self.port}{path}", data=body, method="POST",
-            headers=headers or {},
-        )
-        with urllib.request.urlopen(req, timeout=5) as resp:
-            return resp.status, json.loads(resp.read())
-
-    def _get(self, path: str) -> tuple[int, dict[str, object]]:
-        with urllib.request.urlopen(f"http://127.0.0.1:{self.port}{path}", timeout=5) as r:
-            return r.status, json.loads(r.read())
-
-    def test_webhook_dispatches(self):
-        self._serve()
-        body = json.dumps(_ISSUE_ASSIGNED).encode()
-        status, payload = self._post("/webhook", body, {"X-Gitea-Event": "issues"})
-        self.assertEqual(200, status)
-        self.assertTrue(payload["handled"])
-        self.assertEqual(1, len(self.orch.events))
-
-    def test_unhandled_event_ok_but_not_handled(self):
-        self._serve()
-        body = json.dumps({"action": "push"}).encode()
-        _status, payload = self._post("/webhook", body, {"X-Gitea-Event": "push"})
-        self.assertFalse(payload["handled"])
-        self.assertEqual([], self.orch.events)
-
-    def test_invalid_json_400(self):
-        self._serve()
-        with self.assertRaises(HTTPError) as ctx:
-            self._post("/webhook", b"{not json", {"X-Gitea-Event": "issues"})
-        self.assertEqual(400, ctx.exception.code)
-
-    def test_bad_signature_rejected(self):
-        self._serve(secret=b"sekret")
-        body = json.dumps(_ISSUE_ASSIGNED).encode()
-        with self.assertRaises(HTTPError) as ctx:
-            self._post("/webhook", body,
-                       {"X-Gitea-Event": "issues", "X-Gitea-Signature": "deadbeef"})
-        self.assertEqual(401, ctx.exception.code)
-        self.assertEqual([], self.orch.events)
-
-    def test_good_signature_accepted(self):
-        self._serve(secret=b"sekret")
-        body = json.dumps(_ISSUE_ASSIGNED).encode()
-        sig = hmac.new(b"sekret", body, hashlib.sha256).hexdigest()
-        status, _payload = self._post(
-            "/webhook", body, {"X-Gitea-Event": "issues", "X-Gitea-Signature": sig})
-        self.assertEqual(200, status)
-        self.assertEqual(1, len(self.orch.events))
-
-    def test_healthz(self):
-        self._serve()
-        self.assertEqual(200, self._get("/healthz")[0])
-
-    def test_unknown_path_404(self):
-        self._serve()
-        with self.assertRaises(HTTPError) as ctx:
-            self._post("/nope", b"{}", {"X-Gitea-Event": "issues"})
-        self.assertEqual(404, ctx.exception.code)
-
-    def test_provenance_returns_record_and_ops(self):
-        store = InMemoryStateStore()
-        store.upsert(RunRecord(owner="didericis", repo="bot-bottle", issue_number=17,
-                               slug="impl-17", agent_name="impl", bottle_names=["claude"]))
-
-        def reader(rec: object) -> list[dict[str, object]]:  # pylint: disable=unused-argument
-            return [{"at": "T", "op": "post_comment", "target": 17, "detail": "ok"}]
-
-        self._serve(store=store, op_log_reader=reader)
-        status, payload = self._get("/provenance?owner=didericis&repo=bot-bottle&issue=17")
-        self.assertEqual(200, status)
-        self.assertEqual("impl-17", payload["slug"])
-        self.assertEqual(1, len(payload["ops"]))  # type: ignore[arg-type]
-
-    def test_provenance_missing_params_400(self):
-        self._serve()
-        with self.assertRaises(HTTPError) as ctx:
-            self._get("/provenance?owner=didericis")
-        self.assertEqual(400, ctx.exception.code)
-
-    def test_provenance_unknown_run_404(self):
-        self._serve()
-        with self.assertRaises(HTTPError) as ctx:
-            self._get("/provenance?owner=x&repo=y&issue=1")
-        self.assertEqual(404, ctx.exception.code)
-
-    def test_unknown_get_path_404(self):
-        self._serve()
-        with self.assertRaises(HTTPError) as ctx:
-            self._get("/nope")
-        self.assertEqual(404, ctx.exception.code)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/test_agent_provider.py

@@ -9,15 +9,11 @@ import unittest
 from pathlib import Path
 
 from bot_bottle.agent_provider import (
-    CLAUDE_HOST_CREDENTIAL_HOSTS,
     CODEX_HOST_CREDENTIAL_HOSTS,
     build_agent_provision_plan,
     prompt_args,
 )
-from bot_bottle.egress import (
-    CLAUDE_HOST_CREDENTIAL_TOKEN_REF,
-    CODEX_HOST_CREDENTIAL_TOKEN_REF,
-)
+from bot_bottle.egress import CODEX_HOST_CREDENTIAL_TOKEN_REF
 
 
 def _jwt(exp: int) -> str:
@@ -293,67 +289,6 @@ class TestAgentProviderRuntime(unittest.TestCase):
             )
         self.assertEqual({}, plan.provisioned_env)
 
-    def test_claude_forward_host_credentials_populates_egress_route(self):
-        access_token = "sk-ant-oat01-test-key"
-        with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
-            home = Path(tmp) / "host-claude"
-            cred_dir = home / ".claude"
-            cred_dir.mkdir(parents=True)
-            (cred_dir / ".credentials.json").write_text(json.dumps({
-                "claudeAiOauth": {"accessToken": access_token},
-            }))
-            plan = build_agent_provision_plan(
-                template="claude",
-                dockerfile="",
-                state_dir=Path(tmp),
-                instance_name="bot-bottle-test",
-                prompt_file=Path(tmp) / "prompt.txt",
-                forward_host_credentials=True,
-                host_env={"HOME": str(home)},
-            )
-        self.assertEqual(1, len(plan.egress_routes))
-        route = plan.egress_routes[0]
-        self.assertIn(route.host, CLAUDE_HOST_CREDENTIAL_HOSTS)
-        self.assertEqual("Bearer", route.auth_scheme)
-        self.assertEqual(CLAUDE_HOST_CREDENTIAL_TOKEN_REF, route.token_ref)
-        self.assertEqual("egress-placeholder", plan.env_vars["CLAUDE_CODE_OAUTH_TOKEN"])
-        self.assertEqual(frozenset({"CLAUDE_CODE_OAUTH_TOKEN"}), plan.hidden_env_names)
-
-    def test_claude_forward_host_credentials_populates_provisioned_env(self):
-        access_token = "sk-ant-oat01-test-key"
-        with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
-            home = Path(tmp) / "host-claude"
-            cred_dir = home / ".claude"
-            cred_dir.mkdir(parents=True)
-            (cred_dir / ".credentials.json").write_text(json.dumps({
-                "claudeAiOauth": {"accessToken": access_token},
-            }))
-            plan = build_agent_provision_plan(
-                template="claude",
-                dockerfile="",
-                state_dir=Path(tmp),
-                instance_name="bot-bottle-test",
-                prompt_file=Path(tmp) / "prompt.txt",
-                forward_host_credentials=True,
-                host_env={"HOME": str(home)},
-            )
-        self.assertEqual(
-            {CLAUDE_HOST_CREDENTIAL_TOKEN_REF: access_token},
-            plan.provisioned_env,
-        )
-
-    def test_claude_without_forward_host_credentials_has_empty_provisioned_env(self):
-        with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
-            plan = build_agent_provision_plan(
-                template="claude",
-                dockerfile="",
-                state_dir=Path(tmp),
-                instance_name="bot-bottle-test",
-                prompt_file=Path(tmp) / "prompt.txt",
-                forward_host_credentials=False,
-            )
-        self.assertEqual({}, plan.provisioned_env)
-
     def test_pi_plan_writes_default_ollama_models(self):
         with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
             plan = build_agent_provision_plan(

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

@@ -56,7 +56,7 @@ class TestCmdStartHeadless(unittest.TestCase):
             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()
         # No bottles running by default → no label collision.
         patch(

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

@@ -1,187 +0,0 @@
-"""Unit: host Claude auth extraction."""
-
-from __future__ import annotations
-
-import json
-import subprocess
-import tempfile
-import unittest
-from datetime import datetime, timezone
-from pathlib import Path
-from unittest.mock import MagicMock, patch
-
-from bot_bottle.contrib.claude.claude_auth import (
-    claude_auth_path,
-    claude_host_access_token,
-)
-from bot_bottle.log import Die
-
-
-def _cred_json(access_token: str, **extra) -> str:  # type: ignore[no-untyped-def]
-    payload: dict = {"claudeAiOauth": {"accessToken": access_token, **extra}}
-    return json.dumps(payload)
-
-
-class TestClaudeHostAccessToken(unittest.TestCase):
-    def setUp(self):
-        self.tmp = tempfile.TemporaryDirectory(prefix="bb-claude-auth.")
-        self.home = Path(self.tmp.name)
-        self.cred_dir = self.home / ".claude"
-        self.cred_dir.mkdir()
-        self.auth_path = self.cred_dir / ".credentials.json"
-
-    def tearDown(self):
-        self.tmp.cleanup()
-
-    def _write(self, payload: dict) -> None:  # type: ignore[no-untyped-def]
-        self.auth_path.write_text(json.dumps(payload))
-
-    def test_auth_path_uses_home_env(self):
-        self.assertEqual(
-            self.auth_path,
-            claude_auth_path({"HOME": str(self.home)}),
-        )
-
-    # --- file-based (Linux) ---
-
-    def test_file_returns_access_token(self):
-        key = "sk-ant-oat01-real-key"
-        self._write({"claudeAiOauth": {"accessToken": key}})
-        out = claude_host_access_token({"HOME": str(self.home)})
-        self.assertEqual(key, out)
-
-    def test_file_missing_claude_ai_oauth_dies(self):
-        self._write({"hasCompletedOnboarding": True})
-        with self.assertRaises(Die):
-            claude_host_access_token({"HOME": str(self.home)})
-
-    def test_file_missing_access_token_dies(self):
-        self._write({"claudeAiOauth": {"expiresAt": 2000000000000}})
-        with self.assertRaises(Die):
-            claude_host_access_token({"HOME": str(self.home)})
-
-    def test_file_empty_access_token_dies(self):
-        self._write({"claudeAiOauth": {"accessToken": ""}})
-        with self.assertRaises(Die):
-            claude_host_access_token({"HOME": str(self.home)})
-
-    def test_file_expired_token_dies(self):
-        # expiresAt is milliseconds; 1_000_000 ms is year 1970
-        self._write({
-            "claudeAiOauth": {"accessToken": "sk-ant-oat01-x", "expiresAt": 1_000_000},
-        })
-        with self.assertRaises(Die):
-            claude_host_access_token(
-                {"HOME": str(self.home)},
-                now=datetime(2026, 1, 1, tzinfo=timezone.utc),
-            )
-
-    def test_file_future_expiry_is_accepted(self):
-        key = "sk-ant-oat01-y"
-        # 2_000_000_000_000 ms ≈ year 2033
-        self._write({
-            "claudeAiOauth": {"accessToken": key, "expiresAt": 2_000_000_000_000},
-        })
-        out = claude_host_access_token(
-            {"HOME": str(self.home)},
-            now=datetime(2026, 1, 1, tzinfo=timezone.utc),
-        )
-        self.assertEqual(key, out)
-
-    def test_file_absent_expiry_is_accepted(self):
-        key = "sk-ant-oat01-z"
-        self._write({"claudeAiOauth": {"accessToken": key}})
-        out = claude_host_access_token({"HOME": str(self.home)})
-        self.assertEqual(key, out)
-
-    def test_file_non_json_dies(self):
-        self.auth_path.write_text("not json {{{")
-        with self.assertRaises(Die):
-            claude_host_access_token({"HOME": str(self.home)})
-
-    def test_file_json_array_root_dies(self):
-        self.auth_path.write_text("[]")
-        with self.assertRaises(Die):
-            claude_host_access_token({"HOME": str(self.home)})
-
-    def test_file_extra_fields_are_ignored(self):
-        key = "sk-ant-oat01-real"
-        self._write({
-            "claudeAiOauth": {
-                "accessToken": key,
-                "refreshToken": "sk-ant-ort01-secret",
-                "scopes": ["user:inference"],
-                "expiresAt": 2_000_000_000_000,
-            },
-        })
-        out = claude_host_access_token({"HOME": str(self.home)})
-        self.assertEqual(key, out)
-
-    # --- macOS Keychain fallback ---
-
-    def _home_without_creds(self) -> Path:
-        """A home dir that has .claude/ but no .credentials.json."""
-        empty = self.home / "no-creds"
-        (empty / ".claude").mkdir(parents=True)
-        return empty
-
-    def _mock_keychain(self, stdout: str, returncode: int = 0) -> MagicMock:
-        mock = MagicMock()
-        mock.returncode = returncode
-        mock.stdout = stdout
-        return mock
-
-    def test_keychain_used_when_file_absent(self):
-        key = "sk-ant-oat01-keychain"
-        home = self._home_without_creds()
-        with patch(
-            "bot_bottle.contrib.claude.claude_auth.subprocess.run",
-            return_value=self._mock_keychain(_cred_json(key)),
-        ), patch(
-            "bot_bottle.contrib.claude.claude_auth.sys.platform", "darwin",
-        ):
-            out = claude_host_access_token({"HOME": str(home)})
-        self.assertEqual(key, out)
-
-    def test_keychain_failure_when_file_absent_dies(self):
-        home = self._home_without_creds()
-        with patch(
-            "bot_bottle.contrib.claude.claude_auth.subprocess.run",
-            return_value=self._mock_keychain("", returncode=44),
-        ), patch(
-            "bot_bottle.contrib.claude.claude_auth.sys.platform", "darwin",
-        ):
-            with self.assertRaises(Die):
-                claude_host_access_token({"HOME": str(home)})
-
-    def test_no_file_no_keychain_on_linux_dies(self):
-        home = self._home_without_creds()
-        with patch("bot_bottle.contrib.claude.claude_auth.sys.platform", "linux"):
-            with self.assertRaises(Die):
-                claude_host_access_token({"HOME": str(home)})
-
-    def test_keychain_non_json_dies(self):
-        home = self._home_without_creds()
-        with patch(
-            "bot_bottle.contrib.claude.claude_auth.subprocess.run",
-            return_value=self._mock_keychain("not-json"),
-        ), patch(
-            "bot_bottle.contrib.claude.claude_auth.sys.platform", "darwin",
-        ):
-            with self.assertRaises(Die):
-                claude_host_access_token({"HOME": str(home)})
-
-    def test_keychain_security_not_found_dies(self):
-        home = self._home_without_creds()
-        with patch(
-            "bot_bottle.contrib.claude.claude_auth.subprocess.run",
-            side_effect=FileNotFoundError,
-        ), patch(
-            "bot_bottle.contrib.claude.claude_auth.sys.platform", "darwin",
-        ):
-            with self.assertRaises(Die):
-                claude_host_access_token({"HOME": str(home)})
-
-
-if __name__ == "__main__":
-    unittest.main()

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,

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,

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

@@ -1,152 +1,144 @@
-"""Unit: GiteaClient and GiteaForge (urllib mocked — no network)."""
+"""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="http://g/api/v1", owner="o", repo="r", token="tok")
+    return GiteaClient(
+        api_url="https://gitea.example.com/api/v1",
+        owner="didericis",
+        repo="bot-bottle",
+        token="test-token",
+    )
 
 
-def _mock_response(body: bytes) -> MagicMock:
+def _resp(body: object, status: int = 200) -> MagicMock:
     resp = MagicMock()
-    resp.read.return_value = body
-    resp.__enter__.return_value = resp
-    resp.__exit__.return_value = False
+    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
 
 
-class GiteaClientTest(unittest.TestCase):
-    # pylint: disable=protected-access
-    def setUp(self):
-        self.client = _client()
-
-    def test_request_returns_parsed_json(self):
-        payload = {"number": 42}
-        resp = _mock_response(json.dumps(payload).encode())
-        with patch("urllib.request.urlopen", return_value=resp):
-            result = self.client._request("GET", "/repos/o/r/issues/42")
-        self.assertEqual(payload, result)
-
-    def test_request_empty_body_returns_none(self):
-        resp = _mock_response(b"")
-        with patch("urllib.request.urlopen", return_value=resp):
-            result = self.client._request("POST", "/some/path", {"x": 1})
-        self.assertIsNone(result)
-
-    def test_is_org_member_true_on_200(self):
-        mock_resp = MagicMock()
-        mock_resp.close = MagicMock()
-        with patch("urllib.request.urlopen", return_value=mock_resp):
-            self.assertTrue(self.client.is_org_member("myorg", "alice"))
-
-    def test_is_org_member_false_on_http_error(self):
-        err = urllib.error.HTTPError("url", 404, "Not Found", None, None)  # type: ignore[arg-type]
-        with patch("urllib.request.urlopen", side_effect=err):
-            self.assertFalse(self.client.is_org_member("myorg", "nobody"))
-
-    def test_get_issue(self):
-        resp = _mock_response(json.dumps({"number": 1}).encode())
-        with patch("urllib.request.urlopen", return_value=resp):
-            result = self.client.get_issue(1)
-        self.assertEqual(1, result["number"])
-
-    def test_get_pull(self):
-        resp = _mock_response(json.dumps({"number": 7, "merged": False}).encode())
-        with patch("urllib.request.urlopen", return_value=resp):
-            result = self.client.get_pull(7)
-        self.assertEqual(7, result["number"])
-
-    def test_list_comments(self):
-        resp = _mock_response(json.dumps([{"id": 1, "body": "hi"}]).encode())
-        with patch("urllib.request.urlopen", return_value=resp):
-            result = self.client.list_comments(1)
-        self.assertEqual(1, len(result))
-        self.assertEqual(1, result[0]["id"])
-
-    def test_create_comment(self):
-        resp = _mock_response(b"")
-        with patch("urllib.request.urlopen", return_value=resp) as mock_open:
-            self.client.create_comment(1, "hello")
-        mock_open.assert_called_once()
-
-    def test_update_issue(self):
-        resp = _mock_response(b"")
-        with patch("urllib.request.urlopen", return_value=resp) as mock_open:
-            self.client.update_issue(1, "new body")
-        mock_open.assert_called_once()
-
-    def test_request_builds_correct_url(self):
-        import urllib.request as ureq
-        captured: list[ureq.Request] = []
-
-        def fake_urlopen(req: ureq.Request, timeout: float) -> MagicMock:  # pylint: disable=unused-argument
-            captured.append(req)
-            return _mock_response(b"{}")
-
-        with patch("urllib.request.urlopen", side_effect=fake_urlopen):
-            self.client.get_issue(5)
-
-        self.assertIn("/issues/5", captured[0].full_url)
-
-    def test_request_sends_auth_header(self):
-        import urllib.request as ureq
-        captured: list[ureq.Request] = []
-
-        def fake_urlopen(req: ureq.Request, timeout: float) -> MagicMock:  # pylint: disable=unused-argument
-            captured.append(req)
-            return _mock_response(b"{}")
-
-        with patch("urllib.request.urlopen", side_effect=fake_urlopen):
-            self.client.get_issue(1)
-
-        self.assertEqual("token tok", captured[0].get_header("Authorization"))
+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()),
+    )
 
 
-class GiteaForgeTest(unittest.TestCase):
-    def setUp(self):
-        self.client = MagicMock(spec=GiteaClient)
-        self.forge = GiteaForge(self.client)
+_URLOPEN = "bot_bottle.contrib.gitea.client.urllib.request.urlopen"
 
-    def test_is_org_member_delegates(self):
-        self.client.is_org_member.return_value = True
-        self.assertTrue(self.forge.is_org_member("org", "alice"))
-        self.client.is_org_member.assert_called_once_with("org", "alice")
 
-    def test_is_org_member_false(self):
-        self.client.is_org_member.return_value = False
-        self.assertFalse(self.forge.is_org_member("org", "outsider"))
+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_read_issue_delegates(self):
-        self.client.get_issue.return_value = {"number": 3}
-        self.assertEqual({"number": 3}, self.forge.read_issue(3))
-        self.client.get_issue.assert_called_once_with(3)
+    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_read_pr_delegates(self):
-        self.client.get_pull.return_value = {"number": 5, "merged": False}
-        result = self.forge.read_pr(5)
-        self.assertEqual(5, result["number"])
-        self.client.get_pull.assert_called_once_with(5)
+    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))
 
-    def test_read_comments_delegates(self):
-        self.client.list_comments.return_value = [{"id": 1}]
-        comments = self.forge.read_comments(1)
-        self.assertEqual([{"id": 1}], comments)
-        self.client.list_comments.assert_called_once_with(1)
 
-    def test_post_comment_delegates(self):
-        self.forge.post_comment(1, "looks good")
-        self.client.create_comment.assert_called_once_with(1, "looks good")
+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_update_description_delegates(self):
-        self.forge.update_description(1, "updated body")
-        self.client.update_issue.assert_called_once_with(1, "updated body")
+    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__":

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_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

@@ -210,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)

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

@@ -80,19 +80,11 @@ class TestAgentProviderHostCredentials(unittest.TestCase):
                 "forward_host_credentials": "yes",
             })
 
-    def test_forward_host_credentials_allowed_for_claude(self):
-        b = _provider_config_bottle({
-            "template": "claude",
-            "forward_host_credentials": True,
-        })
-        self.assertTrue(b.agent_provider.forward_host_credentials)
-
-    def test_forward_host_credentials_and_auth_token_rejected_together(self):
+    def test_forward_host_credentials_rejected_for_claude(self):
         with self.assertRaises(ManifestError):
             _provider_config_bottle({
                 "template": "claude",
                 "forward_host_credentials": True,
-                "auth_token": "SOME_TOKEN",
             })
 
     def test_auth_token_defaults_empty(self):

tests/unit/test_manifest_validation.py

@@ -82,22 +82,10 @@ class TestAgentProviderValidation(unittest.TestCase):
                 "b", {"forward_host_credentials": True, "template": "weird"}
             )
 
-    def test_forward_creds_pi_template_rejected(self) -> None:
+    def test_forward_creds_non_codex_template(self) -> None:
         with self.assertRaises(ManifestError):
             ManifestAgentProvider.from_dict(
-                "b", {"forward_host_credentials": True, "template": "pi"}
-            )
-
-    def test_forward_creds_claude_allowed(self) -> None:
-        p = ManifestAgentProvider.from_dict(
-            "b", {"forward_host_credentials": True, "template": "claude"}
-        )
-        self.assertTrue(p.forward_host_credentials)
-
-    def test_forward_creds_and_auth_token_rejected(self) -> None:
-        with self.assertRaises(ManifestError):
-            ManifestAgentProvider.from_dict(
-                "b", {"forward_host_credentials": True, "auth_token": "T", "template": "claude"}
+                "b", {"forward_host_credentials": True, "template": "claude"}
             )
 
     def test_valid_claude_auth_token(self) -> None:

tests/unit/test_smolmachines_provision.py

@@ -130,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,
@@ -422,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(