fix(backend): fix pyright errors in lazy-load implementation

- Rename _BACKENDS → _backends: pyright treats uppercase module-level
  names as constants and flags the reassignment in _get_backends() as
  reportConstantRedefinition; lowercase avoids this.
- Add TYPE_CHECKING guard importing CommitCancelled/Freezer/get_freezer
  from .freeze: pyright cannot see module-level __getattr__ bindings, so
  reportUnsupportedDunderAll fired for those three __all__ entries; the
  guard makes them visible to the type checker without running at import
  time.
- Update test_backend_selection.py to patch _backends (lowercase).

.gitea/workflows/test.yml

@@ -34,13 +34,13 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      # No actions/setup-python: the runner image already ships Python 3.12,
-      # and older act_runner engines mishandle setup-python's PATH (coverage
-      # lands in one interpreter, `python3` resolves to another). Install
-      # straight into the ephemeral job container's system Python —
-      # --break-system-packages is safe because the container is disposable.
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
       - name: Install dev requirements
-        run: python3 -m pip install --break-system-packages -r requirements-dev.txt
+        run: python3 -m pip install -r requirements-dev.txt
 
       - name: Run unit tests
         run: python3 -m coverage run -m unittest discover -t . -s tests/unit -v
@@ -54,8 +54,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      # No actions/setup-python (see the note in the `unit` job); the
-      # container's system Python 3.12 runs the stdlib test suite directly.
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
       - name: Show environment
         run: |
           python3 --version
@@ -85,13 +88,13 @@ jobs:
         with:
           fetch-depth: 0
 
-      # No actions/setup-python: the runner image already ships Python 3.12,
-      # and older act_runner engines mishandle setup-python's PATH (coverage
-      # lands in one interpreter, `python3` resolves to another). Install
-      # straight into the ephemeral job container's system Python —
-      # --break-system-packages is safe because the container is disposable.
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
       - name: Install dev requirements
-        run: python3 -m pip install --break-system-packages -r requirements-dev.txt
+        run: python3 -m pip install -r requirements-dev.txt
 
       - name: Combined coverage report (unit + integration)
         run: PYTHON=python3 bash scripts/coverage.sh critical

Dockerfile.gateway

@@ -16,12 +16,10 @@
 # Layout:
 #
 #   /usr/bin/gitleaks                    gitleaks binary
-#   /app/egress_addon.py                 mitmproxy addon entry point
+#   /app/egress_addon.py + siblings      mitmproxy addon (egress)
 #   /app/egress-entrypoint.sh            mitmdump launcher
-#   /usr/local/lib/python*/bot_bottle/   installed package (all daemons + shared modules)
-#   /app/egress_addon.py                 one-line shim: re-exports addons from package
-#                                        (mitmdump -s requires a file path, not a module)
-#   /etc/egress/routes.yaml              bind-mounted at run time
+#   /app/supervise_server.py + .py       supervise MCP server
+#   /app/gateway_init.py                 PID 1 supervisor
 #   /etc/git-gate/pre-receive            docker-cp'd at start time
 #   /git-gate-entrypoint.sh              docker-cp'd at start time
 #   /git-gate/creds/*                    docker-cp'd at start time
@@ -89,16 +87,27 @@ RUN arch="${TARGETARCH:-$(dpkg --print-architecture)}" \
  && tar -xzf /tmp/gitleaks.tar.gz -C /usr/bin gitleaks \
  && rm /tmp/gitleaks.tar.gz
 
-# Install bot_bottle as a proper package so entry-point scripts can use
-# `from bot_bottle.X import Y` absolute imports. A rename or a missing
-# module is caught at pip-install time — not at container runtime.
-COPY pyproject.toml /src/
-COPY bot_bottle/    /src/bot_bottle/
-RUN pip install --no-cache-dir /src/
-
-# mitmdump -s requires a file path, not a module. Write a one-line shim that
-# re-exports `addons` from the installed package; mitmdump finds it there.
-RUN printf 'from bot_bottle.egress_addon import addons\n' > /app/egress_addon.py
+# Project Python: addon + server modules + the init supervisor.
+# Kept flat under /app/ so mitmdump's loader resolves them as
+# top-level siblings (absolute imports), matching the prior
+# Dockerfile.egress / Dockerfile.supervise layout.
+COPY bot_bottle/egress_addon_core.py /app/egress_addon_core.py
+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/policy_resolver.py   /app/policy_resolver.py
+COPY bot_bottle/dlp_detectors.py     /app/dlp_detectors.py
+COPY bot_bottle/yaml_subset.py       /app/yaml_subset.py
+COPY bot_bottle/paths.py             /app/paths.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/gateway_init.py      /app/gateway_init.py
+COPY bot_bottle/git_http_backend.py  /app/git_http_backend.py
 COPY bot_bottle/egress_entrypoint.sh /app/egress-entrypoint.sh
 RUN chmod +x /app/egress-entrypoint.sh
 
