agentgov-gateway 0.1.0__tar.gz

agentgov_gateway-0.1.0/.gitignore

@@ -0,0 +1,79 @@
+# ============================================================================
+# AgentGov top-level .gitignore
+# Per-subsystem gitignores live inside control-tower/, gateway/, cli/ if needed.
+# ============================================================================
+
+# ---- Secrets & environment ----
+.env
+.env.local
+.env.*.local
+.env.production
+!.env.example
+!.env.act.example
+*.pem
+*.key
+!signing_keys.example/*.pub
+
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+ENV/
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+.tox/
+
+# ---- Node / Next.js ----
+node_modules/
+.next/
+out/
+.vercel/
+.turbo/
+*.tsbuildinfo
+next-env.d.ts
+.pnpm-debug.log*
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-store/
+
+# ---- Supabase ----
+supabase/.branches/
+supabase/.temp/
+supabase/functions/*/deno.lock
+
+# ---- Gateway runtime state ----
+# The gateway keeps SQLite caches + disk-backed event queues in these paths.
+# They are ephemeral by design and must never be committed.
+gateway/.runtime/
+gateway/policy_cache.sqlite*
+gateway/event_queue/
+~/.agentgov/
+
+# ---- IDE / OS ----
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# ---- Local overrides ----
+*.local
+CLAUDE.local.md

agentgov_gateway-0.1.0/Dockerfile

@@ -0,0 +1,45 @@
+# Fly.io / self-host image for the AgentGov gateway.
+#
+# HARD RULE (§12.1): this container must NEVER run on a governed developer's
+# machine. `agentgov doctor` checks host fingerprint against known developer
+# machines and refuses.
+
+FROM python:3.12-slim AS build
+
+WORKDIR /app
+
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+RUN pip install --upgrade pip uv==0.4.20
+
+COPY pyproject.toml uv.lock* README.md /app/
+COPY agentgov_gateway /app/agentgov_gateway
+RUN uv sync --frozen 2>/dev/null || uv sync
+
+
+FROM python:3.12-slim AS run
+
+WORKDIR /app
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    AGENTGOV_ENV=production \
+    POLICY_CACHE_PATH=/app/.runtime/policy_cache.sqlite \
+    EVENT_QUEUE_DIR=/app/.runtime/event_queue
+
+COPY --from=build /app /app
+
+# Non-root user — the vault key never touches root's crash dumps.
+RUN useradd -u 10001 -r -s /usr/sbin/nologin gateway \
+    && mkdir -p /app/.runtime \
+    && chown -R gateway:gateway /app/.runtime
+USER gateway
+
+EXPOSE 8000 9090
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD python -c "import httpx; httpx.get('http://127.0.0.1:8000/health', timeout=3).raise_for_status()" || exit 1
+
+CMD ["/app/.venv/bin/uvicorn", "agentgov_gateway.main:app", "--host", "0.0.0.0", "--port", "8000"]