@@ -117,8 +126,10 @@ RUN mkdir -p \
 # subset the bottle uses.
 EXPOSE 8888 9099 9418 9420 9100
 
+# WORKDIR matches Dockerfile.supervise's prior layout so the
+# in-app same-dir import in supervise_server.py stays deterministic.
 WORKDIR /app
 
 # PID 1 is the supervisor. It owns signal handling and exit-code
 # propagation; no `exec` chain in the entrypoint itself.
-ENTRYPOINT ["python3", "-m", "bot_bottle.gateway_init"]
+ENTRYPOINT ["python3", "/app/gateway_init.py"]

bot_bottle/constants.py

@@ -1,17 +0,0 @@
-"""Shared wire-protocol constants for gateway-bundled modules.
-
-Single source of truth for values that appear across the egress addon,
-git-http backend, supervise server, and git-gate renderer. Importing
-from this module instead of duplicating the literals means a rename is
-a one-line change and is caught by the type checker at the import site."""
-
-# App-layer identity token header. Delivered as proxy credentials
-# (HTTPS_PROXY=http://<bottle_id>:<token>@gw) by launch; the egress
-# addon reads and strips it, the supervise server and git-http backend
-# read it for attribution, and none of them forward it upstream.
-IDENTITY_HEADER = "x-bot-bottle-identity"
-
-# Shared timeout (seconds) for all git-gate subprocess and CGI calls:
-# git daemon (--timeout/--init-timeout), the access-hook subprocess in
-# git_http_backend, and the git http-backend CGI subprocess.
-GIT_GATE_TIMEOUT_SECS = 15

bot_bottle/dlp_detectors.py

@@ -3,8 +3,9 @@
 Pure Python, no mitmproxy dependency. Each detector is a module-level
 function returning `ScanResult | None`.
 
-Available in the gateway via the installed `bot_bottle` package
-(see `Dockerfile.gateway`).
+Ships flat into the gateway image alongside
+`egress_addon_core.py` — both this file and the package source use
+the same try/except import shim pattern.
 """
 
 from __future__ import annotations
@@ -19,7 +20,10 @@ from math import log2
 from collections import Counter
 from urllib.parse import quote as url_quote
 
-from .egress_addon_core import ScanResult
+try:
+    from egress_addon_core import ScanResult  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover - host-side path
+    from .egress_addon_core import ScanResult
 
 
 # ---------------------------------------------------------------------------

bot_bottle/egress_addon.py

@@ -15,9 +15,7 @@ import typing
 
 from mitmproxy import http  # type: ignore[import-not-found]  # pylint: disable=import-error
 
-from bot_bottle.constants import IDENTITY_HEADER
-from bot_bottle.dlp_detectors import redact_tokens, strip_crlf
-from bot_bottle.egress_addon_core import (
+from egress_addon_core import (  # type: ignore[import-not-found]  # pylint: disable=import-error
     LOG_BLOCKS,
     LOG_FULL,
     DEFAULT_OUTBOUND_ON_MATCH,
@@ -40,8 +38,24 @@ from bot_bottle.egress_addon_core import (
     scan_inbound,
     scan_outbound,
 )
-from bot_bottle import supervise as _sv
-from bot_bottle.policy_resolver import PolicyResolver
+
+try:
+    from dlp_detectors import redact_tokens, strip_crlf  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover - host-side path
+    from bot_bottle.dlp_detectors import (  # type: ignore[import-not-found]
+        redact_tokens,
+        strip_crlf,
+    )
+
+try:
+    import supervise as _sv  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover - host-side path
+    from bot_bottle import supervise as _sv  # type: ignore[import-not-found]
+
+try:
+    from policy_resolver import PolicyResolver  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover - host-side path
+    from bot_bottle.policy_resolver import PolicyResolver
 
 
 INTROSPECT_HOST = "_egress.local"
@@ -52,6 +66,13 @@ INTROSPECT_HOST = "_egress.local"
 # back to — so an unset value is a fatal misconfiguration (see __init__).
 ORCHESTRATOR_URL_ENV = "BOT_BOTTLE_ORCHESTRATOR_URL"
 
+# App-layer identity token. Delivered as proxy credentials
+# (`HTTPS_PROXY=http://<bottle_id>:<token>@gw`): clients honor it as part of
+# the proxy protocol without app changes, and the addon reads + strips it so
+# it never leaks upstream. The legacy `x-bot-bottle-identity` request header
+# is still stripped defensively (git-http uses that header on its own port).
+IDENTITY_HEADER = "x-bot-bottle-identity"
+
 # Per-flow key under which `request()` stashes the resolved (Config, supervise
 # slug, env) so the later `response()` and `websocket_message()` hooks scan
 # against the *calling bottle's* policy — the same one the request was decided

bot_bottle/egress_addon_core.py

@@ -6,9 +6,9 @@ exercise the parse + decision functions without depending on the
 `mitmproxy.http.HTTPFlow` API and is loaded inside the gateway
 container.
 
-Imports: stdlib + sibling package modules (`yaml_subset`,
-`egress_dlp_config`). Available in the gateway via the installed
-`bot_bottle` package (see `Dockerfile.gateway`)."""
+Imports: stdlib + `yaml_subset` (which is itself stdlib-only and
+ships flat into the gateway image alongside this file —
+see `Dockerfile.gateway`)."""
 
 from __future__ import annotations
 
@@ -16,20 +16,36 @@ import re
 import typing
 from dataclasses import dataclass
 
-from .yaml_subset import YamlSubsetError, parse_yaml_subset
+try:
+    from yaml_subset import YamlSubsetError, parse_yaml_subset  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover - host-side path
+    from .yaml_subset import YamlSubsetError, parse_yaml_subset
 
-# DLP detector-config parsing lives in a sibling module. Re-exported below
-# so existing `from egress_addon_core import ON_MATCH_*` callers keep working.
-from .egress_dlp_config import (
-    DEFAULT_OUTBOUND_ON_MATCH,
-    INBOUND_DETECTOR_NAMES,
-    ON_MATCH_BLOCK,
-    ON_MATCH_REDACT,
-    ON_MATCH_SUPERVISE,
-    OUTBOUND_DETECTOR_NAMES,
-    OUTBOUND_ON_MATCH_VALUES,
-    parse_dlp_block,
-)
+# DLP detector-config parsing lives in a sibling module (also flat-bundled
+# into the gateway — see Dockerfile.gateway). Re-exported below so existing
+# `from egress_addon_core import ON_MATCH_*` callers keep working.
+try:
+    from egress_dlp_config import (  # type: ignore[import-not-found]
+        DEFAULT_OUTBOUND_ON_MATCH,
+        INBOUND_DETECTOR_NAMES,
+        ON_MATCH_BLOCK,
+        ON_MATCH_REDACT,
+        ON_MATCH_SUPERVISE,
+        OUTBOUND_DETECTOR_NAMES,
+        OUTBOUND_ON_MATCH_VALUES,
+        parse_dlp_block,
+    )
+except ImportError:  # pragma: no cover - host-side path
+    from .egress_dlp_config import (
+        DEFAULT_OUTBOUND_ON_MATCH,
+        INBOUND_DETECTOR_NAMES,
+        ON_MATCH_BLOCK,
+        ON_MATCH_REDACT,
+        ON_MATCH_SUPERVISE,
+        OUTBOUND_DETECTOR_NAMES,
+        OUTBOUND_ON_MATCH_VALUES,
+        parse_dlp_block,
+    )
 
 
 # ---------------------------------------------------------------------------

bot_bottle/gateway_init.py

@@ -78,8 +78,8 @@ def _env_for_daemon(name: str, base_env: dict[str, str]) -> dict[str, str]:
 _DAEMONS: tuple[_DaemonSpec, ...] = (
     _DaemonSpec("egress", ("/bin/sh", "/app/egress-entrypoint.sh")),
     _DaemonSpec("git-gate", ("/bin/sh", "/git-gate-entrypoint.sh")),
-    _DaemonSpec("git-http", ("python3", "-m", "bot_bottle.git_http_backend")),
-    _DaemonSpec("supervise", ("python3", "-m", "bot_bottle.supervise_server")),
+    _DaemonSpec("git-http", ("python3", "/app/git_http_backend.py")),
+    _DaemonSpec("supervise", ("python3", "/app/supervise_server.py")),
 )
 
 

bot_bottle/git_gate_render.py

@@ -14,12 +14,18 @@ import shlex
 from dataclasses import dataclass
 from pathlib import Path
 
-from .constants import GIT_GATE_TIMEOUT_SECS, IDENTITY_HEADER
 from .manifest import ManifestBottle, ManifestGitEntry
 
 # Short network alias for git-gate inside the gateway. The
 # agent's `.gitconfig` insteadOf rewrites resolve through this name.
 GIT_GATE_HOSTNAME = "git-gate"
+# App-layer identity token header the agent's git sends to git-http and the
+# gateway validates (mirrors egress_addon / git_http_backend IDENTITY_HEADER).
+IDENTITY_HEADER = "x-bot-bottle-identity"
+# Shared timeout (seconds) for all git-gate subprocess and CGI calls:
+# git daemon (--timeout/--init-timeout), the access-hook subprocess in
+# git_http_backend, and the git http-backend CGI subprocess.
+GIT_GATE_TIMEOUT_SECS = 15
 
 
 @dataclass(frozen=True)

bot_bottle/git_http_backend.py

@@ -26,8 +26,16 @@ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 from urllib.parse import urlsplit
 
-from bot_bottle.constants import GIT_GATE_TIMEOUT_SECS, IDENTITY_HEADER
-from bot_bottle.policy_resolver import PolicyResolveError, PolicyResolver
+# policy_resolver ships flat alongside this file in the gateway
+# image (see Dockerfile.gateway); the bot_bottle.* fallback is the
+# host-side / test path. Mirrors egress_addon's import shape.
+try:
+    from policy_resolver import (  # type: ignore[import-not-found]
+        PolicyResolveError,
+        PolicyResolver,
+    )
+except ImportError:  # pragma: no cover - host-side path
+    from bot_bottle.policy_resolver import PolicyResolveError, PolicyResolver
 
 
 DEFAULT_PORT = 9420
@@ -38,6 +46,12 @@ DEFAULT_PORT = 9420
 # repo-root fallback.
 ORCHESTRATOR_URL_ENV = "BOT_BOTTLE_ORCHESTRATOR_URL"
 
+# App-layer identity token (defense-in-depth over the source-IP invariant);
+# the agent injects it, the backend reads it for attribution and never
+# forwards it to `git http-backend`. Mirrors egress_addon.IDENTITY_HEADER
+# (duplicated, not imported: egress_addon pulls in mitmproxy).
+IDENTITY_HEADER = "x-bot-bottle-identity"
+
 # The base under which each bottle's `<bottle_id>` repo namespace is nested.
 DEFAULT_REPO_ROOT = "/git"
 
@@ -75,6 +89,13 @@ def resolve_sandbox_root(
         return None  # bottle_id tried to escape the root → deny
     return namespace
 
+# Mirrors git_gate_render.GIT_GATE_TIMEOUT_SECS. Duplicated rather than
+# imported: this module ships as a flat top-level sibling in the gateway
+# bundle image (see Dockerfile.gateway), not as part of the bot_bottle
+# package, so `bot_bottle.git_gate` and its dependency chain aren't
+# available at runtime.
+GIT_GATE_TIMEOUT_SECS = 15
+
 # Bound memory use while still allowing ordinary git push packfiles.
 MAX_BODY_BYTES = 100 * 1024 * 1024
 

bot_bottle/policy_resolver.py

@@ -22,7 +22,8 @@ closed too rather than silently serving stale or empty policy.
 
 The resolved value is the policy blob the orchestrator stores verbatim; the
 consumer parses it (e.g. the egress addon's `load_config`). This module is
-stdlib-only and free of bot-bottle imports.
+stdlib-only and free of bot-bottle imports so it can be COPYed flat into
+the gateway.
 """
 
 from __future__ import annotations