agentgov_gateway-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.5
+Name: agentgov-gateway
+Version: 0.1.0
+Summary: AgentGov FastAPI gateway (vaults ANTHROPIC_API_KEY; enforces from signed policy cache; §12.1)
+Author: AgentGov Contributors
+License: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: cryptography>=43.0.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx[http2]>=0.27.2
+Requires-Dist: prometheus-client>=0.21.0
+Requires-Dist: pydantic-settings>=2.5.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: python-json-logger>=2.0.7
+Requires-Dist: structlog>=24.4.0
+Requires-Dist: supabase>=2.9.0
+Requires-Dist: uuid7>=0.1.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Provides-Extra: dev
+Requires-Dist: httpx[http2]>=0.27.2; extra == 'dev'
+Requires-Dist: mypy>=1.11.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: respx>=0.21.1; extra == 'dev'
+Requires-Dist: ruff>=0.6.9; extra == 'dev'
+Requires-Dist: types-python-dateutil; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentgov-gateway
+
+The local FastAPI gateway that Claude Code (via `ANTHROPIC_BASE_URL=http://localhost:8000`) talks to.
+
+Runs on each developer's machine. Vaults the upstream credential (X25519 sealed-box decrypted from the signed policy snapshot). Enforces repo-lock + work-item binding + budget middleware chain. Streams SSE verbatim to Claude Code while tee-parsing usage frames for attribution.
+
+Part of the AgentGov project — see [github.com/deepakahu/agentGov](https://github.com/deepakahu/agentGov) for the full monorepo (control tower, CLI, client assets, Supabase migrations, docs).
+
+## Install
+
+```bash
+pip install agentgov-gateway
+```
+
+## Configure
+
+Requires these env vars — see the project `.env.example` for the full list:
+
+- `CONTROL_TOWER_URL` — where your AgentGov control tower is deployed
+- `GATEWAY_SERVICE_TOKEN` — a `gtw_...` token from `agentgov register-device`
+- `POLICY_SIGNING_PUBLIC_KEY_B64` — Ed25519 public key (control tower gives you this)
+- `DEVICE_KEY_PATH` — path to your X25519 device private key (default: `./.runtime/device_key.priv`)
+- `UPSTREAM_MODE` — `oauth_passthrough` (default, personal) or `apikey_vault`
+
+## Run
+
+```bash
+uvicorn agentgov_gateway.main:app --host 127.0.0.1 --port 8000
+```
+
+Under systemd / launchd for persistent operation.
+
+## License
+
+Apache-2.0

agentgov_gateway-0.1.0/README.md

@@ -0,0 +1,35 @@
+# agentgov-gateway
+
+The local FastAPI gateway that Claude Code (via `ANTHROPIC_BASE_URL=http://localhost:8000`) talks to.
+
+Runs on each developer's machine. Vaults the upstream credential (X25519 sealed-box decrypted from the signed policy snapshot). Enforces repo-lock + work-item binding + budget middleware chain. Streams SSE verbatim to Claude Code while tee-parsing usage frames for attribution.
+
+Part of the AgentGov project — see [github.com/deepakahu/agentGov](https://github.com/deepakahu/agentGov) for the full monorepo (control tower, CLI, client assets, Supabase migrations, docs).
+
+## Install
+
+```bash
+pip install agentgov-gateway
+```
+
+## Configure
+
+Requires these env vars — see the project `.env.example` for the full list:
+
+- `CONTROL_TOWER_URL` — where your AgentGov control tower is deployed
+- `GATEWAY_SERVICE_TOKEN` — a `gtw_...` token from `agentgov register-device`
+- `POLICY_SIGNING_PUBLIC_KEY_B64` — Ed25519 public key (control tower gives you this)
+- `DEVICE_KEY_PATH` — path to your X25519 device private key (default: `./.runtime/device_key.priv`)
+- `UPSTREAM_MODE` — `oauth_passthrough` (default, personal) or `apikey_vault`
+
+## Run
+
+```bash
+uvicorn agentgov_gateway.main:app --host 127.0.0.1 --port 8000
+```
+
+Under systemd / launchd for persistent operation.
+
+## License
+
+Apache-2.0

agentgov_gateway-0.1.0/agentgov_gateway/__init__.py

@@ -0,0 +1,6 @@
+"""AgentGov gateway — FastAPI proxy between Claude Code and Anthropic.
+
+Vaults ANTHROPIC_API_KEY. Enforces from a signed policy cache. Streams SSE.
+"""
+
+__version__ = "0.1.0"

agentgov_gateway-0.1.0/agentgov_gateway/config.py

@@ -0,0 +1,140 @@
+"""Gateway configuration (pydantic-settings, env-first, agentgov.toml overlay).
+
+Config validation is fail-fast. In particular:
+  - POLICY_SNAPSHOT_INTERVAL_SEC has a floor of 60 s (§12.2, per user direct
+    instruction). Anything lower is rejected at boot.
+  - ANTHROPIC_API_KEY must be present and NEVER logged. Its presence is
+    verified but the value is never rendered by our __repr__.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import AliasChoices, Field, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# Floors — see CLAUDE.md §12.2. Rejecting below-floor at boot protects the
+# control tower's Vercel invocation budget from a misconfigured customer.
+POLICY_SNAPSHOT_INTERVAL_FLOOR_SEC = 60
+REVOCATION_DELTA_POLL_FLOOR_SEC = 15
+
+
+class Settings(BaseSettings):
+    """All gateway config. Read once at boot; treated as immutable after."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # ---- Runtime ---------------------------------------------------------
+    agentgov_env: Literal["development", "staging", "production"] = "development"
+    log_level: str = "INFO"
+    log_format: Literal["json", "text"] = "json"
+
+    # ---- Upstream mode (§13.1) ------------------------------------------
+    # `oauth_passthrough` — the gateway forwards the Authorization header
+    #   verbatim to Anthropic; no local vault; nothing to steal.
+    # `apikey_vault`      — the gateway decrypts a per-device sealed credential
+    #   from the policy snapshot and swaps it into the Authorization header
+    #   before forwarding. Requires device registration (§14.1).
+    # Personal-mode default is `oauth_passthrough`. Enterprise-remote (§12)
+    # keeps setting ANTHROPIC_API_KEY via env for backwards compat.
+    upstream_mode: Literal["oauth_passthrough", "apikey_vault"] = "oauth_passthrough"
+    anthropic_base_url: str = "https://api.anthropic.com"
+
+    # ---- Legacy env-provided key (only for §12 enterprise-remote deploys) ---
+    # If set + `upstream_mode = apikey_vault`, this key is used INSTEAD of a
+    # per-device sealed credential. Do NOT set this in personal/team mode.
+    anthropic_api_key: SecretStr = Field(
+        default=SecretStr(""),
+        validation_alias=AliasChoices("ANTHROPIC_API_KEY", "anthropic_api_key"),
+    )
+
+    # ---- Device identity (§14.1) -----------------------------------------
+    device_key_path: Path = Path(".runtime/device_key.priv")
+    device_id: str = ""
+
+    # ---- Optional downstream Headroom hop -------------------------------
+    # §1 — Headroom is NOT modified by us; it's an OPTIONAL downstream service.
+    # When enabled, we forward /v1/messages to Headroom which then forwards to
+    # Anthropic with its own compression config.
+    headroom_enabled: bool = False
+    headroom_upstream_url: str = ""
+
+    # ---- Control tower --------------------------------------------------
+    control_tower_url: str
+    gateway_service_token: SecretStr
+
+    # ---- Policy sync (§12.2) --------------------------------------------
+    policy_snapshot_interval_sec: int = 300
+    revocation_delta_poll_interval_sec: int = 20
+    policy_staleness_warn_hours: int = 1
+    policy_staleness_fail_hours: int = 24
+    policy_signing_public_key_b64: str
+
+    # ---- Supabase Realtime (revocation fast path) -----------------------
+    supabase_url: str = ""
+    supabase_anon_key: SecretStr = SecretStr("")
+
+    # ---- Local runtime state ---------------------------------------------
+    policy_cache_path: Path = Path(".runtime/policy_cache.sqlite")
+    event_queue_dir: Path = Path(".runtime/event_queue")
+
+    # ---- Prometheus ------------------------------------------------------
+    prometheus_metrics_enabled: bool = True
+    prometheus_metrics_port: int = 9090
+
+    # ---- Validators ------------------------------------------------------
+    @field_validator("policy_snapshot_interval_sec")
+    @classmethod
+    def _floor_snapshot(cls, v: int) -> int:
+        if v < POLICY_SNAPSHOT_INTERVAL_FLOOR_SEC:
+            raise ValueError(
+                f"POLICY_SNAPSHOT_INTERVAL_SEC={v} is below the floor of "
+                f"{POLICY_SNAPSHOT_INTERVAL_FLOOR_SEC}s (CLAUDE.md §12.2)"
+            )
+        return v
+
+    @field_validator("revocation_delta_poll_interval_sec")
+    @classmethod
+    def _floor_delta(cls, v: int) -> int:
+        if v < REVOCATION_DELTA_POLL_FLOOR_SEC:
+            raise ValueError(
+                f"REVOCATION_DELTA_POLL_INTERVAL_SEC={v} is below the floor of "
+                f"{REVOCATION_DELTA_POLL_FLOOR_SEC}s (CLAUDE.md §12.2)"
+            )
+        return v
+
+    @field_validator("policy_staleness_fail_hours")
+    @classmethod
+    def _fail_cap(cls, v: int) -> int:
+        if v > 24 or v < 1:
+            raise ValueError("POLICY_STALENESS_FAIL_HOURS must be in [1, 24] (CLAUDE.md §12.2)")
+        return v
+
+    # NOTE: we no longer force ANTHROPIC_API_KEY at boot. Personal-mode
+    # deployments (§13, default) don't need it. `apikey_vault` mode reads its
+    # key from the per-device sealed credential in the policy snapshot.
+    # The old always-required check would break local-mode installs.
+
+
+_settings: Settings | None = None
+
+
+def settings() -> Settings:
+    """Return the singleton Settings instance, constructing on first call."""
+    global _settings
+    if _settings is None:
+        _settings = Settings()  # type: ignore[call-arg]
+    return _settings
+
+
+def _reset_for_tests() -> None:
+    """Test-only helper — the settings singleton is re-read from env."""
+    global _settings
+    _settings = None

agentgov_gateway-0.1.0/agentgov_gateway/device_key.py

@@ -0,0 +1,111 @@
+"""Device X25519 keypair — persistence + sealed-box decrypt (CLAUDE.md §14.2).
+
+First-run: generate a keypair, write the private key to disk (0600),
+send the public key to the control tower during `agentgov register-device`.
+
+Every subsequent gateway boot: load the private key into RAM. Use it to decrypt
+`upstream_credential` ciphertext from each policy snapshot.
+
+Wire format matches control-tower/lib/sealed-box.ts (NaCl `box`, ephemeral
+sender keypair). Byte-parity guarded by test_device_key.py.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from nacl.public import Box, PrivateKey, PublicKey
+
+log = logging.getLogger(__name__)
+
+
+class SealedBoxError(Exception):
+    """Raised when a sealed box fails to decrypt (bad key, nonce, ciphertext)."""
+
+
+@dataclass(frozen=True)
+class DeviceKeyPair:
+    """32-byte X25519 keypair. private_key held in memory only."""
+
+    private_key_b64: str
+    public_key_b64: str
+
+
+def generate() -> DeviceKeyPair:
+    """Create a fresh keypair."""
+    priv = PrivateKey.generate()
+    return DeviceKeyPair(
+        private_key_b64=base64.b64encode(bytes(priv)).decode(),
+        public_key_b64=base64.b64encode(bytes(priv.public_key)).decode(),
+    )
+
+
+def load_or_create(path: Path) -> DeviceKeyPair:
+    """Load a persisted keypair (via load()) or generate + persist a new one.
+
+    On generation, writes `{path}` (private) and `{path}.pub` (public).
+    """
+    if path.exists():
+        return load(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    kp = generate()
+    path.write_text(kp.private_key_b64 + "\n")
+    path.chmod(0o600)
+    pub_path = path.with_suffix(path.suffix + ".pub")
+    pub_path.write_text(kp.public_key_b64 + "\n")
+    log.info("device_key: generated new keypair at %s (pub: %s)", path, pub_path)
+    return kp
+
+
+def load(path: Path) -> DeviceKeyPair:
+    """Load a keypair whose private key is already on disk. Derives pub from priv."""
+    priv_b64 = path.read_text().strip()
+    priv_bytes = base64.b64decode(priv_b64)
+    if len(priv_bytes) != 32:
+        raise ValueError(
+            f"device_key: private key at {path} is {len(priv_bytes)} bytes, expected 32"
+        )
+    priv = PrivateKey(priv_bytes)
+    return DeviceKeyPair(
+        private_key_b64=priv_b64,
+        public_key_b64=base64.b64encode(bytes(priv.public_key)).decode(),
+    )
+
+
+def unseal(sealed: dict[str, Any], recipient_private_key_b64: str) -> bytes:
+    """Decrypt a sealed-box envelope produced by lib/sealed-box.ts.
+
+    Envelope keys: ephemeral_pubkey_b64, nonce_b64, ciphertext_b64.
+    Returns the plaintext bytes.
+    """
+    try:
+        eph_pub_b64 = sealed["ephemeral_pubkey_b64"]
+        nonce_b64 = sealed["nonce_b64"]
+        ct_b64 = sealed["ciphertext_b64"]
+    except KeyError as e:
+        raise SealedBoxError(f"missing envelope field: {e}") from e
+
+    try:
+        eph_pub = PublicKey(base64.b64decode(eph_pub_b64))
+        priv = PrivateKey(base64.b64decode(recipient_private_key_b64))
+        nonce = base64.b64decode(nonce_b64)
+        ct = base64.b64decode(ct_b64)
+    except Exception as e:
+        raise SealedBoxError(f"envelope decode failed: {e}") from e
+
+    box = Box(priv, eph_pub)
+    try:
+        return box.decrypt(ct, nonce)
+    except Exception as e:
+        raise SealedBoxError(f"decryption failed: {e}") from e
+
+
+def unseal_json(sealed: dict[str, Any], recipient_private_key_b64: str) -> dict[str, Any]:
+    """Decrypt + JSON-parse. Return dict."""
+    parsed: dict[str, Any] = json.loads(unseal(sealed, recipient_private_key_b64).decode("utf-8"))
+    return parsed

agentgov_gateway-0.1.0/agentgov_gateway/event_queue.py

@@ -0,0 +1,176 @@
+"""Disk-backed at-least-once event queue (§R-P8).
+
+Every TokenEvent + AuthzDecision the middleware chain produces goes on a
+local JSONL queue file. A worker task batches up to 50 or 5 s of events
+and POSTs to the control-tower /api/ingest. On failure it retries with
+exponential backoff and NEVER drops. On success it truncates the batch
+from the file. Never blocks the request hot path.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+if TYPE_CHECKING:
+    from .config import Settings
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+log = logging.getLogger(__name__)
+
+MAX_BATCH = 50
+FLUSH_INTERVAL_SEC = 5.0
+QUEUE_FILE = "queue.jsonl"
+
+# gap-P1-6: queue size ceiling + shed policy.
+# If the control tower is unreachable for hours, an idle laptop's disk still
+# has room, but a busy dev's queue grows without bound. We cap at 50_000
+# pending items (~10 MB on disk at typical row size) and, when the cap is hit,
+# SHED THE OLDEST — never the newest. Rationale: oldest events are the least
+# useful (most likely already stale in the user's mental model); newest are
+# the ones a debugging session wants. The shed count is logged loudly + a
+# best-effort authz_decisions row is queued so the loss is audited.
+MAX_QUEUE_SIZE = 50_000
+SHED_WATERMARK = int(MAX_QUEUE_SIZE * 0.9)  # start shedding at 90% full
+
+
+class EventQueue:
+    def __init__(self, settings: Settings) -> None:
+        self._s = settings
+        self._dir = Path(settings.event_queue_dir)
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._path = self._dir / QUEUE_FILE
+        self._lock = asyncio.Lock()
+        self._pending: list[dict[str, Any]] = []
+        self._stop = asyncio.Event()
+        self._flusher: asyncio.Task[None] | None = None
+
+    def start(self) -> None:
+        if self._flusher is None:
+            self._flusher = asyncio.create_task(self._flush_loop(), name="event_queue_flush")
+
+    async def stop(self) -> None:
+        self._stop.set()
+        if self._flusher is not None:
+            self._flusher.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._flusher
+
+    async def enqueue_event(self, event: dict[str, Any]) -> None:
+        async with self._lock:
+            self._pending.append({"kind": "event", "payload": event})
+            self._enforce_ceiling_locked()
+            await self._persist_all()
+
+    async def enqueue_decision(self, decision: dict[str, Any]) -> None:
+        async with self._lock:
+            self._pending.append({"kind": "decision", "payload": decision})
+            self._enforce_ceiling_locked()
+            await self._persist_all()
+
+    def _enforce_ceiling_locked(self) -> None:
+        """gap-P1-6: shed oldest when the queue exceeds the ceiling.
+
+        Called with self._lock held. Logs loudly + appends a synthetic
+        SHED audit row so the drop is recorded even after the fact.
+        """
+        if len(self._pending) <= MAX_QUEUE_SIZE:
+            return
+        # Shed enough to bring us back under the watermark so we don't
+        # thrash on the next enqueue.
+        target = SHED_WATERMARK
+        drop = len(self._pending) - target
+        if drop <= 0:
+            return
+        dropped_kinds = {"event": 0, "decision": 0}
+        for item in self._pending[:drop]:
+            dropped_kinds[item.get("kind", "event")] = (
+                dropped_kinds.get(item.get("kind", "event"), 0) + 1
+            )
+        self._pending = self._pending[drop:]
+        log.error(
+            "event_queue: SHED %d oldest items (queue >= %d); dropped=%s. "
+            "Control tower likely unreachable. Attribution for these events is lost.",
+            drop,
+            MAX_QUEUE_SIZE,
+            dropped_kinds,
+        )
+        # Append an audit note about the shed so the ledger has a marker.
+        self._pending.append(
+            {
+                "kind": "decision",
+                "payload": {
+                    "session_id": None,
+                    "user_id": None,
+                    "repo_claimed": None,
+                    "repo_id": None,
+                    "decision": "DENY",  # data-loss counts as a policy failure
+                    "reason_code": "EVENT_QUEUE_SHED",
+                    "sync_path": "local",
+                    "detail": {"dropped_count": drop, "dropped_kinds": dropped_kinds},
+                    "occurred_at": _now_iso(),
+                },
+            }
+        )
+
+    async def _persist_all(self) -> None:
+        # Overwrite the file with the current pending list. Cheap for small
+        # queues; if it ever grows we can move to append-only + compaction.
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, self._write_sync)
+
+    def _write_sync(self) -> None:
+        with self._path.open("w", encoding="utf-8") as f:
+            for item in self._pending:
+                f.write(json.dumps(item, separators=(",", ":")) + "\n")
+
+    async def _flush_loop(self) -> None:
+        while not self._stop.is_set():
+            try:
+                await asyncio.wait_for(self._stop.wait(), timeout=FLUSH_INTERVAL_SEC)
+                return
+            except TimeoutError:
+                await self._flush_once()
+
+    async def _flush_once(self) -> None:
+        async with self._lock:
+            if not self._pending:
+                return
+            batch = self._pending[:MAX_BATCH]
+        events = [i["payload"] for i in batch if i["kind"] == "event"]
+        decisions = [i["payload"] for i in batch if i["kind"] == "decision"]
+        try:
+            token = self._s.gateway_service_token.get_secret_value()
+            async with httpx.AsyncClient(timeout=15.0) as client:
+                resp = await client.post(
+                    f"{self._s.control_tower_url.rstrip('/')}/api/ingest",
+                    headers={
+                        "Authorization": f"Bearer {token}",
+                        "Content-Type": "application/json",
+                    },
+                    content=json.dumps({"events": events, "decisions": decisions}),
+                )
+            if resp.status_code >= 500:
+                log.warning("ingest: retriable status %s; keeping batch", resp.status_code)
+                return
+            if resp.status_code >= 400:
+                # 4xx = we shipped a bad batch. Drop to prevent poison. Log loudly.
+                log.error("ingest: DROP batch on 4xx: %s", resp.text)
+        except Exception:
+            log.exception("ingest: transport error; keeping batch for next flush")
+            return
+
+        # Success or 4xx → remove from pending + persist.
+        async with self._lock:
+            self._pending = self._pending[len(batch) :]
+            await self._persist_all()