bot_bottle/supervise.py

@@ -37,22 +37,40 @@ from abc import ABC
 from dataclasses import dataclass
 from pathlib import Path
 
-from .supervise_types import (
-    ACTION_OPERATOR_EDIT,
-    AuditEntry,
-    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,
-)
+try:
+    from .supervise_types import (
+        ACTION_OPERATOR_EDIT,
+        AuditEntry,
+        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,
+    )
+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,
+        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,
+    )
 
 
 try:

bot_bottle/supervise_server.py

@@ -26,8 +26,9 @@ Speaks MCP over HTTP+JSON-RPC. Methods handled:
 
 Everything else returns JSON-RPC error -32601 (method not found).
 
-The Dockerfile copies this script to /app/supervise_server.py and installs
-the bot_bottle package so its `from bot_bottle.*` imports resolve.
+Stdlib-only. The Dockerfile copies this file + bot_bottle/supervise.py
+into the image; the server imports `supervise` for the queue / Proposal
+plumbing.
 """
 
 from __future__ import annotations
@@ -41,18 +42,29 @@ import time
 import typing
 from dataclasses import dataclass, replace
 
-from bot_bottle.constants import IDENTITY_HEADER
-from bot_bottle.egress_addon_core import (
-    LOG_OFF, load_config, resolve_client_context, route_to_yaml_dict,
-)
-from bot_bottle.policy_resolver import PolicyResolveError, PolicyResolver
-from bot_bottle import supervise as _sv
+try:
+    # Same-directory imports inside the bundle container; these files are
+    # COPYed flat under /app by Dockerfile.gateway.
+    from egress_addon_core import (
+        LOG_OFF, load_config, resolve_client_context, route_to_yaml_dict,
+    )
+    from policy_resolver import PolicyResolveError, PolicyResolver
+    import supervise as _sv
+except ModuleNotFoundError:
+    # Package imports for host-side tests and tooling.
+    from .egress_addon_core import (
+        LOG_OFF, load_config, resolve_client_context, route_to_yaml_dict,
+    )
+    from .policy_resolver import PolicyResolveError, PolicyResolver
+    from . import supervise as _sv
 
 
 # --- JSON-RPC / MCP plumbing ----------------------------------------------
 
 
 MCP_PROTOCOL_VERSION = "2024-11-05"
+# App-layer identity token header (mirrors egress_addon / git_http_backend).
+IDENTITY_HEADER = "x-bot-bottle-identity"
 SERVER_NAME = "bot-bottle-supervise"
 SERVER_VERSION = "0.1.0"
 

pyproject.toml

@@ -1,8 +0,0 @@
-[build-system]
-requires = ["setuptools>=68"]
-build-backend = "setuptools.backends.legacy:build"
-
-[project]
-name = "bot-bottle"
-version = "0.0.0"
-requires-python = ">=3.11"

tests/unit/test_egress_addon_log_redaction.py

@@ -18,7 +18,7 @@ from unittest.mock import patch
 
 
 # ---------------------------------------------------------------------------
-# mitmproxy stub — must run before importing egress_addon
+# Gateway-import shims — must run before importing egress_addon
 # ---------------------------------------------------------------------------
 
 def _ensure_shims() -> None:
@@ -32,6 +32,9 @@ def _ensure_shims() -> None:
         setattr(_mm, "http", _mh)
         sys.modules["mitmproxy"] = _mm
         sys.modules["mitmproxy.http"] = _mh
+    if "egress_addon_core" not in sys.modules:
+        import bot_bottle.egress_addon_core as _core
+        sys.modules["egress_addon_core"] = _core
 
 
 _ensure_shims()

tests/unit/test_egress_addon_request_flow.py

@@ -190,6 +190,9 @@ def _ensure_shims() -> None:
         setattr(mh, "Response", _Response)
     if not hasattr(mh, "HTTPFlow"):
         setattr(mh, "HTTPFlow", object)
+    if "egress_addon_core" not in sys.modules:
+        import bot_bottle.egress_addon_core as _core
+        sys.modules["egress_addon_core"] = _core
 
 
 _ensure_shims()

tests/unit/test_supervise_server.py

@@ -2,6 +2,7 @@
 
 import http.client
 import json
+import sys
 import tempfile
 import threading
 import time
@@ -12,9 +13,15 @@ from unittest.mock import patch
 
 from tests.unit import use_bottle_root
 
-from bot_bottle import supervise as _sv
-from bot_bottle import queue_store as _qs
-from bot_bottle import audit_store as _as
+
+# The server module loads `supervise` via same-directory import inside
+# the container (Dockerfile.supervise WORKDIRs into /app). For tests
+# we mirror that by injecting bot_bottle/ onto sys.path under the
+# bare name `supervise`.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent / "bot_bottle"))
+import supervise as _sv  # noqa: E402  # type: ignore
+import queue_store as _qs  # noqa: E402  # type: ignore
+import audit_store as _as  # noqa: E402  # type: ignore
 
 from bot_bottle import supervise_server  # noqa: E402
 from bot_bottle.supervise_server import (